@rlabs-inc/fsdb 1.0.0

package/README.md

@@ -0,0 +1,358 @@
+# fsDB - Fractal State Database
+
+A reactive database with parallel arrays and fine-grained reactivity. Built on the **Father State Pattern** at every level.
+
+**F**ather **S**tate **DB** = **F**ractal **S**tate **DB**
+
+## Features
+
+- **Parallel Arrays** - One reactive array per field, not array of objects
+- **Fine-Grained Reactivity** - Update one field, only that field triggers
+- **Reactive Queries** - Queries auto-update when data changes
+- **Vector Search** - Cosine similarity with stale detection
+- **Markdown Persistence** - YAML frontmatter + body, human-readable
+- **File Watching** - External changes sync automatically
+- **Zero Global State** - Each database instance is isolated
+
+## Installation
+
+```bash
+bun add @rlabs-inc/fsdb
+```
+
+## Quick Start
+
+```typescript
+import { createDatabase, eq, gt, and, query, effect } from '@rlabs-inc/fsdb'
+
+// Create a database
+const db = createDatabase({ name: 'myapp' })
+
+// Create a collection with schema
+const users = db.collection('users', {
+  schema: {
+    name: 'string',
+    age: 'number',
+    email: 'string',
+    active: 'boolean',
+  }
+})
+
+// Insert records
+const id = users.insert({
+  name: 'Alice',
+  age: 30,
+  email: 'alice@example.com',
+  active: true,
+})
+
+// Query with filters
+const activeUsers = users.find(eq('active', true))
+const seniors = users.find(and(gt('age', 50), eq('active', true)))
+
+// Reactive queries - auto-update on changes
+const activeQuery = query(users, r => r.active)
+
+effect(() => {
+  console.log('Active count:', activeQuery.value.count)
+})
+
+// Updates trigger the effect above
+users.update(id, { active: false })
+```
+
+## The Father State Pattern
+
+Instead of storing records as objects (slow):
+
+```typescript
+// Traditional - array of objects
+const records = [
+  { id: '1', name: 'Alice', age: 30 },
+  { id: '2', name: 'Bob', age: 25 },
+]
+```
+
+We use parallel arrays indexed by a central registry (fast):
+
+```typescript
+// Father State Pattern - parallel arrays
+registry = { idToIndex: { '1': 0, '2': 1 } }
+names = ['Alice', 'Bob']
+ages  = [30, 25]
+```
+
+**Benefits:**
+- O(1) array access vs object property lookup
+- Better CPU cache locality
+- Fine-grained reactivity at field level
+- Minimal garbage collection
+
+## API Reference
+
+### Database
+
+```typescript
+import { createDatabase } from '@rlabs-inc/fsdb'
+
+// Global storage (default): ~/.fsdb/myapp/
+const db = createDatabase({ name: 'myapp' })
+
+// Project-local storage: ./.fsdb/myapp/
+const localDb = createDatabase({ name: 'myapp', local: true })
+
+// Custom path: /custom/path/
+const customDb = createDatabase({ basePath: '/custom/path' })
+
+// Create/get collections
+const users = db.collection('users', { schema: {...} })
+
+// List collections
+db.listCollections()
+
+// Cleanup
+db.close()
+```
+
+### Collections
+
+```typescript
+const users = db.collection('users', {
+  schema: {
+    name: 'string',
+    age: 'number',
+    score: 'number',
+    tags: 'string[]',
+    embedding: 'vector:384',  // 384-dimensional vector
+  },
+  contentColumn: 'bio',       // Stored as markdown body
+  autoSave: true,             // Auto-persist changes
+  watchFiles: true,           // Watch for external changes
+})
+
+// CRUD
+const id = users.insert({ name: 'Alice', age: 30 })
+const user = users.get(id)
+users.update(id, { age: 31 })
+users.updateField(id, 'score', 100)
+users.delete(id)
+
+// Querying
+const all = users.all()
+const found = users.find(filter)
+const first = users.findOne(filter)
+const count = users.count(filter)
+
+// Persistence (if path configured)
+await users.load()
+await users.save()
+
+// File watching
+users.startWatching()
+users.stopWatching()
+users.onFileChange((event) => {
+  console.log(event.type, event.id, event.stale)
+})
+```
+
+### Schema Types
+
+| Type | TypeScript | Example |
+|------|------------|---------|
+| `'string'` | `string` | `'hello'` |
+| `'number'` | `number` | `42` |
+| `'boolean'` | `boolean` | `true` |
+| `'timestamp'` | `number` | `Date.now()` |
+| `'string[]'` | `string[]` | `['a', 'b']` |
+| `'number[]'` | `number[]` | `[1, 2, 3]` |
+| `'vector:N'` | `Float32Array` | 384-dim embedding |
+
+### Filter Helpers
+
+```typescript
+import {
+  // Comparison
+  eq, neq, gt, gte, lt, lte, between, oneOf,
+
+  // Text
+  fullText, matches, startsWith, endsWith,
+
+  // Arrays
+  contains, containsAny, containsAll, isEmpty, isNotEmpty,
+
+  // Logic
+  and, or, not,
+
+  // Existence
+  exists, isNull,
+
+  // Time
+  after, before, withinLast,
+} from '@rlabs-inc/fsdb'
+
+// Examples
+users.find(eq('name', 'Alice'))
+users.find(gt('age', 30))
+users.find(contains('tags', 'admin'))
+users.find(and(gt('age', 18), eq('active', true)))
+users.find(or(eq('role', 'admin'), eq('role', 'moderator')))
+users.find(fullText('search term'))
+users.find(withinLast('created', 24 * 60 * 60 * 1000)) // Last 24h
+```
+
+### Reactive Queries
+
+```typescript
+import { query, querySorted, queryCount, queryFirst, effect } from '@rlabs-inc/fsdb'
+
+// Basic query - returns { indices, records, count }
+const activeUsers = query(users, r => r.active === true)
+
+// Sorted query
+const topScorers = querySorted(users, r => r.score > 0, 'score', true)
+
+// Count query
+const activeCount = queryCount(users, r => r.active)
+
+// First match
+const admin = queryFirst(users, r => r.role === 'admin')
+
+// Use in effects - auto-updates!
+effect(() => {
+  console.log('Active users:', activeUsers.value.count)
+})
+```
+
+### Vector Search
+
+```typescript
+import { vectorSearch, cosineSimilarity } from '@rlabs-inc/fsdb'
+
+// Schema with vector column
+const docs = db.collection('docs', {
+  schema: {
+    content: 'string',
+    embedding: 'vector:384',
+  }
+})
+
+// Store embeddings with stale detection
+docs.setEmbedding(id, 'embedding', vector, sourceContent)
+
+// Search
+const results = docs.search('embedding', queryVector, {
+  topK: 10,
+  minSimilarity: 0.5,
+  filter: r => r.category === 'tech',
+})
+
+// Results include stale flag
+results.forEach(({ record, similarity, stale }) => {
+  console.log(record.content, similarity, stale ? '(stale)' : '')
+})
+
+// Manual similarity calculation
+const sim = cosineSimilarity(vecA, vecB)
+```
+
+### Sorting & Pagination
+
+```typescript
+import { sortBy, paginate } from '@rlabs-inc/fsdb'
+
+const records = users.all()
+
+// Sort
+const sorted = sortBy(records, { column: 'score', direction: 'desc' })
+
+// Multi-column sort
+const sorted2 = sortBy(records,
+  { column: 'age', direction: 'asc' },
+  { column: 'name', direction: 'asc' }
+)
+
+// Paginate
+const page = paginate(records, 1, 20)
+// { records, total, page, pageSize, totalPages, hasNext, hasPrev }
+```
+
+### File Persistence
+
+Records are stored as markdown files with YAML frontmatter:
+
+```markdown
+---
+id: user-1703289600000-abc123
+created: 1703289600000
+updated: 1703289600000
+name: Alice
+age: 30
+embedding: [0.1, 0.2, 0.3, ...]
+---
+
+This is the bio content (contentColumn)
+```
+
+### Stale Detection
+
+When content changes but embedding isn't regenerated:
+
+```typescript
+// Store embedding with content hash
+users.setEmbedding(id, 'embedding', vector, originalContent)
+
+// Later, if content changes externally...
+users.isStale(id)     // true
+users.getStaleIds()   // ['id1', 'id2', ...]
+
+// After regenerating embedding
+users.setEmbedding(id, 'embedding', newVector, newContent)
+users.isStale(id)     // false
+```
+
+## Benchmarks
+
+On Apple Silicon (M1/M2/M3):
+
+| Operation | Time |
+|-----------|------|
+| Insert 1000 records | 2.28ms |
+| Get by ID | 0.13μs |
+| Update field | 0.11μs |
+| Filter 1000 records | 107μs |
+| fullText search | 169μs |
+| Sort 1000 records | 110μs |
+| Cosine similarity (384d) | 0.17μs |
+| Vector search top-10 | 534μs |
+| Vector search with filter | 194μs |
+| Bun.hash (fingerprint) | 0.28μs |
+
+**Test Coverage:** 77 tests passing across all features.
+
+## Architecture
+
+```
+Database (FatherState)
+  └── Collections (ReactiveMap)
+        └── Collection (FatherState)
+              ├── Registry (index management)
+              └── Columns (parallel arrays)
+                    ├── names:  ['Alice', 'Bob', ...]
+                    ├── ages:   [30, 25, ...]
+                    └── scores: [100, 85, ...]
+```
+
+The same pattern repeats at every level - **fractal architecture**.
+
+## Requirements
+
+- Bun 1.0+
+- @rlabs-inc/signals
+
+## License
+
+MIT
+
+---
+
+Built with ❤️ by RLabs Inc.

