@fulmenhq/tsfulmen 0.1.13 → 0.1.14

package/CHANGELOG.md

@@ -7,23 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.1.13] - 2025-11-19
+## [0.1.14] - 2025-11-28
 
 ### Added
 
-- **Enterprise Configuration Loading** (`@fulmenhq/tsfulmen/config`) - Compliant implementation of Fulmen Forge Workhorse "Three-Layer Configuration" pattern:
-  - **Three Layers**: Defaults (required) → User Config (XDG paths) → Environment Variables (prefix-based)
-  - **Schema Validation**: Optional validation against Crucible-compliant JSON/YAML schemas via AJV
-  - **Metadata Tracking**: Detailed traceability of active layers, paths, and validation status
-  - **Type Safety**: Generic `loadConfig<T>` with typed error handling (`ConfigValidationError`)
+- **Unified Hashing Stack** (`@fulmenhq/tsfulmen/fulhash`) - Consolidated hashing implementations on `hash-wasm`
+  - Added support for **CRC32** and **CRC32C** algorithms (block and streaming)
+  - Implemented `multiHash()` for efficient single-pass multi-algorithm hashing
+  - Implemented `verify()` for checksum validation
+  - Benchmarked performance: XXH3-128 (~5GB/s), SHA-256 (~2GB/s), CRC (~1.2GB/s)
+  - Added comprehensive tests for streaming, concurrency, and encoding handling
 
 ### Changed
 
-- **Crucible SSOT** - Updated to v0.2.19 (syncs latest config, docs, and schemas)
+- **Crucible SSOT** - Updated to v0.2.20 (syncs latest fulhash types)
+- **Dependency Cleanup** - Removed `crc-32` and `fast-crc32c` in favor of `hash-wasm` consolidation
+- **Bug Fixes**:
+  - Fixed `Digest.parse` to support 8-char CRC checksums
+  - Fixed XXH3 encoding handling for non-UTF8 inputs
+  - Improved `MultiHashResult` typing and deduplication
 
 ---
 
-## [0.1.12] - 2025-11-18
+## [0.1.13] - 2025-11-20
 
 ### Fixed
 

package/dist/fulhash/index.d.ts

@@ -1,28 +1,80 @@
 /**
- * Type definitions for FulHash hashing module
+ * FulHash Types
+ * Code generated by scripts/codegen/generate-fulhash-types.ts; DO NOT EDIT.
+ */
+/**
+ * Supported hashing algorithms for FulHash
  */
 declare enum Algorithm {
+    /**
+     * XXH3 (128-bit)
+     * Fast non-cryptographic hash (default). Excellent collision resistance, extremely high throughput (50GB/s+).
+     */
     XXH3_128 = "xxh3-128",
-    SHA256 = "sha256"
-}
-interface HashOptions {
-    algorithm?: Algorithm;
-    encoding?: BufferEncoding;
+    /**
+     * SHA-256
+     * Cryptographic security standard. Resistant to intentional collisions. Use for security verification.
+     */
+    SHA256 = "sha256",
+    /**
+     * CRC-32 (IEEE)
+     * 32-bit Cyclic Redundancy Check. Standard for GZIP/ZIP/PNG legacy format interoperability.
+     */
+    CRC32 = "crc32",
+    /**
+     * CRC-32C (Castagnoli)
+     * 32-bit CRC (Castagnoli). HW accelerated (SSE4.2/ARMv8). Use for cloud storage (GCS, AWS) and networking.
+     */
+    CRC32C = "crc32c"
 }
+/**
+ * Standard digest payload returned by FulHash helpers
+ */
 interface Digest$1 {
-    algorithm: Algorithm;
+    /**
+     * Hash algorithm identifier
+     */
+    algorithm: "xxh3-128" | "crc32" | "crc32c" | "sha256";
+    /**
+     * Lowercase hexadecimal representation of the digest
+     */
     hex: string;
-    bytes: Uint8Array;
+    /**
+     * Canonical string representation '<algorithm>:<hex>'
+     */
     formatted: string;
+    /**
+     * Raw digest bytes (optional)
+     */
+    bytes?: number[];
 }
