@mark1russell7/collections 0.3.0 → 0.5.0

package/build/layers.d.ts

@@ -0,0 +1,59 @@
+/**
+ * This module holds the one fold of a stack of layers. A layer wraps the next thing, so a stack
+ * of layers wraps a base. The next thing can be a collection, a function or any other value.
+ *
+ * This file has no imports. A package that needs only the fold loads this one file.
+ *
+ * @example
+ * const parse = compose(
+ *   (next: (text: string) => number) => (text: string) => next(text.trim()),
+ *   (next: (text: string) => number) => (text: string) => next(text) * 2
+ * )(Number);
+ * parse(" 21 "); // 42
+ */
+/**
+ * A layer takes the next thing and gives a wrapped thing.
+ *
+ * @template Inner The type that the layer wraps
+ * @template Outer The type that the layer gives
+ */
+type Layer<Inner = any, Outer = Inner> = (next: Inner) => Outer;
+/** This type gives the type that a layer wraps. */
+type InnerOf<L> = L extends ((next: infer I) => any) ? I : never;
+/** This type gives the type that a layer gives. */
+type OuterOf<L> = L extends ((next: any) => infer O) ? O : never;
+/**
+ * This type checks each neighbor pair of a list of layers. The result of the inner neighbor must
+ * fit the input of the outer neighbor. At the first bad pair, the compiler marks that argument.
+ *
+ * The type is tail recursive, so the compiler accepts a chain of 100 layers.
+ */
+type Chain<L extends readonly unknown[], Done extends readonly unknown[] = readonly []> = L extends readonly [infer A, infer B, ...infer R] ? [OuterOf<B>] extends [InnerOf<A>] ? Chain<readonly [B, ...R], readonly [...Done, A]> : readonly [...Done, A, Layer<any, InnerOf<A>>, ...R] : readonly [...Done, ...L];
+/**
+ * This type gives the function that {@link compose} returns. Its input is the input of the last
+ * layer, and its result is the result of the first layer. No layers give the identity function.
+ * A list that the compiler cannot see as a tuple gives the types of one element.
+ */
+type Composed<L extends readonly unknown[]> = L extends readonly [] ? <B>(base: B) => B : L extends readonly [infer First, ...unknown[]] ? L extends readonly [...unknown[], infer Last] ? (base: InnerOf<Last>) => OuterOf<First> : never : L extends readonly (infer E)[] ? (base: InnerOf<E>) => OuterOf<E> : never;
+/** This type gives the intersection of the results of a list of layers. */
+type Outers<L extends readonly unknown[], Sum = unknown> = L extends readonly [infer First, ...infer Rest] ? Outers<Rest, Sum & OuterOf<First>> : Sum;
+/**
+ * This type gives the function for layers that keep each capability of the layers under them.
+ * Its result has the result of each layer and the base. Use it only when that law holds.
+ */
+type Stacked<L extends readonly unknown[]> = L extends readonly [...unknown[], infer Last] ? (base: InnerOf<Last>) => Outers<L> & InnerOf<Last> : Composed<L>;
+/**
+ * This function folds layers into one function that wraps a base. The first layer is the outermost.
+ *
+ * The fold holds four laws:
+ * - Identity: `compose()(b)` is `b`.
+ * - One layer: `compose(f)(b)` is `f(b)`.
+ * - Associativity: `compose(f, compose(g, h))` equals `compose(compose(f, g), h)`.
+ * - Order: `compose(f, g)(b)` is `f(g(b))`.
+ *
+ * @param layers The layers, from the outermost to the innermost
+ * @returns A function that wraps a base in the layers
+ */
+declare function compose<const L extends readonly Layer[]>(...layers: L & Chain<L>): Composed<L>;
+export { OuterOf as a, compose as c, Layer as i, Composed as n, Outers as o, InnerOf as r, Stacked as s, Chain as t };
+//# sourceMappingURL=layers.d.ts.map

