genome 0.1.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Valtio Universe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

package/README.md

@@ -1,153 +1,286 @@
+![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)
+![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
 
-Simple build system using ES6 classes, generators, and promises
+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
-genome requires io.js or node.js with harmony flags.
 
-```
-npm i -g genome
-npm i -save-dev genome
+```bash
+pnpm add genome
 ```
 
-## Usage
-Create a `genomefile.js` in your project's root directory.
+## 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
 
-```javascript
-var genome = require('genome');
+// 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)
 
-genome.tasks = {
-  // Tasks go here
-};
+// Get info for a compact id
+const {
+  id,         // cd76ea96
+  levels,     // 3
+  collisions  // 0     ID collisions - same object structure already ran through generator
+} = getCompactInfo(user)
 
-// Run tasks passed in from command line
-genome.run();
+// get all of the data being stored about the state - debugging info
+const allStructureStateData = exportStructureState()
 ```
 
-### Create tasks
-Tasks in genome are generator functions. Task names may include colons (:) and/or hyphens (-).
+## API Reference
 
-```javascript
-* sayhi() {
-  console.log('Hello, world');
-},
+### `generateStructureId(obj: Record<string, any>, config?: StructureIdConfig): string`
 
-* 'say-something-else'() {
-  console.log('Something else');
-},
+Generates a unique ID string based on the structure of the provided object.
 
-* 'say:goodbye'() {
-  console.log('See ya later');
-}
-```
+- **Parameters**:
+  - `obj`: The object to generate an ID for.
+  - `config` (optional): Configuration options for ID generation.
+- **Returns**: A string representing the structure ID.
 
-### Run tasks
-In your command line, run:
+### `getStructureInfo(obj: Record<string, any>, config?: StructureIdConfig): { id: string; levels: number; collisionCount: number; }`
 
-```
-genome sayhi
-```
+Provides additional information about the object's structure.
 
-genome commands may accept multiple tasks to run asyncronously:
+- **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.
 
-```
-genome sayhi say-something-else say:goodbye
-```
+### `setStructureIdConfig(config: StructureIdConfig): void`
 
-Run a task from within another task using `genome.spawn()`.
+Sets global configuration options for structure ID generation.
 
-```javascript
-* speak() {
-  genome.spawn('sayhi');
+- **Parameters**:
+  - `config`: The configuration object.
 
-  // Or use genome's shorthand methods:
-  genome.sayhi();
-}
-```
+### `getStructureIdConfig(): StructureIdConfig`
+
+Gets the current global configuration.
 
-`genome.spawn()` accepts strings and arrays. Arrays of tasks will be run asyncronously.
+- **Returns**: A copy of the current global configuration object.
 
-```javascript
-* speak1() {
-  genome.spawn(['sayhi', 'say-something-else', 'say:goodbye']);
-},
+### `resetState(): void`
 
-// Is the same as:
+Resets the internal state of the library, clearing all cached property mappings.
 
-* speak2() {
-  genome.spawn('sayhi');
-  genome.spawn('say-something-else');
-  genome.spawn('say:goodbye');
+**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;
 }
 ```
 
-If you need tasks to run in a certain order, add the yield statement before calling `genome.spawn()`.
+#### `newIdOnCollision` (default: `false`)
 
-```javascript
-* speak2() {
-  yield genome.spawn('sayhi');
-  yield genome.spawn('say-something-else');
-  genome.spawn('say:goodbye');
-}
+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 };
+
+const obj1 = { name: "John", age: 30 };
+const obj2 = { name: "Alice", age: 25 };
+
+const id1 = generateStructureId(obj1, config);
+const id2 = generateStructureId(obj2, config);
+
+console.log(id1); // "L0:0-L1:5"
+console.log(id2); // "L0:1-L1:5"
+console.log(id1 === id2); // false (even though structure is identical)
 ```
 
-### Read/write files
-Genome adds `read()` and `write()` methods to strings to make reading and writing files as easy as:
+You can set this option globally or per call:
+
+```typescript
+// Set globally
+setStructureIdConfig({ newIdOnCollision: true });
 
