@kikiutils/shared 18.3.0 → 20.0.0

package/src/logger/_internals/levels.ts

@@ -0,0 +1,60 @@
+import type { LoggerMethod } from '../types';
+
+// Constants/Variables
+export const loggerMethods = {
+    debug: {
+        ansiColor: '36',
+        consoleMethod: 'debug',
+        cssColor: '#0891b2',
+        icon: '⚙',
+        severity: 20,
+    },
+    error: {
+        ansiColor: '31',
+        consoleMethod: 'error',
+        cssColor: '#dc2626',
+        icon: '✖',
+        severity: 50,
+    },
+    fatal: {
+        ansiColor: '31',
+        consoleMethod: 'error',
+        cssColor: '#dc2626',
+        icon: '✖',
+        severity: 60,
+    },
+    info: {
+        ansiColor: '36',
+        consoleMethod: 'info',
+        cssColor: '#0891b2',
+        icon: 'ℹ',
+        severity: 30,
+    },
+    success: {
+        ansiColor: '32',
+        consoleMethod: 'info',
+        cssColor: '#16a34a',
+        icon: '✔',
+        severity: 30,
+    },
+    trace: {
+        ansiColor: '90',
+        consoleMethod: 'debug',
+        cssColor: '#808080',
+        icon: '·',
+        severity: 10,
+    },
+    warn: {
+        ansiColor: '33',
+        consoleMethod: 'warn',
+        cssColor: '#ca8a04',
+        icon: '⚠',
+        severity: 40,
+    },
+} as const;
+
+// Functions
+export function getLoggerStreamName(type: LoggerMethod): 'stderr' | 'stdout' {
+    const method = loggerMethods[type].consoleMethod;
+    return method === 'warn' || method === 'error' ? 'stderr' : 'stdout';
+}

package/src/logger/_internals/logger.ts

