venerate 0.0.0

package/README.md

@@ -0,0 +1,55 @@
+# treetrunks
+
+<a aria-label="NPM version" href="https://www.npmjs.com/package/treetrunks">
+  <img alt="NPM Version" src="https://img.shields.io/npm/v/treetrunks?style=for-the-badge">
+</a>
+<a aria-label="Dependencies 0" href="https://www.npmjs.com/package/treetrunks">
+  <img alt="Dependencies 0" src=" https://img.shields.io/badge/dependencies-0-0?style=for-the-badge">
+</a>
+<a href="https://bundlephobia.com/result?p=treetrunks">
+  <img alt="Bundlephobia" src="https://img.shields.io/bundlephobia/minzip/treetrunks?style=for-the-badge">
+</a>
+<a aria-label="Coverage" href="https://recoverage.cloud/">
+  <img alt="Coverage" src="https://img.shields.io/endpoint?url=https%3A%2F%2Frecoverage.cloud%2Fshields%2FS1ikz1yFmk93qbAI7lLnu%2Ftreetrunks">
+</a>
+
+```sh
+npm i treetrunks
+```
+
+treetrunks is a convenient way to define type-safe routers.
+
+## overview
+
+a tree structure affords many possible routes through the tree
+
+```typescript
+import type { Tree, TreePath } from "treetrunks";
+import { optional, required } from "treetrunks";
+
+const greetingTree = required({
+  hello: optional({
+    world: null,
+    $name: optional({
+      good: required({
+        morning: null,
+      }),
+    }),
+  }),
+}) satisfies Tree;
+
+const validPaths: TreePath<typeof greetingTree>[] = [
+  [`hello`],
+  [`hello`, `world`],
+  [`hello`, `jeremybanka`],
+  [`hello`, `treetrunks`, `good`, `morning`],
+];
+```
+
+the `optional` and `required` functions help determine what routes are valid.
+
+note that,
+
+- `"hello"` is required
+- `"world"`, or any `$name` is optional
+- `"good morning"` is optional

package/dist/venerate.d.ts

@@ -0,0 +1,48 @@
+//#region src/venerate.d.ts
+/**
+* Cross-realm-safe check for anything that extends Set.
+*/
+declare function isSet(value: unknown): value is Set<any>;
+/**
+* Materializes an unknown iterable as a Set, without providing for mutation.
+* Does not copy the input if it is already a Set.
+*/
+declare const toSet: <T>(it: Iterable<T>) => ReadonlySet<T>;
+/**
+* Lazily yield the union of A, B, C, ... preserving first-seen order.
+* Only a small "seen" Set is maintained; inputs are streamed.
+*/
+declare function union<T>(...iterables: Iterable<T>[]): Iterable<T>;
+/**
+* Lazily yield A \ (B ∪ C ∪ ...), streaming A and pre-materializing removals.
+*/
+declare function difference<T>(a: Iterable<T>, ...rest: Iterable<T>[]): Iterable<T>;
+/**
+* Lazily yield A ∩ B ∩ C ∩ ...
+* Streams only the FIRST iterable; others are materialized as Sets for O(1) lookups.
+* If no others are provided, yields a shallow copy of A.
+*/
+declare function intersection<T>(a: Iterable<T>, ...rest: Iterable<T>[]): Iterable<T>;
+/**
+* Lazily yield A △ B (pairwise symmetric difference).
+* Streams A and B once; materializes the opposite side for membership checks.
+* - First yields items unique to A (preserving A's order)
+* - Then yields items unique to B (preserving B's order)
+*/
+declare function symmetricDifference<T>(a: Iterable<T>, b: Iterable<T>): Iterable<T>;
+/**
+* Variadic symmetric difference via left fold of the pairwise version.
+* Still lazy in the sense that we only materialize small per-step Sets;
+* each fold pass consumes its input generator.
+*/
+declare function symmetricDifferenceVariadic<T>(first: Iterable<T>, ...rest: Iterable<T>[]): Iterable<T>;
+/**
+* Predicates (not lazy outputs, but efficient w/ early exits)
+*/
+declare function isSubset<T>(a: Iterable<T>, b: Iterable<T>): boolean;
+declare function isSuperset<T>(a: Iterable<T>, b: Iterable<T>): boolean;
+declare function isDisjoint<T>(a: Iterable<T>, b: Iterable<T>): boolean;
+declare function equals<T>(a: Iterable<T>, b: Iterable<T>): boolean;
+//#endregion
+export { difference, equals, intersection, isDisjoint, isSet, isSubset, isSuperset, symmetricDifference, symmetricDifferenceVariadic, toSet, union };
+//# sourceMappingURL=venerate.d.ts.map