-```javascript
-return 'dist/html.index'.write(yield 'app/html.index'.read());
+// Will use global config
+const id1 = generateStructureId(obj1);
+const id2 = generateStructureId(obj2);
+
+// Override for a specific call
+const id3 = generateStructureId(obj3, { newIdOnCollision: false });
 ```
 
-Genome also adds a `.contents` property as a read/write shorthand, so the same code can be written as:
+## 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
 
-```javascript
-'dist/html.index'.contents = yield 'app/html.index'.contents;
+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.
+
+```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));
 ```
 
-Not that `read()`, `write()` and the `.contents` *getter* all return promises, but the `.contents` *setter*
-does not return anything. So if you need the file to be written *before* something else happens, use `write()`.
+### Memoization and Caching
 
-`.write()` accepts strings, promises, streams and arrays of file objects.
+When implementing memoization patterns, you can use structure-based IDs to cache results based on input structure rather than identity:
 
-### Processing files
-Genome does not require plugins like gulp or grunt. Simply install standard node packages and use their
-build-in api.
+```ts
+const memoizedResults = new Map<string, any>();
 
-```javascript
-* html() {
-  // Process one file and output it
-  var slm = require('slm');
+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;
+}
+```
 
-  return 'dist/index.html'.write(slm.render(yield 'app/index.slm'.contents));
-},
+### Normalizing Data for Storage
 
-* scripts() {
-  // Output stream to file
-  var browserify = require('browserify');
+When storing objects in databases or state management systems, you can use structural IDs to create consistent references:
 
-  return 'dist/scripts/app.js'.write(browserify('app/scripts/app.js', { transform: 'babelify' }).bundle());
-},
+```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;
+}
+```
 
