genome 1.0.0 → 1.0.3

package/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,286 +1,97 @@
 ![NPM Version](https://img.shields.io/npm/v/genome?style=flat-square&color=%23e8b339)
-![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/overthemike/genome/test.yml?style=flat-square&color=%23e8b339)
+![Crates.io Version](https://img.shields.io/crates/v/genome-rs?style=flat-square&color=%23e8b339)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/overthemike/genome/ci.yml?style=flat-square&color=%23e8b339)
 ![npm bundle size](https://img.shields.io/bundlephobia/minzip/genome?style=flat-square&color=%23e8b339)
 ![NPM License](https://img.shields.io/npm/l/genome?style=flat-square&color=%23e8b339)
+# `genome`
 
+Deterministic structural hashing for JSON values. Generates hierarchical 
+IDs that capture the shape of an object — same structure, same ID, 
+regardless of values.
 
-# genome
-
-A lightweight, robust library for generating unique identifiers for JavaScript/TypeScript objects based on their structure rather than requiring explicit string keys.
-
-## Purpose
-
-This library provides a solution for scenarios where you need to:
-
-- Persist and rehydrate state without requiring explicit string keys
-- Identify structurally identical objects across different instances
-- Match objects by their shape rather than by identity or manual keys
-- Detect circular references safely
-
-## Installation
+## Install
 
+**[npm (WASM) ↗](https://www.npmjs.com/package/genome)**
 ```bash
-pnpm add genome
-```
-
-## Basic Usage
-```typescript
-import { generateStructureId, getCompactId } from 'genome';
-
-// Example object
-const user = {
-  name: 'John',
-  age: 30,
-  preferences: {
-    theme: 'dark',
-    notifications: true
-  }
-}
-
-// Generate a unique ID based on the object structure and it's properties' types
-const id = generateStructureId(user) // L0:3713-L1:5761-L2:13827
-
-// Generate a unique ID and then hash that value
-const hashed = getCompactId(user) // cd76ea96
-
-// Get info on what a structure would be without generating
-const {
-  id,         // L0:541598767187353870402585606-L1:1547425049106725343623905933-L2:10
-  levels,     // 3
-  collisions  // 0     ID collisions - same object structure already ran through generator
-} = getStructureInfo(user)
-
-// Get info for a compact id
-const {
-  id,         // cd76ea96
-  levels,     // 3
-  collisions  // 0     ID collisions - same object structure already ran through generator
-} = getCompactInfo(user)
-
-// get all of the data being stored about the state - debugging info
-const allStructureStateData = exportStructureState()
+npm install genome
 ```
 
-## API Reference
-
-### `generateStructureId(obj: Record<string, any>, config?: StructureIdConfig): string`
-
-Generates a unique ID string based on the structure of the provided object.
-
-- **Parameters**:
-  - `obj`: The object to generate an ID for.
-  - `config` (optional): Configuration options for ID generation.
-- **Returns**: A string representing the structure ID.
-
-### `getStructureInfo(obj: Record<string, any>, config?: StructureIdConfig): { id: string; levels: number; collisionCount: number; }`
-
-Provides additional information about the object's structure.
-
-- **Parameters**:
-  - `obj`: The object to analyze.
-  - `config` (optional): Configuration options for ID generation.
-- **Returns**: An object containing:
-  - `id`: The structure ID.
-  - `levels`: The number of nesting levels in the object.
-  - `collisionCount`: The number of times this structure has been encountered.
-
-### `setStructureIdConfig(config: StructureIdConfig): void`
-
-Sets global configuration options for structure ID generation.
-
-- **Parameters**:
-  - `config`: The configuration object.
-
-### `getStructureIdConfig(): StructureIdConfig`
-
-Gets the current global configuration.
-
-- **Returns**: A copy of the current global configuration object.
-
-### `resetState(): void`
-
-Resets the internal state of the library, clearing all cached property mappings.
-
-**Note**: You typically don't need to call this unless you want to start fresh with property-to-bit mappings.
-
-### Configuration Options
-
-The `StructureIdConfig` object supports the following options:
-
-```typescript
-interface StructureIdConfig {
-  newIdOnCollision?: boolean;
-}
+**[Rust ↗](https://crates.io/crates/genome-rs)**
+```toml
+[dependencies]
+genome = "1.0.0"
 ```
 
-#### `newIdOnCollision` (default: `false`)
+## Usage
 
-When set to `true`, each object with the same structure will receive a unique ID. This is useful when you need to distinguish between different object instances that share the same structure.
-
-```typescript
-// Generate a unique ID for each object, even with the same structure
-const config = { newIdOnCollision: true };
+**TypeScript / JavaScript**
+```ts
+import init, { hash, signature, compare, compareValues, setConfig, reset } from 'genome'
 
-const obj1 = { name: "John", age: 30 };
-const obj2 = { name: "Alice", age: 25 };
+// `init()` loads and compiles the WASM binary — call it once before using any other functions.
+await init()
 
-const id1 = generateStructureId(obj1, config);
-const id2 = generateStructureId(obj2, config);
+const id = hash(JSON.stringify({ id: 1, name: "alice" }))
+const score = compare(id1, id2)
 
-console.log(id1); // "L0:0-L1:5"
-console.log(id2); // "L0:1-L1:5"
-console.log(id1 === id2); // false (even though structure is identical)
+// setConfig(newIdOnCollision, ignoreArrayLength, ignoreValueTypes)
+setConfig(false, true, false)
 ```
 
-You can set this option globally or per call:
+**Rust**
+```rust
+use genome::{Genome, GenomeConfig};
+use serde_json::json;
 
-```typescript
-// Set globally
-setStructureIdConfig({ newIdOnCollision: true });
+let mut g = Genome::new(GenomeConfig::default());
 
-// Will use global config
-const id1 = generateStructureId(obj1);
-const id2 = generateStructureId(obj2);
+let id1 = g.hash(&json!({ "id": 1, "name": "alice" }));
+let id2 = g.hash(&json!({ "id": 2, "name": "bob" }));
 
-// Override for a specific call
-const id3 = generateStructureId(obj3, { newIdOnCollision: false });
+assert_eq!(id1, id2); // same structure
 ```
 
-## When to use `genome`
-
-The `genome` library shines in scenarios where you need to identify and match objects based on their structure rather than explicit keys or instance identity. Here are some ideal use cases:
-
-### State Management Without Explicit Keys
+## Config
 
-When persisting and rehydrating application state, you often need a way to match stored state with the corresponding objects in your application. Instead of manually maintaining string keys for every object, `genome` automatically generates consistent identifiers based on object structure.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `newIdOnCollision` | bool | false | Give structurally identical values distinct IDs |
+| `ignoreArrayLength` | bool | false | Treat arrays with different lengths but same element shapes as equivalent |
+| `ignoreValueTypes` | bool | false | Treat all scalar types as equivalent — only key names and depth matter |
 
-```ts
-// Instead of this:
-const componentKey = "user-preferences-panel";
-storeState(componentKey, preferences);
-// Later:
-const savedState = getState(componentKey);
-
-// You can do this:
-const structureId = generateStructureId(preferences);
-storeState(structureId, preferences);
-// Later:
-const savedState = getState(generateStructureId(preferences));
-```
+## API
 
-### Memoization and Caching
+### `hash(json)`
+Accepts a JSON string. Use `JSON.stringify()` before passing.
 
-When implementing memoization patterns, you can use structure-based IDs to cache results based on input structure rather than identity:
+### `signature(value)`
+Returns the structural fingerprint. In default mode returns the full ID. 
+When `newIdOnCollision` is true, strips L0 and returns L1+ only.
 
-```ts
-const memoizedResults = new Map<string, any>();
-
-function expensiveCalculation(data: SomeComplexObject) {
-  const structureId = generateStructureId(data);
-  
-  if (memoizedResults.has(structureId)) {
-    return memoizedResults.get(structureId);
-  }
-  
-  const result = /* complex calculation */;
-  memoizedResults.set(structureId, result);
-  return result;
-}
-```
-
-### Normalizing Data for Storage
-
-When storing objects in databases or state management systems, you can use structural IDs to create consistent references:
-
-```ts
-function normalizeForStorage(entities: Record<string, unknown>[]) {
-  const normalizedEntities: Record<string, any> = {};
-  
-  for (const entity of entities) {
-    const id = generateStructureId(entity);
-    normalizedEntities[id] = entity;
-  }
-  
-  return normalizedEntities;
-}
-```
+### `compare(idA, idB) → number`
+Compares two structure IDs and returns a similarity score from 0.0 to 1.0.
 
-### Change detection
+### `compareValues(a, b)`
+Compares two JSON strings structurally.
 
-Detect changes in object structure without relying on reference equality:
+### `seed(sig, count)`
+Seeds the collision counter for a known signature. Useful for restoring persisted state.
 
-```ts
-function hasStructuralChanges(oldObj: object, newObj: object): boolean {
-  return generateStructureId(oldObj) !== generateStructureId(newObj);
-}
-```
+### `reset()`
+Clears all internal state.
 
-### Object Deduplication
+## How it works
 
-Efficiently identify and remove duplicate objects with identical structures:
+genome builds a hierarchical hash where each level (`L0`, `L1`, `L2`...) 
+represents a depth in the object tree. Two objects with the same keys, 
+same nesting structure, and same value types will always produce the same ID 
+regardless of the actual values stored.
 
-```ts
-function deduplicateByStructure<T>(objects: T[]): T[] {
-  const uniqueStructures = new Map<string, T>();
-  
-  for (const obj of objects) {
-    const id = generateStructureId(obj as Record<string, unknown>);
-    if (!uniqueStructures.has(id)) {
-      uniqueStructures.set(id, obj);
-    }
-  }
-  
-  return Array.from(uniqueStructures.values());
-}
 ```
-
-### Unique Per-Instance IDs
-
-When you need to uniquely identify each object instance, even if they share the same structure, you can use the `newIdOnCollision` option:
-
-```ts
-function assignUniqueIds<T>(objects: T[]): Map<T, string> {
-  const idMap = new Map<T, string>();
-  const config = { newIdOnCollision: true };
-  
-  for (const obj of objects) {
-    const id = generateStructureId(obj as Record<string, unknown>, config);
-    idMap.set(obj, id);
-  }
-  
-  return idMap;
-}
+{ id: 1, name: "alice", address: { city: "NYC" } }
+  └── L0: root level  (keys: id, name, address + their types)
+  └── L1: depth 1     (keys inside address: city + its type)
 ```
-### Benefits Over Manual Key Management
-
-- Automatic: No need to manually specify and maintain string keys
-- Consistent: Same structure always generates the same ID
-- Structural: Changes to object structure are automatically reflected in the ID
-- Safe: Handles circular references without issues
-- Deterministic: Property order doesn't affect the generated ID
-
-## How It Works
-
-The library uses a bit-wise approach to generate structure IDs:
-
-1. Each JavaScript type gets a unique bit value (`number`, `string`, `object`, etc.)
-2. Each property name gets a unique bit value the first time it's encountered
-3. These bit values are consistently used for the same types and property names
-4. The object is traversed, and hash values are calculated for each level of nesting
-5. The final ID is formed by combining these level hashes
-
-This approach ensures:
-- Identical structures get identical IDs
-- Different structures get different IDs
-- The algorithm works correctly with circular references
-- Property order doesn't affect the generated ID
-
-## Performance Considerations
-
-- The library maintains a global mapping of property names to bit values, which grows as more unique property names are encountered
-- For very large or complex objects, the bit values might become quite large (using BigInt internally)
-- Circular references are handled efficiently without stack overflows
 
 ## License
-
-MIT
+MIT

package/genome_rs.d.ts

@@ -0,0 +1,93 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Compares two structure ID strings and returns a similarity score
+ * between 0.0 (completely different) and 1.0 (identical).
+ *
+ * ```js
+ * import { compare } from 'genome'
+ * const score = compare("L0:100-L1:200", "L0:100-L1:200") // 1.0
+ * ```
+ */
+export function compare(id_a: string, id_b: string): number;
+
+/**
+ * Compares two JSON strings structurally and returns a similarity score.
+ *
+ * ```js
+ * import { compareValues } from 'genome'
+ * const score = compareValues(
+ *   JSON.stringify({ id: 1, name: "alice" }),
+ *   JSON.stringify({ id: 2, name: "bob" }),
+ * ) // 1.0 — same structure
+ * ```
+ */
+export function compareValues(a: string, b: string): number;
+
+/**
+ * Generates a deterministic hierarchical structure ID for a JSON string.
+ *
+ * ```js
+ * import { hash } from 'genome'
+ * const id = hash(JSON.stringify({ id: 1, name: "alice" }))
+ * ```
+ */
+export function hash(json: string): string;
+
+/**
+ * Hashes a string with xxHash32 and returns a hex string.
+ *
+ * ```js
+ * import { hashStr } from 'genome'
+ * const hex = hashStr("hello", 0)
+ * ```
+ */
+export function hashStr(input: string, seed: number): string;
+
+/**
+ * Resets all internal state — clears the key cache and collision counters.
+ *
+ * ```js
+ * import { reset } from 'genome'
+ * reset()
+ * ```
+ */
+export function reset(): void;
+
+/**
+ * Seeds the collision counter for a known signature.
+ * Use this to restore persisted counter state.
+ *
+ * ```js
+ * import { seed } from 'genome'
+ * seed("L1:12345-L2:67890", 3n)
+ * ```
+ */
+export function seed(signature: string, count: bigint): void;
+
+/**
+ * Sets the global config. Call this before using any other functions
+ * if you need non-default behaviour.
+ *
+ * ```js
+ * import { setConfig, hash } from 'genome'
+ *
+ * setConfig({ ignoreArrayLength: true, ignoreValueTypes: true })
+ * const id = hash(JSON.stringify({ items: [1, 2, 3] }))
+ * ```
+ */
+export function setConfig(new_id_on_collision: boolean, ignore_array_length: boolean, ignore_value_types: boolean): void;
+
+/**
+ * Returns the structural signature for a JSON string.
+ *
+ * In default mode returns the full ID. When `newIdOnCollision` is true
+ * (set via `setConfig`), strips L0 and returns L1+ only.
+ *
+ * ```js
+ * import { signature } from 'genome'
+ * const sig = signature(JSON.stringify({ id: 1, name: "alice" }))
+ * ```
+ */
+export function signature(json: string): string;

package/genome_rs.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./genome_rs.d.ts" */
+
+import * as wasm from "./genome_rs_bg.wasm";
+import { __wbg_set_wasm } from "./genome_rs_bg.js";
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();
+export {
+    compare, compareValues, hash, hashStr, reset, seed, setConfig, signature
+} from "./genome_rs_bg.js";