package/dist/venerate.js

@@ -0,0 +1,109 @@
+//#region src/venerate.ts
+/**
+* Cross-realm-safe check for anything that extends Set.
+*/
+function isSet(value) {
+	if (value == null) return false;
+	try {
+		Set.prototype.has.call(value, Symbol.for(`@@brandCheck`));
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Materializes an unknown iterable as a Set, without providing for mutation.
+* Does not copy the input if it is already a Set.
+*/
+const toSet = (it) => isSet(it) ? it : new Set(it);
+/**
+* Lazily yield the union of A, B, C, ... preserving first-seen order.
+* Only a small "seen" Set is maintained; inputs are streamed.
+*/
+function* union(...iterables) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const it of iterables) for (const v of it) if (!seen.has(v)) {
+		seen.add(v);
+		yield v;
+	}
+}
+/**
+* Lazily yield A \ (B ∪ C ∪ ...), streaming A and pre-materializing removals.
+*/
+function* difference(a, ...rest) {
+	if (rest.length === 0) {
+		yield* a;
+		return;
+	}
+	const remove = /* @__PURE__ */ new Set();
+	for (const it of rest) for (const v of it) remove.add(v);
+	for (const v of a) if (!remove.has(v)) yield v;
+}
+/**
+* Lazily yield A ∩ B ∩ C ∩ ...
+* Streams only the FIRST iterable; others are materialized as Sets for O(1) lookups.
+* If no others are provided, yields a shallow copy of A.
+*/
+function* intersection(a, ...rest) {
+	if (rest.length === 0) {
+		yield* a;
+		return;
+	}
+	const sets = rest.map(toSet);
+	for (const v of a) if (sets.every((s) => s.has(v))) yield v;
+}
+/**
+* Lazily yield A △ B (pairwise symmetric difference).
+* Streams A and B once; materializes the opposite side for membership checks.
+* - First yields items unique to A (preserving A's order)
+* - Then yields items unique to B (preserving B's order)
+*/
+function* symmetricDifference(a, b) {
+	const A = toSet(a);
+	const B = toSet(b);
+	for (const v of A) if (!B.has(v)) yield v;
+	for (const v of B) if (!A.has(v)) yield v;
+}
+/**
+* Variadic symmetric difference via left fold of the pairwise version.
+* Still lazy in the sense that we only materialize small per-step Sets;
+* each fold pass consumes its input generator.
+*/
+function* symmetricDifferenceVariadic(first, ...rest) {
+	let acc = first;
+	for (const it of rest) acc = symmetricDifference(acc, it);
+	yield* acc;
+}
+/**
+* Predicates (not lazy outputs, but efficient w/ early exits)
+*/
+function isSubset(a, b) {
+	const A = toSet(a);
+	const B = toSet(b);
+	if (A.size > B.size) return false;
+	for (const v of A) if (!B.has(v)) return false;
+	return true;
+}
+function isSuperset(a, b) {
+	return isSubset(b, a);
+}
+function isDisjoint(a, b) {
+	const A = toSet(a);
+	const B = toSet(b);
+	const aIsSmall = A.size <= B.size;
+	const small = aIsSmall ? A : B;
+	const big = aIsSmall ? B : A;
+	for (const v of small) if (big.has(v)) return false;
+	return true;
+}
+function equals(a, b) {
+	const A = toSet(a);
+	const B = toSet(b);
+	if (A.size !== B.size) return false;
+	for (const v of A) if (!B.has(v)) return false;
+	return true;
+}
+
+//#endregion
+export { difference, equals, intersection, isDisjoint, isSet, isSubset, isSuperset, symmetricDifference, symmetricDifferenceVariadic, toSet, union };
+//# sourceMappingURL=venerate.js.map

