@zhin.js/database 1.1.4 → 1.1.6

package/README.md

@@ -16,6 +16,8 @@ npm install mysql2
 
 # For PostgreSQL
 npm install pg
+# TypeScript projects selecting PostgreSQL types also install its declarations
+npm install --save-dev @types/pg
 
 # For MongoDB
 npm install mongodb
@@ -24,6 +26,34 @@ npm install mongodb
 npm install redis
 ```
 
+## TypeScript entry points
+
+The default entry exports the neutral database/model/transaction APIs and Memory/SQLite. External dialects expose their complete native driver options through their own entries:
+
+| Dialect | Class and configuration entry |
+| --- | --- |
+| MySQL | `@zhin.js/database/dialects/mysql` |
+| PostgreSQL | `@zhin.js/database/dialects/pg` |
+| MongoDB | `@zhin.js/database/dialects/mongodb` |
+| Redis | `@zhin.js/database/dialects/redis` |
+
+Select the corresponding types before using a remote `Registry.create()` call:
+
+```typescript
+import { Registry } from '@zhin.js/database';
+import type {} from '@zhin.js/database/dialects/pg';
+
+const db = Registry.create('pg', { application_name: 'my-bot', statement_timeout: 1000 });
+```
+
+Direct constructors are imported from the same dialect entry, for example `import { PG } from '@zhin.js/database/dialects/pg'`. They are no longer re-exported by the database, Core or Zhin default entry. SQLite users do not need the other four drivers or their declarations; JavaScript PostgreSQL users only need `pg`. `@types/pg` remains a build development dependency of this package, not a new optional peer.
+
+All built-in factories still register when the default entry is loaded. `Registry.create()` remains synchronous; native clients are loaded when the selected database connects. Host YAML/JSON configuration is unchanged.
+
+Third-party dialects augment only `@zhin.js/database/registry`: both `Databases<S>` and `Registry.Config` must describe their concrete class and configuration. The Registry value from this entry and from the default entry is the same initialized object. See the [type-isolation contract](../../docs/plans/database-optional-dialect-types.md).
+
+These entries first require **`@zhin.js/database >=1.1.6` (pending release)**. Plugins using them must declare that minimum database dependency; existing root imports of external dialect classes must be migrated together.
+
 ## Quick Start
 
 ```typescript
@@ -125,6 +155,8 @@ MySQL 方言将 `text` 的非空默认值和 `json` 默认值写成表达式，
 MySQL 或 mysql2，也无需删除已有数据库。修复针对新建表，不会缩窄既有文本列。
 
 ```typescript
+import type {} from '@zhin.js/database/dialects/mysql';
+
 const db = Registry.create('mysql', {
   host: 'localhost',
   port: 3306,
@@ -139,6 +171,8 @@ await db.start();
 ### PostgreSQL Example
 
 ```typescript
