@h-ai/reldb 1.0.0-beta.2 → 1.0.0-beta.20

package/dist/chunk-7OE27ZH3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/reldb-config.ts"],"names":[],"mappings":"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","file":"chunk-7OE27ZH3.js","sourcesContent":["/**\n * @h-ai/reldb — 数据库配置 Schema\n *\n * 本文件定义数据库模块的配置结构，使用 Zod 进行运行时校验。\n * @module reldb-config\n */\n\nimport { z } from 'zod'\n// ─── 数据库配置 Schema ───\n\n/**\n * 数据库类型枚举\n *\n * 支持的数据库类型：\n * - `sqlite` - SQLite 嵌入式数据库（使用 better-sqlite3）\n * - `postgresql` - PostgreSQL 数据库（使用 pg）\n * - `mysql` - MySQL 数据库（使用 mysql2）\n * @example\n * ```ts\n * import { ReldbTypeSchema } from '@h-ai/reldb/schemas'\n *\n * const value = ReldbTypeSchema.parse('postgresql')\n * void value\n * ```\n */\nexport const ReldbTypeSchema = z.enum(['sqlite', 'postgresql', 'mysql'])\n\n/**\n * 数据库类型\n * @example\n * ```ts\n * import type { DbType } from '@h-ai/reldb/schemas'\n *\n * const value: DbType = 'postgresql'\n * void value\n * ```\n */\nexport type DbType = z.infer<typeof ReldbTypeSchema>\n\n/**\n * ReldbOperationLogConfigSchema 的数据约束与操作契约。\n * @example\n * ```ts\n * import { ReldbOperationLogConfigSchema } from '@h-ai/reldb/schemas'\n *\n * const value = ReldbOperationLogConfigSchema.parse({ read: false, write: true, maxLength: 100, level: 'debug' })\n * void value\n * ```\n */\nexport const ReldbOperationLogConfigSchema = z.object({\n  read: z.boolean().default(false),\n  write: z.boolean().default(false),\n  /** 安全数量摘要的最大字符数；0 表示省略摘要，永不记录 SQL 原文或参数值。 */\n  maxLength: z.number().int().min(0).default(1000),\n  level: z.enum(['info', 'debug', 'trace']).default('debug'),\n})\n\n/**\n * ReldbOperationLogConfig 的数据约束与操作契约。\n * @example\n * ```ts\n * import { ReldbOperationLogConfigSchema, type ReldbOperationLogConfig } from '@h-ai/reldb/schemas'\n *\n * const value: ReldbOperationLogConfig = ReldbOperationLogConfigSchema.parse({ read: false, write: true, maxLength: 100, level: 'debug' })\n * void value\n * ```\n */\nexport type ReldbOperationLogConfig = z.infer<typeof ReldbOperationLogConfigSchema>\n\nconst OperationLogConfigFieldSchema = {\n  operationLog: ReldbOperationLogConfigSchema.optional(),\n}\n\n/**\n * PostgreSQL 连接池配置 Schema\n *\n * min 是已建立连接的保留下限，不主动预建连接。\n * MySQL 使用独立的 MysqlPoolConfigSchema；SQLite 不使用连接池。\n * @example\n * ```ts\n * import { PoolConfigSchema } from '@h-ai/reldb/schemas'\n *\n * const value = PoolConfigSchema.parse({ max: 10, acquireTimeout: 5000 })\n * void value\n * ```\n */\nexport const PoolConfigSchema = z.object({\n  /** PostgreSQL 已建立连接的最小保留数（默认 1，不主动预建） */\n  min: z.number().int().min(0).default(1),\n  /** 最大连接数（默认 10） */\n  max: z.number().int().min(1).default(10),\n  /** PostgreSQL 空闲连接超时，毫秒（默认 30000；0 禁用） */\n  idleTimeout: z.number().int().min(0).default(30000),\n  /** 获取连接超时，毫秒（默认10000）；PostgreSQL >=0，0禁用；MySQL排队+建连总期限为1–2147483647 */\n  acquireTimeout: z.number().int().min(0).default(10000),\n})\n\n/**\n * PostgreSQL 连接池配置类型。\n * @example\n * ```ts\n * import { PoolConfigSchema, type PoolConfig } from '@h-ai/reldb/schemas'\n *\n * const value: PoolConfig = PoolConfigSchema.parse({ max: 10, acquireTimeout: 5000 })\n * void value\n * ```\n */\nexport type PoolConfig = z.infer<typeof PoolConfigSchema>\n\n/**\n * MySQL 连接池配置：有界 FIFO 等待，拒绝没有可靠驱动语义的 min/idleTimeout。\n *\n * acquireTimeout 覆盖排队和建立连接，不是 SQL 执行时限。驱动建连也使用此值作为 connectTimeout。\n * 空闲连接由 mysql2/服务端管理；本模块不承诺最小保留数或可配置的空闲回收期限。\n * @example\n * ```ts\n * import { MysqlPoolConfigSchema } from '@h-ai/reldb/schemas'\n *\n * const value = MysqlPoolConfigSchema.parse({ max: 10, acquireTimeout: 5000, queueLimit: 100 })\n * void value\n * ```\n */\nexport const MysqlPoolConfigSchema = z.object({\n  /** 最大连接数（默认 10） */\n  max: z.number().int().min(1).default(10),\n  /** 获取连接超时，毫秒（默认10000）；PostgreSQL >=0，0禁用；MySQL排队+建连总期限为1–2147483647 */\n  acquireTimeout: z.number().int().min(1).max(2147483647).default(10000),\n  /** MySQL 等待队列最大请求数（默认 1000；正整数，不支持无限队列） */\n  queueLimit: z.number().int().min(1).default(1000),\n}).strict()\n\n/**\n * MySQL 解析后的连接池配置。\n * @example\n * ```ts\n * import { MysqlPoolConfigSchema, type MysqlPoolConfig } from '@h-ai/reldb/schemas'\n *\n * const value: MysqlPoolConfig = MysqlPoolConfigSchema.parse({ max: 10, acquireTimeout: 5000, queueLimit: 100 })\n * void value\n * ```\n */\nexport type MysqlPoolConfig = z.infer<typeof MysqlPoolConfigSchema>\n\n/**\n * PostgreSQL SSL 配置 Schema\n *\n * 支持多种配置方式：\n * - `true/false` - 简单开关\n * - `'require'/'prefer'/'allow'/'disable'` - SSL 模式\n * - 自定义对象 - 详细 SSL 配置\n * @example\n * ```ts\n * import { SslConfigSchema } from '@h-ai/reldb/schemas'\n *\n * const value = SslConfigSchema.parse({ rejectUnauthorized: true })\n * void value\n * ```\n */\nexport const SslConfigSchema = z.union([\n  z.boolean(),\n  z.enum([\n    'require',\n    'prefer',\n    'allow',\n    'disable',\n  ]),\n  z.record(z.string(), z.unknown()),\n])\n\n/**\n * PostgreSQL SSL 配置类型\n * @example\n * ```ts\n * import { SslConfigSchema, type SslConfig } from '@h-ai/reldb/schemas'\n *\n * const value: SslConfig = SslConfigSchema.parse({ rejectUnauthorized: true })\n * void value\n * ```\n */\nexport type SslConfig = z.infer<typeof SslConfigSchema>\n\n/**\n * MySQL TLS 配置；空对象默认校验证书链和 DNS 主机身份，只接收明确支持的 PEM 字段。\n *\n * cert/key 必须成对。verifyIdentity 在当前驱动仅支持 DNS 主机，不能宣称验证 IP 身份。\n * 显式关闭验证会记录风险日志；本模块不提供任意 TLS 参数或回调透传。\n * @example\n * ```ts\n * import { MysqlSslConfigSchema } from '@h-ai/reldb/schemas'\n *\n * const value = MysqlSslConfigSchema.parse({ rejectUnauthorized: true, verifyIdentity: true })\n * void value\n * ```\n */\nexport const MysqlSslConfigSchema = z.union([\n  z.literal(false),\n  z.object({\n    /** MySQL 是否校验证书链（默认 true）；false 明确放弃服务端认证 */\n    rejectUnauthorized: z.boolean().default(true),\n    /** MySQL 是否验证 DNS 主机身份（默认 true）；仅证书链验证开启时有效 */\n    verifyIdentity: z.boolean().default(true),\n    /** MySQL 信任的 CA，PEM 内容；省略时使用 Node 信任库 */\n    ca: z.string().min(1).optional(),\n    /** MySQL 客户端证书，PEM 内容；必须同时提供 key */\n    cert: z.string().min(1).optional(),\n    /** MySQL 客户端私钥，PEM 内容；必须同时提供 cert */\n    key: z.string().min(1).optional(),\n  }).strict().refine(ssl => Boolean(ssl.cert) === Boolean(ssl.key), {\n    path: ['key'],\n  }),\n])\n\n/**\n * SQLite 特定选项 Schema\n * @example\n * ```ts\n * import { SqliteOptionsSchema } from '@h-ai/reldb/schemas'\n *\n * const value = SqliteOptionsSchema.parse({ walMode: true, executor: 'worker' })\n * void value\n * ```\n */\nexport const SqliteOptionsSchema = z.object({\n  /** 是否启用 WAL 模式（默认 true），可提高并发读写性能 */\n  walMode: z.boolean().default(true),\n  /** 是否只读模式（默认 false） */\n  readonly: z.boolean().default(false),\n  /**\n   * 执行方式（默认 sync）。\n   *\n   * - `sync`：主线程直接执行 better-sqlite3（同步阻塞主线程事件循环）。\n   * - `worker`：在专用 worker 线程持有唯一连接执行，把阻塞移出主线程。\n   *   注意 WAL 只改善数据库锁并发，无法避免 better-sqlite3 同步调用占用调用线程。\n   */\n  executor: z.enum(['sync', 'worker']).default('sync'),\n  /** worker 执行方式下等待连接打开的超时（毫秒，默认 10000） */\n  workerConnectTimeoutMs: z.number().int().positive().default(10_000),\n})\n\n/**\n * MySQL 特定选项 Schema\n * @example\n * ```ts\n * import { MysqlOptionsSchema } from '@h-ai/reldb/schemas'\n *\n * const value = MysqlOptionsSchema.parse({ charset: 'utf8mb4' })\n * void value\n * ```\n */\nexport const MysqlOptionsSchema = z.object({\n  /** 字符集（默认 utf8mb4），推荐使用 utf8mb4 支持完整 Unicode */\n  charset: z.string().default('utf8mb4'),\n}).strict()\n\n// ─── 网络数据库共享字段 ───\n\nconst NetworkConfigSchema = z.object({\n  /**\n   * 连接字符串（可选）\n   * 如果提供 url，将优先使用，忽略 host/port 等字段\n   */\n  url: z.string().optional(),\n\n  /** 数据库主机地址（默认 localhost） */\n  host: z.string().default('localhost'),\n\n  /**\n   * 数据库端口\n   * - PostgreSQL 默认 5432\n   * - MySQL 默认 3306\n   */\n  port: z.number().int().min(1).max(65535).optional(),\n\n  /** 数据库名称 */\n  database: z.string(),\n\n  /** 数据库用户名 */\n  user: z.string().optional(),\n\n  /** 数据库密码 */\n  password: z.string().optional(),\n\n  /** SSL/TLS 连接配置 */\n  ssl: SslConfigSchema.optional(),\n\n  /** 连接池配置 */\n  pool: PoolConfigSchema.optional(),\n})\n\n// ─── 各数据库类型配置 Schema ───\n\n/**\n * SQLite 配置 Schema\n * @example\n * ```ts\n * import { SqliteConfigSchema } from '@h-ai/reldb/schemas'\n *\n * const value = SqliteConfigSchema.parse({ type: 'sqlite', database: './data/app.db' })\n * void value\n * ```\n */\nexport const SqliteConfigSchema = z.object({\n  type: z.literal('sqlite'),\n  /** 数据库文件路径（如 './data.db'）或 ':memory:'（内存数据库） */\n  database: z.string(),\n  /** SQLite 特定选项 */\n  sqlite: SqliteOptionsSchema.optional(),\n  ...OperationLogConfigFieldSchema,\n})\n\n/**\n * PostgreSQL 配置 Schema\n * @example\n * ```ts\n * import { PostgresqlConfigSchema } from '@h-ai/reldb/schemas'\n *\n * const value = PostgresqlConfigSchema.parse({ type: 'postgresql', database: 'app', host: 'db', pool: { max: 10 } })\n * void value\n * ```\n */\nexport const PostgresqlConfigSchema = NetworkConfigSchema.extend({\n  type: z.literal('postgresql'),\n  ...OperationLogConfigFieldSchema,\n})\n\n/**\n * MySQL 配置 Schema\n * @example\n * ```ts\n * import { MysqlConfigSchema } from '@h-ai/reldb/schemas'\n *\n * const value = MysqlConfigSchema.parse({ type: 'mysql', database: 'app', host: 'db', pool: { max: 10, queueLimit: 100 } })\n * void value\n * ```\n */\nexport const MysqlConfigSchema = NetworkConfigSchema.extend({\n  type: z.literal('mysql'),\n  /** 网络数据库URL；MySQL空串表示使用分字段，非空仅mysql://且拒绝query/fragment，优先于host/port/database/user/password */\n  url: z.union([\n    z.literal('').transform(() => undefined),\n    z.url({ protocol: /^mysql$/ }).refine(value => !value.includes('?') && !value.includes('#')),\n  ]).optional(),\n  /** 数据库：SQLite文件路径或:memory:；PostgreSQL必填名称；MySQL无URL时必填，URL模式从URL读取 */\n  database: z.string().min(1).optional(),\n  /** TLS：PostgreSQL使用其模式；MySQL仅false或严格对象，空对象默认校验证书链和DNS身份 */\n  ssl: MysqlSslConfigSchema.optional(),\n  /** 连接池配置：PostgreSQL支持min/idleTimeout；MySQL仅max/acquireTimeout/queueLimit，拒绝其他字段 */\n  pool: MysqlPoolConfigSchema.optional(),\n  /** MySQL 特定选项 */\n  mysql: MysqlOptionsSchema.optional(),\n  ...OperationLogConfigFieldSchema,\n}).refine(config => Boolean(config.url) || Boolean(config.database), {\n  path: ['database'],\n})\n\n/**\n * 统一数据库配置 Schema（判别联合体）\n *\n * 根据 `type` 字段区分不同数据库类型的配置。\n * @example\n * ```ts\n * import { ReldbConfigSchema } from '@h-ai/reldb/schemas'\n *\n * const value = ReldbConfigSchema.parse({ type: 'postgresql', database: 'app', host: 'db' })\n * void value\n * ```\n */\nexport const ReldbConfigSchema = z.discriminatedUnion('type', [\n  SqliteConfigSchema,\n  PostgresqlConfigSchema,\n  MysqlConfigSchema,\n])\n\n/**\n * 数据库配置类型（判别联合体）\n * @example\n * ```ts\n * import { ReldbConfigSchema, type ReldbConfig } from '@h-ai/reldb/schemas'\n *\n * const value: ReldbConfig = ReldbConfigSchema.parse({ type: 'postgresql', database: 'app', host: 'db' })\n * void value\n * ```\n */\nexport type ReldbConfig = z.infer<typeof ReldbConfigSchema>\n\n/**\n * SQLite 配置类型\n * @example\n * ```ts\n * import { SqliteConfigSchema, type SqliteConfig } from '@h-ai/reldb/schemas'\n *\n * const value: SqliteConfig = SqliteConfigSchema.parse({ type: 'sqlite', database: './data/app.db' })\n * void value\n * ```\n */\nexport type SqliteConfig = z.infer<typeof SqliteConfigSchema>\n\n/**\n * PostgreSQL 配置类型\n * @example\n * ```ts\n * import { PostgresqlConfigSchema, type PostgresqlConfig } from '@h-ai/reldb/schemas'\n *\n * const value: PostgresqlConfig = PostgresqlConfigSchema.parse({ type: 'postgresql', database: 'app', host: 'db', pool: { max: 10 } })\n * void value\n * ```\n */\nexport type PostgresqlConfig = z.infer<typeof PostgresqlConfigSchema>\n\n/**\n * MySQL 配置类型\n * @example\n * ```ts\n * import { MysqlConfigSchema, type MysqlConfig } from '@h-ai/reldb/schemas'\n *\n * const value: MysqlConfig = MysqlConfigSchema.parse({ type: 'mysql', database: 'app', host: 'db', pool: { max: 10, queueLimit: 100 } })\n * void value\n * ```\n */\nexport type MysqlConfig = z.infer<typeof MysqlConfigSchema>\n\n/**\n * 数据库配置输入类型（用于 init 等入口）\n *\n * 说明：Zod 的 default 会让输入端字段可省略，但输出端字段为必填。\n * 因此对外 API（如 reldb.init）更适合接收 ReldbConfigInput。\n * @example\n * ```ts\n * import type { ReldbConfigInput } from '@h-ai/reldb/schemas'\n *\n * const value: ReldbConfigInput = { type: 'postgresql', host: 'db', database: 'app' }\n * void value\n * ```\n */\nexport type ReldbConfigInput = z.input<typeof ReldbConfigSchema>\n"]}

