pgsql-template-tag 0.0.3 → 0.0.5

package/dist/src/core.d.ts

@@ -1,18 +1,93 @@
+/**
+ * SQL クエリー内で使用される値の型定義です。
+ */
 export type Value = unknown;
+/**
+ * SQL クエリーの構築に使用できる生の値、または別の Sql インスタンスを表す型です。
+ */
 export type RawValue = Value | Sql;
+/**
+ * 安全な SQL クエリーを構築するためのクラスです。
+ * プレースホルダーを使用したパラメーター化クエリーを生成します。
+ */
 export declare class Sql {
+    /**
+     * 構築された SQL クエリーテキストを取得します。
+     *
+     * 初回アクセス時に文字列が結合され、結果はキャッシュされます。
+     *
+     * @returns SQL クエリーテキストを返します。
+     */
     get text(): string;
+    /**
+     * クエリーに使用されるパラメーター値の配列です。
+     */
     readonly values: readonly Value[];
+    /**
+     * 内部状態を保持するためのプロパティーです。
+     */
     private readonly _;
+    /**
+     * 新しい Sql インスタンスを初期化します。
+     *
+     * @param rawStrings SQL の断片となる文字列の配列です。
+     * @param rawBindings 文字列の間に挿入される値の配列です。
+     */
     constructor(rawStrings: readonly string[], rawBindings: readonly RawValue[]);
+    /**
+     * オブジェクトを JSON 形式に変換可能な形式で返します。
+     *
+     * @returns クエリーテキストと値の配列を含むオブジェクトを返します。
+     */
     toJSON(): {
         text: string;
         values: Value[];
     };
+    /**
+     * インスタンスを文字列に変換します。
+     *
+     * @returns 構築された SQL クエリーテキストを返します。
+     */
     toString(): string;
 }
+/**
+ * 生の文字列を SQL 断片として扱います。
+ * この値はパラメーター化の対象にならず、そのままクエリーに含まれます。
+ *
+ * @param value SQL に含める生の文字列です。
+ * @returns 指定された文字列を持つ Sql インスタンスを返します。
+ */
 export declare function raw(value: string): Sql;
+/**
+ * 空の SQL インスタンスを表す定数です。
+ */
 export declare const empty: Sql;
+/**
+ * 複数の SQL 断片や値を、指定されたセパレーターで結合します。
+ *
+ * 配列が空の場合は、{@link empty} を返します。
+ *
+ * @param values 結合対象となる値の配列です。
+ * @param separator 結合時に挿入される文字列です。デフォルトはカンマ（,）です。
+ * @returns 結合された新しい Sql インスタンスを返します。
+ */
 export declare function join(values: readonly RawValue[], separator?: string | undefined): Sql;
+/**
+ * 文字列を SQL の識別子（テーブル名やカラム名など）として安全にエスケープします。
+ *
+ * 二重引用符を二重にすることでエスケープを行い、全体を二重引用符で囲みます。
+ *
+ * @param value エスケープする識別子の文字列です。
+ * @returns エスケープ済みの識別子文字列を返します。
+ */
 export declare function ident(value: string): string;
+/**
+ * 文字列を SQL のリテラル文字列として安全にエスケープします。
+ *
+ * 一重引用符を二重にすることでエスケープを行い、全体を一重引用符で囲みます。
+ *
+ * @param value エスケープする文字列です。
+ * @returns エスケープ済みのリテラル文字列を返します。
+ */
+export declare function literal(value: string): string;
 //# sourceMappingURL=core.d.ts.map

