distillate 0.1.2 → 0.2.0

package/dist/blocked/index.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_serialize = require("../serialize-CHHDM4TQ.cjs");
+const require_params = require("../params-J8p3bKq5.cjs");
 //#region src/blocked/blocked.ts
 const TYPE = 2;
 const SALT = Uint32Array.of(1203114875, 1150766481, 2284105051, 2729912477, 1884591559, 770785867, 2667333959, 1550580529);
@@ -45,6 +46,8 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	* @returns A new, empty filter.
 	*/
 	static create(n, epsilon) {
+		require_params.assertPositiveInt(n, "n");
+		require_params.assertProbability(epsilon, "epsilon");
 		const t = Math.log10(1 / epsilon);
 		const a = BlockedBloomFilter.#ANCHORS;
 		let seg = a.findIndex((p) => t <= p[0]);
@@ -53,7 +56,7 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 		const [t1, b1] = a[seg] ?? [0, 0];
 		const bitsPerKey = b0 + (b1 - b0) / (t1 - t0) * (t - t0);
 		return new BlockedBloomFilter({
-			bitsPerKey: Math.ceil(bitsPerKey),
+			bitsPerKey: Math.max(1, Math.ceil(bitsPerKey)),
 			capacity: n
 		});
 	}
@@ -62,6 +65,9 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	* {@link BlockedBloomFilter.create} unless restoring a specific configuration.
 	*/
 	constructor({ bitsPerKey, capacity, seed = 0 }) {
+		require_params.assertPositiveFinite(bitsPerKey, "bitsPerKey");
+		require_params.assertPositiveInt(capacity, "capacity");
+		require_params.assertUint32(seed, "seed");
 		this.#numBlocks = Math.max(1, Math.ceil(bitsPerKey * capacity / 256));
 		this.#lanes = new Uint32Array(this.#numBlocks * 8);
 		this.#seed = seed;
@@ -168,3 +174,4 @@ function fillBlock(key, numBlocks, seed, outWords, outBits) {
 //#endregion
 exports.BlockedBloomFilter = BlockedBloomFilter;
 exports.BlockedBloomParamMismatchError = BlockedBloomParamMismatchError;
+exports.ParamError = require_params.ParamError;

package/dist/blocked/index.d.cts

@@ -1,4 +1,5 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.cjs";
+import { t as ParamError } from "../params-DnqJBqLS.cjs";
 //#region src/blocked/blocked.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
 declare class BlockedBloomParamMismatchError extends Error {
@@ -78,4 +79,4 @@ declare class BlockedBloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams };
+export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, ParamError };

package/dist/blocked/index.d.ts

@@ -1,4 +1,5 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.js";
+import { t as ParamError } from "../params-DnqJBqLS.js";
 //#region src/blocked/blocked.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
 declare class BlockedBloomParamMismatchError extends Error {
@@ -78,4 +79,4 @@ declare class BlockedBloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams };
+export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, ParamError };

package/dist/blocked/index.js

@@ -1,4 +1,5 @@
 import { i as hash128KeyInto, n as readHeader, o as reduce, r as writeHeader } from "../serialize-5XQ5y_R-.js";
+import { a as assertUint32, i as assertProbability, n as assertPositiveFinite, r as assertPositiveInt, t as ParamError } from "../params-ChTRNxM9.js";
 //#region src/blocked/blocked.ts
 const TYPE = 2;
 const SALT = Uint32Array.of(1203114875, 1150766481, 2284105051, 2729912477, 1884591559, 770785867, 2667333959, 1550580529);
@@ -44,6 +45,8 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	* @returns A new, empty filter.
 	*/
 	static create(n, epsilon) {
+		assertPositiveInt(n, "n");
+		assertProbability(epsilon, "epsilon");
 		const t = Math.log10(1 / epsilon);
 		const a = BlockedBloomFilter.#ANCHORS;
 		let seg = a.findIndex((p) => t <= p[0]);
@@ -52,7 +55,7 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 		const [t1, b1] = a[seg] ?? [0, 0];
 		const bitsPerKey = b0 + (b1 - b0) / (t1 - t0) * (t - t0);
 		return new BlockedBloomFilter({
-			bitsPerKey: Math.ceil(bitsPerKey),
+			bitsPerKey: Math.max(1, Math.ceil(bitsPerKey)),
 			capacity: n
 		});
 	}
