narou 1.1.0 → 1.2.0

package/src/search-builder.ts

@@ -34,16 +34,32 @@ export abstract class SearchBuilderBase<
   /**
    * constructor
    * @private
+   * @param params クエリパラメータ
+   * @param api NarouNovel インスタンス
    */
   constructor(
     protected params: TParams = {} as TParams,
     protected api: NarouNovel
   ) {}
 
+  /**
+   * 配列から重複を除去する
+   * @protected
+   * @static
+   * @param array 配列
+   * @returns 重複を除去した配列
+   */
   protected static distinct<T>(array: readonly T[]): T[] {
     return Array.from(new Set(array));
   }
 
+  /**
+   * 配列をハイフン区切りの文字列に変換する
+   * @protected
+   * @static
+   * @param n 文字列または数値の配列、あるいは単一の文字列または数値
+   * @returns ハイフン区切りの文字列
+   */
   protected static array2string<T extends string | number>(
     n: T | readonly T[]
   ): Join<T> {
@@ -55,8 +71,9 @@ export abstract class SearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 取得件数を指定する (lim)
+   * @param num 取得件数 (1-500)
+   * @return {this}
    */
   limit(num: number): this {
     this.set({ lim: num } as TParams);
@@ -64,8 +81,9 @@ export abstract class SearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 取得開始位置を指定する (st)
+   * @param num 取得開始位置 (1-)
+   * @return {this}
    */
   start(num: number): this {
     this.set({ st: num } as TParams);
@@ -73,18 +91,20 @@ export abstract class SearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * ページ番号と1ページあたりの件数で取得範囲を指定する
+   * @param no ページ番号 (0-)
+   * @param count 1ページあたりの件数 (デフォルト: 20)
+   * @return {this}
    */
   page(no: number, count = 20): this {
     return this.limit(count).start(no * count);
   }
 
   /**
-   * 出力順序を指定する。指定しない場合は新着順となります。
-   * old	古い順
+   * 出力順序を指定する (order)
+   * 指定しない場合は新着順となります。
    * @param {TOrder} order 出力順序
-   * @return {SearchBuilder} this
+   * @return {this}
    */
   order(order: TOrder): this {
     this.set({ order: order } as TParams);
@@ -92,11 +112,11 @@ export abstract class SearchBuilderBase<
   }
 
   /**
-   * gzip圧縮する。
+   * gzip圧縮レベルを指定する (gzip)
    *
    * 転送量上限を減らすためにも推奨
    * @param {GzipLevel} level gzip圧縮レベル(1～5)
-   * @return {SearchBuilder} this
+   * @return {this}
    */
   gzip(level: GzipLevel): this {
     this.set({ gzip: level } as TParams);
@@ -105,8 +125,9 @@ export abstract class SearchBuilderBase<
 
   /**
    * クエリパラメータをセットする
-   * @private
-   * @return {SearchBuilder} this
+   * @protected
+   * @param obj セットするパラメータ
+   * @return {this}
    */
   protected set(obj: TParams): this {
     this.params = { ...this.params, ...obj };
@@ -115,6 +136,9 @@ export abstract class SearchBuilderBase<
 
   /**
    * クエリパラメータを削除する
+   * @protected
+   * @param key 削除するパラメータのキー
+   * @returns {this}
    */
   protected unset(key: keyof TParams): this {
     delete this.params[key];
@@ -126,8 +150,10 @@ export abstract class NovelSearchBuilderBase<
   T extends SearchResultFieldNames,
 > extends SearchBuilderBase<SearchParams, Order> {
   /**
-   * a
-   * @return {SearchBuilder} this
+   * 検索語を指定します (word)。
+   * 半角または全角スペースで区切るとAND抽出になります。部分一致でHITします。
+   * @param word 検索語
+   * @return {this}
    */
   word(word: string): this {
     this.set({ word: word });
@@ -135,8 +161,10 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 除外したい単語を指定します (notword)。
+   * スペースで区切ることにより除外する単語を増やせます。部分一致で除外されます。
+   * @param word 除外語
+   * @return {this}
    */
   notWord(word: string): this {
     this.set({ notword: word });
@@ -144,8 +172,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 検索対象を作品名に限定するかどうかを指定します (title)。
+   * @param bool trueの場合、作品名を検索対象とする (デフォルト: true)
+   * @return {this}
    */
   byTitle(bool = true): this {
     this.set({ title: bool ? BooleanNumber.True : BooleanNumber.False });
@@ -153,8 +182,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 検索対象をあらすじに限定するかどうかを指定します (ex)。
+   * @param bool trueの場合、あらすじを検索対象とする (デフォルト: true)
+   * @return {this}
    */
   byOutline(bool = true): this {
     this.set({ ex: bool ? BooleanNumber.True : BooleanNumber.False });
@@ -162,8 +192,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 検索対象をキーワードに限定するかどうかを指定します (keyword)。
+   * @param bool trueの場合、キーワードを検索対象とする (デフォルト: true)
+   * @return {this}
    */
   byKeyword(bool = true): this {
     this.set({ keyword: bool ? BooleanNumber.True : BooleanNumber.False });
@@ -171,8 +202,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 検索対象を作者名に限定するかどうかを指定します (wname)。
+   * @param bool trueの場合、作者名を検索対象とする (デフォルト: true)
+   * @return {this}
    */
   byAuthor(bool = true): this {
     this.set({ wname: bool ? BooleanNumber.True : BooleanNumber.False });
@@ -180,8 +212,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * ボーイズラブ作品を抽出または除外します (isbl/notbl)。
+   * @param bool trueの場合、ボーイズラブ作品を抽出する (デフォルト: true)。falseの場合、除外する。
+   * @return {this}
    */
   isBL(bool = true): this {
     if (bool) {
@@ -193,8 +226,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * ガールズラブ作品を抽出または除外します (isgl/notgl)。
+   * @param bool trueの場合、ガールズラブ作品を抽出する (デフォルト: true)。falseの場合、除外する。
+   * @return {this}
    */
   isGL(bool = true): this {
     if (bool) {
@@ -206,8 +240,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 残酷な描写あり作品を抽出または除外します (iszankoku/notzankoku)。
+   * @param bool trueの場合、残酷な描写あり作品を抽出する (デフォルト: true)。falseの場合、除外する。
+   * @return {this}
    */
   isZankoku(bool = true): this {
     if (bool) {
@@ -219,8 +254,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 異世界転生作品を抽出または除外します (istensei/nottensei)。
+   * @param bool trueの場合、異世界転生作品を抽出する (デフォルト: true)。falseの場合、除外する。
+   * @return {this}
    */
   isTensei(bool = true): this {
     if (bool) {
@@ -232,8 +268,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 異世界転移作品を抽出または除外します (istenni/nottenni)。
+   * @param bool trueの場合、異世界転移作品を抽出する (デフォルト: true)。falseの場合、除外する。
+   * @return {this}
    */
   isTenni(bool = true): this {
     if (bool) {
@@ -245,8 +282,8 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 異世界転生または異世界転移作品を抽出します (istt)。
+   * @return {this}
    */
   isTT(): this {
     this.set({ istt: BooleanNumber.True });
@@ -254,8 +291,10 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 抽出する作品の文字数を指定します (length)。
+   * 範囲指定する場合は、最小文字数と最大文字数をハイフン(-)記号で区切ってください。
+   * @param length 文字数、または[最小文字数, 最大文字数]
+   * @return {this}
    */
   length(length: number | readonly number[]): this {
     this.set({ length: NovelSearchBuilderBase.array2string(length) });
@@ -263,10 +302,17 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 抽出する作品の会話率を%単位で指定します (kaiwaritu)。
+   * @param num 会話率(%)
+   * @return {this}
    */
   kaiwaritu(num: number): this;
+  /**
+   * 抽出する作品の会話率を%単位で範囲指定します (kaiwaritu)。
+   * @param min 最低会話率(%)
+   * @param max 最高会話率(%)
+   * @return {this}
+   */
   kaiwaritu(min: number, max: number): this;
 
   kaiwaritu(min: number, max?: number): this {
@@ -281,8 +327,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 抽出する作品の挿絵数を指定します (sasie)。
+   * @param num 挿絵数、または[最小挿絵数, 最大挿絵数]
+   * @return {this}
    */
   sasie(num: number | readonly number[]): this {
     this.set({ sasie: NovelSearchBuilderBase.array2string(num) });
@@ -290,8 +337,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 抽出する作品の予想読了時間を分単位で指定します (time)。
+   * @param num 読了時間(分)、または[最小読了時間, 最大読了時間]
+   * @return {this}
    */
   time(num: number | readonly number[]): this {
     this.set({ time: NovelSearchBuilderBase.array2string(num) });
@@ -299,8 +347,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * Nコードを指定して取得します (ncode)。
+   * @param ncodes Nコード、またはNコードの配列
+   * @return {this}
    */
   ncode(ncodes: string | readonly string[]): this {
     this.set({ ncode: NovelSearchBuilderBase.array2string(ncodes) });
@@ -308,8 +357,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 抽出する小説タイプを指定します (type)。
+   * @param type 小説タイプ (t: 短編, r: 連載中, er: 完結済連載小説, ter: 短編と完結済連載小説, re: 連載中と完結済連載小説)
+   * @return {this}
    */
   type(type: NovelTypeParam): this {
     this.set({ type });
@@ -317,8 +367,10 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 抽出する作品の文体を指定します (buntai)。
+   * 複数指定する場合はハイフン(-)で区切ってください。
+   * @param buntai 文体コード、または文体コードの配列
+   * @return {this}
    */
   buntai(buntai: BuntaiParam | readonly BuntaiParam[]): this {
     this.set({ buntai: NovelSearchBuilderBase.array2string(buntai) });
@@ -326,8 +378,9 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 連載停止中作品に関する指定をします (stop)。
+   * @param bool trueの場合、長期連載停止中のみ取得する (デフォルト: true)。falseの場合、長期連載停止中を除外する。
+   * @return {this}
    */
   isStop(bool = true): this {
     this.set({ stop: bool ? StopParam.Stopping : StopParam.NoStopping });
@@ -335,20 +388,33 @@ export abstract class NovelSearchBuilderBase<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * ピックアップ作品のみを取得します (ispickup)。
+   * @return {this}
    */
-  isPickup(bool = true): this {
-    this.set({ ispickup: bool ? BooleanNumber.True : BooleanNumber.False });
+  isPickup(): this {
+    this.set({ ispickup: BooleanNumber.True });
     return this;
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 最終更新日時を指定します (lastup)。
+   * @param date 最終更新日時 (YYYYMMDDhhmmss形式またはUNIXタイムスタンプ)
+   * @return {this}
    */
   lastUpdate(date: DateParam): this;
+  /**
+   * 最終更新日時の範囲を指定します (lastup)。
+   * @param from 開始日時 (UNIXタイムスタンプ)
+   * @param to 終了日時 (UNIXタイムスタンプ)
+   * @return {this}
+   */
   lastUpdate(from: number, to: number): this;
+  /**
+   * 最終更新日時の範囲を指定します (lastup)。
+   * @param from 開始日時 (Dateオブジェクト)
+   * @param to 終了日時 (Dateオブジェクト)
+   * @return {this}
+   */
   lastUpdate(from: Date, to: Date): this;
 
   lastUpdate(x: string | number | Date, y?: number | Date): this {
@@ -367,8 +433,25 @@ export abstract class NovelSearchBuilderBase<
     return this;
   }
 
+  /**
+   * 作品の更新日時を指定します (lastupdate)。
+   * @param date 作品の更新日時 (YYYYMMDDhhmmss形式またはUNIXタイムスタンプ)
+   * @return {this}
+   */
   lastNovelUpdate(date: DateParam): this;
+  /**
+   * 作品の更新日時の範囲を指定します (lastupdate)。
+   * @param from 開始日時 (UNIXタイムスタンプ)
+   * @param to 終了日時 (UNIXタイムスタンプ)
+   * @return {this}
+   */
   lastNovelUpdate(from: number, to: number): this;
+  /**
+   * 作品の更新日時の範囲を指定します (lastupdate)。
+   * @param from 開始日時 (Dateオブジェクト)
+   * @param to 終了日時 (Dateオブジェクト)
+   * @return {this}
+   */
   lastNovelUpdate(from: Date, to: Date): this;
 
   lastNovelUpdate(x: string | number | Date, y?: number | Date): this {
@@ -405,8 +488,10 @@ export default class SearchBuilder<
   TOpt extends keyof NarouSearchResult = never,
 > extends NovelSearchBuilderBase<T | TOpt> {
   /**
-   *
-   * @return {SearchBuilder} this
+   * 大ジャンルを指定して取得します (biggenre)。
+   * 複数指定する場合はハイフン(-)で区切ってください。
+   * @param genre 大ジャンルコード、または大ジャンルコードの配列
+   * @return {this}
    */
   bigGenre(genre: BigGenre | readonly BigGenre[]): this {
     this.set({ biggenre: SearchBuilder.array2string(genre) });
@@ -414,8 +499,10 @@ export default class SearchBuilder<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 除外したい大ジャンルを指定します (notbiggenre)。
+   * 複数指定する場合はハイフン(-)で区切ってください。
+   * @param genre 除外する大ジャンルコード、または大ジャンルコードの配列
+   * @return {this}
    */
   notBigGenre(genre: BigGenre | readonly BigGenre[]): this {
     this.set({ notbiggenre: SearchBuilder.array2string(genre) });
@@ -423,8 +510,10 @@ export default class SearchBuilder<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * ジャンルを指定して取得します (genre)。
+   * 複数指定する場合はハイフン(-)で区切ってください。
+   * @param genre ジャンルコード、またはジャンルコードの配列
+   * @return {this}
    */
   genre(genre: Genre | readonly Genre[]): this {
     this.set({ genre: SearchBuilder.array2string(genre) });
@@ -432,8 +521,10 @@ export default class SearchBuilder<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 除外したいジャンルを指定します (notgenre)。
+   * 複数指定する場合はハイフン(-)で区切ってください。
+   * @param genre 除外するジャンルコード、またはジャンルコードの配列
+   * @return {this}
    */
   notGenre(genre: Genre | readonly Genre[]): this {
     this.set({ notgenre: SearchBuilder.array2string(genre) });
@@ -441,8 +532,10 @@ export default class SearchBuilder<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * ユーザIDを指定して取得します (userid)。
+   * 複数指定する場合はハイフン(-)で区切ってください。
+   * @param ids ユーザID、またはユーザIDの配列
+   * @return {this}
    */
   userId(ids: number | readonly number[]): this {
     this.set({ userid: SearchBuilder.array2string(ids) });
@@ -450,8 +543,9 @@ export default class SearchBuilder<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * R15作品を抽出または除外します (isr15/notr15)。
+   * @param bool trueの場合、R15作品を抽出する (デフォルト: true)。falseの場合、除外する。
+   * @return {this}
    */
   isR15(bool = true): this {
     if (bool) {
@@ -463,8 +557,11 @@ export default class SearchBuilder<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 出力する項目を個別に指定します (of)。
+   * 未指定時は全項目出力されます。転送量軽減のため、このパラメータの使用が推奨されます。
+   * 複数項目を出力する場合はハイフン(-)記号で区切ってください。
+   * @param fields 出力するフィールド名、またはフィールド名の配列
+   * @return {SearchBuilder<SearchResultFields<TFields>, TOpt>} 型が更新されたビルダー
    */
   fields<TFields extends Fields>(
     fields: TFields | readonly TFields[]
@@ -474,6 +571,12 @@ export default class SearchBuilder<
     return this as any;
   }
 
+  /**
+   * 出力オプション項目を指定します (opt)。
+   * 複数項目を出力する場合はハイフン(-)記号で区切ってください。
+   * @param option 出力するオプションフィールド名、またはオプションフィールド名の配列
+   * @return {SearchBuilder<T, SearchResultOptionalFields<TFields>>} 型が更新されたビルダー
+   */
   opt<TFields extends OptionalFields>(
     option: TFields | readonly TFields[]
   ): SearchBuilder<T, SearchResultOptionalFields<TFields>> {

package/src/util/date.ts

@@ -0,0 +1,38 @@
+// 日付関連のユーティリティ関数
+
+/**
+ * 文字列の日付（yyyyMMdd形式）をDateオブジェクトに変換する
+ * @param dateStr yyyyMMdd形式の日付文字列
+ * @returns Dateオブジェクト
+ */
+export function parseDate(dateStr: string): Date {
+  const year = parseInt(dateStr.substring(0, 4), 10);
+  const month = parseInt(dateStr.substring(4, 6), 10) - 1; // JavaScriptの月は0から始まる
+  const day = parseInt(dateStr.substring(6, 8), 10);
+
+  return new Date(year, month, day, 0, 0, 0, 0);
+}
+
+/**
+ * 日付をyyyyMMdd形式の文字列に変換する
+ * @param date 日付
+ * @returns yyyyMMdd形式の文字列
+ */
+export function formatDate(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}${month}${day}`;
+}
+
+/**
+ * 指定された日数を加算した新しい日付を返す
+ * @param date 元の日付
+ * @param days 加算する日数
+ * @returns 新しい日付
+ */
+export function addDays(date: Date, days: number): Date {
+  const result = new Date(date);
+  result.setDate(result.getDate() + days);
+  return result;
+}

package/src/util/jsonp.ts

@@ -13,30 +13,75 @@ declare global {
     [key: CallbackId]: (data: any) => void;
   }
 }
+
+/**
+ * JSONP呼び出しのオプション設定
+ */
 export type JsonpOption = {
+  /**
+   * コールバック関数名のプレフィックス
+   * @default "__jp"
+   */
   prefix?: string;
+  
+  /**
+   * コールバック関数名を指定するURLパラメータ名
+   * @default "callback"
+   */
   param?: string;
+  
+  /**
+   * タイムアウト時間（ミリ秒）
+   * @default 15000
+   */
   timeout?: number;
 };
 
- 
-const noop = function () {};
+const noop = function () { };
 
+/**
+ * JSONPリクエストを実行してデータを取得します。
+ * 
+ * @param url - リクエスト先のURL
+ * @param options - JSONP呼び出しのオプション設定
+ * @returns JSONPリクエストの結果をPromiseで返します
+ * @throws {Error} タイムアウトが発生した場合、"Timeout"メッセージのエラーをスローします
+ * 
+ * @example
+ * ```typescript
+ * // 基本的な使用方法
+ * const data = await jsonp<ResponseType>('https://example.com/api');
+ * 
+ * // オプション指定
+ * const data = await jsonp<ResponseType>('https://example.com/api', {
+ *   prefix: 'customPrefix',
+ *   param: 'callbackParam',
+ *   timeout: 10000
+ * });
+ * ```
+ */
 export function jsonp<T>(
   url: string,
   { prefix = "__jp", param = "callback", timeout = 15000 }: JsonpOption = {}
 ): Promise<T> {
   return new Promise(function (resolve, reject) {
+    // 最初のscriptタグを取得し、そのタグの直前に新しいscriptタグを挿入するための参照を取得
+    // これにより、ページの構造を大きく変えることなくscriptを追加できる
     const targetChild = document.getElementsByTagName("script").item(0);
     const target = targetChild?.parentNode ?? document.head;
 
+    // ユニークなコールバック関数名を生成
     const id: CallbackId = `${prefix}${count++}`;
+    
+    // リソース解放用の関数を定義
+    // スクリプトタグの削除、コールバック関数のクリーンアップ、タイマーのクリアを行う
     const cleanup = function () {
       // Remove the script tag.
       if (script && script.parentNode) {
         script.parentNode.removeChild(script);
       }
 
+      // コールバック関数を空の関数に置き換えてメモリリークを防止
       window[id] = noop;
 
       if (timer) {
@@ -44,25 +89,35 @@ export function jsonp<T>(
       }
     };
 
+    // タイムアウト処理の設定
+    // 指定された時間内にレスポンスがない場合はエラーとして処理
     const timer =
       timeout > 0
         ? setTimeout(() => {
-            cleanup();
-            reject(new Error("Timeout"));
-          }, timeout)
+          cleanup();
+          reject(new Error("Timeout"));
+        }, timeout)
         : undefined;
 
+    // サーバーからのレスポンスを処理するコールバック関数
     const callback = (data: T) => {
       cleanup();
       resolve(data);
     };
+    
+    // グローバルスコープにコールバック関数を登録
+    // これによりJSONPのレスポンスから関数が呼び出せるようになる
     window[id] = callback;
 
-    // Create script.
+    // JSONPリクエスト用のscriptタグを作成
     const script = document.createElement("script");
     const urlObj = new URL(url);
+    
+    // URLにコールバック関数名をパラメータとして追加
     urlObj.searchParams.set(param, id);
     script.setAttribute("src", urlObj.toString());
+    
+    // DOMにscriptタグを挿入し、リクエストを開始
     target.insertBefore(script, targetChild);
   });
 }