ee-core 4.1.5 → 5.0.0-beta.5

package/dist/cjs/socket/ipcServer.js.map

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

package/dist/cjs/socket/socketServer.d.ts

@@ -0,0 +1,43 @@
+import { Server } from 'socket.io';
+import type { SocketServerConfig } from '../types/index.js';
+/**
+ * SocketServer - SocketIO server
+ *
+ * Created using factory pattern (static create()), because initialization requires async port acquisition.
+ * When enable=false in config, the service will not start after creation.
+ */
+export declare class SocketServer {
+    /** SocketIO server configuration */
+    config: SocketServerConfig;
+    /** Channel separator */
+    channelSeparator: string;
+    /** Currently connected socket instance */
+    socket: ReturnType<Server['on']> | undefined;
+    /** SocketIO Server instance */
+    io: Server | undefined;
+    private constructor();
+    /**
+     * Factory method: create and initialize SocketServer
+     *
+     * @returns Fully initialized SocketServer instance
+     */
+    static create(): Promise<SocketServer>;
+    /**
+     * Initialize SocketIO server
+     *
+     * Acquires an available port then creates a SocketIO Server instance.
+     * The port number is written to process.env.EE_SOCKET_PORT for other modules to access.
+     */
+    init(): Promise<void>;
+    /**
+     * Listen for client connections and handle messages
+     *
+     * After client connects, listens on the configured channel (default 'socket-channel').
+     * Upon receiving a message, routes via cmd path to the corresponding controller method for execution.
+     *
+     * Message format: { cmd: string, args: unknown }
+     * Return method: Results are sent back to client via callback function
+     */
+    connect(): void;
+}
+//# sourceMappingURL=socketServer.d.ts.map

package/dist/cjs/socket/socketServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socketServer.d.ts","sourceRoot":"","sources":["../../../src/socket/socketServer.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAMnC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAK5D;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,oCAAoC;IACpC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,wBAAwB;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;IAC7C,+BAA+B;IAC/B,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IAEvB,OAAO;IAQP;;;;OAIG;WACU,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAM5C;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB3B;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;CA+BhB"}

package/dist/cjs/socket/socketServer.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketServer = void 0;
+/**
+ * @module socket/socketServer
+ * @description SocketIO server. Provides WebSocket/HTTP polling communication for
+ * third-party software (non-Electron renderer processes) to call main process controller methods.
+ *
+ * Communication protocol:
+ * - After client connects, send messages on a specified channel: { cmd: 'controller/user/add', args: {...} }
+ * - Server parses the cmd path and calls the corresponding controller method
+ * - Controller execution result is returned to client via callback
+ *
+ * Use cases:
+ * - Local other processes (Go/Python backends) communicating with Electron main process
+ * - Remote control panels operating the application via WebSocket
+ */
+const debug_1 = __importDefault(require("debug"));
+const socket_io_1 = require("socket.io");
+const index_js_1 = require("../log/index.js");
+const index_js_2 = require("../config/index.js");
+const channel_js_1 = require("../const/channel.js");
+const index_js_3 = require("../controller/index.js");
+const index_js_4 = require("../utils/port/index.js");
+const utils_js_1 = require("./utils.js");
+const debugLog = (0, debug_1.default)('ee-core:socket:socketServer');
+/**
+ * SocketServer - SocketIO server
+ *
+ * Created using factory pattern (static create()), because initialization requires async port acquisition.
+ * When enable=false in config, the service will not start after creation.
+ */
+class SocketServer {
+    constructor() {
+        const config = (0, index_js_2.getConfig)();
+        this.config = config.socketServer;
+        this.channelSeparator = config.mainServer.channelSeparator || '/';
+        this.socket = undefined;
+        this.io = undefined;
+    }
+    /**
+     * Factory method: create and initialize SocketServer
+     *
+     * @returns Fully initialized SocketServer instance
+     */
+    static async create() {
+        const instance = new SocketServer();
+        await instance.init();
+        return instance;
+    }
+    /**
+     * Initialize SocketIO server
+     *
+     * Acquires an available port then creates a SocketIO Server instance.
+     * The port number is written to process.env.EE_SOCKET_PORT for other modules to access.
+     */
+    async init() {
+        if (this.config.enable === false) {
+            return;
+        }
+        const port = await (0, index_js_4.getPort)({ port: this.config.port });
+        if (!port) {
+            throw new Error('[ee-core] [socket/socketServer] socekt port required, and must be a number !');
+        }
+        index_js_1.coreLogger.info('[socket/socketServer] port is:', port);
+        process.env.EE_SOCKET_PORT = String(port);
+        this.config.port = port;
+        this.io = new socket_io_1.Server(port, this.config);
+        this.connect();
+    }
+    /**
+     * Listen for client connections and handle messages
+     *
+     * After client connects, listens on the configured channel (default 'socket-channel').
+     * Upon receiving a message, routes via cmd path to the corresponding controller method for execution.
+     *
+     * Message format: { cmd: string, args: unknown }
+     * Return method: Results are sent back to client via callback function
+     */
+    connect() {
+        const controller = (0, index_js_3.getController)();
+        if (!this.io)
+            return;
+        this.io.on('connection', (socket) => {
+            const channel = this.config.channel || channel_js_1.SocketIO.partySoftware;
+            this.socket = socket;
+            socket.on(channel, async (message, callback) => {
+                index_js_1.coreLogger.info('[socket/socketServer] socket id:' + socket.id + ' message cmd: ' + message.cmd);
+                try {
+                    const cmd = message.cmd;
+                    const args = message.args;
+                    debugLog('[socket] channel %s', cmd);
+                    const fn = (0, utils_js_1.resolveControllerFn)(controller, cmd, this.channelSeparator);
+                    if (!fn)
+                        throw new Error('function not exists');
+                    const result = await fn.call(controller, args);
+                    if (callback) {
+                        callback(result);
+                    }
+                }
+                catch (err) {
+                    index_js_1.coreLogger.error('[socket/socketServer] throw error:', err);
+                    // Return error to client so it's not silently lost
+                    if (callback) {
+                        callback({ __EE_ERROR__: true, message: err instanceof Error ? err.message : String(err) });
+                    }
+                }
+            });
+        });
+    }
+}
+exports.SocketServer = SocketServer;
+//# sourceMappingURL=socketServer.js.map