package/dist/core/collection.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Collection
+ *
+ * A reactive collection using the Father State Pattern.
+ * Combines the registry (index management) with columns (parallel arrays).
+ *
+ * This is where the fractal pattern lives - each collection is a FatherState.
+ */
+import { type DerivedSignal } from '@rlabs-inc/signals';
+import { type Registry } from './registry';
+import { type ColumnsManager } from './columns';
+import type { SchemaDefinition, SchemaToRecord, RecordWithMeta, PartialRecord, CollectionOptions, FilterFn } from './types';
+export interface Collection<S extends SchemaDefinition> {
+    /** Collection name */
+    readonly name: string;
+    /** The schema definition */
+    readonly schema: S;
+    /** Content column (stored as markdown body) */
+    readonly contentColumn: keyof S | undefined;
+    /** Access to the registry */
+    readonly registry: Registry;
+    /** Access to the columns manager */
+    readonly columns: ColumnsManager<S>;
+    /** Insert a record, returns the ID */
+    insert(data: PartialRecord<S>): string;
+    /** Insert multiple records, returns array of IDs */
+    insertMany(records: PartialRecord<S>[]): string[];
+    /** Get a record by ID */
+    get(id: string): RecordWithMeta<S> | undefined;
+    /** Get all records */
+    all(): RecordWithMeta<S>[];
+    /** Find records matching a filter */
+    find(filter: FilterFn<S>): RecordWithMeta<S>[];
+    /** Find first record matching a filter */
+    findOne(filter: FilterFn<S>): RecordWithMeta<S> | undefined;
+    /** Update a record by ID */
+    update(id: string, data: Partial<SchemaToRecord<S>>): boolean;
+    /** Update a specific field of a record */
+    updateField<K extends keyof S>(id: string, field: K, value: SchemaToRecord<S>[K]): boolean;
+    /** Update multiple records matching a filter */
+    updateMany(filter: FilterFn<S>, data: Partial<SchemaToRecord<S>>): number;
+    /** Delete a record by ID */
+    delete(id: string): boolean;
+    /** Delete multiple records matching a filter */
+    deleteMany(filter: FilterFn<S>): number;
+    /** Count records (optionally filtered) */
+    count(filter?: FilterFn<S>): number;
+    /** Get a reactive count */
+    readonly reactiveCount: DerivedSignal<number>;
+    /** Get record by array index (not ID) */
+    getByIndex(index: number): RecordWithMeta<S> | undefined;
+    /** Get all allocated indices */
+    getIndices(): number[];
+    /** Check if record exists */
+    has(id: string): boolean;
+    /** Check if a record's embedding is stale */
+    isStale(id: string): boolean;
+    /** Get all IDs with stale embeddings */
+    getStaleIds(): string[];
+    /** Manually set stale flag */
+    setStale(id: string, stale: boolean): void;
+    /** Clear all data */
+    clear(): void;
+}
+export declare function createCollection<S extends SchemaDefinition>(name: string, options: CollectionOptions<S>): Collection<S>;
+//# sourceMappingURL=collection.d.ts.map

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

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

