narou 1.1.0 → 1.2.0

package/dist/index.cjs

@@ -169,7 +169,10 @@ var NarouNovel = class {
    * @see https://dev.syosetu.com/man/userapi/
    */
   async executeUserSearch(params) {
-    return await this.execute(params, "https://api.syosetu.com/userapi/api/");
+    return new NarouSearchResults(
+      await this.execute(params, "https://api.syosetu.com/userapi/api/"),
+      params
+    );
   }
 };
 
@@ -647,14 +650,30 @@ var SearchBuilderBase = class {
   /**
    * constructor
    * @private
+   * @param params クエリパラメータ
+   * @param api NarouNovel インスタンス
    */
   constructor(params = {}, api) {
     this.params = params;
     this.api = api;
   }
+  /**
+   * 配列から重複を除去する
+   * @protected
+   * @static
+   * @param array 配列
+   * @returns 重複を除去した配列
+   */
   static distinct(array) {
     return Array.from(new Set(array));
   }
+  /**
+   * 配列をハイフン区切りの文字列に変換する
+   * @protected
+   * @static
+   * @param n 文字列または数値の配列、あるいは単一の文字列または数値
+   * @returns ハイフン区切りの文字列
+   */
   static array2string(n) {
     if (Array.isArray(n)) {
       return this.distinct(n).join("-");
@@ -663,44 +682,48 @@ var SearchBuilderBase = class {
     }
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 取得件数を指定する (lim)
+   * @param num 取得件数 (1-500)
+   * @return {this}
    */
   limit(num) {
     this.set({ lim: num });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 取得開始位置を指定する (st)
+   * @param num 取得開始位置 (1-)
+   * @return {this}
    */
   start(num) {
     this.set({ st: num });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * ページ番号と1ページあたりの件数で取得範囲を指定する
+   * @param no ページ番号 (0-)
+   * @param count 1ページあたりの件数 (デフォルト: 20)
+   * @return {this}
    */
   page(no, count2 = 20) {
     return this.limit(count2).start(no * count2);
   }
   /**
-   * 出力順序を指定する。指定しない場合は新着順となります。
-   * old	古い順
+   * 出力順序を指定する (order)
+   * 指定しない場合は新着順となります。
    * @param {TOrder} order 出力順序
-   * @return {SearchBuilder} this
+   * @return {this}
    */
   order(order) {
     this.set({ order });
     return this;
   }
   /**
-   * gzip圧縮する。
+   * gzip圧縮レベルを指定する (gzip)
    *
    * 転送量上限を減らすためにも推奨
    * @param {GzipLevel} level gzip圧縮レベル(1～5)
-   * @return {SearchBuilder} this
+   * @return {this}
    */
   gzip(level) {
     this.set({ gzip: level });
@@ -708,8 +731,9 @@ var SearchBuilderBase = class {
   }
   /**
    * クエリパラメータをセットする
-   * @private
-   * @return {SearchBuilder} this
+   * @protected
+   * @param obj セットするパラメータ
+   * @return {this}
    */
   set(obj) {
     this.params = { ...this.params, ...obj };
@@ -717,6 +741,9 @@ var SearchBuilderBase = class {
   }
   /**
    * クエリパラメータを削除する
+   * @protected
+   * @param key 削除するパラメータのキー
+   * @returns {this}
    */
   unset(key) {
     delete this.params[key];
@@ -725,56 +752,65 @@ var SearchBuilderBase = class {
 };
 var NovelSearchBuilderBase = class _NovelSearchBuilderBase extends SearchBuilderBase {
   /**
-   * a
-   * @return {SearchBuilder} this
+   * 検索語を指定します (word)。
+   * 半角または全角スペースで区切るとAND抽出になります。部分一致でHITします。
+   * @param word 検索語
+   * @return {this}
    */
   word(word) {
     this.set({ word });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 除外したい単語を指定します (notword)。
+   * スペースで区切ることにより除外する単語を増やせます。部分一致で除外されます。
+   * @param word 除外語
+   * @return {this}
    */
   notWord(word) {
     this.set({ notword: word });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 検索対象を作品名に限定するかどうかを指定します (title)。
+   * @param bool trueの場合、作品名を検索対象とする (デフォルト: true)
+   * @return {this}
    */
   byTitle(bool = true) {
     this.set({ title: bool ? BooleanNumber.True : BooleanNumber.False });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 検索対象をあらすじに限定するかどうかを指定します (ex)。
+   * @param bool trueの場合、あらすじを検索対象とする (デフォルト: true)
+   * @return {this}
    */
   byOutline(bool = true) {
     this.set({ ex: bool ? BooleanNumber.True : BooleanNumber.False });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 検索対象をキーワードに限定するかどうかを指定します (keyword)。
+   * @param bool trueの場合、キーワードを検索対象とする (デフォルト: true)
+   * @return {this}
    */
   byKeyword(bool = true) {
     this.set({ keyword: bool ? BooleanNumber.True : BooleanNumber.False });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 検索対象を作者名に限定するかどうかを指定します (wname)。
+   * @param bool trueの場合、作者名を検索対象とする (デフォルト: true)
+   * @return {this}
    */
   byAuthor(bool = true) {
     this.set({ wname: bool ? BooleanNumber.True : BooleanNumber.False });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * ボーイズラブ作品を抽出または除外します (isbl/notbl)。
+   * @param bool trueの場合、ボーイズラブ作品を抽出する (デフォルト: true)。falseの場合、除外する。
+   * @return {this}
    */
   isBL(bool = true) {
     if (bool) {
@@ -785,8 +821,9 @@ var NovelSearchBuilderBase = class _NovelSearchBuilderBase extends SearchBuilder
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * ガールズラブ作品を抽出または除外します (isgl/notgl)。
+   * @param bool trueの場合、ガールズラブ作品を抽出する (デフォルト: true)。falseの場合、除外する。
+   * @return {this}
    */
   isGL(bool = true) {
     if (bool) {
@@ -797,8 +834,9 @@ var NovelSearchBuilderBase = class _NovelSearchBuilderBase extends SearchBuilder
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 残酷な描写あり作品を抽出または除外します (iszankoku/notzankoku)。
+   * @param bool trueの場合、残酷な描写あり作品を抽出する (デフォルト: true)。falseの場合、除外する。
+   * @return {this}
    */
   isZankoku(bool = true) {
     if (bool) {
@@ -809,8 +847,9 @@ var NovelSearchBuilderBase = class _NovelSearchBuilderBase extends SearchBuilder
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 異世界転生作品を抽出または除外します (istensei/nottensei)。
+   * @param bool trueの場合、異世界転生作品を抽出する (デフォルト: true)。falseの場合、除外する。
+   * @return {this}
    */
   isTensei(bool = true) {
     if (bool) {
@@ -821,8 +860,9 @@ var NovelSearchBuilderBase = class _NovelSearchBuilderBase extends SearchBuilder
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 異世界転移作品を抽出または除外します (istenni/nottenni)。
+   * @param bool trueの場合、異世界転移作品を抽出する (デフォルト: true)。falseの場合、除外する。
+   * @return {this}
    */
   isTenni(bool = true) {
     if (bool) {
@@ -833,16 +873,18 @@ var NovelSearchBuilderBase = class _NovelSearchBuilderBase extends SearchBuilder
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 異世界転生または異世界転移作品を抽出します (istt)。
+   * @return {this}
    */
   isTT() {
     this.set({ istt: BooleanNumber.True });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 抽出する作品の文字数を指定します (length)。
+   * 範囲指定する場合は、最小文字数と最大文字数をハイフン(-)記号で区切ってください。
+   * @param length 文字数、または[最小文字数, 最大文字数]
+   * @return {this}
    */
   length(length) {
     this.set({ length: _NovelSearchBuilderBase.array2string(length) });
@@ -859,59 +901,66 @@ var NovelSearchBuilderBase = class _NovelSearchBuilderBase extends SearchBuilder
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 抽出する作品の挿絵数を指定します (sasie)。
+   * @param num 挿絵数、または[最小挿絵数, 最大挿絵数]
+   * @return {this}
    */
   sasie(num) {
     this.set({ sasie: _NovelSearchBuilderBase.array2string(num) });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 抽出する作品の予想読了時間を分単位で指定します (time)。
+   * @param num 読了時間(分)、または[最小読了時間, 最大読了時間]
+   * @return {this}
    */
   time(num) {
     this.set({ time: _NovelSearchBuilderBase.array2string(num) });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * Nコードを指定して取得します (ncode)。
+   * @param ncodes Nコード、またはNコードの配列
+   * @return {this}
    */
   ncode(ncodes) {
     this.set({ ncode: _NovelSearchBuilderBase.array2string(ncodes) });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 抽出する小説タイプを指定します (type)。
+   * @param type 小説タイプ (t: 短編, r: 連載中, er: 完結済連載小説, ter: 短編と完結済連載小説, re: 連載中と完結済連載小説)
+   * @return {this}
    */
   type(type) {
     this.set({ type });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 抽出する作品の文体を指定します (buntai)。
+   * 複数指定する場合はハイフン(-)で区切ってください。
+   * @param buntai 文体コード、または文体コードの配列
+   * @return {this}
    */
   buntai(buntai) {
     this.set({ buntai: _NovelSearchBuilderBase.array2string(buntai) });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 連載停止中作品に関する指定をします (stop)。
+   * @param bool trueの場合、長期連載停止中のみ取得する (デフォルト: true)。falseの場合、長期連載停止中を除外する。
+   * @return {this}
    */
   isStop(bool = true) {
     this.set({ stop: bool ? StopParam.Stopping : StopParam.NoStopping });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * ピックアップ作品のみを取得します (ispickup)。
+   * @return {this}
    */
-  isPickup(bool = true) {
-    this.set({ ispickup: bool ? BooleanNumber.True : BooleanNumber.False });
+  isPickup() {
+    this.set({ ispickup: BooleanNumber.True });
     return this;
   }
   lastUpdate(x, y) {
@@ -952,48 +1001,59 @@ var NovelSearchBuilderBase = class _NovelSearchBuilderBase extends SearchBuilder
 };
 var SearchBuilder = class _SearchBuilder extends NovelSearchBuilderBase {
   /**
-   *
-   * @return {SearchBuilder} this
+   * 大ジャンルを指定して取得します (biggenre)。
+   * 複数指定する場合はハイフン(-)で区切ってください。
+   * @param genre 大ジャンルコード、または大ジャンルコードの配列
+   * @return {this}
    */
   bigGenre(genre) {
     this.set({ biggenre: _SearchBuilder.array2string(genre) });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 除外したい大ジャンルを指定します (notbiggenre)。
+   * 複数指定する場合はハイフン(-)で区切ってください。
+   * @param genre 除外する大ジャンルコード、または大ジャンルコードの配列
+   * @return {this}
    */
   notBigGenre(genre) {
     this.set({ notbiggenre: _SearchBuilder.array2string(genre) });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * ジャンルを指定して取得します (genre)。
+   * 複数指定する場合はハイフン(-)で区切ってください。
+   * @param genre ジャンルコード、またはジャンルコードの配列
+   * @return {this}
    */
   genre(genre) {
     this.set({ genre: _SearchBuilder.array2string(genre) });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 除外したいジャンルを指定します (notgenre)。
+   * 複数指定する場合はハイフン(-)で区切ってください。
+   * @param genre 除外するジャンルコード、またはジャンルコードの配列
+   * @return {this}
    */
   notGenre(genre) {
     this.set({ notgenre: _SearchBuilder.array2string(genre) });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * ユーザIDを指定して取得します (userid)。
+   * 複数指定する場合はハイフン(-)で区切ってください。
+   * @param ids ユーザID、またはユーザIDの配列
+   * @return {this}
    */
   userId(ids) {
     this.set({ userid: _SearchBuilder.array2string(ids) });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * R15作品を抽出または除外します (isr15/notr15)。
+   * @param bool trueの場合、R15作品を抽出する (デフォルト: true)。falseの場合、除外する。
+   * @return {this}
    */
   isR15(bool = true) {
     if (bool) {
@@ -1004,37 +1064,82 @@ var SearchBuilder = class _SearchBuilder extends NovelSearchBuilderBase {
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 出力する項目を個別に指定します (of)。
+   * 未指定時は全項目出力されます。転送量軽減のため、このパラメータの使用が推奨されます。
+   * 複数項目を出力する場合はハイフン(-)記号で区切ってください。
+   * @param fields 出力するフィールド名、またはフィールド名の配列
+   * @return {SearchBuilder<SearchResultFields<TFields>, TOpt>} 型が更新されたビルダー
    */
   fields(fields) {
     this.set({ of: _SearchBuilder.array2string(fields) });
     return this;
   }
+  /**
+   * 出力オプション項目を指定します (opt)。
+   * 複数項目を出力する場合はハイフン(-)記号で区切ってください。
+   * @param option 出力するオプションフィールド名、またはオプションフィールド名の配列
+   * @return {SearchBuilder<T, SearchResultOptionalFields<TFields>>} 型が更新されたビルダー
+   */
   opt(option) {
     this.set({ opt: _SearchBuilder.array2string(option) });
     return this;
   }
 };
 
+// src/util/date.ts
+function parseDate(dateStr) {
+  const year = parseInt(dateStr.substring(0, 4), 10);
+  const month = parseInt(dateStr.substring(4, 6), 10) - 1;
+  const day = parseInt(dateStr.substring(6, 8), 10);
+  return new Date(year, month, day, 0, 0, 0, 0);
+}
+function formatDate(date) {
+  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}`;
+}
+function addDays(date, days) {
+  const result = new Date(date);
+  result.setDate(result.getDate() + days);
+  return result;
+}
+
 // src/ranking.ts
-var import_date_fns = require("date-fns");
-var dateFormat = "yyyyMMdd";
 var RankingBuilder = class {
   /**
    * constructor
+   * @param params - 初期クエリパラメータ
+   * @param api - API実行クラスのインスタンス
    * @private
    */
   constructor(params = {}, api) {
     this.params = params;
     this.api = api;
-    this.date$ = (0, import_date_fns.addDays)(Date.now(), -1);
+    this.date$ = addDays(/* @__PURE__ */ new Date(), -1);
     this.type$ = RankingType.Daily;
   }
+  /**
+   * ランキング集計対象の日付を指定します。
+   *
+   * - 日間: 任意の日付
+   * - 週間: 火曜日の日付
+   * - 月間・四半期: 1日の日付
+   *
+   * @param date 集計対象の日付
+   * @returns {RankingBuilder} this
+   * @see https://dev.syosetu.com/man/rankapi/
+   */
   date(date) {
     this.date$ = date;
     return this;
   }
+  /**
+   * ランキング種別を指定します。
+   * @param type ランキング種別
+   * @returns {RankingBuilder} this
+   * @see https://dev.syosetu.com/man/rankapi/
+   */
   type(type) {
     this.type$ = type;
     return this;
@@ -1051,23 +1156,36 @@ var RankingBuilder = class {
     return this;
   }
   /**
-   * クエリパラメータをセットする
+   * クエリパラメータを内部的にセットします。
+   * @param obj - セットするパラメータオブジェクト
+   * @returns {RankingBuilder} this
    * @private
-   * @return {RankingBuilder} this
    */
   set(obj) {
     Object.assign(this.params, obj);
     return this;
   }
   /**
-   * なろう小説APIへのリクエストを実行する
-   * @returns ランキング
+   * 設定されたパラメータに基づき、なろう小説ランキングAPIへのリクエストを実行します。
+   *
+   * 返される結果には、Nコード、ポイント、順位が含まれます。
+   * @returns {Promise<NarouRankingResult[]>} ランキング結果の配列
+   * @see https://dev.syosetu.com/man/rankapi/#output
    */
   execute() {
-    const date = (0, import_date_fns.format)(this.date$, dateFormat);
+    const date = formatDate(this.date$);
     this.set({ rtype: `${date}-${this.type$}` });
     return this.api.executeRanking(this.params);
   }
+  /**
+   * ランキングAPIを実行し、取得したNコードを元になろう小説APIで詳細情報を取得して結合します。
+   *
+   * @template TFields - 取得する小説情報のフィールド型
+   * @template TOpt - オプショナルな取得フィールドの型
+   * @param fields - 取得するフィールドの配列 (省略時はデフォルトフィールド)
+   * @param opt - オプショナルな取得フィールド (`weekly` など)
+   * @returns {Promise<RankingResult<SearchResultFields<TFields>>[]>} 詳細情報を含むランキング結果の配列
+   */
   async executeWithFields(fields = [], opt) {
     const ranking2 = await this.execute();
     const fields$ = Array.isArray(fields) ? fields.length == 0 ? [] : [...fields, Fields.ncode] : [fields, Fields.ncode];
@@ -1089,12 +1207,10 @@ var RankingBuilder = class {
 };
 
 // src/ranking-history.ts
-var import_date_fns2 = require("date-fns");
-var dateFormat2 = "yyyyMMdd";
 function formatRankingHistory(rankin) {
   const { rtype, pt, rank } = rankin;
   const [_date, _type] = rtype.split("-");
-  const date = (0, import_date_fns2.parse)(_date, dateFormat2, /* @__PURE__ */ new Date());
+  const date = parseDate(_date);
   const type = _type;
   return { type, date, pt, rank };
 }
@@ -1109,26 +1225,39 @@ var SearchBuilderR18 = class extends NovelSearchBuilderBase {
   execute() {
     return this.api.executeNovel18(this.params);
   }
+  /**
+   * 抽出するR18サイトを指定します (nocgenre)。
+   * @param sites R18サイトコード、またはR18サイトコードの配列 (1: ノクターンノベルズ, 2: ムーンライトノベルズ(男性向け), 3: ムーンライトノベルズ(BL), 4: ミッドナイトノベルズ)
+   * @return {this}
+   */
   r18Site(sites) {
     this.set({ nocgenre: NovelSearchBuilderBase.array2string(sites) });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * X-IDを指定して取得します (xid)。
+   * @param ids X-ID、またはX-IDの配列
+   * @return {this}
    */
   xid(ids) {
     this.set({ xid: NovelSearchBuilderBase.array2string(ids) });
     return this;
   }
   /**
-   *
-   * @return {SearchBuilder} this
+   * 出力する項目を個別に指定します (of)。
+   * 未指定時は全項目出力されます。転送量軽減のため、このパラメータの使用が推奨されます。
+   * @param fields 出力するR18フィールド名、またはR18フィールド名の配列
+   * @return {SearchBuilderR18<SearchResultR18Fields<R18Fields>>} 型が更新されたビルダー
    */
   fields(fields) {
     this.set({ of: NovelSearchBuilderBase.array2string(fields) });
     return this;
   }
+  /**
+   * 出力オプション項目を指定します (opt)。
+   * @param option 出力するオプションフィールド名、またはオプションフィールド名の配列
+   * @return {SearchBuilderR18<T, SearchResultOptionalFields<TFields>>} 型が更新されたビルダー
+   */
   opt(option) {
     this.set({ opt: NovelSearchBuilderBase.array2string(option) });
     return this;