package/dist/cjs/socket/socketServer.js.map

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

package/dist/cjs/socket/utils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolve controller function from channel/command path string
+ *
+ * Splits cmd by separator, then traverses the controller object tree level by level to find the corresponding function.
+ * Example: cmd='controller/user/add', separator='/' → looks up controller.user.add
+ *
+ * @param controller - Controller method mapping object
+ * @param cmd - Channel/command path string (non-string types return null directly)
+ * @param separator - Path separator
+ * @returns Controller method function, or null if resolution fails
+ */
+export declare function resolveControllerFn(controller: Record<string, unknown>, cmd: string, separator: string): ((...args: unknown[]) => unknown) | null;
+//# sourceMappingURL=utils.d.ts.map

package/dist/cjs/socket/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/socket/utils.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,IAAI,CAoB1C"}

package/dist/cjs/socket/utils.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveControllerFn = resolveControllerFn;
+/**
+ * @module socket/utils
+ * @description Shared utility functions for the socket module.
+ * Provides controller function resolution, used by HttpServer, IpcServer, and SocketServer.
+ */
+const type_check_js_1 = require("../utils/type_check.js");
+const index_js_1 = require("../log/index.js");
+/**
+ * Resolve controller function from channel/command path string
+ *
+ * Splits cmd by separator, then traverses the controller object tree level by level to find the corresponding function.
+ * Example: cmd='controller/user/add', separator='/' → looks up controller.user.add
+ *
+ * @param controller - Controller method mapping object
+ * @param cmd - Channel/command path string (non-string types return null directly)
+ * @param separator - Path separator
+ * @returns Controller method function, or null if resolution fails
+ */
+function resolveControllerFn(controller, cmd, separator) {
+    // Guard: non-string types (e.g., numbers passed via WebSocket) return directly
+    if (typeof cmd !== 'string')
+        return null;
+    const actions = cmd.split(separator);
+    let obj = { controller };
+    for (const key of actions) {
+        obj = obj[key];
+        if (!obj) {
+            index_js_1.coreLogger.error(`[resolveControllerFn] class or function '${key}' not exists in path '${cmd}'`);
+            return null;
+        }
+    }
+    if (!(0, type_check_js_1.isFunction)(obj)) {
+        index_js_1.coreLogger.error(`[resolveControllerFn] resolved path '${cmd}' is not a function`);
+        return null;
+    }
+    return obj;
+}
+//# sourceMappingURL=utils.js.map

package/dist/cjs/socket/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/socket/utils.ts"],"names":[],"mappings":";;AAmBA,kDAwBC;AA3CD;;;;GAIG;AACH,0DAAoD;AACpD,8CAA6C;AAE7C;;;;;;;;;;GAUG;AACH,SAAgB,mBAAmB,CACjC,UAAmC,EACnC,GAAW,EACX,SAAiB;IAEjB,+EAA+E;IAC/E,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEzC,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACrC,IAAI,GAAG,GAA4B,EAAE,UAAU,EAAE,CAAC;IAClD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,GAAG,GAAG,GAAG,CAAC,GAAG,CAA4B,CAAC;QAC1C,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,qBAAU,CAAC,KAAK,CAAC,4CAA4C,GAAG,yBAAyB,GAAG,GAAG,CAAC,CAAC;YACjG,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,IAAI,CAAC,IAAA,0BAAU,EAAC,GAAG,CAAC,EAAE,CAAC;QACrB,qBAAU,CAAC,KAAK,CAAC,wCAAwC,GAAG,qBAAqB,CAAC,CAAC;QACnF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,GAAiD,CAAC;AAC3D,CAAC"}

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

