jsql-neo 4.2.0 → 4.4.0

package/index.d.ts

@@ -0,0 +1,351 @@
+/**
+ * JSQL-NEO — Rust-powered embedded database (Native / WASM / Pure JS)
+ * with a MySQL-compatible server mode.
+ */
+
+declare namespace JSQLNeo {
+  export type FieldType =
+    | 'string' | 'text' | 'varchar'
+    | 'integer' | 'int' | 'bigint'
+    | 'float' | 'double' | 'number'
+    | 'boolean'
+    | 'date' | 'datetime' | 'timestamp'
+    | 'object' | 'json' | 'array'
+    | 'any' | 'binary';
+
+  export interface FieldDef {
+    type: FieldType;
+    primaryKey?: boolean;
+    autoIncrement?: boolean;
+    unique?: boolean;
+    required?: boolean;
+    nullable?: boolean;
+    length?: number;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+    default?: unknown;
+    check?: string;
+    ref?: string;
+    computed?: boolean;
+  }
+
+  export type Schema = Record<string, FieldDef>;
+
+  export interface Row {
+    id: number | string;
+    fields?: Record<string, unknown>;
+    created_at?: string;
+    updated_at?: string;
+    [key: string]: unknown;
+  }
+
+  export interface FindOptions {
+    limit?: number;
+    offset?: number;
+  }
+
+  export interface JSQLOptions {
+    dataDir?: string;
+    flushThreshold?: number;
+    modules?: boolean;
+    persistence?: boolean;
+    dbName?: string;
+  }
+
+  export type JSQLHook =
+    | 'beforeInsert' | 'afterInsert'
+    | 'beforeUpdate' | 'afterUpdate'
+    | 'beforeDelete' | 'afterDelete'
+    | 'beforeFind' | 'afterFind'
+    | 'beforeCreateTable' | 'afterCreateTable'
+    | 'beforeDropTable' | 'afterDropTable'
+    | 'beforeFlush' | 'afterFlush'
+    | 'beforeCount' | 'afterCount'
+    | 'onStart' | 'onStop';
+
+  export interface JSQLPlugin {
+    name?: string;
+    install?(db: JSQL, ctx: PluginContext): void;
+    onEvent?(event: string, data: unknown): void;
+    hooks?: Partial<Record<JSQLHook, (...args: any[]) => unknown>>;
+  }
+
+  export interface PluginContext {
+    name: string;
+    engine: JSQL;
+    plugin: JSQLPlugin;
+    on(hook: JSQLHook, fn: (...args: any[]) => unknown): JSQL;
+    onEvent(fn: (event: string, data: unknown) => void): JSQL;
+    emit(eventName: string, data: unknown): void;
+    tables(): string[];
+    hasTable(name: string): boolean;
+    getTableSchema(name: string): Schema | null;
+  }
+
+  export class JSQL {
+    constructor(opts?: JSQLOptions);
+    use(plugin: JSQLPlugin | ((db: JSQL) => void)): this;
+    on(event: JSQLHook, fn: (...args: any[]) => unknown): this;
+    onEvent(fn: (event: string, data: unknown) => void): this;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    flush(): Promise<void>;
+    createTable(name: string, schema: Schema): Promise<unknown>;
+    dropTable(name: string): Promise<unknown>;
+    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<unknown>;
+    insertMany(table: string, data: Record<string, unknown>[]): Promise<unknown>;
+    findById(table: string, id: number | string | bigint): Promise<Row | null>;
+    findByIds(table: string, ids: Array<number | string>): Promise<Row[] | null>;
+    find(table: string, filter?: Record<string, unknown>, opts?: FindOptions): Promise<Row[]>;
+    count(table: string): Promise<number>;
+    updateById(table: string, id: number | string, data: Record<string, unknown>): Promise<unknown>;
+    updateByIds(table: string, entries: Array<[number | string, Record<string, unknown>]>): Promise<unknown>;
+    removeById(table: string, id: number | string): Promise<unknown>;
+    removeByIds(table: string, ids: Array<number | string>): Promise<unknown>;
+    hasTable(name: string): Promise<boolean>;
+    getTables(): Promise<string[]>;
+    getTableSchema(name: string): Promise<Schema | null>;
+  }
+
+  export class NativeJSQL extends JSQL {}
+
+  export interface MysqlServerOptions {
+    port?: number;
+    host?: string;
+    dataDir?: string;
+    defaultDatabase?: string;
+    noAuth?: boolean;
+    auth?: Record<string, string>;
+    allowComments?: boolean;
+    safety?: boolean;
+    maxConnections?: number;
+    handshakeTimeout?: number;
+    maxAuthFails?: number;
+  }
+
+  export class MysqlServer {
+    constructor(options?: MysqlServerOptions);
+    listen(cb?: (err?: Error) => void): this;
+    close(cb?: () => void): void;
+    readonly address: { port: number; address: string; family: string } | null;
+    listDatabases(): Promise<string[]>;
+    createDatabase(name: string, opts?: { ifNotExists?: boolean }): Promise<void>;
+    dropDatabase(name: string, opts?: { ifExists?: boolean }): Promise<void>;
+  }
+
+  export function createMysqlServer(options?: MysqlServerOptions): MysqlServer;
+
+  export interface RedisServerOptions {
+    port?: number;
+    host?: string;
+    password?: string | null;
+    dataDir?: string | null;
+    onQuery?: (cmd: string, args: string[]) => void;
+  }
+
+  export class RedisServer {
+    constructor(options?: RedisServerOptions);
+    listen(): this;
+    stop(): void;
+    execute(cmd: string, args: string[]): string | number | string[] | null | 'OK' | 'PONG';
+  }
+
+  export function createRedisServer(options?: RedisServerOptions): RedisServer;
+
+  export interface WebUIOptions {
+    port?: number;
+    host?: string;
+    dataDir?: string;
+    readonly?: boolean;
+  }
+
+  export class WebUI {
+    constructor(options?: WebUIOptions);
+    start(): Promise<number>;
+    stop(): Promise<void>;
+    listDatabases(): { name: string; tables: number }[];
+  }
+
+  export interface MigrateResult {
+    created?: string[];
+    inserted?: number;
+    errors?: { line?: number; error: string }[];
+  }
+
+  export interface MigrateTools {
+    normalizeSchema(schema: Record<string, unknown>): Record<string, unknown>;
+    parseCSV(text: string): string[][];
+    toCSV(rows: Record<string, unknown>[], columns?: string[]): string;
+    exportTableToJSON(db: unknown, table: string): { schema: unknown; rows: unknown[] };
+    exportAllToJSON(db: unknown): Record<string, unknown>;
+    importFromJSON(db: unknown, data: Record<string, unknown>): Promise<MigrateResult>;
+    exportTableToCSV(db: unknown, table: string): string;
+    importFromCSV(db: unknown, table: string, csv: string, opts?: { schema?: unknown }): Promise<MigrateResult>;
+    importDump(db: unknown, sql: string, opts?: { strict?: boolean }): Promise<MigrateResult>;
+    importDumpFile(db: unknown, file: string, opts?: { strict?: boolean }): Promise<MigrateResult>;
+    exportToFile(db: unknown, table: string, outFile: string): Promise<number>;
+  }
+
+  export const migrate: MigrateTools;
+  export function exportTableToJSON(db: unknown, table: string): { schema: unknown; rows: unknown[] };
+  export function exportAllToJSON(db: unknown): Record<string, unknown>;
+  export function importFromJSON(db: unknown, data: Record<string, unknown>): Promise<MigrateResult>;
+  export function exportTableToCSV(db: unknown, table: string): string;
+  export function importFromCSV(db: unknown, table: string, csv: string, opts?: { schema?: unknown }): Promise<MigrateResult>;
+  export function importDump(db: unknown, sql: string, opts?: { strict?: boolean }): Promise<MigrateResult>;
+  export function importDumpFile(db: unknown, file: string, opts?: { strict?: boolean }): Promise<MigrateResult>;
+  export function exportToFile(db: unknown, table: string, outFile: string): Promise<number>;
+
+  export interface ConnectionOptions {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+  }
+
+  export interface ConnectionResult {
+    insertId: number | null;
+    affectedRows: number;
+    rows: unknown[];
+    fields?: unknown[];
+  }
+
+  export class Connection {
+    constructor(options?: ConnectionOptions);
+    connect(cb?: (err?: Error) => void): void;
+    query(sql: string, params?: unknown[], cb?: (err: Error | null, result: ConnectionResult) => void): void;
+    execute(sql: string, params?: unknown[], cb?: (err: Error | null, result: ConnectionResult) => void): void;
+    beginTransaction(cb?: (err?: Error) => void): void;
+    commit(cb?: (err?: Error) => void): void;
+    rollback(cb?: (err?: Error) => void): void;
+    end(): void;
+    format(sql: string, params?: unknown[]): string;
+    escape(value: unknown): string;
+    escapeId(value: string): string;
+  }
+
+  export class Pool {
+    constructor(options?: ConnectionOptions & { max?: number });
+    query(sql: string, params?: unknown[], cb?: (err: Error | null, result: ConnectionResult) => void): void;
+    getConnection(cb: (err: Error | null, conn: Connection) => void): void;
+    end(): void;
+  }
+
+  export function createConnection(options?: ConnectionOptions): Connection;
+  export function createPool(options?: ConnectionOptions & { max?: number }): Pool;
+
+  export interface SQLResult {
+    ok: boolean;
+    type: string;
+    table?: string | null;
+    columns?: string[];
+    rows?: unknown[][];
+    raw?: unknown[];
+    affectedRows?: number;
+    insertId?: number | null;
+    ids?: unknown[];
+    error?: string;
+  }
+
+  export interface SQLOptions {
+    allowComments?: boolean;
+    safety?: boolean;
+    maxStatements?: number;
+    session?: Record<string, unknown>;
+  }
+
+  export function executeSQL(engine: unknown, sql: string, paramsOrOpts?: unknown[] | SQLOptions, opts?: SQLOptions): Promise<SQLResult>;
+  export function parseSQL(sql: string): unknown;
+  export function splitStatements(sql: string): string[];
+  export function applyParams(sql: string, values: unknown[]): string;
+  export function escapeValue(value: unknown): string;
+  export function escapeId(value: string): string;
+
+  export interface DatabaseOptions {
+    dataDir?: string;
+    persist?: boolean;
+    inMemoryOnly?: boolean;
+  }
+
+  export class Database {
+    constructor(options?: DatabaseOptions);
+    createTable(name: string, schema: Schema): Promise<unknown>;
+    insert(table: string, data: Record<string, unknown>): Promise<unknown>;
+    find(table: string, filter?: Record<string, unknown>): Promise<Row[]>;
+    update(table: string, filter: Record<string, unknown>, data: Record<string, unknown>): Promise<number>;
+    remove(table: string, filter: Record<string, unknown>): Promise<number>;
+    findOne(table: string, filter?: Record<string, unknown>): Promise<Row | null>;
+    count(table: string): Promise<number>;
+    getTables(): Promise<string[]>;
+    dropTable(name: string): Promise<void>;
+    getTableSchema(name: string): Promise<Schema | null>;
+  }
+
+  export class Table {
+    constructor(name: string, schema: Schema, db?: unknown);
+    insert(data: Record<string, unknown>): Promise<unknown>;
+    find(filter?: Record<string, unknown>): Promise<Row[]>;
+    updateById(id: number | string, data: Record<string, unknown>): Promise<unknown>;
+    removeById(id: number | string): Promise<unknown>;
+    count(): Promise<number>;
+  }
+
+  export class Query {
+    constructor(table: unknown);
+    exec(): Promise<Row[]>;
+    then(resolve: (rows: Row[]) => unknown, reject?: (err: Error) => unknown): Promise<unknown>;
+  }
+
+  export class BTree {
+    constructor(order?: number);
+    insert(key: unknown, value: unknown): void;
+    find(key: unknown): unknown;
+    range(min: unknown, max: unknown): unknown[];
+  }
+
+  export class Cache {
+    constructor(options?: Record<string, unknown>);
+    get(key: string): unknown;
+    set(key: string, value: unknown, ttlMs?: number): void;
+    del(key: string): void;
+    flush(): void;
+    close(): void;
+  }
+
+  export class Plugin {
+    static create(plugin: JSQLPlugin): JSQLPlugin;
+  }
+
+  export class ModuleManager {
+    constructor(opts?: { cwd?: string });
+    applyTo(engine: JSQL): void;
+  }
+
+  export class JSQL_Error extends Error {
+    code: number;
+    codeKey: string;
+    args: unknown[];
+  }
+
+  export const ErrorCodes: Record<string, { code: number; msg: string }>;
+
+  export class JSQLFormat {
+    constructor(db: unknown);
+    dump(): string;
+    load(dump: string): void;
+  }
+
+  export class Datastore {
+    constructor(options?: DatabaseOptions);
+    insert(docs: unknown): Promise<unknown>;
+    find(query?: unknown): Promise<unknown[]>;
+    update(query: unknown, update: unknown): Promise<number>;
+    remove(query: unknown): Promise<number>;
+    loadDatabase(): Promise<void>;
+    persistence: { persistCachedDatabase: (cb?: (err?: Error) => void) => void };
+  }
+}
+
+export = JSQLNeo;

