@ix-xs/node-comfort 1.1.3 → 1.1.31

package/package.json

@@ -1,19 +1,16 @@
 {
 	"name": "@ix-xs/node-comfort",
-	"version": "1.1.3",
+	"version": "1.1.31",
 	"description": "Small collection of Node.js utilities: colorful logger, filesystem helper, SQLite wrapper, runtime type checks and async/process helpers.",
 	"main": "index.js",
-	"scripts": {
-		"test": "echo \"Error: no test specified\" && exit 1"
-	},
+  "types": "types/index.d.ts",
 	"keywords": [],
 	"author": "ix-xs",
-	"license": "MIT",
 	"type": "commonjs",
-    "engines": {
-        "node": ">=20.12.0"
-    },
-    "repository": {
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "repository": {
     "type": "git",
     "url": "https://github.com/ix-xs/node-comfort.git"
   },

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "nodenext",
+		"allowJs": true,
+		"declaration": true,
+		"emitDeclarationOnly": true,
+		"outDir": "types",
+		"declarationMap": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"moduleResolution": "nodenext",
+		"esModuleInterop": true,
+		"resolveJsonModule": true
+	},
+	"include": ["**/*"],
+	"exclude": ["node_modules", "types"]
+}

package/types/index.d.ts

@@ -0,0 +1,120 @@
+declare const _exports: {
+    SQLite: {
+        new (path?: string): SQLite;
+    };
+    wait(ms: number): Promise<void>;
+    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;
+    };
+    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;
+    };
+    JSONString(value: any): string;
+    JSONParse(value: string): any;
+    isArray(value: any): boolean;
+    isNumber(value: any): boolean;
+    isFunction(value: any): boolean;
+    isObject(value: any): boolean;
+    isBoolean(value: any): boolean;
+    isString(value: any): boolean;
+    isUndefined(value: any): boolean;
+    isNull(value: any): boolean;
+    isDate(value: any): boolean;
+    isMap(value: any): boolean;
+    isSet(value: any): boolean;
+    isError(value: any): boolean;
+    getEnv(value: string, envFilePath?: string): string | undefined;
+    createPath(path?: string): string;
+    getFoldersIn(path?: string, recursive?: boolean): string[] | undefined;
+    getFolder(path?: string): string | undefined;
+    getFilesIn(path?: string, recursive?: boolean): string[] | undefined;
+    getFile(path: string): string | undefined;
+    createFolder(path: string, force?: boolean): boolean | undefined;
+    createFile(path: string, force?: boolean, data?: string | object | null | undefined): boolean | undefined;
+    deleteFoldersIn(path?: string, filter?: (folder: string) => boolean): number | undefined;
+    deleteFolder(path: string): boolean | undefined;
+    deleteFilesIn(path?: string, recursive?: boolean, filter?: (file: string) => boolean): number | undefined;
+    deleteFile(path: string): boolean | undefined;
+    copyFoldersIn(options: {
+        dest: string;
+        path?: string | undefined;
+        recursive?: boolean | undefined;
+        withFiles?: boolean | undefined;
+        force?: boolean | undefined;
+        filter?: ((folder: string) => boolean) | undefined;
+    }): number | undefined;
+    copyFolder(options: {
+        dest: string;
+        path?: string | undefined;
+        recursive?: boolean | undefined;
+        withFiles?: boolean | undefined;
+        force?: boolean | undefined;
+    }): boolean | undefined;
+    copyFilesIn(options: {
+        dest: string;
+        path?: string | undefined;
+        recursive?: boolean | undefined;
+        force?: boolean | undefined;
+        filter?: ((file: string) => boolean) | undefined;
+    }): number | undefined;
+    copyFile(options: {
+        path: string;
+        dest: string;
+        force?: boolean | undefined;
+    }): boolean | undefined;
+    moveFoldersIn(options: {
+        dest: string;
+        path?: string | undefined;
+        recursive?: boolean | undefined;
+        withFiles?: boolean | undefined;
+        force?: boolean | undefined;
+        filter?: ((folder: string) => boolean) | undefined;
+    }): number | undefined;
+    moveFolder(options: {
+        path: string;
+        dest: string;
+        recursive?: boolean | undefined;
+        withFiles?: boolean | undefined;
+        force?: boolean | undefined;
+    }): boolean | undefined;
+    moveFilesIn(options: {
+        dest: string;
+        path?: string | undefined;
+        recursive?: boolean | undefined;
+        force?: boolean | undefined;
+        filter?: ((file: string) => boolean) | undefined;
+    }): number | undefined;
+    moveFile(options: {
+        path: string;
+        dest: string;
+        force?: boolean | undefined;
+    }): boolean | undefined;
+    readFile(path: string): string | undefined;
+    watch(options?: {
+        path?: string | undefined;
+        recursive?: boolean | undefined;
+        filter?: ((event: "rename" | "change", file: string) => boolean) | undefined;
+    }): {
+        on: <E extends "change" | "rename" | "all">(event: E, callback: E extends "all" ? (event: "change" | "rename", file: string) => void | Promise<void> : (file: string) => void | Promise<void>) => any;
+        stop: () => void;
+        pause: () => any;
+        resume: () => any;
+    } | undefined;
+    setTimestamp(value: boolean): Logger;
+    setDelimiter(options?: {
+        open?: string | undefined;
+        close?: string | undefined;
+    }): Logger;
+    log(content: any): Logger;
+    group(label: string): Logger;
+    groupEnd(): Logger;
+};
+export = _exports;
+import SQLite = require("./src/SQLite");
+//# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;iFAYi3N,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kCAAn0C,MAAM;;;;QAAuZ,MAAM;uBAAiX,MAAM;0BAAq/B,MAAM;gBAA0T,MAAM"}