package/dist/index.d.ts

@@ -192,6 +192,38 @@ declare function parseJsonPath(path: string): string[];
  */
 declare function createJsonOps(dbType: 'sqlite' | 'postgresql' | 'mysql'): ReldbJsonOps;
 
+/** 模块维护自己的迁移；这里只提供跨数据库列检查、版本账本和执行边界。 */
+
+/**
+ * 一个可重入的模块升级步骤；只接收代码中固定的 SQL 与表名。
+ * @example
+ * ```ts
+ * import type { SchemaMigration } from '@h-ai/reldb'
+ * const steps: SchemaMigration[] = []
+ * ```
+ */
+interface SchemaMigration {
+    version: number;
+    name: string;
+    needed: (sql: DmlOperations) => Promise<HaiResult<boolean>>;
+    apply: (sql: DmlOperations) => Promise<HaiResult<unknown>>;
+}
+/**
+ * 只读预检结果；生产升级需先停旧写入并备份数据库与共享缓存。
+ * @example
+ * ```ts
+ * import type { SchemaMigrationPlan } from '@h-ai/reldb'
+ * function changes(plan: SchemaMigrationPlan) { return plan.changes }
+ * ```
+ */
+interface SchemaMigrationPlan {
+    module: string;
+    currentVersion: number;
+    targetVersion: number;
+    changes: string[];
+    requiresExclusiveAccess: boolean;
+}
+
 /**
  * HaiReldbError 的数据约束与操作契约。
  * @example
@@ -957,6 +989,28 @@ interface ReldbFunctions {
     readonly crud: CrudManager;
     /** 事务管理器 */
     readonly tx: TxManager;
