narou 1.1.0 → 1.2.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

@@ -14,8 +14,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 +29,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 +44,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 +56,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,6 +66,8 @@ export function ranking(api: NarouNovel = narouNovelFetch): RankingBuilder {
 
 /**
  * なろう殿堂入り API でランキング履歴を取得する
+ * @param {string} ncode 小説のNコード
+ * @see https://dev.syosetu.com/man/rankinapi/
  */
 export async function rankingHistory(
   ncode: string,

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

@@ -112,6 +112,9 @@ export default abstract class NarouNovel {
   async executeUserSearch<T extends keyof UserSearchResult>(
     params: UserSearchParams
   ): 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/"),
+      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;
 

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,
@@ -13,19 +12,34 @@ import {
 } from "./params.js";
 import type NarouNovel 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 +50,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 +94,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,33 +105,65 @@ export default class RankingBuilder {
   }
 
   /**
-   * なろう小説APIへのリクエストを実行する
-   * @returns ランキング
+   * 設定されたパラメータに基づき、なろう小説ランキングAPIへのリクエストを実行します。
+   *
+   * 返される結果には、Nコード、ポイント、順位が含まれます。
+   * @returns {Promise<NarouRankingResult[]>} ランキング結果の配列
+   * @see https://dev.syosetu.com/man/rankapi/#output
    */
   execute(): Promise<NarouRankingResult[]> {
-    const date = format(this.date$, dateFormat);
+    const date = formatDate(this.date$);
     this.set({ rtype: `${date}-${this.type$}` });
     return this.api.executeRanking(this.params as RankingParams);
   }
 
+  /**
+   * ランキングAPIを実行し、取得したNコードを元になろう小説APIで詳細情報を取得して結合します。
+   */
   async executeWithFields(): Promise<
     RankingResult<DefaultSearchResultFields>[]
   >;
-
+  /**
+   * ランキングAPIを実行し、取得したNコードを元になろう小説APIで詳細情報を取得して結合します。
+   *
+   * @template TFields - 取得する小説情報のフィールド型
+   * @param fields - 取得するフィールドの配列
+   * @returns {Promise<RankingResult<SearchResultFields<TFields>>[]>} 詳細情報を含むランキング結果の配列
+   */
   async executeWithFields<TFields extends Fields>(
     fields: TFields | TFields[]
   ): Promise<RankingResult<SearchResultFields<TFields>>[]>;
-
+  /**
+   * ランキングAPIを実行し、取得したNコードを元になろう小説APIで詳細情報を取得して結合します。
+   *
+   * @param opt - オプショナルな取得フィールド (`weekly` など)
+   * @returns {Promise<RankingResult<DefaultSearchResultFields | "weekly_unique">[]>} 詳細情報を含むランキング結果の配列
+   */
   async executeWithFields(
     fields: never[],
     opt: OptionalFields | OptionalFields[]
   ): 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[]
   ): 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

package/src/search-builder-r18.ts

@@ -34,14 +34,20 @@ export default class SearchBuilderR18<
     return this.api.executeNovel18(this.params);
   }
 
+  /**
+   * 抽出する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 +55,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 +68,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>> {