ee-core 5.0.0-beta.8 → 5.0.1

package/README.md

@@ -4,7 +4,7 @@ Enterprise-grade Electron application framework core — TypeScript edition with
 
 ## Overview
 
-`ee-core` provides the runtime foundation for [electron-egg](https://github.com/wallace5303/electron-egg) applications. It handles the complete lifecycle from boot to shutdown: configuration loading, controller registration, IPC communication, window management, logging, storage, background jobs, and cross-process coordination.
+`ee-core` is the runtime foundation for [electron-egg](https://github.com/wallace5303/electron-egg) applications. It handles the complete lifecycle from boot to shutdown: configuration loading, controller registration, IPC communication, window management, logging, storage, background jobs, and cross-process coordination.
 
 The package outputs dual module formats (CJS + ESM) via conditional exports in `package.json`, making it compatible with both `require()` and `import` environments.
 
@@ -19,13 +19,13 @@ npm install ee-core
 ee-core exposes fine-grained subpath modules. Each can be imported individually:
 
 ```ts
-// Main entry (boot, app, config, etc.)
+// Main entry (boot, app, config, events, etc.)
 import { ElectronEgg } from 'ee-core';
 
 // Specific submodules
 import { ControllerLoader } from 'ee-core/controller';
 import { Cross, cross } from 'ee-core/cross';
-import { extend } from 'ee-core/utils';
+import { extend, is } from 'ee-core/utils';
 import { SqliteStorage } from 'ee-core/storage';
 import { ChildJob, ChildPoolJob, LoadBalancer } from 'ee-core/jobs';
 import type { Config, DevConfig } from 'ee-core/types';
@@ -35,51 +35,88 @@ Available subpaths:
 
 | Subpath | Description |
 |---|---|
-| `ee-core` | Main entry — boot, application, config, events |
-| `ee-core/app` | Application lifecycle and event bus |
+| `ee-core` | Main entry — boot, application, config, events, all modules |
+| `ee-core/app` | Application lifecycle, event bus, directory init |
 | `ee-core/config` | Configuration loading and merging |
+| `ee-core/const` | IPC channel and event constants |
 | `ee-core/controller` | Controller loader and registry |
-| `ee-core/core` | FileLoader and core utilities |
-| `ee-core/cross` | IPC communication (socket.io, HTTP, Electron IPC) |
+| `ee-core/core` | FileLoader, Timing, core utilities |
+| `ee-core/cross` | External process management (Go/Python backends) |
 | `ee-core/electron` | Electron app/window management |
-| `ee-core/exception` | Exception handling |
-| `ee-core/html` | HTML static resource path utility |
+| `ee-core/exception` | Global exception handling (uncaught/unhandled) |
+| `ee-core/html` | Static HTML page path utility (failure pages) |
 | `ee-core/jobs` | Background jobs (ChildJob, ChildPoolJob, LoadBalancer) |
 | `ee-core/loader` | File/module loading utilities |
-| `ee-core/log` | Pino-based logging (pino-roll + pino-pretty) |
-| `ee-core/message` | IPC message routing |
-| `ee-core/ps` | Process/environment utilities (paths, env detection) |
-| `ee-core/socket` | Socket.IO, HTTP, IPC servers |
+| `ee-core/log` | Pino logging (pino-roll + pino-pretty) |
+| `ee-core/message` | Child process IPC message routing |
+| `ee-core/ps` | Process state, environment detection, path utilities |
+| `ee-core/socket` | Socket.IO, HTTP (Koa), IPC servers |
 | `ee-core/storage` | SQLite storage (better-sqlite3) |
 | `ee-core/types` | TypeScript type definitions |
-| `ee-core/utils` | extend, is, json, helper, pargv, port |
+| `ee-core/utils` | extend, is, json, wrap, helper, pargv, port, ip |
 
 ## Architecture
 
 ### Lifecycle
 
-Boot → loadConfig → loadLog → loadDir → loadController → loadSocket → loadElectron
+The `ElectronEgg` startup sequence is strictly ordered:
+
+```
+init() → loadException → loadConfig → loadDir → loadLog
+run() → loadController → loadSocket → emitLifecycle(Ready) → loadElectron
+```
+
+Exception handling must register first to catch subsequent errors; config is the foundation for all modules; directories must exist before writing logs; controllers precede communication services; Ready fires after core modules are loaded; Electron starts last.
+
+### Lifecycle Events
+
+Five framework milestones managed by `EventBus`:
+
+| Event | When |
+|---|---|
+| `Ready` | Core modules loaded, before Electron |
+| `ElectronAppReady` | `app.whenReady()` completed |
+| `WindowReady` | BrowserWindow created |
+| `BeforeClose` | Window close triggered |
+| `Preload` | Preload scripts executing |
+
+Register handlers via `app.register(eventName, handler)` or custom events via `eventBus.on()/emit()`.
 
 ### Controller Loading Pipeline
 
-- **Build time** (ee-bin): `controllerRegistryPlugin` scans `electron/controller/`, generates `ee-core:controller-registry` virtual module with lazy getters.
-- **Runtime** (ee-core): If `globalThis.__EE_CONTROLLER_REGISTRY__` exists (bundle mode), loads from registry. Otherwise falls back to filesystem scanning via globby.
+- **Build time** (ee-bin): `bundleRegistryPlugin` scans `electron/controller/`, computes property paths (`defaultCamelize` with `caseStyle: 'lower'`), generates `app:controller-registry` virtual module setting `global.__EE_CONTROLLER_REGISTRY__` with lazy getters (`get module() { return require(...) }`).
+- **Bundle entry** (`app:bundle-entry`): loads config registry → controller registry → real `main.js`.
+- **Runtime** (ee-core): If `globalThis.__EE_CONTROLLER_REGISTRY__` exists (bundle mode), `FileLoader.parseFromRegistry()` reads from it. Otherwise, falls back to filesystem scanning via `scanDirSync()`.
+
+### Configuration Loading Pipeline
+
+Same dual-mode pattern as controllers:
+
+- **Build time** (ee-bin): `bundleRegistryPlugin` scans `electron/config/`, generates `app:config-registry` virtual module.
+- **Runtime** (ee-core): If `globalThis.__EE_CONFIG_REGISTRY__` exists, `ConfigLoader._loadConfig()` loads by filename. Otherwise, reads from filesystem using `loadFile()`.
 
-### IPC Communication
+Config layering (dev mode only): `config.default.js` → `config.local.js` / `config.prod.js`, merged by `ConfigLoader`.
 
-Main ↔ renderer via `ee-core/cross`, supporting three transport modes:
-- Socket.IO (bidirectional real-time)
-- HTTP server (RESTful)
-- Electron IPC (native)
+### Communication Services
 
-Channels follow pattern `controller/{name}/{method}`.
+Three channels created in order during `loadSocket()`:
+
+| Server | Use Case | Implementation |
+|---|---|---|
+| `SocketServer` | Third-party process communication (Go/Python) | Socket.IO |
+| `HttpServer` | RESTful API for external HTTP clients | Koa + middleware |
+| `IpcServer` | Main ↔ renderer process | `ipcMain.handle/on` + `ipcRenderer.invoke/send` |
+
+All share `resolveControllerFn()` routing — channel pattern: `controller/{name}/{method}`.
 
 ### Window Loading Strategy
 
-- Remote mode → Load remote URL
-- Dev mode → Wait for frontend dev server, show loading page first
-- Prod + cross takeover → Wait for cross-process service
-- Prod (default) → Load local HTML file
+`loadServer()` selects strategy based on config and environment:
+
+1. **Remote mode** (`remote.enable=true`) → Load remote URL
+2. **Dev mode** → Poll frontend dev server (`waitForUrl`), show loading page first
+3. **Prod + cross takeover** → Wait for cross-process service to be ready
+4. **Prod (default)** → Load local HTML file
 
 ## Key APIs
 
@@ -89,7 +126,10 @@ Channels follow pattern `controller/{name}/{method}`.
 import { ElectronEgg } from 'ee-core';
 
 // Start the framework
-const app = new ElectronEgg();
+const boot = new ElectronEgg();
+
+// Async startup (ESM)
+await boot.runAsync();
 ```
 
 ### Configuration
@@ -98,32 +138,83 @@ const app = new ElectronEgg();
 import { getConfig, setConfig } from 'ee-core/config';
 
 const config = getConfig();
+
+// Child processes can receive config without filesystem access
+setConfig(config);
 ```
 
 ### Controller
 
 ```ts
-import { getController } from 'ee-core/controller';
+import { getController, getControllers } from 'ee-core/controller';
 
+// Get specific controller
 const userController = getController('user');
+
+// Get all loaded controllers
+const all = getControllers();
 ```
 
 ### Cross-Process Communication
 
 ```ts
 import { cross } from 'ee-core/cross';
+import type { CrossTargetConfig } from 'ee-core';
+
+// Run Go backend with custom config
+const opt: CrossTargetConfig = {
+  name: 'goapp',
+  cmd: path.join(getExtraResourcesDir(), 'goapp'),
+  directory: getExtraResourcesDir(),
+  args: ['--port=7073'],
+  appExit: true,
+};
+const entity = await cross.run('go', opt);
+
+// Get service URL
+const url = cross.getUrl('goapp');
+
+// Kill by name
+cross.killByName('goapp');
+```
+
+### Communication Servers
 
-// Send IPC message to renderer
-cross.sendToRenderer('controller/user/info', data);
+```ts
+import { getSocketServer, getHttpServer, getIpcServer } from 'ee-core/socket';
+
+// All getters return non-null instances after Ready event
+const socket = getSocketServer();
+const http = getHttpServer();
+const ipc = getIpcServer();
+```
+
+### Main Window
+
+```ts
+import { getMainWindow } from 'ee-core/electron';
+
+// Returns BrowserWindow (non-null) after WindowReady event
+const win = getMainWindow();
+win.setMenuBarVisibility(false);
 ```
 
 ### Jobs
 
 ```ts
-import { ChildJob, ChildPoolJob, LoadBalancer } from 'ee-core/jobs';
+import { ChildJob, ChildPoolJob, LoadBalancer, AlgorithmType } from 'ee-core/jobs';
 
+// Single task execution
 const job = new ChildJob();
-const result = await job.exec({ name: 'task', script: './jobs/demo.js' });
+const result = await job.exec('./jobs/demo.js', { taskName: 'cleanup' });
+
+// Process pool with load balancing
+const pool = new ChildPoolJob();
+pool.create(3); // Create 3 workers
+const result = await pool.run('./jobs/demo.js', { taskName: 'batch' });
+
+// 8 algorithms: polling, weights, random, specify, weightsPolling,
+// weightsRandom, minimumConnection, weightsMinimumConnection
 ```
 
 ### Storage
@@ -131,28 +222,99 @@ const result = await job.exec({ name: 'task', script: './jobs/demo.js' });
 ```ts
 import { SqliteStorage } from 'ee-core/storage';
 
-const db = new SqliteStorage('./data/app.db');
-db.prepare('CREATE TABLE IF NOT EXISTS user (id INTEGER PRIMARY KEY, name TEXT)').run();
+// Four modes: memory, onlyName, relative, absolute
+const db = new SqliteStorage({ mode: 'onlyName', name: 'app' });
 ```
 
 ### Logging
 
 ```ts
-import { coreLogger, getLoggers } from 'ee-core/log';
+import { logger, coreLogger } from 'ee-core/log';
+
+// Supports three call styles: pino standard, pino printf, concatenation
+logger.info('Application started');
+logger.info('User %s logged in', 'admin');
+logger.info('data:', { id: 1, name: 'test' });
 
-coreLogger.info('Application started');
+// Log files: ee.log, ee-core.log, ee-error.log
+// Rotation: daily/hourly via pino-roll
+// Dev mode: pino-pretty for terminal output
 ```
 
 ### Process/Environment
 
 ```ts
-import { isDev, getBaseDir, env } from 'ee-core/ps';
+import { isDev, isProd, getBaseDir, getDataDir, getLogDir } from 'ee-core/ps';
+import { is } from 'ee-core/utils';
 
 if (isDev()) {
   // Development-specific logic
 }
+
+// Platform detection
+if (is.macOS()) { /* macOS */ }
+if (is.windows()) { /* Windows */ }
+if (is.linux()) { /* Linux */ }
+if (is.openharmony()) { /* OpenHarmony */ }
+
+// Path utilities
+const baseDir = getBaseDir();
+const dataDir = getDataDir();
+const logDir = getLogDir();
+const extraRes = getExtraResourcesDir();
+```
+
+### Event Bus
+
+```ts
+import { eventBus, BeforeClose } from 'ee-core/app';
+
+// Register lifecycle hook
+app.register(BeforeClose, async () => {
+  // Cleanup before app closes
+});
+
+// Custom events
+eventBus.on('myEvent', (data) => { /* handle */ });
+eventBus.emit('myEvent', { key: 'value' });
+```
+
+### Exception Handling
+
+```ts
+// Auto-registered during boot. Controls exit behavior:
+// exception.mainExit / childExit / rendererExit
+// Errors logged via coreLogger, dev mode sends to terminal
+```
+
+### Utility Functions
+
+```ts
+import { extend, strictParse, getPort, parseArgv, sleep } from 'ee-core/utils';
+
+// Deep merge with prototype pollution guard
+const merged = extend(true, {}, defaults, userConfig);
+
+// Port allocation with two-level locking
+const port = await getPort({ port: 7070 });
+
+// CLI argument parser
+const args = parseArgv(process.argv);
+
+// Sync sleep (Atomics.wait-based, no subprocess)
+sleep(1000);
 ```
 
+## TypeScript Types
+
+All types are exported from `ee-core/types`:
+
+```ts
+import type { Config, CrossTargetConfig, DevConfig, AppInfo } from 'ee-core/types';
+```
+
+Key type interfaces: `ElectronEggOptions`, `Config`, `AppInfo`, `CrossTargetConfig`, `CrossRunOptions`, `LoggerConfig`, `ExceptionConfig`, `FileLoaderOptions`, `LoadBalancerOptions`, `JobProcessOptions`, `MessageData`.
+
 ## Build
 
 ```bash
@@ -161,10 +323,21 @@ npm run build:cjs      # Build CommonJS only
 npm run build:esm      # Build ESM only
 npm run typecheck      # TypeScript type checking
 npm run test           # Run vitest
+npm run test:watch     # Run vitest in watch mode
 ```
 
 The `exports` map in `package.json` is auto-generated by `scripts/gen-exports.js`. Do not edit manually — run `npm run gen-exports` after adding new subpath modules.
 
+## Debug Logging
+
+ee-core uses the `debug` library for verbose namespace-scoped logging. Enable to see runtime internals (config merging, controller loading, module resolution):
+
+```bash
+DEBUG=ee-* node your-app            # All ee-* namespaces
+DEBUG=ee-core:config:* node your-app  # Config subsystem only
+DEBUG=ee-core:controller:* node your-app  # Controller loading only
+```
+
 ## Requirements
 
 - Node.js >= 20.19.0
@@ -174,5 +347,6 @@ The `exports` map in `package.json` is auto-generated by `scripts/gen-exports.js
 ## Notes
 
 - ESM imports in ee-core source must include `.js` extensions (required by `module: NodeNext`)
-- ee-core is NOT bundled into the Electron main process bundle — it's an esbuild external loaded from `node_modules` at runtime
-- The framework uses the `debug` library for verbose logging. Enable with `DEBUG=ee-*` environment variable
+- ee-core is NOT bundled into the Electron main process bundle — it's an esbuild external loaded from `node_modules` at runtime. This allows `child_process.fork()` to find `app.js` as a real disk file
+- `getMainWindow()`, `getSocketServer()`, `getHttpServer()`, `getIpcServer()` return non-null instances. If called before the corresponding lifecycle event, they throw an Error indicating a lifecycle ordering bug
+- The `exports` map is auto-generated — run `npm run gen-exports` after adding new modules

package/dist/cjs/jobs/child/jobProcess.js

@@ -55,7 +55,7 @@ class JobProcess {
             processOptions: {
                 cwd,
                 env: (0, index_js_2.allEnv)(),
-                stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+                stdio: ['ignore', 'pipe', 'pipe', 'ipc']
             },
         };
         const options = (0, extend_js_1.extend)(true, defaultOptions, opt);

package/dist/cjs/storage/index.d.ts

@@ -1,2 +1,17 @@
+/**
+ * @module storage
+ * @description Data storage module entry point. Provides SqliteStorage for SQLite database operations.
+ *
+ * SqliteStorage class is exported statically — loading this module only imports built-in
+ * Node.js modules (assert, fs, path), NOT better-sqlite3. The native better-sqlite3 binding
+ * is only loaded when `SqliteStorage.init()` is called, via dynamic import().
+ *
+ * Usage:
+ * ```ts
+ * import { SqliteStorage } from 'ee-core/storage';
+ * const db = new SqliteStorage('myapp.db');
+ * await db.init();  // ← here better-sqlite3 is actually loaded
+ * ```
+ */
 export { SqliteStorage } from './sqliteStorage.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/cjs/storage/index.js

@@ -1,6 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SqliteStorage = void 0;
+/**
+ * @module storage
+ * @description Data storage module entry point. Provides SqliteStorage for SQLite database operations.
+ *
+ * SqliteStorage class is exported statically — loading this module only imports built-in
+ * Node.js modules (assert, fs, path), NOT better-sqlite3. The native better-sqlite3 binding
+ * is only loaded when `SqliteStorage.init()` is called, via dynamic import().
+ *
+ * Usage:
+ * ```ts
+ * import { SqliteStorage } from 'ee-core/storage';
+ * const db = new SqliteStorage('myapp.db');
+ * await db.init();  // ← here better-sqlite3 is actually loaded
+ * ```
+ */
 var sqliteStorage_js_1 = require("./sqliteStorage.js");
 Object.defineProperty(exports, "SqliteStorage", { enumerable: true, get: function () { return sqliteStorage_js_1.SqliteStorage; } });
 //# sourceMappingURL=index.js.map

package/dist/cjs/storage/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":";;;AAAA,uDAAmD;AAA1C,iHAAA,aAAa,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;GAcG;AACH,uDAAmD;AAA1C,iHAAA,aAAa,OAAA"}

package/dist/cjs/storage/sqliteStorage.d.ts

@@ -1,4 +1,4 @@
-import Database from 'better-sqlite3';
+import type Database from 'better-sqlite3';
 /**
  * SqliteStorage - SQLite database storage class
  *
@@ -15,6 +15,12 @@ import Database from 'better-sqlite3';
  * Security:
  * The constructor validates the database name for path traversal, disallowing ".." in the name
  * to prevent malicious input from accessing files outside the intended directory.
+ *
+ * Lazy loading:
+ * better-sqlite3 is a native module that requires electron-rebuild for Electron.
+ * The constructor only computes paths (synchronous). The `init()` method lazily imports
+ * better-sqlite3 and opens the database connection. Projects that don't use SQLite
+ * never load the native binding.
  */
 export declare class SqliteStorage {
     /** Database name (original input value) */
@@ -25,42 +31,36 @@ export declare class SqliteStorage {
     dbDir: string;
     /** Database filename (only the filename part, excluding directory) */
     fileName: string;
-    /** better-sqlite3 database instance */
+    /** better-sqlite3 database instance (set after init()) */
     db: Database.Database;
     /**
-     * Create a SqliteStorage instance
+     * Create a SqliteStorage instance (path computation only, DB not yet opened)
      *
-     * Initialization flow:
-     * 1. Validate that the name is non-empty and does not contain path traversal characters ".."
-     * 2. Infer storage mode from the name (getMode)
-     * 3. Create the database file directory (_createDatabaseDir)
-     * 4. Extract the filename part (_formatFileName)
-     * 5. Open the database connection (_initDB)
+     * The constructor only validates the name, infers the storage mode, computes paths,
+     * and creates the database directory. It does NOT open the database connection —
+     * call `init()` to lazily load better-sqlite3 and open the DB.
      *
      * @param name - Database name or path. Supports the following formats:
      *   - ":memory:" - In-memory database
      *   - "app.db" - Filename only, stored under {dataDir}/db/
      *   - "sub/app.db" - Relative path, relative to {dataDir}/db/
      *   - "/tmp/app.db" - Absolute path
-     * @param opt - better-sqlite3 database options, defaults merged with timeout: 5000
      * @throws Asserts error if name is empty or contains ".." path traversal characters
      */
-    constructor(name: string, opt?: Record<string, unknown>);
+    constructor(name: string);
     /**
      * Initialize the database connection
      *
-     * Determines the database path based on storage mode:
-     * - memory mode: Uses ":memory:" as the path, better-sqlite3 creates the database in memory
-     * - file mode: Uses getFilePath() to get the full database file path
+     * Lazily imports better-sqlite3 via dynamic import() and opens the database.
+     * This is the only point where the native .node binding is loaded.
      *
-     * In file mode, additionally validates that the database file was created successfully.
-     * If the file does not exist, throws an assertion error (possibly due to insufficient directory permissions, etc.).
+     * Must be called after construction before using `this.db`.
      *
      * @param opt - better-sqlite3 database options, defaults merged with { timeout: 5000 }
-     * @returns better-sqlite3 Database instance
+     * @returns this SqliteStorage instance (for chaining: `const db = await new SqliteStorage('app.db').init()`)
      * @throws Asserts error if the database file was not created successfully in file mode
      */
-    _initDB(opt?: Record<string, unknown>): Database.Database;
+    init(opt?: Record<string, unknown>): Promise<this>;
     /**
      * Extract the database filename
      *

package/dist/cjs/storage/sqliteStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqliteStorage.d.ts","sourceRoot":"","sources":["../../../src/storage/sqliteStorage.ts"],"names":[],"mappings":"AA6BA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAItC;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAa;IACxB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IAEb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IAEb,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IAEd,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IAEjB,uCAAuC;IACvC,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC;IAEtB;;;;;;;;;;;;;;;;;OAiBG;gBACS,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAY3D;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,QAAQ,CAAC,QAAQ;IAmB7D;;;;;;;;OAQG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAOrC;;;;;;;;;;;OAWG;IACH,kBAAkB,IAAI,MAAM;IAc5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAe7B;;;;OAIG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;;;;OAOG;IACH,WAAW,IAAI,MAAM;CAGtB"}
+{"version":3,"file":"sqliteStorage.d.ts","sourceRoot":"","sources":["../../../src/storage/sqliteStorage.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa;IACxB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IAEb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IAEb,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IAEd,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IAEjB,0DAA0D;IAC1D,EAAE,EAAG,QAAQ,CAAC,QAAQ,CAAC;IAEvB;;;;;;;;;;;;;OAaG;gBACS,IAAI,EAAE,MAAM;IAWxB;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB5D;;;;;;;;OAQG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAOrC;;;;;;;;;;;OAWG;IACH,kBAAkB,IAAI,MAAM;IAc5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAe7B;;;;OAIG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;;;;OAOG;IACH,WAAW,IAAI,MAAM;CAGtB"}

package/dist/cjs/storage/sqliteStorage.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -15,25 +48,32 @@ exports.SqliteStorage = void 0;
  * - Prevent path traversal attacks (validates that ".." is not present in the name during construction)
  * - Provide a unified interface for obtaining database file paths
  *
+ * better-sqlite3 is lazily imported — only loaded when `init()` is called to open the database.
+ * This avoids loading the native .node binding at module import time, which would happen unconditionally
+ * even if the consumer never uses SQLite.
+ *
  * Usage examples:
  * ```ts
  * // Name-only mode: file stored at {dataDir}/db/{name}.db
  * const db1 = new SqliteStorage('myapp.db');
+ * await db1.init();
  *
  * // Relative path mode: file stored at {dataDir}/db/sub/myapp.db
  * const db2 = new SqliteStorage('sub/myapp.db');
+ * await db2.init();
  *
  * // Absolute path mode: file stored at the specified path
  * const db3 = new SqliteStorage('/tmp/data/myapp.db');
+ * await db3.init();
  *
  * // In-memory mode: not persisted, data is lost when the process exits
  * const db4 = new SqliteStorage(':memory:');
+ * await db4.init();
  * ```
  */
 const assert_1 = __importDefault(require("assert"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const helper_js_1 = require("../utils/helper.js");
 const index_js_1 = require("../ps/index.js");
 /**
@@ -52,27 +92,29 @@ const index_js_1 = require("../ps/index.js");
  * Security:
  * The constructor validates the database name for path traversal, disallowing ".." in the name
  * to prevent malicious input from accessing files outside the intended directory.
+ *
+ * Lazy loading:
+ * better-sqlite3 is a native module that requires electron-rebuild for Electron.
+ * The constructor only computes paths (synchronous). The `init()` method lazily imports
+ * better-sqlite3 and opens the database connection. Projects that don't use SQLite
+ * never load the native binding.
  */
 class SqliteStorage {
     /**
-     * Create a SqliteStorage instance
+     * Create a SqliteStorage instance (path computation only, DB not yet opened)
      *
-     * Initialization flow:
-     * 1. Validate that the name is non-empty and does not contain path traversal characters ".."
-     * 2. Infer storage mode from the name (getMode)
-     * 3. Create the database file directory (_createDatabaseDir)
-     * 4. Extract the filename part (_formatFileName)
-     * 5. Open the database connection (_initDB)
+     * The constructor only validates the name, infers the storage mode, computes paths,
+     * and creates the database directory. It does NOT open the database connection —
+     * call `init()` to lazily load better-sqlite3 and open the DB.
      *
      * @param name - Database name or path. Supports the following formats:
      *   - ":memory:" - In-memory database
      *   - "app.db" - Filename only, stored under {dataDir}/db/
      *   - "sub/app.db" - Relative path, relative to {dataDir}/db/
      *   - "/tmp/app.db" - Absolute path
-     * @param opt - better-sqlite3 database options, defaults merged with timeout: 5000
      * @throws Asserts error if name is empty or contains ".." path traversal characters
      */
-    constructor(name, opt = {}) {
+    constructor(name) {
         (0, assert_1.default)(name, `db name ${name} Cannot be empty`);
         // Prevent path traversal attacks: disallow ".." in the name to avoid directory backtracking
         (0, assert_1.default)(!name.includes('..'), `db name ${name} contains path traversal`);
@@ -80,35 +122,36 @@ class SqliteStorage {
         this.mode = this.getMode(name);
         this.dbDir = this._createDatabaseDir();
         this.fileName = this._formatFileName(name);
-        this.db = this._initDB(opt);
     }
     /**
      * Initialize the database connection
      *
-     * Determines the database path based on storage mode:
-     * - memory mode: Uses ":memory:" as the path, better-sqlite3 creates the database in memory
-     * - file mode: Uses getFilePath() to get the full database file path
+     * Lazily imports better-sqlite3 via dynamic import() and opens the database.
+     * This is the only point where the native .node binding is loaded.
      *
-     * In file mode, additionally validates that the database file was created successfully.
-     * If the file does not exist, throws an assertion error (possibly due to insufficient directory permissions, etc.).
+     * Must be called after construction before using `this.db`.
      *
      * @param opt - better-sqlite3 database options, defaults merged with { timeout: 5000 }
-     * @returns better-sqlite3 Database instance
+     * @returns this SqliteStorage instance (for chaining: `const db = await new SqliteStorage('app.db').init()`)
      * @throws Asserts error if the database file was not created successfully in file mode
      */
-    _initDB(opt = {}) {
+    async init(opt = {}) {
+        // Lazy import: better-sqlite3 is only loaded when actually needed.
+        // This avoids loading the native .node binding at module import time.
+        // better-sqlite3 is a CJS package; dynamic import() resolves it correctly.
+        const { default: Database } = await Promise.resolve().then(() => __importStar(require('better-sqlite3')));
         const options = Object.assign({ timeout: 5000 }, opt);
         // Storage type: db file, in-memory (:memory:)
         let dbPath = this.name;
         if (this.mode !== 'memory') {
             dbPath = this.getFilePath();
         }
-        const db = new better_sqlite3_1.default(dbPath, options);
+        this.db = new Database(dbPath, options);
         // For file mode, check if the file was created successfully
         if (this.mode !== 'memory') {
             (0, assert_1.default)(fs_1.default.existsSync(dbPath), `error: db ${dbPath} not exists`);
         }
-        return db;
+        return this;
     }
     /**
      * Extract the database filename

package/dist/cjs/storage/sqliteStorage.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqliteStorage.js","sourceRoot":"","sources":["../../../src/storage/sqliteStorage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sqliteStorage.js","sourceRoot":"","sources":["../../../src/storage/sqliteStorage.ts"],"names":[],"mappings":"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"}

package/dist/esm/jobs/child/jobProcess.js

@@ -55,7 +55,7 @@ class JobProcess {
             processOptions: {
                 cwd,
                 env: (0, index_js_2.allEnv)(),
-                stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+                stdio: ['ignore', 'pipe', 'pipe', 'ipc']
             },
         };
         const options = (0, extend_js_1.extend)(true, defaultOptions, opt);

package/dist/esm/storage/index.d.ts

@@ -1,2 +1,17 @@
+/**
+ * @module storage
+ * @description Data storage module entry point. Provides SqliteStorage for SQLite database operations.
+ *
+ * SqliteStorage class is exported statically — loading this module only imports built-in
+ * Node.js modules (assert, fs, path), NOT better-sqlite3. The native better-sqlite3 binding
+ * is only loaded when `SqliteStorage.init()` is called, via dynamic import().
+ *
+ * Usage:
+ * ```ts
+ * import { SqliteStorage } from 'ee-core/storage';
+ * const db = new SqliteStorage('myapp.db');
+ * await db.init();  // ← here better-sqlite3 is actually loaded
+ * ```
+ */
 export { SqliteStorage } from './sqliteStorage.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/esm/storage/index.js

@@ -1,6 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SqliteStorage = void 0;
+/**
+ * @module storage
+ * @description Data storage module entry point. Provides SqliteStorage for SQLite database operations.
+ *
+ * SqliteStorage class is exported statically — loading this module only imports built-in
+ * Node.js modules (assert, fs, path), NOT better-sqlite3. The native better-sqlite3 binding
+ * is only loaded when `SqliteStorage.init()` is called, via dynamic import().
+ *
+ * Usage:
+ * ```ts
+ * import { SqliteStorage } from 'ee-core/storage';
+ * const db = new SqliteStorage('myapp.db');
+ * await db.init();  // ← here better-sqlite3 is actually loaded
+ * ```
+ */
 var sqliteStorage_js_1 = require("./sqliteStorage.js");
 Object.defineProperty(exports, "SqliteStorage", { enumerable: true, get: function () { return sqliteStorage_js_1.SqliteStorage; } });
 //# sourceMappingURL=index.js.map

package/dist/esm/storage/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":";;;AAAA,uDAAmD;AAA1C,iHAAA,aAAa,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;GAcG;AACH,uDAAmD;AAA1C,iHAAA,aAAa,OAAA"}

package/dist/esm/storage/sqliteStorage.d.ts

@@ -1,4 +1,4 @@
-import Database from 'better-sqlite3';
+import type Database from 'better-sqlite3';
 /**
  * SqliteStorage - SQLite database storage class
  *
@@ -15,6 +15,12 @@ import Database from 'better-sqlite3';
  * Security:
  * The constructor validates the database name for path traversal, disallowing ".." in the name
  * to prevent malicious input from accessing files outside the intended directory.
+ *
+ * Lazy loading:
+ * better-sqlite3 is a native module that requires electron-rebuild for Electron.
+ * The constructor only computes paths (synchronous). The `init()` method lazily imports
+ * better-sqlite3 and opens the database connection. Projects that don't use SQLite
+ * never load the native binding.
  */
 export declare class SqliteStorage {
     /** Database name (original input value) */
@@ -25,42 +31,36 @@ export declare class SqliteStorage {
     dbDir: string;
     /** Database filename (only the filename part, excluding directory) */
     fileName: string;
-    /** better-sqlite3 database instance */
+    /** better-sqlite3 database instance (set after init()) */
     db: Database.Database;
     /**
-     * Create a SqliteStorage instance
+     * Create a SqliteStorage instance (path computation only, DB not yet opened)
      *
-     * Initialization flow:
-     * 1. Validate that the name is non-empty and does not contain path traversal characters ".."
-     * 2. Infer storage mode from the name (getMode)
-     * 3. Create the database file directory (_createDatabaseDir)
-     * 4. Extract the filename part (_formatFileName)
-     * 5. Open the database connection (_initDB)
+     * The constructor only validates the name, infers the storage mode, computes paths,
+     * and creates the database directory. It does NOT open the database connection —
+     * call `init()` to lazily load better-sqlite3 and open the DB.
      *
      * @param name - Database name or path. Supports the following formats:
      *   - ":memory:" - In-memory database
      *   - "app.db" - Filename only, stored under {dataDir}/db/
      *   - "sub/app.db" - Relative path, relative to {dataDir}/db/
      *   - "/tmp/app.db" - Absolute path
-     * @param opt - better-sqlite3 database options, defaults merged with timeout: 5000
      * @throws Asserts error if name is empty or contains ".." path traversal characters
      */
-    constructor(name: string, opt?: Record<string, unknown>);
+    constructor(name: string);
     /**
      * Initialize the database connection
      *
-     * Determines the database path based on storage mode:
-     * - memory mode: Uses ":memory:" as the path, better-sqlite3 creates the database in memory
-     * - file mode: Uses getFilePath() to get the full database file path
+     * Lazily imports better-sqlite3 via dynamic import() and opens the database.
+     * This is the only point where the native .node binding is loaded.
      *
-     * In file mode, additionally validates that the database file was created successfully.
-     * If the file does not exist, throws an assertion error (possibly due to insufficient directory permissions, etc.).
+     * Must be called after construction before using `this.db`.
      *
      * @param opt - better-sqlite3 database options, defaults merged with { timeout: 5000 }
-     * @returns better-sqlite3 Database instance
+     * @returns this SqliteStorage instance (for chaining: `const db = await new SqliteStorage('app.db').init()`)
      * @throws Asserts error if the database file was not created successfully in file mode
      */
-    _initDB(opt?: Record<string, unknown>): Database.Database;
+    init(opt?: Record<string, unknown>): Promise<this>;
     /**
      * Extract the database filename
      *

package/dist/esm/storage/sqliteStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqliteStorage.d.ts","sourceRoot":"","sources":["../../../src/storage/sqliteStorage.ts"],"names":[],"mappings":"AA6BA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAItC;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAa;IACxB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IAEb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IAEb,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IAEd,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IAEjB,uCAAuC;IACvC,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC;IAEtB;;;;;;;;;;;;;;;;;OAiBG;gBACS,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAY3D;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,QAAQ,CAAC,QAAQ;IAmB7D;;;;;;;;OAQG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAOrC;;;;;;;;;;;OAWG;IACH,kBAAkB,IAAI,MAAM;IAc5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAe7B;;;;OAIG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;;;;OAOG;IACH,WAAW,IAAI,MAAM;CAGtB"}
+{"version":3,"file":"sqliteStorage.d.ts","sourceRoot":"","sources":["../../../src/storage/sqliteStorage.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa;IACxB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IAEb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IAEb,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IAEd,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IAEjB,0DAA0D;IAC1D,EAAE,EAAG,QAAQ,CAAC,QAAQ,CAAC;IAEvB;;;;;;;;;;;;;OAaG;gBACS,IAAI,EAAE,MAAM;IAWxB;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB5D;;;;;;;;OAQG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAOrC;;;;;;;;;;;OAWG;IACH,kBAAkB,IAAI,MAAM;IAc5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAe7B;;;;OAIG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;;;;OAOG;IACH,WAAW,IAAI,MAAM;CAGtB"}

package/dist/esm/storage/sqliteStorage.js

@@ -15,25 +15,32 @@ exports.SqliteStorage = void 0;
  * - Prevent path traversal attacks (validates that ".." is not present in the name during construction)
  * - Provide a unified interface for obtaining database file paths
  *
+ * better-sqlite3 is lazily imported — only loaded when `init()` is called to open the database.
+ * This avoids loading the native .node binding at module import time, which would happen unconditionally
+ * even if the consumer never uses SQLite.
+ *
  * Usage examples:
  * ```ts
  * // Name-only mode: file stored at {dataDir}/db/{name}.db
  * const db1 = new SqliteStorage('myapp.db');
+ * await db1.init();
  *
  * // Relative path mode: file stored at {dataDir}/db/sub/myapp.db
  * const db2 = new SqliteStorage('sub/myapp.db');
+ * await db2.init();
  *
  * // Absolute path mode: file stored at the specified path
  * const db3 = new SqliteStorage('/tmp/data/myapp.db');
+ * await db3.init();
  *
  * // In-memory mode: not persisted, data is lost when the process exits
  * const db4 = new SqliteStorage(':memory:');
+ * await db4.init();
  * ```
  */
 const assert_1 = __importDefault(require("assert"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const helper_js_1 = require("../utils/helper.js");
 const index_js_1 = require("../ps/index.js");
 /**
@@ -52,27 +59,29 @@ const index_js_1 = require("../ps/index.js");
  * Security:
  * The constructor validates the database name for path traversal, disallowing ".." in the name
  * to prevent malicious input from accessing files outside the intended directory.
+ *
+ * Lazy loading:
+ * better-sqlite3 is a native module that requires electron-rebuild for Electron.
+ * The constructor only computes paths (synchronous). The `init()` method lazily imports
+ * better-sqlite3 and opens the database connection. Projects that don't use SQLite
+ * never load the native binding.
  */
 class SqliteStorage {
     /**
-     * Create a SqliteStorage instance
+     * Create a SqliteStorage instance (path computation only, DB not yet opened)
      *
-     * Initialization flow:
-     * 1. Validate that the name is non-empty and does not contain path traversal characters ".."
-     * 2. Infer storage mode from the name (getMode)
-     * 3. Create the database file directory (_createDatabaseDir)
-     * 4. Extract the filename part (_formatFileName)
-     * 5. Open the database connection (_initDB)
+     * The constructor only validates the name, infers the storage mode, computes paths,
+     * and creates the database directory. It does NOT open the database connection —
+     * call `init()` to lazily load better-sqlite3 and open the DB.
      *
      * @param name - Database name or path. Supports the following formats:
      *   - ":memory:" - In-memory database
      *   - "app.db" - Filename only, stored under {dataDir}/db/
      *   - "sub/app.db" - Relative path, relative to {dataDir}/db/
      *   - "/tmp/app.db" - Absolute path
-     * @param opt - better-sqlite3 database options, defaults merged with timeout: 5000
      * @throws Asserts error if name is empty or contains ".." path traversal characters
      */
-    constructor(name, opt = {}) {
+    constructor(name) {
         (0, assert_1.default)(name, `db name ${name} Cannot be empty`);
         // Prevent path traversal attacks: disallow ".." in the name to avoid directory backtracking
         (0, assert_1.default)(!name.includes('..'), `db name ${name} contains path traversal`);
@@ -80,35 +89,36 @@ class SqliteStorage {
         this.mode = this.getMode(name);
         this.dbDir = this._createDatabaseDir();
         this.fileName = this._formatFileName(name);
-        this.db = this._initDB(opt);
     }
     /**
      * Initialize the database connection
      *
-     * Determines the database path based on storage mode:
-     * - memory mode: Uses ":memory:" as the path, better-sqlite3 creates the database in memory
-     * - file mode: Uses getFilePath() to get the full database file path
+     * Lazily imports better-sqlite3 via dynamic import() and opens the database.
+     * This is the only point where the native .node binding is loaded.
      *
-     * In file mode, additionally validates that the database file was created successfully.
-     * If the file does not exist, throws an assertion error (possibly due to insufficient directory permissions, etc.).
+     * Must be called after construction before using `this.db`.
      *
      * @param opt - better-sqlite3 database options, defaults merged with { timeout: 5000 }
-     * @returns better-sqlite3 Database instance
+     * @returns this SqliteStorage instance (for chaining: `const db = await new SqliteStorage('app.db').init()`)
      * @throws Asserts error if the database file was not created successfully in file mode
      */
-    _initDB(opt = {}) {
+    async init(opt = {}) {
+        // Lazy import: better-sqlite3 is only loaded when actually needed.
+        // This avoids loading the native .node binding at module import time.
+        // better-sqlite3 is a CJS package; dynamic import() resolves it correctly.
+        const { default: Database } = await import('better-sqlite3');
         const options = Object.assign({ timeout: 5000 }, opt);
         // Storage type: db file, in-memory (:memory:)
         let dbPath = this.name;
         if (this.mode !== 'memory') {
             dbPath = this.getFilePath();
         }
-        const db = new better_sqlite3_1.default(dbPath, options);
+        this.db = new Database(dbPath, options);
         // For file mode, check if the file was created successfully
         if (this.mode !== 'memory') {
             (0, assert_1.default)(fs_1.default.existsSync(dbPath), `error: db ${dbPath} not exists`);
         }
-        return db;
+        return this;
     }
     /**
      * Extract the database filename

package/dist/esm/storage/sqliteStorage.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqliteStorage.js","sourceRoot":"","sources":["../../../src/storage/sqliteStorage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sqliteStorage.js","sourceRoot":"","sources":["../../../src/storage/sqliteStorage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ee-core",
-  "version": "5.0.0-beta.8",
+  "version": "5.0.1",
   "description": "ee core - TypeScript edition with dual module support",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",