package/dist/core/columns.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Columns Manager
+ *
+ * Manages parallel reactive arrays for each schema column.
+ * This is the heart of the Father State Pattern - each field
+ * gets its own array, indexed by the registry.
+ */
+import { type WritableSignal } from '@rlabs-inc/signals';
+import type { SchemaDefinition, SchemaToRecord, ParsedColumnType, ParsedSchema } from './types';
+/**
+ * Parse a column type string into structured info
+ */
+export declare function parseColumnType(type: string): ParsedColumnType;
+/**
+ * Get default value for a column type
+ */
+export declare function getDefaultValue(type: string): unknown;
+/**
+ * Parse a schema definition into structured info
+ */
+export declare function parseSchema<S extends SchemaDefinition>(definition: S): ParsedSchema<S>;
+export interface ColumnsManager<S extends SchemaDefinition> {
+    /** Get the parsed schema */
+    readonly schema: ParsedSchema<S>;
+    /** Get a raw column array (reactive signal) */
+    getColumn<K extends keyof S>(name: K): WritableSignal<unknown[]>;
+    /** Get a value from a column at an index */
+    get<K extends keyof S>(column: K, index: number): SchemaToRecord<S>[K];
+    /** Set a value in a column at an index */
+    set<K extends keyof S>(column: K, index: number, value: SchemaToRecord<S>[K]): void;
+    /** Get all column values for an index as a record */
+    getRecord(index: number): SchemaToRecord<S>;
+    /** Set all column values for an index from a record */
+    setRecord(index: number, record: Partial<SchemaToRecord<S>>): void;
+    /** Clear all values at an index (reset to defaults) */
+    clearAt(index: number): void;
+    /** Reset all columns (for testing/cleanup) */
+    reset(): void;
+}
+/**
+ * Create a columns manager for a schema
+ *
+ * Each column is a reactive signal containing an array.
+ * Fine-grained updates: modifying arr[i] triggers only effects reading that index.
+ */
+export declare function createColumns<S extends SchemaDefinition>(definition: S): ColumnsManager<S>;
+//# sourceMappingURL=columns.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"columns.d.ts","sourceRoot":"","sources":["../../src/core/columns.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAU,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAO/F;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAkB9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAoBrD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,gBAAgB,EAAE,UAAU,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAoBtF;AAMD,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,gBAAgB;IACxD,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAA;IAEhC,+CAA+C;IAC/C,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,cAAc,CAAC,OAAO,EAAE,CAAC,CAAA;IAEhE,4CAA4C;IAC5C,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAEtE,0CAA0C;IAC1C,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IAEnF,qDAAqD;IACrD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAA;IAE3C,uDAAuD;IACvD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IAElE,uDAAuD;IACvD,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAE5B,8CAA8C;IAC9C,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,gBAAgB,EACtD,UAAU,EAAE,CAAC,GACZ,cAAc,CAAC,CAAC,CAAC,CA6FnB"}