-* styles() {
-  // Output multiple files to directory with the String.prototype.use method
-  var stylus = require('stylus');
+### Change detection
 
-  return 'dist/styles/'.write(yield 'app/styles/*.styl'.use(stylus.render, '.css'));
+Detect changes in object structure without relying on reference equality:
+
+```ts
+function hasStructuralChanges(oldObj: object, newObj: object): boolean {
+  return generateStructureId(oldObj) !== generateStructureId(newObj);
 }
 ```
 
-### Watch files
-Watch files for changes with String.prototype.onChange, passing in a function or a task name or array of task names.
+### Object Deduplication
+
+Efficiently identify and remove duplicate objects with identical structures:
+
+```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());
+}
+```
 
-```javascript
-* watch() {
-  'app/**/*.slm'.onChange('html');
-  'app/scripts/**/*.js'.onChange('scripts');
-  'app/styles/**/*.styl'.onChange('styles');
-  'dist/**/*'.onChange(browserSync.reload);
+### 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;
 }
 ```
+### 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
 
-## Project Goals
-- Never require speciallized plugins like Gulp and Grunt
-- Keep code as simple and natural as possible
+MIT

package/dist/hash.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Fast, non-cryptographic hash functions for structure ID generation
+ * @module @synpatico/genome/hash
+ */
+/**
+ * Available hash function implementations
+ */
+export declare const hashFunction: {
+    readonly MURMUR: typeof murmurHash3;
+    readonly XXHASH: typeof xxHash32;
+};
+/**
+ * Type representing available hash functions
+ */
+export type HashFunction = (typeof hashFunction)[keyof typeof hashFunction];
+/**
+ * Options for hash function selection
+ */
+type HashFunctionProps = {
+    /** Built-in hash function to use */
+    type?: HashFunction;
+    /** Custom hash function implementation */
+    custom?: (str: string) => string;
+};
+/**
+ * Generates a hash from a string using the specified algorithm.
+ * Defaults to xxHash32 for optimal performance.
+ *
+ * @param str - The string to hash
+ * @param options - Optional hash function configuration
+ * @returns A hexadecimal hash string
+ *
+ * @example
+ * ```javascript
+ * // Using default xxHash32
+ * const h1 = hash("hello"); // "884863d4"
+ *
+ * // Using MurmurHash3
+ * const h2 = hash("hello", { type: hashFunction.MURMUR }); // "613cae7d"
+ *
+ * // Using custom function
+ * const h3 = hash("hello", { custom: (s) => s.length.toString() }); // "5"
+ * ```
+ */
+export declare const hash: (str: string, options?: HashFunctionProps) => string;
+/**
+ * MurmurHash3 implementation - fast non-cryptographic hash function.
+ * Provides good distribution and collision resistance for hash tables.
+ *
+ * @param str - The string to hash
+ * @returns A hexadecimal hash string
+ *
+ * @example
+ * ```javascript
+ * const hash = murmurHash3("hello world");
+ * console.log(hash); // "5e928f0f"
+ * ```
+ */
+export declare function murmurHash3(str: string): string;
+/**
+ *
+ * @param input - byte array or string
+ * @param seed - optional seed (32-bit unsigned);
+ */
+export declare function xxHash32(input: Uint8Array | string, seed?: number): string;
+export {};
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY;;;CAGf,CAAA;AAEV;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAA;AAE3E;;GAEG;AACH,KAAK,iBAAiB,GAAG;IACxB,oCAAoC;IACpC,IAAI,CAAC,EAAE,YAAY,CAAA;IACnB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAA;CAChC,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,EAAE,UAAU,iBAAiB,KAAG,MAU/D,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAyD/C;AAsBD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE,IAAI,SAAI,GAAG,MAAM,CA2KrE"}

package/dist/id-indexhash.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Order-preserving structure ID generator that avoids GLOBAL_KEY_MAP growth
+ * from array indices and lengths by hashing numeric values directly.
+ *
+ * This mirrors the current generateStructureId algorithm with one change:
+ * - For arrays, we compute index/length contributions via numeric hashing
+ *   (fixed seeds) instead of storing strings like "[i]" and "length:n"
+ *   in GLOBAL_KEY_MAP. Property names still use GLOBAL_KEY_MAP.
+ */
+import { type StructureIdConfig } from "./index";
+/**
+ * Generate a structure ID while avoiding GLOBAL_KEY_MAP growth from array indices/lengths.
+ * Property names still use GLOBAL_KEY_MAP like the current implementation.
+ */
+export declare const generateStructureIdIndexHash: (obj: unknown, config?: StructureIdConfig) => string;
+export declare function getStructureInfoIndexHash(obj: unknown, config?: StructureIdConfig): {
+    id: string;
+    levels: number;
+    collisionCount: number;
+};
+//# sourceMappingURL=id-indexhash.d.ts.map

package/dist/id-indexhash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-indexhash.d.ts","sourceRoot":"","sources":["../src/id-indexhash.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAML,KAAK,iBAAiB,EACvB,MAAM,SAAS,CAAA;AA8DhB;;;GAGG;AACH,eAAO,MAAM,4BAA4B,GACvC,KAAK,OAAO,EACZ,SAAS,iBAAiB,KACzB,MAuHF,CAAA;AAED,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,OAAO,EACZ,MAAM,CAAC,EAAE,iBAAiB,GACzB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAUxD"}

package/dist/id-multiset.d.ts

@@ -0,0 +1,6 @@
+export declare function generateStructureIdMultiset(obj: unknown): string;
+export declare function getStructureInfoMultiset(obj: unknown): {
+    id: string;
+    levels: number;
+};
+//# sourceMappingURL=id-multiset.d.ts.map

package/dist/id-multiset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-multiset.d.ts","sourceRoot":"","sources":["../src/id-multiset.ts"],"names":[],"mappings":"AAgCA,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAyEhE;AAGD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAGrF"}

package/dist/id-multiset32.d.ts

@@ -0,0 +1,2 @@
+export declare function generateStructureIdMultiset32(obj: unknown): string;
+//# sourceMappingURL=id-multiset32.d.ts.map

package/dist/id-multiset32.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-multiset32.d.ts","sourceRoot":"","sources":["../src/id-multiset32.ts"],"names":[],"mappings":"AAwCA,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAiElE"}