@kikiutils/shared 18.3.0 → 19.0.0

package/src/logger/_internals/types.ts

@@ -0,0 +1,12 @@
+import type { LoggerMethod } from '../types';
+
+export interface LoggerRecord {
+    args: readonly unknown[];
+    console: boolean;
+    date: Date;
+    icons: boolean;
+    prefix: string;
+    suffix: string;
+    timestamp: boolean;
+    type: LoggerMethod;
+}

package/src/logger/index.ts

@@ -0,0 +1,34 @@
+import { formatLoggerConsoleArgs } from './_internals/formatter';
+import { loggerMethods } from './_internals/levels';
+import {
+    createDiagnosticReporter,
+    createLoggerCore,
+} from './_internals/logger';
+import type {
+    Logger,
+    LoggerOptions,
+} from './types';
+
+// Functions
+
+/**
+ * Creates an independent, browser-safe console logger.
+ *
+ * Log calls never throw or reject for recoverable output failures. Awaiting a call
+ * waits for the console invocation, not display or durable delivery. Unspecified
+ * levels follow LOG_LEVEL when a process environment is available, otherwise info.
+ */
+export function createLogger(options: LoggerOptions = {}): Logger {
+    const target = globalThis.console;
+    const fallback = target?.error?.bind(target);
+    return createLoggerCore(
+        options,
+        {
+            report: createDiagnosticReporter(options.onError, (message) => fallback?.(message.trimEnd())),
+            write(record) {
+                if (!record.console) return;
+                target?.[loggerMethods[record.type].consoleMethod](...formatLoggerConsoleArgs(record));
+            },
+        },
+    );
+}

package/src/logger/node/_internals/file-writer.ts

