@neoware_inc/neozipkit 0.5.0

package/dist/core/ZstdManager.d.ts

@@ -0,0 +1,56 @@
+/**
+ * ZstdManager - Global Zstd Codec Manager
+ *
+ * This manager ensures safe usage of the Zstd WASM module across multiple instances.
+ *
+ * ## Why This Is Necessary
+ *
+ * The `@oneidentity/zstd-js` library uses a shared WASM module internally.
+ * While `ZstdInit()` returns different object references, they all share the same
+ * `ZstdSimple` implementation and WASM memory/heap.
+ *
+ * This means concurrent or improperly managed sequential operations can cause
+ * memory corruption because they're all operating on the same underlying WASM state.
+ *
+ * ## How It Works
+ *
+ * 1. Single initialization: WASM module is initialized once globally
+ * 2. Operation queuing: All compress/decompress operations are queued
+ * 3. Sequential execution: JavaScript's single-threaded nature ensures safe execution
+ * 4. Automatic initialization: Lazy initialization on first use
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { ZstdManager } from './ZstdManager';
+ *
+ * // Compress
+ * const compressed = await ZstdManager.compress(data, level);
+ *
+ * // Decompress
+ * const decompressed = await ZstdManager.decompress(compressedData);
+ * ```
+ */
+/**
+ * Global Zstd Manager
+ * Use this for all Zstd compression/decompression operations
+ */
+export declare const ZstdManager: {
+    /**
+     * Compress data using Zstd
+     * Operations are automatically queued to prevent interference
+     */
+    compress: (data: Uint8Array, level?: number) => Promise<Uint8Array<ArrayBufferLike>>;
+    /**
+     * Decompress data using Zstd
+     * Operations are automatically queued to prevent interference
+     */
+    decompress: (data: Uint8Array | Buffer) => Promise<Uint8Array<ArrayBufferLike>>;
+    /**
+     * Reset the manager (for testing)
+     * @internal
+     */
+    reset: () => void;
+};
+export default ZstdManager;
+//# sourceMappingURL=ZstdManager.d.ts.map