-interface StreamHasherOptions {
+
+interface HashOptions {
     algorithm?: Algorithm;
+    encoding?: BufferEncoding;
 }
 interface StreamHasher {
     update(data: string | Uint8Array): StreamHasher;
     digest(): Digest$1;
     reset(): StreamHasher;
 }
+interface StreamHasherOptions {
+    algorithm?: Algorithm;
+}
+type MultiHashResult = Partial<Record<Algorithm, Digest$1>>;
+
+type HashInput = string | Uint8Array | AsyncIterable<string | Uint8Array>;
+/**
+ * Compute multiple hashes in a single pass over the data.
+ * Useful for generating checksums for multiple algorithms (e.g. SHA256 + XXH3)
+ * without reading the stream multiple times.
+ */
+declare function multiHash(input: HashInput, algorithms: Algorithm[], encoding?: BufferEncoding): Promise<MultiHashResult>;
+/**
+ * Verify data against a formatted checksum (e.g. "sha256:abc...").
+ * Automatically selects the algorithm from the checksum prefix.
+ */
+declare function verify(input: HashInput, checksum: string, encoding?: BufferEncoding): Promise<boolean>;
 
 /**
  * Digest implementation - immutable hash result container
@@ -34,7 +86,7 @@ declare class Digest implements Digest$1 {
     readonly hex: string;
     readonly formatted: string;
     constructor(algorithm: Algorithm, bytes: Uint8Array);
-    get bytes(): Uint8Array;
+    get bytes(): number[];
     toJSON(): object;
     toString(): string;
     static parse(formatted: string): Digest;
@@ -74,9 +126,9 @@ declare function createStreamHasher(options?: StreamHasherOptions): Promise<Stre
 /**
  * FulHash - Consistent hashing API for Fulmen ecosystem
  *
- * Provides block and streaming hashing with xxh3-128 and sha256 algorithms.
+ * Provides block and streaming hashing with XXH3-128, SHA-256, CRC32, and CRC32C algorithms.
  * Cross-language compatible with gofulmen and pyfulmen.
  */
 declare const VERSION = "1.0.0";
 
-export { Algorithm, Digest, DigestStateError, FulHashError, type HashOptions, InvalidChecksumError, InvalidChecksumFormatError, type StreamHasher, type StreamHasherOptions, UnsupportedAlgorithmError, VERSION, createStreamHasher, hash, hashBytes, hashString };
+export { Algorithm, Digest, DigestStateError, FulHashError, type HashInput, type HashOptions, InvalidChecksumError, InvalidChecksumFormatError, type StreamHasher, type StreamHasherOptions, UnsupportedAlgorithmError, VERSION, createStreamHasher, hash, hashBytes, hashString, multiHash, verify };

package/dist/fulhash/index.js

@@ -1,5 +1,5 @@
+import { crc32, xxhash128, createXXHash128, createCRC32 } from 'hash-wasm';
 import { createHash } from 'crypto';
-import { xxhash128, createXXHash128 } from 'hash-wasm';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -11,6 +11,20 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/crucible/fulhash/types.ts
+var Algorithm;
+var init_types = __esm({
+  "src/crucible/fulhash/types.ts"() {
+    Algorithm = /* @__PURE__ */ ((Algorithm2) => {
+      Algorithm2["XXH3_128"] = "xxh3-128";
+      Algorithm2["SHA256"] = "sha256";
+      Algorithm2["CRC32"] = "crc32";
+      Algorithm2["CRC32C"] = "crc32c";
+      return Algorithm2;
+    })(Algorithm || {});
+  }
+});
+
 // src/fulhash/errors.ts
 var FulHashError, UnsupportedAlgorithmError, InvalidChecksumError, InvalidChecksumFormatError, DigestStateError;
 var init_errors = __esm({
@@ -54,24 +68,70 @@ var init_errors = __esm({
     };
   }
 });
-
-// src/fulhash/types.ts
-var Algorithm;
-var init_types = __esm({
-  "src/fulhash/types.ts"() {
-    Algorithm = /* @__PURE__ */ ((Algorithm2) => {
-      Algorithm2["XXH3_128"] = "xxh3-128";
-      Algorithm2["SHA256"] = "sha256";
-      return Algorithm2;
-    })(Algorithm || {});
+function hexToBytes(hex) {
+  const bytes = new Uint8Array(4);
+  for (let i = 0; i < 4; i++) {
+    bytes[i] = Number.parseInt(hex.substr(i * 2, 2), 16);
+  }
+  return bytes;
+}
+async function hashBytes(data) {
+  const hex = await crc32(data);
+  return hexToBytes(hex);
+}
+async function hashString(str, encoding = "utf8") {
+  if (encoding !== "utf8") {
+    const buf = Buffer.from(str, encoding);
+    const hex2 = await crc32(buf);
+    return hexToBytes(hex2);
+  }
+  const hex = await crc32(str);
+  return hexToBytes(hex);
+}
+async function createHasher() {
+  const hasher = await createCRC32();
+  return hasher;
+}
+var init_crc32 = __esm({
+  "src/fulhash/algorithms/crc32.ts"() {
   }
 });
-function hashBytes(data) {
+function hexToBytes2(hex) {
+  const bytes = new Uint8Array(4);
+  for (let i = 0; i < 4; i++) {
+    bytes[i] = Number.parseInt(hex.substr(i * 2, 2), 16);
+  }
+  return bytes;
+}
+async function hashBytes2(data) {
+  const hex = await crc32(data, CRC32C_POLYNOMIAL);
+  return hexToBytes2(hex);
+}
+async function hashString2(str, encoding = "utf8") {
+  if (encoding !== "utf8") {
+    const buf = Buffer.from(str, encoding);
+    const hex2 = await crc32(buf, CRC32C_POLYNOMIAL);
+    return hexToBytes2(hex2);
+  }
+  const hex = await crc32(str, CRC32C_POLYNOMIAL);
+  return hexToBytes2(hex);
+}
+async function createHasher2() {
+  const hasher = await createCRC32(CRC32C_POLYNOMIAL);
+  return hasher;
+}
+var CRC32C_POLYNOMIAL;
+var init_crc32c = __esm({
+  "src/fulhash/algorithms/crc32c.ts"() {
+    CRC32C_POLYNOMIAL = 2197175160;
+  }
+});
+function hashBytes3(data) {
   const hash2 = createHash("sha256");
   hash2.update(data);
   return new Uint8Array(hash2.digest());
 }
-function hashString(str, encoding = "utf8") {
+function hashString3(str, encoding = "utf8") {
   const hash2 = createHash("sha256");
   hash2.update(str, encoding);
   return new Uint8Array(hash2.digest());
@@ -80,25 +140,25 @@ var init_sha256 = __esm({
   "src/fulhash/algorithms/sha256.ts"() {
   }
 });
-function hexToBytes(hex) {
+function hexToBytes3(hex) {
   const bytes = new Uint8Array(16);
   for (let i = 0; i < 16; i++) {
     bytes[i] = Number.parseInt(hex.substr(i * 2, 2), 16);
   }
   return bytes;
 }
-async function hashBytes2(data) {
+async function hashBytes4(data) {
   const hex = await xxhash128(data);
-  return hexToBytes(hex);
+  return hexToBytes3(hex);
 }
-async function hashString2(str, encoding = "utf8") {
+async function hashString4(str, encoding = "utf8") {
   if (encoding !== "utf8") {
     throw new FulHashError(
       "XXH3-128 only supports UTF-8 encoding. Use utf8 encoding or convert data to Uint8Array."
     );
   }
   const hex = await xxhash128(str);
-  return hexToBytes(hex);
+  return hexToBytes3(hex);
 }
 var init_xxh3 = __esm({
   "src/fulhash/algorithms/xxh3.ts"() {
@@ -110,43 +170,66 @@ var init_xxh3 = __esm({
 var hash_exports = {};
 __export(hash_exports, {
   hash: () => hash,
-  hashBytes: () => hashBytes3,
-  hashString: () => hashString3
+  hashBytes: () => hashBytes5,
+  hashString: () => hashString5
 });
 async function hash(input, options) {
   const algorithm = options?.algorithm ?? "xxh3-128" /* XXH3_128 */;
   const encoding = options?.encoding ?? "utf8";
   let bytes;
-  if (algorithm === "sha256" /* SHA256 */) {
-    if (typeof input === "string") {
-      bytes = hashString(input, encoding);
-    } else {
-      bytes = hashBytes(input);
-    }
-  } else if (algorithm === "xxh3-128" /* XXH3_128 */) {
-    if (typeof input === "string") {
-      bytes = await hashString2(input, "utf8");
-    } else {
-      bytes = await hashBytes2(input);
-    }
-  } else {
-    throw new UnsupportedAlgorithmError(algorithm, ["sha256" /* SHA256 */, "xxh3-128" /* XXH3_128 */]);
+  switch (algorithm) {
+    case "sha256" /* SHA256 */:
+      if (typeof input === "string") {
+        bytes = hashString3(input, encoding);
+      } else {
+        bytes = hashBytes3(input);
+      }
+      break;
+    case "xxh3-128" /* XXH3_128 */:
+      if (typeof input === "string") {
+        if (encoding !== "utf8") {
+          bytes = await hashBytes4(Buffer.from(input, encoding));
+        } else {
+          bytes = await hashString4(input, "utf8");
+        }
+      } else {
+        bytes = await hashBytes4(input);
+      }
+      break;
+    case "crc32" /* CRC32 */:
+      if (typeof input === "string") {
+        bytes = await hashString(input, encoding);
+      } else {
+        bytes = await hashBytes(input);
+      }
+      break;
+    case "crc32c" /* CRC32C */:
+      if (typeof input === "string") {
+        bytes = await hashString2(input, encoding);
+      } else {
+        bytes = await hashBytes2(input);
+      }
+      break;
+    default:
+      throw new UnsupportedAlgorithmError(algorithm, Object.values(Algorithm));
   }
   return new Digest(algorithm, bytes);
 }
-async function hashString3(str, options) {
+async function hashString5(str, options) {
   return hash(str, options);
 }
-async function hashBytes3(data, options) {
+async function hashBytes5(data, options) {
   return hash(data, options);
 }
 var init_hash = __esm({
   "src/fulhash/hash.ts"() {
+    init_types();
+    init_crc32();
+    init_crc32c();
     init_sha256();
     init_xxh3();
     init_digest();
     init_errors();
-    init_types();
   }
 });
 
@@ -154,8 +237,8 @@ var init_hash = __esm({
 var Digest;
 var init_digest = __esm({
   "src/fulhash/digest.ts"() {
-    init_errors();
     init_types();
+    init_errors();
     Digest = class _Digest {
       algorithm;
       _bytes;
@@ -169,7 +252,7 @@ var init_digest = __esm({
         Object.freeze(this);
       }
       get bytes() {
-        return new Uint8Array(this._bytes);
+        return Array.from(this._bytes);
       }
       toJSON() {
         return {
@@ -199,7 +282,21 @@ var init_digest = __esm({
             "hex must contain only lowercase hexadecimal characters"
           );
         }
-        const expectedLength = algorithm === "xxh3-128" /* XXH3_128 */ ? 32 : 64;
+        let expectedLength;
+        switch (algorithm) {
+          case "xxh3-128" /* XXH3_128 */:
+            expectedLength = 32;
+            break;
+          case "sha256" /* SHA256 */:
+            expectedLength = 64;
+            break;
+          case "crc32" /* CRC32 */:
+          case "crc32c" /* CRC32C */:
+            expectedLength = 8;
+            break;
+          default:
+            throw new UnsupportedAlgorithmError(algorithm, Object.values(Algorithm));
+        }
         if (hex.length !== expectedLength) {
           throw new InvalidChecksumError(
             formatted,
@@ -232,14 +329,17 @@ var init_digest = __esm({
 });
 
 // src/fulhash/index.ts
+init_types();
+
+// src/fulhash/convenience.ts
 init_digest();
-init_errors();
-init_hash();
 
 // src/fulhash/stream.ts
+init_types();
+init_crc32();
+init_crc32c();
 init_digest();
 init_errors();
-init_types();
 
 // src/fulhash/wasm-loader.ts
 init_errors();
@@ -260,7 +360,7 @@ async function initializeWasm() {
   });
   return initPromise;
 }
-async function createHasher() {
+async function createHasher3() {
   if (!isWasmReady) {
     throw new FulHashError("WASM not initialized. Call initializeWasm() first.");
   }
@@ -268,6 +368,15 @@ async function createHasher() {
 }
 
 // src/fulhash/stream.ts
+function intToBytes(crc) {
+  const bytes = new Uint8Array(4);
+  const unsigned = crc >>> 0;
+  bytes[0] = unsigned >>> 24 & 255;
+  bytes[1] = unsigned >>> 16 & 255;
+  bytes[2] = unsigned >>> 8 & 255;
+  bytes[3] = unsigned & 255;
+  return bytes;
+}
 var BaseStreamHasher = class {
   state = "initial" /* INITIAL */;
   algorithm;
@@ -352,23 +461,153 @@ var XXH3StreamHasher = class extends BaseStreamHasher {
     return this;
   }
 };
+var CRC32StreamHasher = class extends BaseStreamHasher {
+  hasher = null;
+  constructor() {
+    super("crc32" /* CRC32 */);
+  }
+  async init() {
+    this.hasher = await createHasher();
+    this.hasher.init();
+  }
+  update(data) {
+    this.ensureNotFinalized();
+    this.markUpdating();
+    if (!this.hasher) {
+      throw new Error("Hasher not initialized");
+    }
+    if (typeof data === "string") {
+      const encoder = new TextEncoder();
+      this.hasher.update(encoder.encode(data));
+    } else {
+      this.hasher.update(data);
+    }
+    return this;
+  }
+  digest() {
+    this.ensureUpdating();
+    this.markFinalized();
+    if (!this.hasher) throw new Error("Hasher not initialized");
+    const hex = this.hasher.digest();
+    const bytes = intToBytes(parseInt(hex, 16));
+    return new Digest(this.algorithm, bytes);
+  }
+  reset() {
+    if (!this.hasher) throw new Error("Hasher not initialized");
+    this.hasher.init();
+    this.markInitial();
+    return this;
+  }
+};
+var CRC32CStreamHasher = class extends BaseStreamHasher {
+  hasher = null;
+  constructor() {
+    super("crc32c" /* CRC32C */);
+  }
+  async init() {
+    this.hasher = await createHasher2();
+    this.hasher.init();
+  }
+  update(data) {
+    this.ensureNotFinalized();
+    this.markUpdating();
+    if (!this.hasher) throw new Error("Hasher not initialized");
+    if (typeof data === "string") {
+      const encoder = new TextEncoder();
+      this.hasher.update(encoder.encode(data));
+    } else {
+      this.hasher.update(data);
+    }
+    return this;
+  }
+  digest() {
+    this.ensureUpdating();
+    this.markFinalized();
+    if (!this.hasher) throw new Error("Hasher not initialized");
+    const hex = this.hasher.digest();
+    const bytes = intToBytes(parseInt(hex, 16));
+    return new Digest(this.algorithm, bytes);
+  }
+  reset() {
+    if (!this.hasher) throw new Error("Hasher not initialized");
+    this.hasher.init();
+    this.markInitial();
+    return this;
+  }
+};
 async function createStreamHasher(options = {}) {
   const algorithm = options.algorithm ?? "xxh3-128" /* XXH3_128 */;
-  if (algorithm === "sha256" /* SHA256 */) {
-    return new SHA256StreamHasher();
+  switch (algorithm) {
+    case "sha256" /* SHA256 */:
+      return new SHA256StreamHasher();
+    case "xxh3-128" /* XXH3_128 */: {
+      await initializeWasm();
+      const wasmHasher = await createHasher3();
+      return new XXH3StreamHasher(wasmHasher);
+    }
+    case "crc32" /* CRC32 */: {
+      const hasher = new CRC32StreamHasher();
+      await hasher.init();
+      return hasher;
+    }
+    case "crc32c" /* CRC32C */: {
+      const hasher = new CRC32CStreamHasher();
+      await hasher.init();
+      return hasher;
+    }
+    default:
+      throw new UnsupportedAlgorithmError(algorithm, Object.values(Algorithm));
+  }
+}
+
+// src/fulhash/convenience.ts
+async function multiHash(input, algorithms, encoding = "utf8") {
+  const uniqueAlgorithms = [...new Set(algorithms)];
+  const hashers = await Promise.all(
+    uniqueAlgorithms.map((algo) => createStreamHasher({ algorithm: algo }))
+  );
+  if (typeof input === "string") {
+    if (encoding !== "utf8") {
+      const buf = Buffer.from(input, encoding);
+      for (const hasher of hashers) {
+        hasher.update(buf);
+      }
+    } else {
+      for (const hasher of hashers) {
+        hasher.update(input);
+      }
+    }
+  } else if (input instanceof Uint8Array) {
+    for (const hasher of hashers) {
+      hasher.update(input);
+    }
+  } else {
+    for await (const chunk of input) {
+      for (const hasher of hashers) {
+        hasher.update(chunk);
+      }
+    }
   }
-  if (algorithm === "xxh3-128" /* XXH3_128 */) {
-    await initializeWasm();
-    const wasmHasher = await createHasher();
-    return new XXH3StreamHasher(wasmHasher);
+  const result = {};
+  for (let i = 0; i < uniqueAlgorithms.length; i++) {
+    result[uniqueAlgorithms[i]] = hashers[i].digest();
   }
-  throw new UnsupportedAlgorithmError(algorithm, ["sha256" /* SHA256 */, "xxh3-128" /* XXH3_128 */]);
+  return result;
+}
+async function verify(input, checksum, encoding = "utf8") {
+  const expected = Digest.parse(checksum);
+  const result = await multiHash(input, [expected.algorithm], encoding);
+  const actual = result[expected.algorithm];
+  if (!actual) return false;
+  return actual.algorithm === expected.algorithm && actual.hex === expected.hex;
 }
 
 // src/fulhash/index.ts
-init_types();
+init_digest();
+init_errors();
+init_hash();
 var VERSION = "1.0.0";
 
-export { Algorithm, Digest, DigestStateError, FulHashError, InvalidChecksumError, InvalidChecksumFormatError, UnsupportedAlgorithmError, VERSION, createStreamHasher, hash, hashBytes3 as hashBytes, hashString3 as hashString };
+export { Algorithm, Digest, DigestStateError, FulHashError, InvalidChecksumError, InvalidChecksumFormatError, UnsupportedAlgorithmError, VERSION, createStreamHasher, hash, hashBytes5 as hashBytes, hashString5 as hashString, multiHash, verify };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map