@@ -0,0 +1,298 @@
+import { Buffer } from 'node:buffer';
+import { createWriteStream } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import {
+    basename,
+    dirname,
+} from 'node:path';
+import type { Writable } from 'node:stream';
+import { fileURLToPath } from 'node:url';
+
+import { Path } from '../../../classes/path';
+import type { LoggerDiagnostic } from '../../types';
+import type {
+    LoggerFileOptions,
+    NodeLoggerStats,
+} from '../types';
+
+interface LoggerFileWriter {
+    close: () => Promise<void>;
+    getStats: () => NodeLoggerStats;
+    write: (text: string) => Promise<void>;
+}
+
+// Constants/Variables
+const defaultMaxPendingBytes = 8 * 1024 * 1024;
+
+// Functions
+
+/** A bounded admission layer over the stream's own ordered write buffer; not a second FIFO. */
+export async function createFileWriter(
+    options: LoggerFileOptions,
+    report: (event: LoggerDiagnostic) => void,
+): Promise<LoggerFileWriter> {
+    const {
+        maxPendingBytes,
+        path,
+        rotate,
+    } = validateFileOptions(options);
+
+    const createRotatingStream = rotate ? (await import('rotating-file-stream')).createStream : undefined;
+    await mkdir(dirname(path), { recursive: true });
+    const stream: Writable = rotate && createRotatingStream
+        ? createRotatingStream(
+            basename(path),
+            {
+                compress: rotate.compress === false ? false : 'gzip',
+                ...rotate.interval === undefined ? {} : { interval: rotate.interval === 'hourly' ? '1h' : '1d' },
+                intervalBoundary: true,
+                intervalUTC: false,
+                maxFiles: rotate.keepFiles ?? 30,
+                ...rotate.maxTotalSize === undefined ? {} : { maxSize: rotate.maxTotalSize },
+                path: dirname(path),
+                ...rotate.maxSize === undefined ? {} : { size: rotate.maxSize },
+            },
+        )
+        : createWriteStream(path, { flags: 'a' });
+
+    let pendingBytes = 0;
+    let droppedCount = 0;
+    let writeErrorCount = 0;
+    let failed = false;
+    let closing = false;
+    let closed = false;
+    let closePromise: Promise<void> | undefined;
+    let initializing = true;
+    const unfinished = new Set<() => void>();
+    let rejectInitialization: ((error: unknown) => void) | undefined;
+
+    const settleAll = () => {
+        for (const settle of unfinished) settle();
+    };
+
+    const fail = (error: unknown) => {
+        rejectInitialization?.(error);
+        if (!failed) {
+            failed = true;
+            if (!initializing) {
+                writeErrorCount++;
+                report({
+                    error,
+                    message: 'File output failed and has been disabled.',
+                    type: 'file',
+                });
+            }
+        }
+
+        settleAll();
+        if (!stream.destroyed) stream.destroy();
+    };
+
+    stream.on('error', fail);
+    stream.on(
+        'warning',
+        (error: unknown) => {
+            writeErrorCount++;
+            report({
+                error,
+                message: 'File rotation cleanup failed.',
+                type: 'file',
+            });
+        },
+    );
+
+    stream.on(
+        'close',
+        () => {
+            closed = true;
+            if (!closing && !failed) fail(new Error('File stream closed unexpectedly.'));
+            settleAll();
+        },
+    );
+
+    // A write callback also waits for RFS's asynchronous initialization and initial rotation.
+    try {
+        await new Promise<void>((resolveReady, rejectReady) => {
+            rejectInitialization = rejectReady;
+            stream.write(
+                Buffer.alloc(0),
+                (error) => {
+                    if (error) rejectReady(error);
+                    else resolveReady();
+                },
+            );
+        });
+
+        if (failed || closed) throw new Error('File output failed during initialization.');
+    } catch (error) {
+        if (!stream.destroyed) stream.destroy();
+        if (!closed) {
+            await new Promise<void>((resolveClosed) => {
+                stream.once('close', resolveClosed);
+            });
+        }
+
+        throw error;
+    } finally {
+        rejectInitialization = undefined;
+        initializing = false;
+    }
+
+    return {
+        close() {
+            if (closePromise) return closePromise;
+            closing = true;
+            closePromise = new Promise<void>((resolveClosed) => {
+                if (closed) {
+                    resolveClosed();
+                    return;
+                }
+
+                stream.once('close', resolveClosed);
+                try {
+                    if (!stream.destroyed) stream.end();
+                } catch (error) {
+                    fail(error);
+                }
+            });
+
+            return closePromise;
+        },
+        getStats: () => ({
+            droppedCount,
+            pendingBytes,
+            writeErrorCount,
+        }),
+        write(text) {
+            if (closing || closed || failed) {
+                report({
+                    message: 'File output is closed or unavailable.',
+                    type: 'closed',
+                });
+
+                return Promise.resolve();
+            }
+
+            const bytes = Buffer.byteLength(text);
+            if (bytes > maxPendingBytes - pendingBytes) {
+                droppedCount++;
+                report({
+                    droppedCount,
+                    message: 'File output queue is full; the newest record was discarded.',
+                    type: 'overflow',
+                });
+
+                return Promise.resolve();
+            }
+
+            pendingBytes += bytes;
+            return new Promise<void>((resolveWritten) => {
+                let settled = false;
+                const settle = () => {
+                    if (settled) return;
+                    settled = true;
+                    pendingBytes -= bytes;
+                    unfinished.delete(settle);
+                    resolveWritten();
+                };
+
+                unfinished.add(settle);
+                try {
+                    stream.write(
+                        text,
+                        (error) => {
+                            if (error) fail(error);
+                            settle();
+                        },
+                    );
+                } catch (error) {
+                    fail(error);
+                }
+            });
+        },
+    };
+}
+
+/** Validate before mkdir, stream creation, or other filesystem side effects. */
+function validateFileOptions(options: LoggerFileOptions) {
+    if (
+        !options
+        || typeof options !== 'object'
+        || !(
+            typeof options.path === 'string'
+            || options.path instanceof Path
+            || options.path instanceof URL
+            || Buffer.isBuffer(options.path)
+        )
+    ) {
+        throw new TypeError('file.path must be a string, Buffer, file URL, or Path');
+    }
+
+    const path = options.path instanceof URL
+        ? fileURLToPath(options.path)
+        : options.path.toString();
+
+    if (Buffer.isBuffer(options.path) && !Buffer.from(path).equals(options.path)) {
+        throw new TypeError('file.path Buffer must contain valid UTF-8');
+    }
+
+    if (!path.trim() || path.includes('\0')) {
+        throw new TypeError('file.path must be a nonempty path without null bytes');
+    }
+
+    const maxPendingBytes = options.maxPendingBytes ?? defaultMaxPendingBytes;
+    if (!Number.isSafeInteger(maxPendingBytes) || maxPendingBytes <= 0) {
+        throw new RangeError('file.maxPendingBytes must be a positive safe integer');
+    }
+
+    const rotate = options.rotate;
+    if (rotate !== undefined && rotate !== false) {
+        if (!rotate || typeof rotate !== 'object') {
+            throw new TypeError('file.rotate must be false or an options object');
+        }
+
+        if (rotate.interval !== undefined && rotate.interval !== 'hourly' && rotate.interval !== 'daily') {
+            throw new TypeError('file.rotate.interval must be hourly or daily');
+        }
+
+        if (rotate.interval === undefined && rotate.maxSize === undefined) {
+            throw new TypeError('file.rotate requires interval or maxSize');
+        }
+
+        const keepFiles = rotate.keepFiles ?? 30;
+        if (!Number.isSafeInteger(keepFiles) || keepFiles <= 0) {
+            throw new RangeError('file.rotate.keepFiles must be a positive safe integer');
+        }
+
+        if (rotate.compress !== undefined && typeof rotate.compress !== 'boolean') {
+            throw new TypeError('file.rotate.compress must be a boolean');
+        }
+
+        validateSize(rotate.maxSize, 'file.rotate.maxSize');
+        validateSize(rotate.maxTotalSize, 'file.rotate.maxTotalSize');
+    }
+
+    return {
+        maxPendingBytes,
+        path: Path.resolve(path).value,
+        rotate,
+    };
+}
+
+function validateSize(value: string | undefined, name: string) {
+    if (value === undefined) return;
+    if (typeof value !== 'string' || !/^[1-9]\d*[BKMG]$/.test(value)) {
+        throw new TypeError(`${name} must be a positive integer followed by B, K, M, or G`);
+    }
+
+    const multiplier = {
+        B: 1,
+        G: 1024 ** 3,
+        K: 1024,
+        M: 1024 ** 2,
+    }[value.at(-1) as 'B' | 'G' | 'K' | 'M'];
+
+    if (!Number.isSafeInteger(Number(value.slice(0, -1)) * multiplier)) {
+        throw new RangeError(`${name} exceeds the supported size range`);
+    }
+}