package/dist/src/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,KAAK,GAAG,OAAO,CAAC;AAG5B,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,GAAG,CAAC;AAEnC,qBAAa,GAAG;IACd,IAAW,IAAI,IAAI,MAAM,CAiBxB;IAED,SAAgB,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAEzC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAWhB;gBAEiB,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,QAAQ,EAAE;IA0E3E,MAAM,IAAI;QACf,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,KAAK,EAAE,CAAC;KACjB;IAOM,QAAQ,IAAI,MAAM;CAG1B;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAEtC;AAED,eAAO,MAAM,KAAK,EAAE,GAAa,CAAC;AAElC,wBAAgB,IAAI,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,EAAE,SAAS,GAAE,MAAM,GAAG,SAAe,GAAG,GAAG,CAM1F;AAID,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3C"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,CAAC;AAE5B;;GAEG;AAEH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,GAAG,CAAC;AAsBnC;;;GAGG;AACH,qBAAa,GAAG;IACd;;;;;;OAMG;IACH,IAAW,IAAI,IAAI,MAAM,CAexB;IAED;;OAEG;IACH,SAAgB,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAEzC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAgB;IAElC;;;;;OAKG;gBACgB,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,QAAQ,EAAE;IAsElF;;;;OAIG;IACI,MAAM,IAAI;QACf,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,KAAK,EAAE,CAAC;KACjB;IAOD;;;;OAIG;IACI,QAAQ,IAAI,MAAM;CAG1B;AAED;;;;;;GAMG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAEtC;AAED;;GAEG;AACH,eAAO,MAAM,KAAK,EAAE,GAAa,CAAC;AAElC;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,EAAE,SAAS,GAAE,MAAM,GAAG,SAAe,GAAG,GAAG,CAM1F;AAOD;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3C;AAOD;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7C"}

package/dist/src/core.js

