pgsql-template-tag 0.0.5 → 0.0.7

package/dist/src/core.d.ts

@@ -1,3 +1,4 @@
+import type { UnionToTuple } from "type-fest";
 /**
  * SQL クエリー内で使用される値の型定義です。
  */
@@ -5,12 +6,123 @@ export type Value = unknown;
 /**
  * SQL クエリーの構築に使用できる生の値、または別の Sql インスタンスを表す型です。
  */
-export type RawValue = Value | Sql;
+export type RawValue = Value | Slot | Sql;
+/**
+ * Slot クラスを一意に識別するためのシンボルです。
+ */
+declare const SLOT_SYMBOL: unique symbol;
+/**
+ * Slot クラスの基底となる型定義です。
+ */
+declare const SlotTypes: {
+    new (): {
+        /**
+         * このプロパティーは、TypeScript の `extends Slot` で `Slot` インスタンスのみに一致させるためにあります。そのため、`Slot` と同じプロパティーを持つオブジェクトに対して一致することはありません。
+         */
+        readonly ["~kind"]: typeof SLOT_SYMBOL;
+    };
+};
+/**
+ * スロットを表すクラスです。
+ *
+ * スロットは後から値を注入可能なプレースホルダーです。
+ *
+ * @template TName スロットの名前となる文字列リテラル型です。
+ * @template TValue スロットに許容される値の型です。
+ */
+export declare class Slot<const TName extends string = string, TValue extends RawValue = RawValue> extends SlotTypes {
+    /**
+     * スロット名です。
+     */
+    readonly name: TName;
+    /**
+     * デフォルト値です。
+     */
+    readonly defaultValue: TValue;
+    /**
+     * 新しい Slot インスタンスを初期化します。
+     *
+     * @param name スロット名です。
+     * @param defaultValue デフォルト値です。
+     */
+    constructor(...args: null extends TValue ? [name: TName, defaultValue?: TValue] : [name: TName, defaultValue: TValue]);
+}
+/**
+ * オブジェクトのバリューの型を抽出するヘルパー型です。
+ *
+ * @template T 対象となるオブジェクト型です。
+ */
+type $ValueOf<T> = T[keyof T];
+/**
+ * スロットの配列から、再帰的に値をマージして型を決定します。
+ *
+ * @template TSlots スロットのタプル型です。
+ */
+type $MergeSlotValue<TSlots> = TSlots extends [
+    Slot<string, infer TValue>,
+    infer TSlot,
+    ...infer TOtherSlots
+] ? TValue & $MergeSlotValue<[TSlot, ...TOtherSlots]> : TSlots extends [Slot<string, infer TValue>] ? TValue : never;
+/**
+ * RawValue の配列からスロット情報を抽出し、名前ごとのマップ型に変換します。
+ *
+ * @template TValues RawValue の読み取り専用配列型です。
+ */
+type $MapSlotValue<TValues extends readonly RawValue[]> = TValues extends readonly (infer TSlot extends Slot)[] ? {
+    [TName in TSlot["name"]]: $MergeSlotValue<UnionToTuple<Extract<TSlot, Slot<TName>>>>;
+} : {};
+/**
+ * 指定された値のリストに対して、スロットを実際の内容で置き換えた型を生成します。
+ *
+ * @template TValues 置き換え対象の配列型です。
+ * @template TSlots スロット名と値のマップ型です。
+ */
+type $FillSlots<TValues, TSlots> = TValues extends [infer TValue, ...infer TOtherValues] ? [
+    TValue extends Slot<infer TName extends Extract<keyof TSlots, string>, infer TSlotValue> ? TSlotValue extends TSlots[TName] ? TSlotValue : TValue : TValue,
+    ...$FillSlots<TOtherValues, TSlots>
+] : [];
+/**
+ * スロットを埋めるための部分的な引数型を定義します。
+ *
+ * @template TSlots スロット名と値のマップ型です。
+ */
+type _FillSlots<TSlots> = {
+    readonly [TName in Extract<keyof TSlots, string>]?: TSlots[TName];
+} | Iterable<readonly [
+    name: $ValueOf<{
+        [TName in Extract<keyof TSlots, string>]: TName | Slot<TName, TSlots[TName]>;
+    }>,
+    value: $ValueOf<TSlots>
+]>;
+/**
+ * すべてのスロットを埋めるために必要な引数型を定義します。
+ *
+ * @template TSlots スロット名と値のマップ型です。
+ */
+type _FillAllSlots<TSlots> = {
+    readonly [TName in Extract<keyof TSlots, string>]: TSlots[TName];
+};
+/**
+ * スロットの部分的な補完に使用する外部向けの型定義です。
+ *
+ * @template TValues RawValue の配列です。
+ */
+export type FillSlots<TValues extends readonly RawValue[] = readonly RawValue[]> = _FillSlots<$MapSlotValue<TValues>>;
+/**
+ * すべてのスロットの強制的な補完に使用する外部向けの型定義です。
+ *
+ * @template TValues RawValue の配列です。
+ */
+export type FillAllSlots<TValues extends readonly RawValue[] = readonly RawValue[]> = _FillAllSlots<$MapSlotValue<TValues>>;
 /**
  * 安全な SQL クエリーを構築するためのクラスです。
+ *
  * プレースホルダーを使用したパラメーター化クエリーを生成します。
+ *
+ * @template TRawBindings クエリーに渡される生の値のタプル型です。
  */
