@dbx-tools/shared-core 0.1.18 → 0.1.20

package/src/object.ts

@@ -1,9 +1,810 @@
 /**
- * Small value guards, coercions, object-shape types, and structural
- * deep-equality: narrow parsed JSON to a record, coerce loose truthy/falsy
- * strings to a boolean, describe object shapes (`NameLike`, `NonFunctionKeys`),
- * and compare values with {@link deepEqual}. Dependency-free and browser-safe.
+ * 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.
+ */
+
+/** 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 function isOneOrMany<T = unknown>(value: readonly T[]): value is OneOrMany<T> {
+  return value.length > 0;
+}
+
+/** 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 function isCollection<T = unknown>(value: unknown): value is Collection<T> {
+  return Array.isArray(value) || value instanceof Set || value instanceof Map;
+}
+
+/**
+ * `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 function isEmpty(
+  collection: Collection<unknown> | Record<string, unknown>,
+  options?: { recursive?: boolean },
+): boolean {
+
+  function visit(value: unknown, seen?: Set<unknown>): boolean {
+    if (value == null) return true;
+    else if (typeof value === "object") {
+      if (seen?.has(value)) return true;
+      seen?.add(value);
+      if (Array.isArray(value)) {
+        return value.length === 0 || (seen ? value.every((item) => visit(item, seen)) : false);
+      }
+      if (value instanceof Set) {
+        return (
+          value.size === 0 || (seen ? [...value].every((item) => visit(item, seen)) : false)
+        );
+      }
+      if (value instanceof Map) {
+        return (
+          value.size === 0 ||
+          (seen ? [...value.values()].every((item) => visit(item, seen)) : false)
+        );
+      }
+      const keys = Object.keys(value);
+      if (keys.length === 0) return true;
+      else if (seen) {
+        return keys.every((key) => visit((value as Record<string, unknown>)[key], seen));
+      } else {
+        return false
+      }
+    } else {
+      return false;
+    }
+  }
+  return visit(collection, options?.recursive ? new Set() : undefined);
+}
+
+
+/**
+ * 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 function values<T>(source: Iterable<T> | ReadonlyMap<unknown, T>): Iterable<T> {
+  return source instanceof Map ? source.values() : (source as 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 function isContainer<T = unknown>(value: unknown): value is Container<T> {
+  return (
+    value != null &&
+    typeof value !== "string" &&
+    !(value instanceof String) &&
+    !(value instanceof RegExp) &&
+    typeof value !== "function" &&
+    typeof (value as { [Symbol.iterator]?: unknown })[Symbol.iterator] === "function"
+  );
+}
+
+
+function sequenceSources<T>(...sources: SequenceSource<T>[]): Iterable<T>[] {
+  const sourceIterables: Iterable<T>[] = [];
+  for (const source of sources) {
+    if (source == null || (isCollection(source) && isEmpty(source))) continue;
+    sourceIterables.push(values(source));
+  }
+  return sourceIterables;
+}
+
+/**
+ * Flattens nested arrays for {@link flat}. Non-array values are wrapped as a
+ * single-element iterable; depth decrements per array level.
+ */
+function flattenValue(value: unknown, depth: number): Iterable<unknown> {
+  if (depth > 0 && Array.isArray(value)) {
+    const nextDepth = Number.isFinite(depth) ? depth - 1 : depth;
+    return {
+      *[Symbol.iterator]() {
+        for (const item of value) yield* flattenValue(item, nextDepth);
+      },
+    };
+  }
+  return [value];
+}
+
+/** Wrap a per-element transform (each element -> an iterable) as a lazy {@link Sequence}. */
+function derive<T, U>(
+  source: Iterable<T>,
+  fn: (value: T, index: number) => Iterable<U>,
+): Sequence<U> {
+  return sequence({
+    *[Symbol.iterator]() {
+      let index = 0;
+      for (const value of source) yield* fn(value, index++);
+    },
+  });
+}
+
+/** Like {@link derive}, but yields one value per source element (no wrapper iterable). */
+function deriveOne<T, U>(source: Iterable<T>, fn: (value: T, index: number) => U): Sequence<U> {
+  return sequence({
+    *[Symbol.iterator]() {
+      let index = 0;
+      for (const value of source) yield fn(value, index++);
+    },
+  });
+}
+
+/**
+ * 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 function map<T, U>(
+  source: Source<T>,
+  callback: (value: T, index: number) => U,
+): Sequence<U> {
+  return deriveOne(sequence(source), callback);
+}
+
+/**
+ * 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 function filter<T, S extends T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => value is S,
+): Sequence<S>;
+export function filter<T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => boolean,
+): Sequence<T>;
+export function filter<T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => boolean,
+): Sequence<T> {
+  return derive(sequence(source), function* (value, index) {
+    if (predicate(value, index)) yield value;
+  });
+}
+
+/**
+ * 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 function nonNull<T>(...sources: readonly Source<T>[]): Sequence<NonNullable<T>> {
+  return filter(sequence(...sources), (value): value is NonNullable<T> => value != null);
+}
+
+/**
+ * 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 function flatMap<T, U>(
+  source: Source<T>,
+  callback: (value: T, index: number) => U | ReadonlyArray<U>,
+): Sequence<U> {
+  return derive(sequence(source), function* (value, index) {
+    const result = callback(value, index);
+    if (Array.isArray(result)) yield* result;
+    else yield result as 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 function flat<T>(depth: number, ...sources: readonly Source<T>[]): Sequence<T> {
+  const src = sequence(...sources);
+  if (depth < 1) return src;
+  return derive(src, (value) => flattenValue(value, depth)) as 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 function distinct<T>(...sources: readonly Source<T>[]): Sequence<T> {
+  const src = sequence(...sources);
+  return sequence({
+    *[Symbol.iterator]() {
+      const seen = new Set<T>();
+      for (const value of src) {
+        if (seen.has(value)) continue;
+        seen.add(value);
+        yield value;
+      }
+    },
+  });
+}
+
+/**
+ * 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 function concat<T>(
+  source: Source<T>,
+  ...items: readonly (T | ReadonlyArray<T>)[]
+): Sequence<T> {
+  const src = sequence(source);
+  if (items.length === 0) return src;
+  return sequence({
+    *[Symbol.iterator]() {
+      yield* src;
+      for (const item of items) {
+        if (Array.isArray(item)) yield* item;
+        else yield item as 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 function take<T>(count: number, ...sources: readonly Source<T>[]): Sequence<T> {
+  if (count <= 0) return emptySequence as Sequence<T>;
+  const src = sequence(...sources);
+  return sequence({
+    *[Symbol.iterator]() {
+      let taken = 0;
+      for (const value of src) {
+        yield value;
+        if (++taken >= count) return;
+      }
+    },
+  });
+}
+
+/**
+ * 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 function group<T, G extends GroupPredicates<T>>(
+  predicates: G,
+  ...sources: readonly Source<T>[]
+): { [K in keyof G]: GroupValue<T, G[K]>[] } {
+  const keys = Object.keys(predicates) as (keyof G)[];
+  const buckets = new Map<keyof G, T[]>(keys.map((key) => [key, []]));
+  let index = 0;
+  for (const value of sequence(...sources)) {
+    const i = index++;
+    for (const key of keys) {
+      if (predicates[key]!(value, i)) {
+        buckets.get(key)!.push(value);
+        break;
+      }
+    }
+  }
+  const result = {} as { [K in keyof G]: GroupValue<T, G[K]>[] };
+  for (const key of keys) {
+    result[key] = buckets.get(key)! as GroupValue<T, G[typeof key]>[];
+  }
+  return result;
+}
+
+/**
+ * Same semantics as `Array.prototype.find`, over a single {@link Container}.
+ * Consumes elements until a match. A type guard narrows the return type.
+ */
+export function find<T, S extends T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => value is S,
+): S | undefined;
+export function find<T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => boolean,
+): T | undefined;
+export function find<T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => boolean,
+): T | undefined {
+  let index = 0;
+  for (const value of sequence(source)) {
+    if (predicate(value, index++)) return value;
+  }
+  return undefined;
+}
+
+/**
+ * Same semantics as `Array.prototype.findLast`, over a single {@link Container}.
+ * Consumes the full source. A type guard narrows the return type.
+ */
+export function findLast<T, S extends T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => value is S,
+): S | undefined;
+export function findLast<T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => boolean,
+): T | undefined;
+export function findLast<T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => boolean,
+): T | undefined {
+  let index = 0;
+  let match: T | undefined;
+  for (const value of sequence(source)) {
+    if (predicate(value, index++)) match = value;
+  }
+  return match;
+}
+
+/**
+ * Same semantics as `Array.prototype.findIndex`, over a single {@link Container}.
+ * Consumes elements until a match.
+ */
+export function findIndex<T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => boolean,
+): number {
+  let index = 0;
+  for (const value of sequence(source)) {
+    if (predicate(value, index)) return index;
+    index++;
+  }
+  return -1;
+}
+
+/**
+ * Same semantics as `Array.prototype.findLastIndex`, over a single
+ * {@link Container}. Consumes the full source.
+ */
+export function findLastIndex<T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => boolean,
+): number {
+  let index = 0;
+  let match = -1;
+  for (const value of sequence(source)) {
+    if (predicate(value, index)) match = index;
+    index++;
+  }
+  return match;
+}
+
+/**
+ * Same semantics as `Array.prototype.some`, over a single {@link Container}.
+ * Short-circuits on the first match.
+ */
+export function some<T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => boolean,
+): boolean {
+  let index = 0;
+  for (const value of sequence(source)) if (predicate(value, index++)) return true;
+  return false;
+}
+
+/**
+ * Same semantics as `Array.prototype.every`, over a single {@link Container}.
+ * Short-circuits on the first failure.
+ */
+export function every<T, S extends T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => value is S,
+): boolean;
+export function every<T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => boolean,
+): boolean;
+export function every<T>(
+  source: Source<T>,
+  predicate: (value: T, index: number) => boolean,
+): boolean {
+  let index = 0;
+  for (const value of sequence(source)) if (!predicate(value, index++)) return false;
+  return true;
+}
+
+/**
+ * Same semantics as `Array.prototype.forEach`, over a single {@link Container}.
+ * Consumes the source.
+ */
+export function forEach<T>(source: Source<T>, callback: (value: T, index: number) => void): void {
+  let index = 0;
+  for (const value of sequence(source)) callback(value, index++);
+}
+
+/**
+ * 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 function at<T>(index: number, ...sources: readonly Source<T>[]): T | undefined {
+  const src = sequence(...sources);
+  if (index < 0) return toArray(src).at(index);
+  let i = 0;
+  for (const value of src) {
+    if (i++ === index) return value;
+  }
+  return undefined;
+}
+
+export function toOneOrMany<T>(input: (T | OneOrMany<T>)): OneOrMany<T> {
+  return Array.isArray(input) ? input : [input];
+}
+
+/**
+ * Materializes the concatenated sources into a new array. Consumes single-pass
+ * sources.
+ *
+ * @param sources - Containers to concatenate (nullish sources are skipped).
+ */
+export function toArray<T>(...sources: readonly Source<T>[]): readonly T[] {
+  return [...sequence(...sources)];
+}
+
+/**
+ * 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.
+ */
+class SequenceImpl<T> {
+  private iterator?: Iterator<T>;
+  private exhausted: boolean;
+
+  constructor(
+    private readonly source: Iterable<T>,
+    private readonly buffer: T[] | undefined,
+    state: { readonly exhausted?: boolean } = {},
+  ) {
+    this.exhausted = state.exhausted ?? false;
+  }
+
+  private get caching(): boolean {
+    return this.buffer !== undefined;
+  }
+
+  /** Advance the underlying source once, creating the iterator on first use. */
+  private pull(): IteratorResult<T> {
+    this.iterator ??= this.source[Symbol.iterator]();
+    return this.iterator.next();
+  }
+
+  *[Symbol.iterator](): Iterator<T> {
+    if (!this.caching) {
+      if (this.exhausted) return;
+      for (let next = this.pull(); !next.done; next = this.pull()) {
+        yield next.value;
+      }
+      this.exhausted = true;
+    } else {
+      // Cached: iterate like a list. Always replay the buffer from the start,
+      // extending it from the source on demand until exhausted. A broken loop
+      // leaves the buffer intact, so the next iteration starts over from the
+      // beginning.
+      const buffer = this.buffer!;
+      let index = 0;
+      for (; ;) {
+        if (index < buffer.length) {
+          yield buffer[index++]!;
+          continue;
+        }
+        if (this.exhausted) return;
+        const next = this.pull();
+        if (next.done) {
+          this.exhausted = true;
+          return;
+        }
+        buffer.push(next.value);
+        yield next.value;
+        index++;
+      }
+    }
+  }
+
+  /** @see {@link map} */
+  map<U>(callback: (value: T, index: number) => U): Sequence<U> {
+    return map(this, callback);
+  }
+
+  /** @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>;
+  filter(predicate: (value: T, index: number) => boolean): Sequence<T> {
+    return filter(this, predicate);
+  }
+
+  /** @see {@link nonNull} */
+  nonNull(): Sequence<NonNullable<T>> {
+    return nonNull(this);
+  }
+
+  /** @see {@link flatMap} */
+  flatMap<U>(callback: (value: T, index: number) => U | ReadonlyArray<U>): Sequence<U> {
+    return flatMap(this, callback);
+  }
+
+  /** @see {@link flat} */
+  flat(depth = 1): Sequence<T> {
+    return flat(depth, this);
+  }
+
+  /** @see {@link distinct} */
+  distinct(): Sequence<T> {
+    return distinct(this);
+  }
+
+  /** @see {@link concat} */
+  concat(...items: readonly (T | ReadonlyArray<T>)[]): Sequence<T> {
+    return concat(this, ...items);
+  }
+
+  /**
+   * 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> {
+    const sourceIterables = sequenceSources(this, ...sources);
+    return sequenceSources.length === 0 ? this : sequence(...sourceIterables);
+  }
+
+  /** @see {@link take} */
+  take(count: number): Sequence<T> {
+    return take(count, this);
+  }
+
+  /** @see {@link group} */
+  group<G extends GroupPredicates<T>>(predicates: G): { [K in keyof G]: GroupValue<T, G[K]>[] } {
+    return group(predicates, this);
+  }
+
+  /**
+   * 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> {
+    return this.caching ? this : new SequenceImpl(this, []);
+  }
+
+  /** @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;
+  find(predicate: (value: T, index: number) => boolean): T | undefined {
+    return find(this, predicate);
+  }
+
+  /** @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;
+  findLast(predicate: (value: T, index: number) => boolean): T | undefined {
+    return findLast(this, predicate);
+  }
+
+  /** @see {@link findIndex} */
+  findIndex(predicate: (value: T, index: number) => boolean): number {
+    return findIndex(this, predicate);
+  }
+
+  /** @see {@link findLastIndex} */
+  findLastIndex(predicate: (value: T, index: number) => boolean): number {
+    return findLastIndex(this, predicate);
+  }
+
+  /** @see {@link some} */
+  some(predicate: (value: T, index: number) => boolean): boolean {
+    return some(this, predicate);
+  }
+
+  /** @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;
+  every(predicate: (value: T, index: number) => boolean): boolean {
+    return every(this, predicate);
+  }
+
+  /** @see {@link forEach} */
+  forEach(callback: (value: T, index: number) => void): void {
+    forEach(this, callback);
+  }
+
+  /** @see {@link at} */
+  at(index: number): T | undefined {
+    return at(index, this);
+  }
+
+  /**
+   * 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[] {
+    if (this.caching && this.exhausted) return [...this.buffer!];
+    return toArray(this);
+  }
+}
+
+/** Shared empty sequence singleton, reusable for any element type. */
+const emptySequence: Sequence<never> = new SequenceImpl([], undefined, {
+  exhausted: true,
+});
+
+/**
+ * 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 function sequence<T>(
+  ...sources: readonly SequenceSource<T>[]
+): Sequence<T> {
+  // Skip nullish sources and known-empty collections; normalize the rest to
+  // their values so a Map contributes values rather than [key, value] entries.
+  const sourceIterables = sequenceSources(...sources);
+  if (sourceIterables.length === 0) return emptySequence as Sequence<T>;
+  // Reuse an existing sequence as-is rather than re-wrapping it.
+  if (sourceIterables.length === 1) {
+    const only = sourceIterables[0]!;
+    return only instanceof SequenceImpl ? (only as Sequence<T>) : new SequenceImpl(only, undefined);
+  }
+  return new SequenceImpl(
+    {
+      *[Symbol.iterator]() {
+        for (const source of sourceIterables) yield* source;
+      },
+    },
+    undefined,
+  );
+}
+
+
+
+/**
+ * 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 function* generator<T>(
+  ...items: readonly (T | Iterable<T> | null | undefined)[]
+): Generator<T> {
+  for (const item of items) {
+    if (item === null || item === undefined) {
+      continue;
+    } else if (isContainer(item)) {
+      yield* item;
+    } else {
+      yield item;
+    }
+  }
+}
+
+
+
+
+
+// ---------------------------------------------------------------------------
+// Object value guards, coercions, and structural equality
+// ---------------------------------------------------------------------------
 
 /** Minimal shape for objects that expose an optional `name` (e.g. AppKit plugins). */
 export interface NameLike {