package/dist/venerate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"venerate.js","names":["acc: Iterable<T>"],"sources":["../src/venerate.ts"],"sourcesContent":["/**\n * Cross-realm-safe check for anything that extends Set.\n */\nexport function isSet(value: unknown): value is Set<any> {\n\tif (value == null) return false\n\ttry {\n\t\t// brand check: throws TypeError unless `value` has [[SetData]]\n\t\tSet.prototype.has.call(value, Symbol.for(`@@brandCheck`))\n\t\treturn true\n\t} catch {\n\t\treturn false\n\t}\n}\n\n/**\n * Materializes an unknown iterable as a Set, without providing for mutation.\n * Does not copy the input if it is already a Set.\n */\nexport const toSet = <T>(it: Iterable<T>): ReadonlySet<T> =>\n\tisSet(it) ? it : new Set(it)\n\n/**\n * Lazily yield the union of A, B, C, ... preserving first-seen order.\n * Only a small \"seen\" Set is maintained; inputs are streamed.\n */\nexport function* union<T>(...iterables: Iterable<T>[]): Iterable<T> {\n\tconst seen = new Set<T>()\n\tfor (const it of iterables) {\n\t\tfor (const v of it) {\n\t\t\tif (!seen.has(v)) {\n\t\t\t\tseen.add(v)\n\t\t\t\tyield v\n\t\t\t}\n\t\t}\n\t}\n}\n\n/**\n * Lazily yield A \\ (B ∪ C ∪ ...), streaming A and pre-materializing removals.\n */\nexport function* difference<T>(\n\ta: Iterable<T>,\n\t...rest: Iterable<T>[]\n): Iterable<T> {\n\tif (rest.length === 0) {\n\t\tyield* a\n\t\treturn\n\t}\n\tconst remove = new Set<T>()\n\tfor (const it of rest) for (const v of it) remove.add(v)\n\tfor (const v of a) if (!remove.has(v)) yield v\n}\n\n/**\n * Lazily yield A ∩ B ∩ C ∩ ...\n * Streams only the FIRST iterable; others are materialized as Sets for O(1) lookups.\n * If no others are provided, yields a shallow copy of A.\n */\nexport function* intersection<T>(\n\ta: Iterable<T>,\n\t...rest: Iterable<T>[]\n): Iterable<T> {\n\tif (rest.length === 0) {\n\t\tyield* a\n\t\treturn\n\t}\n\tconst sets = rest.map(toSet)\n\tfor (const v of a) {\n\t\tif (sets.every((s) => s.has(v))) yield v\n\t}\n}\n\n/**\n * Lazily yield A △ B (pairwise symmetric difference).\n * Streams A and B once; materializes the opposite side for membership checks.\n * - First yields items unique to A (preserving A's order)\n * - Then yields items unique to B (preserving B's order)\n */\nexport function* symmetricDifference<T>(\n\ta: Iterable<T>,\n\tb: Iterable<T>,\n): Iterable<T> {\n\tconst A = toSet(a)\n\tconst B = toSet(b)\n\n\t// Items unique to A\n\tfor (const v of A) if (!B.has(v)) yield v\n\t// Items unique to B\n\tfor (const v of B) if (!A.has(v)) yield v\n}\n\n/**\n * Variadic symmetric difference via left fold of the pairwise version.\n * Still lazy in the sense that we only materialize small per-step Sets;\n * each fold pass consumes its input generator.\n */\nexport function* symmetricDifferenceVariadic<T>(\n\tfirst: Iterable<T>,\n\t...rest: Iterable<T>[]\n): Iterable<T> {\n\tlet acc: Iterable<T> = first\n\tfor (const it of rest) acc = symmetricDifference(acc, it)\n\tyield* acc\n}\n\n/**\n * Predicates (not lazy outputs, but efficient w/ early exits)\n */\nexport function isSubset<T>(a: Iterable<T>, b: Iterable<T>): boolean {\n\tconst A = toSet(a)\n\tconst B = toSet(b)\n\tif (A.size > B.size) return false\n\tfor (const v of A) if (!B.has(v)) return false\n\treturn true\n}\n\nexport function isSuperset<T>(a: Iterable<T>, b: Iterable<T>): boolean {\n\treturn isSubset(b, a)\n}\n\nexport function isDisjoint<T>(a: Iterable<T>, b: Iterable<T>): boolean {\n\tconst A = toSet(a)\n\tconst B = toSet(b)\n\tconst aIsSmall = A.size <= B.size\n\tconst small = aIsSmall ? A : B\n\tconst big = aIsSmall ? B : A\n\tfor (const v of small) if (big.has(v)) return false\n\treturn true\n}\n\nexport function equals<T>(a: Iterable<T>, b: Iterable<T>): boolean {\n\tconst A = toSet(a)\n\tconst B = toSet(b)\n\tif (A.size !== B.size) return false\n\tfor (const v of A) if (!B.has(v)) return false\n\treturn true\n}\n"],"mappings":";;;;AAGA,SAAgB,MAAM,OAAmC;AACxD,KAAI,SAAS,KAAM,QAAO;AAC1B,KAAI;AAEH,MAAI,UAAU,IAAI,KAAK,OAAO,OAAO,IAAI;AACzC,SAAO;CACP,QAAO;AACP,SAAO;CACP;AACD;;;;;AAMD,MAAa,SAAY,OACxB,MAAM,MAAM,KAAK,IAAI,IAAI;;;;;AAM1B,UAAiB,MAAS,GAAG,WAAuC;CACnE,MAAM,uBAAO,IAAI;AACjB,MAAK,MAAM,MAAM,UAChB,MAAK,MAAM,KAAK,GACf,KAAI,CAAC,KAAK,IAAI,IAAI;AACjB,OAAK,IAAI;AACT,QAAM;CACN;AAGH;;;;AAKD,UAAiB,WAChB,GACA,GAAG,MACW;AACd,KAAI,KAAK,WAAW,GAAG;AACtB,SAAO;AACP;CACA;CACD,MAAM,yBAAS,IAAI;AACnB,MAAK,MAAM,MAAM,KAAM,MAAK,MAAM,KAAK,GAAI,QAAO,IAAI;AACtD,MAAK,MAAM,KAAK,EAAG,KAAI,CAAC,OAAO,IAAI,GAAI,OAAM;AAC7C;;;;;;AAOD,UAAiB,aAChB,GACA,GAAG,MACW;AACd,KAAI,KAAK,WAAW,GAAG;AACtB,SAAO;AACP;CACA;CACD,MAAM,OAAO,KAAK,IAAI;AACtB,MAAK,MAAM,KAAK,EACf,KAAI,KAAK,OAAO,MAAM,EAAE,IAAI,IAAK,OAAM;AAExC;;;;;;;AAQD,UAAiB,oBAChB,GACA,GACc;CACd,MAAM,IAAI,MAAM;CAChB,MAAM,IAAI,MAAM;AAGhB,MAAK,MAAM,KAAK,EAAG,KAAI,CAAC,EAAE,IAAI,GAAI,OAAM;AAExC,MAAK,MAAM,KAAK,EAAG,KAAI,CAAC,EAAE,IAAI,GAAI,OAAM;AACxC;;;;;;AAOD,UAAiB,4BAChB,OACA,GAAG,MACW;CACd,IAAIA,MAAmB;AACvB,MAAK,MAAM,MAAM,KAAM,OAAM,oBAAoB,KAAK;AACtD,QAAO;AACP;;;;AAKD,SAAgB,SAAY,GAAgB,GAAyB;CACpE,MAAM,IAAI,MAAM;CAChB,MAAM,IAAI,MAAM;AAChB,KAAI,EAAE,OAAO,EAAE,KAAM,QAAO;AAC5B,MAAK,MAAM,KAAK,EAAG,KAAI,CAAC,EAAE,IAAI,GAAI,QAAO;AACzC,QAAO;AACP;AAED,SAAgB,WAAc,GAAgB,GAAyB;AACtE,QAAO,SAAS,GAAG;AACnB;AAED,SAAgB,WAAc,GAAgB,GAAyB;CACtE,MAAM,IAAI,MAAM;CAChB,MAAM,IAAI,MAAM;CAChB,MAAM,WAAW,EAAE,QAAQ,EAAE;CAC7B,MAAM,QAAQ,WAAW,IAAI;CAC7B,MAAM,MAAM,WAAW,IAAI;AAC3B,MAAK,MAAM,KAAK,MAAO,KAAI,IAAI,IAAI,GAAI,QAAO;AAC9C,QAAO;AACP;AAED,SAAgB,OAAU,GAAgB,GAAyB;CAClE,MAAM,IAAI,MAAM;CAChB,MAAM,IAAI,MAAM;AAChB,KAAI,EAAE,SAAS,EAAE,KAAM,QAAO;AAC9B,MAAK,MAAM,KAAK,EAAG,KAAI,CAAC,EAAE,IAAI,GAAI,QAAO;AACzC,QAAO;AACP"}

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "venerate",
+	"version": "0.0.0",
+	"license": "MIT",
+	"author": {
+		"name": "Jeremy Banka",
+		"email": "hello@jeremybanka.com"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jeremybanka/wayforge.git",
+		"directory": "packages/venerate"
+	},
+	"type": "module",
+	"files": [
+		"dist",
+		"src"
+	],
+	"main": "dist/venerate.js",
+	"scripts": {
+		"build": "tsdown",
+		"lint:biome": "biome check -- .",
+		"lint:eslint": "eslint -- .",
+		"lint:types": "tsgo --noEmit",
+		"watch:types": "tsgo --watch --noEmit",
+		"lint": "concurrently \"bun:lint:*\"",
+		"test": "vitest",
+		"test:coverage": "vitest run --coverage",
+		"test:once": "vitest run",
+		"postversion": "biome format --write package.json"
+	},
+	"devDependencies": {
+		"@types/node": "24.3.0",
+		"@vitest/coverage-v8": "3.2.4",
+		"concurrently": "9.2.0",
+		"eslint": "9.33.0",
+		"recoverage": "0.1.11",
+		"tsdown": "0.14.1",
+		"vite": "7.1.3",
+		"vitest": "3.2.4"
+	}
+}