package/types/src/Checker.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Checks if a value is a real Array.
+ *
+ * @example
+ * nodeComfort.Checker.isArray([1, 2, 3]);    // true
+ * nodeComfort.Checker.isArray("not array");  // false
+ *
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if the value is an Array.
+ */
+export function isArray(value: any): boolean;
+/**
+ * Checks if a value is a number (excluding NaN).
+ *
+ * @example
+ * nodeComfort.Checker.isNumber(42);          // true
+ * nodeComfort.Checker.isNumber(NaN);         // false
+ * nodeComfort.Checker.isNumber("42");        // false
+ *
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if the value is a finite number or Infinity/-Infinity.
+ */
+export function isNumber(value: any): boolean;
+/**
+ * Checks if a value is a function.
+ *
+ * @example
+ * nodeComfort.Checker.isFunction(() => {});  // true
+ * nodeComfort.Checker.isFunction(class {});  // true
+ * nodeComfort.Checker.isFunction("fn");      // false
+ *
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if the value is a function.
+ */
+export function isFunction(value: any): boolean;
+/**
+ * Checks if a value is a non-null object.
+ *
+ * Note: Arrays, Maps, Sets, Dates, etc. are also considered objects here.
+ *
+ * @example
+ * nodeComfort.Checker.isObject({});          // true
+ * nodeComfort.Checker.isObject([]);          // true
+ * nodeComfort.Checker.isObject(null);        // false
+ * nodeComfort.Checker.isObject("str");       // false
+ *
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if the value is a non-null object.
+ */
+export function isObject(value: any): boolean;
+/**
+ * Checks if a value is a boolean.
+ *
+ * @example
+ * nodeComfort.Checker.isBoolean(true);       // true
+ * nodeComfort.Checker.isBoolean(false);      // true
+ * nodeComfort.Checker.isBoolean(0);          // false
+ *
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if the value is a boolean.
+ */
+export function isBoolean(value: any): boolean;
+/**
+ * Checks if a value is a string.
+ *
+ * @example
+ * nodeComfort.Checker.isString("hello");     // true
+ * nodeComfort.Checker.isString(123);         // false
+ *
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if the value is a string.
+ */
+export function isString(value: any): boolean;
+/**
+ * Checks if a value is exactly undefined.
+ *
+ * @example
+ * nodeComfort.Checker.isUndefined(undefined);  // true
+ * nodeComfort.Checker.isUndefined(null);       // false
+ *
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if the value is undefined.
+ */
+export function isUndefined(value: any): boolean;
+/**
+ * Checks if a value is exactly null.
+ *
+ * @example
+ * nodeComfort.Checker.isNull(null);          // true
+ * nodeComfort.Checker.isNull(undefined);     // false
+ *
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if the value is null.
+ */
+export function isNull(value: any): boolean;
+/**
+ * Checks if a value is a built-in Date instance.
+ *
+ * Uses `util.types.isDate` under the hood to handle cross-realm Dates.
+ *
+ * @example
+ * nodeComfort.Checker.isDate(new Date());    // true
+ * nodeComfort.Checker.isDate("2024-01-01");  // false
+ *
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if the value is a Date instance.
+ */
+export function isDate(value: any): boolean;
+/**
+ * Checks if a value is a built-in Map instance.
+ *
+ * @example
+ * nodeComfort.Checker.isMap(new Map());      // true
+ * nodeComfort.Checker.isMap({});             // false
+ *
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if the value is a Map.
+ */
+export function isMap(value: any): boolean;
+/**
+ * Checks if a value is a built-in Set instance.
+ *
+ * @example
+ * nodeComfort.Checker.isSet(new Set());      // true
+ * nodeComfort.Checker.isSet([]);             // false
+ *
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if the value is a Set.
+ */
+export function isSet(value: any): boolean;
+/**
+ * Checks if a value is a native Error instance.
+ *
+ * Uses `util.types.isNativeError` to correctly handle errors from other realms.
+ *
+ * @example
+ * nodeComfort.Checker.isError(new Error("x"));      // true
+ * nodeComfort.Checker.isError(new TypeError("x"));  // true
+ * nodeComfort.Checker.isError({ message: "x" });    // false
+ *
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if the value is a native Error.
+ */
+export function isError(value: any): boolean;
+//# sourceMappingURL=Checker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Checker.d.ts","sourceRoot":"","sources":["../../src/Checker.js"],"names":[],"mappings":"AAQE;;;;;;;;;GASG;AACH,+BAHW,GAAC,GACC,OAAO,CAInB;AAED;;;;;;;;;;GAUG;AACH,gCAHW,GAAC,GACC,OAAO,CAInB;AAED;;;;;;;;;;GAUG;AACH,kCAHW,GAAC,GACC,OAAO,CAInB;AAED;;;;;;;;;;;;;GAaG;AACH,gCAHW,GAAC,GACC,OAAO,CAInB;AAED;;;;;;;;;;GAUG;AACH,iCAHW,GAAC,GACC,OAAO,CAInB;AAED;;;;;;;;;GASG;AACH,gCAHW,GAAC,GACC,OAAO,CAInB;AAED;;;;;;;;;GASG;AACH,mCAHW,GAAC,GACC,OAAO,CAInB;AAED;;;;;;;;;GASG;AACH,8BAHW,GAAC,GACC,OAAO,CAInB;AAED;;;;;;;;;;;GAWG;AACH,8BAHW,GAAC,GACC,OAAO,CAInB;AAED;;;;;;;;;GASG;AACH,6BAHW,GAAC,GACC,OAAO,CAInB;AAED;;;;;;;;;GASG;AACH,6BAHW,GAAC,GACC,OAAO,CAInB;AAED;;;;;;;;;;;;GAYG;AACH,+BAHW,GAAC,GACC,OAAO,CAInB"}

