@egi/smart-db/smart-tools.d.ts

Unified Smart DB Access

import { DateTime } from "luxon";
export interface FormatDateOptions {
    millis?: boolean;
    noBlanks?: boolean;
    separator?: string;
    tz?: string;
}
export interface GetCallerOptions {
    ignoreFiles?: string[];
    projectRoot?: string;
}
export interface FrameData {
    columnNumber: number;
    fileName: string;
    functionName: string;
    lineNumber: number;
    methodName: string;
    native: boolean;
    typeName: string;
}
/**
 * Controls how `Date` values are converted when writing to and reading from the database.
 * - `"rule"` *(default)* — TIMESTAMP columns store UTC; DATE / DATETIME columns store local time.
 * - `"utc"` — all date/time columns store UTC.
 * - `"local"` — all date/time columns store local time (no UTC conversion).
 * - `"none"` — no conversion; values are passed through to the driver as-is.
 */
export type SmartDbDateTimeMode = "rule" | "utc" | "local" | "none";
export interface SmartToolOptions {
    /** Controls how `Date` values are converted on read and write. Defaults to `"rule"`. */
    dateTimeMode?: SmartDbDateTimeMode;
}
export declare class SmartTools {
    private formatters;
    /**
     * Captures the stack trace starting from the point just below the provided function.
     *
     * @param belowFn - A reference function to exclude from the stack trace.
     * @returns An array of FrameData objects representing the captured stack trace.
     */
    getStackTrace(belowFn?: () => any): FrameData[];
    /**
     * Parses an error's stack trace into an array of FrameData objects.
     *
     * @param err - An error object containing the stack trace.
     * @returns An array of FrameData objects parsed from the error's stack trace.
     */
    parseStackTrace(err: Error): FrameData[];
    /**
     * Retrieves caller information from the stack trace, excluding specified files or patterns.
     *
     * @param {Error | (() => Error)} [errorOrStackProvider] - An error object or function returning an error,
     *     used to extract the stack trace. Defaults to capturing the current stack trace if omitted.
     * @param options - Optional settings for filtering and formatting the caller information.
     * @returns {string} A string with the format "fileName:lineNumber (functionName)",
     *     or "unknown location" if caller information cannot be determined.
     */
    getCallerFromStack(errorOrStackProvider?: Error | (() => Error), options?: GetCallerOptions): string;
    /** Converts a string to `kebab-case`. Accepts camelCase, PascalCase, snake_case, or kebab-case input. */
    kebabCase(s: string): string;
    /** Converts a string to `snake_case`. Accepts camelCase, PascalCase, kebab-case, or snake_case input. */
    snakeCase(s: string): string;
    /** Converts a string to `camelCase`. Returns `""` for empty or null input. */
    camelCase(s: string): string;
    /** Converts a string to `PascalCase`. Returns `""` for empty or null input. */
    pascalCase(s: string): string;
    /** Converts a string to `Title Case` with spaces between words. Returns `""` for empty or null input. */
    titleCase(s: string): string;
    /** Converts a string to `CONSTANT_CASE` (SCREAMING_SNAKE). */
    constantCase(s: string): string;
    /** Returns a shallow copy of `obj` (top-level properties are copied; nested objects are shared). */
    clone<T extends object>(obj: T): T;
    /** Returns a deep clone of `obj`. Handles nested objects, arrays, and primitive values. */
    cloneDeep<T>(obj: T): T;
    /** Returns `true` if `obj` is a plain object created with `{}` or `new Object()`. */
    isSimpleObject(obj: any): boolean;
    /** Returns `true` if `obj` is any object (includes arrays, Dates, class instances). Returns `false` for `null` and primitives. */
    isObject(obj: any): boolean;
    /** Returns `true` if `obj` is an array. */
    isArray(obj: any): boolean;
    /** Returns `true` for string primitives and `String` wrapper objects. */
    isString(obj: any): boolean;
    /** Returns `true` for finite numbers. Returns `false` for `NaN`, `Infinity`, and non-number types. */
    isNumber(obj: any): boolean;
    /** Returns `true` only for `true` or `false` boolean primitives. */
    isBoolean(obj: any): boolean;
    /** Returns `true` only for `null` (strict equality). */
    isNull(obj: any): boolean;
    /** Returns `true` only for `undefined`. */
    isUndefined(obj: any): boolean;
    /** Returns `true` for functions and class constructors. */
    isFunction(obj: any): boolean;
    /** Returns `true` for `Date` instances. Returns `false` for date strings or timestamps. */
    isDate(obj: any): boolean;
    /** Returns `true` for `RegExp` instances (both literals and `new RegExp()`). */
    isRegExp(obj: any): boolean;
    /** Returns `true` for `Error` instances and subclasses (e.g. `TypeError`, `RangeError`). */
    isError(obj: any): boolean;
    /** Returns `true` for Symbol values. */
    isSymbol(obj: any): boolean;
    /**
     * Returns `true` when `obj` is considered empty:
     * - `null` or `undefined`
     * - empty string `""`
     * - empty array `[]`
     * - empty plain object `{}`
     *
     * Note: `0`, `false`, and non-plain objects are **not** considered empty.
     */
    isEmpty(obj: any): boolean;
    /** Returns `true` for strings, numbers, booleans, `null`, `undefined`, and symbols. Returns `false` for objects, arrays, and functions. */
    isPrimitive(obj: any): boolean;
    /**
     * Converts a millisecond timestamp, ISO string, Luxon `DateTime`, or `Date` to a JavaScript `Date`.
     * If `date` is already a `Date` it is returned as-is.
     */
    toDate(date: number | Date | DateTime | string): Date;
    /**
     * Converts a millisecond timestamp, ISO string, JavaScript `Date`, or Luxon `DateTime` to a Luxon `DateTime`.
     * Passing `null` or `undefined` returns `DateTime.now()`.
     * Throws if the value cannot be parsed.
     */
    toDateTime(date: number | Date | DateTime | string): DateTime<boolean>;
    /**
     * Returns the Unix timestamp in milliseconds for the given date value.
     * Accepts a millisecond number (returned as-is), `Date`, Luxon `DateTime`, or a parseable string.
     */
    toTimestamp(date: number | Date | DateTime | string): number;
    /**
     * Formats a date as a locale-independent ISO-like string (`YYYY-MM-DD HH:mm:ss`).
     * Defaults to the system timezone and current time when arguments are omitted.
     *
     * @param date - The date to format. Accepts a `Date`, ISO string, or millisecond timestamp. Defaults to now.
     * @param options - Optional formatting options:
     *   - `tz` — IANA timezone (defaults to the system timezone).
     *   - `noBlanks` — replaces the date/time separator space with `T`.
     *   - `separator` — replaces all separators (dashes, colons, space) with a single character.
     *   - `millis` — appends milliseconds to the output.
     */
    formatDate(date?: Date | string | number, options?: FormatDateOptions): string;
    /**
     * Converts a millisecond duration to a human-readable time string.
     *
     * @param millies - Duration in milliseconds. Must represent less than one month.
     * @param includeMillis - When `true`, appends milliseconds to the output. Defaults to `false`.
     * @param useHms - When `true`, uses `h`/`m`/`s` suffixes (e.g. `"1h30m05s"`) instead of `HH:MM:SS` notation.
     * @throws {Error} If the duration is too large (exceeds one month).
     *
     * @example
     * millisToTimeString(5_400_000)            // "01:30:00"
     * millisToTimeString(5_400_000, false, true) // "1h30m00s"
     */
    millisToTimeString(millies: number, includeMillis?: boolean, useHms?: boolean): string;
    /**
     * Returns a promise that resolves after `millis` milliseconds.
     * Useful for introducing deliberate pauses in async code.
     */
    sleep(millis: number): Promise<void>;
    /**
     * Extracts a human-readable message string from any error value.
     * Inspects common properties in order: `error`, `message`, `text`, `status`, `stderr`, `stdout`, `code`.
     * Falls back to `String(error)` for unrecognized shapes.
     */
    getErrorText(error: any): string;
    /**
     * Casts `value` to the requested primitive type.
     * - `"number"` — applies `Number(value)`.
     * - `"boolean"` — returns `true` for `1`, `true`, `"1"`, `"T"`, or `"TRUE"` (case-insensitive); `false` otherwise.
     * - `"string"` — returns `value` unchanged.
     */
    castToType(value: any, type: "string"): string;
    castToType(value: any, type: "number"): number;
    castToType(value: any, type: "boolean"): boolean;
    castToType(value: any, type: "string" | "number" | "boolean"): any;
    /** Splits a string into lowercase words by detecting camelCase boundaries and normalising separators. */
    private splitWords;
}
export declare const tools: SmartTools;