ee-core 5.0.0-beta.2 → 5.0.0-beta.5

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

@@ -1 +1 @@
-{"version":3,"file":"ipcServer.js","sourceRoot":"","sources":["../../../src/socket/ipcServer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ipcServer.js","sourceRoot":"","sources":["../../../src/socket/ipcServer.ts"],"names":[],"mappings":";;;;;;AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,kDAA0B;AAC1B,uCAAmC;AACnC,8CAA6C;AAC7C,qDAAuD;AACvD,kEAAwD;AACxD,iDAA+C;AAC/C,yCAAiD;AAEjD,MAAM,QAAQ,GAAG,IAAA,eAAK,EAAC,0BAA0B,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,MAAa,SAAS;IAMpB;QACE,IAAI,CAAC,gBAAgB,GAAG,IAAA,oBAAS,GAAE,CAAC,UAAU,CAAC,gBAAgB,IAAI,GAAG,CAAC;QACvE,IAAI,CAAC,SAAS,GAAG,YAAY,CAAC;QAC9B,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAED;;OAEG;IACH,IAAI;QACF,MAAM,UAAU,GAAG,IAAA,wBAAa,GAAE,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;;;;OASG;IACH,IAAI,CAAC,GAA4B,EAAE,QAAgB;QACjD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC9B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,GAAG,KAAK,aAAa;gBAAE,SAAS;YAEpC,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACxB,MAAM,aAAa,GAAG,QAAQ,GAAG,GAAG,GAAG,GAAG,CAAC;YAC3C,qFAAqF;YACrF,IAAI,MAAM,IAAK,MAAkC,CAAC,wBAAO,CAAC,KAAK,IAAI,EAAE,CAAC;gBACpE,IAAI,CAAC,QAAQ,CAAC,MAAiC,EAAE,aAAa,CAAC,CAAC;YAClE,CAAC;iBAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACtC,IAAI,CAAC,IAAI,CAAC,MAAiC,EAAE,aAAa,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAkC,EAAE,aAAqB;QAChE,MAAM,UAAU,GAAG,IAAA,wBAAa,GAAE,CAAC;QACnC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACpC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,UAAU,GAAG,GAAG,aAAa,IAAI,GAAG,EAAE,CAAC;YAC7C,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YAClE,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAC;YAE3C,8BAA8B;YAC9B,8EAA8E;YAC9E,gEAAgE;YAChE,kBAAO,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;gBAC1C,IAAI,CAAC;oBACH,MAAM,EAAE,GAAG,IAAA,8BAAmB,EAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;oBAC3E,IAAI,CAAC,EAAE;wBAAE,OAAO;oBAChB,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;oBACxD,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC;gBAC7B,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,qBAAU,CAAC,KAAK,CAAC,yCAAyC,EAAE,CAAC,CAAC,CAAC;oBAC/D,oFAAoF;oBACpF,KAAK,CAAC,WAAW,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClG,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,kDAAkD;YAClD,8FAA8F;YAC9F,kBAAO,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;gBAC9C,MAAM,EAAE,GAAG,IAAA,8BAAmB,EAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;gBAC3E,IAAI,CAAC,EAAE;oBAAE,OAAO,SAAS,CAAC;gBAC1B,OAAO,MAAM,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;YAClD,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;CACF;AAzFD,8BAyFC"}

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

@@ -1,12 +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;
-    constructor();
+    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

@@ -1 +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;AAI5D,qBAAa,YAAY;IACvB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;IAC7C,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;;IASjB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB3B,OAAO,IAAI,IAAI;CAqChB"}
+{"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

@@ -4,22 +4,59 @@ var __importDefault = (this && this.__importDefault) || function (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 type_check_js_1 = require("../utils/type_check.js");
 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.init();
+        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;
@@ -34,6 +71,15 @@ class SocketServer {
         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)
@@ -46,19 +92,8 @@ class SocketServer {
                 try {
                     const cmd = message.cmd;
                     const args = message.args;
-                    let fn = null;
                     debugLog('[socket] channel %s', cmd);
-                    if ((0, type_check_js_1.isString)(cmd)) {
-                        const actions = cmd.split(this.channelSeparator);
-                        debugLog('[findFn] channel %o', actions);
-                        let obj = { controller };
-                        actions.forEach((key) => {
-                            obj = obj[key];
-                            if (!obj)
-                                throw new Error(`class or function '${key}' not exists`);
-                        });
-                        fn = obj;
-                    }
+                    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);
@@ -68,6 +103,10 @@ class SocketServer {
                 }
                 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) });
+                    }
                 }
             });
         });

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

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

