@ix-xs/node-comfort 1.1.2 → 1.1.31

package/types/src/SQLite.d.ts

@@ -0,0 +1,391 @@
+export = SQLite;
+declare class SQLite {
+    /**
+     * Creates a new SQLite database connection.
+     *
+     * The database file and its parent folders are created if necessary.
+     * WAL journal mode and foreign key support are enabled automatically.
+     *
+     * @param {string} [path] - Path to the SQLite database file.
+     *
+     * @example
+     * const db = new SQLite();
+     *
+     * @example
+     * const db = new SQLite("data/my-app.sqlite");
+     */
+    constructor(path?: string);
+    /**
+     * Executes a raw SQL statement using `run()`.
+     *
+     * Use this for custom SQL that is not covered by the helper methods.
+     * This method is intended for statements such as:
+     * - `INSERT`
+     * - `UPDATE`
+     * - `DELETE`
+     * - `CREATE INDEX`
+     * - PRAGMA writes
+     *
+     * @param {string} sql - SQL statement.
+     * @param {any[]|any} [params=[]] - Parameters to bind.
+     * @returns {Promise<{ changes: number, lastInsertRowid: bigint|number } | { error: string }>}
+     */
+    exec(sql: string, params?: any[] | any): Promise<{
+        changes: number;
+        lastInsertRowid: bigint | number;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Executes a raw SQL query and returns the first row.
+     *
+     * @param {string} sql - SQL query.
+     * @param {any[]|any} [params=[]] - Parameters to bind.
+     * @returns {Promise<object|undefined|{ error: string }>}
+     */
+    queryOne(sql: string, params?: any[] | any): Promise<object | undefined | {
+        error: string;
+    }>;
+    /**
+     * Executes a raw SQL query and returns all rows.
+     *
+     * @param {string} sql - SQL query.
+     * @param {any[]|any} [params=[]] - Parameters to bind.
+     * @returns {Promise<object[]|{ error: string }>}
+     */
+    queryAll(sql: string, params?: any[] | any): Promise<object[] | {
+        error: string;
+    }>;
+    /**
+     * Creates a table and stores its schema in memory.
+     *
+     * This method supports both the new `columns` property and the legacy
+     * `options` property for backward compatibility.
+     *
+     * @param {{
+     *   name: string,
+     *   columns?: Record<string, {
+     *     type: "INTEGER"|"TEXT"|"REAL"|"BLOB"|"NUMERIC",
+     *     primaryKey?: boolean,
+     *     autoincrement?: boolean,
+     *     notNull?: boolean,
+     *     unique?: boolean,
+     *     defaultValue?: any,
+     *     values?: any[],
+     *     references?: { table: string, column: string },
+     *     onDelete?: string,
+     *     onUpdate?: string
+     *   }>,
+     *   options?: Record<string, any>,
+     *   constraints?: Array<
+     *     | { type: "unique", columns: string[] }
+     *     | { type: "primaryKey", columns: string[] }
+     *     | { type: "check", expression: string }
+     *     | {
+     *         type: "foreignKey",
+     *         columns: string[],
+     *         references: { table: string, columns: string[] },
+     *         onDelete?: string,
+     *         onUpdate?: string
+     *       }
+     *   >,
+     *   indexes?: Array<{
+     *     name?: string,
+     *     columns: string[],
+     *     unique?: boolean
+     *   }>
+     * }} table - Table definition.
+     * @returns {Promise<{ ok: true } | { error: string }>}
+     *
+     * @example
+     * await db.createTable({
+     *   name: "Post",
+     *   columns: {
+     *     id: { type: "INTEGER", primaryKey: true, autoincrement: true },
+     *     userId: {
+     *       type: "INTEGER",
+     *       notNull: true,
+     *       references: { table: "User", column: "id" },
+     *       onDelete: "CASCADE"
+     *     },
+     *     title: { type: "TEXT", notNull: true }
+     *   },
+     *   indexes: [{ columns: ["userId"] }]
+     * });
+     */
+    createTable(table: {
+        name: string;
+        columns?: Record<string, {
+            type: "INTEGER" | "TEXT" | "REAL" | "BLOB" | "NUMERIC";
+            primaryKey?: boolean;
+            autoincrement?: boolean;
+            notNull?: boolean;
+            unique?: boolean;
+            defaultValue?: any;
+            values?: any[];
+            references?: {
+                table: string;
+                column: string;
+            };
+            onDelete?: string;
+            onUpdate?: string;
+        }>;
+        options?: Record<string, any>;
+        constraints?: Array<{
+            type: "unique";
+            columns: string[];
+        } | {
+            type: "primaryKey";
+            columns: string[];
+        } | {
+            type: "check";
+            expression: string;
+        } | {
+            type: "foreignKey";
+            columns: string[];
+            references: {
+                table: string;
+                columns: string[];
+            };
+            onDelete?: string;
+            onUpdate?: string;
+        }>;
+        indexes?: Array<{
+            name?: string;
+            columns: string[];
+            unique?: boolean;
+        }>;
+    }): Promise<{
+        ok: true;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Creates an index on an existing table.
+     *
+     * Composite indexes are supported by passing multiple columns.
+     *
+     * @param {string} tableName - Table name.
+     * @param {{
+     *   name?: string,
+     *   columns: string[],
+     *   unique?: boolean
+     * }} index - Index definition.
+     * @returns {Promise<{ ok: true } | { error: string }>}
+     *
+     * @example
+     * await db.createIndex("UserAuthMethod", {
+     *   columns: ["provider", "providerUserId"],
+     *   unique: true
+     * });
+     */
+    createIndex(tableName: string, index: {
+        name?: string;
+        columns: string[];
+        unique?: boolean;
+    }): Promise<{
+        ok: true;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Drops a table and removes its model definition.
+     *
+     * @param {string} tableName - Table name.
+     * @returns {Promise<{ ok: true } | { error: string }>}
+     */
+    deleteTable(tableName: string): Promise<{
+        ok: true;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Deletes all rows from a table.
+     *
+     * @param {string} tableName - Table name.
+     * @returns {Promise<{ ok: true } | { error: string }>}
+     */
+    clearTable(tableName: string): Promise<{
+        ok: true;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Returns a single row matching a plain-object WHERE clause.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} [where={}] - Conditions.
+     * @returns {Promise<object|undefined|{ error: string }>}
+     */
+    get(tableName: string, where?: Record<string, any>): Promise<object | undefined | {
+        error: string;
+    }>;
+    /**
+     * Returns multiple rows from a table.
+     *
+     * Supports:
+     * - exact-match filters via `where`
+     * - custom ordering
+     * - pagination via `limit` and `offset`
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} [where={}] - Exact-match conditions.
+     * @param {{
+     *   limit?: number,
+     *   offset?: number,
+     *   orderBy?: string,
+     *   direction?: "ASC"|"DESC"
+     * }} [options={}] - Query options.
+     * @returns {Promise<object[] | { error: string }>}
+     *
+     * @example
+     * const posts = await db.getAll("Post", { userId: 1 }, {
+     *   limit: 20,
+     *   offset: 0,
+     *   orderBy: "createdAt",
+     *   direction: "DESC"
+     * });
+     */
+    getAll(tableName: string, where?: Record<string, any>, options?: {
+        limit?: number;
+        offset?: number;
+        orderBy?: string;
+        direction?: "ASC" | "DESC";
+    }): Promise<object[] | {
+        error: string;
+    }>;
+    /**
+     * Inserts a new row into a table.
+     *
+     * This method performs a plain `INSERT`.
+     * If a unique constraint is violated, SQLite will throw an error.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} data - Row to insert.
+     * @returns {Promise<{ ok: true, lastInsertRowid: bigint|number, changes: number } | { error: string }>}
+     */
+    insert(tableName: string, data: Record<string, any>): Promise<{
+        ok: true;
+        lastInsertRowid: bigint | number;
+        changes: number;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Updates one or more rows matching a WHERE clause.
+     *
+     * This method performs a plain `UPDATE`.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} data - Fields to update.
+     * @param {Record<string, any>} where - Conditions used to select rows.
+     * @returns {Promise<{ ok: true, changes: number } | { error: string }>}
+     */
+    update(tableName: string, data: Record<string, any>, where: Record<string, any>): Promise<{
+        ok: true;
+        changes: number;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Inserts or updates a row using SQLite `ON CONFLICT DO UPDATE`.
+     *
+     * This is safer than `INSERT OR REPLACE` because it does not delete
+     * and recreate the row.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} data - Row data.
+     * @param {string[]} conflict - Columns that define the conflict target.
+     * @returns {Promise<{ ok: true, changes: number, lastInsertRowid: bigint|number } | { error: string }>}
+     *
+     * @example
+     * await db.upsert("UserAuthMethod", {
+     *   userId: 1,
+     *   provider: "google",
+     *   providerUserId: "123"
+     * }, ["provider", "providerUserId"]);
+     */
+    upsert(tableName: string, data: Record<string, any>, conflict?: string[]): Promise<{
+        ok: true;
+        changes: number;
+        lastInsertRowid: bigint | number;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Backward-compatible helper that inserts or updates a row.
+     *
+     * Behavior:
+     * - If `where` is provided, the existing row is loaded and merged with `data`,
+     *   then updated if found or inserted if not found.
+     * - If `where` is not provided but `data.id` exists, lookup is performed on `id`.
+     * - If no existing row is found, a new row is inserted.
+     *
+     * This method is intentionally simple, but for production-grade control,
+     * prefer using `insert()`, `update()`, or `upsert()`.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} data - Row data.
+     * @param {Record<string, any>|null} [where=null] - Lookup condition.
+     * @returns {Promise<{ ok: true } | { error: string }>}
+     */
+    set(tableName: string, data: Record<string, any>, where?: Record<string, any> | null): Promise<{
+        ok: true;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Deletes rows matching a WHERE clause.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} where - Conditions.
+     * @returns {Promise<{ ok: true, changes: number } | { error: string }>}
+     */
+    delete(tableName: string, where: Record<string, any>): Promise<{
+        ok: true;
+        changes: number;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Counts rows matching a WHERE clause.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} [where={}] - Conditions.
+     * @returns {Promise<number | { error: string }>}
+     */
+    count(tableName: string, where?: Record<string, any>): Promise<number | {
+        error: string;
+    }>;
+    /**
+     * Runs multiple operations inside a transaction.
+     *
+     * If the callback throws, the transaction is rolled back.
+     * If the callback completes successfully, the transaction is committed.
+     *
+     * The callback may be synchronous or asynchronous.
+     *
+     * @template T
+     * @param {() => T|Promise<T>} callback - Function to execute inside the transaction.
+     * @returns {Promise<T | { error: string }>}
+     *
+     * @example
+     * const result = await db.transaction(async () => {
+     *   await db.insert("User", { email: "a@b.com", createdAt: Date.now() });
+     *   await db.insert("Profile", { userId: 1, nickname: "John" });
+     *   return { ok: true };
+     * });
+     */
+    transaction<T>(callback: () => T | Promise<T>): Promise<T | {
+        error: string;
+    }>;
+    /**
+     * Closes the underlying SQLite connection.
+     *
+     * @example
+     * db.close();
+     */
+    close(): void;
+    #private;
+}
+//# sourceMappingURL=SQLite.d.ts.map

package/types/src/SQLite.d.ts.map

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

package/types/src/Utils.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Waits for a given number of milliseconds.
+ *
+ * @example
+ * await nodeComfort.wait(500); // waits 500 ms
+ *
+ * @param {number} ms - Delay in milliseconds.
+ * @returns {Promise<void>} A promise that resolves after the delay.
+ */
+export function wait(ms: number): Promise<void>;
+/**
+ * Polls a predicate at a given interval and emits events when it matches or times out.
+ *
+ * The predicate is evaluated every `options.interval` milliseconds (default: 50 ms).
+ * Be careful with the default interval: 50 ms is very frequent polling and can be
+ * unnecessarily CPU‑intensive if your predicate or trigger handlers are heavy.
+ * When `options.max` is `null`, the predicate can match indefinitely (infinite triggers),
+ * so you should choose an interval that makes sense for your use‑case.
+ *
+ * A `when(...)` task is one‑shot: once it has been stopped (manually or via `max`/`timeout`),
+ * calling `.start()` again on the same task will not restart it.
+ *
+ * @param {boolean|Promise<boolean>|(() => boolean|Promise<boolean>)} predicate
+ *        Condition to evaluate at each tick, or a function returning it.
+ * @param {*} [payload={}]
+ *        Value passed to listeners when events are emitted (e.g. an object or message).
+ * @param {object} [options]
+ * @param {number} [options.interval=50]
+ *        Polling interval in milliseconds. Increase this value if your predicate is
+ *        expensive or you expect many triggers without a `max` limit.
+ * @param {number|null} [options.timeout=null]
+ *        Maximum time in milliseconds before emitting a "timeout" event and stopping.
+ *        If `null`, no timeout is applied.
+ * @param {number|null} [options.max=null]
+ *        Maximum number of successful predicate evaluations ("trigger" events) before
+ *        automatically stopping. If `null`, triggers are infinite until `stop()` is called.
+ *
+ * @example
+ * // Basic usage: infinite triggers every 50 ms (default interval) – use with caution.
+ * const task = nodeComfort.when(() => true, { message: "Ok" });
+ *
+ * task
+ *   .on("trigger", (payload) => {
+ *     console.log(payload.message);
+ *     // task.stop(); // stop when you’re done
+ *   })
+ *   .start();
+ *
+ * @example
+ * // Safer usage: limit triggers and/or lower polling frequency.
+ * nodeComfort.when(() => true, { message: "Ok" }, { max: 1, interval: 500 })
+ *   .on("trigger", (payload) => {
+ *     console.log(payload.message);
+ *   })
+ *   .on("timeout", (payload) => {
+ *     console.log("Timed out", payload);
+ *   })
+ *   .start();
+ *
+ * @returns {{
+ *   start: () => any,
+ *   stop: () => any,
+ *   on: <E extends "error"|"trigger"|"timeout">(event: E, handler: E extends "error"
+ *       ? (error: unknown) => void|Promise<void>
+ *       : (payload: any) => void|Promise<void>) => any
+ * }} A small task controller with `start`, `stop` and `on`.
+ */
+export function when(predicate: boolean | Promise<boolean> | (() => boolean | Promise<boolean>), payload?: any, options?: {
+    interval?: number | undefined;
+    timeout?: number | null | undefined;
+    max?: number | null | undefined;
+}): {
+    start: () => any;
+    stop: () => any;
+    on: <E extends "error" | "trigger" | "timeout">(event: E, handler: E extends "error" ? (error: unknown) => void | Promise<void> : (payload: any) => void | Promise<void>) => any;
+};
+/**
+ * Installs process-level safety nets for errors, exits and signals.
+ *
+ * By default, it:
+ * - logs uncaught exceptions and unhandled rejections,
+ * - logs process exit codes,
+ * - logs SIGINT/SIGTERM/SIGQUIT and exits with code 0.
+ *
+ * You can override each handler with `.on(event, handler)`.
+ *
+ * @example
+ * // Use defaults:
+ * nodeComfort.dontCrash();
+ *
+ * @example
+ * // Custom error handler:
+ * nodeComfort.dontCrash().on("error", (err) => {
+ *   console.error("Global error:", err);
+ *   process.exit(1);
+ * });
+ *
+ * @returns {{
+ *   on: <E extends "error"|"exit"|"sig"|"beforeExit">(event: E, handler?: (
+ *     E extends "error" ? (error: Error|unknown) => void|Promise<void> :
+ *     E extends "exit" ? (code: number) => void|Promise<void> :
+ *     E extends "sig" ? (signal: "SIGINT"|"SIGTERM"|"SIGQUIT") => void|Promise<void> :
+ *     (code: number) => void|Promise<void>
+ *   )) => any
+ * }} A small controller to configure global handlers.
+ */
+export function dontCrash(): {
+    on: <E extends "error" | "exit" | "sig" | "beforeExit">(event: E, handler?: (E extends "error" ? (error: Error | unknown) => void | Promise<void> : E extends "exit" ? (code: number) => void | Promise<void> : E extends "sig" ? (signal: "SIGINT" | "SIGTERM" | "SIGQUIT") => void | Promise<void> : (code: number) => void | Promise<void>)) => any;
+};
+/**
+ * Safely stringifies a value to pretty-printed JSON (4 spaces indent).
+ *
+ * @param {*} value - Value to stringify.
+ * @returns {string} JSON string representation.
+ */
+export function JSONString(value: any): string;
+/**
+ * Parses a JSON string.
+ *
+ * @param {string} value - JSON string to parse.
+ * @returns {*} Parsed value.
+ */
+export function JSONParse(value: string): any;
+//# sourceMappingURL=Utils.d.ts.map

package/types/src/Utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Utils.d.ts","sourceRoot":"","sources":["../../src/Utils.js"],"names":[],"mappings":"AAME;;;;;;;;GAQG;AACH,yBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAIzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,gCA7CW,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,CAAC,MAAM,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,CAAC,YAEzD,GAAC,YAGT;IAAyB,QAAQ;IAGH,OAAO;IAGP,GAAG;CAIjC,GAsBU;IACR,KAAK,EAAE,MAAM,GAAG,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,CAAC;IAChB,EAAE,EAAE,CAAC,CAAC,SAAS,OAAO,GAAC,SAAS,GAAC,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,SAAS,OAAO,GAC1E,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,GACtC,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,CAAA;CACnD,CAsIH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,6BATa;IACR,EAAE,EAAE,CAAC,CAAC,SAAS,OAAO,GAAC,MAAM,GAAC,KAAK,GAAC,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,CACpE,CAAC,SAAS,OAAO,GAAG,CAAC,KAAK,EAAE,KAAK,GAAC,OAAO,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,GAChE,CAAC,SAAS,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,GACvD,CAAC,SAAS,KAAK,GAAG,CAAC,MAAM,EAAE,QAAQ,GAAC,SAAS,GAAC,SAAS,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,GACpF,CAAO,IAAI,EAAE,MAAM,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,CACrC,KAAK,GAAG,CAAA;CACV,CAiEH;AAED;;;;;GAKG;AACH,kCAHW,GAAC,GACC,MAAM,CAIlB;AAED;;;;;GAKG;AACH,iCAHW,MAAM,GACJ,GAAC,CAIb"}