@fuzdev/fuz_util 0.42.0

package/dist/json.js

@@ -0,0 +1,44 @@
+/**
+ * Returns the `JsonType` of `value`, which is like `typeof json`
+ * but includes `'array'` and omits `'undefined'`.
+ */
+export const json_type_of = (value) => {
+    const type = typeof value;
+    switch (type) {
+        case 'string':
+        case 'number':
+        case 'boolean':
+            return type;
+        case 'object': {
+            return value === null ? 'null' : Array.isArray(value) ? 'array' : 'object';
+        }
+        default: {
+            // "undefined" | "function" | "bigint" | "symbol"
+            return undefined;
+        }
+    }
+};
+/**
+ * Embeds `data` as a JSON string, escaping single quotes.
+ * Useful for optimizing JSON in JS because it parses faster.
+ */
+export const json_embed = (data, stringify = JSON.stringify) => `JSON.parse('${stringify(data).replaceAll("'", "\\'").replaceAll('\n', '\\\n')}')`;
+/**
+ * Serializes a value to JSON with deterministic key ordering.
+ * Recursively sorts object keys alphabetically for consistent hashing.
+ * Arrays and primitives are serialized as-is.
+ *
+ * @param value Any JSON-serializable value
+ * @returns Deterministic JSON string representation
+ */
+export const json_stringify_deterministic = (value) => JSON.stringify(value, (_key, val) => {
+    if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+        const sorted = {};
+        const keys = Object.keys(val).sort();
+        for (const k of keys) {
+            sorted[k] = val[k];
+        }
+        return sorted;
+    }
+    return val;
+});

package/dist/library_json.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Library metadata combining package.json with analyzed source.
+ */
+import type { PackageJson } from './package_json.js';
+import type { SourceJson } from './source_json.js';
+import type { Url } from './url.js';
+/**
+ * A library's package.json and source metadata with computed properties.
+ */
+export interface LibraryJson {
+    package_json: PackageJson;
+    source_json: SourceJson;
+    /** Package name, e.g. `@ryanatkn/fuz`. */
+    name: string;
+    /** Name without scope, e.g. `fuz`. */
+    repo_name: string;
+    /** GitHub repo URL, e.g. `https://github.com/ryanatkn/fuz`. */
+    repo_url: Url;
+    /** GitHub user/org, e.g. `ryanatkn`. */
+    owner_name: string | null;
+    homepage_url: Url | null;
+    /** Logo URL, falls back to `favicon.png`. */
+    logo_url: Url | null;
+    logo_alt: string;
+    npm_url: Url | null;
+    changelog_url: Url | null;
+    /** True if has exports and version is not `0.0.1`. */
+    published: boolean;
+}
+/**
+ * Creates a `LibraryJson` with computed properties from package.json and source metadata.
+ */
+export declare const library_json_parse: (package_json: PackageJson, source_json: SourceJson) => LibraryJson;
+/**
+ * Extracts repo name from a package name, e.g. `@ryanatkn/fuz` → `fuz`.
+ */
+export declare const library_repo_name_parse: (name: string) => string;
+/**
+ * Extracts GitHub org URL from a library, e.g. `https://github.com/ryanatkn`.
+ */
+export declare const library_org_url_parse: (library: LibraryJson) => string | null;
+//# sourceMappingURL=library_json.d.ts.map

package/dist/library_json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"library_json.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/library_json.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,UAAU,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,YAAY,EAAE,WAAW,CAAC;IAC1B,WAAW,EAAE,UAAU,CAAC;IACxB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,QAAQ,EAAE,GAAG,CAAC;IACd,wCAAwC;IACxC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,EAAE,GAAG,GAAG,IAAI,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,EAAE,GAAG,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,GAAG,GAAG,IAAI,CAAC;IACpB,aAAa,EAAE,GAAG,GAAG,IAAI,CAAC;IAC1B,sDAAsD;IACtD,SAAS,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC9B,cAAc,WAAW,EACzB,aAAa,UAAU,KACrB,WAuDF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM,KAAG,MAStD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAI,SAAS,WAAW,KAAG,MAAM,GAAG,IAQrE,CAAC"}

package/dist/library_json.js