+    /**
+     * 预检或执行模块维护的版本迁移；绑定当前数据库，不接受其它模块实例。
+     * @example
+     * ```ts
+     * import { reldb } from '@h-ai/reldb'
+     * const plan = await reldb.migrateSchema('example', [], { dryRun: true })
+     * if (!plan.success) throw new Error(plan.error.message)
+     * ```
+     */
+    migrateSchema: (module: string, steps: readonly SchemaMigration[], options?: {
+        dryRun?: boolean;
+    }) => Promise<HaiResult<SchemaMigrationPlan>>;
+    /**
+     * 只读查询当前数据库真实列名；sql 可指定当前事务，不创建表。
+     * @example
+     * ```ts
+     * import { reldb } from '@h-ai/reldb'
+     * const columns = await reldb.schemaColumns('hai_iam_users')
+     * if (!columns.success) throw new Error(columns.error.message)
+     * ```
+     */
+    schemaColumns: (table: string, sql?: DmlOperations) => Promise<HaiResult<string[]>>;
     /** 当前数据库脱敏配置快照（未初始化时为 null） */
     readonly config: ReldbConfig | null;
     /** 是否已初始化 */
@@ -1458,59 +1512,6 @@ declare abstract class BaseReldbCrudRepository<TItem> implements ReldbCrudReposi
  */
 declare const reldb: ReldbFunctions;
 