package/build/layers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layers.d.ts","names":[],"sources":["../src/core/layers.ts"],"mappings":";;;;;;;;;;;;;;;;;;;KAoBY,MAAM,aAAa,QAAQ,UAAU,MAAM,UAAU;;KAGrD,QAAQ,KAAK,YAAW,YAAY,aAAY;;KAGhD,QAAQ,KAAK,YAAW,oBAAoB,KAAI;;;;;;;KAQhD,MAAM,8BAA8B,iDAC9C,0BAA0B,SAAS,YAAY,MAC1C,QAAQ,aAAa,QAAQ,MAC5B,gBAAgB,MAAM,iBAAiB,MAAM,mBAChC,MAAM,GAAG,WAAW,QAAQ,QAAQ,kBACtC,SAAS;;;;;;KAOhB,SAAS,gCACnB,yBACK,GAAG,MAAM,MAAM,IAChB,0BAA0B,uBACxB,wCAAwC,SACrC,MAAM,QAAQ,UAAU,QAAQ,iBAEnC,0BAA0B,QACvB,MAAM,QAAQ,OAAO,QAAQ;;KAI5B,OAAO,8BAA8B,iBAC/C,0BAA0B,gBAAgB,QAAQ,OAAO,MAAM,MAAM,QAAQ,UAAU;;;;;KAM7E,QAAQ,gCAClB,wCAAwC,SACnC,MAAM,QAAQ,UAAU,OAAO,KAAK,QAAQ,QAC7C,SAAS;;;;;;;;;;;;;iBAcC,cAAc,mBAAmB,YAAY,QAAQ,IAAI,MAAM,KAAK,SAAS"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/collections",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Collections with no dependencies: lists, maps, queues, a summary tree, channels, lazy operations and dependency graphs.",
   "keywords": [
     "collections",
@@ -43,6 +43,10 @@
       "types": "./build/graph/index.d.ts",
       "default": "./build/graph/index.js"
     },
+    "./layers": {
+      "types": "./build/core/layers.d.ts",
+      "default": "./build/core/layers.js"
+    },
     "./testing": {
       "types": "./build/testing/index.d.ts",
       "default": "./build/testing/index.js"
@@ -64,6 +68,9 @@
   },
   "devDependencies": {
     "@mark1russell7/cue": "^2.0.0",
+    "@mark1russell7/rigor-bench": "^0.2.5",
+    "@mark1russell7/rigor-generators": "^0.1.5",
+    "@mark1russell7/rigor-statistics": "^0.1.8",
     "@types/node": "^26.6.5",
     "esbuild": "^0.28.2",
     "fast-check": "^4.10.2",

package/src/behaviors/bounded.ts

@@ -6,7 +6,7 @@
  *
  * @example
  * const list = compose(
- *   boundedList({ capacity: 100, policy: 'drop-oldest' })
+ *   boundedList<number>({ capacity: 100, policy: 'drop-oldest' })
  * )(arrayList<number>())
  *
  * // Add 101 elements - first element will be dropped
@@ -15,6 +15,7 @@
  * }
  */
 
+import { checkCapacity } from "../core/capacity.js";
 import type { Middleware } from "../core/middleware.js";
 import type { List } from "../interfaces/list.js";
 import type { Queue, Deque } from "../interfaces/queue.js";
