@fuzdev/fuz_util 0.42.0

package/dist/object.js

@@ -0,0 +1,89 @@
+/**
+ * Returns a boolean indicating if `value` is
+ * a plain object, possibly created with `Object.create(null)`.
+ * But warning! This fails for some obscure corner cases, use a proper library for weird things.
+ */
+export const is_plain_object = (value) => value ? value.constructor === Object || value.constructor === undefined : false;
+/**
+ * Iterated keys in `for..in` are always returned as strings,
+ * so to prevent usage errors the key type of `mapper` is always a string.
+ * Symbols are not enumerable as keys, so they're excluded.
+ */
+export const map_record = (obj, mapper) => {
+    const result = {};
+    for (const key in obj) {
+        result[key] = mapper(obj[key], key);
+    }
+    return result;
+};
+/**
+ * Creates a new object without the specified `keys`.
+ */
+export const omit = (obj, keys) => {
+    const result = {};
+    for (const key in obj) {
+        if (!keys.includes(key)) {
+            result[key] = obj[key];
+        }
+    }
+    return result;
+};
+/**
+ * Creates a new object with properties that pass the `should_pick` predicate.
+ */
+export const pick_by = (obj, should_pick) => {
+    const result = {};
+    for (const key in obj) {
+        const value = obj[key];
+        if (should_pick(value, key)) {
+            result[key] = value;
+        }
+    }
+    return result;
+};
+/**
+ * `omit_undefined` is a commonly used form of `pick_by`.
+ * See this issue for why it's used so much:
+ * https://github.com/Microsoft/TypeScript/issues/13195
+ * @param obj
+ * @returns `obj` with all `undefined` properties removed
+ */
+export const omit_undefined = (obj) => pick_by(obj, (v) => v !== undefined);
+/**
+ * A more explicit form of `{put_this_first: obj.put_this_first, ...obj}`.
+ */
+export const reorder = (obj, keys) => {
+    const result = {};
+    for (const k of keys)
+        result[k] = obj[k];
+    // overwriting is probably faster than using
+    // a `Set` to track what's already been added
+    for (const k in obj)
+        result[k] = obj[k];
+    return result;
+};
+/**
+ * Frozen empty object with no properties, good for options default values.
+ */
+export const EMPTY_OBJECT = Object.freeze({}); // eslint-disable-line @typescript-eslint/no-redundant-type-constituents
+/**
+ * Performs a depth-first traversal of an object's enumerable properties,
+ * calling `cb` for every key and value with the current `obj` context.
+ * @param obj - any object with enumerable properties
+ * @param cb - receives the key, value, and `obj` for every enumerable property on `obj` and its descendents
+ */
+export const traverse = (obj, cb) => {
+    if (!obj || typeof obj !== 'object')
+        return;
+    for (const k in obj) {
+        const v = obj[k];
+        cb(k, v, obj);
+        traverse(v, cb);
+    }
+};
+export const transform_empty_object_to_undefined = (obj) => {
+    if (obj && Object.keys(obj).length === 0) {
+        return;
+    }
+    return obj;
+};