+import type {} from '@zhin.js/database/dialects/pg';
+
 const db = Registry.create('pg', {
   host: 'localhost',
   port: 5432,
@@ -153,6 +187,8 @@ await db.start();
 ### MongoDB Example
 
 ```typescript
+import type {} from '@zhin.js/database/dialects/mongodb';
+
 const db = Registry.create('mongodb', {
   url: 'mongodb://localhost:27017',
   dbName: 'myapp'
@@ -164,6 +200,8 @@ await db.start();
 ### Redis Example
 
 ```typescript
+import type {} from '@zhin.js/database/dialects/redis';
+
 const db = Registry.create('redis', {
   socket: {
     host: 'localhost',
@@ -934,6 +972,9 @@ if (db.isLogging) {
 MySQL 和 PostgreSQL 支持连接池，提高高并发场景下的性能：
 
 ```typescript
+import type {} from '@zhin.js/database/dialects/mysql';
+import type {} from '@zhin.js/database/dialects/pg';
+
 // MySQL 连接池配置
 const db = Registry.create('mysql', {
   host: 'localhost',

package/lib/base/database.d.ts

@@ -22,6 +22,10 @@ export declare abstract class Database<D = any, S extends Record<string, object>
     readonly models: Database.Models<S, D, Q>;
     private _logger?;
     private _logging;
+    private readonly transactionContext;
+    private connectionTail;
+    /** 单连接事务独占连接；连接池仍允许不相关操作并行。 */
+    private acquireConnection;
     constructor(dialect: Dialect<D, S, Q>, definitions?: Database.DefinitionObj<S>);
     /**
      * 若方言支持按列声明类型处理（如 SQLite 读路径的 json 反序列化），向其注册表结构

package/lib/base/database.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import * as QueryClasses from './query-classes.js';
 import { TransactionContextImpl } from './transaction.js';
 import { getLogger } from '@zhin.js/logger';
@@ -21,6 +22,19 @@ export class Database {
     models = new Database.Models();
     _logger;
     _logging = false;
+    transactionContext = new AsyncLocalStorage();
+    connectionTail = Promise.resolve();
+    /** 单连接事务独占连接；连接池仍允许不相关操作并行。 */
+    async acquireConnection() {
+        if (this.dialect.name !== 'sqlite'
+            && (!['mysql', 'pg'].includes(this.dialect.name) || this.config?.pool))
+            return () => undefined;
+        const previous = this.connectionTail;
+        let release;
+        this.connectionTail = new Promise(resolve => { release = resolve; });
+        await previous;
+        return release;
+    }
     constructor(dialect, definitions) {
         this.dialect = dialect;
         for (const key in definitions) {
@@ -108,9 +122,15 @@ export class Database {
         if (!this.isStarted) {
             throw new Error('Database not started');
         }
+        const context = this.transactionContext.getStore();
+        if (context && !context.active)
+            throw new Error('Database transaction is already closed');
+        const release = context ? () => undefined : await this.acquireConnection();
         const start = Date.now();
         try {
-            const result = await this.dialect.query(sql, params);
+            const result = context
+                ? await context.transaction.query(sql, params)
+                : await this.dialect.query(sql, params);
             this.log(String(sql), params, Date.now() - start);
             return result;
         }
@@ -118,6 +138,9 @@ export class Database {
             this.log(String(sql), params, Date.now() - start, error);
             throw error;
         }
+        finally {
+            release();
+        }
     }
     /**
      * 获取数据库方言名称
@@ -198,16 +221,37 @@ export class Database {
         if (!this.isStarted) {
             throw new Error('Database not started');
         }
-        const trx = await this.dialect.beginTransaction(options);
-        const trxContext = new TransactionContextImpl(this, trx);
+        if (this.transactionContext.getStore())
+            throw new Error('Nested database transactions are not supported');
+        const release = await this.acquireConnection();
         try {
-            const result = await callback(trxContext);
-            await trxContext.commit();
-            return result;
+            const trx = await this.dialect.beginTransaction(options);
+            const frame = { transaction: trx, active: true };
+            // 所有入口（含 model 查询）都绑定同一个事务，禁止异步逃逸后继续访问。
+            const guarded = {
+                query: (sql, params) => {
+                    if (!frame.active)
+                        return Promise.reject(new Error('Database transaction is already closed'));
+                    return trx.query(sql, params);
+                },
+                commit: () => trx.commit(),
+                rollback: () => trx.rollback(),
+            };
+            const trxContext = new TransactionContextImpl(this, guarded);
+            try {
+                const result = await this.transactionContext.run(frame, () => callback(trxContext));
+                frame.active = false;
+                await trxContext.commit();
+                return result;
+            }
+            catch (error) {
+                frame.active = false;
+                await trxContext.rollback();
+                throw error;
+            }
         }
-        catch (error) {
-            await trxContext.rollback();
-            throw error;
+        finally {
+            release();
         }
     }
     /**

package/lib/base/transaction.js

@@ -32,7 +32,7 @@ class TrxSelection {
         this.offsetCount = count;
         return this;
     }
-    then(onfulfilled) {
+    then(onfulfilled, onrejected) {
         const { query, params } = this.db.buildQuery({
             type: 'select',
             tableName: this.tableName,
@@ -42,7 +42,7 @@ class TrxSelection {
             limitCount: this.limitCount,
             offsetCount: this.offsetCount
         });
-        return this.trx.query(query, params).then(onfulfilled);
+        return this.trx.query(query, params).then(onfulfilled, onrejected);
     }
 }
 /**
@@ -64,18 +64,15 @@ class TrxUpdation {
         this.conditions = { ...this.conditions, ...condition };
         return this;
     }
-    then(onfulfilled) {
+    then(onfulfilled, onrejected) {
         const { query, params } = this.db.buildQuery({
             type: 'update',
             tableName: this.tableName,
             update: this.data,
             conditions: this.conditions
         });
-        return this.trx.query(query, params)
-            .then(result => {
-            const affected = affectedRows(result);
-            return onfulfilled ? onfulfilled(affected) : affected;
-        });
+        return this.trx.query(this.db.dialectName === 'pg' ? `${query} RETURNING 1` : query, params)
+            .then(affectedRows).then(onfulfilled, onrejected);
     }
 }
 /**
@@ -95,20 +92,19 @@ class TrxDeletion {
         this.conditions = { ...this.conditions, ...condition };
         return this;
     }
-    then(onfulfilled) {
+    then(onfulfilled, onrejected) {
         const { query, params } = this.db.buildQuery({
             type: 'delete',
             tableName: this.tableName,
             conditions: this.conditions
         });
-        return this.trx.query(query, params)
-            .then(result => {
-            const affected = affectedRows(result);
-            return onfulfilled ? onfulfilled(affected) : affected;
-        });
+        return this.trx.query(this.db.dialectName === 'pg' ? `${query} RETURNING 1` : query, params)
+            .then(affectedRows).then(onfulfilled, onrejected);
     }
 }
 function affectedRows(result) {
+    if (Array.isArray(result))
+        return result.length;
     return typeof result === 'number'
         ? result
         : result.affectedRows ?? result.changes ?? 0;

package/lib/builtin-runtime.d.ts

@@ -0,0 +1,2 @@
+/** Root-entry initialization only; vendor clients are still loaded on connect. */
+export declare function registerBuiltinDatabases(): void;

package/lib/builtin-runtime.js

@@ -0,0 +1,16 @@
+import { Registry } from './registry.js';
+import { Memory } from './dialects/memory.js';
+import { MySQL } from './dialects/mysql.js';
+import { PG } from './dialects/pg.js';
+import { Redis } from './dialects/redis.js';
+import { Sqlite } from './dialects/sqlite.js';
+import { MongoDB } from './dialects/mongodb.js';
+/** Root-entry initialization only; vendor clients are still loaded on connect. */
+export function registerBuiltinDatabases() {
+    Registry.register('memory', Memory);
+    Registry.register('mysql', MySQL);
+    Registry.register('pg', PG);
+    Registry.register('redis', Redis);
+    Registry.register('sqlite', Sqlite);
+    Registry.register('mongodb', MongoDB);
+}

package/lib/dialects/memory.js

@@ -1,6 +1,5 @@
 import { Dialect } from '../base/index.js';
 import { RelatedDatabase } from "../type/related/database.js";
-import { Registry } from "../registry.js";
 function readSqlIdentifier(sql, start) {
     let i = start;
     while (i < sql.length && /\s/.test(sql[i]))
@@ -831,4 +830,3 @@ export class Memory extends RelatedDatabase {
         super(new MemoryDialect(config), definitions);
     }
 }
-Registry.register('memory', Memory);

package/lib/dialects/mongodb.d.ts

@@ -87,3 +87,13 @@ export declare class MongoDBDialect<S extends Record<string, object> = Record<st
 export declare class MongoDB<S extends Record<string, object> = Record<string, object>> extends DocumentDatabase<MongoDBDialectConfig, S> {
     constructor(config: MongoDBDialectConfig, definitions?: Database.DefinitionObj<S>);
 }
+declare module '../registry.js' {
+    interface Databases<S extends Record<string, object> = Record<string, object>> {
+        mongodb: MongoDB<S>;
+    }
+    namespace Registry {
+        interface Config {
+            mongodb: MongoDBDialectConfig;
+        }
+    }
+}

package/lib/dialects/mongodb.js

@@ -1,6 +1,5 @@
 import { Dialect } from '../base/index.js';
 import { DocumentDatabase } from "../type/document/database.js";
-import { Registry } from "../registry.js";
 import { getLogger } from '@zhin.js/logger';
 const logger = getLogger('database');
 export class MongoDBDialect extends Dialect {
@@ -482,4 +481,3 @@ export class MongoDB extends DocumentDatabase {
         super(new MongoDBDialect(config), definitions);
     }
 }
-Registry.register('mongodb', MongoDB);

package/lib/dialects/mysql.d.ts

@@ -66,3 +66,13 @@ export declare class MySQL<S extends Record<string, object> = Record<string, obj
     constructor(config: MySQLDialectConfig, definitions?: Database.DefinitionObj<S>);
     protected initialize(): Promise<void>;
 }
+declare module '../registry.js' {
+    interface Databases<S extends Record<string, object> = Record<string, object>> {
+        mysql: MySQL<S>;
+    }
+    namespace Registry {
+        interface Config {
+            mysql: MySQLDialectConfig;
+        }
+    }
+}

package/lib/dialects/mysql.js

@@ -1,6 +1,5 @@
 import { Dialect } from '../base/index.js';
 import { RelatedDatabase } from "../type/related/database.js";
-import { Registry } from "../registry.js";
 import { getLogger } from '@zhin.js/logger';
 const logger = getLogger('database');
 export class MySQLDialect extends Dialect {
@@ -352,4 +351,3 @@ export class MySQL extends RelatedDatabase {
         await super.initialize();
     }
 }
-Registry.register('mysql', MySQL);

package/lib/dialects/pg.d.ts

@@ -60,3 +60,13 @@ export declare class PostgreSQLDialect<S extends Record<string, object> = Record
 export declare class PG<S extends Record<string, object> = Record<string, object>> extends RelatedDatabase<PostgreSQLDialectConfig, S> {
     constructor(config: PostgreSQLDialectConfig, definitions?: Database.DefinitionObj<S>);
 }
+declare module '../registry.js' {
+    interface Databases<S extends Record<string, object> = Record<string, object>> {
+        pg: PG<S>;
+    }
+    namespace Registry {
+        interface Config {
+            pg: PostgreSQLDialectConfig;
+        }
+    }
+}

package/lib/dialects/pg.js

@@ -1,6 +1,5 @@
 import { Dialect } from '../base/index.js';
 import { RelatedDatabase } from "../type/related/database.js";
-import { Registry } from "../registry.js";
 import { getLogger } from '@zhin.js/logger';
 const logger = getLogger('database');
 export class PostgreSQLDialect extends Dialect {
@@ -175,7 +174,7 @@ export class PostgreSQLDialect extends Dialect {
     }
     formatColumnDefinition(field, column) {
         const name = this.quoteIdentifier(String(field));
-        const type = this.mapColumnType(column.type);
+        const type = column.type === 'text' && column.length ? 'VARCHAR' : this.mapColumnType(column.type);
         const length = column.length ? `(${column.length})` : '';
         const nullable = column.nullable === false ? ' NOT NULL' : '';
         const primary = column.primary ? ' PRIMARY KEY' : '';
@@ -307,4 +306,3 @@ export class PG extends RelatedDatabase {
         super(new PostgreSQLDialect(config), definitions);
     }
 }
-Registry.register('pg', PG);

package/lib/dialects/redis.d.ts

@@ -88,3 +88,13 @@ export declare class RedisDialect<S extends Record<string, object> = Record<stri
 export declare class Redis<S extends Record<string, object> = Record<string, object>> extends KeyValueDatabase<RedisDialectConfig, S> {
     constructor(config: RedisDialectConfig, definitions?: Database.DefinitionObj<S>);
 }
+declare module '../registry.js' {
+    interface Databases<S extends Record<string, object> = Record<string, object>> {
+        redis: Redis<S>;
+    }
+    namespace Registry {
+        interface Config {
+            redis: RedisDialectConfig;
+        }
+    }
+}

package/lib/dialects/redis.js

@@ -1,6 +1,5 @@
 import { Dialect } from '../base/index.js';
 import { KeyValueDatabase } from "../type/keyvalue/database.js";
-import { Registry } from "../registry.js";
 import { getLogger } from '@zhin.js/logger';
 const logger = getLogger('database');
 export class RedisDialect extends Dialect {
@@ -502,4 +501,3 @@ export class Redis extends KeyValueDatabase {
         super(new RedisDialect(config), definitions);
     }
 }
-Registry.register('redis', Redis);

package/lib/dialects/sqlite.d.ts

@@ -16,27 +16,15 @@ export declare class SQLiteDialect<S extends Record<string, object> = Record<str
     /** node:sqlite 仅支持 number/string/bigint/buffer/null；JSON 列在库内为 TEXT，对象需序列化 */
     private prepareBindParams;
     query<U = any>(sql: string, params?: any[]): Promise<U>;
-    /** 声明为 json 的列名集合（由 Database 层注册表结构时填充），读路径仅对这些列做 JSON 反序列化 */
+    /** Column declarations are scoped to the table in this database, never the result alias. */
     private readonly jsonColumns;
-    /**
-     * 注册表的列声明类型，用于读路径按声明类型反序列化（避免对 TEXT 列做启发式 JSON 解析破坏往返）
-     */
     registerTableSchema(table: string, definition: Record<string, {
         type: string;
     }>): void;
-    /**
-     * 处理查询结果，按列声明类型反序列化（json 列）
-     */
+    /** node:sqlite columns() is available since Node 22.16. It preserves table/column
+     * provenance through aliases and joins; expression results have no origin. */
     private processQueryResults;
-    /**
-     * 处理单行数据
-     */
     private processRowData;
-    /**
-     * 处理字段值：仅对声明为 json 的列做 JSON 反序列化；
-     * 普通 TEXT 列原样返回，保证写入什么读出什么（不剥离引号、不启发式 JSON.parse）
-     */
-    private processFieldValue;
     dispose(): Promise<void>;
     mapColumnType(type: string): string;
     quoteIdentifier(identifier: string): string;

package/lib/dialects/sqlite.js

@@ -1,7 +1,6 @@
 import * as fs from 'node:fs';
 import path from 'node:path';
 import { Dialect } from '../base/index.js';
-import { Registry } from '../registry.js';
 import { RelatedDatabase } from '../type/related/database.js';
 export class SQLiteDialect extends Dialect {
     /** Node 内置 SQLite 连接（node:sqlite），在 connect() 中动态加载 */
@@ -82,62 +81,43 @@ export class SQLiteDialect extends Dialect {
         // SELECT / WITH / PRAGMA / DDL / 带 RETURNING 的 DML：按可能有结果集处理。
         // node:sqlite 的 all() 对无结果集语句返回空数组，不会抛错。
         const rows = stmt.all(...args);
-        return this.processQueryResults(rows);
+        return this.processQueryResults(rows, stmt.columns());
     }
-    /** 声明为 json 的列名集合（由 Database 层注册表结构时填充），读路径仅对这些列做 JSON 反序列化 */
-    jsonColumns = new Set();
-    /**
-     * 注册表的列声明类型，用于读路径按声明类型反序列化（避免对 TEXT 列做启发式 JSON 解析破坏往返）
-     */
+    /** Column declarations are scoped to the table in this database, never the result alias. */
+    jsonColumns = new Map();
     registerTableSchema(table, definition) {
-        for (const [columnName, column] of Object.entries(definition)) {
-            if (column && column.type === 'json') {
-                this.jsonColumns.add(columnName);
-            }
+        this.jsonColumns.set(table, new Set(Object.entries(definition)
+            .filter(([, column]) => column?.type === 'json').map(([name]) => name)));
+    }
+    /** node:sqlite columns() is available since Node 22.16. It preserves table/column
+     * provenance through aliases and joins; expression results have no origin. */
+    processQueryResults(data, columns) {
+        const decoded = new Set();
+        for (const column of columns) {
+            // Registered model definitions describe the main database. Attached tables
+            // with the same name do not inherit their schema.
+            if (column.database === 'main' && column.table && column.column
+                && this.jsonColumns.get(column.table)?.has(column.column))
+                decoded.add(column.name);
+            else
+                decoded.delete(column.name);
         }
+        return Array.isArray(data) ? data.map(row => this.processRowData(row, decoded)) : data;
     }
-    /**
-     * 处理查询结果，按列声明类型反序列化（json 列）
-     */
-    processQueryResults(data) {
-        if (!data)
-            return data;
-        if (Array.isArray(data)) {
-            return data.map(row => this.processRowData(row));
-        }
-        else if (typeof data === 'object') {
-            return this.processRowData(data);
-        }
-        return data;
-    }
-    /**
-     * 处理单行数据
-     */
-    processRowData(row) {
+    processRowData(row, decoded) {
         if (!row || typeof row !== 'object')
             return row;
-        const processedRow = {};
+        const result = {};
         for (const [key, value] of Object.entries(row)) {
-            processedRow[key] = this.processFieldValue(key, value);
-        }
-        return processedRow;
-    }
-    /**
-     * 处理字段值：仅对声明为 json 的列做 JSON 反序列化；
-     * 普通 TEXT 列原样返回，保证写入什么读出什么（不剥离引号、不启发式 JSON.parse）
-     */
-    processFieldValue(key, value) {
-        if (typeof value !== 'string')
-            return value;
-        if (!this.jsonColumns.has(key))
-            return value;
-        try {
-            return JSON.parse(value);
-        }
-        catch {
-            // 解析失败，返回原始字符串
-            return value;
+            result[key] = value;
+            if (decoded.has(key) && typeof value === 'string') {
+                try {
+                    result[key] = JSON.parse(value);
+                }
+                catch { /* Preserve invalid JSON exactly as before. */ }
+            }
         }
+        return result;
     }
     async dispose() {
         if (this.db) {
@@ -274,4 +254,3 @@ export class Sqlite extends RelatedDatabase {
         super(new SQLiteDialect(config), definitions);
     }
 }
-Registry.register('sqlite', Sqlite);

package/lib/index.d.ts

@@ -10,9 +10,6 @@ export * from './type/keyvalue/database.js';
 export * from './type/keyvalue/model.js';
 export * from './registry.js';
 export * from './dialects/memory.js';
-export * from './dialects/mysql.js';
-export * from './dialects/pg.js';
-export * from './dialects/redis.js';
 export * from './dialects/sqlite.js';
-export * from './dialects/mongodb.js';
 export * from './migration.js';
+export * from './structured-schema.js';

package/lib/index.js

@@ -10,9 +10,8 @@ export * from './type/keyvalue/database.js';
 export * from './type/keyvalue/model.js';
 export * from './registry.js';
 export * from './dialects/memory.js';
-export * from './dialects/mysql.js';
-export * from './dialects/pg.js';
-export * from './dialects/redis.js';
 export * from './dialects/sqlite.js';
-export * from './dialects/mongodb.js';
 export * from './migration.js';
+export * from './structured-schema.js';
+import { registerBuiltinDatabases } from './builtin-runtime.js';
+registerBuiltinDatabases();

package/lib/registry.d.ts

@@ -1,20 +1,12 @@
-import { Database } from './base/database.js';
-import { Memory } from './dialects/memory.js';
-import { MongoDB } from './dialects/mongodb.js';
-import { MySQL } from "./dialects/mysql.js";
-import { PG } from "./dialects/pg.js";
-import { Redis } from "./dialects/redis.js";
-import { Sqlite } from "./dialects/sqlite.js";
+import type { Database } from './base/database.js';
+import type { Memory, MemoryConfig } from './dialects/memory.js';
+import type { Sqlite, SQLiteDialectConfig } from './dialects/sqlite.js';
 /**
  * 数据库注册表接口
  * 支持模块声明扩展
  */
 export interface Databases<S extends Record<string, object> = Record<string, object>> {
     memory: Memory<S>;
-    mongodb: MongoDB<S>;
-    mysql: MySQL<S>;
-    pg: PG<S>;
-    redis: Redis<S>;
     sqlite: Sqlite<S>;
 }
 /**
@@ -26,12 +18,8 @@ export type Factory<D, S extends Record<string, object>, R extends Database<D, S
 export declare namespace Registry {
     const factories: Map<string, Factory<any, any, any>>;
     interface Config {
-        memory: import('./dialects/memory.js').MemoryConfig;
-        mongodb: import('./dialects/mongodb.js').MongoDBDialectConfig;
-        mysql: import('./dialects/mysql.js').MySQLDialectConfig;
-        pg: import('./dialects/pg.js').PostgreSQLDialectConfig;
-        redis: import('./dialects/redis.js').RedisDialectConfig;
-        sqlite: import('./dialects/sqlite.js').SQLiteDialectConfig;
+        memory: MemoryConfig;
+        sqlite: SQLiteDialectConfig;
     }
     type DatabaseType = 'related' | 'document' | 'keyvalue';
     function register<S extends Record<string, object>, D extends keyof Databases<S>>(dialect: D, factory: Factory<Config[D], S, any>): void;

package/lib/structured-schema.d.ts

@@ -0,0 +1,10 @@
+import type { Database } from './base/database.js';
+export type StructuredDatabase = Database<unknown, Record<string, Record<string, unknown>>, string>;
+import type { Column } from './types.js';
+/** Explicit additive migrations for a declared table; never removes old columns/data. */
+export declare function ensureDatabaseColumns(database: StructuredDatabase, table: string, columns: Record<string, Column>): Promise<void>;
+/** Index migration with exact identifier quoting; MySQL TEXT needs a bounded prefix. */
+export declare function ensureDatabaseIndex(database: StructuredDatabase, table: string, name: string, columns: readonly {
+    name: string;
+    text?: boolean;
+}[]): Promise<void>;

package/lib/structured-schema.js

@@ -0,0 +1,32 @@
+/** Explicit additive migrations for a declared table; never removes old columns/data. */
+export async function ensureDatabaseColumns(database, table, columns) {
+    const dialect = database.dialectName;
+    if (!['sqlite', 'mysql', 'pg'].includes(dialect))
+        return;
+    const quote = (name) => dialect === 'mysql' ? `\`${name.replaceAll('`', '``')}\`` : `"${name.replaceAll('"', '""')}"`;
+    const rows = dialect === 'sqlite'
+        ? await database.query(`PRAGMA table_info(${quote(table)})`)
+        : dialect === 'mysql' ? await database.query(`SHOW COLUMNS FROM ${quote(table)}`)
+            : await database.query('SELECT column_name FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = $1', [table]);
+    if (!rows.length)
+        throw new Error(`Cannot migrate missing table '${table}'`);
+    const existing = new Set(rows.map(row => String(row.name ?? row.Field ?? row.column_name)));
+    for (const [name, definition] of Object.entries(columns)) {
+        if (!existing.has(name))
+            await database.alter(table, { [name]: { action: 'add', ...definition } });
+    }
+}
+/** Index migration with exact identifier quoting; MySQL TEXT needs a bounded prefix. */
+export async function ensureDatabaseIndex(database, table, name, columns) {
+    const dialect = database.dialectName;
+    if (!['sqlite', 'mysql', 'pg'].includes(dialect))
+        return;
+    const quote = (value) => dialect === 'mysql' ? `\`${value.replaceAll('`', '``')}\`` : `"${value.replaceAll('"', '""')}"`;
+    if (dialect === 'mysql') {
+        const rows = await database.query(`SHOW INDEX FROM ${quote(table)} WHERE Key_name = ?`, [name]);
+        if (rows.length)
+            return;
+    }
+    const fields = columns.map(column => quote(column.name) + (dialect === 'mysql' && column.text ? '(128)' : '')).join(', ');
+    await database.query(`CREATE INDEX ${dialect === 'mysql' ? '' : 'IF NOT EXISTS '}${quote(name)} ON ${quote(table)} (${fields})`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/database",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Universal database abstraction layer for Zhin.js - supports SQLite, MySQL, PostgreSQL, MongoDB, Redis",
   "type": "module",
   "main": "./lib/index.js",
@@ -10,6 +10,31 @@
       "types": "./lib/index.d.ts",
       "import": "./lib/index.js",
       "require": "./lib/index.js"
+    },
+    "./registry": {
+      "types": "./lib/registry.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.js"
+    },
+    "./dialects/mysql": {
+      "types": "./lib/dialects/mysql.d.ts",
+      "import": "./lib/dialects/mysql.js",
+      "require": "./lib/dialects/mysql.js"
+    },
+    "./dialects/pg": {
+      "types": "./lib/dialects/pg.d.ts",
+      "import": "./lib/dialects/pg.js",
+      "require": "./lib/dialects/pg.js"
+    },
+    "./dialects/mongodb": {
+      "types": "./lib/dialects/mongodb.d.ts",
+      "import": "./lib/dialects/mongodb.js",
+      "require": "./lib/dialects/mongodb.js"
+    },
+    "./dialects/redis": {
+      "types": "./lib/dialects/redis.d.ts",
+      "import": "./lib/dialects/redis.js",
+      "require": "./lib/dialects/redis.js"
     }
   },
   "files": [