@@ -66,7 +67,8 @@ export interface BoundedCollection {
 export function boundedList<T>(
   options: BoundedOptions<T>
 ): Middleware<List<T>, List<T> & BoundedCollection> {
-  const { capacity, policy = "throw", onOverflow } = options;
+  const { policy = "throw", onOverflow } = options;
+  const capacity = checkCapacity(options.capacity, "boundedList");
 
   return (next: List<T>): List<T> & BoundedCollection => {
     // An unshift puts the element at the front, so drop-oldest drops the last element for it
@@ -235,7 +237,8 @@ export function boundedList<T>(
 export function boundedQueue<T>(
   options: BoundedOptions<T>
 ): Middleware<Queue<T>, Queue<T> & BoundedCollection> {
-  const { capacity, policy = "throw", onOverflow } = options;
+  const { policy = "throw", onOverflow } = options;
+  const capacity = checkCapacity(options.capacity, "boundedQueue");
 
   return (next: Queue<T>): Queue<T> & BoundedCollection => {
     const handleOverflow = (element: T): void => {
@@ -306,7 +309,8 @@ export function boundedQueue<T>(
 export function boundedDeque<T>(
   options: BoundedOptions<T>
 ): Middleware<Deque<T>, Deque<T> & BoundedCollection> {
-  const { capacity, policy = "throw", onOverflow } = options;
+  const { policy = "throw", onOverflow } = options;
+  const capacity = checkCapacity(options.capacity, "boundedDeque");
 
   return (next: Deque<T>): Deque<T> & BoundedCollection => {
     const handleOverflow = (element: T): void => {
@@ -383,7 +387,8 @@ export function boundedMap<K, V>(
     onOverflow?: (context: Omit<OverflowContext<V>, "newElement"> & { key: K; value: V }) => void;
   }
 ): Middleware<MapLike<K, V>, MapLike<K, V> & BoundedCollection> {
-  const { capacity, policy = "throw", onOverflow } = options;
+  const { policy = "throw", onOverflow } = options;
+  const capacity = checkCapacity(options.capacity, "boundedMap");
 
   return (next: MapLike<K, V>): MapLike<K, V> & BoundedCollection => {
     let insertionOrder: K[] = []; // Track insertion order for drop-oldest

package/src/behaviors/evented.ts

@@ -6,7 +6,7 @@
  *
  * @example
  * const list = compose(
- *   eventedList()
+ *   eventedList<number>()
  * )(arrayList<number>())
  *
  * list.on('add', ({ value, index }) => {

package/src/behaviors/lru.ts

@@ -6,7 +6,7 @@
  *
  * @example
  * const cache = compose(
- *   lruMap({ capacity: 100 })
+ *   lruMap<string, Data>({ capacity: 100 })
  * )(hashMap<string, Data>())
  *
  * cache.set('key1', data1) // Accessed
@@ -14,6 +14,7 @@
  * // When full, least recently accessed keys are evicted
  */
 
+import { checkCapacity } from "../core/capacity.js";
 import type { Middleware } from "../core/middleware.js";
 import type { MapLike } from "../interfaces/map.js";
 import { compositeMapMethod } from "./composite.js";
@@ -23,7 +24,8 @@ import { compositeMapMethod } from "./composite.js";
  */
 export interface LRUOptions {
   /**
-   * Maximum capacity. When exceeded, least recently used items are evicted.
+   * The maximum number of entries, a positive whole number. When the map is full, a new key
+   * evicts the least recently used entry.
    */
   capacity: number;
 
@@ -50,11 +52,14 @@ interface LRUNode<K, V> {
  * This function maintains a doubly-linked list to track access order.
  * Most recently accessed items are at the head.
  * When capacity is exceeded, items at the tail are evicted.
+ *
+ * @throws RangeError when `options.capacity` is not a positive whole number.
  */
 export function lruMap<K, V>(
   options: LRUOptions
 ): Middleware<MapLike<K, V>, MapLike<K, V> & { readonly isFull: boolean }> {
-  const { capacity, onEvict } = options;
+  const { onEvict } = options;
+  const capacity = checkCapacity(options.capacity, "lruMap");
 
   return (next: MapLike<K, V>): MapLike<K, V> & { readonly isFull: boolean } => {
     // Doubly-linked list for LRU tracking
@@ -290,8 +295,13 @@ export class LRUCache<K, V> {
   private head: LRUNode<K, V> | null = null;
   private tail: LRUNode<K, V> | null = null;
 
+  /**
+   * @param capacity - The maximum number of entries, a positive whole number.
+   * @param onEvict - The function that this cache starts for each entry that it evicts.
+   * @throws RangeError when `capacity` is not a positive whole number.
+   */
   constructor(capacity: number, onEvict?: ((key: K, value: V) => void) | undefined) {
-    this.capacity = capacity;
+    this.capacity = checkCapacity(capacity, "LRUCache");
     this.onEvict = onEvict;
   }
 
@@ -359,6 +369,32 @@ export class LRUCache<K, V> {
     return true;
   }
 
+  /**
+   * This method deletes each entry for which `matches` gives true, and it gives the number of
+   * deleted entries. It is not a use: the order of the other entries does not change, and it
+   * does not start `onEvict`. It starts `matches` once for each entry, the most recent first. If
+   * `matches` throws, the entries that it matched before stay deleted.
+   *
+   * @param matches - The test of an entry.
+   * @returns The number of deleted entries.
+   */
+  deleteWhere(matches: (value: V, key: K) => boolean): number {
+    const nodes: LRUNode<K, V>[] = [];
+    for (let node = this.head; node; node = node.next) nodes.push(node);
+    let deleted = 0;
+    for (const node of nodes) {
+      // The function `matches` can change the cache. Skip each node that is not in it now.
+      if (this.map.get(node.key)?.node !== node) continue;
+      if (!matches(node.value, node.key)) continue;
+      // The function `matches` can delete this node itself, so check again.
+      if (this.map.get(node.key)?.node !== node) continue;
+      this.removeNode(node);
+      this.map.delete(node.key);
+      deleted++;
+    }
+    return deleted;
+  }
+
   clear(): void {
     this.map.clear();
     this.head = null;
@@ -439,7 +475,9 @@ export class LRUCache<K, V> {
 }
 
 /**
- * Factory function to make an LRU cache.
+ * This function makes an LRU cache.
+ *
+ * @throws RangeError when `capacity` is not a positive whole number.
  */
 export function lruCache<K, V>(
   capacity: number,

package/src/behaviors/safe.ts

@@ -6,7 +6,7 @@
  *
  * @example
  * const list = compose(
- *   safeList()
+ *   safeList<number>()
  * )(arrayList<number>())
  *
  * const value = list.safe.get(10) // Option<number> instead of throwing

package/src/behaviors/ttl.ts

@@ -6,7 +6,7 @@
  *
  * @example
  * const cache = compose(
- *   ttlMap({ ttl: 60000 }) // 60 seconds
+ *   ttlMap<string, Data>({ ttl: 60000 }) // 60 seconds
  * )(hashMap<string, Data>())
  *
  * cache.set('key', data)

package/src/core/capacity.ts

@@ -0,0 +1,21 @@
+/**
+ * The check of a capacity, for each layer and class that has a maximum size.
+ */
+
+/**
+ * This function gives the capacity when it is a positive whole number. Otherwise it throws a
+ * `RangeError`. A capacity of `NaN` makes a comparison `size >= capacity` always false, so a
+ * structure with that capacity grows without a limit. A capacity of 0 or less, or a fraction,
+ * has no clear meaning.
+ *
+ * @param capacity - The capacity to check.
+ * @param owner - The name of the layer or class, for the message of the error.
+ * @returns The same capacity.
+ * @throws RangeError when the capacity is not a positive whole number.
+ */
+export function checkCapacity(capacity: number, owner: string): number {
+  if (!Number.isSafeInteger(capacity) || capacity < 1) {
+    throw new RangeError(`${owner}: the capacity must be a positive whole number, not ${String(capacity)}`);
+  }
+  return capacity;
+}

package/src/core/layers.ts

@@ -0,0 +1,86 @@
+/**
+ * This module holds the one fold of a stack of layers. A layer wraps the next thing, so a stack
+ * of layers wraps a base. The next thing can be a collection, a function or any other value.
+ *
+ * This file has no imports. A package that needs only the fold loads this one file.
+ *
+ * @example
+ * const parse = compose(
+ *   (next: (text: string) => number) => (text: string) => next(text.trim()),
+ *   (next: (text: string) => number) => (text: string) => next(text) * 2
+ * )(Number);
+ * parse(" 21 "); // 42
+ */
+
+/**
+ * A layer takes the next thing and gives a wrapped thing.
+ *
+ * @template Inner The type that the layer wraps
+ * @template Outer The type that the layer gives
+ */
+export type Layer<Inner = any, Outer = Inner> = (next: Inner) => Outer;
+
+/** This type gives the type that a layer wraps. */
+export type InnerOf<L> = L extends (next: infer I) => any ? I : never;
+
+/** This type gives the type that a layer gives. */
+export type OuterOf<L> = L extends (next: any) => infer O ? O : never;
+
+/**
+ * This type checks each neighbor pair of a list of layers. The result of the inner neighbor must
+ * fit the input of the outer neighbor. At the first bad pair, the compiler marks that argument.
+ *
+ * The type is tail recursive, so the compiler accepts a chain of 100 layers.
+ */
+export type Chain<L extends readonly unknown[], Done extends readonly unknown[] = readonly []> =
+  L extends readonly [infer A, infer B, ...infer R]
+    ? [OuterOf<B>] extends [InnerOf<A>]
+      ? Chain<readonly [B, ...R], readonly [...Done, A]>
+      : readonly [...Done, A, Layer<any, InnerOf<A>>, ...R]
+    : readonly [...Done, ...L];
+
+/**
+ * This type gives the function that {@link compose} returns. Its input is the input of the last
+ * layer, and its result is the result of the first layer. No layers give the identity function.
+ * A list that the compiler cannot see as a tuple gives the types of one element.
+ */
+export type Composed<L extends readonly unknown[]> =
+  L extends readonly []
+    ? <B>(base: B) => B
+    : L extends readonly [infer First, ...unknown[]]
+      ? L extends readonly [...unknown[], infer Last]
+        ? (base: InnerOf<Last>) => OuterOf<First>
+        : never
+      : L extends readonly (infer E)[]
+        ? (base: InnerOf<E>) => OuterOf<E>
+        : never;
+
+/** This type gives the intersection of the results of a list of layers. */
+export type Outers<L extends readonly unknown[], Sum = unknown> =
+  L extends readonly [infer First, ...infer Rest] ? Outers<Rest, Sum & OuterOf<First>> : Sum;
+
+/**
+ * This type gives the function for layers that keep each capability of the layers under them.
+ * Its result has the result of each layer and the base. Use it only when that law holds.
+ */
+export type Stacked<L extends readonly unknown[]> =
+  L extends readonly [...unknown[], infer Last]
+    ? (base: InnerOf<Last>) => Outers<L> & InnerOf<Last>
+    : Composed<L>;
+
+/**
+ * This function folds layers into one function that wraps a base. The first layer is the outermost.
+ *
+ * The fold holds four laws:
+ * - Identity: `compose()(b)` is `b`.
+ * - One layer: `compose(f)(b)` is `f(b)`.
+ * - Associativity: `compose(f, compose(g, h))` equals `compose(compose(f, g), h)`.
+ * - Order: `compose(f, g)(b)` is `f(g(b))`.
+ *
+ * @param layers The layers, from the outermost to the innermost
+ * @returns A function that wraps a base in the layers
+ */
+export function compose<const L extends readonly Layer[]>(...layers: L & Chain<L>): Composed<L> {
+  const list: readonly Layer[] = layers;
+  return ((base: unknown) => list.reduceRight((acc, layer) => layer(acc), base)) as Composed<L>;
+}

package/src/core/middleware.ts

@@ -9,13 +9,14 @@
  *
  * @example
  * const list = compose(
- *   safeList(),
- *   eventedList(),
- *   boundedList({ capacity: 100 })
+ *   safeList<number>(),
+ *   eventedList<number>(),
+ *   boundedList<number>({ capacity: 100 })
  * )(arrayList<number>())
  */
 
 import type { Collection } from "../interfaces/collection.js";
+import { compose as fold, type Chain, type Layer, type Stacked } from "./layers.js";
 
 /**
  * A middleware is a function that takes a collection and gives
@@ -52,9 +53,9 @@ export type Middleware<In = any, Out extends In = In> = (next: In) => Out;
  * // 3. bounded - enforces capacity limits
  * // 4. base - the underlying ArrayList
  * const enhancer = compose(
- *   safeList(),
- *   eventedList(),
- *   boundedList({ capacity: 100 })
+ *   safeList<number>(),
+ *   eventedList<number>(),
+ *   boundedList<number>({ capacity: 100 })
  * )
  * const list = enhancer(arrayList<number>())
  * // Type: List<number> & SafeCollection & EventedCollection & BoundedCollection
@@ -62,49 +63,8 @@ export type Middleware<In = any, Out extends In = In> = (next: In) => Out;
  * @param layers The middleware layers to compose
  * @returns A function that applies all layers to a base collection
  */
-
-// Overload for 1 middleware
-export function compose<C, R1 extends C>(
-  m1: Middleware<C, R1>
-): (base: C) => R1;
-
-// Overload for 2 middleware
-export function compose<C, R1 extends C, R2 extends R1>(
-  m1: Middleware<R1, R2>,
-  m2: Middleware<C, R1>
-): (base: C) => R2;
-
-// Overload for 3 middleware
-export function compose<C, R1 extends C, R2 extends R1, R3 extends R2>(
-  m1: Middleware<R2, R3>,
-  m2: Middleware<R1, R2>,
-  m3: Middleware<C, R1>
-): (base: C) => R3;
-
-// Overload for 4 middleware
-export function compose<C, R1 extends C, R2 extends R1, R3 extends R2, R4 extends R3>(
-  m1: Middleware<R3, R4>,
-  m2: Middleware<R2, R3>,
-  m3: Middleware<R1, R2>,
-  m4: Middleware<C, R1>
-): (base: C) => R4;
-
-// Overload for 5 middleware
-export function compose<C, R1 extends C, R2 extends R1, R3 extends R2, R4 extends R3, R5 extends R4>(
-  m1: Middleware<R4, R5>,
-  m2: Middleware<R3, R4>,
-  m3: Middleware<R2, R3>,
-  m4: Middleware<R1, R2>,
-  m5: Middleware<C, R1>
-): (base: C) => R5;
-
-// General fallback for any number of middleware
-export function compose<C>(...layers: Middleware<any, any>[]): (base: C) => any;
-
-// Implementation
-export function compose(...layers: Middleware<any, any>[]) {
-  return (base: any): any =>
-    layers.reduceRight((acc, layer) => layer(acc), base);
+export function compose<const L extends readonly Layer[]>(...layers: L & Chain<L>): Stacked<L> {
+  return fold(...(layers as readonly Layer[])) as unknown as Stacked<L>;
 }
 
 /**
@@ -361,53 +321,11 @@ export const enhanceMethod = <C extends object, K extends keyof C & string>(
  *
  * @example
  * const standardBehaviors = bundle(
- *   boundedList({ capacity: 1000 }),
- *   eventedList(),
- *   safeList()
+ *   boundedList<number>({ capacity: 1000 }),
+ *   eventedList<number>(),
+ *   safeList<number>()
  * )
  *
  * const list = compose(standardBehaviors)(arrayList<number>())
  */
-
-// Overload for 1 middleware
-export function bundle<C, R1 extends C>(
-  m1: Middleware<C, R1>
-): Middleware<C, R1>;
-
-// Overload for 2 middleware
-export function bundle<C, R1 extends C, R2 extends R1>(
-  m1: Middleware<R1, R2>,
-  m2: Middleware<C, R1>
-): Middleware<C, R2>;
-
-// Overload for 3 middleware
-export function bundle<C, R1 extends C, R2 extends R1, R3 extends R2>(
-  m1: Middleware<R2, R3>,
-  m2: Middleware<R1, R2>,
-  m3: Middleware<C, R1>
-): Middleware<C, R3>;
-
-// Overload for 4 middleware
-export function bundle<C, R1 extends C, R2 extends R1, R3 extends R2, R4 extends R3>(
-  m1: Middleware<R3, R4>,
-  m2: Middleware<R2, R3>,
-  m3: Middleware<R1, R2>,
-  m4: Middleware<C, R1>
-): Middleware<C, R4>;
-
-// Overload for 5 middleware
-export function bundle<C, R1 extends C, R2 extends R1, R3 extends R2, R4 extends R3, R5 extends R4>(
-  m1: Middleware<R4, R5>,
-  m2: Middleware<R3, R4>,
-  m3: Middleware<R2, R3>,
-  m4: Middleware<R1, R2>,
-  m5: Middleware<C, R1>
-): Middleware<C, R5>;
-
-// General fallback for any number of middleware
-export function bundle<C>(...middleware: Middleware<any, any>[]): Middleware<C, any>;
-
-// Implementation
-export function bundle(...middleware: Middleware<any, any>[]): Middleware<any, any> {
-  return (next: any): any => compose(...middleware)(next);
-}
+export const bundle: typeof compose = compose;