@@ -0,0 +1,76 @@
+/**
+ * Library metadata combining package.json with analyzed source.
+ */
+import { ensure_end, strip_end, strip_start } from './string.js';
+/**
+ * Creates a `LibraryJson` with computed properties from package.json and source metadata.
+ */
+export const library_json_parse = (package_json, source_json) => {
+    const { name } = package_json;
+    // TODO hacky
+    const parse_repo = (r) => {
+        if (!r)
+            return null;
+        return strip_end(strip_start(strip_end(r, '.git'), 'git+'), '/');
+    };
+    const repo_url = parse_repo(package_json.repository
+        ? typeof package_json.repository === 'string'
+            ? package_json.repository
+            : package_json.repository.url
+        : null);
+    if (!repo_url) {
+        throw Error('failed to parse library_json - `repo_url` is required in package_json');
+    }
+    const homepage_url = package_json.homepage ?? null;
+    const published = !package_json.private && !!package_json.exports && package_json.version !== '0.0.1';
+    // TODO generic registries
+    const npm_url = published ? 'https://www.npmjs.com/package/' + package_json.name : null;
+    const changelog_url = published && repo_url ? repo_url + '/blob/main/CHANGELOG.md' : null;
+    const repo_name = library_repo_name_parse(name);
+    const owner_name = repo_url ? strip_start(repo_url, 'https://github.com/').split('/')[0] : null;
+    const logo_url = homepage_url
+        ? ensure_end(homepage_url, '/') +
+            (package_json.logo ? strip_start(package_json.logo, '/') : 'favicon.png')
+        : null;
+    const logo_alt = package_json.logo_alt ?? `logo for ${repo_name}`;
+    return {
+        package_json,
+        source_json,
+        name,
+        repo_name,
+        repo_url,
+        owner_name,
+        homepage_url,
+        logo_url,
+        logo_alt,
+        npm_url,
+        changelog_url,
+        published,
+    };
+};
+/**
+ * Extracts repo name from a package name, e.g. `@ryanatkn/fuz` → `fuz`.
+ */
+export const library_repo_name_parse = (name) => {
+    if (name[0] === '@') {
+        const parts = name.split('/');
+        if (parts.length < 2) {
+            throw new Error(`invalid scoped package name: "${name}" (expected format: @org/package)`);
+        }
+        return parts[1];
+    }
+    return name;
+};
+/**
+ * Extracts GitHub org URL from a library, e.g. `https://github.com/ryanatkn`.
+ */
+export const library_org_url_parse = (library) => {
+    const { repo_name, repo_url } = library;
+    if (!repo_url)
+        return null;
+    const suffix = '/' + repo_name;
+    if (repo_url.endsWith(suffix)) {
+        return strip_end(repo_url, suffix);
+    }
+    return null;
+};