package/dist/core/constants.d.ts

@@ -0,0 +1,22 @@
+/**
+ * fsDB Constants
+ */
+/** Default values for column types */
+export declare const DEFAULT_VALUES: {
+    readonly string: "";
+    readonly number: 0;
+    readonly boolean: false;
+    readonly timestamp: 0;
+    readonly 'string[]': string[];
+    readonly 'number[]': number[];
+    readonly vector: Float32Array | null;
+};
+/** File watcher debounce time in ms */
+export declare const WATCHER_DEBOUNCE_MS = 100;
+/** Time to wait after save before allowing file watcher to process (prevents loops) */
+export declare const SAVE_GRACE_PERIOD_MS = 200;
+/** Default page size for pagination */
+export declare const DEFAULT_PAGE_SIZE = 20;
+/** Maximum iterations for stale detection loop */
+export declare const MAX_STALE_CHECK_ITERATIONS = 10000;
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/core/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,sCAAsC;AACtC,eAAO,MAAM,cAAc;;;;;yBAKP,MAAM,EAAE;yBACR,MAAM,EAAE;qBACV,YAAY,GAAG,IAAI;CAC3B,CAAA;AAEV,uCAAuC;AACvC,eAAO,MAAM,mBAAmB,MAAM,CAAA;AAEtC,uFAAuF;AACvF,eAAO,MAAM,oBAAoB,MAAM,CAAA;AAEvC,uCAAuC;AACvC,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAEnC,kDAAkD;AAClD,eAAO,MAAM,0BAA0B,QAAQ,CAAA"}

