narou 1.0.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-fetch.ts

@@ -25,17 +25,20 @@ export default class NarouNovelFetch extends NarouNovel {
     if (query.gzip === undefined) {
       query.gzip = 5;
     }
+    if (query.gzip === 0) {
+      delete query.gzip;
+    }
     const url = new URL(endpoint);
 
     Object.entries(query).forEach(([key, value]) => {
-      if (value) {
+      if (value !== undefined) {
         url.searchParams.append(key, value.toString());
       }
     });
 
     const res = await (this.fetch ?? fetch)(url);
 
-    if (query.gzip === 0) {
+    if (!query.gzip) {
       return (await res.json()) as T;
     }
 

package/src/narou-jsonp.ts

@@ -16,7 +16,7 @@ export default class NarouNovelJsonp extends NarouNovel {
     const url = new URL(endpoint);
 
     Object.entries(query).forEach(([key, value]) => {
-      if (value) {
+      if (value !== undefined) {
         url.searchParams.append(key, value.toString());
       }
     });

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

@@ -1,4 +1,7 @@
-import type { NarouSearchResult, UserSearchResult } from "./narou-search-results.js";
+import type {
+  NarouSearchResult,
+  UserSearchResult,
+} from "./narou-search-results.js";
 import type { Join } from "./util/type.js";
 
 export const RankingType = {
@@ -7,7 +10,7 @@ export const RankingType = {
   Monthly: "m",
   Quarterly: "q",
 } as const;
-export type RankingType = typeof RankingType[keyof typeof RankingType];
+export type RankingType = (typeof RankingType)[keyof typeof RankingType];
 
 /**
  * すべてのAPIで共通のクエリパラメータ
@@ -82,11 +85,10 @@ export interface SearchParams extends ParamsBaseWithOrder<Order> {
   notzankoku?: BooleanNumber;
   nottensei?: BooleanNumber;
   nottenni?: BooleanNumber;
-  nottt?: BooleanNumber;
 
   minlen?: number;
   maxlen?: number;
-  length?: number | Join<number>;
+  length?: number | Join<number | "">;
 
   kaiwaritu?: number | string;
   sasie?: number | string;
@@ -103,8 +105,9 @@ export interface SearchParams extends ParamsBaseWithOrder<Order> {
 
   stop?: StopParam;
 
-  ispickup?: BooleanNumber;
+  ispickup?: typeof BooleanNumber.True;
   lastup?: string;
+  lastupdate?: string;
 
   opt?: Join<OptionalFields>;
 }
@@ -143,7 +146,7 @@ export const BooleanNumber = {
   True: 1,
   False: 0,
 } as const;
-export type BooleanNumber = typeof BooleanNumber[keyof typeof BooleanNumber];
+export type BooleanNumber = (typeof BooleanNumber)[keyof typeof BooleanNumber];
 
 export type SearchResultFieldNames = keyof NarouSearchResult;
 
@@ -231,7 +234,7 @@ export const Fields = {
   updated_at: "ua",
 } as const;
 
-export type Fields = typeof Fields[keyof Omit<
+export type Fields = (typeof Fields)[keyof Omit<
   NarouSearchResult,
   "novel_type" | "weekly_unique" | "nocgenre"
 >];
@@ -316,7 +319,7 @@ export const R18Fields = {
   updated_at: "ua",
 } as const;
 
-export type R18Fields = typeof R18Fields[keyof Omit<
+export type R18Fields = (typeof R18Fields)[keyof Omit<
   NarouSearchResult,
   "novel_type" | "weekly_unique" | "biggenre" | "genre" | "isr15"
 >];
@@ -333,7 +336,7 @@ export const OptionalFields = {
   weekly_unique: "weekly",
 } as const;
 
-export type OptionalFields = typeof OptionalFields[keyof Pick<
+export type OptionalFields = (typeof OptionalFields)[keyof Pick<
   NarouSearchResult,
   "weekly_unique"
 >];
@@ -360,7 +363,7 @@ export const UserFields = {
   /** 総合評価ポイントの合計 */
   sum_global_point: "sg",
 } as const;
-export type UserFields = typeof UserFields[keyof UserSearchResult];
+export type UserFields = (typeof UserFields)[keyof UserSearchResult];
 
 /**
  * 出力順序
@@ -402,9 +405,11 @@ export const Order = {
   QuarterPoint: "quarterpoint",
   /** 年間ポイントの高い順 */
   YearlyPoint: "yearlypoint",
+  /** 初回掲載順 */
+  GeneralFirstUp: "generalfirstup",
 } as const;
 
-export type Order = typeof Order[keyof typeof Order];
+export type Order = (typeof Order)[keyof typeof Order];
 
 /** R18掲載サイト */
 export const R18Site = {
@@ -418,7 +423,7 @@ export const R18Site = {
   Midnight: 4,
 } as const;
 
-export type R18Site = typeof R18Site[keyof typeof R18Site];
+export type R18Site = (typeof R18Site)[keyof typeof R18Site];
 
 /** R18掲載サイト表記ヘルパー */
 export const R18SiteNotation: { readonly [K in R18Site]: string } = {
@@ -444,7 +449,7 @@ export const BigGenre = {
   NonGenre: 98,
 } as const;
 
-export type BigGenre = typeof BigGenre[keyof typeof BigGenre];
+export type BigGenre = (typeof BigGenre)[keyof typeof BigGenre];
 
 /** 大ジャンル表記ヘルパー */
 export const BigGenreNotation: { readonly [K in BigGenre]: string } = {
@@ -501,7 +506,7 @@ export const Genre = {
   /** ノンジャンル〔ノンジャンル〕*/
   NonGenre: 9801,
 } as const;
-export type Genre = typeof Genre[keyof typeof Genre];
+export type Genre = (typeof Genre)[keyof typeof Genre];
 
 /** ジャンル表記ヘルパー */
 export const GenreNotation: { readonly [K in Genre]: string } = {
@@ -540,7 +545,7 @@ export const BuntaiParam = {
   JisageKaigyoHutsuu: 6,
 } as const;
 
-export type BuntaiParam = typeof BuntaiParam[keyof typeof BuntaiParam];
+export type BuntaiParam = (typeof BuntaiParam)[keyof typeof BuntaiParam];
 
 /** 連載停止中指定 */
 export const StopParam = {
@@ -550,7 +555,7 @@ export const StopParam = {
   Stopping: 2,
 } as const;
 
-export type StopParam = typeof StopParam[keyof typeof StopParam];
+export type StopParam = (typeof StopParam)[keyof typeof StopParam];
 
 /** 小説タイプ指定 */
 export const NovelTypeParam = {
@@ -565,7 +570,18 @@ export const NovelTypeParam = {
   /** 短編と完結済連載小説 */
   ShortAndRensai: "ter",
 } as const;
-export type NovelTypeParam = typeof NovelTypeParam[keyof typeof NovelTypeParam];
+export type NovelTypeParam =
+  (typeof NovelTypeParam)[keyof typeof NovelTypeParam];
+
+/** 日付指定パラメータ */
+export const DateParam = {
+  ThisWeek: "thisweek",
+  LastWeek: "lastweek",
+  SevenDays: "sevenday",
+  ThisMonth: "thismonth",
+  LastMonth: "lastmonth",
+};
+export type DateParam = (typeof DateParam)[keyof typeof DateParam];
 
 export const UserOrder = {
   /** ユーザIDの新しい順 */
@@ -581,6 +597,6 @@ export const UserOrder = {
   /** ユーザIDの古い順 */
   Old: "old",
 } as const;
-export type UserOrder = typeof UserOrder[keyof typeof UserOrder];
+export type UserOrder = (typeof UserOrder)[keyof typeof UserOrder];
 
 export type GzipLevel = 0 | 1 | 2 | 3 | 4 | 5;

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>> {