-export declare class Sql {
+export declare class Sql<const TRawBindings extends readonly RawValue[] = readonly RawValue[]> {
+    #private;
     /**
      * 構築された SQL クエリーテキストを取得します。
      *
@@ -23,17 +135,29 @@ export declare class Sql {
      * クエリーに使用されるパラメーター値の配列です。
      */
     readonly values: readonly Value[];
-    /**
-     * 内部状態を保持するためのプロパティーです。
-     */
-    private readonly _;
     /**
      * 新しい Sql インスタンスを初期化します。
      *
      * @param rawStrings SQL の断片となる文字列の配列です。
      * @param rawBindings 文字列の間に挿入される値の配列です。
      */
-    constructor(rawStrings: readonly string[], rawBindings: readonly RawValue[]);
+    constructor(rawStrings: readonly string[], rawBindings: TRawBindings);
+    /**
+     * スロットを値で埋めます。
+     *
+     * @template TSlots 指定されたスロットのマップ型です。
+     * @param slots スロットの値です。
+     * @returns スロットが埋められた新しい Sql インスタンスです。
+     */
+    fill<TSlots extends FillSlots<TRawBindings>>(slots: TSlots): Sql<$FillSlots<TRawBindings, TSlots>>;
+    /**
+     * すべてのスロットを値で埋めます。
+     *
+     * @template TSlots 全てのスロットをカバーするマップ型です。
+     * @param slots スロットの値です。
+     * @returns スロットが埋められた新しい Sql インスタンスです。
+     */
+    fillAll<TSlots extends FillAllSlots<TRawBindings>>(slots: TSlots): Sql<$FillSlots<TRawBindings, TSlots>>;
     /**
      * オブジェクトを JSON 形式に変換可能な形式で返します。
      *
@@ -52,6 +176,7 @@ export declare class Sql {
 }
 /**
  * 生の文字列を SQL 断片として扱います。
+ *
  * この値はパラメーター化の対象にならず、そのままクエリーに含まれます。
  *
  * @param value SQL に含める生の文字列です。
@@ -90,4 +215,5 @@ export declare function ident(value: string): string;
  * @returns エスケープ済みのリテラル文字列を返します。
  */
 export declare function literal(value: string): string;
+export {};
 //# 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;AAOD;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7C"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"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"}

package/dist/src/core.js

@@ -1,6 +1,45 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _Sql_instances, _a, _Sql_state, _Sql_fill;
+import { isPlainObject } from "es-toolkit/predicate";
+/**
+ * Slot クラスの基底となる型定義です。
+ */
+const SlotTypes = class {
+};
+/**
+ * スロットを表すクラスです。
+ *
+ * スロットは後から値を注入可能なプレースホルダーです。
+ *
+ * @template TName スロットの名前となる文字列リテラル型です。
+ * @template TValue スロットに許容される値の型です。
+ */
+export class Slot extends SlotTypes {
+    constructor(name, defaultValue) {
+        super();
+        if (arguments.length < 2) {
+            defaultValue = null;
+        }
+        this.name = name;
+        this.defaultValue = defaultValue;
+    }
+}
 /**
  * 安全な SQL クエリーを構築するためのクラスです。
+ *
  * プレースホルダーを使用したパラメーター化クエリーを生成します。
+ *
+ * @template TRawBindings クエリーに渡される生の値のタプル型です。
  */
 export class Sql {
     /**
@@ -12,15 +51,15 @@ export class Sql {
      */
     get text() {
         // キャッシュが存在しない場合にのみ、文字列を構築します。
-        if (this._.t === undefined) {
-            let i = 0, text = this._.s[0];
+        if (__classPrivateFieldGet(this, _Sql_state, "f").text === undefined) {
+            let i = 0, text = __classPrivateFieldGet(this, _Sql_state, "f").parts[0];
             // 文字列の断片とプレースホルダー（$1, $2...）を交互に結合します。
-            for (; i < this._.p.length; i++) {
-                text += "$" + this._.p[i] + this._.s[i + 1];
+            for (; i < __classPrivateFieldGet(this, _Sql_state, "f").phIds.length; i++) {
+                text += "$" + __classPrivateFieldGet(this, _Sql_state, "f").phIds[i] + __classPrivateFieldGet(this, _Sql_state, "f").parts[i + 1];
             }
-            this._.t = text;
+            __classPrivateFieldGet(this, _Sql_state, "f").text = text;
         }
-        return this._.t;
+        return __classPrivateFieldGet(this, _Sql_state, "f").text;
     }
     /**
      * 新しい Sql インスタンスを初期化します。
@@ -29,6 +68,11 @@ export class Sql {
      * @param rawBindings 文字列の間に挿入される値の配列です。
      */
     constructor(rawStrings, rawBindings) {
+        _Sql_instances.add(this);
+        /**
+         * 内部状態を保持するためのプロパティーです。
+         */
+        _Sql_state.set(this, void 0);
         if (rawStrings.length === 0) {
             throw new TypeError("Expected at least 1 string");
         }
@@ -38,51 +82,98 @@ 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];
             const rawString = rawStrings[i + 1];
             // バインディング値が Sql インスタンス（ネストされたクエリー）の場合の処理です。
-            if (child instanceof Sql) {
+            if (child instanceof _a) {
                 // 現在の最後の文字列断片に、ネストされた Sql の最初の断片を結合します。
-                strings[strings.length - 1] += child._.s[0];
+                strings[strings.length - 1] += __classPrivateFieldGet(child, _Sql_state, "f").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 < __classPrivateFieldGet(child, _Sql_state, "f").phIds.length; j++) {
+                    const childPlaceholderId = __classPrivateFieldGet(child, _Sql_state, "f").phIds[j];
+                    const valueIndex = childPlaceholderId - 1;
+                    const value = child.values[valueIndex];
+                    const slot = __classPrivateFieldGet(child, _Sql_state, "f").idx2slot.get(valueIndex);
+                    const placeholderId = slot !== undefined ? registerSlot(slot) : registerValue(value);
+                    strings.push(__classPrivateFieldGet(child, _Sql_state, "f").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);
             }
         }
         this.values = bindings;
-        // 内部状態を隠蔽し、不必要なプロパティーの露出を防ぎます。
-        Object.defineProperty(this, "_", {
-            value: {
-                s: strings,
-                p: placeholderIds,
-            },
-        });
+        __classPrivateFieldSet(this, _Sql_state, {
+            parts: strings,
+            phIds: placeholderIds,
+            idx2slot,
+            slot2idx,
+        }, "f");
+    }
+    /**
+     * スロットを値で埋めます。
+     *
+     * @template TSlots 指定されたスロットのマップ型です。
+     * @param slots スロットの値です。
+     * @returns スロットが埋められた新しい Sql インスタンスです。
+     */
+    fill(slots) {
+        return __classPrivateFieldGet(this, _Sql_instances, "m", _Sql_fill).call(this, slots, false);
+    }
+    /**
+     * すべてのスロットを値で埋めます。
+     *
+     * @template TSlots 全てのスロットをカバーするマップ型です。
+     * @param slots スロットの値です。
+     * @returns スロットが埋められた新しい Sql インスタンスです。
+     */
+    fillAll(slots) {
+        return __classPrivateFieldGet(this, _Sql_instances, "m", _Sql_fill).call(this, slots, true);
     }
     /**
      * オブジェクトを JSON 形式に変換可能な形式で返します。
@@ -104,8 +195,61 @@ export class Sql {
         return this.text;
     }
 }
+_a = Sql, _Sql_state = new WeakMap(), _Sql_instances = new WeakSet(), _Sql_fill = function _Sql_fill(slots, all) {
+    if (isPlainObject(slots)) {
+        slots = Object.entries(slots);
+    }
+    else {
+        // 一旦 Map のインスタンスにすることで、重複する名前またはスロットを 1 つに絞ります。
+        slots = new Map(slots);
+    }
+    const { parts, idx2slot, slot2idx } = __classPrivateFieldGet(this, _Sql_state, "f");
+    const filled = new Set();
+    const values = this.values.slice();
+    for (const [target, value] of new Map(slots)) {
+        let idxes;
+        if (typeof target === "string") {
+            idxes = slot2idx.get(target);
+        }
+        else {
+            // インスタンスが直接指定された場合、全インデックスから一致するものを探します。
+            for (const [idx, slot] of idx2slot) {
+                if (slot === target) {
+                    idxes || (idxes = new Set());
+                    idxes.add(idx);
+                }
+            }
+        }
+        if (idxes === undefined) {
+            // スロットが見つからない場合は無視します。
+            continue;
+        }
+        // 該当するすべてのプレースホルダーインデックスを新しい値で更新します。
+        for (const idx of idxes) {
+            values[idx] = value;
+            filled.add(idx);
+        }
+    }
+    // 全て埋める必要がある場合、未解決のスロットが残っていないか検証します。
+    if (all) {
+        for (let idx = 0; idx < values.length; idx++) {
+            if (idx2slot.has(idx) && !filled.has(idx)) {
+                const missingSlots = new Set();
+                missingSlots.add(idx2slot.get(idx).name);
+                for (; idx < values.length; idx++) {
+                    if (idx2slot.has(idx)) {
+                        missingSlots.add(idx2slot.get(idx).name);
+                    }
+                }
+                throw new Error(`Not all slots are filled. Missing: ${[...missingSlots].join(", ")}`);
+            }
+        }
+    }
+    return new _a(parts, values);
+};
 /**
  * 生の文字列を SQL 断片として扱います。
+ *
  * この値はパラメーター化の対象にならず、そのままクエリーに含まれます。
  *
  * @param value SQL に含める生の文字列です。

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, literal } from "./core.js";
+import { join, raw, Sql, ident, literal, Slot, RawValue } from "./core.js";
 declare namespace sql {
     /**
      * SQL クエリーの構築に使用できる生の値、または別の Sql インスタンスを表す型です。
@@ -8,14 +8,36 @@ declare namespace sql {
      * SQL クエリー内で使用される値の型定義です。
      */
     type Value = import("./core.js").Value;
+    /**
+     * スロットを表すクラスです。
+     *
+     * スロットは後から値を注入可能なプレースホルダーです。
+     *
+     * @template TName スロットの名前となる文字列リテラル型です。
+     * @template TValue スロットに許容される値の型です。
+     */
+    type Slot<TName extends string = string, TValue extends RawValue = RawValue> = import("./core.js").Slot<TName, TValue>;
     /**
      * 安全な SQL クエリーを構築するためのクラス型です。
+     *
+     * @template TRawBindings クエリーに渡される生の値のタプル型です。
      */
-    type Sql = import("./core.js").Sql;
+    type Sql<TRawBindings extends readonly RawValue[] = readonly RawValue[]> = import("./core.js").Sql<TRawBindings>;
 }
+/**
+ * 新しい Slot インスタンスを作成します。
+ *
+ * @template TName スロットの名前となる文字列リテラル型です。
+ * @template TValue スロットに許容される値の型です。
+ * @param name スロット名です。
+ * @param defaultValue デフォルト値です。
+ * @returns 作成された新しい Slot インスタンスです。
+ */
+declare function slot<const TName extends string, TValue extends RawValue = RawValue>(name: TName, defaultValue?: TValue): sql.Slot<TName, TValue>;
 /**
  * テンプレートリテラルを使用して SQL クエリーを安全に構築するためのタグ関数です。
  *
+ * @template TRawBindings クエリーに渡される生の値のタプル型です。
  * @param strings テンプレートリテラルの静的な文字列部分の配列です。
  * @param bindings テンプレートリテラルに埋め込まれた動的な値の配列です。
  * @returns パラメーター化された SQL 情報を保持する Sql インスタンスを返します。
@@ -24,15 +46,25 @@ declare namespace sql {
  * const query = sql`SELECT * FROM users WHERE id = ${1}`;
  * ```
  */
-declare const sql: ((strings: TemplateStringsArray, ...bindings: readonly sql.RawValue[]) => sql.Sql) & {
+declare const sql: (<const TRawBindings extends readonly RawValue[]>(strings: TemplateStringsArray, ...bindings: TRawBindings) => sql.Sql<TRawBindings>) & {
     /**
-     * Sql クラス自体への参照です。
+     * Sql クラスです。
      */
     readonly Sql: typeof Sql;
     /**
      * 生の文字列を SQL 断片として扱うための関数です。
      */
     readonly raw: typeof raw;
+    /**
+     *　新しい Slot インスタンスを作成する関数です。
+     */
+    readonly slot: typeof slot;
+    /**
+     * スロットを表すクラスです。
+     *
+     * スロットは後から値を注入可能なプレースホルダーです。
+     */
+    readonly Slot: typeof Slot;
     /**
      * 複数の SQL 断片を結合するための関数です。
      */
@@ -40,7 +72,7 @@ declare const sql: ((strings: TemplateStringsArray, ...bindings: readonly sql.Ra
     /**
      * 空の SQL クエリーを表す定数です。
      */
-    readonly empty: Sql;
+    readonly empty: Sql<readonly unknown[]>;
     /**
      * 識別子（テーブル名等）を安全にエスケープするための関数です。
      */

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,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"}
+{"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,QAAQ,EAAE,MAAM,WAAW,CAAC;AAElF,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;;;;;;;OAOG;IACH,KAAY,IAAI,CACd,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,MAAM,SAAS,QAAQ,GAAG,QAAQ,IAChC,OAAO,WAAW,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAE5C;;;;OAIG;IACH,KAAY,GAAG,CAAC,YAAY,SAAS,SAAS,QAAQ,EAAE,GAAG,SAAS,QAAQ,EAAE,IAC5E,OAAO,WAAW,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,iBAAS,IAAI,CAAC,KAAK,CAAC,KAAK,SAAS,MAAM,EAAE,MAAM,SAAS,QAAQ,GAAG,QAAQ,EAC1E,IAAI,EAAE,KAAK,EACX,YAAY,CAAC,EAAE,MAAM,GACpB,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAM3B;;;;;;;;;;;GAWG;AACH,QAAA,MAAM,GAAG,UACY,YAAY,SAAS,SAAS,QAAQ,EAAE,WAChD,oBAAoB,eAChB,YAAY,KACxB,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC;IAItB;;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,7 +1,11 @@
-import { empty, join, raw, Sql, ident, literal } from "./core.js";
+import { empty, join, raw, Sql, ident, literal, Slot } from "./core.js";
+function slot(...args) {
+    return new sql.Slot(...args);
+}
 /**
  * テンプレートリテラルを使用して SQL クエリーを安全に構築するためのタグ関数です。
  *
+ * @template TRawBindings クエリーに渡される生の値のタプル型です。
  * @param strings テンプレートリテラルの静的な文字列部分の配列です。
  * @param bindings テンプレートリテラルに埋め込まれた動的な値の配列です。
  * @returns パラメーター化された SQL 情報を保持する Sql インスタンスを返します。
@@ -14,13 +18,23 @@ const sql = /*#__PURE__*/ Object.assign(function sql(strings, ...bindings) {
     return new Sql(strings, bindings);
 }, {
     /**
-     * Sql クラス自体への参照です。
+     * Sql クラスです。
      */
     Sql,
     /**
      * 生の文字列を SQL 断片として扱うための関数です。
      */
     raw,
+    /**
+     *　新しい Slot インスタンスを作成する関数です。
+     */
+    slot,
+    /**
+     * スロットを表すクラスです。
+     *
+     * スロットは後から値を注入可能なプレースホルダーです。
+     */
+    Slot,
     /**
      * 複数の SQL 断片を結合するための関数です。
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgsql-template-tag",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "",
   "homepage": "https://github.com/tai-kun/pgsql-template-tag",
   "license": "MIT",
@@ -25,6 +25,10 @@
       "default": "./dist/src/index.js"
     }
   },
+  "dependencies": {
+    "es-toolkit": "^1.46.1",
+    "type-fest": "^5.6.0"
+  },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.4",
     "@tsconfig/strictest": "^2.0.8",
@@ -33,9 +37,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,6 @@
+import { isPlainObject } from "es-toolkit/predicate";
+import type { UnionToTuple } from "type-fest";
+
 /**
  * SQL クエリー内で使用される値の型定義です。
  */
@@ -7,7 +10,167 @@ 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;
+
+/**
+ * Slot クラスを一意に識別するためのシンボルです。
+ */
+declare const SLOT_SYMBOL: unique symbol;
+
+/**
+ * Slot クラスの基底となる型定義です。
+ */
+const SlotTypes = class {} as {
+  new (): {
+    /**
+     * このプロパティーは、TypeScript の `extends Slot` で `Slot` インスタンスのみに一致させるためにあります。そのため、`Slot` と同じプロパティーを持つオブジェクトに対して一致することはありません。
+     */
+    readonly ["~kind"]: typeof SLOT_SYMBOL;
+  };
+};
+
+/**
+ * スロットを表すクラスです。
+ *
+ * スロットは後から値を注入可能なプレースホルダーです。
+ *
+ * @template TName スロットの名前となる文字列リテラル型です。
+ * @template TValue スロットに許容される値の型です。
+ */
+export class Slot<
+  const TName extends string = string,
+  TValue extends RawValue = RawValue,
+> extends SlotTypes {
+  /**
+   * スロット名です。
+   */
+  public readonly name: TName;
+
+  /**
+   * デフォルト値です。
+   */
+  public readonly defaultValue: TValue;
+
+  /**
+   * 新しい Slot インスタンスを初期化します。
+   *
+   * @param name スロット名です。
+   * @param defaultValue デフォルト値です。
+   */
+  public constructor(
+    ...args: null extends TValue
+      ? [name: TName, defaultValue?: TValue]
+      : [name: TName, defaultValue: TValue]
+  );
+
+  public constructor(name: TName, defaultValue?: RawValue) {
+    super();
+
+    if (arguments.length < 2) {
+      defaultValue = null;
+    }
+
+    this.name = name;
+    this.defaultValue = defaultValue as TValue;
+  }
+}
+
+/**
+ * オブジェクトのバリューの型を抽出するヘルパー型です。
+ *
+ * @template T 対象となるオブジェクト型です。
+ */
+type $ValueOf<T> = T[keyof T];
+
+/**
+ * スロットの配列から、再帰的に値をマージして型を決定します。
+ *
+ * @template TSlots スロットのタプル型です。
+ */
+type $MergeSlotValue<TSlots> = TSlots extends [
+  Slot<string, infer TValue>,
+  infer TSlot,
+  ...infer TOtherSlots,
+]
+  ? TValue & $MergeSlotValue<[TSlot, ...TOtherSlots]>
+  : TSlots extends [Slot<string, infer TValue>]
+    ? TValue
+    : never;
+
+/**
+ * RawValue の配列からスロット情報を抽出し、名前ごとのマップ型に変換します。
+ *
+ * @template TValues RawValue の読み取り専用配列型です。
+ */
+type $MapSlotValue<TValues extends readonly RawValue[]> =
+  TValues extends readonly (infer TSlot extends Slot)[]
+    ? {
+        // `Slot<"id", string | number> | Slot<"id", string>` の場合、`(string | number) & (string)` となるように、各スロットの積集合をとります。
+        [TName in TSlot["name"]]: $MergeSlotValue<UnionToTuple<Extract<TSlot, Slot<TName>>>>;
+      }
+    : {};
+
+/**
+ * 指定された値のリストに対して、スロットを実際の内容で置き換えた型を生成します。
+ *
+ * @template TValues 置き換え対象の配列型です。
+ * @template TSlots スロット名と値のマップ型です。
+ */
+type $FillSlots<TValues, TSlots> = TValues extends [infer TValue, ...infer TOtherValues]
+  ? [
+      TValue extends Slot<infer TName extends Extract<keyof TSlots, string>, infer TSlotValue>
+        ? TSlotValue extends TSlots[TName]
+          ? TSlotValue
+          : TValue
+        : TValue,
+      ...$FillSlots<TOtherValues, TSlots>,
+    ]
+  : [];
+
+/**
+ * スロットを埋めるための部分的な引数型を定義します。
+ *
+ * @template TSlots スロット名と値のマップ型です。
+ */
+type _FillSlots<TSlots> =
+  | {
+      readonly [TName in Extract<keyof TSlots, string>]?: TSlots[TName];
+    }
+  | Iterable<
+      readonly [
+        name: $ValueOf<{
+          [TName in Extract<keyof TSlots, string>]: TName | Slot<TName, TSlots[TName]>;
+        }>,
+        value: $ValueOf<TSlots>,
+      ]
+    >;
+
+/**
+ * すべてのスロットを埋めるために必要な引数型を定義します。
+ *
+ * @template TSlots スロット名と値のマップ型です。
+ */
+type _FillAllSlots<TSlots> = {
+  readonly [TName in Extract<keyof TSlots, string>]: TSlots[TName];
+};
+
+/**
+ * スロットの部分的な補完に使用する外部向けの型定義です。
+ *
+ * @template TValues RawValue の配列です。
+ */
+export type FillSlots<TValues extends readonly RawValue[] = readonly RawValue[]> = _FillSlots<
+  $MapSlotValue<TValues>
+>;
+
+/**
+ * すべてのスロットの強制的な補完に使用する外部向けの型定義です。
+ *
+ * @template TValues RawValue の配列です。
+ */
+export type FillAllSlots<TValues extends readonly RawValue[] = readonly RawValue[]> = _FillAllSlots<
+  $MapSlotValue<TValues>
+>;
 
 /**
  * Sql クラスの内部状態を管理するためのプライベートな型定義です。
@@ -16,24 +179,37 @@ 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 クエリーを構築するためのクラスです。
+ *
  * プレースホルダーを使用したパラメーター化クエリーを生成します。
+ *
+ * @template TRawBindings クエリーに渡される生の値のタプル型です。
  */
-export class Sql {
+export class Sql<const TRawBindings extends readonly RawValue[] = readonly RawValue[]> {
   /**
    * 構築された SQL クエリーテキストを取得します。
    *
@@ -43,19 +219,19 @@ export class Sql {
    */
   public get text(): string {
     // キャッシュが存在しない場合にのみ、文字列を構築します。
-    if (this._.t === undefined) {
+    if (this.#state.text === undefined) {
       let i = 0,
-        text = this._.s[0];
+        text = this.#state.parts[0];
 
       // 文字列の断片とプレースホルダー（$1, $2...）を交互に結合します。
-      for (; i < this._.p.length; i++) {
-        text += "$" + this._.p[i] + this._.s[i + 1];
+      for (; i < this.#state.phIds.length; i++) {
+        text += "$" + this.#state.phIds[i] + this.#state.parts[i + 1];
       }
 
-      this._.t = text;
+      this.#state.text = text;
     }
 
-    return this._.t;
+    return this.#state.text;
   }
 
   /**
@@ -66,7 +242,7 @@ export class Sql {
   /**
    * 内部状態を保持するためのプロパティーです。
    */
-  private readonly _!: PrivateState;
+  readonly #state: PrivateState;
 
   /**
    * 新しい Sql インスタンスを初期化します。
@@ -74,7 +250,7 @@ export class Sql {
    * @param rawStrings SQL の断片となる文字列の配列です。
    * @param rawBindings 文字列の間に挿入される値の配列です。
    */
-  public constructor(rawStrings: readonly string[], rawBindings: readonly RawValue[]) {
+  public constructor(rawStrings: readonly string[], rawBindings: TRawBindings) {
     if (rawStrings.length === 0) {
       throw new TypeError("Expected at least 1 string");
     }
@@ -88,10 +264,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 +318,26 @@ export class Sql {
       // バインディング値が Sql インスタンス（ネストされたクエリー）の場合の処理です。
       if (child instanceof Sql) {
         // 現在の最後の文字列断片に、ネストされた Sql の最初の断片を結合します。
-        strings[strings.length - 1] += child._.s[0];
+        strings[strings.length - 1] += child.#state.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.#state.phIds.length; j++) {
+          const childPlaceholderId = child.#state.phIds[j]!;
+          const valueIndex = childPlaceholderId - 1;
+          const value = child.values[valueIndex]!;
+
+          const slot = child.#state.idx2slot.get(valueIndex);
+
+          const placeholderId = slot !== undefined ? registerSlot(slot) : registerValue(value);
 
-          strings.push(child._.s[j + 1]!);
+          strings.push(child.#state.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);
@@ -135,13 +346,102 @@ export class Sql {
 
     this.values = bindings;
 
-    // 内部状態を隠蔽し、不必要なプロパティーの露出を防ぎます。
-    Object.defineProperty(this, "_", {
-      value: {
-        s: strings,
-        p: placeholderIds,
-      },
-    });
+    this.#state = {
+      parts: strings,
+      phIds: placeholderIds,
+      idx2slot,
+      slot2idx,
+    };
+  }
+
+  /**
+   * スロットを値で埋める内部メソッドです。
+   *
+   * @param slots スロットのマップまたはエントリーの配列です。
+   * @param all 全てのスロットが埋まっているかチェックするかどうかです。
+   * @returns 新しい Sql インスタンスを返します。
+   */
+  #fill(slots: FillSlots<Slot[]>, all: boolean): Sql {
+    if (isPlainObject(slots)) {
+      slots = Object.entries(slots);
+    } else {
+      // 一旦 Map のインスタンスにすることで、重複する名前またはスロットを 1 つに絞ります。
+      slots = new Map(slots);
+    }
+
+    const { parts, idx2slot, slot2idx } = this.#state;
+    const filled = new Set<number>();
+    const values = this.values.slice();
+    for (const [target, value] of new Map(slots)) {
+      let idxes: ReadonlySet<number> | undefined;
+      if (typeof target === "string") {
+        idxes = slot2idx.get(target);
+      } else {
+        // インスタンスが直接指定された場合、全インデックスから一致するものを探します。
+        for (const [idx, slot] of 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;
+        filled.add(idx);
+      }
+    }
+
+    // 全て埋める必要がある場合、未解決のスロットが残っていないか検証します。
+    if (all) {
+      for (let idx = 0; idx < values.length; idx++) {
+        if (idx2slot.has(idx) && !filled.has(idx)) {
+          const missingSlots = new Set<string>();
+          missingSlots.add(idx2slot.get(idx)!.name);
+          for (; idx < values.length; idx++) {
+            if (idx2slot.has(idx)) {
+              missingSlots.add(idx2slot.get(idx)!.name);
+            }
+          }
+
+          throw new Error(`Not all slots are filled. Missing: ${[...missingSlots].join(", ")}`);
+        }
+      }
+    }
+
+    return new Sql(parts, values);
+  }
+
+  /**
+   * スロットを値で埋めます。
+   *
+   * @template TSlots 指定されたスロットのマップ型です。
+   * @param slots スロットの値です。
+   * @returns スロットが埋められた新しい Sql インスタンスです。
+   */
+  public fill<TSlots extends FillSlots<TRawBindings>>(
+    slots: TSlots,
+  ): Sql<$FillSlots<TRawBindings, TSlots>> {
+    return this.#fill(slots, false);
+  }
+
+  /**
+   * すべてのスロットを値で埋めます。
+   *
+   * @template TSlots 全てのスロットをカバーするマップ型です。
+   * @param slots スロットの値です。
+   * @returns スロットが埋められた新しい Sql インスタンスです。
+   */
+  public fillAll<TSlots extends FillAllSlots<TRawBindings>>(
+    slots: TSlots,
+  ): Sql<$FillSlots<TRawBindings, TSlots>> {
+    return this.#fill(slots, true);
   }
 
   /**
@@ -171,6 +471,7 @@ export class Sql {
 
 /**
  * 生の文字列を SQL 断片として扱います。
+ *
  * この値はパラメーター化の対象にならず、そのままクエリーに含まれます。
  *
  * @param value SQL に含める生の文字列です。

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, literal } from "./core.js";
+import { empty, join, raw, Sql, ident, literal, Slot, RawValue } from "./core.js";
 
 namespace sql {
   /**
@@ -11,15 +11,50 @@ namespace sql {
    */
   export type Value = import("./core.js").Value;
 
+  /**
+   * スロットを表すクラスです。
+   *
+   * スロットは後から値を注入可能なプレースホルダーです。
+   *
+   * @template TName スロットの名前となる文字列リテラル型です。
+   * @template TValue スロットに許容される値の型です。
+   */
+  export type Slot<
+    TName extends string = string,
+    TValue extends RawValue = RawValue,
+  > = import("./core.js").Slot<TName, TValue>;
+
   /**
    * 安全な SQL クエリーを構築するためのクラス型です。
+   *
+   * @template TRawBindings クエリーに渡される生の値のタプル型です。
    */
-  export type Sql = import("./core.js").Sql;
+  export type Sql<TRawBindings extends readonly RawValue[] = readonly RawValue[]> =
+    import("./core.js").Sql<TRawBindings>;
+}
+
+/**
+ * 新しい Slot インスタンスを作成します。
+ *
+ * @template TName スロットの名前となる文字列リテラル型です。
+ * @template TValue スロットに許容される値の型です。
+ * @param name スロット名です。
+ * @param defaultValue デフォルト値です。
+ * @returns 作成された新しい Slot インスタンスです。
+ */
+function slot<const TName extends string, TValue extends RawValue = RawValue>(
+  name: TName,
+  defaultValue?: TValue,
+): sql.Slot<TName, TValue>;
+
+function slot(...args: [any]): sql.Slot {
+  return new sql.Slot(...args);
 }
 
 /**
  * テンプレートリテラルを使用して SQL クエリーを安全に構築するためのタグ関数です。
  *
+ * @template TRawBindings クエリーに渡される生の値のタプル型です。
  * @param strings テンプレートリテラルの静的な文字列部分の配列です。
  * @param bindings テンプレートリテラルに埋め込まれた動的な値の配列です。
  * @returns パラメーター化された SQL 情報を保持する Sql インスタンスを返します。
@@ -29,12 +64,15 @@ namespace sql {
  * ```
  */
 const sql = /*#__PURE__*/ Object.assign(
-  function sql(strings: TemplateStringsArray, ...bindings: readonly sql.RawValue[]): sql.Sql {
+  function sql<const TRawBindings extends readonly RawValue[]>(
+    strings: TemplateStringsArray,
+    ...bindings: TRawBindings
+  ): sql.Sql<TRawBindings> {
     return new Sql(strings, bindings);
   },
   {
     /**
-     * Sql クラス自体への参照です。
+     * Sql クラスです。
      */
     Sql,
 
@@ -43,6 +81,18 @@ const sql = /*#__PURE__*/ Object.assign(
      */
     raw,
 
+    /**
+     *　新しい Slot インスタンスを作成する関数です。
+     */
+    slot,
+
+    /**
+     * スロットを表すクラスです。
+     *
+     * スロットは後から値を注入可能なプレースホルダーです。
+     */
+    Slot,
+
     /**
      * 複数の SQL 断片を結合するための関数です。
      */