package/dist/package_json.d.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+export declare const PackageJsonRepository: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    type: z.ZodString;
+    url: z.ZodURL;
+    directory: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>]>;
+export type PackageJsonRepository = z.infer<typeof PackageJsonRepository>;
+export declare const PackageJsonAuthor: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    name: z.ZodString;
+    email: z.ZodOptional<z.ZodEmail>;
+    url: z.ZodOptional<z.ZodURL>;
+}, z.core.$loose>]>;
+export type PackageJsonAuthor = z.infer<typeof PackageJsonAuthor>;
+export declare const PackageJsonFunding: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    type: z.ZodString;
+    url: z.ZodURL;
+}, z.core.$loose>]>;
+export type PackageJsonFunding = z.infer<typeof PackageJsonFunding>;
+export declare const ExportValue: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+export type ExportValue = z.infer<typeof ExportValue>;
+/**
+ * Package exports can be:
+ * 1. A string (shorthand for main export)
+ * 2. null (to block exports)
+ * 3. A record of export conditions/paths
+ */
+export declare const PackageJsonExports: z.ZodUnion<readonly [z.ZodString, z.ZodNull, z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>]>;
+export type PackageJsonExports = z.infer<typeof PackageJsonExports>;
+/**
+ * @see https://docs.npmjs.com/cli/v10/configuring-npm/package-json
+ */
+export declare const PackageJson: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    private: z.ZodOptional<z.ZodBoolean>;
+    public: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+    motto: z.ZodOptional<z.ZodString>;
+    glyph: z.ZodOptional<z.ZodString>;
+    logo: z.ZodOptional<z.ZodString>;
+    logo_alt: z.ZodOptional<z.ZodString>;
+    license: z.ZodOptional<z.ZodString>;
+    scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    homepage: z.ZodOptional<z.ZodURL>;
+    author: z.ZodUnion<readonly [z.ZodString, z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodOptional<z.ZodEmail>;
+        url: z.ZodOptional<z.ZodURL>;
+    }, z.core.$loose>]>>]>;
+    repository: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodURL, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        url: z.ZodURL;
+        directory: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>]>]>>;
+    contributors: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodOptional<z.ZodEmail>;
+        url: z.ZodOptional<z.ZodURL>;
+    }, z.core.$loose>]>]>>>;
+    bugs: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        url: z.ZodOptional<z.ZodURL>;
+        email: z.ZodOptional<z.ZodEmail>;
+    }, z.core.$loose>]>>;
+    funding: z.ZodOptional<z.ZodUnion<readonly [z.ZodURL, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        url: z.ZodURL;
+    }, z.core.$loose>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodURL, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        url: z.ZodURL;
+    }, z.core.$loose>]>]>>]>>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    type: z.ZodOptional<z.ZodString>;
+    engines: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    os: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cpu: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    devDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    peerDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    peerDependenciesMeta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        optional: z.ZodBoolean;
+    }, z.core.$loose>>>;
+    optionalDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    bin: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    sideEffects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    main: z.ZodOptional<z.ZodString>;
+    exports: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNull, z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>]>, z.ZodTransform<string | Record<string, unknown> | null | undefined, string | Record<string, unknown> | null>>>;
+}, z.core.$loose>;
+export type PackageJson = z.infer<typeof PackageJson>;
+//# sourceMappingURL=package_json.d.ts.map

package/dist/package_json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package_json.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/package_json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAMtB,eAAO,MAAM,qBAAqB;;;;mBAOhC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,eAAO,MAAM,iBAAiB;;;;mBAO5B,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,kBAAkB;;;mBAM7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAapE,eAAO,MAAM,WAAW,yEAAsB,CAAC;AAC/C,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,kJAI7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoEtB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}

