@versionzero/schema 1.0.0

package/types/core-library/schemas/object-schema.d.ts

@@ -0,0 +1,2 @@
+export const OBJECT_SCHEMA: Schema;
+import { Schema } from '../../schema.js';

package/types/core-library/schemas/root-schema.d.ts

@@ -0,0 +1,2 @@
+export const ROOT_SCHEMA: Schema;
+import { Schema } from '../../schema.js';

package/types/core-library/schemas/string-schema.d.ts

@@ -0,0 +1,2 @@
+export const STRING_SCHEMA: Schema;
+import { Schema } from '../../schema.js';

package/types/core-library-node/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Node.js-specific schemas and processors.
+ *
+ * Loaded automatically when running under Node.js.  Registers the `buffer`
+ * schema type and processors that depend on `node:fs`, `node:dns`, or the
+ * Node.js `Buffer` global.
+ *
+ * @param {SchemaResolver} resolver
+ * @param {object} options
+ */
+export default function coreLibraryNode(resolver: SchemaResolver, options: object): void;
+import type { SchemaResolver } from '../schema-resolver.js';

package/types/core-library-node/processors/base64-decode-operator.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ## $base64-decode
+ *
+ * Decodes a Base64-encoded string to a Buffer.
+ * Throws if the input is not a string.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const BASE64_DECODE_OPERATOR: import("../../value-processor/value-processor.js").ValueProcessorDefinition;

package/types/core-library-node/processors/base64-encode-operator.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ## $base64-encode
+ *
+ * Encodes a Buffer to a Base64 string.
+ * Throws if the input is not a Buffer.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const BASE64_ENCODE_OPERATOR: import("../../value-processor/value-processor.js").ValueProcessorDefinition;

package/types/core-library-node/processors/buffer-operator.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ## $buffer
+ *
+ * Converts a value to a Node.js Buffer.  Accepts:
+ * - `Buffer` — passed through unchanged
+ * - `string` — decoded from Base64 via `Buffer.from(value, 'base64')`
+ * - `{size, fill?, encoding?}` — allocated via `Buffer.alloc(size, fill, encoding)`
+ * - `{encoding, buffer}` — constructed from an underlying ArrayBuffer via `Buffer.from(value.buffer)`
+ * - anything else (TypedArray, byte array, etc.) — via `Buffer.from(value)`
+ *
+ * See `$is-buffer` for strict Buffer validation without conversion.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const BUFFER_OPERATOR: import("../../value-processor/value-processor.js").ValueProcessorDefinition;

package/types/core-library-node/processors/directory-constraint.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ## $directory
+ *
+ * Validates that a path exists on the filesystem and is a directory (not a file).
+ * This is an **async processor** that performs filesystem operations.
+ *
+ * The processor checks both existence and type, throwing distinct errors for:
+ * - Path does not exist (`ENOENT`)
+ * - Path exists but is a file, symlink, or other non-directory type
+ * - Path is inaccessible due to permissions or other filesystem errors
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const DIRECTORY_CONSTRAINT: import("../../value-processor/value-processor.js").ValueProcessorDefinition;

package/types/core-library-node/processors/executable-constraint.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ## $executable
+ *
+ * Validates that a file path points to an executable file by checking execute
+ * permissions. This is an asynchronous processor that performs a file system
+ * access check.
+ *
+ * This processor is particularly useful for validating script paths, binary
+ * paths, and command executables in configuration files.
+ *
+ * **Note**: This processor performs async file system checks and should usually
+ * be used as a validator. Execution permissions are platform-dependent (Unix/Linux/macOS
+ * use chmod +x; Windows uses file extensions and ACLs).
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const EXECUTABLE_CONSTRAINT: import("../../value-processor/value-processor.js").ValueProcessorDefinition;

