@mark1russell7/collections 0.2.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/build/testing/index.d.ts

@@ -11,6 +11,15 @@ export declare function show(value: unknown): string;
 /**
  * This function compares two values deeply: JSON values, arrays, plain objects and maps. Two maps
  * are equal when they have the same keys with equal values, in any order.
+ *
+ * This function is for JSON values in tests. It is not `deepEq`, the equality of the collections,
+ * and it differs in these cases:
+ *
+ * - A `Date`, a `Set` or an instance of a class equals only itself here. So `new Date(0)` does not
+ *   equal `new Date(0)` here, and it does under `deepEq`.
+ * - 0 does not equal -0 here, and it does under `deepEq`.
+ * - `{}` equals `Object.create(null)` here, and it does not under `deepEq`.
+ * - A cyclic value exhausts the stack here, and it ends under `deepEq`.
  */
 export declare function deepEqual(actual: unknown, expected: unknown): boolean;
 /** This function throws `ContractViolation` when the two values are not deeply equal. */

package/build/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/testing/check.ts"],"mappings":";;;;;qBAMa,0BAA0B;oBACnB;;;wBAIJ,KAAK;;;;;wBAmBL,UAAU,iBAAiB;;wBAqB3B,KAAK,iBAAiB,mBAAmB;;wBAOzC,MAAM,oBAAoB;;;;;wBAQpB,QAAQ,aAAa,kBAAkB,eAAe"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/testing/check.ts"],"mappings":";;;;;qBAMa,0BAA0B;oBACnB;;;wBAIJ,KAAK;;;;;;;;;;;;;;wBA4BL,UAAU,iBAAiB;;wBAqB3B,KAAK,iBAAiB,mBAAmB;;wBAOzC,MAAM,oBAAoB;;;;;wBAQpB,QAAQ,aAAa,kBAAkB,eAAe"}

package/build/testing/index.js