package/dist/core/ZstdManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZstdManager.d.ts","sourceRoot":"","sources":["../../src/core/ZstdManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAyGH;;;GAGG;AACH,eAAO,MAAM,WAAW;IACtB;;;OAGG;qBACc,UAAU,UAAU,MAAM;IAG3C;;;OAGG;uBACgB,UAAU,GAAG,MAAM;IAGtC;;;OAGG;;CAEJ,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/core/ZstdManager.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * ZstdManager - Global Zstd Codec Manager
+ *
+ * This manager ensures safe usage of the Zstd WASM module across multiple instances.
+ *
+ * ## Why This Is Necessary
+ *
+ * The `@oneidentity/zstd-js` library uses a shared WASM module internally.
+ * While `ZstdInit()` returns different object references, they all share the same
+ * `ZstdSimple` implementation and WASM memory/heap.
+ *
+ * This means concurrent or improperly managed sequential operations can cause
+ * memory corruption because they're all operating on the same underlying WASM state.
+ *
+ * ## How It Works
+ *
+ * 1. Single initialization: WASM module is initialized once globally
+ * 2. Operation queuing: All compress/decompress operations are queued
+ * 3. Sequential execution: JavaScript's single-threaded nature ensures safe execution
+ * 4. Automatic initialization: Lazy initialization on first use
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { ZstdManager } from './ZstdManager';
+ *
+ * // Compress
+ * const compressed = await ZstdManager.compress(data, level);
+ *
+ * // Decompress
+ * const decompressed = await ZstdManager.decompress(compressedData);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZstdManager = void 0;
+const zstd_js_1 = require("@oneidentity/zstd-js");
+class ZstdCodecManager {
+    constructor() {
+        this.codec = null;
+        this.initPromise = null;
+        this.operationQueue = Promise.resolve();
+    }
+    /**
+     * Get the singleton instance of ZstdCodecManager
+     */
+    static getInstance() {
+        if (!ZstdCodecManager.instance) {
+            ZstdCodecManager.instance = new ZstdCodecManager();
+        }
+        return ZstdCodecManager.instance;
+    }
+    /**
+     * Ensure the Zstd codec is initialized
+     * This is called automatically before any compress/decompress operation
+     */
+    async ensureInitialized() {
+        if (this.codec) {
+            return;
+        }
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+        this.initPromise = (async () => {
+            this.codec = await (0, zstd_js_1.ZstdInit)();
+        })();
+        return this.initPromise;
+    }
+    /**
+     * Queue an operation to ensure sequential execution
+     * This prevents concurrent operations from interfering with each other
+     */
+    async queueOperation(operation) {
+        // Chain this operation after the previous one
+        const promise = this.operationQueue.then(operation, operation);
+        // Update the queue to point to this operation
+        this.operationQueue = promise.catch(() => { }); // Catch to prevent unhandled rejections in queue
+        return promise;
+    }
+    /**
+     * Compress data using Zstd
+     * @param data - Data to compress (Uint8Array)
+     * @param level - Compression level (1-22, default 6)
+     * @returns Compressed data as Uint8Array
+     */
+    async compress(data, level = 6) {
+        return this.queueOperation(async () => {
+            await this.ensureInitialized();
+            if (!this.codec) {
+                throw new Error('Zstd codec not initialized');
+            }
+            return this.codec.ZstdSimple.compress(data, level);
+        });
+    }
+    /**
+     * Decompress data using Zstd
+     * @param data - Compressed data (Uint8Array or Buffer)
+     * @returns Decompressed data as Uint8Array
+     */
+    async decompress(data) {
+        return this.queueOperation(async () => {
+            await this.ensureInitialized();
+            if (!this.codec) {
+                throw new Error('Zstd codec not initialized');
+            }
+            // Convert Buffer to Uint8Array if needed
+            const inputData = data instanceof Buffer
+                ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+                : data;
+            return this.codec.ZstdSimple.decompress(inputData);
+        });
+    }
+    /**
+     * Reset the manager (for testing purposes)
+     * @internal
+     */
+    static reset() {
+        ZstdCodecManager.instance = null;
+    }
+}
+ZstdCodecManager.instance = null;
+/**
+ * Global Zstd Manager
+ * Use this for all Zstd compression/decompression operations
+ */
+exports.ZstdManager = {
+    /**
+     * Compress data using Zstd
+     * Operations are automatically queued to prevent interference
+     */
+    compress: (data, level) => ZstdCodecManager.getInstance().compress(data, level),
+    /**
+     * Decompress data using Zstd
+     * Operations are automatically queued to prevent interference
+     */
+    decompress: (data) => ZstdCodecManager.getInstance().decompress(data),
+    /**
+     * Reset the manager (for testing)
+     * @internal
+     */
+    reset: () => ZstdCodecManager.reset(),
+};
+exports.default = exports.ZstdManager;
+//# sourceMappingURL=ZstdManager.js.map

package/dist/core/ZstdManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZstdManager.js","sourceRoot":"","sources":["../../src/core/ZstdManager.ts"],"names":[],"mappings":"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"}