package/dist/log.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Log level hierarchy from least to most verbose.
+ * - `'off'`: No logging
+ * - `'error'`: Only errors
+ * - `'warn'`: Errors and warnings
+ * - `'info'`: Errors, warnings, and info (default)
+ * - `'debug'`: All messages including debug
+ */
+export type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug';
+/**
+ * Console interface subset used by Logger for output.
+ * Allows custom console implementations for testing.
+ */
+export type LogConsole = Pick<typeof console, 'error' | 'warn' | 'log'>;
+/**
+ * Converts a log level to its numeric value for comparison.
+ * Higher numbers indicate more verbose logging.
+ * @param level The log level to convert
+ * @returns Numeric value (0-4)
+ */
+export declare const log_level_to_number: (level: LogLevel) => number;
+/**
+ * Parses and validates a log level string.
+ * @param value The value to parse as a log level
+ * @returns The validated log level, or undefined if value is undefined
+ * @throws Error if value is provided but invalid
+ */
+export declare const log_level_parse: (value: string | undefined) => LogLevel | undefined;
+/**
+ * Simple, flexible logger with support for child loggers and automatic context.
+ *
+ * Features:
+ * - Instance-based configuration (no global state)
+ * - Child loggers with automatic label concatenation
+ * - Parent chain inheritance for level, console, and colors
+ * - Respects NO_COLOR environment variable
+ *
+ * @example
+ * ```ts
+ * // Basic logger
+ * const log = new Logger('app');
+ * log.info('starting'); // [app] ➤ starting
+ *
+ * // Child logger
+ * const db_log = log.child('db');
+ * db_log.info('connected'); // [app:db] ➤ connected
+ *
+ * // Custom configuration
+ * const verbose_log = new Logger('debug', { level: 'debug', colors: true });
+ * ```
+ */
+export declare class Logger {
+    #private;
+    readonly label?: string;
+    readonly parent?: Logger;
+    /**
+     * Creates a new Logger instance.
+     *
+     * @param label Optional label for this logger. Can be `undefined` for no label, or an
+     *   empty string `''` which is functionally equivalent (both produce no brackets in output).
+     *   Note: Empty strings are only allowed for root loggers - child loggers cannot have empty labels.
+     * @param options Optional configuration for level, colors, and console
+     */
+    constructor(label?: string, options?: LoggerOptions);
+    /**
+     * Dynamic getter for level - checks override, then parent, then default.
+     */
+    get level(): LogLevel;
+    /**
+     * Setter for level - creates override.
+     */
+    set level(value: LogLevel);
+    /**
+     * Dynamic getter for colors - checks override, then parent, then environment variables.
+     *
+     * Colors are disabled if either the `NO_COLOR` or `CLAUDECODE` environment variable is set.
+     * The `CLAUDECODE` check disables colors in Claude Code environments where ANSI color codes
+     * may not render correctly in the output.
+     */
+    get colors(): boolean;
+    /**
+     * Setter for colors - creates override.
+     */
+    set colors(value: boolean);
+    /**
+     * Dynamic getter for console - checks override, then parent, then global console.
+     */
+    get console(): LogConsole;
+    /**
+     * Setter for console - creates override.
+     */
+    set console(value: LogConsole);
+    /**
+     * Gets the root logger by walking up the parent chain.
+     * Useful for setting global configuration that affects all child loggers.
+     * @returns The root logger (the one without a parent)
+     */
+    get root(): Logger;
+    /**
+     * Clears the level override for this logger, restoring inheritance from parent.
+     * After calling this, the logger will dynamically inherit the level from its parent
+     * (or use the default level if it has no parent).
+     */
+    clear_level_override(): void;
+    /**
+     * Clears the colors override for this logger, restoring inheritance from parent.
+     * After calling this, the logger will dynamically inherit colors from its parent
+     * (or use the default colors behavior if it has no parent).
+     */
+    clear_colors_override(): void;
+    /**
+     * Clears the console override for this logger, restoring inheritance from parent.
+     * After calling this, the logger will dynamically inherit the console from its parent
+     * (or use the global console if it has no parent).
+     */
+    clear_console_override(): void;
+    /**
+     * Creates a child logger with automatic label concatenation.
+     * Children inherit parent configuration unless overridden.
+     *
+     * @param label Child label (will be concatenated with parent label using `:`).
+     *   Cannot be an empty string - empty labels would result in confusing output like `parent:`
+     *   with a trailing colon. Use `undefined` or `''` only for root loggers.
+     * @param options Optional configuration overrides
+     * @returns New Logger instance with concatenated label
+     * @throws Error if label is an empty string
+     *
+     * @example
+     * ```ts
+     * const app_log = new Logger('app');
+     * const db_log = app_log.child('db'); // label: 'app:db'
+     * const query_log = db_log.child('query'); // label: 'app:db:query'
+     * ```
+     */
+    child(label: string, options?: LoggerOptions): Logger;
+    /**
+     * Logs an error message with `🞩error🞩` prefix.
+     * Only outputs if current level is `error` or higher.
+     */
+    error(...args: Array<unknown>): void;
+    /**
+     * Logs a warning message with `⚑warn⚑` prefix.
+     * Only outputs if current level is `warn` or higher.
+     */
+    warn(...args: Array<unknown>): void;
+    /**
+     * Logs an informational message.
+     * Unlike error/warn/debug, info has no character prefix - only the label is shown.
+     * This keeps standard output clean since info is the default log level.
+     * Only outputs if current level is `info` or higher.
+     */
+    info(...args: Array<unknown>): void;
+    /**
+     * Logs a debug message with `┆debug┆` prefix.
+     * Only outputs if current level is `debug`.
+     */
+    debug(...args: Array<unknown>): void;
+    /**
+     * Logs raw output without any prefix, formatting, or level filtering.
+     * Bypasses the logger's level checking, prefix formatting, and color application entirely.
+     * Useful for outputting structured data or when you need full control over formatting.
+     *
+     * Note: This method ignores the configured log level - it always outputs regardless of
+     * whether the logger is set to 'off' or any other level.
+     *
+     * @param args Values to log directly to console
+     */
+    raw(...args: Array<unknown>): void;
+}
+export interface LoggerOptions {
+    /**
+     * Log level for this logger instance.
+     * Inherits from parent or defaults to 'info'.
+     */
+    level?: LogLevel;
+    /**
+     * Console interface for output.
+     * Inherits from parent or defaults to global console.
+     * Useful for testing.
+     */
+    console?: LogConsole;
+    /**
+     * Whether to use colors in output.
+     * Inherits from parent or defaults to enabled (unless NO_COLOR env var is set).
+     */
+    colors?: boolean;
+}
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/log.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC,CAAC;AAwBxE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,QAAQ,KAAG,MAAiC,CAAC;AAExF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,QAAQ,GAAG,SAItE,CAAC;AASF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,MAAM;;IAClB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAkBzB;;;;;;;OAOG;gBACS,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB;IAiBvD;;OAEG;IACH,IAAI,KAAK,IAAI,QAAQ,CAQpB;IAED;;OAEG;IACH,IAAI,KAAK,CAAC,KAAK,EAAE,QAAQ,EAGxB;IAED;;;;;;OAMG;IACH,IAAI,MAAM,IAAI,OAAO,CAWpB;IAED;;OAEG;IACH,IAAI,MAAM,CAAC,KAAK,EAAE,OAAO,EAExB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,UAAU,CAQxB;IAED;;OAEG;IACH,IAAI,OAAO,CAAC,KAAK,EAAE,UAAU,EAE5B;IAED;;;;OAIG;IACH,IAAI,IAAI,IAAI,MAAM,CAMjB;IAED;;;;OAIG;IACH,oBAAoB,IAAI,IAAI;IAM5B;;;;OAIG;IACH,qBAAqB,IAAI,IAAI;IAU7B;;;;OAIG;IACH,sBAAsB,IAAI,IAAI;IA8G9B;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM;IAezD;;;OAGG;IACH,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI;IAKpC;;;OAGG;IACH,IAAI,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI;IAKnC;;;;;OAKG;IACH,IAAI,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI;IAKnC;;;OAGG;IACH,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI;IAKpC;;;;;;;;;OASG;IACH,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI;CAGlC;AAED,MAAM,WAAW,aAAa;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,UAAU,CAAC;IAErB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB"}