@@ -0,0 +1,2 @@
+export { SqliteStorage } from './sqliteStorage.js';
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/cjs/storage/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteStorage = void 0;
+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

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

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

@@ -0,0 +1,117 @@
+import Database from 'better-sqlite3';
+/**
+ * SqliteStorage - SQLite database storage class
+ *
+ * Encapsulates the database instance creation flow of better-sqlite3, automatically inferring
+ * the storage mode based on the provided database name and completing initialization tasks
+ * such as directory creation and file path calculation.
+ *
+ * Storage modes:
+ * - memory: In-memory database, name is ":memory:", not persisted to disk
+ * - onlyName: Filename only (e.g. "app.db"), stored under {dataDir}/db/
+ * - relative: Relative path (e.g. "sub/app.db"), resolved relative to {dataDir}/db/
+ * - absolute: Absolute path (e.g. "/tmp/app.db"), uses the specified path directly
+ *
+ * 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.
+ */
+export declare class SqliteStorage {
+    /** Database name (original input value) */
+    name: string;
+    /** Storage mode: memory / onlyName / relative / absolute */
+    mode: string;
+    /** Absolute path of the directory containing the database file */
+    dbDir: string;
+    /** Database filename (only the filename part, excluding directory) */
+    fileName: string;
+    /** better-sqlite3 database instance */
+    db: Database.Database;
+    /**
+     * Create a SqliteStorage instance
+     *
+     * 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)
+     *
+     * @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>);
+    /**
+     * 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
+     *
+     * 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.).
+     *
+     * @param opt - better-sqlite3 database options, defaults merged with { timeout: 5000 }
+     * @returns better-sqlite3 Database instance
+     * @throws Asserts error if the database file was not created successfully in file mode
+     */
+    _initDB(opt?: Record<string, unknown>): Database.Database;
+    /**
+     * Extract the database filename
+     *
+     * - memory mode: Returns the ":memory:" original name directly
+     * - file mode: Uses path.basename to extract the pure filename part, removing directory prefix
+     *
+     * @param name - Original database name
+     * @returns Filename part (returns ":memory:" for memory mode, pure filename for file mode)
+     */
+    _formatFileName(name: string): string;
+    /**
+     * Create the directory for the database file
+     *
+     * The directory path is determined by storage mode:
+     * - absolute mode: Uses the directory part from the database name (path.dirname)
+     * - Other modes: Uses {dataDir}/db as the default directory
+     *
+     * If the directory does not exist, it is created automatically with permission 0o755
+     * (owner can read/write/execute, others can read/execute).
+     *
+     * @returns Absolute path of the directory containing the database file
+     */
+    _createDatabaseDir(): string;
+    /**
+     * Infer storage mode from the database name
+     *
+     * Inference logic:
+     * 1. Name is ":memory:" -> memory mode
+     * 2. Name contains path separators (/ or \):
+     *    - Absolute path -> absolute mode
+     *    - Relative path -> relative mode
+     * 3. Name contains no path separators -> onlyName mode
+     *
+     * @param name - Database name or path
+     * @returns Storage mode string: memory / onlyName / relative / absolute
+     */
+    getMode(name: string): string;
+    /**
+     * Get the directory containing the database file
+     *
+     * @returns Absolute path of the database directory
+     */
+    getDbDir(): string;
+    /**
+     * Get the full path of the database file
+     *
+     * Composed by joining dbDir and fileName, only meaningful for file modes
+     * (in memory mode this path has no practical use).
+     *
+     * @returns Absolute path of the database file
+     */
+    getFilePath(): string;
+}
+//# sourceMappingURL=sqliteStorage.d.ts.map

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

@@ -0,0 +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"}

package/dist/cjs/storage/sqliteStorage.js

