Skip to content

migration.md

Latest commit

 

History

History
228 lines (183 loc) · 7.93 KB

migration.md

File metadata and controls

228 lines (183 loc) · 7.93 KB

Migration Guide: ≤ 0.55.1 → ≥ 0.56.2

Version 0.56.2 is a breaking rewrite. This guide maps patterns from 0.55.1 and earlier to the current API.

Package Structure

The previous version was a single package. The current version is a pnpm monorepo with two packages:

≤ 0.55.1 ≥ 0.56.2
@book000/pixivts (fetch-based, CJS) @book000/pixivts (fetch-based, ESM+CJS)
saving-responses/ (TypeORM + MySQL built-in) @book000/pixivts-db-mysql (optional, Drizzle + MySQL)

Creating a Client

// ≤ 0.55.1
import { Pixiv } from '@book000/pixivts'
const pixiv = await Pixiv.of(refreshToken)

// ≥ 0.56.2
import { PixivClient } from '@book000/pixivts'
const client = await PixivClient.of(refreshToken)

Error Handling

The previous version threw errors on failure. The current version returns Result<T, PixivError> — no thrown exceptions.

// ≤ 0.55.1
try {
  const res = await pixiv.illustDetail({ illustId })
  console.log(res.data.illust.title)
} catch (err) {
  console.error(err)
}

// ≥ 0.56.2
const result = await client.illusts.detail({ illustId })
if (result.isOk) {
  console.log(result.value.illust.title)
} else {
  console.error(result.error.type)
}

Method Mapping

≤ 0.55.1 method ≥ 0.56.2 method
pixiv.illustDetail({ illustId }) client.illusts.detail({ illustId })
pixiv.illustRelated({ illustId }) client.illusts.related({ illustId })
pixiv.searchIllust({ word }) client.illusts.search({ word })
pixiv.illustRanking(opts) client.illusts.ranking(opts)
pixiv.illustRecommended(opts) client.illusts.recommended(opts)
pixiv.illustSeries({ illustSeriesId }) client.illusts.series({ illustSeriesId })
pixiv.illustBookmarkAdd(opts) client.illusts.bookmarkAdd(opts)
pixiv.illustBookmarkDelete(opts) client.illusts.bookmarkDelete(opts)
pixiv.novelDetail({ novelId }) client.novels.detail({ novelId })
pixiv.novelText({ novelId }) client.novels.text({ novelId })
pixiv.novelRelated({ novelId }) client.novels.related({ novelId })
pixiv.searchNovel({ word }) client.novels.search({ word })
pixiv.novelRanking(opts) client.novels.ranking(opts)
pixiv.novelRecommended(opts) client.novels.recommended(opts)
pixiv.novelSeries({ seriesId }) client.novels.series({ seriesId })
pixiv.novelBookmarkAdd(opts) client.novels.bookmarkAdd(opts)
pixiv.novelBookmarkDelete(opts) client.novels.bookmarkDelete(opts)
pixiv.userDetail({ userId }) client.users.detail({ userId })
pixiv.userIllusts({ userId }) client.users.illusts({ userId })
pixiv.userNovels({ userId }) client.users.novels({ userId })
pixiv.userFollowing(opts) client.users.following(opts)
pixiv.userFollowAdd(opts) client.users.followAdd(opts)
pixiv.userFollowDelete(opts) client.users.followDelete(opts)
pixiv.userBookmarksIllust(opts) client.users.bookmarks.illusts(opts)
pixiv.userBookmarksNovel(opts) client.users.bookmarks.novels(opts)
pixiv.mangaRecommended(opts) client.manga.recommended(opts)
pixiv.ugoiraMetadata({ illustId }) client.ugoira.metadata({ illustId })
pixiv.getImageStream(url) client.images.fetch(url)

Pagination

The previous version returned the raw API response including next_url. The current version provides a PaginatedResultAsync with async generators.

// ≤ 0.55.1
let offset = 0
while (true) {
  const res = await pixiv.searchIllust({ word: 'hatsune miku', offset })
  // process res.data.illusts
  if (!res.data.next_url) break
  offset += res.data.illusts.length
}