package/types/src/FS.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Reads an environment variable from process.env.
+ * @param {string} value - The environment variable name.
+ * @param {string} [envFilePath] - Reserved for future use.
+ * @returns {string|undefined} The environment value, or undefined if not set.
+ */
+export function getEnv(value: string, envFilePath?: string): string | undefined;
+/**
+ * Resolves a path even when it does not already exist.
+ * @param {string} [path=process.cwd()] - The path to resolve.
+ * @returns {string} The resolved path.
+ */
+export function createPath(path?: string): string;
+/**
+ * Returns folders found inside a path.
+ * @param {string} [path=process.cwd()] - The base path to inspect.
+ * @param {boolean} [recursive=true] - Whether to scan recursively.
+ * @returns {string[]|undefined} Matching folders, or undefined if the path cannot be resolved.
+ */
+export function getFoldersIn(path?: string, recursive?: boolean): string[] | undefined;
+/**
+ * Returns the resolved folder path.
+ * @param {string} [path=process.cwd()] - The folder path to resolve.
+ * @returns {string|undefined} The resolved folder path, or undefined if not found.
+ */
+export function getFolder(path?: string): string | undefined;
+/**
+ * Returns files found inside a path.
+ * @param {string} [path=process.cwd()] - The base path to inspect.
+ * @param {boolean} [recursive=true] - Whether to scan recursively.
+ * @returns {string[]|undefined} Matching files, or undefined if the path cannot be resolved.
+ */
+export function getFilesIn(path?: string, recursive?: boolean): string[] | undefined;
+/**
+ * Returns the resolved file path.
+ * @param {string} path - The file path to resolve.
+ * @returns {string|undefined} The resolved file path, or undefined if not found.
+ */
+export function getFile(path: string): string | undefined;
+/**
+ * Creates a folder.
+ * @param {string} path - The folder path to create.
+ * @param {boolean} [force=false] - Whether to recreate the folder if it already exists.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if no path was provided.
+ */
+export function createFolder(path: string, force?: boolean): boolean | undefined;
+/**
+ * Creates a file.
+ * @param {string} path - The file path to create.
+ * @param {boolean} [force=false] - Whether to recreate the file if it already exists.
+ * @param {string|object|null|undefined} [data] - File content to write.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if no path was provided.
+ */
+export function createFile(path: string, force?: boolean, data?: string | object | null | undefined): boolean | undefined;
+/**
+ * Deletes folders found inside a path.
+ * @param {string} [path=process.cwd()] - The base path to inspect.
+ * @param {(folder: string) => boolean} [filter=() => true] - Filter applied to each folder path.
+ * @returns {number|undefined} Number of deleted folders, or undefined if the path cannot be resolved.
+ */
+export function deleteFoldersIn(path?: string, filter?: (folder: string) => boolean): number | undefined;
+/**
+ * Deletes a folder.
+ * @param {string} path - The folder path to delete.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if the path is invalid.
+ */
+export function deleteFolder(path: string): boolean | undefined;
+/**
+ * Deletes files found inside a path.
+ * @param {string} [path=process.cwd()] - The base path to inspect.
+ * @param {boolean} [recursive=false] - Whether to scan recursively.
+ * @param {(file: string) => boolean} [filter=() => true] - Filter applied to each file path.
+ * @returns {number|undefined} Number of deleted files, or undefined if the path cannot be resolved.
+ */
+export function deleteFilesIn(path?: string, recursive?: boolean, filter?: (file: string) => boolean): number | undefined;
+/**
+ * Deletes a file.
+ * @param {string} path - The file path to delete.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if the path is invalid.
+ */
+export function deleteFile(path: string): boolean | undefined;
+/**
+ * Copies folders from a source path into a destination folder.
+ * @param {Object} options - Copy options.
+ * @param {string} options.dest - Destination path.
+ * @param {string} [options.path] - Source path.
+ * @param {boolean} [options.recursive=true] - Whether to recurse into subfolders.
+ * @param {boolean} [options.withFiles=false] - Whether to copy files as well.
+ * @param {boolean} [options.force=false] - Whether to overwrite existing folders.
+ * @param {(folder: string) => boolean} [options.filter=() => true] - Filter applied to each folder.
+ * @returns {number|undefined} Number of copied folders, or undefined if invalid input.
+ */
+export function copyFoldersIn(options: {
+    dest: string;
+    path?: string | undefined;
+    recursive?: boolean | undefined;
+    withFiles?: boolean | undefined;
+    force?: boolean | undefined;
+    filter?: ((folder: string) => boolean) | undefined;
+}): number | undefined;
+/**
+ * Copies a folder to a destination path.
+ * @param {Object} options - Copy options.
+ * @param {string} options.dest - Destination path.
+ * @param {string} [options.path] - Source path.
+ * @param {boolean} [options.recursive=false] - Whether to copy subfolders.
+ * @param {boolean} [options.withFiles=false] - Whether to copy files.
+ * @param {boolean} [options.force=false] - Whether to overwrite the destination.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if invalid input.
+ */
+export function copyFolder(options: {
+    dest: string;
+    path?: string | undefined;
+    recursive?: boolean | undefined;
+    withFiles?: boolean | undefined;
+    force?: boolean | undefined;
+}): boolean | undefined;
+/**
+ * Copies files from a source path into a destination folder.
+ * @param {Object} options - Copy options.
+ * @param {string} options.dest - Destination path.
+ * @param {string} [options.path] - Source path.
+ * @param {boolean} [options.recursive=true] - Whether to recurse into subfolders.
+ * @param {boolean} [options.force=false] - Whether to overwrite existing files.
+ * @param {(file: string) => boolean} [options.filter=() => true] - Filter applied to each file.
+ * @returns {number|undefined} Number of copied files, or undefined if invalid input.
+ */
+export function copyFilesIn(options: {
+    dest: string;
+    path?: string | undefined;
+    recursive?: boolean | undefined;
+    force?: boolean | undefined;
+    filter?: ((file: string) => boolean) | undefined;
+}): number | undefined;
+/**
+ * Copies a file to a destination path.
+ * @param {Object} options - Copy options.
+ * @param {string} options.path - Source file path.
+ * @param {string} options.dest - Destination path.
+ * @param {boolean} [options.force=false] - Whether to overwrite the destination file.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if invalid input.
+ */
+export function copyFile(options: {
+    path: string;
+    dest: string;
+    force?: boolean | undefined;
+}): boolean | undefined;
+/**
+ * Moves folders from a source path into a destination folder.
+ * @param {Object} options - Move options.
+ * @param {string} options.dest - Destination path.
+ * @param {string} [options.path] - Source path.
+ * @param {boolean} [options.recursive=true] - Whether to recurse into subfolders.
+ * @param {boolean} [options.withFiles=false] - Whether to move files as well.
+ * @param {boolean} [options.force=false] - Whether to overwrite existing folders.
+ * @param {(folder: string) => boolean} [options.filter=() => true] - Filter applied to each folder.
+ * @returns {number|undefined} Number of copied folders, or undefined if invalid input.
+ */
+export function moveFoldersIn(options: {
+    dest: string;
+    path?: string | undefined;
+    recursive?: boolean | undefined;
+    withFiles?: boolean | undefined;
+    force?: boolean | undefined;
+    filter?: ((folder: string) => boolean) | undefined;
+}): number | undefined;
+/**
+ * Moves a folder to a destination path.
+ * @param {Object} options - Move options.
+ * @param {string} options.path - Source folder path.
+ * @param {string} options.dest - Destination path.
+ * @param {boolean} [options.recursive=false] - Whether to move subfolders.
+ * @param {boolean} [options.withFiles=false] - Whether to move files.
+ * @param {boolean} [options.force=false] - Whether to overwrite the destination.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if invalid input.
+ */
+export function moveFolder(options: {
+    path: string;
+    dest: string;
+    recursive?: boolean | undefined;
+    withFiles?: boolean | undefined;
+    force?: boolean | undefined;
+}): boolean | undefined;
+/**
+ * Moves files from a source path into a destination folder.
+ * @param {Object} options - Move options.
+ * @param {string} options.dest - Destination path.
+ * @param {string} [options.path] - Source path.
+ * @param {boolean} [options.recursive=true] - Whether to recurse into subfolders.
+ * @param {boolean} [options.force=false] - Whether to overwrite existing files.
+ * @param {(file: string) => boolean} [options.filter=() => true] - Filter applied to each file.
+ * @returns {number|undefined} Number of copied files, or undefined if invalid input.
+ */
+export function moveFilesIn(options: {
+    dest: string;
+    path?: string | undefined;
+    recursive?: boolean | undefined;
+    force?: boolean | undefined;
+    filter?: ((file: string) => boolean) | undefined;
+}): number | undefined;
+/**
+ * Moves a file to a destination path.
+ * @param {Object} options - Move options.
+ * @param {string} options.path - Source file path.
+ * @param {string} options.dest - Destination path.
+ * @param {boolean} [options.force=false] - Whether to overwrite the destination file.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if invalid input.
+ */
+export function moveFile(options: {
+    path: string;
+    dest: string;
+    force?: boolean | undefined;
+}): boolean | undefined;
+/**
+ * Reads a file as UTF-8 text.
+ * @param {string} path - The file path to read.
+ * @returns {string|undefined} File content, or undefined if the file cannot be read.
+ */
+export function readFile(path: string): string | undefined;
+/**
+ * Watches a path and exposes event listeners.
+ * @param {Object} [options] - Watch options.
+ * @param {string} [options.path=process.cwd()] - Path to watch.
+ * @param {boolean} [options.recursive=false] - Whether to watch recursively.
+ * @param {(event: "rename"|"change", file: string) => boolean} [options.filter] - Filter applied before dispatch.
+ * @returns {{
+ *   on: <E extends "change"|"rename"|"all">(event: E, callback: E extends "all" ? (event: "change"|"rename", file: string) => void|Promise<void> : (file: string) => void|Promise<void>) => any,
+ *   stop: () => void,
+ *   pause: () => any,
+ *   resume: () => any,
+ * }|undefined} Watch controller, or undefined if the path cannot be resolved.
+ */
+export function watch(options?: {
+    path?: string | undefined;
+    recursive?: boolean | undefined;
+    filter?: ((event: "rename" | "change", file: string) => boolean) | undefined;
+}): {
+    on: <E extends "change" | "rename" | "all">(event: E, callback: E extends "all" ? (event: "change" | "rename", file: string) => void | Promise<void> : (file: string) => void | Promise<void>) => any;
+    stop: () => void;
+    pause: () => any;
+    resume: () => any;
+} | undefined;
+//# sourceMappingURL=FS.d.ts.map

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

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

