@dbx-tools/shared-core 0.3.44 → 0.4.0

package/lib/src/object.d.ts

@@ -0,0 +1,382 @@
+/**
+ * Dependency-free object + iterable utilities.
+ *
+ * Value guards / coercions / shape types: {@link isRecord} narrows parsed JSON
+ * to a record, {@link toBoolean} coerces loose truthy/falsy values, {@link
+ * deepEqual} compares structurally, and {@link NameLike}/{@link NonFunctionKeys}
+ * describe object shapes.
+ *
+ * Iterable helpers: {@link generator} flattens mixed arguments; {@link sequence}
+ * wraps source(s) in a lazy, `Array`-compatible {@link Sequence}. Every
+ * transform/terminal is a standalone function operating on plain {@link
+ * Container}s (see {@link map}, {@link filter}, {@link group}, ...); the {@link
+ * Sequence} methods are thin forwarders over them so the same logic backs both
+ * the free-function and the fluent/chained styles.
+ *
+ * @module
+ */
+/** Lazy sequence over iterable source(s). See {@link sequence}. */
+export type Sequence<T> = SequenceImpl<T>;
+type SequenceSource<T> = Iterable<T> | ReadonlyMap<unknown, T> | OneOrMany<T> | null | undefined;
+/**
+ * A non-scalar {@link Iterable} - one to treat as a collection of elements
+ * rather than a scalar. {@link isContainer} narrows to this, excluding strings,
+ * `String`/`RegExp` objects, and functions. {@link Collection} is the eagerly-
+ * sized subset. The element defaults to `unknown` so any `Collection` is
+ * assignable to a bare `Container`.
+ */
+export type Container<T = unknown> = Iterable<T>;
+/**
+ * A built-in, eagerly-sized {@link Container}: an {@link Array}, {@link Set}, or
+ * {@link Map} (whose *values* are `T` - a Map iterates `[key, value]` entries,
+ * so its element type differs, but its value type is `T`). All share a cheap
+ * emptiness check ({@link isEmpty}).
+ */
+export type Collection<T> = ReadonlyArray<T> | ReadonlySet<T> | ReadonlyMap<unknown, T>;
+export type OneOrMany<T> = [T, ...T[]];
+/** Narrow a readonly array to a non-empty {@link OneOrMany} tuple. */
+export declare function isOneOrMany<T = unknown>(value: readonly T[]): value is OneOrMany<T>;
+/** A source accepted by a variadic op: a {@link Container} of `T`, or nothing. */
+type Source<T> = Container<T> | null | undefined;
+/**
+ * Element type of a {@link group} bucket array: when the predicate `P` is a type
+ * guard (`value is S`), the bucket is narrowed to `S & T`; otherwise it stays `T`.
+ */
+type GroupValue<T, P> = P extends (value: any, ...rest: any[]) => value is infer S ? S & T : T;
+/** A map of group name -> predicate, as accepted by {@link group}. */
+type GroupPredicates<T> = Record<string, (value: T, index: number) => boolean>;
+/**
+ * Type guard for a {@link Collection}: an {@link Array}, {@link Set}, or
+ * {@link Map}. Narrows `value` so its element/value type is treated as `T`.
+ *
+ * @typeParam T - Element (or Map value) type asserted for the collection.
+ * @param value - Value to test.
+ * @returns `true` (narrowing `value` to {@link Collection}<`T`>) for a
+ *   built-in array/set/map.
+ */
+export declare function isCollection<T = unknown>(value: unknown): value is Collection<T>;
+/**
+ * `true` when a {@link Collection} has no elements. Uses `length` for arrays
+ * and `size` for {@link Set}/{@link Map}.
+ *
+ * @param collection - The array, set, or map to test.
+ */
+export declare function isEmpty(collection: Collection<unknown> | Record<string, unknown>, options?: {
+    recursive?: boolean;
+}): boolean;
+/**
+ * Normalizes a source to an iterable of its `T` values, so Maps are treated
+ * uniformly with arrays/sets: a {@link Map} yields its *values* (matching
+ * {@link Collection}'s value-typed `T`), any other iterable yields itself. This
+ * is what {@link sequence} consumes, so a `Map` contributes values everywhere
+ * rather than `[key, value]` entries.
+ */
+export declare function values<T>(source: Iterable<T> | ReadonlyMap<unknown, T>): Iterable<T>;
+/**
+ * Type guard for a {@link Container} - an iterable to be treated as a collection
+ * rather than a scalar.
+ *
+ * Deliberately excludes values that are technically iterable but should be
+ * treated as scalars here - strings, `String`/`RegExp` objects, and functions -
+ * so a lone string is never spread character-by-character.
+ *
+ * @typeParam T - Element type asserted for the iterable.
+ * @param value - Value to test.
+ * @returns `true` (narrowing `value` to {@link Container}<`T`>) for a non-string
+ *   iterable.
+ */
+export declare function isContainer<T = unknown>(value: unknown): value is Container<T>;
+/**
+ * Same semantics as `Array.prototype.map`, over a single {@link Container}.
+ *
+ * @param source - The container to map (nullish yields an empty sequence).
+ * @param callback - Called per element with its index; its result is emitted.
+ */
+export declare function map<T, U>(source: Source<T>, callback: (value: T, index: number) => U): Sequence<U>;
+/**
+ * Same semantics as `Array.prototype.filter`, over a single {@link Container}.
+ * A type-guard predicate narrows the resulting element type.
+ *
+ * @param source - The container to filter (nullish yields an empty sequence).
+ * @param predicate - Keeps elements for which it returns `true`.
+ */
+export declare function filter<T, S extends T>(source: Source<T>, predicate: (value: T, index: number) => value is S): Sequence<S>;
+export declare function filter<T>(source: Source<T>, predicate: (value: T, index: number) => boolean): Sequence<T>;
+/**
+ * Concatenates the sources and yields only elements that are not `null` or
+ * `undefined`, narrowing the element type to {@link NonNullable}<`T`>.
+ *
+ * @param sources - Containers to concatenate (nullish sources are skipped).
+ */
+export declare function nonNull<T>(...sources: readonly Source<T>[]): Sequence<NonNullable<T>>;
+/**
+ * Same semantics as `Array.prototype.flatMap`, over a single {@link Container}.
+ *
+ * @param source - The container to map (nullish yields an empty sequence).
+ * @param callback - Returns a value or array of values, flattened one level.
+ */
+export declare function flatMap<T, U>(source: Source<T>, callback: (value: T, index: number) => U | ReadonlyArray<U>): Sequence<U>;
+/**
+ * Same semantics as `Array.prototype.flat` (arrays only). `depth` leads so the
+ * sources can stay variadic; use `depth < 1` for a no-op passthrough.
+ *
+ * @param depth - How many array levels to flatten.
+ * @param sources - Containers to concatenate, then flatten (nullish skipped).
+ */
+export declare function flat<T>(depth: number, ...sources: readonly Source<T>[]): Sequence<T>;
+/**
+ * Concatenates the sources, then lazily yields values in encounter order,
+ * skipping a value only when an equal one was already yielded (`Set` /
+ * SameValueZero). Uniqueness is checked per element as it is consumed.
+ *
+ * @param sources - Containers to concatenate (nullish sources are skipped).
+ */
+export declare function distinct<T>(...sources: readonly Source<T>[]): Sequence<T>;
+/**
+ * Yields `source`, then each appended `item` in order (arrays spread one level),
+ * mirroring `Array.prototype.concat`. `items` are scalar values/arrays, not
+ * containers, so `source` stays a single leading argument.
+ *
+ * @param source - The leading container (nullish yields just the items).
+ * @param items - Values (or arrays of values) appended after the source.
+ */
+export declare function concat<T>(source: Source<T>, ...items: readonly (T | ReadonlyArray<T>)[]): Sequence<T>;
+/**
+ * Yields at most `count` elements from the front of the concatenated sources.
+ * `count` leads so the sources can stay variadic.
+ *
+ * @param count - Maximum number of elements to yield (`<= 0` yields none).
+ * @param sources - Containers to concatenate (nullish sources are skipped).
+ */
+export declare function take<T>(count: number, ...sources: readonly Source<T>[]): Sequence<T>;
+/**
+ * Splits the concatenated sources into one array per named predicate. Consumes
+ * the input once, routing each element to the FIRST predicate it satisfies (so
+ * groups are disjoint); elements matching no predicate are dropped. Type-guard
+ * predicates narrow their group's element type (see {@link GroupValue}).
+ * `predicates` leads so the sources can stay variadic.
+ *
+ * @typeParam G - The map of group name -> predicate.
+ * @param predicates - Named predicates; evaluated in declaration order.
+ * @param sources - Containers to concatenate (nullish sources are skipped).
+ * @returns An object with the same keys, each an array of its group's elements.
+ *
+ * @example
+ *   const { strings, fns } = group({ strings: isString, fns: isFunction }, xs);
+ */
+export declare function group<T, G extends GroupPredicates<T>>(predicates: G, ...sources: readonly Source<T>[]): {
+    [K in keyof G]: GroupValue<T, G[K]>[];
+};
+/**
+ * Same semantics as `Array.prototype.find`, over a single {@link Container}.
+ * Consumes elements until a match. A type guard narrows the return type.
+ */
+export declare function find<T, S extends T>(source: Source<T>, predicate: (value: T, index: number) => value is S): S | undefined;
+export declare function find<T>(source: Source<T>, predicate: (value: T, index: number) => boolean): T | undefined;
+/**
+ * Same semantics as `Array.prototype.findLast`, over a single {@link Container}.
+ * Consumes the full source. A type guard narrows the return type.
+ */
+export declare function findLast<T, S extends T>(source: Source<T>, predicate: (value: T, index: number) => value is S): S | undefined;
+export declare function findLast<T>(source: Source<T>, predicate: (value: T, index: number) => boolean): T | undefined;
+/**
+ * Same semantics as `Array.prototype.findIndex`, over a single {@link Container}.
+ * Consumes elements until a match.
+ */
+export declare function findIndex<T>(source: Source<T>, predicate: (value: T, index: number) => boolean): number;
+/**
+ * Same semantics as `Array.prototype.findLastIndex`, over a single
+ * {@link Container}. Consumes the full source.
+ */
+export declare function findLastIndex<T>(source: Source<T>, predicate: (value: T, index: number) => boolean): number;
+/**
+ * Same semantics as `Array.prototype.some`, over a single {@link Container}.
+ * Short-circuits on the first match.
+ */
+export declare function some<T>(source: Source<T>, predicate: (value: T, index: number) => boolean): boolean;
+/**
+ * Same semantics as `Array.prototype.every`, over a single {@link Container}.
+ * Short-circuits on the first failure.
+ */
+export declare function every<T, S extends T>(source: Source<T>, predicate: (value: T, index: number) => value is S): boolean;
+export declare function every<T>(source: Source<T>, predicate: (value: T, index: number) => boolean): boolean;
+/**
+ * Same semantics as `Array.prototype.forEach`, over a single {@link Container}.
+ * Consumes the source.
+ */
+export declare function forEach<T>(source: Source<T>, callback: (value: T, index: number) => void): void;
+/**
+ * Same semantics as `Array.prototype.at` over the concatenated sources.
+ * Non-negative indices scan lazily; negative indices materialize first. `index`
+ * leads so the sources can stay variadic.
+ *
+ * @param index - Zero-based position; negative counts from the end.
+ * @param sources - Containers to concatenate (nullish sources are skipped).
+ */
+export declare function at<T>(index: number, ...sources: readonly Source<T>[]): T | undefined;
+export declare function toOneOrMany<T>(input: T | OneOrMany<T>): OneOrMany<T>;
+/**
+ * Materializes the concatenated sources into a new array. Consumes single-pass
+ * sources.
+ *
+ * @param sources - Containers to concatenate (nullish sources are skipped).
+ */
+export declare function toArray<T>(...sources: readonly Source<T>[]): readonly T[];
+/**
+ * Lazy iterable sequence with `Array`-compatible transforms and terminal
+ * methods. Single-pass by default; call {@link SequenceImpl.cache} to retain
+ * pulled values for re-iteration. Built for generators and other sources where
+ * a second pass is not guaranteed.
+ *
+ * The methods forward to the standalone functions of the same name - see each
+ * method's `@see` - so the free-function and chained styles share one impl.
+ */
+declare class SequenceImpl<T> {
+    private readonly source;
+    private readonly buffer;
+    private iterator?;
+    private exhausted;
+    constructor(source: Iterable<T>, buffer: T[] | undefined, state?: {
+        readonly exhausted?: boolean;
+    });
+    private get caching();
+    /** Advance the underlying source once, creating the iterator on first use. */
+    private pull;
+    [Symbol.iterator](): Iterator<T>;
+    /** @see {@link map} */
+    map<U>(callback: (value: T, index: number) => U): Sequence<U>;
+    /** @see {@link filter} */
+    filter<S extends T>(predicate: (value: T, index: number) => value is S): Sequence<S>;
+    filter(predicate: (value: T, index: number) => boolean): Sequence<T>;
+    /** @see {@link nonNull} */
+    nonNull(): Sequence<NonNullable<T>>;
+    /** @see {@link flatMap} */
+    flatMap<U>(callback: (value: T, index: number) => U | ReadonlyArray<U>): Sequence<U>;
+    /** @see {@link flat} */
+    flat(depth?: number): Sequence<T>;
+    /** @see {@link distinct} */
+    distinct(): Sequence<T>;
+    /** @see {@link concat} */
+    concat(...items: readonly (T | ReadonlyArray<T>)[]): Sequence<T>;
+    /**
+     * Lazily yields this sequence followed by each iterable `source` in order.
+     * Like {@link concat}, but for iterable sources (generators, other sequences,
+     * `Set`, `Map`, etc.) rather than scalar values or arrays. A {@link Map}
+     * source contributes its values.
+     *
+     * @see {@link sequence}
+     */
+    join(...sources: readonly SequenceSource<T>[]): Sequence<T>;
+    /** @see {@link take} */
+    take(count: number): Sequence<T>;
+    /** @see {@link group} */
+    group<G extends GroupPredicates<T>>(predicates: G): {
+        [K in keyof G]: GroupValue<T, G[K]>[];
+    };
+    /**
+     * Returns a cached, re-iterable view of this sequence. An already-caching
+     * sequence returns itself; otherwise this one-pass sequence is wrapped in a
+     * new instance that retains pulled values. Iterate the returned instance, not
+     * the original, to avoid competing for the same single-pass source.
+     */
+    cache(): Sequence<T>;
+    /** @see {@link find} */
+    find<S extends T>(predicate: (value: T, index: number) => value is S): S | undefined;
+    find(predicate: (value: T, index: number) => boolean): T | undefined;
+    /** @see {@link findLast} */
+    findLast<S extends T>(predicate: (value: T, index: number) => value is S): S | undefined;
+    findLast(predicate: (value: T, index: number) => boolean): T | undefined;
+    /** @see {@link findIndex} */
+    findIndex(predicate: (value: T, index: number) => boolean): number;
+    /** @see {@link findLastIndex} */
+    findLastIndex(predicate: (value: T, index: number) => boolean): number;
+    /** @see {@link some} */
+    some(predicate: (value: T, index: number) => boolean): boolean;
+    /** @see {@link every} (the `S extends T` overload narrows at compile time only). */
+    every<S extends T>(predicate: (value: T, index: number) => value is S): this is Sequence<S>;
+    every(predicate: (value: T, index: number) => boolean): boolean;
+    /** @see {@link forEach} */
+    forEach(callback: (value: T, index: number) => void): void;
+    /** @see {@link at} */
+    at(index: number): T | undefined;
+    /**
+     * Materialize the sequence into a new array. Consumes a single-pass source; a
+     * cached, exhausted sequence copies its buffer directly.
+     *
+     * @see {@link toArray}
+     */
+    toArray(): readonly T[];
+}
+/**
+ * Wrap one or more iterable `sources` in a single lazy {@link Sequence},
+ * iterated in order. `null`/`undefined` sources are skipped; when nothing
+ * remains (every source omitted, `null`, `undefined`, or an empty array /
+ * `Set` / `Map`), {@link emptySequence} is returned. The result is single-pass
+ * - call `.cache()` to make it re-iterable.
+ *
+ * A {@link Map} source contributes its values (see {@link values}), consistent
+ * with {@link Collection}'s value-typed `T`.
+ *
+ * @typeParam T - Element type of the sequence.
+ * @param sources - Iterables to concatenate, in order (`Map` sources use values).
+ */
+export declare function sequence<T>(...sources: readonly SequenceSource<T>[]): Sequence<T>;
+/**
+ * Flattens a mix of single items and iterables into one lazy {@link Generator}.
+ *
+ * Arguments are emitted in order: `null`/`undefined` are skipped, non-string
+ * iterables (per {@link isContainer}) are yielded element-by-element, and
+ * anything else (including strings) is yielded as a single item.
+ *
+ * @typeParam T - Element type produced by the generator.
+ * @param items - Items and/or iterables to flatten, in order.
+ * @returns A generator over the flattened elements.
+ */
+export declare function generator<T>(...items: readonly (T | Iterable<T> | null | undefined)[]): Generator<T>;
+/** Minimal shape for objects that expose an optional `name` (e.g. AppKit plugins). */
+export interface NameLike {
+    name?: string;
+}
+export type NonFunctionKeys<T> = {
+    [K in keyof T]: T[K] extends (...args: any[]) => any ? never : K;
+}[keyof T];
+/**
+ * Narrow `value` to a plain (non-array) object. Use as a type guard
+ * before indexing into / mutating parsed JSON so the access is
+ * type-safe.
+ *
+ * @example
+ * if (isRecord(parsed)) parsed.foo = 1;
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Coerce a loose boolean-ish value to a real `boolean`, or `undefined`
+ * when it can't be interpreted. Recognizes `true`/`t`/`on`/`1`/`yes`/`y`
+ * and their negatives (case- and whitespace-insensitive for strings), as
+ * well as the numbers `1` and `0`.
+ */
+export declare function toBoolean(value: unknown): boolean | undefined;
+/**
+ * Structural deep-equality with an optional custom comparator.
+ *
+ * {@link deepEqual} mirrors the semantics of the `fast-deep-equal`
+ * package (handled: nested plain objects/arrays, `Map`, `Set`, `Date`,
+ * `RegExp`, typed arrays, `NaN`, and `+0`/`-0` treated as equal) but is
+ * dependency-free so `@dbx-tools/shared-core` keeps no runtime deps.
+ *
+ * The optional `comparator` short-circuits the structural walk at any
+ * node: return `true`/`false` to force the result for that pair, or
+ * `undefined` to defer to the built-in comparison. It is invoked for the
+ * root pair and recursively for each nested pair, so a caller can, e.g.,
+ * compare two domain objects by id while letting everything else fall
+ * back to structural equality.
+ *
+ * @example
+ * deepEqual({ a: 1 }, { a: 1 });                 // true
+ * deepEqual([1, 2], [1, 2]);                      // true
+ * deepEqual(a, b, (x, y) =>
+ *   isEntity(x) && isEntity(y) ? x.id === y.id : undefined);
+ */
+export type DeepEqualComparator = (a: unknown, b: unknown) => boolean | undefined;
+export declare function deepEqual(a: unknown, b: unknown, comparator?: DeepEqualComparator): boolean;
+export {};