@@ -0,0 +1,224 @@
+import type {
+    Logger,
+    LoggerDiagnostic,
+    LoggerLevel,
+    LoggerMethod,
+    LoggerOptions,
+} from '../types';
+
+import { loggerMethods } from './levels';
+import type { LoggerRecord } from './types';
+
+interface LoggerHooks {
+    /** A non-throwing reporter created by createDiagnosticReporter. */
+    report: (event: LoggerDiagnostic) => void;
+    write: (record: LoggerRecord) => Promise<void> | void;
+}
+
+// Constants/Variables
+const booleanPresentationKeys = [
+    'console',
+    'icons',
+    'timestamp',
+] as const;
+
+const stringPresentationKeys = [
+    'prefix',
+    'suffix',
+] as const;
+
+// Functions
+
+/** A non-recursive, rate-limited diagnostic boundary shared by server and browser adapters. */
+export function createDiagnosticReporter(
+    onError?: (event: Readonly<LoggerDiagnostic>) => void,
+    fallback?: (message: string) => void,
+): (event: LoggerDiagnostic) => void {
+    let reporting = false;
+    let callbackPending = false;
+    const stateByType = new Map<LoggerDiagnostic['type'], { lastReportedAt: number; suppressedCount: number }>();
+
+    return (event) => {
+        if (reporting) return;
+        try {
+            const now = Date.now();
+            const state = stateByType.get(event.type);
+            if (state && now - state.lastReportedAt < 1000) {
+                state.suppressedCount++;
+                return;
+            }
+
+            reporting = true;
+            const suppressedCount = state?.suppressedCount ?? 0;
+            if (suppressedCount) {
+                event = {
+                    ...event,
+                    suppressedCount,
+                };
+            }
+
+            stateByType.set(
+                event.type,
+                {
+                    lastReportedAt: now,
+                    suppressedCount: 0,
+                },
+            );
+
+            try {
+                const summary = suppressedCount ? ` (${suppressedCount} similar diagnostics suppressed)` : '';
+                fallback?.(`[logger] ${event.message}${summary}\n`);
+            } catch {
+                // Diagnostics must never re-enter the normal logging pipeline.
+            }
+
+            if (!callbackPending) {
+                try {
+                    callbackPending = true;
+                    const result: unknown = onError?.(Object.freeze({ ...event }));
+                    if (result !== null && (typeof result === 'object' || typeof result === 'function')) {
+                        void Promise.resolve(result).then(
+                            () => {
+                                callbackPending = false;
+                            },
+                            () => {
+                                callbackPending = false;
+                            },
+                        );
+                    } else {
+                        callbackPending = false;
+                    }
+                } catch {
+                    callbackPending = false;
+                    // User diagnostic callbacks have the same non-throwing boundary.
+                }
+            }
+        } catch { /* Diagnostics must never escape into the logging pipeline. */ } finally {
+            reporting = false;
+        }
+    };
+}
+
+export function createLoggerCore(options: LoggerOptions, hooks: LoggerHooks): Readonly<Logger> {
+    validateLevel(options.level);
+    validatePresentation(options);
+    if (options.onError !== undefined && typeof options.onError !== 'function') {
+        throw new TypeError('Logger onError must be a function');
+    }
+
+    const presentation = {
+        console: options.console ?? true,
+        icons: options.icons ?? true,
+        prefix: options.prefix ?? '',
+        suffix: options.suffix ?? '',
+        timestamp: options.timestamp ?? true,
+    };
+
+    const { report } = hooks;
+
+    let override = options.level === 'env' ? undefined : options.level;
+    let previousEnvironment: string | undefined;
+    let currentLevel: LoggerLevel = override ?? 'info';
+    let environmentRead = false;
+
+    function refreshLevel() {
+        if (override !== undefined) return;
+        const input = readEnvironmentLevel();
+        if (environmentRead && input === previousEnvironment) return;
+        environmentRead = true;
+        previousEnvironment = input;
+        const normalized = input?.trim().toLowerCase() || undefined;
+        currentLevel = isLevel(normalized) ? normalized : 'info';
+        if (normalized !== undefined && !isLevel(normalized)) {
+            report({
+                message: 'Invalid LOG_LEVEL; using info',
+                type: 'invalid-level',
+            });
+        }
+    }
+
+    const logger = {
+        configure(configuration) {
+            validatePresentation(configuration);
+            for (const name of booleanPresentationKeys) {
+                const value = configuration[name];
+                if (value !== undefined) presentation[name] = value;
+            }
+
+            for (const name of stringPresentationKeys) {
+                const value = configuration[name];
+                if (value !== undefined) presentation[name] = value;
+            }
+        },
+        isLevelEnabled(level) {
+            if (level !== 'success' && !isLevel(level)) throw new TypeError('Invalid logger level');
+            refreshLevel();
+            return level !== 'silent' && getLevelSeverity(level) >= getLevelSeverity(currentLevel);
+        },
+        setLevel(level) {
+            validateLevel(level);
+            if (level === undefined) throw new TypeError('Invalid logger level');
+            override = level === 'env' ? undefined : level;
+            environmentRead = false;
+            if (override !== undefined) {
+                currentLevel = override;
+            } else {
+                refreshLevel();
+            }
+        },
+    } as Logger;
+
+    for (const type of Object.keys(loggerMethods) as LoggerMethod[]) {
+        logger[type] = async (...args: unknown[]) => {
+            try {
+                refreshLevel();
+                if (loggerMethods[type].severity < getLevelSeverity(currentLevel)) return;
+                await hooks.write({
+                    ...presentation,
+                    args,
+                    date: new Date(),
+                    type,
+                });
+            } catch (error) {
+                report({
+                    error,
+                    message: 'Logger output failed',
+                    type: 'format',
+                });
+            }
+        };
+    }
+
+    return Object.freeze(logger);
+}
+
+function getLevelSeverity(level: LoggerLevel | LoggerMethod): number {
+    return level === 'silent' ? Number.POSITIVE_INFINITY : loggerMethods[level].severity;
+}
+
+function isLevel(value: unknown): value is LoggerLevel {
+    return typeof value === 'string'
+      && (value === 'silent' || (value !== 'success' && Object.hasOwn(loggerMethods, value)));
+}
+
+function readEnvironmentLevel(): string | undefined {
+    return (globalThis as { process?: { env?: { LOG_LEVEL?: string } } }).process?.env?.LOG_LEVEL;
+}
+
+function validateLevel(value: unknown): asserts value is 'env' | LoggerLevel | undefined {
+    if (value !== undefined && value !== 'env' && !isLevel(value)) throw new TypeError('Invalid logger level');
+}
+
+function validatePresentation(options: Pick<LoggerOptions, 'console' | 'icons' | 'prefix' | 'suffix' | 'timestamp'>) {
+    for (const name of booleanPresentationKeys) {
+        if (options[name] !== undefined && typeof options[name] !== 'boolean') {
+            throw new TypeError(`Logger ${name} must be a boolean`);
+        }
+    }
+
+    for (const name of stringPresentationKeys) {
+        if (options[name] !== undefined && typeof options[name] !== 'string') {
+            throw new TypeError(`Logger ${name} must be a string`);
+        }
+    }
+}

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 = {}): Readonly<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: () => Readonly<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<Readonly<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 Object.freeze({
+        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: () => Object.freeze({
+            droppedCount,
+            pendingBytes,
+            writeErrorCount,
+        }),
+        write(text: string) {
+            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(' ');
+}