package/dist/package_json.js

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { count_graphemes } from './string.js';
+import { transform_empty_object_to_undefined } from './object.js';
+import { Url } from './url.js';
+export const PackageJsonRepository = z.union([
+    z.string(),
+    z.looseObject({
+        type: z.string(),
+        url: Url,
+        directory: z.string().optional(),
+    }),
+]);
+export const PackageJsonAuthor = z.union([
+    z.string(),
+    z.looseObject({
+        name: z.string(),
+        email: z.email().optional(),
+        url: Url.optional(),
+    }),
+]);
+export const PackageJsonFunding = z.union([
+    z.string(),
+    z.looseObject({
+        type: z.string(),
+        url: Url,
+    }),
+]);
+// The base export value schema that can be a string, null, or nested conditions
+const export_value_schema = z.lazy(() => z.union([
+    z.string(),
+    z.null(),
+    z.record(z.string(), z.lazy(() => export_value_schema)),
+]));
+export const ExportValue = export_value_schema;
+/**
+ * Package exports can be:
+ * 1. A string (shorthand for main export)
+ * 2. null (to block exports)
+ * 3. A record of export conditions/paths
+ */
+export const PackageJsonExports = z.union([
+    z.string(),
+    z.null(),
+    z.record(z.string(), export_value_schema),
+]);
+/**
+ * @see https://docs.npmjs.com/cli/v10/configuring-npm/package-json
+ */
+export const PackageJson = z.looseObject({
+    // according to the npm docs, `name` and `version` are the only required properties
+    name: z.string(),
+    version: z.string(),
+    private: z
+        .boolean()
+        .meta({ description: 'disallow publishing to the configured registry' })
+        .optional(),
+    public: z
+        .boolean()
+        .meta({
+        description: 'a Gro extension that enables publishing `.well-known/package.json` and `.well-known/src`',
+    })
+        .optional(),
+    description: z.string().optional(),
+    motto: z
+        .string()
+        .meta({ description: "a Gro extension that's a short phrase that represents this project" })
+        .optional(),
+    glyph: z
+        .string()
+        .meta({
+        description: "a Gro extension that's a single unicode character that represents this project",
+    })
+        .refine((v) => count_graphemes(v) === 1, 'must be a single unicode character')
+        .optional(),
+    logo: z
+        .string()
+        .meta({
+        description: "a Gro extension that's a link relative to the `homepage` to an image that represents this project",
+    })
+        .optional(),
+    logo_alt: z
+        .string()
+        .meta({ description: "a Gro extension that's the alt text for the `logo`" })
+        .optional(),
+    license: z.string().optional(),
+    scripts: z.record(z.string(), z.string()).optional(),
+    homepage: Url.optional(),
+    author: z.union([z.string(), PackageJsonAuthor.optional()]),
+    repository: z.union([z.string(), Url, PackageJsonRepository]).optional(),
+    contributors: z.array(z.union([z.string(), PackageJsonAuthor])).optional(),
+    bugs: z
+        .union([z.string(), z.looseObject({ url: Url.optional(), email: z.email().optional() })])
+        .optional(),
+    funding: z
+        .union([Url, PackageJsonFunding, z.array(z.union([Url, PackageJsonFunding]))])
+        .optional(),
+    keywords: z.array(z.string()).optional(),
+    type: z.string().optional(),
+    engines: z.record(z.string(), z.string()).optional(),
+    os: z.array(z.string()).optional(),
+    cpu: z.array(z.string()).optional(),
+    dependencies: z.record(z.string(), z.string()).optional(),
+    devDependencies: z.record(z.string(), z.string()).optional(),
+    peerDependencies: z.record(z.string(), z.string()).optional(),
+    peerDependenciesMeta: z.record(z.string(), z.looseObject({ optional: z.boolean() })).optional(),
+    optionalDependencies: z.record(z.string(), z.string()).optional(),
+    bin: z.record(z.string(), z.string()).optional(),
+    sideEffects: z.array(z.string()).optional(),
+    files: z.array(z.string()).optional(),
+    main: z.string().optional(),
+    exports: PackageJsonExports.transform(transform_empty_object_to_undefined).optional(),
+});

package/dist/path.d.ts