package/dist/core/database.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Database
+ *
+ * The top level of the fractal - manages collections.
+ * Each database is a FatherState at the macro level.
+ */
+import { type Collection } from './collection';
+import type { SchemaDefinition, CollectionOptions, DatabaseOptions, FileChangeEvent } from './types';
+import type { VectorSearchOptions, VectorSearchResult } from './types';
+export interface PersistentCollection<S extends SchemaDefinition> extends Collection<S> {
+    /** Load all records from disk */
+    load(): Promise<number>;
+    /** Save all records to disk */
+    save(): Promise<number>;
+    /** Start file watching */
+    startWatching(): void;
+    /** Stop file watching */
+    stopWatching(): void;
+    /** Is currently watching */
+    readonly isWatching: boolean;
+    /** Register callback for file changes */
+    onFileChange(callback: (event: FileChangeEvent<S>) => void | Promise<void>): () => void;
+    /** Set embedding with content hash for stale detection */
+    setEmbedding(id: string, column: keyof S, embedding: Float32Array | number[], sourceContent: string): void;
+    /** Vector similarity search */
+    search(column: keyof S, queryVector: Float32Array | number[], options?: VectorSearchOptions<S>): VectorSearchResult<S>[];
+    /** Close the collection (stop watching, cleanup) */
+    close(): void;
+}
+/**
+ * Create a persistent collection with file I/O and watching
+ */
+export declare function createPersistentCollection<S extends SchemaDefinition>(name: string, options: CollectionOptions<S> & {
+    path: string;
+}): PersistentCollection<S>;
+export interface Database {
+    /** Database name */
+    readonly name: string;
+    /** Base path for collections */
+    readonly basePath: string;
+    /** Get or create a collection */
+    collection<S extends SchemaDefinition>(name: string, options: Omit<CollectionOptions<S>, 'path'>): PersistentCollection<S>;
+    /** Get an existing collection */
+    getCollection<S extends SchemaDefinition>(name: string): PersistentCollection<S> | undefined;
+    /** List all collection names */
+    listCollections(): string[];
+    /** Close all collections */
+    close(): void;
+}
+/**
+ * Create a database instance
+ */
+export declare function createDatabase(options?: DatabaseOptions): Database;
+export { createDatabase as fsDB };
+//# sourceMappingURL=database.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/core/database.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAA;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAkB,eAAe,EAAE,MAAM,SAAS,CAAA;AAUpH,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAMtE,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACrF,iCAAiC;IACjC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAEvB,+BAA+B;IAC/B,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAEvB,0BAA0B;IAC1B,aAAa,IAAI,IAAI,CAAA;IAErB,yBAAyB;IACzB,YAAY,IAAI,IAAI,CAAA;IAEpB,4BAA4B;IAC5B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAE5B,yCAAyC;IACzC,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAA;IAEvF,0DAA0D;IAC1D,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,YAAY,GAAG,MAAM,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAE1G,+BAA+B;IAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,YAAY,GAAG,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAA;IAExH,oDAAoD;IACpD,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,gBAAgB,EACnE,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/C,oBAAoB,CAAC,CAAC,CAAC,CA8QzB;AAMD,MAAM,WAAW,QAAQ;IACvB,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IAEzB,iCAAiC;IACjC,UAAU,CAAC,CAAC,SAAS,gBAAgB,EACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,GAC1C,oBAAoB,CAAC,CAAC,CAAC,CAAA;IAE1B,iCAAiC;IACjC,aAAa,CAAC,CAAC,SAAS,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;IAE5F,gCAAgC;IAChC,eAAe,IAAI,MAAM,EAAE,CAAA;IAE3B,4BAA4B;IAC5B,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CA0DtE;AAGD,OAAO,EAAE,cAAc,IAAI,IAAI,EAAE,CAAA"}