package/types/src/Logger.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Enables or disables timestamp in logs
+ * @param {boolean} value - True to enable, false to disable
+ * @returns {Logger} The same Logger instance (for chaining)
+ */
+export function setTimestamp(value: boolean): Logger;
+/**
+ * Changes the delimiters used for text formatting
+ * @param {object} options - Delimiter options
+ * @param {string} [options.open] - New opening delimiter
+ * @param {string} [options.close] - New closing delimiter
+ * @returns {Logger} The same Logger instance (for chaining)
+ */
+export function setDelimiter(options?: {
+    open?: string | undefined;
+    close?: string | undefined;
+}): Logger;
+/**
+ * Prints a message to the console with ANSI formatting
+ * @param {*} content - Content to print (string, object, or other)
+ * @returns {Logger} The same Logger instance (for chaining)
+ */
+export function log(content: any): Logger;
+/**
+ * Start a log group (displays a label and adds indentation)
+ * @param {string} label - The group name to display
+ * @returns {Logger} The same Logger instance (for chaining)
+ */
+export function group(label: string): Logger;
+/**
+ * End the current log group
+ * @returns {Logger} The same Logger instance (for chaining)
+ */
+export function groupEnd(): Logger;
+//# sourceMappingURL=Logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/Logger.js"],"names":[],"mappings":"AA+NE;;;;GAIG;AACH,oCAHW,OAAO,GACL,MAAM,CAKlB;AAED;;;;;;GAMG;AACH,uCAJG;IAAyB,IAAI;IACJ,KAAK;CAC9B,GAAU,MAAM,CAQlB;AAED;;;;GAIG;AACH,6BAHW,GAAC,GACC,MAAM,CAiClB;AAED;;;;GAIG;AACH,6BAHW,MAAM,GACJ,MAAM,CAOlB;AAED;;;GAGG;AACH,4BAFa,MAAM,CAKlB"}

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"}