package/index.js

@@ -19,6 +19,9 @@ const sql = require('./lib/sql');
 const { Datastore } = require('./lib/nedb_compat');
 const mysqlCompat = require('./lib/mysql_compat');
 const { createMysqlServer, MysqlServer } = require('./lib/mysql_server');
+const migrate = require('./lib/migrate');
+const { WebUI } = require('./lib/web_ui');
+const { RedisServer, createRedisServer } = require('./lib/redis_server');
 
 module.exports = {
     JSQL: WasmClient.JSQL,
@@ -44,4 +47,19 @@ module.exports = {
     mysql: mysqlCompat,
     createMysqlServer,
     MysqlServer,
+    // 迁移工具: mysqldump 导入 / JSON / CSV
+    migrate,
+    exportTableToJSON: migrate.exportTableToJSON,
+    exportAllToJSON: migrate.exportAllToJSON,
+    importFromJSON: migrate.importFromJSON,
+    exportTableToCSV: migrate.exportTableToCSV,
+    importFromCSV: migrate.importFromCSV,
+    importDump: migrate.importDump,
+    importDumpFile: migrate.importDumpFile,
+    exportToFile: migrate.exportToFile,
+    // Web UI
+    WebUI,
+    // Redis 兼容服务器
+    RedisServer,
+    createRedisServer,
 };

package/lib/migrate.js

@@ -0,0 +1,242 @@
+/*
+ * Migration tools: mysqldump import, JSON import/export, CSV import/export.
+ *
+ * Works against any engine exposing:
+ *   hasTable(name) / getTableSchema(name) / find(name, {}, {limit, offset})
+ *   createTable(name, schema) / insert(name, rows) / executeSQL(sql, ...)
+ * (Database instances and the jsql-neo MySQL server engine both qualify.)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { splitStatements, executeSQL } = require('./sql');
+
+function normalizeSchema(schema) {
+  const out = {};
+  for (const [name, def] of Object.entries(schema || {})) {
+    const d = typeof def === 'string' ? { type: def } : { ...def };
+    if (!d.type) d.type = typeof d === 'object' ? 'any' : 'string';
+    if (d.type === 'int' || d.type === 'bigint' || d.type === 'smallint' || d.type === 'tinyint') d.type = 'integer';
+    if (d.type === 'varchar' || d.type === 'text' || d.type === 'char') d.type = 'string';
+    if (d.type === 'double' || d.type === 'real' || d.type === 'decimal' || d.type === 'numeric') d.type = 'float';
+    if (d.type === 'bool') d.type = 'boolean';
+    delete d.length;
+    if (d.maxLength) { d.length = d.maxLength; delete d.maxLength; }
+    out[name] = d;
+  }
+  return out;
+}
+
+function serializeValue(v) {
+  if (v === null || v === undefined) return '';
+  if (v instanceof Date) return v.toISOString();
+  if (typeof v === 'object') return JSON.stringify(v);
+  return String(v);
+}
+
+function parseValue(str, type) {
+  if (str === '' || str === null || str === undefined) return null;
+  const t = String(type || 'string').toLowerCase();
+  if (t === 'integer') return Number.isFinite(Number(str)) ? Math.trunc(Number(str)) : str;
+  if (t === 'float' || t === 'number') return Number.isFinite(Number(str)) ? Number(str) : str;
+  if (t === 'boolean') {
+    const s = str.toLowerCase();
+    if (['1', 'true', 'yes', 'y'].includes(s)) return true;
+    if (['0', 'false', 'no', 'n'].includes(s)) return false;
+    return str;
+  }
+  if (t === 'object' || t === 'array') {
+    try { return JSON.parse(str); } catch (e) { return str; }
+  }
+  return str;
+}
+
+function parseCSV(text) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQuotes = false;
+  let i = 0;
+  const n = text.length;
+  while (i < n) {
+    const c = text[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (text[i + 1] === '"') { field += '"'; i += 2; continue; }
+        inQuotes = false;
+        i++;
+        continue;
+      }
+      field += c;
+      i++;
+      continue;
+    }
+    if (c === '"' && field === '') { inQuotes = true; i++; continue; }
+    if (c === ',') { row.push(field); field = ''; i++; continue; }
+    if (c === '\n' || c === '\r') {
+      if (c === '\r' && text[i + 1] === '\n') i++;
+      row.push(field);
+      field = '';
+      if (row.length > 1 || row[0] !== '') rows.push(row);
+      row = [];
+      i++;
+      continue;
+    }
+    field += c;
+    i++;
+  }
+  if (field !== '' || row.length > 0) {
+    row.push(field);
+    if (row.length > 1 || row[0] !== '') rows.push(row);
+  }
+  return rows;
+}
+
+function toCSV(rows, columns) {
+  const escape = (v) => {
+    const s = serializeValue(v);
+    return /[",\n\r]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
+  };
+  const lines = [columns.map(escape).join(',')];
+  for (const r of rows) {
+    lines.push(columns.map(c => escape(r[c])).join(','));
+  }
+  return lines.join('\n') + '\n';
+}
+
+/* ---------- JSON ---------- */
+
+async function exportTableToJSON(engine, table) {
+  const schema = await engine.getTableSchema(table);
+  if (!schema) throw new Error(`Table '${table}' does not exist`);
+  const rows = await engine.find(table, {}, { limit: 1e9, offset: 0 });
+  return { table, schema, rows };
+}
+
+async function exportAllToJSON(engine, tables) {
+  const list = tables || await engine.getTables();
+  const out = {};
+  for (const t of list) out[t] = await exportTableToJSON(engine, t);
+  return out;
+}
+
+async function importFromJSON(engine, data) {
+  const tables = typeof data === 'string' ? JSON.parse(data) : data;
+  const created = [];
+  let inserted = 0;
+  for (const [name, t] of Object.entries(tables)) {
+    if (!t || !t.schema) continue;
+    if (engine.hasTable(name)) await engine.dropTable(name);
+    await engine.createTable(name, normalizeSchema(t.schema));
+    created.push(name);
+    if (Array.isArray(t.rows) && t.rows.length > 0) {
+      const ids = await engine.insert(name, t.rows.map(r => ({ ...r.fields, id: r.id })));
+      inserted += Array.isArray(ids) ? ids.length : t.rows.length;
+    }
+  }
+  return { created, inserted };
+}
+
+/* ---------- CSV ---------- */
+
+async function exportTableToCSV(engine, table) {
+  const schema = await engine.getTableSchema(table);
+  if (!schema) throw new Error(`Table '${table}' does not exist`);
+  const columns = Object.keys(schema);
+  const rows = await engine.find(table, {}, { limit: 1e9, offset: 0 });
+  return toCSV(rows, columns);
+}
+
+async function importFromCSV(engine, table, csv, opts = {}) {
+  const schema = opts.schema || await engine.getTableSchema(table);
+  const rows = parseCSV(csv);
+  if (rows.length === 0) return { inserted: 0 };
+  let columns;
+  let start = 0;
+  if (opts.header !== false) {
+    columns = rows[0];
+    start = 1;
+  } else if (schema) {
+    columns = Object.keys(schema);
+  } else {
+    columns = rows[0].map((_, i) => 'col' + (i + 1));
+  }
+  if (!engine.hasTable(table)) {
+    if (!schema) {
+      throw new Error(`Table '${table}' does not exist; provide opts.schema to create it`);
+    }
+    await engine.createTable(table, normalizeSchema(schema));
+  }
+  const dataRows = [];
+  for (let i = start; i < rows.length; i++) {
+    const row = {};
+    for (let j = 0; j < columns.length; j++) {
+      const type = schema && schema[columns[j]] ? schema[columns[j]].type : 'string';
+      row[columns[j]] = parseValue(rows[i][j], type);
+    }
+    if (row.id === null || row.id === undefined || row.id === '') delete row.id;
+    dataRows.push(row);
+  }
+  const ids = dataRows.length > 0 ? await engine.insert(table, dataRows) : [];
+  return { inserted: dataRows.length, ids };
+}
+
+/* ---------- mysqldump ---------- */
+
+async function importDump(engine, sqlText, opts = {}) {
+  const statements = splitStatements(sqlText);
+  const created = [];
+  let inserted = 0;
+  const errors = [];
+  for (const raw of statements) {
+    const stmt = raw.trim();
+    if (!stmt) continue;
+    if (stmt.startsWith('--') || stmt.startsWith('#')) continue;
+    const upper = stmt.toUpperCase();
+    if (upper.startsWith('LOCK ') || upper.startsWith('UNLOCK ')) continue;
+    if (upper.startsWith('/*!')) continue;
+    if (upper.startsWith('SET ') && opts.skipSet !== false) continue;
+    try {
+      const r = await executeSQL(engine, stmt, { safety: false });
+      if (r && r.type === 'createTable') created.push(r.table);
+      if (r && r.type === 'insert') inserted += (r.ids || []).length || r.affectedRows || 0;
+    } catch (e) {
+      if (opts.strict) throw e;
+      errors.push({ sql: stmt.slice(0, 120), error: e.message });
+    }
+  }
+  return { created, inserted, errors };
+}
+
+async function importDumpFile(engine, filePath, opts = {}) {
+  const text = fs.readFileSync(filePath, 'utf8');
+  return importDump(engine, text, opts);
+}
+
+async function exportToFile(engine, table, filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  let content;
+  if (ext === '.json') {
+    content = JSON.stringify(await exportTableToJSON(engine, table), null, 2);
+  } else if (ext === '.csv') {
+    content = await exportTableToCSV(engine, table);
+  } else {
+    throw new Error('Unsupported export format (use .json or .csv): ' + filePath);
+  }
+  fs.writeFileSync(filePath, content);
+  return content.length;
+}
+
+module.exports = {
+  normalizeSchema,
+  parseCSV,
+  toCSV,
+  exportTableToJSON,
+  exportAllToJSON,
+  importFromJSON,
+  exportTableToCSV,
+  importFromCSV,
+  importDump,
+  importDumpFile,
+  exportToFile,
+};