package/src/venerate.ts

@@ -0,0 +1,137 @@
+/**
+ * Cross-realm-safe check for anything that extends Set.
+ */
+export function isSet(value: unknown): value is Set<any> {
+	if (value == null) return false
+	try {
+		// brand check: throws TypeError unless `value` has [[SetData]]
+		Set.prototype.has.call(value, Symbol.for(`@@brandCheck`))
+		return true
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Materializes an unknown iterable as a Set, without providing for mutation.
+ * Does not copy the input if it is already a Set.
+ */
+export const toSet = <T>(it: Iterable<T>): ReadonlySet<T> =>
+	isSet(it) ? it : new Set(it)
+
+/**
+ * Lazily yield the union of A, B, C, ... preserving first-seen order.
+ * Only a small "seen" Set is maintained; inputs are streamed.
+ */
+export function* union<T>(...iterables: Iterable<T>[]): Iterable<T> {
+	const seen = new Set<T>()
+	for (const it of iterables) {
+		for (const v of it) {
+			if (!seen.has(v)) {
+				seen.add(v)
+				yield v
+			}
+		}
+	}
+}
+
+/**
+ * Lazily yield A \ (B ∪ C ∪ ...), streaming A and pre-materializing removals.
+ */
+export function* difference<T>(
+	a: Iterable<T>,
+	...rest: Iterable<T>[]
+): Iterable<T> {
+	if (rest.length === 0) {
+		yield* a
+		return
+	}
+	const remove = new Set<T>()
+	for (const it of rest) for (const v of it) remove.add(v)
+	for (const v of a) if (!remove.has(v)) yield v
+}
+
+/**
+ * Lazily yield A ∩ B ∩ C ∩ ...
+ * Streams only the FIRST iterable; others are materialized as Sets for O(1) lookups.
+ * If no others are provided, yields a shallow copy of A.
+ */
+export function* intersection<T>(
+	a: Iterable<T>,
+	...rest: Iterable<T>[]
+): Iterable<T> {
+	if (rest.length === 0) {
+		yield* a
+		return
+	}
+	const sets = rest.map(toSet)
+	for (const v of a) {
+		if (sets.every((s) => s.has(v))) yield v
+	}
+}
+
+/**
+ * Lazily yield A △ B (pairwise symmetric difference).
+ * Streams A and B once; materializes the opposite side for membership checks.
+ * - First yields items unique to A (preserving A's order)
+ * - Then yields items unique to B (preserving B's order)
+ */
+export function* symmetricDifference<T>(
+	a: Iterable<T>,
+	b: Iterable<T>,
+): Iterable<T> {
+	const A = toSet(a)
+	const B = toSet(b)
+
+	// Items unique to A
+	for (const v of A) if (!B.has(v)) yield v
+	// Items unique to B
+	for (const v of B) if (!A.has(v)) yield v
+}
+
+/**
+ * Variadic symmetric difference via left fold of the pairwise version.
+ * Still lazy in the sense that we only materialize small per-step Sets;
+ * each fold pass consumes its input generator.
+ */
+export function* symmetricDifferenceVariadic<T>(
+	first: Iterable<T>,
+	...rest: Iterable<T>[]
+): Iterable<T> {
+	let acc: Iterable<T> = first
+	for (const it of rest) acc = symmetricDifference(acc, it)
+	yield* acc
+}
+
+/**
+ * Predicates (not lazy outputs, but efficient w/ early exits)
+ */
+export function isSubset<T>(a: Iterable<T>, b: Iterable<T>): boolean {
+	const A = toSet(a)
+	const B = toSet(b)
+	if (A.size > B.size) return false
+	for (const v of A) if (!B.has(v)) return false
+	return true
+}
+
+export function isSuperset<T>(a: Iterable<T>, b: Iterable<T>): boolean {
+	return isSubset(b, a)
+}
+
+export function isDisjoint<T>(a: Iterable<T>, b: Iterable<T>): boolean {
+	const A = toSet(a)
+	const B = toSet(b)
+	const aIsSmall = A.size <= B.size
+	const small = aIsSmall ? A : B
+	const big = aIsSmall ? B : A
+	for (const v of small) if (big.has(v)) return false
+	return true
+}
+
+export function equals<T>(a: Iterable<T>, b: Iterable<T>): boolean {
+	const A = toSet(a)
+	const B = toSet(b)
+	if (A.size !== B.size) return false
+	for (const v of A) if (!B.has(v)) return false
+	return true
+}