@iscc/wasm 0.0.2

package/README.md

@@ -0,0 +1,79 @@
+# @iscc/wasm
+
+[![CI](https://github.com/iscc/iscc-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/iscc/iscc-lib/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@iscc/wasm.svg)](https://www.npmjs.com/package/@iscc/wasm)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+> **Experimental:** This library is in early development (v0.0.x). APIs may change without notice.
+> Not recommended for production use yet.
+
+Browser-compatible WebAssembly bindings for
+[ISO 24138:2024](https://www.iso.org/standard/77899.html) -- International Standard Content Code
+(ISCC). Built with Rust and [wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/) for use in
+browsers and Node.js.
+
+## What is ISCC
+
+The ISCC is a similarity-preserving fingerprint and identifier for digital media assets. ISCCs are
+generated algorithmically from digital content, just like cryptographic hashes. However, instead of
+using a single cryptographic hash function to identify data only, the ISCC uses various algorithms
+to create a composite identifier that exhibits similarity-preserving properties (soft hash).
+
+## Installation
+
+```bash
+npm install @iscc/wasm
+```
+
+## Quick Start
+
+```javascript
+import init, {
+    gen_meta_code_v0
+} from "@iscc/wasm";
+
+await init();
+const iscc = gen_meta_code_v0("ISCC Test Document!");
+console.log(`Meta-Code: ${iscc}`);
+```
+
+Both browser and Node.js targets are supported.
+
+## API Overview
+
+### Code Generators
+
+| Function               | Description                                  |
+| ---------------------- | -------------------------------------------- |
+| `gen_meta_code_v0`     | Generate a Meta-Code from metadata fields    |
+| `gen_text_code_v0`     | Generate a Text-Code from plain text         |
+| `gen_image_code_v0`    | Generate an Image-Code from pixel data       |
+| `gen_audio_code_v0`    | Generate an Audio-Code from Chromaprint data |
+| `gen_video_code_v0`    | Generate a Video-Code from frame signatures  |
+| `gen_mixed_code_v0`    | Generate a Mixed-Code from Content-Codes     |
+| `gen_data_code_v0`     | Generate a Data-Code from raw bytes          |
+| `gen_instance_code_v0` | Generate an Instance-Code from raw bytes     |
+| `gen_iscc_code_v0`     | Generate a composite ISCC-CODE               |
+
+All code generators return ISCC strings directly.
+
+### Utilities
+
+- **Text processing:** `text_clean`, `text_remove_newlines`, `text_trim`, `text_collapse`
+- **Algorithm primitives:** `alg_simhash`, `alg_minhash_256`, `alg_cdc_chunks`, `sliding_window`
+- **Soft hashing:** `soft_hash_video_v0`
+- **Encoding:** `encode_base64`
+- **Codec:** `iscc_decompose`
+- **Streaming:** `DataHasher`, `InstanceHasher` classes for incremental processing
+- **Diagnostics:** `conformance_selftest`
+
+## Links
+
+- [Documentation](https://lib.iscc.codes)
+- [Repository](https://github.com/iscc/iscc-lib)
+- [ISCC Specification (ISO 24138)](https://www.iso.org/standard/77899.html)
+- [ISCC Foundation](https://iscc.io)
+
+## License
+
+Apache-2.0

package/iscc_wasm.d.ts

@@ -0,0 +1,280 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Streaming Data-Code generator.
+ *
+ * Incrementally processes data with content-defined chunking and MinHash
+ * to produce results identical to `gen_data_code_v0`. Follows the
+ * `new() → update() → finalize()` pattern.
+ */
+export class DataHasher {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Consume the hasher and produce a Data-Code ISCC string.
+     *
+     * After calling `finalize`, subsequent calls to `update` or `finalize`
+     * will throw. Default `bits` is 64.
+     */
+    finalize(bits?: number | null): string;
+    /**
+     * Create a new `DataHasher`.
+     */
+    constructor();
+    /**
+     * Push data into the hasher.
+     */
+    update(data: Uint8Array): void;
+}
+
+/**
+ * Streaming Instance-Code generator.
+ *
+ * Incrementally hashes data with BLAKE3 to produce results identical
+ * to `gen_instance_code_v0`. Follows the
+ * `new() → update() → finalize()` pattern.
+ */
+export class InstanceHasher {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Consume the hasher and produce an Instance-Code ISCC string.
+     *
+     * After calling `finalize`, subsequent calls to `update` or `finalize`
+     * will throw. Default `bits` is 64.
+     */
+    finalize(bits?: number | null): string;
+    /**
+     * Create a new `InstanceHasher`.
+     */
+    constructor();
+    /**
+     * Push data into the hasher.
+     */
+    update(data: Uint8Array): void;
+}
+
+/**
+ * Split data into content-defined chunks using gear rolling hash.
+ *
+ * Returns a JS array of `Uint8Array` chunks. At least one chunk is always
+ * returned (empty bytes for empty input). When `utf32` is true, aligns cut
+ * points to 4-byte boundaries. Default `avg_chunk_size` is 1024.
+ */
+export function alg_cdc_chunks(data: Uint8Array, utf32: boolean, avg_chunk_size?: number | null): any;
+
+/**
+ * Compute a 256-bit MinHash digest from 32-bit integer features.
+ *
+ * Uses 64 universal hash functions with bit-interleaved compression to
+ * produce a 32-byte similarity-preserving digest.
+ */
+export function alg_minhash_256(features: Uint32Array): Uint8Array;
+
+/**
+ * Compute a SimHash from a sequence of equal-length hash digests.
+ *
+ * Accepts a JS array of `Uint8Array` values. Returns a similarity-preserving
+ * hash whose length matches the input digest length. Returns 32 zero bytes
+ * for empty input. Throws on mismatched digest lengths.
+ */
+export function alg_simhash(hash_digests: any): Uint8Array;
+
+/**
+ * Encode bytes as base64url (RFC 4648 §5, no padding).
+ *
+ * Returns a URL-safe base64 encoded string without padding characters.
+ */
+export function encode_base64(data: Uint8Array): string;
+
+/**
+ * Generate an Audio-Code from a Chromaprint feature vector.
+ *
+ * Produces an ISCC Content-Code for audio from signed integer
+ * Chromaprint fingerprint features using multi-stage SimHash.
+ */
+export function gen_audio_code_v0(cv: Int32Array, bits?: number | null): string;
+
+/**
+ * Generate a Data-Code from raw byte data.
+ *
+ * Produces an ISCC Data-Code by splitting data into content-defined
+ * chunks and applying MinHash for similarity hashing.
+ */
+export function gen_data_code_v0(data: Uint8Array, bits?: number | null): string;
+
+/**
+ * Generate an Image-Code from pixel data.
+ *
+ * Produces an ISCC Content-Code for images from 1024 grayscale pixels
+ * (32x32) using a DCT-based perceptual hash.
+ */
+export function gen_image_code_v0(pixels: Uint8Array, bits?: number | null): string;
+
+/**
+ * Generate an Instance-Code from raw byte data.
+ *
+ * Produces an ISCC Instance-Code by hashing the complete byte stream
+ * with BLAKE3. Returns the ISCC string with "ISCC:" prefix.
+ */
+export function gen_instance_code_v0(data: Uint8Array, bits?: number | null): string;
+
+/**
+ * Generate a composite ISCC-CODE from individual unit codes.
+ *
+ * Combines multiple ISCC unit codes into a single composite ISCC-CODE.
+ * Requires at least Data-Code and Instance-Code. Accepts a JS array of strings.
+ */
+export function gen_iscc_code_v0(codes: any, wide?: boolean | null): string;
+
+/**
+ * Generate a Meta-Code from name and optional metadata.
+ *
+ * Produces an ISCC Meta-Code by hashing the provided name, description,
+ * and metadata fields using the SimHash algorithm.
+ */
+export function gen_meta_code_v0(name: string, description?: string | null, meta?: string | null, bits?: number | null): string;
+
+/**
+ * Generate a Mixed-Code from multiple Content-Code strings.
+ *
+ * Produces a Mixed Content-Code by combining multiple ISCC Content-Codes
+ * of different types using SimHash. Accepts a JS array of strings.
+ */
+export function gen_mixed_code_v0(codes: any, bits?: number | null): string;
+
+/**
+ * Generate a Text-Code from plain text content.
+ *
+ * Produces an ISCC Content-Code for text using MinHash-based
+ * similarity hashing.
+ */
+export function gen_text_code_v0(text: string, bits?: number | null): string;
+
+/**
+ * Generate a Video-Code from frame signature data.
+ *
+ * Produces an ISCC Content-Code for video from MPEG-7 frame
+ * signature vectors using WTA-Hash. Accepts a JS array of arrays of i32.
+ */
+export function gen_video_code_v0(frame_sigs: any, bits?: number | null): string;
+
+/**
+ * Decompose a composite ISCC-CODE into individual ISCC-UNITs.
+ *
+ * Accepts a normalized ISCC-CODE or concatenated ISCC-UNIT sequence.
+ * The optional "ISCC:" prefix is stripped before decoding.
+ * Returns an array of base32-encoded ISCC-UNIT strings (without prefix).
+ */
+export function iscc_decompose(iscc_code: string): string[];
+
+/**
+ * Generate sliding window n-grams from a string.
+ *
+ * Returns overlapping substrings of `width` Unicode characters, advancing
+ * by one character at a time. Throws if width is less than 2.
+ */
+export function sliding_window(seq: string, width: number): string[];
+
+/**
+ * Compute a similarity-preserving hash from video frame signatures.
+ *
+ * Accepts a JS array of arrays of `i32`. Returns raw bytes of length
+ * `bits / 8`. Default `bits` is 64. Throws if `frame_sigs` is empty.
+ */
+export function soft_hash_video_v0(frame_sigs: any, bits?: number | null): Uint8Array;
+
+/**
+ * Clean and normalize text for display.
+ *
+ * Applies NFKC normalization, removes control characters (except newlines),
+ * normalizes `\r\n` to `\n`, collapses consecutive empty lines, and strips
+ * leading/trailing whitespace.
+ */
+export function text_clean(text: string): string;
+
+/**
+ * Normalize and simplify text for similarity hashing.
+ *
+ * Applies NFD normalization, lowercasing, removes whitespace and characters
+ * in Unicode categories C (control), M (mark), and P (punctuation), then
+ * recombines with NFKC normalization.
+ */
+export function text_collapse(text: string): string;
+
+/**
+ * Remove newlines and collapse whitespace to single spaces.
+ *
+ * Converts multi-line text into a single normalized line.
+ */
+export function text_remove_newlines(text: string): string;
+
+/**
+ * Trim text so its UTF-8 encoded size does not exceed `nbytes`.
+ *
+ * Multi-byte characters that would be split are dropped entirely.
+ * Leading/trailing whitespace is stripped from the result.
+ */
+export function text_trim(text: string, nbytes: number): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_datahasher_free: (a: number, b: number) => void;
+    readonly __wbg_instancehasher_free: (a: number, b: number) => void;
+    readonly alg_cdc_chunks: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly alg_minhash_256: (a: number, b: number, c: number) => void;
+    readonly alg_simhash: (a: number, b: number) => void;
+    readonly datahasher_finalize: (a: number, b: number, c: number) => void;
+    readonly datahasher_new: () => number;
+    readonly datahasher_update: (a: number, b: number, c: number, d: number) => void;
+    readonly encode_base64: (a: number, b: number, c: number) => void;
+    readonly gen_audio_code_v0: (a: number, b: number, c: number, d: number) => void;
+    readonly gen_data_code_v0: (a: number, b: number, c: number, d: number) => void;
+    readonly gen_image_code_v0: (a: number, b: number, c: number, d: number) => void;
+    readonly gen_instance_code_v0: (a: number, b: number, c: number, d: number) => void;
+    readonly gen_iscc_code_v0: (a: number, b: number, c: number) => void;
+    readonly gen_meta_code_v0: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+    readonly gen_mixed_code_v0: (a: number, b: number, c: number) => void;
+    readonly gen_text_code_v0: (a: number, b: number, c: number, d: number) => void;
+    readonly gen_video_code_v0: (a: number, b: number, c: number) => void;
+    readonly instancehasher_finalize: (a: number, b: number, c: number) => void;
+    readonly instancehasher_new: () => number;
+    readonly instancehasher_update: (a: number, b: number, c: number, d: number) => void;
+    readonly iscc_decompose: (a: number, b: number, c: number) => void;
+    readonly sliding_window: (a: number, b: number, c: number, d: number) => void;
+    readonly soft_hash_video_v0: (a: number, b: number, c: number) => void;
+    readonly text_clean: (a: number, b: number, c: number) => void;
+    readonly text_collapse: (a: number, b: number, c: number) => void;
+    readonly text_remove_newlines: (a: number, b: number, c: number) => void;
+    readonly text_trim: (a: number, b: number, c: number, d: number) => void;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export3: (a: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;