@@ -61,6 +64,9 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	* {@link BlockedBloomFilter.create} unless restoring a specific configuration.
 	*/
 	constructor({ bitsPerKey, capacity, seed = 0 }) {
+		assertPositiveFinite(bitsPerKey, "bitsPerKey");
+		assertPositiveInt(capacity, "capacity");
+		assertUint32(seed, "seed");
 		this.#numBlocks = Math.max(1, Math.ceil(bitsPerKey * capacity / 256));
 		this.#lanes = new Uint32Array(this.#numBlocks * 8);
 		this.#seed = seed;
@@ -165,4 +171,4 @@ function fillBlock(key, numBlocks, seed, outWords, outBits) {
 	}
 }
 //#endregion
-export { BlockedBloomFilter, BlockedBloomParamMismatchError };
+export { BlockedBloomFilter, BlockedBloomParamMismatchError, ParamError };

package/dist/bloom/index.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_serialize = require("../serialize-CHHDM4TQ.cjs");
+const require_params = require("../params-J8p3bKq5.cjs");
 //#region src/core/bitset.ts
 var BitSetRangeError = class extends RangeError {
 	name = "BitSetRangeError";
@@ -80,6 +81,8 @@ var BloomFilter = class BloomFilter {
 	* @returns A new, empty filter.
 	*/
 	static create(n, epsilon) {
+		require_params.assertPositiveInt(n, "n");
+		require_params.assertProbability(epsilon, "epsilon");
 		const f = new BloomFilter(optimal(n, epsilon));
 		f.#n = n;
 		return f;
@@ -109,6 +112,9 @@ var BloomFilter = class BloomFilter {
 	* {@link BloomFilter.create} unless restoring a specific configuration.
 	*/
 	constructor({ m, k, seed = 0 }) {
+		require_params.assertPositiveInt(m, "m");
+		require_params.assertPositiveInt(k, "k");
+		require_params.assertUint32(seed, "seed");
 		this.#bits = new BitSet(m);
 		this.#m = m;
 		this.#k = k;
@@ -184,3 +190,4 @@ var BloomFilter = class BloomFilter {
 //#endregion
 exports.BloomFilter = BloomFilter;
 exports.BloomParamMismatchError = BloomParamMismatchError;
+exports.ParamError = require_params.ParamError;

package/dist/bloom/index.d.cts

@@ -1,4 +1,5 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.cjs";
+import { t as ParamError } from "../params-DnqJBqLS.cjs";
 //#region src/bloom/bloom.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
 declare class BloomParamMismatchError extends Error {
@@ -79,4 +80,4 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BloomFilter, BloomParamMismatchError, type BloomParams };
+export { BloomFilter, BloomParamMismatchError, type BloomParams, ParamError };

package/dist/bloom/index.d.ts

@@ -1,4 +1,5 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.js";
+import { t as ParamError } from "../params-DnqJBqLS.js";
 //#region src/bloom/bloom.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
 declare class BloomParamMismatchError extends Error {
@@ -79,4 +80,4 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BloomFilter, BloomParamMismatchError, type BloomParams };
+export { BloomFilter, BloomParamMismatchError, type BloomParams, ParamError };

package/dist/bloom/index.js

@@ -1,4 +1,5 @@
 import { a as probeInto, n as readHeader, r as writeHeader } from "../serialize-5XQ5y_R-.js";
+import { a as assertUint32, i as assertProbability, r as assertPositiveInt, t as ParamError } from "../params-ChTRNxM9.js";
 //#region src/core/bitset.ts
 var BitSetRangeError = class extends RangeError {
 	name = "BitSetRangeError";
@@ -79,6 +80,8 @@ var BloomFilter = class BloomFilter {
 	* @returns A new, empty filter.
 	*/
 	static create(n, epsilon) {
+		assertPositiveInt(n, "n");
+		assertProbability(epsilon, "epsilon");
 		const f = new BloomFilter(optimal(n, epsilon));
 		f.#n = n;
 		return f;
@@ -108,6 +111,9 @@ var BloomFilter = class BloomFilter {
 	* {@link BloomFilter.create} unless restoring a specific configuration.
 	*/
 	constructor({ m, k, seed = 0 }) {
+		assertPositiveInt(m, "m");
+		assertPositiveInt(k, "k");
+		assertUint32(seed, "seed");
 		this.#bits = new BitSet(m);
 		this.#m = m;
 		this.#k = k;
@@ -181,4 +187,4 @@ var BloomFilter = class BloomFilter {
 	}
 };
 //#endregion
-export { BloomFilter, BloomParamMismatchError };
+export { BloomFilter, BloomParamMismatchError, ParamError };

package/dist/index.cjs

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

package/dist/index.js

@@ -1,6 +1,6 @@
 //#endregion
 //#region src/index.ts
 /** The installed `distillate` package version. */
-const VERSION = "0.1.2";
+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.2",
+  "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",