package/src/logger/node/_internals/formatter.ts

@@ -0,0 +1,33 @@
+import { inspect } from 'node:util';
+
+import { formatLoggerParts } from '../../_internals/formatter';
+import type { LoggerRecord } from '../../_internals/types';
+
+// Functions
+
+/** Preserve user ANSI for console output without invoking custom inspect callbacks/getters. */
+export function formatNodeLoggerRecord(record: LoggerRecord, colors = false) {
+    const message = record.args.map(
+        (arg) => typeof arg === 'string'
+            ? arg
+            : inspect(
+                arg,
+                {
+                    colors: false,
+                    customInspect: false,
+                    depth: 6,
+                    getters: false,
+                    maxArrayLength: 100,
+                    maxStringLength: 10_000,
+                },
+            ),
+    ).join(' ');
+
+    return formatLoggerParts(
+        {
+            ...record,
+            args: record.args.length ? [message] : [],
+        },
+        colors,
+    ).join(' ');
+}

package/src/logger/node/index.ts

@@ -0,0 +1,175 @@
+import { writeSync } from 'node:fs';
+import { stripVTControlCharacters } from 'node:util';
+
+import { supportsLoggerColor } from '../_internals/formatter';
+import { getLoggerStreamName } from '../_internals/levels';
+import {
+    createDiagnosticReporter,
+    createLoggerCore,
+} from '../_internals/logger';
+import type { LoggerDiagnostic } from '../types';
+
+import { createFileWriter } from './_internals/file-writer';
+import { formatNodeLoggerRecord } from './_internals/formatter';
+import type {
+    NodeLogger,
+    NodeLoggerOptions,
+} from './types';
+
+interface ConsoleStreamState {
+    onClose: () => void;
+    onError: (error: Error) => void;
+    owners: Set<object>;
+    pending: Set<(error?: Error | null) => void>;
+}
+
+// Constants/Variables
+const consoleStreams = new WeakMap<NodeJS.WriteStream, ConsoleStreamState>();
+
+// Functions
+
+/**
+ * Creates a Node.js/Bun logger with optional bounded, append-only file output and rotation.
+ *
+ * Log calls never throw or reject. Awaiting them waits for processing, not proof of successful
+ * persistence: overload drops the newest file record and failures are reported safely. Factory
+ * validation/open failures reject. Call close explicitly; no process signal handlers are installed.
+ */
+export async function createNodeLogger(options: NodeLoggerOptions = {}): Promise<NodeLogger> {
+    const report = createDiagnosticReporter(options.onError, (message) => writeSync(2, message));
+    let writer: Awaited<ReturnType<typeof createFileWriter>> | undefined;
+    let closed = false;
+    let closePromise: Promise<void> | undefined;
+    const consoleOwner = {};
+    const consoleTargets = new Set<NodeJS.WriteStream>();
+    const consoleWrites = new Set<Promise<void>>();
+    const logger = createLoggerCore(
+        options,
+        {
+            report,
+            write(record) {
+                if (closed) {
+                    report({
+                        message: 'Logger is closed.',
+                        type: 'closed',
+                    });
+
+                    return;
+                }
+
+                if (!record.console && !writer) return;
+                const target = process[getLoggerStreamName(record.type)];
+
+                const text = formatNodeLoggerRecord(record, record.console && supportsLoggerColor(target));
+                if (record.console) {
+                    const line = `${text}\n`;
+                    consoleTargets.add(target);
+                    const completion = writeConsole(target, line, report, consoleOwner);
+                    consoleWrites.add(completion);
+                    void completion.then(() => consoleWrites.delete(completion));
+                    const fileCompletion = writer?.write(`${stripVTControlCharacters(text)}\n`);
+                    return fileCompletion
+                        ? Promise.all([
+                            completion,
+                            fileCompletion,
+                        ]).then(() => {})
+                        : completion;
+                }
+
+                return writer?.write(`${stripVTControlCharacters(text)}\n`);
+            },
+        },
+    );
+
+    if (options.file !== undefined && options.file !== false) writer = await createFileWriter(options.file, report);
+
+    return Object.assign(
+        logger,
+        {
+            close() {
+                if (closePromise) return closePromise;
+                closed = true;
+                closePromise = (async () => {
+                    await Promise.all([
+                        writer?.close(),
+                        ...consoleWrites,
+                    ]);
+
+                    for (const target of consoleTargets) {
+                        const state = consoleStreams.get(target);
+                        if (!state) continue;
+                        state.owners.delete(consoleOwner);
+                        if (!state.owners.size) {
+                            target.off('error', state.onError);
+                            target.off('close', state.onClose);
+                            consoleStreams.delete(target);
+                        }
+                    }
+
+                    consoleTargets.clear();
+                })();
+                return closePromise;
+            },
+            getStats: () => writer?.getStats() ?? {
+                droppedCount: 0,
+                pendingBytes: 0,
+                writeErrorCount: 0,
+            },
+        },
+    );
+}
+
+/** One error listener per shared output stream; retained until its last owning logger calls close(). */
+function writeConsole(
+    target: NodeJS.WriteStream,
+    text: string,
+    report: (event: LoggerDiagnostic) => void,
+    owner: object,
+) {
+    let state = consoleStreams.get(target);
+    if (!state) {
+        const pending = new Set<(error?: Error | null) => void>();
+        const onError = (error: Error) => {
+            for (const settle of pending) settle(error);
+        };
+
+        const onClose = () => onError(new Error('Console stream closed.'));
+        state = {
+            onClose,
+            onError,
+            owners: new Set(),
+            pending,
+        };
+
+        consoleStreams.set(target, state);
+        target.on('error', onError);
+        target.on('close', onClose);
+    }
+
+    state.owners.add(owner);
+    const current = state;
+    return new Promise<void>((resolveWritten) => {
+        let settled = false;
+        const settle = (error?: Error | null) => {
+            if (settled) return;
+            settled = true;
+            current.pending.delete(settle);
+            if (error) {
+                report({
+                    error,
+                    message: 'Console output failed.',
+                    type: 'console',
+                });
+            }
+
+            resolveWritten();
+        };
+
+        current.pending.add(settle);
+        try {
+            target.write(text, settle);
+        } catch (error) {
+            settle(error instanceof Error ? error : new Error('Console output failed.'));
+        }
+    });
+}