package/dist/core/registry.d.ts

@@ -0,0 +1,52 @@
+/**
+ * FatherState Registry
+ *
+ * The central index manager for the Father State Pattern.
+ * Manages ID-to-index mappings with O(1) lookups and index reuse.
+ *
+ * Uses reactive primitives from @rlabs-inc/signals for fine-grained reactivity.
+ */
+import { ReactiveMap, ReactiveSet } from '@rlabs-inc/signals';
+export interface Registry {
+    /** Map from record ID to array index */
+    readonly idToIndex: ReactiveMap<string, number>;
+    /** Map from array index to record ID */
+    readonly indexToId: ReactiveMap<number, string>;
+    /** Set of currently allocated indices */
+    readonly allocatedIndices: ReactiveSet<number>;
+    /** Array of free indices available for reuse */
+    readonly freeIndices: number[];
+    /** Next index to allocate if no free indices */
+    nextIndex: number;
+    /** Allocate an index for an ID (reuses free indices) */
+    allocate(id: string): number;
+    /** Release an index, returning it to the free pool */
+    release(id: string): boolean;
+    /** Get index for an ID (returns -1 if not found) */
+    getIndex(id: string): number;
+    /** Get ID for an index (returns undefined if not found) */
+    getId(index: number): string | undefined;
+    /** Check if a record exists */
+    has(id: string): boolean;
+    /** Get all record IDs */
+    getAllIds(): string[];
+    /** Get all allocated indices */
+    getAllIndices(): number[];
+    /** Get count of records */
+    readonly count: number;
+    /** Reset the registry (for testing/cleanup) */
+    reset(): void;
+}
+/**
+ * Create a new FatherState registry instance
+ *
+ * Each registry is independent - no global state.
+ */
+export declare function createRegistry(): Registry;
+/**
+ * Generate a unique ID
+ *
+ * Format: timestamp-random (e.g., "1703289600000-a1b2c3")
+ */
+export declare function generateId(): string;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/core/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAU,MAAM,oBAAoB,CAAA;AAErE,MAAM,WAAW,QAAQ;IACvB,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAE/C,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAE/C,yCAAyC;IACzC,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAE9C,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,CAAA;IAE9B,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAA;IAEjB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IAE5B,sDAAsD;IACtD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;IAE5B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IAE5B,2DAA2D;IAC3D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IAExC,+BAA+B;IAC/B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;IAExB,yBAAyB;IACzB,SAAS,IAAI,MAAM,EAAE,CAAA;IAErB,gCAAgC;IAChC,aAAa,IAAI,MAAM,EAAE,CAAA;IAEzB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IAEtB,+CAA+C;IAC/C,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,QAAQ,CAkGzC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAInC"}