package/types/core-library-node/processors/file-constraint.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ## $file
+ *
+ * Validates that a path exists in the filesystem and is a file (not a directory or other type).
+ * Performs an asynchronous filesystem check using `fs.stat()`.
+ *
+ * - Non-existent paths: `"/does/not/exist.txt"` → throws "File does not exist"
+ * - Directory paths: `"/var/log"` → throws "Path exists but is not a file"
+ * - Inaccessible paths: `"/root/secret.txt"` (permission denied) → throws "Cannot access file: ..."
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const FILE_CONSTRAINT: import("../../value-processor/value-processor.js").ValueProcessorDefinition;

package/types/core-library-node/processors/file-size-constraint.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ## $file-size
+ *
+ * Validates that a file's size falls within the specified range. Accepts size constraints
+ * in bytes and checks the file's metadata without loading the entire file into memory.
+ * Can specify minimum, maximum, or both bounds.
+ *
+ * **This is an async processor** that performs filesystem I/O, and probably best suited
+ * for use during transformation or validation phases.
+ *
+ * ### Parameters
+ * - `min` (number, optional): Minimum file size in bytes (inclusive). If omitted, no lower bound.
+ * - `max` (number, optional): Maximum file size in bytes (inclusive). If omitted, no upper bound.
+ *
+ * **Unit Conversions**: Size must be specified in bytes. Use standard conversions:
+ * - 1 KB = 1024 bytes
+ * - 1 MB = 1024 * 1024 bytes (1,048,576)
+ * - 1 GB = 1024 * 1024 * 1024 bytes (1,073,741,824)
+ *
+ * **Note**: Typically used with `$file` validator to ensure the file exists before checking size.
+ * The processor reads file metadata via `fs.stat()` and does not load file contents.
+ *
+ * ### Example
+ * ```js
+ * // Validate a config file exists and is under 1 MB
+ * new Schema('string')
+ *   .validator('$file')
+ *   .validator({'$file-size': {max: 1024 * 1024}})
+ *
+ * // Require an upload file to be between 1 KB and 10 MB
+ * new Schema('string')
+ *   .validator('$file')
+ *   .validator({'$file-size': {min: 1024, max: 10 * 1024 * 1024}})
+ *
+ * // Ensure a log file is not empty
+ * new Schema('string')
+ *   .validator('$file')
+ *   .validator({'$file-size': {min: 1}})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const FILE_SIZE_CONSTRAINT: import("../../value-processor/value-processor.js").ValueProcessorDefinition;

package/types/core-library-node/processors/is-buffer-constraint.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ## $is-buffer
+ *
+ * Validates that the input is a Node.js Buffer.
+ *
+ * See `$buffer` for looser normalization that accepts values that can be converted to a Buffer.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const IS_BUFFER_CONSTRAINT: import("../../value-processor/value-processor.js").ValueProcessorDefinition;

package/types/core-library-node/processors/reachable-constraint.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ## $reachable
+ *
+ * Validates that a hostname is reachable by performing a DNS lookup.
+ * This is an asynchronous processor that checks if the hostname resolves to an IP address.
+ *
+ * Note: This processor performs a network operation and may fail if DNS is unavailable
+ * or the hostname does not exist. It does not verify that the host is responding on any port,
+ * only that it has a DNS record.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const REACHABLE_CONSTRAINT: import("../../value-processor/value-processor.js").ValueProcessorDefinition;

package/types/core-library-node/processors/readable-constraint.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ## $readable
+ *
+ * Validates that a file or directory path exists and has read permissions for the
+ * current process. Performs an asynchronous file system access check.
+ *
+ * This processor uses Node.js `fs.access()` with `R_OK` flag to verify read permissions
+ * without actually opening the file. Note that permission checks can be subject to race
+ * conditions where permissions change between validation and actual file access.
+ *
+ * (e.g., `"/etc/hosts"`, `"./config.json"`, `"~/Documents"`)
+ *
+ * or non-string values
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const READABLE_CONSTRAINT: import("../../value-processor/value-processor.js").ValueProcessorDefinition;

package/types/core-library-node/processors/writable-constraint.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ## $writable
+ *
+ * Validates that a file system path is writable by checking write permissions.
+ * If the path does not exist, validates that the parent directory exists and is writable.
+ *
+ * This is an asynchronous processor that performs file system permission checks.
+ *
+ * - Existing files with write permissions: `/tmp/output.log`, `./config.json`
+ * - Non-existent paths in writable directories: `/tmp/new-file.txt`, `./data/output.csv`
+ *
+ * - Read-only files: `/etc/hosts`, system-protected paths
+ * - Paths in non-existent parent directories: `/nonexistent/dir/file.txt`
+ * - Paths in read-only directories: `/read-only-mount/file.txt`
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const WRITABLE_CONSTRAINT: import("../../value-processor/value-processor.js").ValueProcessorDefinition;

package/types/core-library-node/schemas/buffer-schema.d.ts

@@ -0,0 +1,2 @@
+export const BUFFER_SCHEMA: Schema;
+import { Schema } from '../../schema.js';

package/types/errors.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @param {Error} error
+ * @param {RegExp|string} match
+ * @param {string} [fullErrorMessage]
+ * @param {Error} [err]
+ * @returns {boolean}
+ * @internal
+ */
+export function assertErrorMessageInCauseChain(error: Error, match: RegExp | string, fullErrorMessage?: string, err?: Error): boolean;
+export class SchemaError extends Error {
+    /**
+     * @param {string} message
+     * @param {object} [data]
+     * @param {Error|any} [data.cause]
+     * @param {string} [data.path]
+     * @param {SchemaLocation} [data.location]
+     * @param {string|number} [data.property]
+     * @param {any} [data.value]
+     * @param {number} [data.code]
+     * @param {Array<Error>} [data.errors]
+     * @param {boolean} [preserveStack]
+     */
+    constructor(message: string, data?: {
+        cause?: Error | any;
+        path?: string | undefined;
+        location?: SchemaLocation | undefined;
+        property?: string | number | undefined;
+        value?: any;
+        code?: number | undefined;
+        errors?: Error[] | undefined;
+    }, preserveStack?: boolean);
+    /** @type {any} */
+    data: any;
+    __proto__: any;
+    cause: any;
+    get name(): string;
+    set stack(str: string);
+    get stack(): string;
+}
+export class ConstraintError extends SchemaError {
+}
+export class ValidationError extends SchemaError {
+}
+export class NormalizeError extends SchemaError {
+}
+export class TransformError extends SchemaError {
+}
+export class FinalizeError extends SchemaError {
+}
+export class SerializeError extends SchemaError {
+}
+export class UnionResolutionError extends SchemaError {
+}
+export class ResolverError extends SchemaError {
+}
+export class SchemaCompilationError extends SchemaError {
+}
+import { SchemaLocation } from "./schema-location.js";

package/types/executor/array-executor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @augments {Executor<any>}
+ */
+export class ArrayExecutor extends Executor<any> {
+    /**
+     * @param {any[]|any} [array]
+     */
+    constructor(array?: any[] | any);
+    /**
+     * @param {any} input
+     * @param {...any} extra
+     * @returns {any[]|Promise<any[]>}
+     */
+    execute(input: any, ...extra: any[]): any[] | Promise<any[]>;
+    #private;
+}
+import { Executor } from './executor.js';

package/types/executor/conditional-executor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @template T
+ * @typedef {object} ConditionalExecutorActions
+ * @property {any} [success]
+ * @property {any} [failure]
+ */
+/**
+ * Checks if the provided predicate succeeds.  Usable as-is, or as a base class with behavior configured by flags.
+ *
+ * Default behavior simply tries running the predicate; if it throws or rejects, it is considered a failure.
+ *
+ * On success, the success action is called with the original input (default: returns the value)
+ * On failure, the failure action is called with the original input (default: return undefined)
+ *
+ * @template T
+ * @augments {Executor<T>}
+ */
+export class ConditionalExecutor<T> extends Executor<T> {
+    static CHECK_TRUTHY: symbol;
+    static CHECK_DEFINED: symbol;
+    static PASS_RESULT: symbol;
+    static PASS_ERROR: symbol;
+    /**
+     * Construct a `ConditionalExecutor` from a predicate and optional success/failure executors.
+     * - If no success executor is provided, the resolved value from the predicate is returned.
+     * - If no failure executor is provided, `undefined` is returned.
+     *
+     * @param {any} predicate
+     * @param {ConditionalExecutorActions<T>} [actions]
+     * @param {symbol[]} [flags]
+     */
+    constructor(predicate: any, actions?: ConditionalExecutorActions<T>, flags?: symbol[]);
+    /**
+     * @param {T} input
+     * @param {...any} variadic
+     * @returns {T|null|undefined|Promise<T|null|undefined>}
+     */
+    execute(input: T, ...variadic: any[]): T | null | undefined | Promise<T | null | undefined>;
+    #private;
+}
+export type ConditionalExecutorActions<T> = {
+    success?: any;
+    failure?: any;
+};
+import { Executor } from './executor.js';

package/types/executor/each-executor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @template T
+ * @template E
+ * @augments {Executor<T>}
+ */
+export class EachExecutor<T, E> extends Executor<T> {
+    /**
+     * @param {Executor<E>|any} each - executor to apply to each value during execute
+     * @param {(value:T|null|undefined)=>(E|null|undefined)[]} [toValues] - optional value factory
+     * @param {((values:(E|null|undefined)[],input:T|null|undefined)=>T|null|undefined)} [fromValues]
+     */
+    constructor(each: Executor<E> | any, toValues?: (value: T | null | undefined) => (E | null | undefined)[], fromValues?: ((values: (E | null | undefined)[], input: T | null | undefined) => T | null | undefined));
+    #private;
+}
+import { Executor } from './executor.js';

package/types/executor/executor.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @template T
+ * @param {T|Executor<T>|ExecutorFunction<T>} e
+ * @returns {Executor<T>}
+ */
+export function toExecutor<T>(e: T | Executor<T> | ExecutorFunction<T>): Executor<T>;
+/** @import {Thenable} from './thenable.js' */
+/**
+ * @template T
+ * @typedef {(input:T|null|undefined, ...variadic:any) => T|null|undefined|Promise<T|null|undefined>} ExecutorFunction
+ */
+/**
+ * @template T
+ * @template R
+ * @typedef {(input:T|null|undefined, ...variadic:any) => R|null|undefined|Promise<R|null|undefined>} MappingExecutorFunction
+ */
+/**
+ * An `Executor` is a composable unit of computation that processes an input into an output.
+ *
+ * Executors are designed for fine-grained runtime composition (executors calling other executors) and
+ * are frequently used in hot code paths.  Executors may be synchronous or asynchronous, but fully synchronous
+ * executor call chains are optimized to incur no async overhead.  Only the outermost call thus needs to be awaited.
+ *
+ * Errors are surfaced as exceptions or rejections.
+ *
+ * Combinator executors may catch and transform errors, or intercept and reinterpret intermediate outputs.
+ *
+ * @template T
+ */
+export class Executor<T> {
+    /**
+     * Process on a given input.
+     *
+     * The execute() method may return an output synchronously, or return a `Promise`
+     * for deferred output.  Callers must handle both cases.
+     *
+     * Output value conventions:
+     * - An output value of `null` signals that processing this input will *never* produce an output.  Most executors
+     *   receiving `null` as input should propagate it immediately without processing, although coordinator executors
+     *   that check for success or failure may choose to branch to an appropriate handler executor based on the result.
+     * - An output value of `undefined` signals that this input could not be processed *at this time*.
+     *   It is a soft signal (often used to halt a chain); individual executors define whether
+     *   `undefined` is a legal input for their context.
+     *
+     * @param {T|null|undefined} input - required primary input
+     * @param {...any} variadic - optional extra arguments (defined as needed by subclasses)
+     * @returns {T|null|undefined|Promise<T|null|undefined>}
+     */
+    execute(input: T | null | undefined, ...variadic: any[]): T | null | undefined | Promise<T | null | undefined>;
+    get isConstant(): boolean;
+}
+/**
+ * Wrap a provided executor function as an Executor
+ *
+ * @template T
+ * @augments Executor<T>
+ */
+export class FunctionExecutor<T> extends Executor<T> {
+    /**
+     * @param {ExecutorFunction<T>} execute
+     */
+    constructor(execute: ExecutorFunction<T>);
+    /**
+     * @param {T} input - required primary input
+     * @param {...any} variadic - optional extra arguments (defined as needed by subclasses)
+     * @returns {T|null|undefined|Promise<T|null|undefined>}
+     */
+    execute(input: T, ...variadic: any[]): T | null | undefined | Promise<T | null | undefined>;
+    #private;
+}
+export class ConstantExecutor extends Executor<any> {
+    /**
+     * @param {any} value
+     */
+    constructor(value: any);
+    execute(): any;
+    #private;
+}
+export const NULL_EXECUTOR: ConstantExecutor;
+export const UNDEFINED_EXECUTOR: ConstantExecutor;
+export const TRUE_EXECUTOR: ConstantExecutor;
+export const FALSE_EXECUTOR: ConstantExecutor;
+export type ExecutorFunction<T> = (input: T | null | undefined, ...variadic: any) => T | null | undefined | Promise<T | null | undefined>;
+export type MappingExecutorFunction<T, R> = (input: T | null | undefined, ...variadic: any) => R | null | undefined | Promise<R | null | undefined>;

package/types/executor/object-executor.d.ts

@@ -0,0 +1,14 @@
+/** @typedef {[key:string, executor:Executor]} ObjectExecutorEntry */
+/**
+ * @augments {Executor<any>}
+ */
+export class ObjectExecutor extends Executor<any> {
+    /**
+     * @param {object} [object]
+     * @param {(input:any) => any} [preprocess]
+     */
+    constructor(object?: object, preprocess?: (input: any) => any);
+    #private;
+}
+export type ObjectExecutorEntry = [key: string, executor: Executor<any>];
+import { Executor } from './executor.js';

package/types/executor/parallel-executor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Executes a fixed set of executors concurrently, passing the same input value and variadic arguments to each,
+ * and returning an array of all results in the same order as the executors.
+ *
+ * When all executors are synchronous, execution is sequential and the result is a plain array.
+ * When any executor returns a Promise, all results are collected via `Promise.all`, giving true
+ * concurrent execution for I/O-bound processors.
+ *
+ * Errors propagate immediately — a synchronous throw or async rejection halts collection
+ * and surfaces the error to the caller without waiting for remaining executors.
+ *
+ * @augments {Executor<any>}
+ */
+export class ParallelExecutor extends Executor<any> {
+    /**
+     * @param {Array<any>} [parallel] - executors/functions/values to execute concurrently
+     */
+    constructor(parallel?: Array<any>);
+    /**
+     * @param {any} input
+     * @param {...any} variadic
+     * @returns {any[]|Promise<any[]>}
+     */
+    execute(input: any, ...variadic: any[]): any[] | Promise<any[]>;
+    #private;
+}
+import { Executor } from './executor.js';

package/types/executor/pipeline-executor.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @augments Executor<any>
+ */
+export class PipelineExecutor extends Executor<any> {
+    /**
+     * @param {Array<any>|any} pipeline - executors/functions/values to execute as a pipeline
+     */
+    constructor(pipeline?: Array<any> | any);
+    #private;
+}
+import { Executor } from './executor.js';

package/types/executor/sequence-executor.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Call a sequence of executors on the input until one returns a truthy value.  Exceptions/rejections are caught and
+ * interpreted as a falsey value.  Return the first successful truthy result, or undefined on failure.
+ *
+ * @template T
+ * @augments {Executor<T>}
+ */
+export class SequenceExecutor<T> extends Executor<T> {
+    static ANY_CRITERIA: symbol;
+    static ALL_CRITERIA: symbol;
+    static EXCLUSIVE_CRITERIA: symbol;
+    static TRUTHY_CHECK: symbol;
+    static DEFINED_CHECK: symbol;
+    static SUCCESS_CHECK: symbol;
+    static RESULT_RETURN: symbol;
+    static INPUT_RETURN: symbol;
+    static RETHROW_ERRORS: symbol;
+    static CAPTURE_ERRORS: symbol;
+    /**
+     * @param {Array<any>|any} [executors]
+     * @param {symbol[]} [flags]
+     */
+    constructor(executors?: Array<any> | any, flags?: symbol[]);
+    /**
+     * @param {any} input
+     * @param {...any} extra
+     * @returns {T|null|undefined|Promise<T|null|undefined>}
+     */
+    execute(input: any, ...extra: any[]): T | null | undefined | Promise<T | null | undefined>;
+    #private;
+}
+import { Executor } from './executor.js';

package/types/executor/serial-executor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Executes a fixed sequence of executors serially, passing each same input value and variadic arguments.
+ * and returning the original input value on success.  This executor is intended for side-effect-style composition;
+ * for chained processing, see `PipelineExecutor` or `StepExecutor`.  See `SequenceExecutor` to allow fine
+ * tuning of sequence execution behavior.
+ *
+ * @template T
+ * @augments {SequenceExecutor<T>}
+ */
+export class SerialExecutor<T> extends SequenceExecutor<T> {
+    /**
+     * @param {any[]|any} [serial]
+     */
+    constructor(serial?: any[] | any);
+}
+import { SequenceExecutor } from './sequence-executor.js';

package/types/executor/step-executor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * StepExecutor is basically like PipelineExecutor, except that null or undefined step results are returned immediately.
+ *
+ * @template T
+ * @augments {Executor<T>}
+ */
+export class StepExecutor<T> extends Executor<T> {
+    /**
+     * @param {Array<any>|any} steps - executors/functions/values to execute as a pipeline
+     */
+    constructor(steps?: Array<any> | any);
+    #private;
+}
+import { Executor } from './executor.js';

package/types/helpers/case.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+export function toCamelCase(str: string): string;
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+export function toPascalCase(str: string): string;
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+export function toConstantCase(str: string): string;
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+export function toKebabCase(str: string): string;
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+export function toCapitalize(str: string): string;
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+export function toTitleCase(str: string): string;

package/types/helpers/data-size.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Parse a data-size string into a byte count.
+ *
+ * Accepts numeric values (treated as bytes), or strings like `'20KiB'`, `'1.5 MB'`, `'512'`.
+ * When `standard` is omitted, both IEC and SI suffixes are accepted.
+ * When `standard` is `'iec'` or `'si'`, only that standard's suffixes are accepted.
+ *
+ * @package
+ * @param {string|number} value
+ * @param {string} [standard] - `'iec'` or `'si'`; omit to accept either
+ * @returns {number} byte count
+ */
+export function parseDataSize(value: string | number, standard?: string): number;
+/**
+ * Format a byte count into a human-readable data-size string.
+ *
+ * Selects the largest unit where the value is >= 1 and formats with up to
+ * two decimal places (trailing zeros stripped).
+ *
+ * @package
+ * @param {number} bytes
+ * @param {string} [standard='iec'] - `'iec'` or `'si'`
+ * @returns {string|undefined}
+ */
+export function formatDataSize(bytes: number, standard?: string): string | undefined;

package/types/helpers/debug-sink.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A hook for compatible loggers (e.g., `@versionzero/logger`) to automatically capture debug messages.
+ * (Left in for new code hacking; debug calls were removed for performance reasons after the library was stabilized.)
+ *
+ * @param {...any} args
+ * @package
+ * @deprecated
+ */
+export function debug(...args: any[]): void;