package/src/logger/node/types.ts

@@ -0,0 +1,58 @@
+import type { PathLike } from '../../classes/path';
+import type {
+    Logger,
+    LoggerOptions,
+} from '../types';
+
+/** Specify interval and/or maxSize. Size limits use positive integers with B, K, M, or G (binary units). */
+export type LoggerRotationOptions = {
+    /** Gzip historical files. Defaults to true. */
+    compress?: boolean;
+
+    /** Number of historical files, excluding the active file. Defaults to 30. */
+    keepFiles?: number;
+
+    /** Maximum combined size of historical files. */
+    maxTotalSize?: string;
+} & (
+  | {
+      /** Opt-in time rotation aligned to the system's local calendar boundary. */
+      interval: 'daily' | 'hourly';
+      maxSize?: string;
+  }
+  | {
+      /** Opt-in time rotation aligned to the system's local calendar boundary. */
+      interval?: 'daily' | 'hourly';
+      maxSize: string;
+  }
+);
+
+export interface LoggerFileOptions {
+    /** Maximum unfinished payload bytes, including data already submitted to the stream. */
+    maxPendingBytes?: number;
+
+    /** Resolved once at creation. The file is opened in append mode. */
+    path: PathLike;
+
+    /** Omitted or false disables rotation. An object must specify interval or maxSize. */
+    rotate?: false | LoggerRotationOptions;
+}
+
+export interface NodeLogger extends Logger {
+    /** Stop accepting records, finish accepted file writes, then release the stream. Not fsync. */
+    close: () => Promise<void>;
+
+    /** A fresh snapshot. Dropped/failed records still resolve their logging promises. */
+    getStats: () => NodeLoggerStats;
+}
+
+export interface NodeLoggerOptions extends LoggerOptions {
+    /** Disabled by default. Each logger owns at most one fixed file destination. */
+    file?: false | LoggerFileOptions;
+}
+
+export interface NodeLoggerStats {
+    droppedCount: number;
+    pendingBytes: number;
+    writeErrorCount: number;
+}