-/** 模块维护自己的迁移；这里只提供跨数据库列检查、版本账本和执行边界。 */
-
-/**
- * 一个可重入的模块升级步骤；只接收代码中固定的 SQL 与表名。
- * @example
- * ```ts
- * import type { SchemaMigration } from '@h-ai/reldb'
- * const steps: SchemaMigration[] = []
- * ```
- */
-interface SchemaMigration {
-    version: number;
-    name: string;
-    needed: (sql: DmlOperations) => Promise<HaiResult<boolean>>;
-    apply: (sql: DmlOperations) => Promise<HaiResult<unknown>>;
-}
-/**
- * 只读预检结果；生产升级需先停旧写入并备份数据库与共享缓存。
- * @example
- * ```ts
- * import type { SchemaMigrationPlan } from '@h-ai/reldb'
- * function changes(plan: SchemaMigrationPlan) { return plan.changes }
- * ```
- */
-interface SchemaMigrationPlan {
-    module: string;
-    currentVersion: number;
-    targetVersion: number;
-    changes: string[];
-    requiresExclusiveAccess: boolean;
-}
-/**
- * 查询真实列名；不创建表，不把查询错误当成新安装。
- * @example
- * ```ts
- * import { reldb, schemaColumns } from '@h-ai/reldb'
- * const columns = await schemaColumns(reldb, 'hai_iam_users')
- * ```
- */
-declare function schemaColumns(db: ReldbFunctions, table: string, sql?: DmlOperations): Promise<HaiResult<string[]>>;
-/**
- * 预检或执行模块维护的版本迁移。SQLite/PostgreSQL 原子提交；MySQL DDL 隐式提交，步骤须可重入。
- * 失败不记录目标版本；重启重新检查真实结构。新版本账本拒绝旧代码向下迁移。
- * @example
- * ```ts
- * import { reldb, migrateSchema } from '@h-ai/reldb'
- * const plan = await migrateSchema(reldb, 'example', [], { dryRun: true })
- * ```
- */
-declare function migrateSchema(db: ReldbFunctions, module: string, steps: readonly SchemaMigration[], options?: {
-    dryRun?: boolean;
-}): Promise<HaiResult<SchemaMigrationPlan>>;
-
 /**
  * @h-ai/reldb — 安全工具
  *
@@ -1588,4 +1589,5 @@ declare function quoteIdentifier(name: string): string;
  */
 declare function escapeSqlString(value: string): string;
 
