@mark1russell7/collections 0.3.0 → 0.4.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.4.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

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

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/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;