@h-ai/reldb 0.1.0-alpha5

package/dist/index.d.ts

@@ -0,0 +1,1492 @@
+import { z } from 'zod';
+import * as _h_ai_core from '@h-ai/core';
+import { HaiResult, PaginationOptionsInput, PaginatedResult, PaginationOptions } from '@h-ai/core';
+
+/**
+ * @h-ai/reldb — 数据库配置 Schema
+ *
+ * 本文件定义数据库模块的配置结构，使用 Zod 进行运行时校验。
+ * @module reldb-config
+ */
+
+/**
+ * 数据库类型枚举
+ *
+ * 支持的数据库类型：
+ * - `sqlite` - SQLite 嵌入式数据库（使用 better-sqlite3）
+ * - `postgresql` - PostgreSQL 数据库（使用 pg）
+ * - `mysql` - MySQL 数据库（使用 mysql2）
+ */
+declare const ReldbTypeSchema: z.ZodEnum<{
+    sqlite: "sqlite";
+    postgresql: "postgresql";
+    mysql: "mysql";
+}>;
+/** 数据库类型 */
+type DbType = z.infer<typeof ReldbTypeSchema>;
+/**
+ * 连接池配置 Schema
+ *
+ * 用于 PostgreSQL 和 MySQL 的连接池管理。
+ * SQLite 为嵌入式数据库，不使用连接池。
+ *
+ * @example
+ * ```ts
+ * const poolConfig = {
+ *     min: 2,
+ *     max: 20,
+ *     idleTimeout: 30000,
+ *     acquireTimeout: 10000
+ * }
+ * ```
+ */
+declare const PoolConfigSchema: z.ZodObject<{
+    min: z.ZodDefault<z.ZodNumber>;
+    max: z.ZodDefault<z.ZodNumber>;
+    idleTimeout: z.ZodDefault<z.ZodNumber>;
+    acquireTimeout: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** 连接池配置类型 */
+type PoolConfig = z.infer<typeof PoolConfigSchema>;
+/**
+ * SSL 配置 Schema
+ *
+ * 支持多种配置方式：
+ * - `true/false` - 简单开关
+ * - `'require'/'prefer'/'allow'/'disable'` - SSL 模式
+ * - 自定义对象 - 详细 SSL 配置
+ *
+ * @example
+ * ```ts
+ * // 简单开关
+ * ssl: true
+ *
+ * // SSL 模式
+ * ssl: 'require'
+ *
+ * // 自定义配置
+ * ssl: { rejectUnauthorized: false }
+ * ```
+ */
+declare const SslConfigSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
+    require: "require";
+    prefer: "prefer";
+    allow: "allow";
+    disable: "disable";
+}>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+/** SSL 配置类型 */
+type SslConfig = z.infer<typeof SslConfigSchema>;
+/**
+ * SQLite 特定选项 Schema
+ *
+ * @example
+ * ```ts
+ * sqlite: {
+ *     walMode: true,   // 启用 WAL 模式，提高并发性能
+ *     readonly: false  // 只读模式
+ * }
+ * ```
+ */
+declare const SqliteOptionsSchema: z.ZodObject<{
+    walMode: z.ZodDefault<z.ZodBoolean>;
+    readonly: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * MySQL 特定选项 Schema
+ *
+ * @example
+ * ```ts
+ * mysql: {
+ *     charset: 'utf8mb4',
+ *     timezone: '+08:00'
+ * }
+ * ```
+ */
+declare const MysqlOptionsSchema: z.ZodObject<{
+    charset: z.ZodDefault<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * SQLite 配置 Schema
+ *
+ * @example
+ * ```ts
+ * // 文件数据库
+ * { type: 'sqlite', database: './data.db' }
+ *
+ * // 内存数据库（用于测试）
+ * { type: 'sqlite', database: ':memory:' }
+ * ```
+ */
+declare const SqliteConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"sqlite">;
+    database: z.ZodString;
+    sqlite: z.ZodOptional<z.ZodObject<{
+        walMode: z.ZodDefault<z.ZodBoolean>;
+        readonly: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * PostgreSQL 配置 Schema
+ *
+ * @example
+ * ```ts
+ * // 使用连接字符串
+ * { type: 'postgresql', url: 'postgres://user:pass@localhost:5432/mydb' }
+ *
+ * // 使用分开的字段
+ * {
+ *     type: 'postgresql',
+ *     host: 'localhost',
+ *     port: 5432,
+ *     database: 'mydb',
+ *     user: 'admin',
+ *     password: 'secret',
+ *     pool: { max: 20 }
+ * }
+ * ```
+ */
+declare const PostgresqlConfigSchema: z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodOptional<z.ZodNumber>;
+    database: z.ZodString;
+    user: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+    ssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
+        require: "require";
+        prefer: "prefer";
+        allow: "allow";
+        disable: "disable";
+    }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    pool: z.ZodOptional<z.ZodObject<{
+        min: z.ZodDefault<z.ZodNumber>;
+        max: z.ZodDefault<z.ZodNumber>;
+        idleTimeout: z.ZodDefault<z.ZodNumber>;
+        acquireTimeout: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    type: z.ZodLiteral<"postgresql">;
+}, z.core.$strip>;
+/**
+ * MySQL 配置 Schema
+ *
+ * @example
+ * ```ts
+ * // 使用连接字符串
+ * { type: 'mysql', url: 'mysql://user:pass@localhost:3306/mydb' }
+ *
+ * // 使用分开的字段
+ * {
+ *     type: 'mysql',
+ *     host: 'localhost',
+ *     port: 3306,
+ *     database: 'mydb',
+ *     user: 'admin',
+ *     password: 'secret',
+ *     mysql: { charset: 'utf8mb4' }
+ * }
+ * ```
+ */
+declare const MysqlConfigSchema: z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodOptional<z.ZodNumber>;
+    database: z.ZodString;
+    user: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+    ssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
+        require: "require";
+        prefer: "prefer";
+        allow: "allow";
+        disable: "disable";
+    }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    pool: z.ZodOptional<z.ZodObject<{
+        min: z.ZodDefault<z.ZodNumber>;
+        max: z.ZodDefault<z.ZodNumber>;
+        idleTimeout: z.ZodDefault<z.ZodNumber>;
+        acquireTimeout: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    type: z.ZodLiteral<"mysql">;
+    mysql: z.ZodOptional<z.ZodObject<{
+        charset: z.ZodDefault<z.ZodString>;
+        timezone: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * 统一数据库配置 Schema（判别联合体）
+ *
+ * 根据 `type` 字段区分不同数据库类型的配置。
+ */
+declare const ReldbConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"sqlite">;
+    database: z.ZodString;
+    sqlite: z.ZodOptional<z.ZodObject<{
+        walMode: z.ZodDefault<z.ZodBoolean>;
+        readonly: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodOptional<z.ZodNumber>;
+    database: z.ZodString;
+    user: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+    ssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
+        require: "require";
+        prefer: "prefer";
+        allow: "allow";
+        disable: "disable";
+    }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    pool: z.ZodOptional<z.ZodObject<{
+        min: z.ZodDefault<z.ZodNumber>;
+        max: z.ZodDefault<z.ZodNumber>;
+        idleTimeout: z.ZodDefault<z.ZodNumber>;
+        acquireTimeout: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    type: z.ZodLiteral<"postgresql">;
+}, z.core.$strip>, z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodOptional<z.ZodNumber>;
+    database: z.ZodString;
+    user: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+    ssl: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
+        require: "require";
+        prefer: "prefer";
+        allow: "allow";
+        disable: "disable";
+    }>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    pool: z.ZodOptional<z.ZodObject<{
+        min: z.ZodDefault<z.ZodNumber>;
+        max: z.ZodDefault<z.ZodNumber>;
+        idleTimeout: z.ZodDefault<z.ZodNumber>;
+        acquireTimeout: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    type: z.ZodLiteral<"mysql">;
+    mysql: z.ZodOptional<z.ZodObject<{
+        charset: z.ZodDefault<z.ZodString>;
+        timezone: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "type">;
+/** 数据库配置类型（判别联合体） */
+type ReldbConfig = z.infer<typeof ReldbConfigSchema>;
+/** SQLite 配置类型 */
+type SqliteConfig = z.infer<typeof SqliteConfigSchema>;
+/** PostgreSQL 配置类型 */
+type PostgresqlConfig = z.infer<typeof PostgresqlConfigSchema>;
+/** MySQL 配置类型 */
+type MysqlConfig = z.infer<typeof MysqlConfigSchema>;
+/**
+ * 数据库配置输入类型（用于 init 等入口）
+ *
+ * 说明：Zod 的 default 会让输入端字段可省略，但输出端字段为必填。
+ * 因此对外 API（如 reldb.init）更适合接收 ReldbConfigInput。
+ */
+type ReldbConfigInput = z.input<typeof ReldbConfigSchema>;
+
+/**
+ * @h-ai/reldb — JSON 操作 SQL 构建器
+ *
+ * 为不同数据库后端提供统一的 JSON 路径操作 SQL 表达式构建能力。
+ * 路径格式遵循 SQL/JSON Path 标准（`$.key` / `$.key.subkey` / `$[0]`）。
+ *
+ * 各数据库后端映射：
+ *
+ * | 操作     | SQLite                | PostgreSQL                    | MySQL                       |
+ * |---------|----------------------|-------------------------------|-----------------------------|
+ * | extract | json_extract          | #> (text[])                   | JSON_EXTRACT                |
+ * | set     | json_set + json()     | jsonb_set + ::jsonb            | JSON_SET + CAST AS JSON      |
+ * | insert  | json_insert + json()  | jsonb_insert + ::jsonb         | JSON_INSERT + CAST AS JSON   |
+ * | remove  | json_remove           | #- (text[])                   | JSON_REMOVE                 |
+ * | merge   | json_patch            | \|\| ::jsonb                  | JSON_MERGE_PATCH + CAST      |
+ *
+ * @module reldb-json
+ */
+/**
+ * JSON SQL 表达式结果
+ *
+ * 包含可嵌入 SQL 语句的表达式片段与对应参数列表。
+ * 参数占位符统一使用 `?`，各 Provider 会在执行前自动转换。
+ *
+ * @example
+ * ```ts
+ * const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
+ * // 将 sql 和 params 嵌入到完整 SQL 中执行
+ * await reldb.sql.execute(
+ *   `UPDATE users SET settings = ${sql} WHERE id = ?`,
+ *   [...params, userId],
+ * )
+ * ```
+ */
+interface JsonSqlExpr {
+    /** SQL 表达式片段（含 ? 占位符） */
+    sql: string;
+    /** 参数列表（对应 ? 占位符，顺序与 sql 中出现顺序一致） */
+    params: unknown[];
+}
+/**
+ * JSON 操作接口
+ *
+ * 提供跨数据库统一的 JSON 路径操作 SQL 构建能力。
+ * 所有方法返回 `JsonSqlExpr`，可嵌入 `reldb.sql.query` / `reldb.sql.execute` 等调用。
+ *
+ * 路径格式：遵循 SQL/JSON Path 标准，以 `$` 开头：
+ * - 对象字段：`$.key`、`$.key.subkey`
+ * - 数组元素：`$[0]`、`$.items[1]`
+ *
+ * @example
+ * ```ts
+ * // 提取 JSON 字段值（用于 SELECT 或 WHERE）
+ * const { sql, params } = reldb.json.extract('settings', '$.theme')
+ * const rows = await reldb.sql.query(
+ *   `SELECT * FROM users WHERE ${sql} = ?`,
+ *   [...params, '"dark"'],
+ * )
+ *
+ * // 设置 JSON 字段的某个路径（用于 UPDATE SET）
+ * const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
+ * await reldb.sql.execute(
+ *   `UPDATE users SET settings = ${sql} WHERE id = ?`,
+ *   [...params, userId],
+ * )
+ * ```
+ */
+interface ReldbJsonOps {
+    /**
+     * JSON 路径提取表达式
+     *
+     * 提取 JSON 列中指定路径的值，返回 JSON 类型的值。
+     * 可用于 SELECT 列表、WHERE 条件或 ORDER BY。
+     *
+     * @param column - 列名（或 SQL 列表达式，开发者负责安全性，禁止传入用户输入）
+     * @param path - JSON 路径（如 `$.status`、`$.user.name`、`$[0]`）
+     * @returns SQL 表达式与参数
+     *
+     * @example
+     * ```ts
+     * const { sql, params } = reldb.json.extract('data', '$.status')
+     * // SQLite:     sql = "json_extract(data, ?)",    params = ["$.status"]
+     * // PostgreSQL: sql = "data #> ?::text[]",         params = [["status"]]
+     * // MySQL:      sql = "JSON_EXTRACT(data, ?)",     params = ["$.status"]
+     * ```
+     */
+    extract: (column: string, path: string) => JsonSqlExpr;
+    /**
+     * JSON 路径设置表达式（创建或替换）
+     *
+     * 在 JSON 列的指定路径设置新值。若路径不存在则创建，若已存在则替换。
+     * 返回修改后的完整 JSON 值，通常用于 `UPDATE SET col = ...`。
+     *
+     * @param column - 列名（开发者负责安全性，禁止传入用户输入）
+     * @param path - JSON 路径
+     * @param value - 要设置的值（支持任意 JSON 兼容类型）
+     * @returns SQL 表达式与参数
+     *
+     * @example
+     * ```ts
+     * const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
+     * await reldb.sql.execute(
+     *   `UPDATE users SET settings = ${sql} WHERE id = ?`,
+     *   [...params, id],
+     * )
+     * ```
+     */
+    set: (column: string, path: string, value: unknown) => JsonSqlExpr;
+    /**
+     * JSON 路径插入表达式（仅当路径不存在时）
+     *
+     * 仅在指定路径不存在时插入新值，已存在的路径不会被覆盖。
+     * 返回修改后的完整 JSON 值。
+     *
+     * @param column - 列名（开发者负责安全性，禁止传入用户输入）
+     * @param path - JSON 路径
+     * @param value - 要插入的值
+     * @returns SQL 表达式与参数
+     *
+     * @example
+     * ```ts
+     * const { sql, params } = reldb.json.insert('data', '$.newField', 'value')
+     * await reldb.sql.execute(
+     *   `UPDATE items SET data = ${sql} WHERE id = ?`,
+     *   [...params, id],
+     * )
+     * ```
+     */
+    insert: (column: string, path: string, value: unknown) => JsonSqlExpr;
+    /**
+     * JSON 路径删除表达式
+     *
+     * 从 JSON 列中移除指定路径对应的键或数组元素。
+     * 返回删除后的完整 JSON 值。
+     *
+     * @param column - 列名（开发者负责安全性，禁止传入用户输入）
+     * @param path - JSON 路径
+     * @returns SQL 表达式与参数
+     *
+     * @example
+     * ```ts
+     * const { sql, params } = reldb.json.remove('settings', '$.deprecated')
+     * await reldb.sql.execute(
+     *   `UPDATE users SET settings = ${sql} WHERE id = ?`,
+     *   [...params, id],
+     * )
+     * ```
+     */
+    remove: (column: string, path: string) => JsonSqlExpr;
+    /**
+     * JSON 合并/补丁表达式（RFC 7396 Merge Patch）
+     *
+     * 将 patch 对象合并到 JSON 列：
+     * - patch 中存在的键：覆盖原值
+     * - patch 中值为 null 的键：删除原键
+     * - patch 中不存在的键：保持不变
+     *
+     * 返回合并后的完整 JSON 值，通常用于 `UPDATE SET col = ...`。
+     *
+     * @param column - 列名（开发者负责安全性，禁止传入用户输入）
+     * @param patch - 要合并的 JSON 对象
+     * @returns SQL 表达式与参数
+     *
+     * @example
+     * ```ts
+     * const { sql, params } = reldb.json.merge('profile', { bio: 'new bio', avatar: null })
+     * await reldb.sql.execute(
+     *   `UPDATE users SET profile = ${sql} WHERE id = ?`,
+     *   [...params, id],
+     * )
+     * ```
+     */
+    merge: (column: string, patch: Record<string, unknown>) => JsonSqlExpr;
+}
+/**
+ * 解析 JSON Path 为路径段数组
+ *
+ * 将 `$.key.subkey[0]` 格式的路径解析为 `['key', 'subkey', '0']`。
+ *
+ * @param path - JSON 路径（以 `$` 开头）
+ * @returns 路径段数组
+ *
+ * @example
+ * ```ts
+ * parseJsonPath('$.user.name')  // ['user', 'name']
+ * parseJsonPath('$.items[0]')   // ['items', '0']
+ * parseJsonPath('$[1]')         // ['1']
+ * ```
+ */
+declare function parseJsonPath(path: string): string[];
+/**
+ * 创建指定数据库类型的 JSON 操作实例
+ *
+ * @param dbType - 数据库类型（来自 `reldb.config?.type`）
+ * @returns JSON 操作实例
+ *
+ * @example
+ * ```ts
+ * // 通过 reldb.json 直接使用（推荐）
+ * const { sql, params } = reldb.json.extract('data', '$.key')
+ *
+ * // 手动创建（用于测试或特殊场景）
+ * const jsonOps = createJsonOps('sqlite')
+ * const { sql, params } = jsonOps.set('data', '$.key', 'value')
+ * ```
+ */
+declare function createJsonOps(dbType: 'sqlite' | 'postgresql' | 'mysql'): ReldbJsonOps;
+
+declare const HaiReldbError: {
+    CONNECTION_FAILED: _h_ai_core.HaiErrorDef;
+    QUERY_FAILED: _h_ai_core.HaiErrorDef;
+    CONSTRAINT_VIOLATION: _h_ai_core.HaiErrorDef;
+    TRANSACTION_FAILED: _h_ai_core.HaiErrorDef;
+    MIGRATION_FAILED: _h_ai_core.HaiErrorDef;
+    RECORD_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    DUPLICATE_ENTRY: _h_ai_core.HaiErrorDef;
+    DEADLOCK: _h_ai_core.HaiErrorDef;
+    TIMEOUT: _h_ai_core.HaiErrorDef;
+    POOL_EXHAUSTED: _h_ai_core.HaiErrorDef;
+    NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
+    DDL_FAILED: _h_ai_core.HaiErrorDef;
+    UNSUPPORTED_TYPE: _h_ai_core.HaiErrorDef;
+    CONFIG_ERROR: _h_ai_core.HaiErrorDef;
+};
+/**
+ * 列数据类型
+ *
+ * 统一的列类型定义，会根据不同数据库自动映射：
+ *
+ * | 类型        | SQLite  | PostgreSQL       | MySQL        |
+ * |------------|---------|------------------|--------------|
+ * | TEXT       | TEXT    | TEXT             | VARCHAR(255) |
+ * | INTEGER    | INTEGER | INTEGER/SERIAL   | INT/BIGINT   |
+ * | REAL       | REAL    | DOUBLE PRECISION | DOUBLE       |
+ * | BLOB       | BLOB    | BYTEA            | BLOB         |
+ * | BOOLEAN    | INTEGER | BOOLEAN          | TINYINT(1)   |
+ * | TIMESTAMP  | INTEGER | TIMESTAMP        | DATETIME     |
+ * | JSON       | TEXT    | JSONB            | JSON         |
+ *
+ * 注：MySQL 将 TEXT 映射为 VARCHAR(255) 以支持索引和 UNIQUE 约束。
+ * INTEGER 在 MySQL autoIncrement 时映射为 BIGINT，否则映射为 INT。
+ */
+type ColumnType = 'TEXT' | 'INTEGER' | 'REAL' | 'BLOB' | 'BOOLEAN' | 'TIMESTAMP' | 'JSON';
+/**
+ * 列定义接口
+ *
+ * 用于定义表的列结构。
+ *
+ * @example
+ * ```ts
+ * // 主键列
+ * const idColumn: ReldbColumnDef = {
+ *     type: 'INTEGER',
+ *     primaryKey: true,
+ *     autoIncrement: true
+ * }
+ *
+ * // 带外键的列
+ * const userIdColumn: ReldbColumnDef = {
+ *     type: 'INTEGER',
+ *     notNull: true,
+ *     references: {
+ *         table: 'users',
+ *         column: 'id',
+ *         onDelete: 'CASCADE'
+ *     }
+ * }
+ * ```
+ */
+interface ReldbColumnDef {
+    /** 列数据类型 */
+    type: ColumnType;
+    /** 是否为主键 */
+    primaryKey?: boolean;
+    /** 是否自增（仅主键有效） */
+    autoIncrement?: boolean;
+    /** 是否非空 */
+    notNull?: boolean;
+    /** 默认值（支持字符串、数字、布尔、null） */
+    defaultValue?: string | number | boolean | null;
+    /** 是否唯一 */
+    unique?: boolean;
+    /** 外键引用 */
+    references?: {
+        /** 引用的表名 */
+        table: string;
+        /** 引用的列名 */
+        column: string;
+        /** 删除时的行为 */
+        onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+        /** 更新时的行为 */
+        onUpdate?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    };
+}
+/**
+ * 表定义（列名到列定义的映射）
+ *
+ * @example
+ * ```ts
+ * const userTable: ReldbTableDef = {
+ *     id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
+ *     name: { type: 'TEXT', notNull: true },
+ *     email: { type: 'TEXT', unique: true },
+ *     created_at: { type: 'TIMESTAMP', defaultValue: 'NOW()' }
+ * }
+ * ```
+ */
+interface ReldbTableDef {
+    [columnName: string]: ReldbColumnDef;
+}
+/**
+ * 索引定义
+ *
+ * @example
+ * ```ts
+ * // 普通索引
+ * const emailIndex: ReldbIndexDef = { columns: ['email'] }
+ *
+ * // 唯一复合索引
+ * const compositeIndex: ReldbIndexDef = {
+ *     columns: ['user_id', 'created_at'],
+ *     unique: true
+ * }
+ *
+ * // 部分索引（带条件）
+ * const partialIndex: ReldbIndexDef = {
+ *     columns: ['status'],
+ *     where: "status = 'active'"
+ * }
+ * ```
+ */
+interface ReldbIndexDef {
+    /** 索引包含的列 */
+    columns: string[];
+    /** 是否为唯一索引 */
+    unique?: boolean;
+    /**
+     * 索引条件（WHERE 子句，用于部分索引）
+     *
+     * **⚠️ 安全警告：** `where` 为原始 SQL 片段，不会经过参数化处理，
+     * **禁止**将用户输入直接拼接。仅用于开发者编写的静态条件。
+     */
+    where?: string;
+}
+/**
+ * DDL（数据定义语言）操作接口
+ *
+ * 提供表结构管理功能，包括创建/删除表、添加/删除列、创建索引等。
+ * 所有操作返回 `HaiResult<void>` 类型。
+ *
+ * @example
+ * ```ts
+ * // 创建表
+ * const result = await reldb.ddl.createTable('users', {
+ *     id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
+ *     name: { type: 'TEXT', notNull: true }
+ * })
+ *
+ * if (!result.success) {
+ *     // 处理错误：创建表失败（可根据 result.error.code / message 做兜底）
+ * }
+ * ```
+ */
+interface DdlOperations {
+    /**
+     * 创建表
+     * @param tableName - 表名
+     * @param columns - 列定义
+     * @param ifNotExists - 是否使用 IF NOT EXISTS（默认 true）
+     * @example
+     * ```ts
+     * const result = await reldb.ddl.createTable('users', {
+     *     id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
+     *     name: { type: 'TEXT', notNull: true }
+     * })
+     * if (!result.success) {
+     *     // 创建失败：根据 result.error.code / message 处理
+     * }
+     * ```
+     */
+    createTable: (tableName: string, columns: ReldbTableDef, ifNotExists?: boolean) => Promise<HaiResult<void>>;
+    /**
+     * 删除表
+     * @param tableName - 表名
+     * @param ifExists - 是否使用 IF EXISTS（默认 true）
+     * @example
+     * ```ts
+     * await reldb.ddl.dropTable('users')
+     * await reldb.ddl.dropTable('users_backup', false)
+     * ```
+     */
+    dropTable: (tableName: string, ifExists?: boolean) => Promise<HaiResult<void>>;
+    /**
+     * 添加列
+     * @param tableName - 表名
+     * @param columnName - 列名
+     * @param columnDef - 列定义
+     * @example
+     * ```ts
+     * await reldb.ddl.addColumn('users', 'age', { type: 'INTEGER' })
+     * await reldb.ddl.addColumn('users', 'email', { type: 'TEXT', unique: true })
+     * ```
+     */
+    addColumn: (tableName: string, columnName: string, columnDef: ReldbColumnDef) => Promise<HaiResult<void>>;
+    /**
+     * 删除列
+     * @param tableName - 表名
+     * @param columnName - 列名
+     * @example
+     * ```ts
+     * await reldb.ddl.dropColumn('users', 'legacy_field')
+     * ```
+     */
+    dropColumn: (tableName: string, columnName: string) => Promise<HaiResult<void>>;
+    /**
+     * 重命名表
+     * @param oldName - 原表名
+     * @param newName - 新表名
+     * @example
+     * ```ts
+     * await reldb.ddl.renameTable('users_temp', 'users')
+     * ```
+     */
+    renameTable: (oldName: string, newName: string) => Promise<HaiResult<void>>;
+    /**
+     * 创建索引
+     * @param tableName - 表名
+     * @param indexName - 索引名
+     * @param indexDef - 索引定义
+     * @example
+     * ```ts
+     * await reldb.ddl.createIndex('users', 'idx_users_email', {
+     *     columns: ['email'],
+     *     unique: true,
+     * })
+     * ```
+     */
+    createIndex: (tableName: string, indexName: string, indexDef: ReldbIndexDef) => Promise<HaiResult<void>>;
+    /**
+     * 删除索引
+     * @param indexName - 索引名
+     * @param ifExists - 是否使用 IF EXISTS（默认 true）
+     * @example
+     * ```ts
+     * await reldb.ddl.dropIndex('idx_users_email')
+     * ```
+     */
+    dropIndex: (indexName: string, ifExists?: boolean) => Promise<HaiResult<void>>;
+    /**
+     * 执行原始 DDL SQL
+     *
+     * **⚠️ 安全警告：** `sql` 参数不会经过标识符校验或参数化处理，
+     * **禁止**将用户输入直接拼接到 SQL 中，否则会导致 SQL 注入风险。
+     * 仅用于开发者编写的静态 DDL 语句（如 ALTER TABLE）。
+     *
+     * @param sql - DDL SQL 语句（必须为开发者静态构造，禁止包含用户输入）
+     * @example
+     * ```ts
+     * // ✅ 安全：静态 SQL
+     * await reldb.ddl.raw('ALTER TABLE users ADD COLUMN status TEXT')
+     *
+     * // ❌ 危险：拼接用户输入
+     * await reldb.ddl.raw(`ALTER TABLE ${userInput} ADD COLUMN status TEXT`)
+     * ```
+     */
+    raw: (sql: string) => Promise<HaiResult<void>>;
+}
+/**
+ * 查询结果行类型
+ *
+ * 约定为键值对象，字段名与 SQL 返回列一致。
+ */
+type QueryRow = Record<string, unknown>;
+/**
+ * 执行结果
+ *
+ * INSERT/UPDATE/DELETE 操作返回的结果。
+ */
+interface ExecuteResult {
+    /** 影响的行数 */
+    changes: number;
+    /** 最后插入的行 ID（仅 INSERT 时有效） */
+    lastInsertRowid?: number | bigint;
+}
+/**
+ * 规范化后的分页参数
+ */
+interface NormalizedPagination extends PaginationOptions {
+    /** SQL offset */
+    offset: number;
+    /** SQL limit */
+    limit: number;
+}
+/**
+ * 分页参数覆盖
+ */
+interface PaginationOverrides {
+    /** 默认页码 */
+    defaultPage?: number;
+    /** 默认每页数量 */
+    defaultPageSize?: number;
+    /** 最大每页数量 */
+    maxPageSize?: number;
+}
+/**
+ * 分页查询参数
+ */
+interface PaginationQueryOptions {
+    /** 数据查询 SQL（不含 LIMIT/OFFSET） */
+    sql: string;
+    /** 参数列表 */
+    params?: unknown[];
+    /** 分页参数 */
+    pagination?: PaginationOptionsInput;
+    /** 覆盖默认分页参数 */
+    overrides?: PaginationOverrides;
+}
+/**
+ * 数据读写操作接口（SQL / 事务共享）
+ */
+interface DmlOperations {
+    /** 查询多行 */
+    query: <T = QueryRow>(sql: string, params?: unknown[]) => Promise<HaiResult<T[]>>;
+    /** 查询单行 */
+    get: <T = QueryRow>(sql: string, params?: unknown[]) => Promise<HaiResult<T | null>>;
+    /** 执行修改语句（INSERT/UPDATE/DELETE） */
+    execute: (sql: string, params?: unknown[]) => Promise<HaiResult<ExecuteResult>>;
+    /** 批量执行多条语句（在同一事务上下文中） */
+    batch: (statements: Array<{
+        sql: string;
+        params?: unknown[];
+    }>) => Promise<HaiResult<void>>;
+    /** 分页查询 */
+    queryPage: <T = QueryRow>(options: PaginationQueryOptions) => Promise<HaiResult<PaginatedResult<T>>>;
+}
+/** CRUD 查询条件 */
+interface CrudQueryOptions {
+    /**
+     * WHERE 子句（不包含 WHERE 关键字）
+     *
+     * **⚠️ 安全警告：** `where` 为原始 SQL 片段，**禁止**将用户输入直接拼接。
+     * 动态值必须通过 `params` 占位符（`?`）传入。
+     *
+     * @example
+     * ```ts
+     * // ✅ 安全：占位符 + params
+     * crud.findAll({ where: 'status = ? AND age > ?', params: ['active', 18] })
+     *
+     * // ❌ 危险：拼接用户输入
+     * crud.findAll({ where: `name = '${userInput}'` })
+     * ```
+     */
+    where?: string;
+    /** 参数列表 */
+    params?: unknown[];
+    /** ORDER BY 子句（不包含 ORDER BY 关键字） */
+    orderBy?: string;
+    /** LIMIT */
+    limit?: number;
+    /** OFFSET */
+    offset?: number;
+}
+/** CRUD 分页查询条件 */
+interface CrudPageOptions {
+    /**
+     * WHERE 子句（不包含 WHERE 关键字）
+     *
+     * **⚠️ 安全警告：** `where` 为原始 SQL 片段，**禁止**将用户输入直接拼接。
+     * 动态值必须通过 `params` 占位符（`?`）传入。
+     */
+    where?: string;
+    /** 参数列表 */
+    params?: unknown[];
+    /** ORDER BY 子句（不包含 ORDER BY 关键字） */
+    orderBy?: string;
+    /** 分页参数 */
+    pagination?: PaginationOptionsInput;
+    /** 分页参数覆盖 */
+    overrides?: PaginationOverrides;
+}
+/** CRUD 统计条件 */
+interface ReldbCrudCountOptions {
+    /**
+     * WHERE 子句（不包含 WHERE 关键字）
+     *
+     * **⚠️ 安全警告：** `where` 为原始 SQL 片段，**禁止**将用户输入直接拼接。
+     * 动态值必须通过 `params` 占位符（`?`）传入。
+     */
+    where?: string;
+    /** 参数列表 */
+    params?: unknown[];
+}
+/** CRUD 配置 */
+interface CrudConfig<TItem> {
+    /** 表名 */
+    table: string;
+    /** 主键列名（默认 id） */
+    idColumn?: string;
+    /** 查询列（默认 *） */
+    select?: string[];
+    /** 允许插入的列（不填则使用数据本身列） */
+    createColumns?: string[];
+    /** 允许更新的列（不填则使用数据本身列） */
+    updateColumns?: string[];
+    /** 行映射函数（可选） */
+    mapRow?: (row: QueryRow) => TItem;
+    /** 数据库类型 */
+    dbType: DbType;
+}
+/** CRUD 字段定义 */
+interface ReldbCrudFieldDefinition {
+    /** 对象字段名 */
+    fieldName: string;
+    /** 数据库列名 */
+    columnName: string;
+    /** 列定义 */
+    def: ReldbColumnDef;
+    /** 是否用于查询 */
+    select: boolean;
+    /** 是否允许插入 */
+    create: boolean;
+    /** 是否允许更新 */
+    update: boolean;
+}
+/** BaseReldbCrudRepository 配置 */
+interface BaseReldbCrudRepositoryConfig<TItem> {
+    /** 表名 */
+    table: string;
+    /** 字段定义 */
+    fields: ReldbCrudFieldDefinition[];
+    /** 主键列名（默认 id） */
+    idColumn?: string;
+    /** 主键字段名（默认与 idColumn 相同） */
+    idField?: keyof TItem & string;
+    /** 是否自动创建表（默认 true） */
+    createTableIfNotExists?: boolean;
+    /** 主键生成策略（未提供则尝试使用 crypto.randomUUID） */
+    generateId?: () => string | number;
+    /** 当前时间提供者（默认 Date.now） */
+    nowProvider?: () => number;
+}
+/** CRUD 仓库接口 */
+interface ReldbCrudRepository<TItem> {
+    create: (data: Record<string, unknown>, tx?: DmlWithTxOperations) => Promise<HaiResult<ExecuteResult>>;
+    createMany: (items: Array<Record<string, unknown>>, tx?: DmlWithTxOperations) => Promise<HaiResult<void>>;
+    createOrUpdate: (data: Record<string, unknown>, tx?: DmlWithTxOperations) => Promise<HaiResult<ExecuteResult>>;
+    findById: (id: unknown, tx?: DmlWithTxOperations) => Promise<HaiResult<TItem | null>>;
+    getById: (id: unknown, tx?: DmlWithTxOperations) => Promise<HaiResult<TItem>>;
+    findAll: (options?: CrudQueryOptions, tx?: DmlWithTxOperations) => Promise<HaiResult<TItem[]>>;
+    findPage: (options: CrudPageOptions, tx?: DmlWithTxOperations) => Promise<HaiResult<PaginatedResult<TItem>>>;
+    updateById: (id: unknown, data: Record<string, unknown>, tx?: DmlWithTxOperations) => Promise<HaiResult<ExecuteResult>>;
+    deleteById: (id: unknown, tx?: DmlWithTxOperations) => Promise<HaiResult<ExecuteResult>>;
+    count: (options?: ReldbCrudCountOptions, tx?: DmlWithTxOperations) => Promise<HaiResult<number>>;
+    exists: (options?: ReldbCrudCountOptions, tx?: DmlWithTxOperations) => Promise<HaiResult<boolean>>;
+    existsById: (id: unknown, tx?: DmlWithTxOperations) => Promise<HaiResult<boolean>>;
+}
+/** CRUD 管理器（统一入口） */
+interface CrudManager {
+    /** 获取单表 CRUD 仓库 */
+    table: <TItem>(config: CrudConfig<TItem>) => ReldbCrudRepository<TItem>;
+}
+/**
+ * 事务句柄接口（分步事务）
+ */
+interface DmlWithTxOperations extends DmlOperations {
+    /** CRUD 管理器 */
+    crud: CrudManager;
+    /** 提交事务 */
+    commit: () => Promise<HaiResult<void>>;
+    /** 回滚事务 */
+    rollback: () => Promise<HaiResult<void>>;
+}
+/**
+ * 事务回调函数类型
+ *
+ * @param tx - 事务内操作对象
+ * @returns 业务返回值（将被包装为 HaiResult）
+ * @example
+ * ```ts
+ * const result = await reldb.tx.wrap(async (tx) => {
+ *     await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户A'])
+ *     return await tx.get('SELECT * FROM users WHERE name = ?', ['用户A'])
+ * })
+ * ```
+ */
+type TxWrapCallback<T> = (tx: DmlWithTxOperations) => Promise<T>;
+/**
+ * 事务管理器
+ */
+interface TxManager {
+    /** 开启事务（分步事务） */
+    begin: () => Promise<HaiResult<DmlWithTxOperations>>;
+    /** 包裹事务（自动提交/回滚） */
+    wrap: <T>(fn: TxWrapCallback<T>) => Promise<HaiResult<T>>;
+}
+/**
+ * 数据库函数接口
+ *
+ * 统一的数据库访问入口，通过 `reldb` 对象提供所有数据库操作。
+ *
+ * @example
+ * ```ts
+ * import { reldb } from '@h-ai/reldb'
+ *
+ * // 初始化
+ * await reldb.init({ type: 'sqlite', database: ':memory:' })
+ *
+ * // 检查状态
+ * if (reldb.isInitialized) {
+ *     // 可读取当前数据库类型：reldb.config?.type
+ * }
+ *
+ * // 使用 DDL
+ * await reldb.ddl.createTable('users', { ... })
+ *
+ * // 使用 SQL
+ * await reldb.sql.query('SELECT * FROM users')
+ *
+ * // 使用事务
+ * await reldb.tx.wrap(async (tx) => { ... })
+ *
+ * // 关闭连接
+ * await reldb.close()
+ * ```
+ */
+interface ReldbFunctions {
+    /**
+     * 初始化数据库连接
+     *
+     * @param config - 数据库配置
+     * @returns 初始化结果
+     */
+    init: (config: ReldbConfigInput) => Promise<HaiResult<void>>;
+    /** DDL 操作（表结构管理） */
+    readonly ddl: DdlOperations;
+    /** SQL 操作（数据查询和修改） */
+    readonly sql: DmlOperations;
+    /** CRUD 管理器 */
+    readonly crud: CrudManager;
+    /** 事务管理器 */
+    readonly tx: TxManager;
+    /** 当前数据库配置（未初始化时为 null） */
+    readonly config: ReldbConfig | null;
+    /** 是否已初始化 */
+    readonly isInitialized: boolean;
+    /** 分页工具 */
+    readonly pagination: {
+        /** 规范化分页参数 */
+        normalize: (options?: PaginationOptionsInput, overrides?: PaginationOverrides) => NormalizedPagination;
+        /** 构建分页结果 */
+        build: <T>(items: T[], total: number, pagination: PaginationOptions) => PaginatedResult<T>;
+    };
+    /**
+     * JSON 操作 SQL 构建器
+     *
+     * 提供跨数据库统一的 JSON 路径操作（提取、设置、插入、删除、合并）。
+     * 返回的 SQL 片段可嵌入 `reldb.sql.query` / `reldb.sql.execute` 等调用。
+     *
+     * 未初始化时默认返回 SQLite 格式的构建器；初始化后自动匹配当前数据库类型。
+     *
+     * @example
+     * ```ts
+     * // 提取 JSON 字段值（用于 WHERE 条件）
+     * const { sql, params } = reldb.json.extract('settings', '$.theme')
+     * const rows = await reldb.sql.query(
+     *   `SELECT * FROM users WHERE ${sql} = ?`,
+     *   [...params, '"dark"'],
+     * )
+     *
+     * // 设置 JSON 字段路径
+     * const { sql, params } = reldb.json.set('settings', '$.theme', 'dark')
+     * await reldb.sql.execute(
+     *   `UPDATE users SET settings = ${sql} WHERE id = ?`,
+     *   [...params, userId],
+     * )
+     * ```
+     */
+    readonly json: ReldbJsonOps;
+    /** 关闭数据库连接 */
+    close: () => Promise<HaiResult<void>>;
+}
+/**
+ * 数据库 Provider 接口
+ *
+ * 内部使用，定义各数据库驱动需要实现的接口。
+ * 每个数据库类型（SQLite、PostgreSQL、MySQL）都有对应的 Provider 实现。
+ */
+interface ReldbProvider {
+    /** DDL 操作（表结构管理） */
+    readonly ddl: DdlOperations;
+    /** SQL 操作（数据查询和修改） */
+    readonly sql: DmlOperations;
+    /** CRUD 管理器 */
+    readonly crud: CrudManager;
+    /** 事务管理器 */
+    readonly tx: TxManager;
+    /** 连接数据库 */
+    connect: (config: ReldbConfig) => Promise<HaiResult<void>>;
+    /** 关闭连接 */
+    close: () => Promise<HaiResult<void>>;
+    /** 是否已连接 */
+    isConnected: () => boolean;
+}
+
+/**
+ * @h-ai/reldb — CRUD 仓库基类
+ *
+ * 提供 `BaseReldbCrudRepository` 抽象基类，供业务仓库继承复用。
+ * @module reldb-crud-repository
+ */
+
+/**
+ * CRUD 仓库基类
+ *
+ * 提供通用的单表 CRUD 操作封装，业务仓库可继承该类实现自定义逻辑。
+ *
+ * 核心能力：
+ * - 自动建表（默认开启，可通过 `createTableIfNotExists: false` 关闭）
+ * - 字段级别的权限控制（select / create / update 分别配置）
+ * - 自动填充主键、createdAt、updatedAt
+ * - 跨数据库类型值转换（BOOLEAN / TIMESTAMP / JSON）
+ * - 支持事务上下文（所有方法均接受可选 tx 参数）
+ *
+ * @example
+ * ```ts
+ * class UserRepository extends BaseReldbCrudRepository<User> {
+ *   constructor(db: ReldbFunctions) {
+ *     super(db, {
+ *       table: 'users',
+ *       fields: [
+ *         { fieldName: 'id', columnName: 'id', def: { type: 'INTEGER', primaryKey: true, autoIncrement: true }, select: true, create: false, update: false },
+ *         { fieldName: 'name', columnName: 'name', def: { type: 'TEXT', notNull: true }, select: true, create: true, update: true },
+ *         { fieldName: 'createdAt', columnName: 'created_at', def: { type: 'TIMESTAMP' }, select: true, create: true, update: false },
+ *       ],
+ *     })
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudRepository<TItem> {
+    /** 底层 CRUD 仓库实例（基于 reldb-crud-kernel 创建） */
+    protected readonly crud: ReldbCrudRepository<TItem>;
+    /** 数据库服务对象 */
+    protected readonly db: ReldbFunctions;
+    /** 字段定义列表 */
+    private readonly fields;
+    /** 主键字段名（对象侧） */
+    private readonly idField?;
+    /** 主键列名（数据库侧） */
+    private readonly idColumn;
+    /** 主键生成器 */
+    private readonly generateId?;
+    /** 当前时间提供者（默认 Date.now） */
+    private readonly nowProvider;
+    /** 初始化 Promise（自动建表等） */
+    private readonly initPromise;
+    /** 可查询列 */
+    private readonly selectColumns;
+    /** 可插入列 */
+    private readonly createColumns;
+    /** 可更新列 */
+    private readonly updateColumns;
+    /** 表名 */
+    private readonly table;
+    /** 当前数据库类型（延迟读取，确保获取初始化后的值） */
+    private get dbType();
+    /**
+     * 创建 BaseReldbCrudRepository
+     *
+     * 初始化字段映射、构建表结构（默认自动建表）并配置底层 CRUD 仓库。
+     *
+     * @param db - 数据库服务对象
+     * @param config - BaseReldbCrudRepository 配置（表名、字段定义、主键策略等）
+     */
+    protected constructor(db: ReldbFunctions, config: BaseReldbCrudRepositoryConfig<TItem>);
+    /**
+     * 获取 SQL 操作对象（自动选择 reldb.sql 或 tx）
+     *
+     * 当传入事务句柄时，自动使用事务内 DataOperations；否则使用 reldb.sql。
+     *
+     * @param tx - 可选事务句柄
+     * @returns DataOperations 实例
+     */
+    protected sql(tx?: DmlWithTxOperations): DmlOperations;
+    /**
+     * 解析主键字段
+     *
+     * 优先使用声明为主键的字段；如果未声明主键，则回退到列名匹配。
+     *
+     * @param fields - 字段定义列表
+     * @param idColumn - 主键列名
+     * @returns 主键字段名（可能为空）
+     */
+    private resolveIdField;
+    /**
+     * 生成默认主键生成器
+     *
+     * 在运行环境支持 `crypto.randomUUID` 时返回 UUID 生成函数，否则返回 undefined。
+     */
+    private defaultIdGenerator;
+    /**
+     * 构建表结构定义
+     *
+     * @param fields - 字段定义列表
+     * @returns 表结构定义
+     */
+    private buildReldbTableDef;
+    /**
+     * 归一化列定义
+     *
+     * 用于处理不同数据库对默认值的兼容差异（例如 BOOLEAN）。
+     */
+    private normalizeReldbColumnDef;
+    /**
+     * 判断是否为创建时间字段
+     */
+    private isCreatedAtField;
+    /**
+     * 判断是否为更新时间字段
+     */
+    private isUpdatedAtField;
+    /**
+     * 将数据库值转换为业务值
+     *
+     * @param value - 数据库原始值
+     * @param def - 字段定义
+     * @returns 业务侧值（可能为 undefined）
+     */
+    private fromDbValue;
+    /**
+     * 将业务值转换为数据库值
+     *
+     * @param value - 业务侧值
+     * @param def - 字段定义
+     * @returns 适配数据库的值
+     */
+    private toDbValue;
+    /**
+     * 将查询行映射为业务模型
+     */
+    private mapRow;
+    /**
+     * 构建创建数据的列值映射
+     *
+     * 处理主键生成、默认值、createdAt/updatedAt 填充等规则。
+     */
+    private buildCreatePayload;
+    /**
+     * 构建更新数据的列值映射
+     *
+     * 当没有任何可更新字段时返回 null。
+     */
+    private buildUpdatePayload;
+    /**
+     * 等待初始化完成
+     *
+     * @returns 初始化结果
+     */
+    private ensureReady;
+    /**
+     * 创建单条记录
+     *
+     * 自动处理主键生成、createdAt/updatedAt 填充、字段类型转换。
+     *
+     * @param data - 业务字段与值的映射
+     * @param tx - 可选事务句柄
+     * @returns 插入结果（含 changes、lastInsertRowid）
+     */
+    create(data: Record<string, unknown>, tx?: DmlWithTxOperations): Promise<HaiResult<ExecuteResult>>;
+    /**
+     * 批量创建记录
+     *
+     * 每条记录均通过 buildCreatePayload 处理，然后以 batch 方式写入。
+     *
+     * @param items - 待插入的业务数据数组
+     * @param tx - 可选事务句柄
+     * @returns 批量插入结果
+     */
+    createMany(items: Array<Record<string, unknown>>, tx?: DmlWithTxOperations): Promise<HaiResult<void>>;
+    /**
+     * 创建或更新单条记录（upsert）
+     *
+     * 主键存在时更新可更新字段，否则插入新记录。
+     * 自动处理主键生成、createdAt/updatedAt 填充、字段类型转换。
+     * 更新时仅写入用户显式提供的可更新字段，不会用默认值覆盖已有数据。
+     *
+     * ### 为什么不复用 this.crud.createOrUpdate（kernel）
+     *
+     * Kernel 的 createOrUpdate 使用 `excluded.col` / `VALUES(col)` 引用 INSERT 值作为
+     * UPDATE 值，即 INSERT 和 UPDATE 共享同一组数据。但 Repository 层的 INSERT 负载和
+     * UPDATE 负载语义不同：
+     *
+     * - **INSERT 负载**（buildCreatePayload）：包含自动生成的主键、createdAt、updatedAt、
+     *   字段默认值（如 `status: 'active'`）等应用层填充值。
+     * - **UPDATE 负载**（buildUpdatePayload）：仅包含用户显式传入的可更新字段 + updatedAt，
+     *   不包含 createdAt（避免覆盖原始创建时间）、不包含应用默认值（避免覆盖已有数据）。
+     *
+     * 若复用 kernel，冲突更新时会将 INSERT 的 createdAt、默认值等一并写入，破坏已有记录。
+     * 因此 Repository 自行构建两份独立负载，使用 `col = ?` 参数化占位分别传入 INSERT 值
+     * 和 UPDATE 值，通过 this.sql(tx).execute() 直接执行。
+     *
+     * @param data - 业务字段与值的映射
+     * @param tx - 可选事务句柄
+     * @returns 执行结果（含 changes）
+     */
+    createOrUpdate(data: Record<string, unknown>, tx?: DmlWithTxOperations): Promise<HaiResult<ExecuteResult>>;
+    /**
+     * 根据主键查找单条记录
+     *
+     * @param id - 主键值
+     * @param tx - 可选事务句柄
+     * @returns 业务模型对象或 null（未找到）
+     */
+    findById(id: unknown, tx?: DmlWithTxOperations): Promise<HaiResult<TItem | null>>;
+    /**
+     * 根据主键获取单条记录（必须存在）
+     *
+     * 与 findById 不同，当记录不存在时返回 RECORD_NOT_FOUND 错误。
+     *
+     * @param id - 主键值
+     * @param tx - 可选事务句柄
+     * @returns 业务模型对象（不存在时返回错误）
+     */
+    getById(id: unknown, tx?: DmlWithTxOperations): Promise<HaiResult<TItem>>;
+    /**
+     * 条件查询多条记录
+     *
+     * @param options - 查询条件（where、orderBy、limit、offset）
+     * @param tx - 可选事务句柄
+     * @returns 业务模型数组
+     */
+    findAll(options?: CrudQueryOptions, tx?: DmlWithTxOperations): Promise<HaiResult<TItem[]>>;
+    /**
+     * 分页查询记录
+     *
+     * @param options - 分页查询条件（where、orderBy、pagination、overrides）
+     * @param tx - 可选事务句柄
+     * @returns 分页结果（含 items、total、page、pageSize）
+     */
+    findPage(options: CrudPageOptions, tx?: DmlWithTxOperations): Promise<HaiResult<PaginatedResult<TItem>>>;
+    /**
+     * 根据主键更新记录
+     *
+     * 自动填充 updatedAt 字段。无可更新字段时返回 CONFIG_ERROR。
+     *
+     * @param id - 主键值
+     * @param data - 待更新的业务字段
+     * @param tx - 可选事务句柄
+     * @returns 更新结果（含 changes）
+     */
+    updateById(id: unknown, data: Record<string, unknown>, tx?: DmlWithTxOperations): Promise<HaiResult<ExecuteResult>>;
+    /**
+     * 根据主键删除记录
+     *
+     * @param id - 主键值
+     * @param tx - 可选事务句柄
+     * @returns 删除结果（含 changes）
+     */
+    deleteById(id: unknown, tx?: DmlWithTxOperations): Promise<HaiResult<ExecuteResult>>;
+    /**
+     * 统计符合条件的记录数
+     *
+     * @param options - 查询条件（where、params）
+     * @param tx - 可选事务句柄
+     * @returns 记录数
+     */
+    count(options?: ReldbCrudCountOptions, tx?: DmlWithTxOperations): Promise<HaiResult<number>>;
+    /**
+     * 检查是否存在符合条件的记录
+     *
+     * @param options - 查询条件（where、params）
+     * @param tx - 可选事务句柄
+     * @returns 是否存在
+     */
+    exists(options?: ReldbCrudCountOptions, tx?: DmlWithTxOperations): Promise<HaiResult<boolean>>;
+    /**
+     * 根据主键检查记录是否存在
+     *
+     * @param id - 主键值
+     * @param tx - 可选事务句柄
+     * @returns 是否存在
+     */
+    existsById(id: unknown, tx?: DmlWithTxOperations): Promise<HaiResult<boolean>>;
+}
+
+/**
+ * @h-ai/reldb — 数据库服务主入口
+ *
+ * 本文件提供统一的 `reldb` 对象，聚合所有数据库操作功能。
+ * @module reldb-main
+ */
+
+/**
+ * 数据库服务对象
+ *
+ * 统一的数据库访问入口，提供以下功能：
+ * - `reldb.init()` - 初始化数据库连接
+ * - `reldb.close()` - 关闭连接
+ * - `reldb.ddl` - DDL 操作（表结构管理）
+ * - `reldb.sql` - SQL 操作（数据查询和修改）
+ * - `reldb.tx` - 事务管理器（begin / wrap）
+ * - `reldb.json` - JSON 路径操作 SQL 构建器（提取、设置、插入、删除、合并）
+ * - `reldb.config` - 当前配置
+ * - `reldb.isInitialized` - 初始化状态
+ *
+ * @example
+ * ```ts
+ * import { reldb } from '@h-ai/reldb'
+ *
+ * // 初始化
+ * await reldb.init({ type: 'sqlite', database: ':memory:' })
+ *
+ * // DDL 操作
+ * await reldb.ddl.createTable('users', {
+ *     id: { type: 'INTEGER', primaryKey: true, autoIncrement: true },
+ *     name: { type: 'TEXT', notNull: true }
+ * })
+ *
+ * // SQL 操作
+ * await reldb.sql.execute('INSERT INTO users (name) VALUES (?)', ['张三'])
+ * const users = await reldb.sql.query('SELECT * FROM users')
+ *
+ * // 事务操作
+ * await reldb.tx.wrap(async (tx) => {
+ *     await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户1'])
+ *     await tx.execute('INSERT INTO users (name) VALUES (?)', ['用户2'])
+ *     return 'done'
+ * })
+ *
+ * // 关闭连接
+ * await reldb.close()
+ * ```
+ */
+declare const reldb: ReldbFunctions;
+
+/**
+ * @h-ai/reldb — 安全工具
+ *
+ * 提供 SQL 标识符校验与字符串值转义功能，防止注入风险。
+ * @module reldb-security
+ */
+
+/**
+ * 校验 SQL 标识符合法性
+ *
+ * 防止因动态拼接表名/列名/索引名而产生 SQL 注入风险。
+ * 仅允许 `[a-zA-Z_][a-zA-Z0-9_]*`，最长 128 字符。
+ *
+ * @param name - 待校验的标识符
+ * @returns 校验通过时返回 ok(name)；不合法时返回错误 HaiResult
+ *
+ * @example
+ * ```ts
+ * const result = validateIdentifier('users')
+ * // result.success === true
+ *
+ * const bad = validateIdentifier('users; DROP TABLE')
+ * // bad.success === false
+ * ```
+ */
+declare function validateIdentifier(name: string): HaiResult<string>;
+/**
+ * 批量校验多个 SQL 标识符
+ *
+ * 逐个校验，遇到第一个不合法的立即返回错误。
+ *
+ * @param names - 待校验的标识符数组
+ * @returns 全部合法时返回 ok(undefined)；否则返回第一个不合法项的错误
+ */
+declare function validateIdentifiers(names: string[]): HaiResult<void>;
+/**
+ * 用双引号包裹 SQL 标识符（适用于 PostgreSQL / SQLite / 标准 SQL）
+ *
+ * 标识符内的双引号会被转义为两个双引号。
+ * 使用场景：DDL 中的表名、列名、索引名。
+ * 调用前应先通过 `validateIdentifier` 校验合法性。
+ *
+ * @param name - 已校验的标识符
+ * @returns 双引号包裹的安全标识符
+ *
+ * @example
+ * ```ts
+ * quoteIdentifier('users')  // '"users"'
+ * quoteIdentifier('order')  // '"order"'  （安全引用 SQL 保留字）
+ * ```
+ */
+declare function quoteIdentifier(name: string): string;
+/**
+ * 转义 SQL 字符串字面量中的单引号
+ *
+ * 将 `'` 转义为 `''`，用于 DDL 中 DEFAULT 值等需要直接拼接的场景。
+ * 注意：仅用于标识符/DDL 场景，数据操作应始终使用参数化查询。
+ *
+ * @param value - 原始字符串
+ * @returns 转义后的安全字符串
+ *
+ * @example
+ * ```ts
+ * escapeSqlString("it's") // "it''s"
+ * escapeSqlString("normal") // "normal"
+ * ```
+ */
+declare function escapeSqlString(value: string): string;
+
+export { BaseReldbCrudRepository, type BaseReldbCrudRepositoryConfig, type ColumnType, type CrudConfig, type CrudManager, type CrudPageOptions, type CrudQueryOptions, type DbType, type DdlOperations, type DmlOperations, type DmlWithTxOperations, type ExecuteResult, HaiReldbError, type JsonSqlExpr, type MysqlConfig, MysqlConfigSchema, MysqlOptionsSchema, type NormalizedPagination, type PaginationOverrides, type PaginationQueryOptions, type PoolConfig, PoolConfigSchema, type PostgresqlConfig, PostgresqlConfigSchema, type QueryRow, type ReldbColumnDef, type ReldbConfig, type ReldbConfigInput, ReldbConfigSchema, type ReldbCrudCountOptions, type ReldbCrudFieldDefinition, type ReldbCrudRepository, type ReldbFunctions, type ReldbIndexDef, type ReldbJsonOps, type ReldbProvider, type ReldbTableDef, ReldbTypeSchema, type SqliteConfig, SqliteConfigSchema, SqliteOptionsSchema, type SslConfig, SslConfigSchema, type TxManager, type TxWrapCallback, createJsonOps, escapeSqlString, parseJsonPath, quoteIdentifier, reldb, validateIdentifier, validateIdentifiers };