@dbcube/core 5.1.13 → 5.2.1

package/dist/index.d.mts

@@ -2,21 +2,121 @@ import { EventEmitter } from 'events';
 
 export interface ResponseEngine {
 	status: number;
-	message: String;
+	message: string;
 	data: any;
 }
+/**
+ * Connection parameters for one database.
+ */
+export interface DatabaseConnectionConfig {
+	/** Host name or IP (not used by SQLite) */
+	HOST?: string;
+	/** Database user (not used by SQLite) */
+	USER?: string;
+	/** Database password (not used by SQLite) */
+	PASSWORD?: string;
+	/** Database name (SQLite: file name without extension) */
+	DATABASE: string;
+	/** Port (not used by SQLite) */
+	PORT?: number | string;
+}
+/**
+ * Connection-pool tuning. Every field is optional — engine defaults apply
+ * when omitted (maxConnections 5 — 10 for SQLite —, minConnections 2,
+ * acquireTimeoutMs 3000, idleTimeoutMs 3600000).
+ */
+export interface DatabasePoolConfig {
+	/** Max simultaneous connections held by the engine pool */
+	maxConnections?: number;
+	/** Connections kept warm even when idle */
+	minConnections?: number;
+	/** How long to wait for a free connection before failing (ms) */
+	acquireTimeoutMs?: number;
+	/** Close connections idle longer than this (ms) */
+	idleTimeoutMs?: number;
+}
+/**
+ * Daemon-mode tuning.
+ */
+export interface DatabaseDaemonConfig {
+	/** Set to false to disable the persistent TCP daemon (one-shot mode).
+	 *  Transactions require the daemon. Equivalent to DBCUBE_DAEMON=0. */
+	enabled?: boolean;
+	/** Per-request timeout against the daemon (ms, default 30000) */
+	requestTimeoutMs?: number;
+}
+export type DatabaseType = "mysql" | "postgres" | "postgresql" | "sqlite" | "mongodb";
+/**
+ * One database entry in dbcube.config.js.
+ */
+export interface DatabaseDefinition {
+	type: DatabaseType;
+	config: DatabaseConnectionConfig;
+	pool?: DatabasePoolConfig;
+	daemon?: DatabaseDaemonConfig;
+}
+/**
+ * Shape accepted by config.set().
+ */
+export interface ConfigData {
+	databases?: Record<string, DatabaseDefinition>;
+	[key: string]: unknown;
+}
+/**
+ * Clase para manejar la configuración del ORM
+ */
+export declare class Config {
+	private data;
+	private databases;
+	/**
+	 * Establece la configuración
+	 * @param configData - Datos de configuración
+	 */
+	set(configData: ConfigData): void;
+	/**
+	 * Obtiene un valor de configuración
+	 * @param key - Clave de configuración
+	 */
+	get<T = unknown>(key: string): T;
+	/**
+	 * Obtiene la configuración de una base de datos específica
+	 * @param dbName - Nombre de la base de datos
+	 */
+	getDatabase(dbName: string): DatabaseDefinition | null;
+	/**
+	 * Obtiene todas las bases de datos configuradas
+	 */
+	getAllDatabases(): Record<string, DatabaseDefinition>;
+}
 export declare class Engine {
 	private name;
 	private config;
 	private arguments;
 	private binary;
 	private timeout;
+	private daemonFailed;
 	constructor(name: string, timeout?: number);
 	initializeBinary(): Promise<void>;
+	/**
+	 * Returns a connected DaemonClient for this database, or null when
+	 * daemon mode is disabled/unavailable (then callers use spawn mode).
+	 */
+	private getDaemon;
+	/**
+	 * Executes a DML plan. Uses the persistent daemon (sub-millisecond
+	 * overhead) when available; falls back to one-shot spawn otherwise.
+	 */
+	executeDml(dml: object, txId?: string): Promise<ResponseEngine>;
+	/**
+	 * Executes raw SQL (or a MongoDB command document) with bound parameters.
+	 */
+	rawQuery(query: string, params?: any[], txId?: string): Promise<ResponseEngine>;
+	/** Starts a transaction (daemon mode only). Returns the transaction id. */
+	beginTransaction(): Promise<string>;
+	commitTransaction(txId: string): Promise<void>;
+	rollbackTransaction(txId: string): Promise<void>;
 	setArguments(): any[];
-	setConfig(name: string): {
-		[x: string]: any;
-	} | null;
+	setConfig(name: string): DatabaseDefinition | null;
 	getConfig(): any;
 	run(binary: string, args: [
 	]): Promise<ResponseEngine>;
@@ -35,11 +135,26 @@ export declare class QueryEngine {
 	private isPortAvailable;
 	initializeBinary(): Promise<void>;
 	setArguments(): any[];
-	setConfig(name: string): {
-		[x: string]: any;
-	} | null;
+	/** El daemon puede desactivarse por config (daemon.enabled=false) o por env (DBCUBE_DAEMON=0). */
+	private daemonEnabled;
+	setConfig(name: string): DatabaseDefinition | null;
 	getConfig(): any;
 	run(binary: string, args: string[]): Promise<ResponseEngine>;
+	private argsToCommand;
+	/**
+	 * Executes a DML plan over the persistent TCP server.
+	 * Pass txId to run it inside an active transaction.
+	 */
+	executeDml(dml: object, txId?: string): Promise<ResponseEngine>;
+	/**
+	 * Executes raw SQL (or a MongoDB command document) with bound parameters
+	 * over the persistent TCP server.
+	 */
+	rawQuery(query: string, params?: any[], txId?: string): Promise<ResponseEngine>;
+	/** Starts a server-side transaction and returns its id. */
+	beginTransaction(): Promise<string>;
+	commitTransaction(txId: string): Promise<void>;
+	rollbackTransaction(txId: string): Promise<void>;
 	private executeWithTcpServer;
 	private waitForServerReady;
 	private isServerResponding;
@@ -165,42 +280,63 @@ declare class SQLite {
 	convertToParameterizedQuery(sql: string): ParametrizedQueryResult;
 }
 export declare const DbConfig: SQLite;
-type DatabaseConfig$1 = Record<string, any>;
-/**
- * Tipo para la configuración general del ORM
- */
-export interface ConfigData {
-	[key: string]: any;
-	databases?: Record<string, DatabaseConfig$1>;
+export interface DaemonResponse {
+	status: number;
+	message: string;
+	data: any;
 }
 /**
- * Clase para manejar la configuración del ORM
+ * TCP client for the query-engine daemon (server mode).
+ *
+ * Instead of spawning a new engine process per query (30-80ms overhead),
+ * the daemon keeps the engine alive with warm connection pools and serves
+ * requests over a local TCP socket in <1ms. One daemon per database name.
  */
-export declare class Config {
-	private data;
-	private databases;
-	/**
-	 * Establece la configuración
-	 * @param configData - Datos de configuración
-	 */
-	set(configData: ConfigData): void;
+export declare class DaemonClient {
+	private static registry;
+	private name;
+	private binaryPath;
+	private engineArgs;
+	private socket;
+	private buffer;
+	private pending;
+	private starting;
+	private requestTimeout;
+	private constructor();
+	static get(name: string, binaryPath: string, engineArgs: string[]): DaemonClient;
+	static isEnabled(): boolean;
+	private portfilePath;
+	private lockfilePath;
 	/**
-	 * Obtiene un valor de configuración
-	 * @param key - Clave de configuración
-	 * @returns Valor de configuración
+	 * Exclusive-create lock so two processes never spawn two daemons for the
+	 * same database at once. Stale locks (crashed starter) expire after 15s.
 	 */
-	get<T = any>(key: string): T;
+	private acquireSpawnLock;
+	private releaseSpawnLock;
 	/**
-	 * Obtiene la configuración de una base de datos específica
-	 * @param dbName - Nombre de la base de datos
-	 * @returns Configuración de la base de datos o null
+	 * Ensures a usable daemon connection. Returns false when the daemon
+	 * can't be used (old binary, startup failure) so callers fall back
+	 * to one-shot spawn mode.
 	 */
-	getDatabase(dbName: string): DatabaseConfig$1 | null;
+	ensure(): Promise<boolean>;
+	private connectOrStart;
+	private readPortfile;
+	private spawnDaemon;
+	private tryConnect;
+	private attach;
+	private detach;
+	private onData;
 	/**
-	 * Obtiene todas las bases de datos configuradas
-	 * @returns Todas las configuraciones de bases de datos
+	 * Sends a request to the daemon. Responses arrive in FIFO order on the
+	 * single socket, so pending requests resolve in send order.
 	 */
-	getAllDatabases(): Record<string, DatabaseConfig$1>;
+	send(payload: Record<string, any>, timeoutMs?: number): Promise<DaemonResponse>;
+	execute(dml: object, txId?: string): Promise<DaemonResponse>;
+	raw(query: string, params?: any[], txId?: string): Promise<DaemonResponse>;
+	begin(): Promise<string>;
+	commit(txId: string): Promise<void>;
+	rollback(txId: string): Promise<void>;
+	shutdown(): Promise<void>;
 }
 export interface InterceptOptions {
 	interceptLog?: boolean;
@@ -335,7 +471,7 @@ export interface ComputedFieldConfig {
 	created_at: string;
 	updated_at: string;
 }
-export type DatabaseType = "mysql" | "sqlite" | "postgres" | "mongodb";
+type DatabaseType$1 = "mysql" | "sqlite" | "postgres" | "mongodb";
 export declare class ComputedFieldProcessor {
 	static getComputedFields(name: string): Promise<any[]>;
 	/**
@@ -360,7 +496,7 @@ export declare class ComputedFieldProcessor {
 	static computedFields<T extends DataObject>(data: T[], computedConfigs: ComputedFieldConfig[]): T[];
 }
 export declare class TableProcessor {
-	static generateAlterQueries(nowQuery: string, dbType: DatabaseType, tableName: string, database_ref: string): Promise<string[]>;
+	static generateAlterQueries(nowQuery: string, dbType: DatabaseType$1, tableName: string, database_ref: string): Promise<string[]>;
 	static saveQuery(table_ref: string, database_ref: string, struct: string): Promise<void>;
 }
 export declare class TriggerProcessor {

package/dist/index.d.ts

@@ -2,21 +2,121 @@ import { EventEmitter } from 'events';
 
 export interface ResponseEngine {
 	status: number;
-	message: String;
+	message: string;
 	data: any;
 }
+/**
+ * Connection parameters for one database.
+ */
+export interface DatabaseConnectionConfig {
+	/** Host name or IP (not used by SQLite) */
+	HOST?: string;
+	/** Database user (not used by SQLite) */
+	USER?: string;
+	/** Database password (not used by SQLite) */
+	PASSWORD?: string;
+	/** Database name (SQLite: file name without extension) */
+	DATABASE: string;
+	/** Port (not used by SQLite) */
+	PORT?: number | string;
+}
+/**
+ * Connection-pool tuning. Every field is optional — engine defaults apply
+ * when omitted (maxConnections 5 — 10 for SQLite —, minConnections 2,
+ * acquireTimeoutMs 3000, idleTimeoutMs 3600000).
+ */
+export interface DatabasePoolConfig {
+	/** Max simultaneous connections held by the engine pool */
+	maxConnections?: number;
+	/** Connections kept warm even when idle */
+	minConnections?: number;
+	/** How long to wait for a free connection before failing (ms) */
+	acquireTimeoutMs?: number;
+	/** Close connections idle longer than this (ms) */
+	idleTimeoutMs?: number;
+}
+/**
+ * Daemon-mode tuning.
+ */
+export interface DatabaseDaemonConfig {
+	/** Set to false to disable the persistent TCP daemon (one-shot mode).
+	 *  Transactions require the daemon. Equivalent to DBCUBE_DAEMON=0. */
+	enabled?: boolean;
+	/** Per-request timeout against the daemon (ms, default 30000) */
+	requestTimeoutMs?: number;
+}
+export type DatabaseType = "mysql" | "postgres" | "postgresql" | "sqlite" | "mongodb";
+/**
+ * One database entry in dbcube.config.js.
+ */
+export interface DatabaseDefinition {
+	type: DatabaseType;
+	config: DatabaseConnectionConfig;
+	pool?: DatabasePoolConfig;
+	daemon?: DatabaseDaemonConfig;
+}
+/**
+ * Shape accepted by config.set().
+ */
+export interface ConfigData {
+	databases?: Record<string, DatabaseDefinition>;
+	[key: string]: unknown;
+}
+/**
+ * Clase para manejar la configuración del ORM
+ */
+export declare class Config {
+	private data;
+	private databases;
+	/**
+	 * Establece la configuración
+	 * @param configData - Datos de configuración
+	 */
+	set(configData: ConfigData): void;
+	/**
+	 * Obtiene un valor de configuración
+	 * @param key - Clave de configuración
+	 */
+	get<T = unknown>(key: string): T;
+	/**
+	 * Obtiene la configuración de una base de datos específica
+	 * @param dbName - Nombre de la base de datos
+	 */
+	getDatabase(dbName: string): DatabaseDefinition | null;
+	/**
+	 * Obtiene todas las bases de datos configuradas
+	 */
+	getAllDatabases(): Record<string, DatabaseDefinition>;
+}
 export declare class Engine {
 	private name;
 	private config;
 	private arguments;
 	private binary;
 	private timeout;
+	private daemonFailed;
 	constructor(name: string, timeout?: number);
 	initializeBinary(): Promise<void>;
+	/**
+	 * Returns a connected DaemonClient for this database, or null when
+	 * daemon mode is disabled/unavailable (then callers use spawn mode).
+	 */
+	private getDaemon;
+	/**
+	 * Executes a DML plan. Uses the persistent daemon (sub-millisecond
+	 * overhead) when available; falls back to one-shot spawn otherwise.
+	 */
+	executeDml(dml: object, txId?: string): Promise<ResponseEngine>;
+	/**
+	 * Executes raw SQL (or a MongoDB command document) with bound parameters.
+	 */
+	rawQuery(query: string, params?: any[], txId?: string): Promise<ResponseEngine>;
+	/** Starts a transaction (daemon mode only). Returns the transaction id. */
+	beginTransaction(): Promise<string>;
+	commitTransaction(txId: string): Promise<void>;
+	rollbackTransaction(txId: string): Promise<void>;
 	setArguments(): any[];
-	setConfig(name: string): {
-		[x: string]: any;
-	} | null;
+	setConfig(name: string): DatabaseDefinition | null;
 	getConfig(): any;
 	run(binary: string, args: [
 	]): Promise<ResponseEngine>;
@@ -35,11 +135,26 @@ export declare class QueryEngine {
 	private isPortAvailable;
 	initializeBinary(): Promise<void>;
 	setArguments(): any[];
-	setConfig(name: string): {
-		[x: string]: any;
-	} | null;
+	/** El daemon puede desactivarse por config (daemon.enabled=false) o por env (DBCUBE_DAEMON=0). */
+	private daemonEnabled;
+	setConfig(name: string): DatabaseDefinition | null;
 	getConfig(): any;
 	run(binary: string, args: string[]): Promise<ResponseEngine>;
+	private argsToCommand;
+	/**
+	 * Executes a DML plan over the persistent TCP server.
+	 * Pass txId to run it inside an active transaction.
+	 */
+	executeDml(dml: object, txId?: string): Promise<ResponseEngine>;
+	/**
+	 * Executes raw SQL (or a MongoDB command document) with bound parameters
+	 * over the persistent TCP server.
+	 */
+	rawQuery(query: string, params?: any[], txId?: string): Promise<ResponseEngine>;
+	/** Starts a server-side transaction and returns its id. */
+	beginTransaction(): Promise<string>;
+	commitTransaction(txId: string): Promise<void>;
+	rollbackTransaction(txId: string): Promise<void>;
 	private executeWithTcpServer;
 	private waitForServerReady;
 	private isServerResponding;
@@ -165,42 +280,63 @@ declare class SQLite {
 	convertToParameterizedQuery(sql: string): ParametrizedQueryResult;
 }
 export declare const DbConfig: SQLite;
-type DatabaseConfig$1 = Record<string, any>;
-/**
- * Tipo para la configuración general del ORM
- */
-export interface ConfigData {
-	[key: string]: any;
-	databases?: Record<string, DatabaseConfig$1>;
+export interface DaemonResponse {
+	status: number;
+	message: string;
+	data: any;
 }
 /**
- * Clase para manejar la configuración del ORM
+ * TCP client for the query-engine daemon (server mode).
+ *
+ * Instead of spawning a new engine process per query (30-80ms overhead),
+ * the daemon keeps the engine alive with warm connection pools and serves
+ * requests over a local TCP socket in <1ms. One daemon per database name.
  */
-export declare class Config {
-	private data;
-	private databases;
-	/**
-	 * Establece la configuración
-	 * @param configData - Datos de configuración
-	 */
-	set(configData: ConfigData): void;
+export declare class DaemonClient {
+	private static registry;
+	private name;
+	private binaryPath;
+	private engineArgs;
+	private socket;
+	private buffer;
+	private pending;
+	private starting;
+	private requestTimeout;
+	private constructor();
+	static get(name: string, binaryPath: string, engineArgs: string[]): DaemonClient;
+	static isEnabled(): boolean;
+	private portfilePath;
+	private lockfilePath;
 	/**
-	 * Obtiene un valor de configuración
-	 * @param key - Clave de configuración
-	 * @returns Valor de configuración
+	 * Exclusive-create lock so two processes never spawn two daemons for the
+	 * same database at once. Stale locks (crashed starter) expire after 15s.
 	 */
-	get<T = any>(key: string): T;
+	private acquireSpawnLock;
+	private releaseSpawnLock;
 	/**
-	 * Obtiene la configuración de una base de datos específica
-	 * @param dbName - Nombre de la base de datos
-	 * @returns Configuración de la base de datos o null
+	 * Ensures a usable daemon connection. Returns false when the daemon
+	 * can't be used (old binary, startup failure) so callers fall back
+	 * to one-shot spawn mode.
 	 */
-	getDatabase(dbName: string): DatabaseConfig$1 | null;
+	ensure(): Promise<boolean>;
+	private connectOrStart;
+	private readPortfile;
+	private spawnDaemon;
+	private tryConnect;
+	private attach;
+	private detach;
+	private onData;
 	/**
-	 * Obtiene todas las bases de datos configuradas
-	 * @returns Todas las configuraciones de bases de datos
+	 * Sends a request to the daemon. Responses arrive in FIFO order on the
+	 * single socket, so pending requests resolve in send order.
 	 */
-	getAllDatabases(): Record<string, DatabaseConfig$1>;
+	send(payload: Record<string, any>, timeoutMs?: number): Promise<DaemonResponse>;
+	execute(dml: object, txId?: string): Promise<DaemonResponse>;
+	raw(query: string, params?: any[], txId?: string): Promise<DaemonResponse>;
+	begin(): Promise<string>;
+	commit(txId: string): Promise<void>;
+	rollback(txId: string): Promise<void>;
+	shutdown(): Promise<void>;
 }
 export interface InterceptOptions {
 	interceptLog?: boolean;
@@ -335,7 +471,7 @@ export interface ComputedFieldConfig {
 	created_at: string;
 	updated_at: string;
 }
-export type DatabaseType = "mysql" | "sqlite" | "postgres" | "mongodb";
+type DatabaseType$1 = "mysql" | "sqlite" | "postgres" | "mongodb";
 export declare class ComputedFieldProcessor {
 	static getComputedFields(name: string): Promise<any[]>;
 	/**
@@ -360,7 +496,7 @@ export declare class ComputedFieldProcessor {
 	static computedFields<T extends DataObject>(data: T[], computedConfigs: ComputedFieldConfig[]): T[];
 }
 export declare class TableProcessor {
-	static generateAlterQueries(nowQuery: string, dbType: DatabaseType, tableName: string, database_ref: string): Promise<string[]>;
+	static generateAlterQueries(nowQuery: string, dbType: DatabaseType$1, tableName: string, database_ref: string): Promise<string[]>;
 	static saveQuery(table_ref: string, database_ref: string, struct: string): Promise<void>;
 }
 export declare class TriggerProcessor {