@@ -0,0 +1,63 @@
+import type { Flavored } from './types.js';
+/**
+ * An absolute path on the filesystem. Named "id" to be consistent with Rollup.
+ */
+export type PathId = Flavored<string, 'PathId'>;
+/**
+ * Basic information about a filesystem path.
+ */
+export interface PathInfo {
+    id: PathId;
+    is_directory: boolean;
+}
+/**
+ * A resolved path with both the original path string and its absolute id.
+ */
+export interface ResolvedPath extends PathInfo {
+    path: string;
+}
+/**
+ * A filter function for paths, can distinguish between files and directories.
+ */
+export type PathFilter = (path: string, is_directory: boolean) => boolean;
+/**
+ * A filter function for file paths only.
+ */
+export type FileFilter = (path: string) => boolean;
+/**
+ * Converts a URL to a file path string, or returns the string as-is.
+ */
+export declare const to_file_path: (path_or_url: string | URL) => string;
+/**
+ * @example parse_path_parts('./foo/bar/baz.ts') => ['foo', 'foo/bar', 'foo/bar/baz.ts']
+ */
+export declare const parse_path_parts: (path: string) => Array<string>;
+/**
+ * Gets the individual parts of a path, ignoring dots and separators.
+ * @example parse_path_segments('/foo/bar/baz.ts') => ['foo', 'bar', 'baz.ts']
+ */
+export declare const parse_path_segments: (path: string) => Array<string>;
+/**
+ * A piece of a parsed path, either a path segment or separator.
+ */
+export type PathPiece = {
+    type: 'piece';
+    path: PathId;
+    name: string;
+} | {
+    type: 'separator';
+    path: PathId;
+};
+/**
+ * Treats all paths as absolute, so the first piece is always a `'/'` with type `'separator'`.
+ * @todo maybe rethink this API, it's a bit weird, but fits the usage in `ui/Breadcrumbs.svelte`
+ */
+export declare const parse_path_pieces: (raw_path: string) => Array<PathPiece>;
+/**
+ * Converts a string into a URL-compatible slug.
+ * @param str the string to convert
+ * @param map_special_characters if `true`, characters like `ñ` are converted to their ASCII equivalents, runs around 5x faster when disabled
+ * @mutates special_char_mappers calls `get_special_char_mappers()` which lazily initializes the module-level array if `map_special_characters` is true
+ */
+export declare const slugify: (str: string, map_special_characters?: boolean) => string;
+//# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AAEzC;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC7C,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,aAAa,MAAM,GAAG,GAAG,KAAG,MACgC,CAAC;AAE1F;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,MAAM,CAU3D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,MAAM,CACH,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,SAAS,GAClB;IACA,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACZ,GACD;IACA,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACZ,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,KAAK,CAAC,SAAS,CAgBnE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,EAAE,gCAA6B,KAAG,MAYpE,CAAC"}

package/dist/path.js

@@ -0,0 +1,83 @@
+/**
+ * Converts a URL to a file path string, or returns the string as-is.
+ */
+export const to_file_path = (path_or_url) => typeof path_or_url === 'string' ? path_or_url : decodeURIComponent(path_or_url.pathname);
+/**
+ * @example parse_path_parts('./foo/bar/baz.ts') => ['foo', 'foo/bar', 'foo/bar/baz.ts']
+ */
+export const parse_path_parts = (path) => {
+    const segments = parse_path_segments(path);
+    let current_path = path.startsWith('/') ? '/' : '';
+    return segments.map((segment) => {
+        if (current_path && current_path !== '/') {
+            current_path += '/';
+        }
+        current_path += segment;
+        return current_path;
+    });
+};
+/**
+ * Gets the individual parts of a path, ignoring dots and separators.
+ * @example parse_path_segments('/foo/bar/baz.ts') => ['foo', 'bar', 'baz.ts']
+ */
+export const parse_path_segments = (path) => path.split('/').filter((s) => s && s !== '.' && s !== '..');
+/**
+ * Treats all paths as absolute, so the first piece is always a `'/'` with type `'separator'`.
+ * @todo maybe rethink this API, it's a bit weird, but fits the usage in `ui/Breadcrumbs.svelte`
+ */
+export const parse_path_pieces = (raw_path) => {
+    const pieces = [];
+    const path_segments = parse_path_segments(raw_path);
+    if (path_segments.length) {
+        pieces.push({ type: 'separator', path: '/' });
+    }
+    let path = '';
+    for (let i = 0; i < path_segments.length; i++) {
+        const path_segment = path_segments[i];
+        path += '/' + path_segment;
+        pieces.push({ type: 'piece', name: path_segment, path });
+        if (i !== path_segments.length - 1) {
+            pieces.push({ type: 'separator', path });
+        }
+    }
+    return pieces;
+};
+/**
+ * Converts a string into a URL-compatible slug.
+ * @param str the string to convert
+ * @param map_special_characters if `true`, characters like `ñ` are converted to their ASCII equivalents, runs around 5x faster when disabled
+ * @mutates special_char_mappers calls `get_special_char_mappers()` which lazily initializes the module-level array if `map_special_characters` is true
+ */
+export const slugify = (str, map_special_characters = true) => {
+    let s = str.toLowerCase();
+    if (map_special_characters) {
+        for (const mapper of get_special_char_mappers()) {
+            s = mapper(s);
+        }
+    }
+    return s
+        .replace(/[^\s\w-]/g, '')
+        .split(/[\s-]+/g) // collapse whitespace
+        .filter(Boolean)
+        .join('-'); // remove all `''`
+};
+/**
+ * @see https://stackoverflow.com/questions/1053902/how-to-convert-a-title-to-a-url-slug-in-jquery/5782563#5782563
+ */
+const special_char_from = 'áäâàãåÆþčçćďđéěëèêẽĕȇğíìîïıňñóöòôõøðřŕšşßťúůüùûýÿž';
+const special_char_to = 'aaaaaaabcccddeeeeeeeegiiiiinnooooooorrssstuuuuuyyz';
+let special_char_mappers;
+/**
+ * Lazily constructs `special_char_mappers` which
+ * converts special characters to their ASCII equivalents.
+ * @mutates special_char_mappers pushes mapper functions into module-level array on first call
+ */
+const get_special_char_mappers = () => {
+    if (special_char_mappers)
+        return special_char_mappers;
+    special_char_mappers = [];
+    for (let i = 0, j = special_char_from.length; i < j; i++) {
+        special_char_mappers.push((s) => s.replaceAll(special_char_from.charAt(i), special_char_to.charAt(i)));
+    }
+    return special_char_mappers;
+};

