@fuzdev/fuz_util 0.42.0

package/dist/fs.js

@@ -0,0 +1,73 @@
+import { rm, readdir, access, constants } from 'node:fs/promises';
+import { join, isAbsolute } from 'node:path';
+import { EMPTY_OBJECT } from './object.js';
+import { to_array } from './array.js';
+import { ensure_end } from './string.js';
+/**
+ * Checks if a file or directory exists.
+ */
+export const fs_exists = async (path) => {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Empties a directory, recursively by default. If `should_remove` is provided, only entries where it returns `true` are removed.
+ */
+export const fs_empty_dir = async (dir, should_remove, options) => {
+    const entries = await readdir(dir);
+    const to_remove = should_remove ? entries.filter(should_remove) : entries;
+    await Promise.all(to_remove.map((name) => rm(join(dir, name), { recursive: true, ...options })));
+};
+export const fs_search = async (dir, options = EMPTY_OBJECT) => {
+    const { filter, file_filter, sort = default_sort, include_directories = false, cwd = process.cwd(), } = options;
+    const final_dir = ensure_end(cwd && !isAbsolute(dir) ? join(cwd, dir) : dir, '/');
+    const filters = !filter || (Array.isArray(filter) && !filter.length) ? undefined : to_array(filter);
+    const file_filters = !file_filter || (Array.isArray(file_filter) && !file_filter.length)
+        ? undefined
+        : to_array(file_filter);
+    const paths = []; // mutated
+    try {
+        await crawl(final_dir, paths, filters, file_filters, include_directories, null);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return sort ? paths.sort(typeof sort === 'boolean' ? default_sort : sort) : paths;
+};
+const default_sort = (a, b) => a.path.localeCompare(b.path);
+/**
+ * Recursively crawls a directory, collecting paths.
+ * @mutates paths - appends discovered files and directories
+ */
+const crawl = async (dir, paths, filters, file_filters, include_directories, base_dir) => {
+    let subdirs;
+    const dirents = await readdir(dir, { withFileTypes: true });
+    for (const dirent of dirents) {
+        const { name, parentPath } = dirent;
+        const is_directory = dirent.isDirectory();
+        const id = parentPath + name;
+        if (filters && !filters.every((f) => f(id, is_directory))) {
+            continue;
+        }
+        const path = base_dir === null ? name : base_dir + '/' + name;
+        if (is_directory) {
+            const dir_id = id + '/';
+            if (include_directories) {
+                paths.push({ path, id: dir_id, is_directory: true });
+            }
+            (subdirs ??= []).push(crawl(dir_id, paths, filters, file_filters, include_directories, path));
+        }
+        else if (!file_filters || file_filters.every((f) => f(id))) {
+            paths.push({ path, id, is_directory: false });
+        }
+    }
+    if (subdirs)
+        await Promise.all(subdirs);
+};

package/dist/function.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Does nothing when called.
+ */
+export declare const noop: (...args: Array<any>) => any;
+/**
+ * Async function that returns a resolved promise.
+ */
+export declare const noop_async: (...args: Array<any>) => Promise<any>;
+/**
+ * A singleton resolved `Promise`.
+ */
+export declare const resolved: Promise<void>;
+/**
+ * Returns the first arg.
+ */
+export declare const identity: <T>(t: T) => T;
+/**
+ * Represents a value wrapped in a function.
+ * Useful for lazy values and bridging reactive boundaries in Svelte.
+ */
+export type Thunk<T> = () => T;
+/**
+ * Returns the result of calling `value` if it's a function,
+ * otherwise it's like the `identity` function and passes it through.
+ */
+export declare const unthunk: <T>(value: T | Thunk<T>) => T;
+//# sourceMappingURL=function.d.ts.map

package/dist/function.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/function.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,GAAc,CAAC;AAE3D;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,GAAG,CAAkB,CAAC;AAEhF;;GAEG;AACH,eAAO,MAAM,QAAQ,eAAoB,CAAC;AAE1C;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,GAAG,CAAC,KAAG,CAAM,CAAC;AAE1C;;;GAGG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC;AAE/B;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,KAAG,CACM,CAAC"}

package/dist/function.js

@@ -0,0 +1,21 @@
+/**
+ * Does nothing when called.
+ */
+export const noop = () => { }; // eslint-disable-line @typescript-eslint/no-empty-function
+/**
+ * Async function that returns a resolved promise.
+ */
+export const noop_async = () => resolved;
+/**
+ * A singleton resolved `Promise`.
+ */
+export const resolved = Promise.resolve();
+/**
+ * Returns the first arg.
+ */
+export const identity = (t) => t;
+/**
+ * Returns the result of calling `value` if it's a function,
+ * otherwise it's like the `identity` function and passes it through.
+ */
+export const unthunk = (value) => typeof value === 'function' ? value() : value;

package/dist/git.d.ts

@@ -0,0 +1,132 @@
+import type { SpawnOptions } from 'node:child_process';
+import { z } from 'zod';
+import type { Flavored } from './types.js';
+export declare const GitOrigin: z.ZodString;
+export type GitOrigin = Flavored<string, 'GitOrigin'>;
+export declare const GitBranch: z.ZodString;
+export type GitBranch = Flavored<string, 'GitBranch'>;
+/**
+ * Returns the current git branch name or throws if something goes wrong.
+ */
+export declare const git_current_branch_name: (options?: SpawnOptions) => Promise<GitBranch>;
+/**
+ * @returns a boolean indicating if the remote git branch exists
+ */
+export declare const git_remote_branch_exists: (origin?: GitOrigin, branch?: GitBranch, options?: SpawnOptions) => Promise<boolean>;
+/**
+ * @returns a boolean indicating if the local git branch exists
+ */
+export declare const git_local_branch_exists: (branch: GitBranch, options?: SpawnOptions) => Promise<boolean>;
+/**
+ * Git workspace status flags indicating which types of changes are present.
+ */
+export interface GitWorkspaceStatus {
+    unstaged_changes: boolean;
+    staged_changes: boolean;
+    untracked_files: boolean;
+}
+/**
+ * Parses the output of `git status --porcelain -z` (v1 format) into a status object.
+ * This is a pure function that can be tested independently.
+ *
+ * Format: XY path\0 where:
+ * - X = staged status (index)
+ * - Y = unstaged status (work tree)
+ * - path = file path (unescaped with -z)
+ *
+ * Supported status codes:
+ * - M = modified
+ * - A = added
+ * - D = deleted
+ * - R = renamed
+ * - C = copied
+ * - T = type changed (regular file, symbolic link or submodule)
+ * - U = unmerged
+ * - ? = untracked
+ * - ! = ignored
+ *
+ * For renames/copies: XY new\0old\0 (two NUL-separated paths)
+ *
+ * Note: This implementation treats submodules the same as regular files.
+ * Submodule-specific status codes (lowercase m, ?) are interpreted as changes.
+ *
+ * @param stdout - The raw output from `git status --porcelain -z`
+ * @returns status object with flags for unstaged changes, staged changes, and untracked files
+ */
+export declare const git_parse_workspace_status: (stdout: string | null) => GitWorkspaceStatus;
+/**
+ * Checks the git workspace status using a single `git status --porcelain -z` call.
+ * The -z format provides more reliable parsing by using NUL separators and avoiding escaping.
+ * @returns status object with flags for unstaged changes, staged changes, and untracked files
+ */
+export declare const git_check_workspace: (options?: SpawnOptions) => Promise<GitWorkspaceStatus>;
+/**
+ * @returns `true` if the workspace has no changes at all
+ */
+export declare const git_workspace_is_clean: (status: GitWorkspaceStatus) => boolean;
+/**
+ * @returns `true` if the workspace has no unstaged changes and no untracked files (staged changes are OK)
+ */
+export declare const git_workspace_is_fully_staged: (status: GitWorkspaceStatus) => boolean;
+/**
+ * Converts a workspace status to a human-readable message.
+ */
+export declare const git_workspace_status_message: (status: GitWorkspaceStatus) => string;
+/**
+ * @returns an error message if the git workspace has any unstaged or uncommitted changes, or `null` if it's clean
+ */
+export declare const git_check_clean_workspace: (options?: SpawnOptions) => Promise<string | null>;
+/**
+ * @returns an error message if the git workspace has any unstaged changes or untracked files, or `null` if fully staged
+ */
+export declare const git_check_fully_staged_workspace: (options?: SpawnOptions) => Promise<string | null>;
+/**
+ * Calls `git fetch` and throws if anything goes wrong.
+ */
+export declare const git_fetch: (origin?: GitOrigin, branch?: GitBranch, options?: SpawnOptions) => Promise<void>;
+/**
+ * Calls `git checkout` and throws if anything goes wrong.
+ * @returns the previous branch name, if it changed
+ */
+export declare const git_checkout: (branch: GitBranch, options?: SpawnOptions) => Promise<GitBranch | null>;
+/**
+ * Calls `git pull` and throws if anything goes wrong.
+ */
+export declare const git_pull: (origin?: GitOrigin, branch?: GitBranch, options?: SpawnOptions) => Promise<void>;
+/**
+ * Calls `git push` and throws if anything goes wrong.
+ */
+export declare const git_push: (origin: GitOrigin, branch?: GitBranch, options?: SpawnOptions, set_upstream?: boolean) => Promise<void>;
+/**
+ * Calls `git push` and throws if anything goes wrong.
+ */
+export declare const git_push_to_create: (origin?: GitOrigin, branch?: GitBranch, options?: SpawnOptions) => Promise<void>;
+/**
+ * Deletes a branch locally and throws if anything goes wrong.
+ */
+export declare const git_delete_local_branch: (branch: GitBranch, options?: SpawnOptions) => Promise<void>;
+/**
+ * Deletes a branch remotely and throws if anything goes wrong.
+ */
+export declare const git_delete_remote_branch: (origin: GitOrigin, branch: GitBranch, options?: SpawnOptions) => Promise<void>;
+/**
+ * Resets the `target` branch back to its first commit both locally and remotely.
+ */
+export declare const git_reset_branch_to_first_commit: (origin: GitOrigin, branch: GitBranch, options?: SpawnOptions) => Promise<void>;
+/**
+ * Returns the branch's latest commit hash or throws if something goes wrong.
+ */
+export declare const git_current_commit_hash: (branch?: string, options?: SpawnOptions) => Promise<string | null>;
+/**
+ * Returns the hash of the current branch's first commit or throws if something goes wrong.
+ */
+export declare const git_current_branch_first_commit_hash: (options?: SpawnOptions) => Promise<string>;
+/**
+ * Returns the global git config setting for `pull.rebase`.
+ */
+export declare const git_check_setting_pull_rebase: (options?: SpawnOptions) => Promise<boolean>;
+/**
+ * Clones a branch locally to another directory and updates the origin to match the source.
+ */
+export declare const git_clone_locally: (origin: GitOrigin, branch: GitBranch, source_dir: string, target_dir: string, options?: SpawnOptions) => Promise<void>;
+//# sourceMappingURL=git.d.ts.map

package/dist/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/git.ts"],"names":[],"mappings":"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"}

package/dist/git.js

@@ -0,0 +1,288 @@
+import { z } from 'zod';
+import { spawn, spawn_out } from './process.js';
+import { to_file_path } from './path.js';
+import { fs_exists } from './fs.js';
+export const GitOrigin = z.string();
+export const GitBranch = z.string();
+/**
+ * Returns the current git branch name or throws if something goes wrong.
+ */
+export const git_current_branch_name = async (options) => {
+    const { stdout } = await spawn_out('git', ['rev-parse', '--abbrev-ref', 'HEAD'], options);
+    if (!stdout)
+        throw Error('git_current_branch_name failed');
+    const branch_name = stdout.trim();
+    return branch_name;
+};
+/**
+ * @returns a boolean indicating if the remote git branch exists
+ */
+export const git_remote_branch_exists = async (origin = 'origin', branch, options) => {
+    const final_branch = branch ?? (await git_current_branch_name(options));
+    if (options?.cwd && !(await fs_exists(to_file_path(options.cwd)))) {
+        return false;
+    }
+    const result = await spawn('git', ['ls-remote', '--exit-code', '--heads', origin, 'refs/heads/' + final_branch], options);
+    if (result.ok) {
+        return true;
+    }
+    else if (result.code === 2) {
+        return false;
+    }
+    else {
+        throw Error(`git_remote_branch_exists failed for origin '${origin}' and branch '${final_branch}' with code ${result.code}`);
+    }
+};
+/**
+ * @returns a boolean indicating if the local git branch exists
+ */
+export const git_local_branch_exists = async (branch, options) => {
+    if (options?.cwd && !(await fs_exists(to_file_path(options.cwd)))) {
+        return false;
+    }
+    const result = await spawn('git', ['show-ref', '--quiet', 'refs/heads/' + branch], options);
+    return result.ok;
+};
+/**
+ * Parses the output of `git status --porcelain -z` (v1 format) into a status object.
+ * This is a pure function that can be tested independently.
+ *
+ * Format: XY path\0 where:
+ * - X = staged status (index)
+ * - Y = unstaged status (work tree)
+ * - path = file path (unescaped with -z)
+ *
+ * Supported status codes:
+ * - M = modified
+ * - A = added
+ * - D = deleted
+ * - R = renamed
+ * - C = copied
+ * - T = type changed (regular file, symbolic link or submodule)
+ * - U = unmerged
+ * - ? = untracked
+ * - ! = ignored
+ *
+ * For renames/copies: XY new\0old\0 (two NUL-separated paths)
+ *
+ * Note: This implementation treats submodules the same as regular files.
+ * Submodule-specific status codes (lowercase m, ?) are interpreted as changes.
+ *
+ * @param stdout - The raw output from `git status --porcelain -z`
+ * @returns status object with flags for unstaged changes, staged changes, and untracked files
+ */
+export const git_parse_workspace_status = (stdout) => {
+    // Split on NUL character (\0) for -z format
+    // Filter out empty strings (last element after final \0)
+    const entries = stdout?.split('\0').filter(Boolean) ?? [];
+    // For rename/copy operations, we need to skip the old filename entry
+    // Format: R  new\0old\0 or C  new\0old\0
+    let skipNext = false;
+    const lines = [];
+    for (const entry of entries) {
+        if (skipNext) {
+            skipNext = false;
+            continue;
+        }
+        // Check if this is a rename/copy operation in either position
+        // R  = renamed in index, RM = renamed in index + modified in work tree
+        //  R = renamed in work tree (rare but possible with certain configs)
+        if (entry.length >= 3 &&
+            (entry[0] === 'R' || entry[0] === 'C' || entry[1] === 'R' || entry[1] === 'C')) {
+            skipNext = true;
+        }
+        lines.push(entry);
+    }
+    return {
+        // Y position (index 1) - any non-space, non-?, non-! means unstaged changes
+        // Minimum length is 3: XY followed by at least one space (e.g., "M  ")
+        unstaged_changes: lines.some((line) => line.length >= 3 && line[1] !== ' ' && line[1] !== '?' && line[1] !== '!'),
+        // X position (index 0) - any non-space, non-?, non-! means staged changes
+        // Minimum length is 3: XY followed by at least one space (e.g., "M  ")
+        staged_changes: lines.some((line) => line.length >= 3 && line[0] !== ' ' && line[0] !== '?' && line[0] !== '!'),
+        // ?? prefix means untracked files
+        untracked_files: lines.some((line) => line.startsWith('??')),
+    };
+};
+/**
+ * Checks the git workspace status using a single `git status --porcelain -z` call.
+ * The -z format provides more reliable parsing by using NUL separators and avoiding escaping.
+ * @returns status object with flags for unstaged changes, staged changes, and untracked files
+ */
+export const git_check_workspace = async (options) => {
+    const { stdout } = await spawn_out('git', ['status', '--porcelain', '-z'], options);
+    return git_parse_workspace_status(stdout);
+};
+/**
+ * @returns `true` if the workspace has no changes at all
+ */
+export const git_workspace_is_clean = (status) => !status.unstaged_changes && !status.staged_changes && !status.untracked_files;
+/**
+ * @returns `true` if the workspace has no unstaged changes and no untracked files (staged changes are OK)
+ */
+export const git_workspace_is_fully_staged = (status) => !status.unstaged_changes && !status.untracked_files;
+/**
+ * Converts a workspace status to a human-readable message.
+ */
+export const git_workspace_status_message = (status) => {
+    if (git_workspace_is_clean(status))
+        return 'workspace is clean';
+    const issues = [];
+    if (status.unstaged_changes)
+        issues.push('unstaged changes');
+    if (status.staged_changes)
+        issues.push('staged but uncommitted changes');
+    if (status.untracked_files)
+        issues.push('untracked files');
+    return `git has ${issues.join(', ')}`;
+};
+/**
+ * @returns an error message if the git workspace has any unstaged or uncommitted changes, or `null` if it's clean
+ */
+export const git_check_clean_workspace = async (options) => {
+    const status = await git_check_workspace(options);
+    return git_workspace_is_clean(status) ? null : git_workspace_status_message(status);
+};
+/**
+ * @returns an error message if the git workspace has any unstaged changes or untracked files, or `null` if fully staged
+ */
+export const git_check_fully_staged_workspace = async (options) => {
+    const status = await git_check_workspace(options);
+    return git_workspace_is_fully_staged(status) ? null : git_workspace_status_message(status);
+};
+/**
+ * Calls `git fetch` and throws if anything goes wrong.
+ */
+export const git_fetch = async (origin = 'origin', branch, options) => {
+    const args = ['fetch', origin];
+    if (branch)
+        args.push(branch);
+    const result = await spawn('git', args, options);
+    if (!result.ok) {
+        throw Error(`git_fetch failed for origin '${origin}' and branch '${branch}' with code ${result.code}`);
+    }
+};
+/**
+ * Calls `git checkout` and throws if anything goes wrong.
+ * @returns the previous branch name, if it changed
+ */
+export const git_checkout = async (branch, options) => {
+    const current_branch = await git_current_branch_name(options);
+    if (branch === current_branch) {
+        return null;
+    }
+    const result = await spawn('git', ['checkout', branch], options);
+    if (!result.ok) {
+        throw Error(`git_checkout failed for branch '${branch}' with code ${result.code}`);
+    }
+    return current_branch;
+};
+/**
+ * Calls `git pull` and throws if anything goes wrong.
+ */
+export const git_pull = async (origin = 'origin', branch, options) => {
+    const args = ['pull', origin];
+    if (branch)
+        args.push(branch);
+    const result = await spawn('git', args, options);
+    if (!result.ok) {
+        throw Error(`git_pull failed for branch '${branch}' with code ${result.code}`);
+    }
+};
+/**
+ * Calls `git push` and throws if anything goes wrong.
+ */
+export const git_push = async (origin, branch, options, set_upstream = false) => {
+    const final_branch = branch ?? (await git_current_branch_name(options));
+    const args = ['push', origin, final_branch];
+    if (set_upstream)
+        args.push('-u');
+    const result = await spawn('git', args, options);
+    if (!result.ok) {
+        throw Error(`git_push failed for branch '${final_branch}' with code ${result.code}`);
+    }
+};
+/**
+ * Calls `git push` and throws if anything goes wrong.
+ */
+export const git_push_to_create = async (origin = 'origin', branch, options) => {
+    const final_branch = branch ?? (await git_current_branch_name(options));
+    const push_args = ['push'];
+    if (await git_remote_branch_exists(origin, final_branch, options)) {
+        push_args.push(origin);
+    }
+    else {
+        push_args.push('-u', origin);
+    }
+    push_args.push(final_branch);
+    const result = await spawn('git', push_args, options);
+    if (!result.ok) {
+        throw Error(`git_push failed for branch '${final_branch}' with code ${result.code}`);
+    }
+};
+/**
+ * Deletes a branch locally and throws if anything goes wrong.
+ */
+export const git_delete_local_branch = async (branch, options) => {
+    const result = await spawn('git', ['branch', '-D', branch], options);
+    if (!result.ok) {
+        throw Error(`git_delete_local_branch failed for branch '${branch}' with code ${result.code}`);
+    }
+};
+/**
+ * Deletes a branch remotely and throws if anything goes wrong.
+ */
+export const git_delete_remote_branch = async (origin, branch, options) => {
+    const result = await spawn('git', ['push', origin, ':' + branch], options);
+    if (!result.ok) {
+        throw Error(`git_delete_remote_branch failed for branch '${branch}' with code ${result.code}`);
+    }
+};
+/**
+ * Resets the `target` branch back to its first commit both locally and remotely.
+ */
+export const git_reset_branch_to_first_commit = async (origin, branch, options) => {
+    const previous_branch = await git_checkout(branch, options);
+    const first_commit_hash = await git_current_branch_first_commit_hash(options);
+    await spawn('git', ['reset', '--hard', first_commit_hash], options);
+    await spawn('git', ['push', origin, branch, '--force'], options);
+    if (previous_branch) {
+        await git_checkout(previous_branch, options);
+    }
+};
+/**
+ * Returns the branch's latest commit hash or throws if something goes wrong.
+ */
+export const git_current_commit_hash = async (branch, options) => {
+    const final_branch = branch ?? (await git_current_branch_name(options));
+    const { stdout } = await spawn_out('git', ['show-ref', '-s', final_branch], options);
+    if (!stdout)
+        return null; // TODO hack for CI
+    return stdout.split('\n')[0].trim();
+};
+/**
+ * Returns the hash of the current branch's first commit or throws if something goes wrong.
+ */
+export const git_current_branch_first_commit_hash = async (options) => {
+    const { stdout } = await spawn_out('git', ['rev-list', '--max-parents=0', '--abbrev-commit', 'HEAD'], options);
+    if (!stdout)
+        throw Error('git_current_branch_first_commit_hash failed');
+    return stdout.trim();
+};
+/**
+ * Returns the global git config setting for `pull.rebase`.
+ */
+export const git_check_setting_pull_rebase = async (options) => {
+    const value = await spawn_out('git', ['config', '--global', 'pull.rebase'], options);
+    return value.stdout?.trim() === 'true';
+};
+/**
+ * Clones a branch locally to another directory and updates the origin to match the source.
+ */
+export const git_clone_locally = async (origin, branch, source_dir, target_dir, options) => {
+    await spawn('git', ['clone', '-b', branch, '--single-branch', source_dir, target_dir], options);
+    const origin_url = (await spawn_out('git', ['remote', 'get-url', origin], { ...options, cwd: source_dir })).stdout?.trim();
+    if (!origin_url)
+        throw Error('Failed to get the origin url with git in ' + source_dir);
+    await spawn('git', ['remote', 'set-url', origin, origin_url], { ...options, cwd: target_dir });
+};

package/dist/id.d.ts

@@ -0,0 +1,18 @@
+import type { Flavored } from './types.js';
+export type Uuid = Flavored<string, 'Uuid'>;
+/**
+ * Loosely validates a UUID string.
+ */
+export declare const is_uuid: (str: string) => str is Uuid;
+/**
+ * Postgres doesn't support the namespace prefix, so neither does Felt.
+ * For more see the UUID RFC - https://tools.ietf.org/html/rfc4122
+ * The Ajv validator does support the namespace, hence this custom implementation.
+ */
+export declare const UUID_MATCHER: RegExp;
+export type ClientIdCreator = () => string;
+/**
+ * Creates a string id generator function, outputting `${name}_${count}` by default.
+ */
+export declare const create_client_id_creator: (name: string, count?: number, separator?: string) => ClientIdCreator;
+//# sourceMappingURL=id.d.ts.map

package/dist/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/id.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AAGzC,MAAM,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,KAAG,GAAG,IAAI,IAA8B,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAoD,CAAC;AAE9E,MAAM,MAAM,eAAe,GAAG,MAAM,MAAM,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,kBAAe,KACb,eAGF,CAAC"}

package/dist/id.js

@@ -0,0 +1,18 @@
+import { create_counter } from './counter.js';
+/**
+ * Loosely validates a UUID string.
+ */
+export const is_uuid = (str) => UUID_MATCHER.test(str);
+/**
+ * Postgres doesn't support the namespace prefix, so neither does Felt.
+ * For more see the UUID RFC - https://tools.ietf.org/html/rfc4122
+ * The Ajv validator does support the namespace, hence this custom implementation.
+ */
+export const UUID_MATCHER = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/iu;
+/**
+ * Creates a string id generator function, outputting `${name}_${count}` by default.
+ */
+export const create_client_id_creator = (name, count, separator = '_') => {
+    const counter = create_counter(count);
+    return () => `${name}${separator}${counter()}`;
+};

package/dist/iterator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Useful for fast counting when `.length` is not available.
+ */
+export declare const count_iterator: (iterator: Iterable<unknown>) => number;
+//# sourceMappingURL=iterator.d.ts.map

package/dist/iterator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterator.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/iterator.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,QAAQ,CAAC,OAAO,CAAC,KAAG,MAI5D,CAAC"}

package/dist/iterator.js

@@ -0,0 +1,9 @@
+/**
+ * Useful for fast counting when `.length` is not available.
+ */
+export const count_iterator = (iterator) => {
+    var count = 0;
+    for (var _ of iterator)
+        count++;
+    return count;
+};

package/dist/json.d.ts

@@ -0,0 +1,30 @@
+export type Json = JsonPrimitive | JsonObject | JsonArray;
+export type JsonPrimitive = string | number | boolean | null;
+export interface JsonObject extends Record<string, Json> {
+}
+export interface JsonArray extends Array<Json> {
+}
+/**
+ * Like `typeof json`, but includes arrays. Excludes `'undefined'` because it's not valid JSON.
+ */
+export type JsonType = 'string' | 'number' | 'boolean' | 'null' | 'object' | 'array';
+/**
+ * Returns the `JsonType` of `value`, which is like `typeof json`
+ * but includes `'array'` and omits `'undefined'`.
+ */
+export declare const json_type_of: (value: Json) => JsonType | undefined;
+/**
+ * Embeds `data` as a JSON string, escaping single quotes.
+ * Useful for optimizing JSON in JS because it parses faster.
+ */
+export declare const json_embed: <T>(data: T, stringify?: (data: T) => string) => string;
+/**
+ * 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 declare const json_stringify_deterministic: (value: unknown) => string;
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/json.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,IAAI,GAAG,aAAa,GAAG,UAAU,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAE7D,MAAM,WAAW,UAAW,SAAQ,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC;CAAG;AAE3D,MAAM,WAAW,SAAU,SAAQ,KAAK,CAAC,IAAI,CAAC;CAAG;AAEjD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAErF;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,IAAI,KAAG,QAAQ,GAAG,SAerD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,MAAM,CAAC,EAAE,YAAW,CAAC,IAAI,EAAE,CAAC,KAAK,MAAuB,KAAG,MACN,CAAC;AAEpF;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,GAAI,OAAO,OAAO,KAAG,MAW3D,CAAC"}