distillate 0.1.1 → 0.2.0

package/dist/fuse/index.js

@@ -3,7 +3,9 @@ import { i as hash128KeyInto, n as readHeader, r as writeHeader, t as Serializat
 const ARITY = 3;
 const TYPE_FUSE8 = 3;
 const TYPE_FUSE16 = 4;
+/** Thrown when binary fuse construction fails to converge on the key set. */
 var BinaryFuseBuildError = class extends Error {
+	/** Discriminates this error from other `Error`s. */
 	name = "BinaryFuseBuildError";
 };
 let RLO = 0;
@@ -230,6 +232,10 @@ function fuseStateFromBytes(bytes, expectedType) {
 		size
 	};
 }
+/**
+* Shared behavior for the static binary fuse filters: an immutable,
+* space-efficient membership filter built once from a fixed key set.
+*/
 var BinaryFuse = class {
 	#fp;
 	#seed;
@@ -246,12 +252,19 @@ var BinaryFuse = class {
 		this.#segCountLen = state.params.segCountLen;
 		this.#size = state.size;
 	}
+	/** Number of distinct keys the filter was built from. */
 	get size() {
 		return this.#size;
 	}
+	/** Actual bits stored per key (`0` for an empty filter). */
 	get bitsPerKey() {
 		return this.#size === 0 ? 0 : this.#fp.byteLength * 8 / this.#size;
 	}
+	/**
+	* Serializes the filter to a portable little-endian byte layout.
+	*
+	* @returns The serialized filter, readable by the matching `fromBytes`.
+	*/
 	toBytes() {
 		const laneBytes = new Uint8Array(this.#fp.buffer, this.#fp.byteOffset, this.#fp.byteLength);
 		const body = new Uint8Array(16 + laneBytes.length);
@@ -267,6 +280,12 @@ var BinaryFuse = class {
 			flags: 0
 		}, body);
 	}
+	/**
+	* Tests whether a key is in the set.
+	*
+	* @param key - The key to test.
+	* @returns `true` if present (possibly a false positive); `false` guarantees absence.
+	*/
 	has(key) {
 		if (this.#fp.length === 0) return false;
 		hash128KeyInto(key, 0, scratchHash);
@@ -281,18 +300,65 @@ var BinaryFuse = class {
 		return ((mlo ^ mhi) & mask) === (((this.#fp[p0] ?? 0) ^ (this.#fp[p1] ?? 0) ^ (this.#fp[p2] ?? 0)) & mask);
 	}
 };
+/**
+* A static 8-bit binary fuse filter: built once from a key set, then immutable.
+* The most space-efficient option (~9 bits/key at ~0.39% false-positive rate).
+*
+* @example
+* ```ts
+* const filter = BinaryFuse8.from(["alice", "bob", "carol"]);
+* filter.has("alice"); // true
+* filter.size; // 3
+* ```
+*/
 var BinaryFuse8 = class BinaryFuse8 extends BinaryFuse {
+	/**
+	* Builds a filter from the given keys; duplicates are ignored.
+	*
+	* @param keys - The complete set of keys to store.
+	* @returns A new immutable filter.
+	* @throws {@link BinaryFuseBuildError} if construction fails to converge.
+	*/
 	static from(keys) {
 		return new BinaryFuse8(buildState(keys, (n) => new Uint8Array(n)));
 	}
+	/**
+	* Restores a filter from its {@link BinaryFuse8.toBytes} serialization.
+	*
+	* @param bytes - The serialized filter.
+	* @returns The reconstructed filter.
+	*/
 	static fromBytes(bytes) {
 		return new BinaryFuse8(fuseStateFromBytes(bytes, TYPE_FUSE8));
 	}
 };
+/**
+* A static 16-bit binary fuse filter: like {@link BinaryFuse8} but twice the
+* space (~18 bits/key) for a far lower false-positive rate (~1/65536).
+*
+* @example
+* ```ts
+* const filter = BinaryFuse16.from(["alice", "bob", "carol"]);
+* filter.has("alice"); // true
+* ```
+*/
 var BinaryFuse16 = class BinaryFuse16 extends BinaryFuse {
+	/**
+	* Builds a filter from the given keys; duplicates are ignored.
+	*
+	* @param keys - The complete set of keys to store.
+	* @returns A new immutable filter.
+	* @throws {@link BinaryFuseBuildError} if construction fails to converge.
+	*/
 	static from(keys) {
 		return new BinaryFuse16(buildState(keys, (n) => new Uint16Array(n)));
 	}
+	/**
+	* Restores a filter from its {@link BinaryFuse16.toBytes} serialization.
+	*
+	* @param bytes - The serialized filter.
+	* @returns The reconstructed filter.
+	*/
 	static fromBytes(bytes) {
 		return new BinaryFuse16(fuseStateFromBytes(bytes, TYPE_FUSE16));
 	}

package/dist/index.cjs

@@ -1,5 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#endregion
 //#region src/index.ts
-const VERSION = "0.1.0";
+/** The installed `distillate` package version. */
+const VERSION = "0.2.0";
 //#endregion
 exports.VERSION = VERSION;

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 //#region src/index.d.ts
-declare const VERSION = "0.1.0";
+/** The installed `distillate` package version. */
+declare const VERSION: string;
 //#endregion
 export { VERSION };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 //#region src/index.d.ts
-declare const VERSION = "0.1.0";
+/** The installed `distillate` package version. */
+declare const VERSION: string;
 //#endregion
 export { VERSION };

package/dist/index.js

@@ -1,4 +1,6 @@
+//#endregion
 //#region src/index.ts
-const VERSION = "0.1.0";
+/** The installed `distillate` package version. */
+const VERSION = "0.2.0";
 //#endregion
 export { VERSION };

package/dist/params-ChTRNxM9.js

@@ -0,0 +1,24 @@
+//#region src/core/params.ts
+/** Thrown when a structure is constructed with invalid parameters. */
+var ParamError = class extends RangeError {
+	/** Discriminates this error from other `Error`s. */
+	name = "ParamError";
+};
+/** Asserts `value` is an integer greater than or equal to 1. */
+function assertPositiveInt(value, label) {
+	if (!Number.isInteger(value) || value < 1) throw new ParamError(`${label} must be a positive integer, got ${String(value)}`);
+}
+/** Asserts `value` is a finite number greater than 0 (a positive real). */
+function assertPositiveFinite(value, label) {
+	if (!Number.isFinite(value) || value <= 0) throw new ParamError(`${label} must be a positive number, got ${String(value)}`);
+}
+/** Asserts `value` is an integer in the uint32 range `[0, 2^32 - 1]`. */
+function assertUint32(value, label) {
+	if (!Number.isInteger(value) || value < 0 || value > 4294967295) throw new ParamError(`${label} must be a uint32, got ${String(value)}`);
+}
+/** Asserts `value` is a finite number in the open interval `(0, 1)`. */
+function assertProbability(value, label) {
+	if (!Number.isFinite(value) || value <= 0 || value >= 1) throw new ParamError(`${label} must be in the open interval (0, 1), got ${String(value)}`);
+}
+//#endregion
+export { assertUint32 as a, assertProbability as i, assertPositiveFinite as n, assertPositiveInt as r, ParamError as t };

package/dist/params-DnqJBqLS.d.cts

@@ -0,0 +1,8 @@
+//#region src/core/params.d.ts
+/** Thrown when a structure is constructed with invalid parameters. */
+declare class ParamError extends RangeError {
+  /** Discriminates this error from other `Error`s. */
+  override readonly name = "ParamError";
+}
+//#endregion
+export { ParamError as t };

package/dist/params-DnqJBqLS.d.ts

@@ -0,0 +1,8 @@
+//#region src/core/params.d.ts
+/** Thrown when a structure is constructed with invalid parameters. */
+declare class ParamError extends RangeError {
+  /** Discriminates this error from other `Error`s. */
+  override readonly name = "ParamError";
+}
+//#endregion
+export { ParamError as t };

package/dist/params-J8p3bKq5.cjs

@@ -0,0 +1,53 @@
+//#region src/core/params.ts
+/** Thrown when a structure is constructed with invalid parameters. */
+var ParamError = class extends RangeError {
+	/** Discriminates this error from other `Error`s. */
+	name = "ParamError";
+};
+/** Asserts `value` is an integer greater than or equal to 1. */
+function assertPositiveInt(value, label) {
+	if (!Number.isInteger(value) || value < 1) throw new ParamError(`${label} must be a positive integer, got ${String(value)}`);
+}
+/** Asserts `value` is a finite number greater than 0 (a positive real). */
+function assertPositiveFinite(value, label) {
+	if (!Number.isFinite(value) || value <= 0) throw new ParamError(`${label} must be a positive number, got ${String(value)}`);
+}
+/** Asserts `value` is an integer in the uint32 range `[0, 2^32 - 1]`. */
+function assertUint32(value, label) {
+	if (!Number.isInteger(value) || value < 0 || value > 4294967295) throw new ParamError(`${label} must be a uint32, got ${String(value)}`);
+}
+/** Asserts `value` is a finite number in the open interval `(0, 1)`. */
+function assertProbability(value, label) {
+	if (!Number.isFinite(value) || value <= 0 || value >= 1) throw new ParamError(`${label} must be in the open interval (0, 1), got ${String(value)}`);
+}
+//#endregion
+Object.defineProperty(exports, "ParamError", {
+	enumerable: true,
+	get: function() {
+		return ParamError;
+	}
+});
+Object.defineProperty(exports, "assertPositiveFinite", {
+	enumerable: true,
+	get: function() {
+		return assertPositiveFinite;
+	}
+});
+Object.defineProperty(exports, "assertPositiveInt", {
+	enumerable: true,
+	get: function() {
+		return assertPositiveInt;
+	}
+});
+Object.defineProperty(exports, "assertProbability", {
+	enumerable: true,
+	get: function() {
+		return assertProbability;
+	}
+});
+Object.defineProperty(exports, "assertUint32", {
+	enumerable: true,
+	get: function() {
+		return assertUint32;
+	}
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "distillate",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Probabilistic data structures for JavaScript. Space-efficient, approximate-membership filters (Bloom, Blocked Bloom, Binary Fuse) with tunable error and a portable binary format; zero dependencies, universal.",
   "keywords": [
     "bloom-filter",
@@ -76,9 +76,12 @@
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
     "@eslint/js": "^10.0.1",
+    "@microsoft/api-extractor": "^7.58.12",
     "@types/node": "^26.1.2",
+    "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^10.8.0",
     "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-tsdoc": "^0.5.2",
     "fast-check": "^4.9.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.2.0",
@@ -87,6 +90,8 @@
     "publint": "^0.3.22",
     "tsdown": "^0.22.14",
     "tsx": "^4.23.1",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.12.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
@@ -100,6 +105,10 @@
     "check": "publint --strict && attw --pack . --profile node16",
     "attw": "attw --pack . --profile node16",
     "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "api:report": "node scripts/api-extractor.mjs --local",
+    "api:check": "node scripts/api-extractor.mjs",
+    "docs:api": "typedoc",
     "changeset": "changeset",
     "version": "changeset version",
     "release": "changeset publish",