package/dist/print.d.ts

@@ -0,0 +1,52 @@
+import type { styleText } from 'node:util';
+import type { Timings } from './timings.js';
+import type { Logger } from './log.js';
+export declare let st: typeof styleText;
+/**
+ * Configures the module-level styling function for colored output.
+ * @mutates st assigns the module-level `st` variable
+ */
+export declare const configure_print_colors: (s: typeof styleText | null | undefined) => typeof styleText;
+/**
+ * Formats a key-value pair for printing.
+ */
+export declare const print_key_value: (key: string, value: string | number) => string;
+/**
+ * Formats a `number` of milliseconds for printing.
+ */
+export declare const print_ms: (ms: number, decimals?: number, separator?: string) => string;
+/**
+ * Formats a `number` with separators for improved readability.
+ */
+export declare const print_number_with_separators: (v: string, separator?: string) => string;
+/**
+ * Formats a `string` for printing.
+ */
+export declare const print_string: (value: string) => string;
+/**
+ * Formats a `number` for printing.
+ */
+export declare const print_number: (value: number) => string;
+/**
+ * Formats a `boolean` for printing.
+ */
+export declare const print_boolean: (value: boolean) => string;
+/**
+ * Formats any value for printing.
+ */
+export declare const print_value: (value: unknown) => string;
+/**
+ * Formats an error for printing.
+ * Because throwing errors and rejecting promises isn't typesafe,
+ * don't assume the arg is an `Error` and try to return something useful.
+ */
+export declare const print_error: (err: Error) => string;
+/**
+ * Formats a timing entry with `key` for printing.
+ */
+export declare const print_timing: (key: string | number, timing: number | undefined) => string;
+/**
+ * Prints all timings in a `Timings` object.
+ */
+export declare const print_timings: (timings: Timings, log: Logger) => void;
+//# sourceMappingURL=print.d.ts.map