@@ -1,19 +1,33 @@
+/**
+ * 安全な SQL クエリーを構築するためのクラスです。
+ * プレースホルダーを使用したパラメーター化クエリーを生成します。
+ */
 export class Sql {
+    /**
+     * 構築された SQL クエリーテキストを取得します。
+     *
+     * 初回アクセス時に文字列が結合され、結果はキャッシュされます。
+     *
+     * @returns SQL クエリーテキストを返します。
+     */
     get text() {
-        if (!this._.t.c) {
-            let text = this._.s[0], placeholderIds = this._.t.v;
-            if (placeholderIds.length > 0) {
-                for (let i = 0, len = placeholderIds.length; i < len; i++) {
-                    text += "$" + placeholderIds[i] + this._.s[i + 1];
-                }
+        // キャッシュが存在しない場合にのみ、文字列を構築します。
+        if (this._.t === undefined) {
+            let i = 0, text = this._.s[0];
+            // 文字列の断片とプレースホルダー（$1, $2...）を交互に結合します。
+            for (; i < this._.p.length; i++) {
+                text += "$" + this._.p[i] + this._.s[i + 1];
             }
-            this._.t = {
-                c: true,
-                v: text,
-            };
+            this._.t = text;
         }
-        return this._.t.v;
+        return this._.t;
     }
+    /**
+     * 新しい Sql インスタンスを初期化します。
+     *
+     * @param rawStrings SQL の断片となる文字列の配列です。
+     * @param rawBindings 文字列の間に挿入される値の配列です。
+     */
     constructor(rawStrings, rawBindings) {
         if (rawStrings.length === 0) {
             throw new TypeError("Expected at least 1 string");
@@ -24,70 +38,128 @@ export class Sql {
         const strings = [rawStrings[0]];
         const bindings = [];
         const placeholderIds = [];
-        if (rawStrings.length > 0) {
-            const valueToId = new Map();
-            for (let i = 0, len = rawBindings.length, child, rawString, placeholderId; i < len; i++) {
-                child = rawBindings[i];
-                rawString = rawStrings[i + 1];
-                if (child instanceof Sql) {
-                    strings[strings.length - 1] += child._.s[0];
-                    for (let j = 0, value; j < child.values.length; j++) {
-                        value = child.values[j];
-                        placeholderId = valueToId.get(value);
-                        if (placeholderId === undefined) {
-                            bindings.push(value);
-                            placeholderId = bindings.length;
-                            valueToId.set(value, placeholderId);
-                        }
-                        strings.push(child._.s[j + 1]);
-                        placeholderIds.push(placeholderId);
-                    }
-                    strings[strings.length - 1] += rawString;
-                }
-                else {
-                    placeholderId = valueToId.get(child);
+        /** 値の重複を排除し、同じ値には同じプレースホルダー ID を割り当てるためのマップです。 */
+        const valueToId = new Map();
+        // 提供された全てのバインディング値を走査して、SQL 文字列と値を正規化します。
+        for (let i = 0; i < rawBindings.length; i++) {
+            const child = rawBindings[i];
+            const rawString = rawStrings[i + 1];
+            // バインディング値が Sql インスタンス（ネストされたクエリー）の場合の処理です。
+            if (child instanceof Sql) {
+                // 現在の最後の文字列断片に、ネストされた Sql の最初の断片を結合します。
+                strings[strings.length - 1] += child._.s[0];
+                // ネストされた Sql のプレースホルダーと値を再マッピングします。
+                for (let j = 0; j < child._.p.length; j++) {
+                    const childPlaceholderId = child._.p[j];
+                    const value = child.values[childPlaceholderId - 1];
+                    let placeholderId = valueToId.get(value);
                     if (placeholderId === undefined) {
-                        bindings.push(child);
+                        bindings.push(value);
                         placeholderId = bindings.length;
-                        valueToId.set(child, placeholderId);
+                        valueToId.set(value, placeholderId);
                     }
-                    strings.push(rawString);
+                    strings.push(child._.s[j + 1]);
                     placeholderIds.push(placeholderId);
                 }
+                // ネストされた Sql の展開が終わった後に、後続の生の文字列を結合します。
+                strings[strings.length - 1] += rawString;
+            }
+            else {
+                let placeholderId = valueToId.get(child);
+                if (placeholderId === undefined) {
+                    bindings.push(child);
+                    placeholderId = bindings.length;
+                    valueToId.set(child, placeholderId);
+                }
+                strings.push(rawString);
+                placeholderIds.push(placeholderId);
             }
         }
         this.values = bindings;
+        // 内部状態を隠蔽し、不必要なプロパティーの露出を防ぎます。
         Object.defineProperty(this, "_", {
-            value: (this._ = {
-                t: {
-                    c: false,
-                    v: placeholderIds,
-                },
+            value: {
                 s: strings,
-            }),
+                p: placeholderIds,
+            },
         });
     }
+    /**
+     * オブジェクトを JSON 形式に変換可能な形式で返します。
+     *
+     * @returns クエリーテキストと値の配列を含むオブジェクトを返します。
+     */
     toJSON() {
         return {
             text: this.text,
             values: this.values.slice(),
         };
     }
+    /**
+     * インスタンスを文字列に変換します。
+     *
+     * @returns 構築された SQL クエリーテキストを返します。
+     */
     toString() {
         return this.text;
     }
 }
+/**
+ * 生の文字列を SQL 断片として扱います。
+ * この値はパラメーター化の対象にならず、そのままクエリーに含まれます。
+ *
+ * @param value SQL に含める生の文字列です。
+ * @returns 指定された文字列を持つ Sql インスタンスを返します。
+ */
 export function raw(value) {
     return new Sql([value], []);
 }
+/**
+ * 空の SQL インスタンスを表す定数です。
+ */
 export const empty = raw("");
+/**
+ * 複数の SQL 断片や値を、指定されたセパレーターで結合します。
+ *
+ * 配列が空の場合は、{@link empty} を返します。
+ *
+ * @param values 結合対象となる値の配列です。
+ * @param separator 結合時に挿入される文字列です。デフォルトはカンマ（,）です。
+ * @returns 結合された新しい Sql インスタンスを返します。
+ */
 export function join(values, separator = ",") {
     if (values.length === 0) {
         return empty;
     }
     return new Sql(["", ...Array(values.length - 1).fill(separator), ""], values);
 }
+/**
+ * 二重引用符をエスケープするための正規表現です。
+ */
 const DOUBLE_QUOTE_REGEX = /"/g;
+/**
+ * 文字列を SQL の識別子（テーブル名やカラム名など）として安全にエスケープします。
+ *
+ * 二重引用符を二重にすることでエスケープを行い、全体を二重引用符で囲みます。
+ *
+ * @param value エスケープする識別子の文字列です。
+ * @returns エスケープ済みの識別子文字列を返します。
+ */
 export function ident(value) {
     return '"' + value.replace(DOUBLE_QUOTE_REGEX, '""') + '"';
 }
+/**
+ * 一重引用符をエスケープするための正規表現です。
+ */
+const SINGLE_QUOTE_REGEX = /'/g;
+/**
+ * 文字列を SQL のリテラル文字列として安全にエスケープします。
+ *
+ * 一重引用符を二重にすることでエスケープを行い、全体を一重引用符で囲みます。
+ *
+ * @param value エスケープする文字列です。
+ * @returns エスケープ済みのリテラル文字列を返します。
+ */
+export function literal(value) {
+    return "'" + value.replace(SINGLE_QUOTE_REGEX, "''") + "'";
+}

package/dist/src/sql.d.ts

@@ -1,15 +1,54 @@
-import { join, raw, Sql, ident } from "./core.js";
+import { join, raw, Sql, ident, literal } from "./core.js";
 declare namespace sql {
+    /**
+     * SQL クエリーの構築に使用できる生の値、または別の Sql インスタンスを表す型です。
+     */
     type RawValue = import("./core.js").RawValue;
+    /**
+     * SQL クエリー内で使用される値の型定義です。
+     */
     type Value = import("./core.js").Value;
+    /**
+     * 安全な SQL クエリーを構築するためのクラス型です。
+     */
     type Sql = import("./core.js").Sql;
 }
+/**
+ * テンプレートリテラルを使用して SQL クエリーを安全に構築するためのタグ関数です。
+ *
+ * @param strings テンプレートリテラルの静的な文字列部分の配列です。
+ * @param bindings テンプレートリテラルに埋め込まれた動的な値の配列です。
+ * @returns パラメーター化された SQL 情報を保持する Sql インスタンスを返します。
+ * @example
+ * ```typescript
+ * const query = sql`SELECT * FROM users WHERE id = ${1}`;
+ * ```
+ */
 declare const sql: ((strings: TemplateStringsArray, ...bindings: readonly sql.RawValue[]) => sql.Sql) & {
+    /**
+     * Sql クラス自体への参照です。
+     */
     readonly Sql: typeof Sql;
+    /**
+     * 生の文字列を SQL 断片として扱うための関数です。
+     */
     readonly raw: typeof raw;
+    /**
+     * 複数の SQL 断片を結合するための関数です。
+     */
     readonly join: typeof join;
+    /**
+     * 空の SQL クエリーを表す定数です。
+     */
     readonly empty: Sql;
+    /**
+     * 識別子（テーブル名等）を安全にエスケープするための関数です。
+     */
     readonly ident: typeof ident;
+    /**
+     * 文字列を安全にエスケープするための関数です。
+     */
+    readonly literal: typeof literal;
 };
 export { sql };
 //# sourceMappingURL=sql.d.ts.map

package/dist/src/sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/sql.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAEzD,kBAAU,GAAG,CAAC;IACZ,KAAY,QAAQ,GAAG,OAAO,WAAW,EAAE,QAAQ,CAAC;IAEpD,KAAY,KAAK,GAAG,OAAO,WAAW,EAAE,KAAK,CAAC;IAE9C,KAAY,GAAG,GAAG,OAAO,WAAW,EAAE,GAAG,CAAC;CAC3C;AAED,QAAA,MAAM,GAAG,aACe,oBAAoB,eAAe,SAAS,GAAG,CAAC,QAAQ,EAAE,KAAG,GAAG,CAAC,GAAG;;;;;;CAU3F,CAAC;AAEF,OAAO,EAAE,GAAG,EAAE,CAAC"}
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/sql.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAElE,kBAAU,GAAG,CAAC;IACZ;;OAEG;IACH,KAAY,QAAQ,GAAG,OAAO,WAAW,EAAE,QAAQ,CAAC;IAEpD;;OAEG;IACH,KAAY,KAAK,GAAG,OAAO,WAAW,EAAE,KAAK,CAAC;IAE9C;;OAEG;IACH,KAAY,GAAG,GAAG,OAAO,WAAW,EAAE,GAAG,CAAC;CAC3C;AAED;;;;;;;;;;GAUG;AACH,QAAA,MAAM,GAAG,aACe,oBAAoB,eAAe,SAAS,GAAG,CAAC,QAAQ,EAAE,KAAG,GAAG,CAAC,GAAG;IAIxF;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;CAGN,CAAC;AAEF,OAAO,EAAE,GAAG,EAAE,CAAC"}

package/dist/src/sql.js

@@ -1,11 +1,41 @@
-import { empty, join, raw, Sql, ident } from "./core.js";
+import { empty, join, raw, Sql, ident, literal } from "./core.js";
+/**
+ * テンプレートリテラルを使用して SQL クエリーを安全に構築するためのタグ関数です。
+ *
+ * @param strings テンプレートリテラルの静的な文字列部分の配列です。
+ * @param bindings テンプレートリテラルに埋め込まれた動的な値の配列です。
+ * @returns パラメーター化された SQL 情報を保持する Sql インスタンスを返します。
+ * @example
+ * ```typescript
+ * const query = sql`SELECT * FROM users WHERE id = ${1}`;
+ * ```
+ */
 const sql = /*#__PURE__*/ Object.assign(function sql(strings, ...bindings) {
     return new Sql(strings, bindings);
 }, {
+    /**
+     * Sql クラス自体への参照です。
+     */
     Sql,
+    /**
+     * 生の文字列を SQL 断片として扱うための関数です。
+     */
     raw,
+    /**
+     * 複数の SQL 断片を結合するための関数です。
+     */
     join,
+    /**
+     * 空の SQL クエリーを表す定数です。
+     */
     empty,
+    /**
+     * 識別子（テーブル名等）を安全にエスケープするための関数です。
+     */
     ident,
+    /**
+     * 文字列を安全にエスケープするための関数です。
+     */
+    literal,
 });
 export { sql };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgsql-template-tag",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "",
   "homepage": "https://github.com/tai-kun/pgsql-template-tag",
   "license": "MIT",

package/src/core.ts

@@ -1,43 +1,79 @@
+/**
+ * SQL クエリー内で使用される値の型定義です。
+ */
 export type Value = unknown;
 
+/**
+ * SQL クエリーの構築に使用できる生の値、または別の Sql インスタンスを表す型です。
+ */
 // oxlint-disable-next-line typescript/no-redundant-type-constituents
 export type RawValue = Value | Sql;
 
+/**
+ * Sql クラスの内部状態を管理するためのプライベートな型定義です。
+ */
+type PrivateState = {
+  /**
+   * クエリーを構成する静的な文字列の配列です。
+   */
+  readonly s: readonly [string, ...string[]];
+
+  /**
+   * プレースホルダーに対応するインデックス（1 から始まる数値）の配列です。
+   */
+  readonly p: readonly number[];
+
+  /**
+   * キャッシュされた最終的なクエリーテキストです。
+   */
+  t?: string;
+};
+
+/**
+ * 安全な SQL クエリーを構築するためのクラスです。
+ * プレースホルダーを使用したパラメーター化クエリーを生成します。
+ */
 export class Sql {
+  /**
+   * 構築された SQL クエリーテキストを取得します。
+   *
+   * 初回アクセス時に文字列が結合され、結果はキャッシュされます。
+   *
+   * @returns SQL クエリーテキストを返します。
+   */
   public get text(): string {
-    if (!this._.t.c) {
-      let text = this._.s[0],
-        placeholderIds = this._.t.v;
-      if (placeholderIds.length > 0) {
-        for (let i = 0, len = placeholderIds.length; i < len; i++) {
-          text += "$" + placeholderIds[i] + this._.s[i + 1];
-        }
+    // キャッシュが存在しない場合にのみ、文字列を構築します。
+    if (this._.t === undefined) {
+      let i = 0,
+        text = this._.s[0];
+
+      // 文字列の断片とプレースホルダー（$1, $2...）を交互に結合します。
+      for (; i < this._.p.length; i++) {
+        text += "$" + this._.p[i] + this._.s[i + 1];
       }
 
-      this._.t = {
-        c: true,
-        v: text,
-      };
+      this._.t = text;
     }
 
-    return this._.t.v;
+    return this._.t;
   }
 
+  /**
+   * クエリーに使用されるパラメーター値の配列です。
+   */
   public readonly values: readonly Value[];
 
-  private readonly _: {
-    t:
-      | {
-          readonly c: false;
-          readonly v: readonly number[];
-        }
-      | {
-          readonly c: true;
-          readonly v: string;
-        };
-    readonly s: readonly [string, ...string[]];
-  };
-
+  /**
+   * 内部状態を保持するためのプロパティーです。
+   */
+  private readonly _!: PrivateState;
+
+  /**
+   * 新しい Sql インスタンスを初期化します。
+   *
+   * @param rawStrings SQL の断片となる文字列の配列です。
+   * @param rawBindings 文字列の間に挿入される値の配列です。
+   */
   public constructor(rawStrings: readonly string[], rawBindings: readonly RawValue[]) {
     if (rawStrings.length === 0) {
       throw new TypeError("Expected at least 1 string");
@@ -53,65 +89,66 @@ export class Sql {
     const bindings: Value[] = [];
     const placeholderIds: number[] = [];
 
-    if (rawStrings.length > 0) {
-      const valueToId = new Map<Value, number>();
-
-      for (
-        let i = 0,
-          len = rawBindings.length,
-          child: unknown,
-          rawString: string,
-          placeholderId: number | undefined;
-        i < len;
-        i++
-      ) {
-        child = rawBindings[i];
-        rawString = rawStrings[i + 1]!;
-
-        if (child instanceof Sql) {
-          strings[strings.length - 1] += child._.s[0];
-
-          for (let j = 0, value: unknown; j < child.values.length; j++) {
-            value = child.values[j];
-            placeholderId = valueToId.get(value);
-            if (placeholderId === undefined) {
-              bindings.push(value);
-              placeholderId = bindings.length;
-              valueToId.set(value, placeholderId);
-            }
-
-            strings.push(child._.s[j + 1]!);
-            placeholderIds.push(placeholderId);
-          }
+    /** 値の重複を排除し、同じ値には同じプレースホルダー ID を割り当てるためのマップです。 */
+    const valueToId = new Map<Value, number>();
+
+    // 提供された全てのバインディング値を走査して、SQL 文字列と値を正規化します。
+    for (let i = 0; i < rawBindings.length; i++) {
+      const child = rawBindings[i];
+      const rawString = rawStrings[i + 1]!;
+
+      // バインディング値が Sql インスタンス（ネストされたクエリー）の場合の処理です。
+      if (child instanceof Sql) {
+        // 現在の最後の文字列断片に、ネストされた Sql の最初の断片を結合します。
+        strings[strings.length - 1] += child._.s[0];
 
-          strings[strings.length - 1] += rawString;
-        } else {
-          placeholderId = valueToId.get(child);
+        // ネストされた Sql のプレースホルダーと値を再マッピングします。
+        for (let j = 0; j < child._.p.length; j++) {
+          const childPlaceholderId = child._.p[j]!;
+          const value = child.values[childPlaceholderId - 1]!;
 
+          let placeholderId = valueToId.get(value);
           if (placeholderId === undefined) {
-            bindings.push(child);
+            bindings.push(value);
             placeholderId = bindings.length;
-            valueToId.set(child, placeholderId);
+            valueToId.set(value, placeholderId);
           }
 
-          strings.push(rawString);
+          strings.push(child._.s[j + 1]!);
           placeholderIds.push(placeholderId);
         }
+
+        // ネストされた Sql の展開が終わった後に、後続の生の文字列を結合します。
+        strings[strings.length - 1] += rawString;
+      } else {
+        let placeholderId = valueToId.get(child);
+        if (placeholderId === undefined) {
+          bindings.push(child);
+          placeholderId = bindings.length;
+          valueToId.set(child, placeholderId);
+        }
+
+        strings.push(rawString);
+        placeholderIds.push(placeholderId);
       }
     }
 
     this.values = bindings;
+
+    // 内部状態を隠蔽し、不必要なプロパティーの露出を防ぎます。
     Object.defineProperty(this, "_", {
-      value: (this._ = {
-        t: {
-          c: false,
-          v: placeholderIds,
-        },
+      value: {
         s: strings,
-      }),
+        p: placeholderIds,
+      },
     });
   }
 
+  /**
+   * オブジェクトを JSON 形式に変換可能な形式で返します。
+   *
+   * @returns クエリーテキストと値の配列を含むオブジェクトを返します。
+   */
   public toJSON(): {
     text: string;
     values: Value[];
@@ -122,17 +159,41 @@ export class Sql {
     };
   }
 
+  /**
+   * インスタンスを文字列に変換します。
+   *
+   * @returns 構築された SQL クエリーテキストを返します。
+   */
   public toString(): string {
     return this.text;
   }
 }
 
+/**
+ * 生の文字列を SQL 断片として扱います。
+ * この値はパラメーター化の対象にならず、そのままクエリーに含まれます。
+ *
+ * @param value SQL に含める生の文字列です。
+ * @returns 指定された文字列を持つ Sql インスタンスを返します。
+ */
 export function raw(value: string): Sql {
   return new Sql([value], []);
 }
 
+/**
+ * 空の SQL インスタンスを表す定数です。
+ */
 export const empty: Sql = raw("");
 
+/**
+ * 複数の SQL 断片や値を、指定されたセパレーターで結合します。
+ *
+ * 配列が空の場合は、{@link empty} を返します。
+ *
+ * @param values 結合対象となる値の配列です。
+ * @param separator 結合時に挿入される文字列です。デフォルトはカンマ（,）です。
+ * @returns 結合された新しい Sql インスタンスを返します。
+ */
 export function join(values: readonly RawValue[], separator: string | undefined = ","): Sql {
   if (values.length === 0) {
     return empty;
@@ -141,8 +202,36 @@ export function join(values: readonly RawValue[], separator: string | undefined
   return new Sql(["", ...Array(values.length - 1).fill(separator), ""], values);
 }
 
+/**
+ * 二重引用符をエスケープするための正規表現です。
+ */
 const DOUBLE_QUOTE_REGEX = /"/g;
 
+/**
+ * 文字列を SQL の識別子（テーブル名やカラム名など）として安全にエスケープします。
+ *
+ * 二重引用符を二重にすることでエスケープを行い、全体を二重引用符で囲みます。
+ *
+ * @param value エスケープする識別子の文字列です。
+ * @returns エスケープ済みの識別子文字列を返します。
+ */
 export function ident(value: string): string {
   return '"' + value.replace(DOUBLE_QUOTE_REGEX, '""') + '"';
 }
+
+/**
+ * 一重引用符をエスケープするための正規表現です。
+ */
+const SINGLE_QUOTE_REGEX = /'/g;
+
+/**
+ * 文字列を SQL のリテラル文字列として安全にエスケープします。
+ *
+ * 一重引用符を二重にすることでエスケープを行い、全体を一重引用符で囲みます。
+ *
+ * @param value エスケープする文字列です。
+ * @returns エスケープ済みのリテラル文字列を返します。
+ */
+export function literal(value: string): string {
+  return "'" + value.replace(SINGLE_QUOTE_REGEX, "''") + "'";
+}

package/src/sql.ts

@@ -1,23 +1,67 @@
-import { empty, join, raw, Sql, ident } from "./core.js";
+import { empty, join, raw, Sql, ident, literal } from "./core.js";
 
 namespace sql {
+  /**
+   * SQL クエリーの構築に使用できる生の値、または別の Sql インスタンスを表す型です。
+   */
   export type RawValue = import("./core.js").RawValue;
 
+  /**
+   * SQL クエリー内で使用される値の型定義です。
+   */
   export type Value = import("./core.js").Value;
 
+  /**
+   * 安全な SQL クエリーを構築するためのクラス型です。
+   */
   export type Sql = import("./core.js").Sql;
 }
 
+/**
+ * テンプレートリテラルを使用して SQL クエリーを安全に構築するためのタグ関数です。
+ *
+ * @param strings テンプレートリテラルの静的な文字列部分の配列です。
+ * @param bindings テンプレートリテラルに埋め込まれた動的な値の配列です。
+ * @returns パラメーター化された SQL 情報を保持する Sql インスタンスを返します。
+ * @example
+ * ```typescript
+ * const query = sql`SELECT * FROM users WHERE id = ${1}`;
+ * ```
+ */
 const sql = /*#__PURE__*/ Object.assign(
   function sql(strings: TemplateStringsArray, ...bindings: readonly sql.RawValue[]): sql.Sql {
     return new Sql(strings, bindings);
   },
   {
+    /**
+     * Sql クラス自体への参照です。
+     */
     Sql,
+
+    /**
+     * 生の文字列を SQL 断片として扱うための関数です。
+     */
     raw,
+
+    /**
+     * 複数の SQL 断片を結合するための関数です。
+     */
     join,
+
+    /**
+     * 空の SQL クエリーを表す定数です。
+     */
     empty,
+
+    /**
+     * 識別子（テーブル名等）を安全にエスケープするための関数です。
+     */
     ident,
+
+    /**
+     * 文字列を安全にエスケープするための関数です。
+     */
+    literal,
   } as const,
 );