@@ -24,6 +24,15 @@ function isPlainObject(value) {
 /**
 * This function compares two values deeply: JSON values, arrays, plain objects and maps. Two maps
 * are equal when they have the same keys with equal values, in any order.
+*
+* This function is for JSON values in tests. It is not `deepEq`, the equality of the collections,
+* and it differs in these cases:
+*
+* - A `Date`, a `Set` or an instance of a class equals only itself here. So `new Date(0)` does not
+*   equal `new Date(0)` here, and it does under `deepEq`.
+* - 0 does not equal -0 here, and it does under `deepEq`.
+* - `{}` equals `Object.create(null)` here, and it does not under `deepEq`.
+* - A cyclic value exhausts the stack here, and it ends under `deepEq`.
 */
 function deepEqual(actual, expected) {
 	if (Object.is(actual, expected)) return true;

package/build/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/testing/check.ts"],"sourcesContent":["/**\n * The checks of the contract suite. The suite does not import a test framework, so a runtime\n * entry of this package does not load one. A failed check throws `ContractViolation`.\n */\n\n/** The error of a failed check of the contract suite. */\nexport class ContractViolation extends Error {\n  override readonly name = \"ContractViolation\";\n}\n\n/** This function gives the text of a value for a message: JSON, with a `Map` as its entries. */\nexport function show(value: unknown): string {\n  if (value === undefined) return \"undefined\";\n  try {\n    return JSON.stringify(value, (_key, item: unknown) => (item instanceof Map ? { Map: [...item.entries()] } : item === undefined ? \"<undefined>\" : item));\n  } catch {\n    return String(value);\n  }\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null) return false;\n  const prototype = Object.getPrototypeOf(value) as unknown;\n  return prototype === Object.prototype || prototype === null;\n}\n\n/**\n * This function compares two values deeply: JSON values, arrays, plain objects and maps. Two maps\n * are equal when they have the same keys with equal values, in any order.\n */\nexport function deepEqual(actual: unknown, expected: unknown): boolean {\n  if (Object.is(actual, expected)) return true;\n  if (actual instanceof Map && expected instanceof Map) {\n    if (actual.size !== expected.size) return false;\n    for (const [key, value] of actual) {\n      if (!expected.has(key) || !deepEqual(value, expected.get(key))) return false;\n    }\n    return true;\n  }\n  if (Array.isArray(actual) && Array.isArray(expected)) {\n    return actual.length === expected.length && actual.every((item, index) => deepEqual(item, expected[index]));\n  }\n  if (isPlainObject(actual) && isPlainObject(expected)) {\n    const keys = Object.keys(actual);\n    if (keys.length !== Object.keys(expected).length) return false;\n    return keys.every((key) => Object.prototype.hasOwnProperty.call(expected, key) && deepEqual(actual[key], expected[key]));\n  }\n  return false;\n}\n\n/** This function throws `ContractViolation` when the two values are not deeply equal. */\nexport function same(actual: unknown, expected: unknown, what: string): void {\n  if (!deepEqual(actual, expected)) {\n    throw new ContractViolation(`${what}: expected ${show(expected)}, got ${show(actual)}`);\n  }\n}\n\n/** This function throws `ContractViolation` when the condition is false. */\nexport function holds(condition: boolean, what: string): void {\n  if (!condition) throw new ContractViolation(what);\n}\n\n/**\n * This function starts an operation that must fail with a rejected promise, and gives the error.\n * A synchronous throw breaks the contract too: each method of a storage gives a promise.\n */\nexport async function rejects(start: () => Promise<unknown>, what: string): Promise<unknown> {\n  let promise: Promise<unknown>;\n  try {\n    promise = start();\n  } catch (error) {\n    throw new ContractViolation(`${what}: the method threw at once (${show(error instanceof Error ? error.message : error)}), and did not give a rejected promise`);\n  }\n  holds(typeof promise?.then === \"function\", `${what}: the method did not give a promise`);\n  try {\n    await promise;\n  } catch (error) {\n    return error;\n  }\n  throw new ContractViolation(`${what}: the promise did not reject`);\n}\n"],"mappings":";;;;;;AAMA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,OAAyB;AAC3B;;AAGA,SAAgB,KAAK,OAAwB;CAC3C,IAAI,UAAU,KAAA,GAAW,OAAO;CAChC,IAAI;EACF,OAAO,KAAK,UAAU,QAAQ,MAAM,SAAmB,gBAAgB,MAAM,EAAE,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,EAAE,IAAI,SAAS,KAAA,IAAY,gBAAgB,IAAK;CACxJ,QAAQ;EACN,OAAO,OAAO,KAAK;CACrB;AACF;AAEA,SAAS,cAAc,OAAkD;CACvE,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,YAAY,OAAO,eAAe,KAAK;CAC7C,OAAO,cAAc,OAAO,aAAa,cAAc;AACzD;;;;;AAMA,SAAgB,UAAU,QAAiB,UAA4B;CACrE,IAAI,OAAO,GAAG,QAAQ,QAAQ,GAAG,OAAO;CACxC,IAAI,kBAAkB,OAAO,oBAAoB,KAAK;EACpD,IAAI,OAAO,SAAS,SAAS,MAAM,OAAO;EAC1C,KAAK,MAAM,CAAC,KAAK,UAAU,QACzB,IAAI,CAAC,SAAS,IAAI,GAAG,KAAK,CAAC,UAAU,OAAO,SAAS,IAAI,GAAG,CAAC,GAAG,OAAO;EAEzE,OAAO;CACT;CACA,IAAI,MAAM,QAAQ,MAAM,KAAK,MAAM,QAAQ,QAAQ,GACjD,OAAO,OAAO,WAAW,SAAS,UAAU,OAAO,OAAO,MAAM,UAAU,UAAU,MAAM,SAAS,MAAM,CAAC;CAE5G,IAAI,cAAc,MAAM,KAAK,cAAc,QAAQ,GAAG;EACpD,MAAM,OAAO,OAAO,KAAK,MAAM;EAC/B,IAAI,KAAK,WAAW,OAAO,KAAK,QAAQ,CAAC,CAAC,QAAQ,OAAO;EACzD,OAAO,KAAK,OAAO,QAAQ,OAAO,UAAU,eAAe,KAAK,UAAU,GAAG,KAAK,UAAU,OAAO,MAAM,SAAS,IAAI,CAAC;CACzH;CACA,OAAO;AACT;;AAGA,SAAgB,KAAK,QAAiB,UAAmB,MAAoB;CAC3E,IAAI,CAAC,UAAU,QAAQ,QAAQ,GAC7B,MAAM,IAAI,kBAAkB,GAAG,KAAK,aAAa,KAAK,QAAQ,EAAE,QAAQ,KAAK,MAAM,GAAG;AAE1F;;AAGA,SAAgB,MAAM,WAAoB,MAAoB;CAC5D,IAAI,CAAC,WAAW,MAAM,IAAI,kBAAkB,IAAI;AAClD;;;;;AAMA,eAAsB,QAAQ,OAA+B,MAAgC;CAC3F,IAAI;CACJ,IAAI;EACF,UAAU,MAAM;CAClB,SAAS,OAAO;EACd,MAAM,IAAI,kBAAkB,GAAG,KAAK,8BAA8B,KAAK,iBAAiB,QAAQ,MAAM,UAAU,KAAK,EAAE,uCAAuC;CAChK;CACA,MAAM,OAAO,SAAS,SAAS,YAAY,GAAG,KAAK,oCAAoC;CACvF,IAAI;EACF,MAAM;CACR,SAAS,OAAO;EACd,OAAO;CACT;CACA,MAAM,IAAI,kBAAkB,GAAG,KAAK,6BAA6B;AACnE"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/testing/check.ts"],"sourcesContent":["/**\n * The checks of the contract suite. The suite does not import a test framework, so a runtime\n * entry of this package does not load one. A failed check throws `ContractViolation`.\n */\n\n/** The error of a failed check of the contract suite. */\nexport class ContractViolation extends Error {\n  override readonly name = \"ContractViolation\";\n}\n\n/** This function gives the text of a value for a message: JSON, with a `Map` as its entries. */\nexport function show(value: unknown): string {\n  if (value === undefined) return \"undefined\";\n  try {\n    return JSON.stringify(value, (_key, item: unknown) => (item instanceof Map ? { Map: [...item.entries()] } : item === undefined ? \"<undefined>\" : item));\n  } catch {\n    return String(value);\n  }\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null) return false;\n  const prototype = Object.getPrototypeOf(value) as unknown;\n  return prototype === Object.prototype || prototype === null;\n}\n\n/**\n * This function compares two values deeply: JSON values, arrays, plain objects and maps. Two maps\n * are equal when they have the same keys with equal values, in any order.\n *\n * This function is for JSON values in tests. It is not `deepEq`, the equality of the collections,\n * and it differs in these cases:\n *\n * - A `Date`, a `Set` or an instance of a class equals only itself here. So `new Date(0)` does not\n *   equal `new Date(0)` here, and it does under `deepEq`.\n * - 0 does not equal -0 here, and it does under `deepEq`.\n * - `{}` equals `Object.create(null)` here, and it does not under `deepEq`.\n * - A cyclic value exhausts the stack here, and it ends under `deepEq`.\n */\nexport function deepEqual(actual: unknown, expected: unknown): boolean {\n  if (Object.is(actual, expected)) return true;\n  if (actual instanceof Map && expected instanceof Map) {\n    if (actual.size !== expected.size) return false;\n    for (const [key, value] of actual) {\n      if (!expected.has(key) || !deepEqual(value, expected.get(key))) return false;\n    }\n    return true;\n  }\n  if (Array.isArray(actual) && Array.isArray(expected)) {\n    return actual.length === expected.length && actual.every((item, index) => deepEqual(item, expected[index]));\n  }\n  if (isPlainObject(actual) && isPlainObject(expected)) {\n    const keys = Object.keys(actual);\n    if (keys.length !== Object.keys(expected).length) return false;\n    return keys.every((key) => Object.prototype.hasOwnProperty.call(expected, key) && deepEqual(actual[key], expected[key]));\n  }\n  return false;\n}\n\n/** This function throws `ContractViolation` when the two values are not deeply equal. */\nexport function same(actual: unknown, expected: unknown, what: string): void {\n  if (!deepEqual(actual, expected)) {\n    throw new ContractViolation(`${what}: expected ${show(expected)}, got ${show(actual)}`);\n  }\n}\n\n/** This function throws `ContractViolation` when the condition is false. */\nexport function holds(condition: boolean, what: string): void {\n  if (!condition) throw new ContractViolation(what);\n}\n\n/**\n * This function starts an operation that must fail with a rejected promise, and gives the error.\n * A synchronous throw breaks the contract too: each method of a storage gives a promise.\n */\nexport async function rejects(start: () => Promise<unknown>, what: string): Promise<unknown> {\n  let promise: Promise<unknown>;\n  try {\n    promise = start();\n  } catch (error) {\n    throw new ContractViolation(`${what}: the method threw at once (${show(error instanceof Error ? error.message : error)}), and did not give a rejected promise`);\n  }\n  holds(typeof promise?.then === \"function\", `${what}: the method did not give a promise`);\n  try {\n    await promise;\n  } catch (error) {\n    return error;\n  }\n  throw new ContractViolation(`${what}: the promise did not reject`);\n}\n"],"mappings":";;;;;;AAMA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,OAAyB;AAC3B;;AAGA,SAAgB,KAAK,OAAwB;CAC3C,IAAI,UAAU,KAAA,GAAW,OAAO;CAChC,IAAI;EACF,OAAO,KAAK,UAAU,QAAQ,MAAM,SAAmB,gBAAgB,MAAM,EAAE,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,EAAE,IAAI,SAAS,KAAA,IAAY,gBAAgB,IAAK;CACxJ,QAAQ;EACN,OAAO,OAAO,KAAK;CACrB;AACF;AAEA,SAAS,cAAc,OAAkD;CACvE,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,YAAY,OAAO,eAAe,KAAK;CAC7C,OAAO,cAAc,OAAO,aAAa,cAAc;AACzD;;;;;;;;;;;;;;AAeA,SAAgB,UAAU,QAAiB,UAA4B;CACrE,IAAI,OAAO,GAAG,QAAQ,QAAQ,GAAG,OAAO;CACxC,IAAI,kBAAkB,OAAO,oBAAoB,KAAK;EACpD,IAAI,OAAO,SAAS,SAAS,MAAM,OAAO;EAC1C,KAAK,MAAM,CAAC,KAAK,UAAU,QACzB,IAAI,CAAC,SAAS,IAAI,GAAG,KAAK,CAAC,UAAU,OAAO,SAAS,IAAI,GAAG,CAAC,GAAG,OAAO;EAEzE,OAAO;CACT;CACA,IAAI,MAAM,QAAQ,MAAM,KAAK,MAAM,QAAQ,QAAQ,GACjD,OAAO,OAAO,WAAW,SAAS,UAAU,OAAO,OAAO,MAAM,UAAU,UAAU,MAAM,SAAS,MAAM,CAAC;CAE5G,IAAI,cAAc,MAAM,KAAK,cAAc,QAAQ,GAAG;EACpD,MAAM,OAAO,OAAO,KAAK,MAAM;EAC/B,IAAI,KAAK,WAAW,OAAO,KAAK,QAAQ,CAAC,CAAC,QAAQ,OAAO;EACzD,OAAO,KAAK,OAAO,QAAQ,OAAO,UAAU,eAAe,KAAK,UAAU,GAAG,KAAK,UAAU,OAAO,MAAM,SAAS,IAAI,CAAC;CACzH;CACA,OAAO;AACT;;AAGA,SAAgB,KAAK,QAAiB,UAAmB,MAAoB;CAC3E,IAAI,CAAC,UAAU,QAAQ,QAAQ,GAC7B,MAAM,IAAI,kBAAkB,GAAG,KAAK,aAAa,KAAK,QAAQ,EAAE,QAAQ,KAAK,MAAM,GAAG;AAE1F;;AAGA,SAAgB,MAAM,WAAoB,MAAoB;CAC5D,IAAI,CAAC,WAAW,MAAM,IAAI,kBAAkB,IAAI;AAClD;;;;;AAMA,eAAsB,QAAQ,OAA+B,MAAgC;CAC3F,IAAI;CACJ,IAAI;EACF,UAAU,MAAM;CAClB,SAAS,OAAO;EACd,MAAM,IAAI,kBAAkB,GAAG,KAAK,8BAA8B,KAAK,iBAAiB,QAAQ,MAAM,UAAU,KAAK,EAAE,uCAAuC;CAChK;CACA,MAAM,OAAO,SAAS,SAAS,YAAY,GAAG,KAAK,oCAAoC;CACvF,IAAI;EACF,MAAM;CACR,SAAS,OAAO;EACd,OAAO;CACT;CACA,MAAM,IAAI,kBAAkB,GAAG,KAAK,6BAA6B;AACnE"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/collections",
-  "version": "0.2.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;

package/src/testing/check.ts

@@ -27,6 +27,15 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 /**
  * This function compares two values deeply: JSON values, arrays, plain objects and maps. Two maps
  * are equal when they have the same keys with equal values, in any order.
+ *
+ * This function is for JSON values in tests. It is not `deepEq`, the equality of the collections,
+ * and it differs in these cases:
+ *
+ * - A `Date`, a `Set` or an instance of a class equals only itself here. So `new Date(0)` does not
+ *   equal `new Date(0)` here, and it does under `deepEq`.
+ * - 0 does not equal -0 here, and it does under `deepEq`.
+ * - `{}` equals `Object.create(null)` here, and it does not under `deepEq`.
+ * - A cyclic value exhausts the stack here, and it ends under `deepEq`.
  */
 export function deepEqual(actual: unknown, expected: unknown): boolean {
   if (Object.is(actual, expected)) return true;

package/src/utils/defaults.ts

@@ -65,6 +65,15 @@ function equalElements(a: ArrayLike<unknown>, b: ArrayLike<unknown>): boolean {
   return true;
 }
 
+/** The kinds of `equalObjects` and `hashFields`, so that the relation and its hash stay in step. */
+const isBinary = (value: object): value is ArrayBufferLike | DataView =>
+  value instanceof DataView || value instanceof ArrayBuffer || (typeof SharedArrayBuffer !== "undefined" && value instanceof SharedArrayBuffer);
+
+const isOpaque = (value: object): boolean => value instanceof Promise || value instanceof WeakMap || value instanceof WeakSet || value instanceof WeakRef;
+
+const isBoxed = (value: object): boolean =>
+  value instanceof Number || value instanceof String || value instanceof Boolean || value instanceof BigInt || value instanceof Symbol;
+
 function bytesOf(value: ArrayBufferLike | DataView): Uint8Array {
   return ArrayBuffer.isView(value) ? new Uint8Array(value.buffer, value.byteOffset, value.byteLength) : new Uint8Array(value);
 }
@@ -114,16 +123,13 @@ function equalObjects(a: any, b: any, held: HeldPairs): boolean {
     }
     return true;
   }
-  if (a instanceof DataView || a instanceof ArrayBuffer || (typeof SharedArrayBuffer !== "undefined" && a instanceof SharedArrayBuffer)) {
-    return equalElements(bytesOf(a), bytesOf(b));
-  }
+  if (isBinary(a)) return equalElements(bytesOf(a), bytesOf(b));
   if (ArrayBuffer.isView(a)) return equalElements(a as unknown as ArrayLike<unknown>, b);
-  if (a instanceof Promise || a instanceof WeakMap || a instanceof WeakSet || a instanceof WeakRef) return false;
+  if (isOpaque(a)) return false;
   if (a instanceof Date && !sameValueZero(a.getTime(), b.getTime())) return false;
   if (a instanceof RegExp && (a.source !== b.source || a.flags !== b.flags)) return false;
   if (a instanceof Error && !(a.name === b.name && a.message === b.message && equalValues(a.cause, b.cause, held))) return false;
-  const boxed = a instanceof Number || a instanceof String || a instanceof Boolean || a instanceof BigInt || a instanceof Symbol;
-  if (boxed && !sameValueZero(a.valueOf(), b.valueOf())) return false;
+  if (isBoxed(a) && !sameValueZero(a.valueOf(), b.valueOf())) return false;
   if ((a instanceof Map || a instanceof Set) && !equalEntries(a, b, held)) return false;
   return equalKeys(a, b, held);
 }
@@ -166,6 +172,7 @@ function equalValues(a: unknown, b: unknown, held: HeldPairs): boolean {
  * - Cycles are safe: two cyclic values are equal when they unfold to the same infinite tree.
  *
  * The recursion follows the depth of the data, so a very deep value can exhaust the stack.
+ * `defaultHash` agrees with this relation: two equal values have one hash.
  */
 export const deepEq: Eq<any> = (a, b): boolean => equalValues(a, b, { partners: new Map(), log: [] });
 
@@ -188,17 +195,11 @@ export const eqBy = <T, K extends keyof T = keyof T>(
 // Default Hashing
 // ============================================================================
 
-/**
- * Default hash function for primitives and objects.
- * For objects, hashes the JSON string representation.
- */
-export const defaultHash: Hash<any> = (value: any): number => {
+/** The hash of one primitive or function. */
+function hashPrimitive(value: unknown): number {
   if (value === null) return 0;
   if (value === undefined) return 1;
-
-  const type = typeof value;
-
-  switch (type) {
+  switch (typeof value) {
     case "boolean":
       return value ? 1 : 0;
     case "number":
@@ -209,19 +210,104 @@ export const defaultHash: Hash<any> = (value: any): number => {
       return hashString(value.toString());
     case "bigint":
       return hashString(value.toString());
-    case "object":
-      // For objects, hash their JSON representation
-      // This is not ideal for all cases but provides a reasonable default
-      try {
-        return hashString(JSON.stringify(value));
-      } catch {
-        // If JSON.stringify fails, fall back to toString
-        return hashString(value.toString());
-      }
     default:
       return 2;
   }
-};
+}
+
+/** The levels of an object that `defaultHash` reads. A cyclic value unfolds to this depth and stops. */
+const HASH_DEPTH = 16;
+
+/** The hashes of one call, by object and by remaining depth. A shared part costs one visit per depth. */
+type HashMemo = Map<object, number[]>;
+
+/** This function adds one hash to a running hash. The result depends on the order. */
+const mix = (hash: number, part: number): number => (Math.imul(hash, 31) + part) | 0;
+
+/** The finalizer of MurmurHash3. It makes a sum of entries depend on each pair, not on each half. */
+function scramble(hash: number): number {
+  let mixed = hash ^ (hash >>> 16);
+  mixed = Math.imul(mixed, 0x85ebca6b);
+  mixed ^= mixed >>> 13;
+  mixed = Math.imul(mixed, 0xc2b2ae35);
+  return mixed ^ (mixed >>> 16);
+}
+
+/** The start values of the kinds. Two kinds do not compare equal, so their hashes can differ. */
+const KIND = { array: 3, binary: 5, elements: 7, opaque: 11, record: 13 } as const;
+
+const hashAt = (value: unknown, depth: number, memo: HashMemo): number =>
+  isObject(value) ? hashObject(value, depth, memo) : hashPrimitive(value);
+
+function hashElements(start: number, elements: ArrayLike<unknown>): number {
+  let hash = start;
+  for (let i = 0; i < elements.length; i++) hash = mix(hash, hashPrimitive(elements[i]));
+  return hash;
+}
+
+/** The sum of the entries of a map or a set. A sum does not depend on the order of the entries. */
+function hashEntries(value: Map<unknown, unknown> | Set<unknown>, depth: number, memo: HashMemo): number {
+  let sum = 0;
+  for (const [key, entry] of value.entries()) sum = (sum + scramble(mix(hashAt(key, depth, memo), hashAt(entry, depth, memo)))) | 0;
+  return sum;
+}
+
+/** The sum of the own enumerable keys and their values, as `equalKeys` reads them. */
+function hashKeys(value: any, depth: number, memo: HashMemo): number {
+  let sum = 0;
+  for (const key of enumerableKeys(value)) sum = (sum + scramble(mix(hashPrimitive(key), hashAt(value[key], depth, memo)))) | 0;
+  return sum;
+}
+
+/** The hash of the fields of one object. This function reads only what `equalObjects` reads. */
+function hashFields(value: any, depth: number, memo: HashMemo): number {
+  if (Array.isArray(value)) {
+    let hash: number = KIND.array;
+    for (let i = 0; i < value.length; i++) hash = mix(hash, hashAt(value[i], depth, memo));
+    return hash;
+  }
+  if (isBinary(value)) return hashElements(KIND.binary, bytesOf(value));
+  if (ArrayBuffer.isView(value)) return hashElements(KIND.elements, value as unknown as ArrayLike<unknown>);
+  if (isOpaque(value)) return KIND.opaque;
+  let hash: number = KIND.record;
+  if (value instanceof Date) hash = mix(hash, hashNumber(value.getTime()));
+  if (value instanceof RegExp) hash = mix(mix(hash, hashString(value.source)), hashString(value.flags));
+  if (value instanceof Error) {
+    hash = mix(mix(mix(hash, hashAt(value.name, depth, memo)), hashAt(value.message, depth, memo)), hashAt(value.cause, depth, memo));
+  }
+  if (isBoxed(value)) hash = mix(hash, hashPrimitive(value.valueOf()));
+  if (value instanceof Map || value instanceof Set) hash = mix(hash, hashEntries(value, depth, memo));
+  return mix(hash, hashKeys(value, depth, memo));
+}
+
+/** The hash of one object at one depth. The depth falls with each level, so a cycle ends. */
+function hashObject(value: object, depth: number, memo: HashMemo): number {
+  if (depth === 0) return 0;
+  let byDepth = memo.get(value);
+  if (byDepth === undefined) {
+    byDepth = [];
+    memo.set(value, byDepth);
+  }
+  const known = byDepth[depth];
+  if (known !== undefined) return known;
+  const hash = hashFields(value, depth - 1, memo);
+  byDepth[depth] = hash;
+  return hash;
+}
+
+/**
+ * This function is the default hash of a key. It agrees with `deepEq`: when `deepEq(a, b)` is true,
+ * `defaultHash(a)` equals `defaultHash(b)`. So a hash map with `deepEq` finds an equal key.
+ *
+ * - The hash of an object reads the same fields as `deepEq`. The order of the keys of an object,
+ *   and of the entries of a `Map` or a `Set`, has no effect.
+ * - The hash reads 16 levels, so a cyclic or very deep value ends. Two values that differ only
+ *   below that depth have one hash, and `deepEq` then tells them apart.
+ * - A shared part costs one visit per level, so a dense graph ends.
+ * - The hash of an object can change in a new version. Do not store it.
+ */
+export const defaultHash: Hash<any> = (value: any): number =>
+  isObject(value) ? hashObject(value, HASH_DEPTH, new Map()) : hashPrimitive(value);
 
 /**
  * Hash function for strings using djb2 algorithm.