package/dist/print.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"print.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/print.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,UAAU,CAAC;AAErC,eAAO,IAAI,EAAE,EAAE,OAAO,SAAuB,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAClC,GAAG,OAAO,SAAS,GAAG,IAAI,GAAG,SAAS,KACpC,OAAO,SAGT,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,EAAE,OAAO,MAAM,GAAG,MAAM,KAAG,MACtB,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,IAAI,MAAM,EAAE,WAAW,MAAM,EAAE,YAAY,MAAM,KAAG,MAI5E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,4BAA4B,GAAI,GAAG,MAAM,EAAE,kBAAe,KAAG,MAYzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAAmC,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAAgC,CAAC;AAE9E;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,MAAkC,CAAC;AAElF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,KAAG,MAgB5C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,KAAK,KAAG,MAIvC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,GAAG,MAAM,EAAE,QAAQ,MAAM,GAAG,SAAS,KAAG,MAC2B,CAAC;AAE5G;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,OAAO,EAAE,KAAK,MAAM,KAAG,IAI7D,CAAC"}

package/dist/print.js

@@ -0,0 +1,89 @@
+export let st = (_, v) => v;
+/**
+ * Configures the module-level styling function for colored output.
+ * @mutates st assigns the module-level `st` variable
+ */
+export const configure_print_colors = (s) => {
+    st = s ?? ((_, v) => v);
+    return st;
+};
+/**
+ * Formats a key-value pair for printing.
+ */
+export const print_key_value = (key, value) => st('gray', `${key}(`) + value + st('gray', ')');
+/**
+ * Formats a `number` of milliseconds for printing.
+ */
+export const print_ms = (ms, decimals, separator) => {
+    const decimal_count = decimals ?? (ms >= 10 ? 0 : ms < 0.1 ? 2 : 1);
+    const rounded = ms.toFixed(decimal_count);
+    return st('white', print_number_with_separators(rounded, separator)) + st('gray', 'ms');
+};
+/**
+ * Formats a `number` with separators for improved readability.
+ */
+export const print_number_with_separators = (v, separator = ',') => {
+    if (!separator)
+        return v;
+    const decimal_index = v.indexOf('.');
+    const start_index = (decimal_index === -1 ? v.length : decimal_index) - 1;
+    let s = decimal_index === -1 ? '' : v.slice(start_index + 1);
+    let count = 0;
+    for (let i = start_index; i >= 0; i--) {
+        count++;
+        if (count > 3 && count % 3 === 1)
+            s = separator + s;
+        s = v[i] + s;
+    }
+    return s;
+};
+/**
+ * Formats a `string` for printing.
+ */
+export const print_string = (value) => st('green', `'${value}'`);
+/**
+ * Formats a `number` for printing.
+ */
+export const print_number = (value) => st('cyan', value + '');
+/**
+ * Formats a `boolean` for printing.
+ */
+export const print_boolean = (value) => st('yellow', value + '');
+/**
+ * Formats any value for printing.
+ */
+export const print_value = (value) => {
+    if (Array.isArray(value)) {
+        return st('blue', '[') + value.map(print_value).join(st('blue', ', ')) + st('blue', ']');
+    }
+    switch (typeof value) {
+        case 'string':
+            return print_string(value);
+        case 'number':
+            return print_number(value);
+        case 'boolean':
+            return print_boolean(value);
+        case 'object':
+            return value === null ? st('blue', 'null') : st('magenta', JSON.stringify(value));
+        default:
+            return st('blue', value + '');
+    }
+};
+/**
+ * Formats an error for printing.
+ * Because throwing errors and rejecting promises isn't typesafe,
+ * don't assume the arg is an `Error` and try to return something useful.
+ */
+export const print_error = (err) => st('yellow', err.stack ?? ((err.message && `Error: ${err.message}`) || `Unknown error: ${err}`));
+/**
+ * Formats a timing entry with `key` for printing.
+ */
+export const print_timing = (key, timing) => `${timing === undefined ? '...' : print_ms(timing, undefined)} ${st('gray', '←')} ${st('gray', key + '')}`;
+/**
+ * Prints all timings in a `Timings` object.
+ */
+export const print_timings = (timings, log) => {
+    for (const [key, timing] of timings.entries()) {
+        log.debug(print_timing(key, timing));
+    }
+};