-export { BaseReldbCrudRepository, type BaseReldbCrudRepositoryConfig, type ColumnType, type CrudConfig, type CrudManager, type CrudPageOptions, type CrudQueryOptions, DbType, type DdlOperations, type DmlOperations, type DmlWithTxOperations, type ExecuteResult, HaiReldbError, type JsonSqlExpr, type NormalizedPagination, type PaginationOverrides, type PaginationQueryOptions, type QueryRow, type ReldbColumnDef, ReldbConfig, ReldbConfigInput, type ReldbCrudCountOptions, type ReldbCrudFieldDefinition, type ReldbCrudRepository, type ReldbFunctions, type ReldbIndexDef, type ReldbJsonOps, type ReldbTableDef, type SchemaMigration, type SchemaMigrationPlan, type TxManager, type TxWrapCallback, createJsonOps, escapeSqlString, migrateSchema, parseJsonPath, quoteIdentifier, reldb, schemaColumns, validateIdentifier, validateIdentifiers };
+export { BaseReldbCrudRepository, DbType, HaiReldbError, ReldbConfig, ReldbConfigInput, createJsonOps, escapeSqlString, parseJsonPath, quoteIdentifier, reldb, validateIdentifier, validateIdentifiers };
+export type { BaseReldbCrudRepositoryConfig, ColumnType, CrudConfig, CrudManager, CrudPageOptions, CrudQueryOptions, DdlOperations, DmlOperations, DmlWithTxOperations, ExecuteResult, JsonSqlExpr, NormalizedPagination, PaginationOverrides, PaginationQueryOptions, QueryRow, ReldbColumnDef, ReldbCrudCountOptions, ReldbCrudFieldDefinition, ReldbCrudRepository, ReldbFunctions, ReldbIndexDef, ReldbJsonOps, ReldbTableDef, SchemaMigration, SchemaMigrationPlan, TxManager, TxWrapCallback };