@@ -1,28 +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>);
     /**
-     * 初始化db
+     * 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;
     /**
-     * 创建storage目录
+     * 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;
     /**
-     * 获取file path 模式
+     * 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

@@ -1 +1 @@
-{"version":3,"file":"sqliteStorage.d.ts","sourceRoot":"","sources":["../../../src/storage/sqliteStorage.ts"],"names":[],"mappings":"AAGA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAItC,qBAAa,aAAa;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAU3D;;OAEG;IACH,OAAO,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,QAAQ,CAAC,QAAQ;IAmB7D;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAOrC;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAa5B;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAiB7B,QAAQ,IAAI,MAAM;IAIlB,WAAW,IAAI,MAAM;CAGtB"}
+{"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

@@ -4,15 +4,78 @@ var __importDefault = (this && this.__importDefault) || function (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();
@@ -20,24 +83,41 @@ class SqliteStorage {
         this.db = this._initDB(opt);
     }
     /**
-     * 初始化db
+     * 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);
-        // 存储类型：db文件、内存(:memory:)
+        // 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') {
@@ -46,11 +126,21 @@ class SqliteStorage {
         return path_1.default.basename(name);
     }
     /**
-     * 创建storage目录
+     * 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)) {
@@ -59,24 +149,46 @@ class SqliteStorage {
         return dbDir;
     }
     /**
-     * 获取file path 模式
+     * 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';
         }
-        (0, assert_1.default)(path_1.default.extname(name) === '.db', `error: db ${name} file ext name must be .db`);
-        // 路径模式
+        // 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);
     }

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

@@ -1 +1 @@
-{"version":3,"file":"sqliteStorage.js","sourceRoot":"","sources":["../../../src/storage/sqliteStorage.ts"],"names":[],"mappings":";;;;;;AAAA,oDAA4B;AAC5B,4CAAoB;AACpB,gDAAwB;AACxB,oEAAsC;AACtC,kDAA2C;AAC3C,6CAA4C;AAE5C,MAAa,aAAa;IAOxB,YAAY,IAAY,EAAE,MAA+B,EAAE;QACzD,IAAA,gBAAM,EAAC,IAAI,EAAE,WAAW,IAAI,kBAAkB,CAAC,CAAC;QAEhD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACvC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,MAA+B,EAAE;QACvC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;QAEtD,yBAAyB;QACzB,IAAI,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC;QACvB,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAC9B,CAAC;QAED,MAAM,EAAE,GAAG,IAAI,wBAAQ,CAAC,MAAM,EAAE,OAA2B,CAAC,CAAC;QAE7D,qBAAqB;QACrB,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,IAAA,gBAAM,EAAC,YAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,aAAa,MAAM,aAAa,CAAC,CAAC;QAClE,CAAC;QAED,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;OAEG;IACH,eAAe,CAAC,IAAY;QAC1B,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,cAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,kBAAkB;QAChB,IAAI,KAAK,GAAG,cAAI,CAAC,IAAI,CAAC,IAAA,qBAAU,GAAE,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC7B,KAAK,GAAG,cAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,IAAA,iBAAK,EAAC,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAChC,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,IAAY;QAClB,OAAO;QACP,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YACxB,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,IAAA,gBAAM,EAAC,cAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,aAAa,IAAI,4BAA4B,CAAC,CAAC;QAEpF,OAAO;QACP,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAC/C,IAAI,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YACnC,OAAO,cAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC;QACzD,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,WAAW;QACT,OAAO,cAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC;CACF;AA5FD,sCA4FC"}
+{"version":3,"file":"sqliteStorage.js","sourceRoot":"","sources":["../../../src/storage/sqliteStorage.ts"],"names":[],"mappings":"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"}