// ≥ 0.56.2 — iterate pages
for await (const page of client.illusts.search({ word: 'hatsune miku' }).pages()) {
  // process page.illusts
}

// ≥ 0.56.2 — iterate all items across pages (async generator — throws on fetch error)
for await (const illust of client.illusts.search({ word: 'hatsune miku' }).items()) {
  console.log(illust) // IllustSimple
}

Response Type

The previous version returned a custom PixivApiResponse<T> — you accessed the body via .data. The current version returns the unwrapped response body directly.

// ≤ 0.55.1
const res = await pixiv.illustDetail({ illustId })
console.log(res.data.illust.title)  // .data because it's PixivApiResponse<T>

// ≥ 0.56.2
const result = await client.illusts.detail({ illustId })
if (result.isOk) {
  console.log(result.value.illust.title)  // no .data — value is the response body
}

MySQL Response Saving

The previous version had response saving built into the core package via TypeORM. The current version moves this to the optional @book000/pixivts-db-mysql package using Drizzle ORM.

// ≤ 0.55.1
import { Pixiv } from '@book000/pixivts'
const pixiv = await Pixiv.of(refreshToken, {
  responseDatabase: {
    host: 'localhost',
    username: 'pixiv',
    password: 'secret',
    database: 'pixivts',
    synchronize: true,
  },
})

// ≥ 0.56.2
import { PixivClient } from '@book000/pixivts'
import { createResponseRecorder } from '@book000/pixivts-db-mysql'

const { interceptor, close } = await createResponseRecorder({
  host: 'localhost',
  user: 'pixiv',
  password: 'secret',
  database: 'pixivts',
  bootstrap: true,
})
const client = await PixivClient.of(refreshToken, { onResponse: interceptor })
// ... use client ...
await close()

Dependencies Removed

The following dependencies from ≤ 0.55.1 are no longer required:

Removed Reason
qs Replaced by URLSearchParams
typeorm Moved to @book000/pixivts-db-mysql (Drizzle)
typeorm-naming-strategies Same as above
snake-camel-types Replaced by local type utilities

Migration Guide: ≤ 0.57.x → ≥ 0.58.0

Response Fields: snake_case → lowerCamelCase

All response field names have been renamed from snake_case to lowerCamelCase. This is a breaking change.

The library continues to communicate with the pixiv API using snake_case internally, but all values returned to callers are now camelCase.

Examples

≤ 0.57.x ≥ 0.58.0
illust.image_urls.square_medium illust.imageUrls.squareMedium
illust.create_date illust.createDate
illust.page_count illust.pageCount
illust.x_restrict illust.xRestrict
illust.meta_single_page illust.metaSinglePage
illust.meta_pages illust.metaPages
illust.total_view illust.totalView
illust.total_bookmarks illust.totalBookmarks
illust.is_bookmarked illust.isBookmarked
illust.illust_ai_type illust.illustAiType
novel.x_restrict novel.xRestrict
novel.create_date novel.createDate
novel.is_bookmarked novel.isBookmarked
novel.novel_ai_type novel.novelAiType
page.next_url page.nextUrl
page.user_previews page.userPreviews
page.ugoira_metadata page.ugoiraMetadata
user.profile_image_urls user.profileImageUrls
ugoira.zip_urls ugoira.zipUrls

Pagination Cursors

// ≤ 0.57.x
const page = await client.users.bookmarks.illusts({ userId: client.userId })
if (page.isOk && page.value.next_url) {
  const cursor = parseNextUrl(page.value.next_url)
}

// ≥ 0.58.0
const page = await client.users.bookmarks.illusts({ userId: client.userId })
if (page.isOk && page.value.nextUrl) {
  const cursor = parseNextUrl(page.value.nextUrl)
}

New: Token Getters

PixivClient now exposes getAccessToken() and getRefreshToken() methods:

const client = await PixivClient.of(refreshToken)
console.log(client.getAccessToken())  // current bearer token
console.log(client.getRefreshToken()) // current refresh token

DB Recording

The @book000/pixivts-db-mysql package continues to save raw snake_case response bodies to the database for archival fidelity. This behaviour is unchanged.