package/dist/core/components/HashCalculator.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Unified hash calculator supporting:
+ * - Incremental CRC-32 and SHA-256 calculation from raw data chunks
+ * - Accumulation of pre-computed SHA-256 hashes with XOR and Merkle tree operations
+ * - Merkle tree construction, proof generation, and verification
+ *
+ * Usage examples:
+ *
+ * Incremental hash calculation:
+ * ```typescript
+ * const calculator = new HashCalculator({ useSHA256: true });
+ * calculator.update(dataChunk);
+ * const crc32 = calculator.finalizeCRC32();
+ * const sha256 = calculator.finalizeSHA256();
+ * ```
+ *
+ * Hash accumulation:
+ * ```typescript
+ * const calculator = new HashCalculator({ enableAccumulation: true });
+ * calculator.addHash(sha256Hash1);
+ * calculator.addHash(sha256Hash2);
+ * const xor = calculator.xorHash();
+ * const merkle = calculator.merkleRoot();
+ * ```
+ */
+export declare class HashCalculator {
+    private crc32State;
+    private sha256Hash;
+    private useSHA256;
+    private hashes;
+    private xorResult;
+    private enableAccumulation;
+    private merkleLeaves;
+    private merkleLayers;
+    private merkleOptions;
+    /**
+     * Creates a new HashCalculator instance
+     * @param options - Configuration options:
+     *   - useSHA256: Enable SHA-256 calculation for incremental mode (default: false)
+     *   - enableAccumulation: Enable hash accumulation mode (default: false)
+     */
+    constructor(options?: {
+        useSHA256?: boolean;
+        enableAccumulation?: boolean;
+    });
+    /**
+     * Update hash state with a new chunk of data
+     * Updates both CRC-32 and SHA-256 (if enabled) incrementally
+     * @param chunk - Data chunk to process
+     */
+    update(chunk: Buffer): void;
+    /**
+     * Get final CRC-32 value
+     * @returns Final CRC-32 value as unsigned 32-bit integer
+     */
+    finalizeCRC32(): number;
+    /**
+     * Get final SHA-256 hash as hex string
+     * @returns SHA-256 hash as hex string, or null if SHA-256 not enabled
+     */
+    finalizeSHA256(): string | null;
+    /**
+     * Reset the incremental hash calculation state
+     */
+    reset(): void;
+    /**
+     * Adds a pre-computed SHA-256 hash to both the XOR accumulation and hash array
+     * @param hash - Hash value as hex string or Buffer (must be 32 bytes for SHA-256)
+     */
+    addHash(hash: string | Buffer): void;
+    /**
+     * Gets the accumulated XOR of all added hashes
+     * @returns Hex string of XOR result
+     */
+    xorHash(): string;
+    /**
+     * Creates a Merkle tree from accumulated hashes and returns the root
+     * @returns Hex string of Merkle root, or null if no hashes added
+     */
+    merkleRoot(): string | null;
+    /**
+     * Gets the number of hashes accumulated
+     * @returns Number of accumulated hashes
+     */
+    leafCount(): number;
+    /**
+     * Clears the accumulated hashes and resets XOR buffer
+     */
+    clear(): void;
+    /**
+     * Combines multiple hash results into a single Merkle root
+     * Static method for combining results from multiple HashCalculator instances
+     * @param results - Array of objects containing merkleRoot properties
+     * @returns Combined Merkle root as hex string, or null if no valid roots
+     */
+    static combineResults(results: {
+        merkleRoot?: string;
+    }[]): string | null;
+    /**
+     * Computes SHA-256 hash of input data
+     * @param data - Data to hash
+     * @returns Buffer containing hash
+     */
+    private hash;
+    /**
+     * Combines two child hashes to create parent hash
+     * @param left - Left child hash
+     * @param right - Right child hash
+     * @returns Combined hash of children
+     */
+    private combinedHash;
+    /**
+     * Builds the Merkle tree by creating successive layers of hashes
+     * @param nodes - Array of nodes in current layer
+     */
+    private createHashes;
+    /**
+     * Rebuilds the Merkle tree from current leaves
+     */
+    private rebuildMerkleTree;
+    /**
+     * Generates a proof of inclusion for a leaf node
+     * @param leaf - The leaf node to generate proof for
+     * @returns Array of sibling hashes needed to reconstruct root
+     * @throws Error if leaf not found in tree or accumulation not enabled
+     */
+    getProof(leaf: Buffer): Buffer[];
+    /**
+     * Verifies a proof of inclusion for a leaf node
+     * @param proof - Array of sibling hashes from getProof()
+     * @param targetHash - Hash of the leaf node being verified
+     * @param root - Expected root hash
+     * @returns boolean indicating if proof is valid
+     */
+    verify(proof: Buffer[], targetHash: Buffer, root: Buffer): boolean;
+}
+export default HashCalculator;
+//# sourceMappingURL=HashCalculator.d.ts.map

package/dist/core/components/HashCalculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HashCalculator.d.ts","sourceRoot":"","sources":["../../../src/core/components/HashCalculator.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,cAAc;IAEzB,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,SAAS,CAAkB;IAGnC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,kBAAkB,CAAkB;IAG5C,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,aAAa,CAKnB;IAEF;;;;;OAKG;gBACS,OAAO,CAAC,EAAE;QACpB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,kBAAkB,CAAC,EAAE,OAAO,CAAC;KAC9B;IAaD;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAY3B;;;OAGG;IACH,aAAa,IAAI,MAAM;IAIvB;;;OAGG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAO/B;;OAEG;IACH,KAAK,IAAI,IAAI;IAWb;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAuBpC;;;OAGG;IACH,OAAO,IAAI,MAAM;IAOjB;;;OAGG;IACH,UAAU,IAAI,MAAM,GAAG,IAAI;IAsB3B;;;OAGG;IACH,SAAS,IAAI,MAAM;IAOnB;;OAEG;IACH,KAAK,IAAI,IAAI;IAUb;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,MAAM,GAAG,IAAI;IAiBxE;;;;OAIG;IACH,OAAO,CAAC,IAAI;IAIZ;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAOpB;;;OAGG;IACH,OAAO,CAAC,YAAY;IA8BpB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsBzB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IA2BhC;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;CAWnE;AAGD,eAAe,cAAc,CAAC"}