@@ -0,0 +1,197 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteStorage = void 0;
+/**
+ * @module storage/sqliteStorage
+ * @description SQLite database storage module. Based on better-sqlite3, provides synchronous database operations,
+ * supporting three database file location modes (name only, relative path, absolute path) and in-memory database (:memory:).
+ *
+ * Core responsibilities:
+ * - Automatically determine storage mode based on database name (onlyName / relative / absolute / memory)
+ * - Automatically create the database directory (ensures the directory exists before opening the database file)
+ * - Prevent path traversal attacks (validates that ".." is not present in the name during construction)
+ * - Provide a unified interface for obtaining database file paths
+ *
+ * Usage examples:
+ * ```ts
+ * // Name-only mode: file stored at {dataDir}/db/{name}.db
+ * const db1 = new SqliteStorage('myapp.db');
+ *
+ * // Relative path mode: file stored at {dataDir}/db/sub/myapp.db
+ * const db2 = new SqliteStorage('sub/myapp.db');
+ *
+ * // Absolute path mode: file stored at the specified path
+ * const db3 = new SqliteStorage('/tmp/data/myapp.db');
+ *
+ * // In-memory mode: not persisted, data is lost when the process exits
+ * const db4 = new SqliteStorage(':memory:');
+ * ```
+ */
+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");
+/**
+ * SqliteStorage - SQLite database storage class
+ *
+ * Encapsulates the database instance creation flow of better-sqlite3, automatically inferring
+ * the storage mode based on the provided database name and completing initialization tasks
+ * such as directory creation and file path calculation.
+ *
+ * Storage modes:
+ * - memory: In-memory database, name is ":memory:", not persisted to disk
+ * - onlyName: Filename only (e.g. "app.db"), stored under {dataDir}/db/
+ * - relative: Relative path (e.g. "sub/app.db"), resolved relative to {dataDir}/db/
+ * - absolute: Absolute path (e.g. "/tmp/app.db"), uses the specified path directly
+ *
+ * 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.
+ */
+class SqliteStorage {
+    /**
+     * Create a SqliteStorage instance
+     *
+     * 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)
+     *
+     * @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 = {}) {
+        (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`);
+        this.name = name;
+        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
+     *
+     * 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.).
+     *
+     * @param opt - better-sqlite3 database options, defaults merged with { timeout: 5000 }
+     * @returns better-sqlite3 Database instance
+     * @throws Asserts error if the database file was not created successfully in file mode
+     */
+    _initDB(opt = {}) {
+        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);
+        // 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;
+    }
+    /**
+     * Extract the database filename
+     *
+     * - memory mode: Returns the ":memory:" original name directly
+     * - file mode: Uses path.basename to extract the pure filename part, removing directory prefix
+     *
+     * @param name - Original database name
+     * @returns Filename part (returns ":memory:" for memory mode, pure filename for file mode)
+     */
+    _formatFileName(name) {
+        if (this.mode === 'memory') {
+            return name;
+        }
+        return path_1.default.basename(name);
+    }
+    /**
+     * Create the directory for the database file
+     *
+     * The directory path is determined by storage mode:
+     * - absolute mode: Uses the directory part from the database name (path.dirname)
+     * - Other modes: Uses {dataDir}/db as the default directory
+     *
+     * If the directory does not exist, it is created automatically with permission 0o755
+     * (owner can read/write/execute, others can read/execute).
+     *
+     * @returns Absolute path of the directory containing the database file
+     */
+    _createDatabaseDir() {
+        let dbDir = path_1.default.join((0, index_js_1.getDataDir)(), 'db');
+        if (this.mode === 'absolute') {
+            // Absolute path mode: directory is taken from the path part of the name, not the default data/db
+            dbDir = path_1.default.dirname(this.name);
+        }
+        if (!fs_1.default.existsSync(dbDir)) {
+            (0, helper_js_1.mkdir)(dbDir, { mode: 0o755 });
+        }
+        return dbDir;
+    }
+    /**
+     * Infer storage mode from the database name
+     *
+     * Inference logic:
+     * 1. Name is ":memory:" -> memory mode
+     * 2. Name contains path separators (/ or \):
+     *    - Absolute path -> absolute mode
+     *    - Relative path -> relative mode
+     * 3. Name contains no path separators -> onlyName mode
+     *
+     * @param name - Database name or path
+     * @returns Storage mode string: memory / onlyName / relative / absolute
+     */
+    getMode(name) {
+        // Memory mode
+        if (name === ':memory:') {
+            return 'memory';
+        }
+        // Path mode
+        const normalized = name.replace(/[/\\]/g, '/');
+        if (normalized.indexOf('/') !== -1) {
+            return path_1.default.isAbsolute(name) ? 'absolute' : 'relative';
+        }
+        return 'onlyName';
+    }
+    /**
+     * Get the directory containing the database file
+     *
+     * @returns Absolute path of the database directory
+     */
+    getDbDir() {
+        return this.dbDir;
+    }
+    /**
+     * Get the full path of the database file
+     *
+     * Composed by joining dbDir and fileName, only meaningful for file modes
+     * (in memory mode this path has no practical use).
+     *
+     * @returns Absolute path of the database file
+     */
+    getFilePath() {
+        return path_1.default.join(this.dbDir, this.fileName);
+    }
+}
+exports.SqliteStorage = SqliteStorage;
+//# sourceMappingURL=sqliteStorage.js.map

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

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