package/src/logger/types.ts

@@ -0,0 +1,59 @@
+/** Minimum severity to emit; `success` uses the same threshold as `info`. */
+export type LoggerLevel = 'debug' | 'error' | 'fatal' | 'info' | 'silent' | 'trace' | 'warn';
+
+/** A logging method, including the informational success presentation. */
+export type LoggerMethod = 'success' | Exclude<LoggerLevel, 'silent'>;
+
+/**
+ * A logger whose logging methods never throw or reject for recoverable failures.
+ *
+ * Awaiting a method waits for processing, not guaranteed successful delivery or fsync.
+ * Configuration errors may throw from the factory, configure(), or setLevel().
+ */
+export interface Logger {
+    configure: (options: Pick<LoggerOptions, 'console' | 'icons' | 'prefix' | 'suffix' | 'timestamp'>) => void;
+    debug: (...args: unknown[]) => Promise<void>;
+    error: (...args: unknown[]) => Promise<void>;
+    fatal: (...args: unknown[]) => Promise<void>;
+    info: (...args: unknown[]) => Promise<void>;
+
+    /** Accepts success as an informational method; it is not a configurable threshold. */
+    isLevelEnabled: (level: LoggerLevel | LoggerMethod) => boolean;
+
+    /** Sets a severity threshold (not success); env restores environment-driven filtering. */
+    setLevel: (level: 'env' | LoggerLevel) => void;
+    success: (...args: unknown[]) => Promise<void>;
+    trace: (...args: unknown[]) => Promise<void>;
+    warn: (...args: unknown[]) => Promise<void>;
+}
+
+/** A recoverable logging failure, reported without throwing from log methods. */
+export interface LoggerDiagnostic {
+    droppedCount?: number;
+    error?: unknown;
+    message: string;
+
+    /** Same-type notifications suppressed since the previous emitted diagnostic. */
+    suppressedCount?: number;
+    type: 'closed' | 'console' | 'file' | 'format' | 'invalid-level' | 'overflow';
+}
+
+/** Configuration shared by browser and server loggers. */
+export interface LoggerOptions {
+    /** Enables console output. Defaults to `true`. */
+    console?: boolean;
+
+    /** Enables Unicode level icons. Defaults to `true`. */
+    icons?: boolean;
+
+    /** Overrides LOG_LEVEL; `env` restores the environment-driven threshold. */
+    level?: 'env' | LoggerLevel;
+
+    /** Best-effort, rate-limited notification; failures in this callback are contained. */
+    onError?: (event: LoggerDiagnostic) => void;
+    prefix?: string;
+    suffix?: string;
+
+    /** Enables the fixed local-time millisecond prefix. Defaults to `true`. */
+    timestamp?: boolean;
+}

package/src/types/index.ts

@@ -6,11 +6,6 @@ import type {
 
 export type { FilteredKeyPath } from './filtered-key-path';
 
-/**
- * A generic string-keyed object for utility APIs that intentionally accept any value shape.
- */
-export type AnyRecord = Record<string, any>;
-
 /**
  * Binary-like inputs accepted by `toBuffer` across browser and Node.js runtimes.
  */
@@ -31,11 +26,6 @@ export type MaybePartial<T> = Partial<T> | T;
  */
 export type MaybeReadonly<T> = Readonly<T> | T;
 
-/**
- * Number-like value represented as a number or a numeric string.
- */
-export type Numberish = number | string;
-
 /**
  * A `Record` where every key is optional.
  */