pgsql-template-tag 0.0.4 → 0.0.6

package/dist/src/core.d.ts

@@ -5,9 +5,32 @@ export type Value = unknown;
 /**
  * SQL クエリーの構築に使用できる生の値、または別の Sql インスタンスを表す型です。
  */
-export type RawValue = Value | Sql;
+export type RawValue = Value | Slot | Sql;
+/**
+ * スロットを表すクラスです。
+ *
+ * スロットは後から値を注入可能なプレースホルダーです。
+ */
+export declare class Slot {
+    /**
+     * スロット名です。
+     */
+    readonly name: string;
+    /**
+     * デフォルト値です。
+     */
+    readonly defaultValue: Value;
+    /**
+     * 新しい Slot インスタンスを初期化します。
+     *
+     * @param name スロット名です。
+     * @param defaultValue デフォルト値です。
+     */
+    constructor(name: string, defaultValue?: Value);
+}
 /**
  * 安全な SQL クエリーを構築するためのクラスです。
+ *
  * プレースホルダーを使用したパラメーター化クエリーを生成します。
  */
 export declare class Sql {
@@ -34,6 +57,15 @@ export declare class Sql {
      * @param rawBindings 文字列の間に挿入される値の配列です。
      */
     constructor(rawStrings: readonly string[], rawBindings: readonly RawValue[]);
+    /**
+     * スロットを値で埋めます。
+     *
+     * @param slots スロットの値です。
+     * @returns スロットが埋められた新しい Sql インスタンスです。
+     */
+    fill(slots: {
+        readonly [name: string]: Value;
+    } | Iterable<readonly [string | Slot, Value]>): Sql;
     /**
      * オブジェクトを JSON 形式に変換可能な形式で返します。
      *
@@ -52,6 +84,7 @@ export declare class Sql {
 }
 /**
  * 生の文字列を SQL 断片として扱います。
+ *
  * この値はパラメーター化の対象にならず、そのままクエリーに含まれます。
  *
  * @param value SQL に含める生の文字列です。
@@ -81,4 +114,13 @@ export declare function join(values: readonly RawValue[], separator?: string | u
  * @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;;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"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,CAAC;AAE5B;;GAEG;AAEH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,IAAI,GAAG,GAAG,CAAC;AAE1C;;;;GAIG;AACH,qBAAa,IAAI;IACf;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,SAAgB,YAAY,EAAE,KAAK,CAAC;IAEpC;;;;;OAKG;gBACgB,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,KAAK;CAQtD;AAgCD;;;;GAIG;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;IA2GlF;;;;;OAKG;IACI,IAAI,CACT,KAAK,EAAE;QAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC,GACpF,GAAG;IAmCN;;;;OAIG;IACI,MAAM,IAAI;QACf,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,KAAK,EAAE,CAAC;KACjB;IAOD;;;;OAIG;IACI,QAAQ,IAAI,MAAM;CAG1B;AAED;;;;;;;GAOG;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,5 +1,27 @@
+import { isPlainObject } from "es-toolkit/predicate";
+/**
+ * スロットを表すクラスです。
+ *
+ * スロットは後から値を注入可能なプレースホルダーです。
+ */
+export class Slot {
+    /**
+     * 新しい Slot インスタンスを初期化します。
+     *
+     * @param name スロット名です。
+     * @param defaultValue デフォルト値です。
+     */
+    constructor(name, defaultValue) {
+        if (arguments.length < 2) {
+            defaultValue = null;
+        }
+        this.name = name;
+        this.defaultValue = defaultValue;
+    }
+}
 /**
  * 安全な SQL クエリーを構築するためのクラスです。
+ *
  * プレースホルダーを使用したパラメーター化クエリーを生成します。
  */
 export class Sql {
@@ -12,15 +34,15 @@ export class Sql {
      */
     get text() {
         // キャッシュが存在しない場合にのみ、文字列を構築します。
-        if (this._.t === undefined) {
-            let i = 0, text = this._.s[0];
+        if (this._.text === undefined) {
+            let i = 0, text = this._.parts[0];
             // 文字列の断片とプレースホルダー（$1, $2...）を交互に結合します。
-            for (; i < this._.p.length; i++) {
-                text += "$" + this._.p[i] + this._.s[i + 1];
+            for (; i < this._.phIds.length; i++) {
+                text += "$" + this._.phIds[i] + this._.parts[i + 1];
             }
-            this._.t = text;
+            this._.text = text;
         }
-        return this._.t;
+        return this._.text;
     }
     /**
      * 新しい Sql インスタンスを初期化します。
@@ -38,8 +60,44 @@ export class Sql {
         const strings = [rawStrings[0]];
         const bindings = [];
         const placeholderIds = [];
+        const idx2slot = new Map();
+        const slot2idx = new Map();
         /** 値の重複を排除し、同じ値には同じプレースホルダー ID を割り当てるためのマップです。 */
         const valueToId = new Map();
+        /** スロットごとのプレースホルダー ID を管理します。 */
+        const slotToId = new Map();
+        /**
+         * 値を bindings に登録し、placeholderId を取得します。
+         */
+        const registerValue = (value) => {
+            let placeholderId = valueToId.get(value);
+            if (placeholderId === undefined) {
+                bindings.push(value);
+                placeholderId = bindings.length;
+                valueToId.set(value, placeholderId);
+            }
+            return placeholderId;
+        };
+        /**
+         * スロットを bindings に登録し、placeholderId を取得します。
+         */
+        const registerSlot = (slot) => {
+            let placeholderId = slotToId.get(slot);
+            if (placeholderId === undefined) {
+                bindings.push(slot.defaultValue);
+                placeholderId = bindings.length;
+                slotToId.set(slot, placeholderId);
+                const index = placeholderId - 1;
+                idx2slot.set(index, slot);
+                let idxes = slot2idx.get(slot.name);
+                if (idxes === undefined) {
+                    idxes = new Set();
+                    slot2idx.set(slot.name, idxes);
+                }
+                idxes.add(index);
+            }
+            return placeholderId;
+        };
         // 提供された全てのバインディング値を走査して、SQL 文字列と値を正規化します。
         for (let i = 0; i < rawBindings.length; i++) {
             const child = rawBindings[i];
@@ -47,30 +105,22 @@ export class Sql {
             // バインディング値が Sql インスタンス（ネストされたクエリー）の場合の処理です。
             if (child instanceof Sql) {
                 // 現在の最後の文字列断片に、ネストされた Sql の最初の断片を結合します。
-                strings[strings.length - 1] += child._.s[0];
+                strings[strings.length - 1] += child._.parts[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(value);
-                        placeholderId = bindings.length;
-                        valueToId.set(value, placeholderId);
-                    }
-                    strings.push(child._.s[j + 1]);
+                for (let j = 0; j < child._.phIds.length; j++) {
+                    const childPlaceholderId = child._.phIds[j];
+                    const valueIndex = childPlaceholderId - 1;
+                    const value = child.values[valueIndex];
+                    const slot = child._.idx2slot.get(valueIndex);
+                    const placeholderId = slot !== undefined ? registerSlot(slot) : registerValue(value);
+                    strings.push(child._.parts[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);
-                }
+                const placeholderId = child instanceof Slot ? registerSlot(child) : registerValue(child);
                 strings.push(rawString);
                 placeholderIds.push(placeholderId);
             }
@@ -79,11 +129,51 @@ export class Sql {
         // 内部状態を隠蔽し、不必要なプロパティーの露出を防ぎます。
         Object.defineProperty(this, "_", {
             value: {
-                s: strings,
-                p: placeholderIds,
+                parts: strings,
+                phIds: placeholderIds,
+                idx2slot,
+                slot2idx,
             },
         });
     }
+    /**
+     * スロットを値で埋めます。
+     *
+     * @param slots スロットの値です。
+     * @returns スロットが埋められた新しい Sql インスタンスです。
+     */
+    fill(slots) {
+        if (isPlainObject(slots)) {
+            slots = Object.entries(slots);
+        }
+        else {
+            // 一旦 Map のインスタンスにすることで、重複する名前またはスロットを 1 つに絞ります。
+            slots = new Map(slots);
+        }
+        const values = [...this.values];
+        for (const [target, value] of new Map(slots)) {
+            let idxes;
+            if (typeof target === "string") {
+                idxes = this._.slot2idx.get(target);
+            }
+            else {
+                for (const [idx, slot] of this._.idx2slot) {
+                    if (slot === target) {
+                        idxes || (idxes = new Set());
+                        idxes.add(idx);
+                    }
+                }
+            }
+            if (idxes === undefined) {
+                // スロットが見つからない場合は無視します。
+                continue;
+            }
+            for (const idx of idxes) {
+                values[idx] = value;
+            }
+        }
+        return new Sql(this._.parts, values);
+    }
     /**
      * オブジェクトを JSON 形式に変換可能な形式で返します。
      *
@@ -106,6 +196,7 @@ export class Sql {
 }
 /**
  * 生の文字列を SQL 断片として扱います。
+ *
  * この値はパラメーター化の対象にならず、そのままクエリーに含まれます。
  *
  * @param value SQL に含める生の文字列です。
@@ -148,3 +239,18 @@ const DOUBLE_QUOTE_REGEX = /"/g;
 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/index.d.ts

@@ -1,3 +1,3 @@
-export { empty, join, raw, ident, type RawValue, Sql, type Value } from "./core.js";
+export { type Value, type RawValue, Sql, Slot, empty, join, raw, ident } from "./core.js";
 export { sql } from "./sql.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,QAAQ,EAAE,GAAG,EAAE,KAAK,KAAK,EAAE,MAAM,WAAW,CAAC;AAEpF,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAE1F,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}

package/dist/src/index.js

@@ -1,2 +1,2 @@
-export { empty, join, raw, ident, Sql } from "./core.js";
+export { Sql, Slot, empty, join, raw, ident } from "./core.js";
 export { sql } from "./sql.js";

package/dist/src/sql.d.ts

@@ -1,4 +1,4 @@
-import { join, raw, Sql, ident } from "./core.js";
+import { join, raw, Sql, ident, literal, Slot } from "./core.js";
 declare namespace sql {
     /**
      * SQL クエリーの構築に使用できる生の値、または別の Sql インスタンスを表す型です。
@@ -8,11 +8,25 @@ declare namespace sql {
      * SQL クエリー内で使用される値の型定義です。
      */
     type Value = import("./core.js").Value;
+    /**
+     * スロットを表すクラスです。
+     *
+     * スロットは後から値を注入可能なプレースホルダーです。
+     */
+    type Slot = import("./core.js").Slot;
     /**
      * 安全な SQL クエリーを構築するためのクラス型です。
      */
     type Sql = import("./core.js").Sql;
 }
+/**
+ * 新しい Slot インスタンスを作成します。
+ *
+ * @param name スロット名です。
+ * @param defaultValue デフォルト値です。
+ * @returns 作成された新しい Slot インスタンスです。
+ */
+declare function slot(name: string, defaultValue?: sql.Value): sql.Slot;
 /**
  * テンプレートリテラルを使用して SQL クエリーを安全に構築するためのタグ関数です。
  *
@@ -26,13 +40,23 @@ declare namespace sql {
  */
 declare const sql: ((strings: TemplateStringsArray, ...bindings: readonly sql.RawValue[]) => sql.Sql) & {
     /**
-     * Sql クラス自体への参照です。
+     * Sql クラスです。
      */
     readonly Sql: typeof Sql;
     /**
      * 生の文字列を SQL 断片として扱うための関数です。
      */
     readonly raw: typeof raw;
+    /**
+     *　新しい Slot インスタンスを作成する関数です。
+     */
+    readonly slot: typeof slot;
+    /**
+     * スロットを表すクラスです。
+     *
+     * スロットは後から値を注入可能なプレースホルダーです。
+     */
+    readonly Slot: typeof Slot;
     /**
      * 複数の SQL 断片を結合するための関数です。
      */
@@ -45,6 +69,10 @@ declare const sql: ((strings: TemplateStringsArray, ...bindings: readonly sql.Ra
      * 識別子（テーブル名等）を安全にエスケープするための関数です。
      */
     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;;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;;CAGN,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,IAAI,EAAE,MAAM,WAAW,CAAC;AAExE,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;;;;OAIG;IACH,KAAY,IAAI,GAAG,OAAO,WAAW,EAAE,IAAI,CAAC;IAE5C;;OAEG;IACH,KAAY,GAAG,GAAG,OAAO,WAAW,EAAE,GAAG,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,iBAAS,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC;AAMhE;;;;;;;;;;GAUG;AACH,QAAA,MAAM,GAAG,aACe,oBAAoB,eAAe,SAAS,GAAG,CAAC,QAAQ,EAAE,KAAG,GAAG,CAAC,GAAG;IAIxF;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;;;OAIG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;CAGN,CAAC;AAEF,OAAO,EAAE,GAAG,EAAE,CAAC"}

package/dist/src/sql.js

@@ -1,4 +1,7 @@
-import { empty, join, raw, Sql, ident } from "./core.js";
+import { empty, join, raw, Sql, ident, literal, Slot } from "./core.js";
+function slot(...args) {
+    return new sql.Slot(...args);
+}
 /**
  * テンプレートリテラルを使用して SQL クエリーを安全に構築するためのタグ関数です。
  *
@@ -14,13 +17,23 @@ const sql = /*#__PURE__*/ Object.assign(function sql(strings, ...bindings) {
     return new Sql(strings, bindings);
 }, {
     /**
-     * Sql クラス自体への参照です。
+     * Sql クラスです。
      */
     Sql,
     /**
      * 生の文字列を SQL 断片として扱うための関数です。
      */
     raw,
+    /**
+     *　新しい Slot インスタンスを作成する関数です。
+     */
+    slot,
+    /**
+     * スロットを表すクラスです。
+     *
+     * スロットは後から値を注入可能なプレースホルダーです。
+     */
+    Slot,
     /**
      * 複数の SQL 断片を結合するための関数です。
      */
@@ -33,5 +46,9 @@ const sql = /*#__PURE__*/ Object.assign(function sql(strings, ...bindings) {
      * 識別子（テーブル名等）を安全にエスケープするための関数です。
      */
     ident,
+    /**
+     * 文字列を安全にエスケープするための関数です。
+     */
+    literal,
 });
 export { sql };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgsql-template-tag",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "",
   "homepage": "https://github.com/tai-kun/pgsql-template-tag",
   "license": "MIT",
@@ -25,6 +25,9 @@
       "default": "./dist/src/index.js"
     }
   },
+  "dependencies": {
+    "es-toolkit": "^1.46.1"
+  },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.4",
     "@tsconfig/strictest": "^2.0.8",
@@ -33,9 +36,9 @@
     "@vitest/browser": "^4.1.5",
     "@vitest/browser-playwright": "^4.1.5",
     "npm-check-updates": "^20.0.2",
-    "oxfmt": "^0.46.0",
-    "oxlint": "^1.61.0",
-    "oxlint-tsgolint": "^0.22.0",
+    "oxfmt": "^0.47.0",
+    "oxlint": "^1.62.0",
+    "oxlint-tsgolint": "^0.22.1",
     "playwright": "^1.59.1",
     "typescript": "^6.0.3",
     "vite": "^8.0.10",

package/src/core.ts

@@ -1,3 +1,5 @@
+import { isPlainObject } from "es-toolkit/predicate";
+
 /**
  * SQL クエリー内で使用される値の型定義です。
  */
@@ -7,7 +9,39 @@ export type Value = unknown;
  * SQL クエリーの構築に使用できる生の値、または別の Sql インスタンスを表す型です。
  */
 // oxlint-disable-next-line typescript/no-redundant-type-constituents
-export type RawValue = Value | Sql;
+export type RawValue = Value | Slot | Sql;
+
+/**
+ * スロットを表すクラスです。
+ *
+ * スロットは後から値を注入可能なプレースホルダーです。
+ */
+export class Slot {
+  /**
+   * スロット名です。
+   */
+  public readonly name: string;
+
+  /**
+   * デフォルト値です。
+   */
+  public readonly defaultValue: Value;
+
+  /**
+   * 新しい Slot インスタンスを初期化します。
+   *
+   * @param name スロット名です。
+   * @param defaultValue デフォルト値です。
+   */
+  public constructor(name: string, defaultValue?: Value) {
+    if (arguments.length < 2) {
+      defaultValue = null;
+    }
+
+    this.name = name;
+    this.defaultValue = defaultValue;
+  }
+}
 
 /**
  * Sql クラスの内部状態を管理するためのプライベートな型定義です。
@@ -16,21 +50,32 @@ type PrivateState = {
   /**
    * クエリーを構成する静的な文字列の配列です。
    */
-  readonly s: readonly [string, ...string[]];
+  readonly parts: readonly [string, ...string[]];
 
   /**
    * プレースホルダーに対応するインデックス（1 から始まる数値）の配列です。
    */
-  readonly p: readonly number[];
+  readonly phIds: readonly number[];
+
+  /**
+   * values のインデックス -> スロット情報 のマップです。
+   */
+  readonly idx2slot: ReadonlyMap<number, Slot>;
+
+  /**
+   * スロット名 -> values のインデックス のマップです。
+   */
+  readonly slot2idx: ReadonlyMap<string, ReadonlySet<number>>;
 
   /**
    * キャッシュされた最終的なクエリーテキストです。
    */
-  t?: string;
+  text?: string;
 };
 
 /**
  * 安全な SQL クエリーを構築するためのクラスです。
+ *
  * プレースホルダーを使用したパラメーター化クエリーを生成します。
  */
 export class Sql {
@@ -43,19 +88,19 @@ export class Sql {
    */
   public get text(): string {
     // キャッシュが存在しない場合にのみ、文字列を構築します。
-    if (this._.t === undefined) {
+    if (this._.text === undefined) {
       let i = 0,
-        text = this._.s[0];
+        text = this._.parts[0];
 
       // 文字列の断片とプレースホルダー（$1, $2...）を交互に結合します。
-      for (; i < this._.p.length; i++) {
-        text += "$" + this._.p[i] + this._.s[i + 1];
+      for (; i < this._.phIds.length; i++) {
+        text += "$" + this._.phIds[i] + this._.parts[i + 1];
       }
 
-      this._.t = text;
+      this._.text = text;
     }
 
-    return this._.t;
+    return this._.text;
   }
 
   /**
@@ -88,10 +133,52 @@ export class Sql {
     const strings: [string, ...string[]] = [rawStrings[0]!];
     const bindings: Value[] = [];
     const placeholderIds: number[] = [];
+    const idx2slot = new Map<number, Slot>();
+    const slot2idx = new Map<string, Set<number>>();
 
     /** 値の重複を排除し、同じ値には同じプレースホルダー ID を割り当てるためのマップです。 */
     const valueToId = new Map<Value, number>();
 
+    /** スロットごとのプレースホルダー ID を管理します。 */
+    const slotToId = new Map<Slot, number>();
+
+    /**
+     * 値を bindings に登録し、placeholderId を取得します。
+     */
+    const registerValue = (value: Value): number => {
+      let placeholderId = valueToId.get(value);
+      if (placeholderId === undefined) {
+        bindings.push(value);
+        placeholderId = bindings.length;
+        valueToId.set(value, placeholderId);
+      }
+
+      return placeholderId;
+    };
+
+    /**
+     * スロットを bindings に登録し、placeholderId を取得します。
+     */
+    const registerSlot = (slot: Slot): number => {
+      let placeholderId = slotToId.get(slot);
+      if (placeholderId === undefined) {
+        bindings.push(slot.defaultValue);
+        placeholderId = bindings.length;
+        slotToId.set(slot, placeholderId);
+
+        const index = placeholderId - 1;
+        idx2slot.set(index, slot);
+        let idxes = slot2idx.get(slot.name);
+        if (idxes === undefined) {
+          idxes = new Set();
+          slot2idx.set(slot.name, idxes);
+        }
+        idxes.add(index);
+      }
+
+      return placeholderId;
+    };
+
     // 提供された全てのバインディング値を走査して、SQL 文字列と値を正規化します。
     for (let i = 0; i < rawBindings.length; i++) {
       const child = rawBindings[i];
@@ -100,33 +187,26 @@ export class Sql {
       // バインディング値が Sql インスタンス（ネストされたクエリー）の場合の処理です。
       if (child instanceof Sql) {
         // 現在の最後の文字列断片に、ネストされた Sql の最初の断片を結合します。
-        strings[strings.length - 1] += child._.s[0];
+        strings[strings.length - 1] += child._.parts[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(value);
-            placeholderId = bindings.length;
-            valueToId.set(value, placeholderId);
-          }
+        for (let j = 0; j < child._.phIds.length; j++) {
+          const childPlaceholderId = child._.phIds[j]!;
+          const valueIndex = childPlaceholderId - 1;
+          const value = child.values[valueIndex]!;
+
+          const slot = child._.idx2slot.get(valueIndex);
+
+          const placeholderId = slot !== undefined ? registerSlot(slot) : registerValue(value);
 
-          strings.push(child._.s[j + 1]!);
+          strings.push(child._.parts[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);
-        }
+        const placeholderId = child instanceof Slot ? registerSlot(child) : registerValue(child);
 
         strings.push(rawString);
         placeholderIds.push(placeholderId);
@@ -138,12 +218,57 @@ export class Sql {
     // 内部状態を隠蔽し、不必要なプロパティーの露出を防ぎます。
     Object.defineProperty(this, "_", {
       value: {
-        s: strings,
-        p: placeholderIds,
-      },
+        parts: strings,
+        phIds: placeholderIds,
+        idx2slot,
+        slot2idx,
+      } satisfies PrivateState,
     });
   }
 
+  /**
+   * スロットを値で埋めます。
+   *
+   * @param slots スロットの値です。
+   * @returns スロットが埋められた新しい Sql インスタンスです。
+   */
+  public fill(
+    slots: { readonly [name: string]: Value } | Iterable<readonly [string | Slot, Value]>,
+  ): Sql {
+    if (isPlainObject(slots)) {
+      slots = Object.entries(slots);
+    } else {
+      // 一旦 Map のインスタンスにすることで、重複する名前またはスロットを 1 つに絞ります。
+      slots = new Map(slots);
+    }
+
+    const values: Value[] = [...this.values];
+    for (const [target, value] of new Map(slots)) {
+      let idxes: ReadonlySet<number> | undefined;
+      if (typeof target === "string") {
+        idxes = this._.slot2idx.get(target);
+      } else {
+        for (const [idx, slot] of this._.idx2slot) {
+          if (slot === target) {
+            idxes ||= new Set();
+            (idxes as Set<number>).add(idx);
+          }
+        }
+      }
+
+      if (idxes === undefined) {
+        // スロットが見つからない場合は無視します。
+        continue;
+      }
+
+      for (const idx of idxes) {
+        values[idx] = value;
+      }
+    }
+
+    return new Sql(this._.parts, values);
+  }
+
   /**
    * オブジェクトを JSON 形式に変換可能な形式で返します。
    *
@@ -171,6 +296,7 @@ export class Sql {
 
 /**
  * 生の文字列を SQL 断片として扱います。
+ *
  * この値はパラメーター化の対象にならず、そのままクエリーに含まれます。
  *
  * @param value SQL に含める生の文字列です。
@@ -218,3 +344,20 @@ const DOUBLE_QUOTE_REGEX = /"/g;
 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/index.ts

@@ -1,3 +1,3 @@
-export { empty, join, raw, ident, type RawValue, Sql, type Value } from "./core.js";
+export { type Value, type RawValue, Sql, Slot, empty, join, raw, ident } from "./core.js";
 
 export { sql } from "./sql.js";

package/src/sql.ts

@@ -1,4 +1,4 @@
-import { empty, join, raw, Sql, ident } from "./core.js";
+import { empty, join, raw, Sql, ident, literal, Slot } from "./core.js";
 
 namespace sql {
   /**
@@ -11,12 +11,32 @@ namespace sql {
    */
   export type Value = import("./core.js").Value;
 
+  /**
+   * スロットを表すクラスです。
+   *
+   * スロットは後から値を注入可能なプレースホルダーです。
+   */
+  export type Slot = import("./core.js").Slot;
+
   /**
    * 安全な SQL クエリーを構築するためのクラス型です。
    */
   export type Sql = import("./core.js").Sql;
 }
 
+/**
+ * 新しい Slot インスタンスを作成します。
+ *
+ * @param name スロット名です。
+ * @param defaultValue デフォルト値です。
+ * @returns 作成された新しい Slot インスタンスです。
+ */
+function slot(name: string, defaultValue?: sql.Value): sql.Slot;
+
+function slot(...args: [any]): sql.Slot {
+  return new sql.Slot(...args);
+}
+
 /**
  * テンプレートリテラルを使用して SQL クエリーを安全に構築するためのタグ関数です。
  *
@@ -34,7 +54,7 @@ const sql = /*#__PURE__*/ Object.assign(
   },
   {
     /**
-     * Sql クラス自体への参照です。
+     * Sql クラスです。
      */
     Sql,
 
@@ -43,6 +63,18 @@ const sql = /*#__PURE__*/ Object.assign(
      */
     raw,
 
+    /**
+     *　新しい Slot インスタンスを作成する関数です。
+     */
+    slot,
+
+    /**
+     * スロットを表すクラスです。
+     *
+     * スロットは後から値を注入可能なプレースホルダーです。
+     */
+    Slot,
+
     /**
      * 複数の SQL 断片を結合するための関数です。
      */
@@ -57,6 +89,11 @@ const sql = /*#__PURE__*/ Object.assign(
      * 識別子（テーブル名等）を安全にエスケープするための関数です。
      */
     ident,
+
+    /**
+     * 文字列を安全にエスケープするための関数です。
+     */
+    literal,
   } as const,
 );