@zhin.js/database 1.1.5 → 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/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 {
@@ -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,10 +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,10 +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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/database",
-  "version": "1.1.5",
+  "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": [