narou 1.1.0 → 2.0.0

package/src/index.browser.ts

@@ -12,9 +12,10 @@ export { NarouNovelJsonp };
 const narouNovelJsonp = new NarouNovelJsonp();
 
 /**
- * 検索
- * @param {string} [word] - 検索ワード
+ * なろう小説 API で小説を検索する
+ * @param {string} [word] 検索ワード
  * @returns {SearchBuilder}
+ * @see https://dev.syosetu.com/man/api/
  */
 export function search(
   word = "",
@@ -26,9 +27,10 @@ export function search(
 }
 
 /**
- * 検索
- * @param {string} [word] - 検索ワード
+ * 18禁小説 API で小説を検索する
+ * @param {string} [word] 検索ワード
  * @returns {SearchBuilder}
+ * @see https://dev.syosetu.com/xman/api/
  */
 export function searchR18(
   word = "",
@@ -40,7 +42,10 @@ export function searchR18(
 }
 
 /**
- * ユーザ検索
+ * なろうユーザ検索 API でユーザを検索する
+ * @param {string} [word] - 検索ワード
+ * @returns {UserSearchBuilder}
+ * @see https://dev.syosetu.com/man/userapi/
  */
 export function searchUser(word = "", api: NarouNovel = narouNovelJsonp) {
   const builder = new UserSearchBuilder({}, api);
@@ -48,11 +53,22 @@ export function searchUser(word = "", api: NarouNovel = narouNovelJsonp) {
   return builder;
 }
 
+
+/**
+ * なろう小説ランキング API でランキングを取得する
+ * @returns {RankingBuilder}
+ * @see https://dev.syosetu.com/man/rankapi/
+ */
 export function ranking(api: NarouNovel = narouNovelJsonp): RankingBuilder {
   const builder = new RankingBuilder({}, api);
   return builder;
 }
 
+/**
+ * なろう殿堂入り API でランキング履歴を取得する
+ * @param {string} ncode 小説のNコード
+ * @see https://dev.syosetu.com/man/rankinapi/
+ */
 export async function rankingHistory(
   ncode: string,
   api: NarouNovel = narouNovelJsonp

package/src/index.ts

@@ -1,4 +1,5 @@
 import type NarouNovel from "./narou.js";
+import type { ExecuteOptions } from "./narou.js";
 import NarouNovelFetch from "./narou-fetch.js";
 import NarouNovelJsonp from "./narou-jsonp.js";
 import RankingBuilder from "./ranking.js";
@@ -14,8 +15,9 @@ const narouNovelFetch = new NarouNovelFetch();
 
 /**
  * なろう小説 API で小説を検索する
- * @param {string} [word] - 検索ワード
+ * @param {string} [word] 検索ワード
  * @returns {SearchBuilder}
+ * @see https://dev.syosetu.com/man/api/
  */
 export function search(
   word = "",
@@ -28,8 +30,9 @@ export function search(
 
 /**
  * 18禁小説 API で小説を検索する
- * @param {string} [word] - 検索ワード
+ * @param {string} [word] 検索ワード
  * @returns {SearchBuilder}
+ * @see https://dev.syosetu.com/xman/api/
  */
 export function searchR18(
   word = "",
@@ -42,6 +45,9 @@ export function searchR18(
 
 /**
  * なろうユーザ検索 API でユーザを検索する
+ * @param {string} [word] - 検索ワード
+ * @returns {UserSearchBuilder}
+ * @see https://dev.syosetu.com/man/userapi/
  */
 export function searchUser(word = "", api: NarouNovel = narouNovelFetch) {
   const builder = new UserSearchBuilder({}, api);
@@ -51,6 +57,8 @@ export function searchUser(word = "", api: NarouNovel = narouNovelFetch) {
 
 /**
  * なろう小説ランキング API でランキングを取得する
+ * @returns {RankingBuilder}
+ * @see https://dev.syosetu.com/man/rankapi/
  */
 export function ranking(api: NarouNovel = narouNovelFetch): RankingBuilder {
   const builder = new RankingBuilder({}, api);
@@ -59,12 +67,17 @@ export function ranking(api: NarouNovel = narouNovelFetch): RankingBuilder {
 
 /**
  * なろう殿堂入り API でランキング履歴を取得する
+ * @param {string} ncode 小説のNコード
+ * @param {ExecuteOptions} [options] 実行オプション
+ * @param {NarouNovel} [api] API実行クラスのインスタンス
+ * @see https://dev.syosetu.com/man/rankinapi/
  */
 export async function rankingHistory(
   ncode: string,
+  options?: ExecuteOptions,
   api: NarouNovel = narouNovelFetch
 ): Promise<RankingHistoryResult[]> {
-  const result = await api.executeRankingHistory({ ncode });
+  const result = await api.executeRankingHistory({ ncode }, options);
   if (Array.isArray(result)) {
     return result.map(formatRankingHistory);
   } else {

package/src/narou-fetch.ts

@@ -1,6 +1,6 @@
 import { unzipp } from "./util/unzipp.js";
 import NarouNovel from "./narou.js";
-import type { NarouParams } from "./narou.js";
+import type { NarouParams, ExecuteOptions } from "./narou.js";
 
 type Fetch = typeof fetch;
 
@@ -18,7 +18,8 @@ export default class NarouNovelFetch extends NarouNovel {
 
   protected async execute<T>(
     params: NarouParams,
-    endpoint: string
+    endpoint: string,
+    options?: ExecuteOptions
   ): Promise<T> {
     const query = { ...params, out: "json" };
 
@@ -36,7 +37,7 @@ export default class NarouNovelFetch extends NarouNovel {
       }
     });
 
-    const res = await (this.fetch ?? fetch)(url);
+    const res = await (this.fetch ?? fetch)(url, options?.fetchOptions);
 
     if (!query.gzip) {
       return (await res.json()) as T;

package/src/narou-jsonp.ts

@@ -1,5 +1,5 @@
 import NarouNovel from "./narou.js";
-import type { NarouParams } from "./narou.js";
+import type { NarouParams, ExecuteOptions } from "./narou.js";
 import { jsonp } from "./util/jsonp.js";
 
 /**
@@ -8,7 +8,9 @@ import { jsonp } from "./util/jsonp.js";
 export default class NarouNovelJsonp extends NarouNovel {
   protected async execute<T>(
     params: NarouParams,
-    endpoint: string
+    endpoint: string,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _options?: ExecuteOptions
   ): Promise<T> {
     const query = { ...params, out: "jsonp" };
     query.gzip = 0;

package/src/narou-search-results.ts

@@ -8,6 +8,7 @@ import type {
   R18Fields,
   OptionalFields,
   UserFields,
+  UserSearchParams,
 } from "./params.js";
 
 /**
@@ -45,7 +46,7 @@ export default class NarouSearchResults<T, TKey extends keyof T> {
    */
   constructor(
     [header, ...result]: [{ allcount: number }, ...Pick<T, TKey>[]],
-    params: SearchParams
+    params: SearchParams | UserSearchParams
   ) {
     const count = header.allcount;
     const limit = params.lim ?? 20;

package/src/narou.ts

@@ -21,6 +21,16 @@ export type NarouParams =
   | RankingHistoryParams
   | UserSearchParams;
 
+/**
+ * なろう小説APIへのリクエストオプション
+ */
+export interface ExecuteOptions {
+  /**
+   * fetch関数のオプション
+   */
+  fetchOptions?: RequestInit;
+}
+
 /**
  * なろう小説APIへのリクエストを実行する
  * @class NarouNovel
@@ -35,7 +45,8 @@ export default abstract class NarouNovel {
    */
   protected abstract execute<T>(
     params: NarouParams,
-    endpoint: string
+    endpoint: string,
+    options?: ExecuteOptions
   ): Promise<T>;
 
   /**
@@ -46,9 +57,13 @@ export default abstract class NarouNovel {
    */
   protected async executeSearch<T extends keyof NarouSearchResult>(
     params: SearchParams,
-    endpoint = "https://api.syosetu.com/novelapi/api/"
+    endpoint = "https://api.syosetu.com/novelapi/api/",
+    options?: ExecuteOptions
   ): Promise<NarouSearchResults<NarouSearchResult, T>> {
-    return new NarouSearchResults(await this.execute(params, endpoint), params);
+    return new NarouSearchResults(
+      await this.execute(params, endpoint, options),
+      params
+    );
   }
 
   /**
@@ -58,11 +73,13 @@ export default abstract class NarouNovel {
    * @see https://dev.syosetu.com/man/api/
    */
   async executeNovel<T extends keyof NarouSearchResult>(
-    params: SearchParams
+    params: SearchParams,
+    options?: ExecuteOptions
   ): Promise<NarouSearchResults<NarouSearchResult, T>> {
     return await this.executeSearch(
       params,
-      "https://api.syosetu.com/novelapi/api/"
+      "https://api.syosetu.com/novelapi/api/",
+      options
     );
   }
 
@@ -73,11 +90,13 @@ export default abstract class NarouNovel {
    * @see https://dev.syosetu.com/xman/api/
    */
   async executeNovel18<T extends keyof NarouSearchResult>(
-    params: SearchParams
+    params: SearchParams,
+    options?: ExecuteOptions
   ): Promise<NarouSearchResults<NarouSearchResult, T>> {
     return await this.executeSearch(
       params,
-      "https://api.syosetu.com/novel18api/api/"
+      "https://api.syosetu.com/novel18api/api/",
+      options
     );
   }
 
@@ -87,20 +106,33 @@ export default abstract class NarouNovel {
    * @returns ランキング結果
    * @see https://dev.syosetu.com/man/rankapi/
    */
-  async executeRanking(params: RankingParams): Promise<NarouRankingResult[]> {
-    return await this.execute(params, "https://api.syosetu.com/rank/rankget/");
+  async executeRanking(
+    params: RankingParams,
+    options?: ExecuteOptions
+  ): Promise<NarouRankingResult[]> {
+    return await this.execute(
+      params,
+      "https://api.syosetu.com/rank/rankget/",
+      options
+    );
   }
 
   /**
    * 殿堂入りAPiへのリクエストを実行する
    * @param params クエリパラメータ
+   * @param options 実行オプション
    * @returns ランキング履歴結果
    * @see https://dev.syosetu.com/man/rankinapi/
    */
   async executeRankingHistory(
-    params: RankingHistoryParams
+    params: RankingHistoryParams,
+    options?: ExecuteOptions
   ): Promise<RankingHistoryRawResult[]> {
-    return await this.execute(params, "https://api.syosetu.com/rank/rankin/");
+    return await this.execute(
+      params,
+      "https://api.syosetu.com/rank/rankin/",
+      options
+    );
   }
 
   /**
@@ -110,8 +142,16 @@ export default abstract class NarouNovel {
    * @see https://dev.syosetu.com/man/userapi/
    */
   async executeUserSearch<T extends keyof UserSearchResult>(
-    params: UserSearchParams
+    params: UserSearchParams,
+    options?: ExecuteOptions
   ): Promise<NarouSearchResults<UserSearchResult, T>> {
-    return await this.execute(params, "https://api.syosetu.com/userapi/api/");
+    return new NarouSearchResults<UserSearchResult, T>(
+      await this.execute(
+        params,
+        "https://api.syosetu.com/userapi/api/",
+        options
+      ),
+      params
+    );
   }
 }

package/src/params.ts

@@ -105,7 +105,7 @@ export interface SearchParams extends ParamsBaseWithOrder<Order> {
 
   stop?: StopParam;
 
-  ispickup?: BooleanNumber;
+  ispickup?: typeof BooleanNumber.True;
   lastup?: string;
   lastupdate?: string;
 
@@ -372,7 +372,7 @@ export const Order = {
   /** ブックマーク数の多い順 */
   FavoriteNovelCount: "favnovelcnt",
   /** レビュー数の多い順 */
-  ReviewCount: "favnovelcnt",
+  ReviewCount: "reviewcnt",
   /** 総合ポイントの高い順 */
   HyokaDesc: "hyoka",
   /** 総合ポイントの低い順 */

package/src/ranking-history.ts

@@ -1,7 +1,5 @@
-import { parse } from "date-fns";
 import type { RankingType } from "./params.js";
-
-const dateFormat = "yyyyMMdd";
+import { parseDate } from "./util/date.js";
 
 export interface RankingHistoryRawResult {
   rtype: `${string}-${RankingType}`;
@@ -16,12 +14,23 @@ export interface RankingHistoryResult {
   rank: number;
 }
 
+/**
+ * 生のランキング履歴エントリを構造化された形式にフォーマットします。
+ * 
+ * @param rankin - フォーマットする生のランキング履歴データ
+ * @returns 日付とタイプが解析されたフォーマット済みランキング履歴
+ * 
+ * @example
+ * const rawData = { rtype: "20230101-daily", pt: 500, rank: 10 };
+ * const formattedData = formatRankingHistory(rawData);
+ * // 返り値: { type: "daily", date: [Dateオブジェクト], pt: 500, rank: 10 }
+ */
 export function formatRankingHistory(
   rankin: RankingHistoryRawResult
 ): RankingHistoryResult {
   const { rtype, pt, rank } = rankin;
   const [_date, _type] = rtype.split("-");
-  const date = parse(_date, dateFormat, new Date());
+  const date = parseDate(_date);
   const type = _type as RankingType;
 
   return { type, date, pt, rank };

package/src/ranking.ts

@@ -1,7 +1,6 @@
 import type { NarouRankingResult, RankingResult } from "./narou-ranking-results.js";
 import SearchBuilder from "./search-builder.js";
 import type { DefaultSearchResultFields } from "./search-builder.js";
-import { addDays, format } from "date-fns";
 import type {
   GzipLevel,
   OptionalFields,
@@ -12,20 +11,36 @@ import {
   Fields,
 } from "./params.js";
 import type NarouNovel from "./narou.js";
+import type { ExecuteOptions } from "./narou.js";
 import type { SearchResultFields } from "./narou-search-results.js";
-
-const dateFormat = "yyyyMMdd";
+import { addDays, formatDate } from "./util/date.js";
 
 /**
- * ランキングヘルパー
- * @class Ranking
+ * なろう小説ランキングAPIのヘルパークラス。
+ *
+ * ランキング種別や日付を指定してランキングデータを取得します。
+ * また、取得したランキングデータに含まれるNコードを元に、
+ * なろう小説APIを利用して詳細な小説情報を取得することも可能です。
+ *
+ * @class RankingBuilder
+ * @see https://dev.syosetu.com/man/rankapi/ なろう小説ランキングAPI仕様
  */
 export default class RankingBuilder {
+  /**
+   * ランキング集計対象の日付
+   * @protected
+   */
   protected date$: Date;
+  /**
+   * ランキング種別
+   * @protected
+   */
   protected type$: RankingType;
 
   /**
    * constructor
+   * @param params - 初期クエリパラメータ
+   * @param api - API実行クラスのインスタンス
    * @private
    */
   constructor(
@@ -36,15 +51,32 @@ export default class RankingBuilder {
      * クエリパラメータ
      * @protected
      */
-    this.date$ = addDays(Date.now(), -1);
+    this.date$ = addDays(new Date(), -1);
     this.type$ = RankingType.Daily;
   }
 
+  /**
+   * ランキング集計対象の日付を指定します。
+   *
+   * - 日間: 任意の日付
+   * - 週間: 火曜日の日付
+   * - 月間・四半期: 1日の日付
+   *
+   * @param date 集計対象の日付
+   * @returns {RankingBuilder} this
+   * @see https://dev.syosetu.com/man/rankapi/
+   */
   date(date: Date) {
     this.date$ = date;
     return this;
   }
 
+  /**
+   * ランキング種別を指定します。
+   * @param type ランキング種別
+   * @returns {RankingBuilder} this
+   * @see https://dev.syosetu.com/man/rankapi/
+   */
   type(type: RankingType) {
     this.type$ = type;
     return this;
@@ -63,9 +95,10 @@ export default class RankingBuilder {
   }
 
   /**
-   * クエリパラメータをセットする
+   * クエリパラメータを内部的にセットします。
+   * @param obj - セットするパラメータオブジェクト
+   * @returns {RankingBuilder} this
    * @private
-   * @return {RankingBuilder} this
    */
   protected set(obj: Partial<RankingParams>) {
     Object.assign(this.params, obj);
@@ -73,41 +106,81 @@ export default class RankingBuilder {
   }
 
   /**
-   * なろう小説APIへのリクエストを実行する
-   * @returns ランキング
+   * 設定されたパラメータに基づき、なろう小説ランキングAPIへのリクエストを実行します。
+   *
+   * 返される結果には、Nコード、ポイント、順位が含まれます。
+   * @param options 実行オプション
+   * @returns {Promise<NarouRankingResult[]>} ランキング結果の配列
+   * @see https://dev.syosetu.com/man/rankapi/#output
    */
-  execute(): Promise<NarouRankingResult[]> {
-    const date = format(this.date$, dateFormat);
+  execute(options?: ExecuteOptions): Promise<NarouRankingResult[]> {
+    const date = formatDate(this.date$);
     this.set({ rtype: `${date}-${this.type$}` });
-    return this.api.executeRanking(this.params as RankingParams);
+    return this.api.executeRanking(this.params as RankingParams, options);
   }
 
-  async executeWithFields(): Promise<
-    RankingResult<DefaultSearchResultFields>[]
-  >;
-
+  /**
+   * ランキングAPIを実行し、取得したNコードを元になろう小説APIで詳細情報を取得して結合します。
+   */
+  async executeWithFields(
+    fields?: never[] | undefined,
+    opt?: never[] | undefined,
+    options?: ExecuteOptions
+  ): Promise<RankingResult<DefaultSearchResultFields>[]>;
+  /**
+   * ランキングAPIを実行し、取得したNコードを元になろう小説APIで詳細情報を取得して結合します。
+   *
+   * @template TFields - 取得する小説情報のフィールド型
+   * @param fields - 取得するフィールドの配列
+   * @returns {Promise<RankingResult<SearchResultFields<TFields>>[]>} 詳細情報を含むランキング結果の配列
+   */
   async executeWithFields<TFields extends Fields>(
-    fields: TFields | TFields[]
+    fields: TFields | TFields[],
+    opt?: never | never[],
+    options?: ExecuteOptions
   ): Promise<RankingResult<SearchResultFields<TFields>>[]>;
-
+  /**
+   * ランキングAPIを実行し、取得したNコードを元になろう小説APIで詳細情報を取得して結合します。
+   *
+   * @param opt - オプショナルな取得フィールド (`weekly` など)
+   * @returns {Promise<RankingResult<DefaultSearchResultFields | "weekly_unique">[]>} 詳細情報を含むランキング結果の配列
+   */
   async executeWithFields(
     fields: never[],
-    opt: OptionalFields | OptionalFields[]
+    opt: OptionalFields | OptionalFields[],
+    options?: ExecuteOptions
   ): Promise<RankingResult<DefaultSearchResultFields | "weekly_unique">[]>;
-
+  /**
+   * ランキングAPIを実行し、取得したNコードを元になろう小説APIで詳細情報を取得して結合します。
+   *
+   * @template TFields - 取得する小説情報のフィールド型
+   * @param fields - 取得するフィールドの配列
+   * @param opt - オプショナルな取得フィールド (`weekly` など)
+   * @returns {Promise<RankingResult<SearchResultFields<TFields> | "weekly_unique">[]>} 詳細情報を含むランキング結果の配列
+   */
   async executeWithFields<TFields extends Fields>(
     fields: TFields | TFields[],
-    opt: OptionalFields | OptionalFields[]
+    opt: OptionalFields | OptionalFields[],
+    options?: ExecuteOptions
   ): Promise<RankingResult<SearchResultFields<TFields> | "weekly_unique">[]>;
-
+  /**
+   * ランキングAPIを実行し、取得したNコードを元になろう小説APIで詳細情報を取得して結合します。
+   *
+   * @template TFields - 取得する小説情報のフィールド型
+   * @template TOpt - オプショナルな取得フィールドの型
+   * @param fields - 取得するフィールドの配列 (省略時はデフォルトフィールド)
+   * @param opt - オプショナルな取得フィールド (`weekly` など)
+   * @returns {Promise<RankingResult<SearchResultFields<TFields>>[]>} 詳細情報を含むランキング結果の配列
+   */
   async executeWithFields<
     TFields extends Fields,
     TOpt extends OptionalFields | undefined = undefined
   >(
     fields: TFields | TFields[] = [],
-    opt?: TOpt
+    opt?: TOpt,
+    options?: ExecuteOptions
   ): Promise<RankingResult<SearchResultFields<TFields>>[]> {
-    const ranking = await this.execute();
+    const ranking = await this.execute(options);
     const fields$ = Array.isArray(fields)
       ? fields.length == 0
         ? []
@@ -122,7 +195,7 @@ export default class RankingBuilder {
     }
     builder.ncode(rankingNcodes);
     builder.limit(ranking.length);
-    const result = await builder.execute();
+    const result = await builder.execute(options);
 
     return ranking.map<
       RankingResult<

package/src/search-builder-r18.ts

@@ -1,4 +1,5 @@
 import { NovelSearchBuilderBase } from "./search-builder.js";
+import type { ExecuteOptions } from "./narou.js";
 import type NarouSearchResults from "./narou-search-results.js";
 import type {
   NarouSearchResult,
@@ -28,20 +29,29 @@ export default class SearchBuilderR18<
   /**
    * なろう小説APIへの検索リクエストを実行する
    * @override
+   * @param options 実行オプション
    * @returns {Promise<NarouSearchResults>} 検索結果
    */
-  execute(): Promise<NarouSearchResults<NarouSearchResult, T | TOpt>> {
-    return this.api.executeNovel18(this.params);
+  execute(
+    options?: ExecuteOptions
+  ): Promise<NarouSearchResults<NarouSearchResult, T | TOpt>> {
+    return this.api.executeNovel18(this.params, options);
   }
 
+  /**
+   * 抽出するR18サイトを指定します (nocgenre)。
+   * @param sites R18サイトコード、またはR18サイトコードの配列 (1: ノクターンノベルズ, 2: ムーンライトノベルズ(男性向け), 3: ムーンライトノベルズ(BL), 4: ミッドナイトノベルズ)
+   * @return {this}
+   */
   r18Site(sites: R18Site | readonly R18Site[]) {
     this.set({ nocgenre: NovelSearchBuilderBase.array2string(sites) });
     return this;
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * X-IDを指定して取得します (xid)。
+   * @param ids X-ID、またはX-IDの配列
+   * @return {this}
    */
   xid(ids: number | readonly number[]) {
     this.set({ xid: NovelSearchBuilderBase.array2string(ids) });
@@ -49,8 +59,10 @@ export default class SearchBuilderR18<
   }
 
   /**
-   *
-   * @return {SearchBuilder} this
+   * 出力する項目を個別に指定します (of)。
+   * 未指定時は全項目出力されます。転送量軽減のため、このパラメータの使用が推奨されます。
+   * @param fields 出力するR18フィールド名、またはR18フィールド名の配列
+   * @return {SearchBuilderR18<SearchResultR18Fields<R18Fields>>} 型が更新されたビルダー
    */
   fields<TFields extends R18Fields>(
     fields: TFields | readonly TFields[]
@@ -60,6 +72,11 @@ export default class SearchBuilderR18<
     return this as any;
   }
 
+  /**
+   * 出力オプション項目を指定します (opt)。
+   * @param option 出力するオプションフィールド名、またはオプションフィールド名の配列
+   * @return {SearchBuilderR18<T, SearchResultOptionalFields<TFields>>} 型が更新されたビルダー
+   */
   opt<TFields extends OptionalFields>(
     option: TFields | readonly TFields[]
   ): SearchBuilderR18<T, SearchResultOptionalFields<TFields>> {