package/dist/process.d.ts

@@ -0,0 +1,77 @@
+import { type SpawnOptions, type ChildProcess } from 'node:child_process';
+import type { Result } from './result.js';
+export interface SpawnedProcess {
+    child: ChildProcess;
+    closed: Promise<SpawnResult>;
+}
+export interface Spawned {
+    child: ChildProcess;
+    signal: NodeJS.Signals | null;
+    code: number | null;
+}
+export type SpawnResult = Result<Spawned, Spawned>;
+/**
+ * A convenient promise wrapper around `spawn_process`
+ * intended for commands that have an end, not long running-processes like watchers.
+ * Any more advanced usage should use `spawn_process` directly for access to the `child` process.
+ */
+export declare const spawn: (...args: Parameters<typeof spawn_process>) => Promise<SpawnResult>;
+export interface SpawnedOut {
+    result: SpawnResult;
+    stdout: string | null;
+    stderr: string | null;
+}
+/**
+ * Similar to `spawn` but buffers and returns `stdout` and `stderr` as strings.
+ */
+export declare const spawn_out: (command: string, args?: ReadonlyArray<string>, options?: SpawnOptions) => Promise<SpawnedOut>;
+/**
+ * Wraps the normal Node `childProcess.spawn` with graceful child shutdown behavior.
+ * Also returns a convenient `closed` promise.
+ * If you only need `closed`, prefer the shorthand function `spawn`.
+ * @mutates global_spawn calls `register_global_spawn()` which adds to the module-level Set
+ */
+export declare const spawn_process: (command: string, args?: ReadonlyArray<string>, options?: SpawnOptions) => SpawnedProcess;
+export declare const print_child_process: (child: ChildProcess) => string;
+/**
+ * We register spawned processes gloabally so we can gracefully exit child processes.
+ * Otherwise, errors can cause zombie processes, sometimes blocking ports even!
+ */
+export declare const global_spawn: Set<ChildProcess>;
+/**
+ * Returns a function that unregisters the `child`.
+ * @param child the child process to register
+ * @returns cleanup function that removes the child from `global_spawn`
+ * @mutates global_spawn adds child to the module-level Set, and the returned function removes it
+ */
+export declare const register_global_spawn: (child: ChildProcess) => (() => void);
+/**
+ * Kills a child process and returns a `SpawnResult`.
+ */
+export declare const despawn: (child: ChildProcess) => Promise<SpawnResult>;
+/**
+ * Kills all globally registered child processes.
+ * @mutates global_spawn indirectly removes processes through `despawn()` calls
+ */
+export declare const despawn_all: () => Promise<Array<SpawnResult>>;
+/**
+ * Attaches the `'uncoughtException'` event to despawn all processes,
+ * and enables custom error logging with `to_error_label`.
+ * @param to_error_label - Customize the error label or return `null` for the default `origin`.
+ * @param map_error_text - Customize the error text. Return `''` to silence, or `null` for the default `print_error(err)`.
+ */
+export declare const attach_process_error_handlers: (to_error_label?: (err: Error, origin: NodeJS.UncaughtExceptionOrigin) => string | null, map_error_text?: (err: Error, origin: NodeJS.UncaughtExceptionOrigin) => string | null, handle_error?: (err: Error, origin: NodeJS.UncaughtExceptionOrigin) => void) => void;
+/**
+ * Formats a `SpawnResult` for printing.
+ */
+export declare const print_spawn_result: (result: SpawnResult) => string;
+export interface RestartableProcess {
+    restart: () => void;
+    kill: () => Promise<void>;
+}
+/**
+ * Like `spawn_process` but with `restart` and `kill`,
+ * handling many concurrent `restart` calls gracefully.
+ */
+export declare const spawn_restartable_process: (command: string, args?: ReadonlyArray<string>, options?: SpawnOptions) => RestartableProcess;
+//# sourceMappingURL=process.d.ts.map