@soulcraft/cortex 1.3.1

package/dist/utils/nativeEntityIdMapper.d.ts

@@ -0,0 +1,84 @@
+/**
+ * EntityIdMapper — Bidirectional UUID ↔ integer mapping for roaring bitmaps
+ *
+ * Thin TypeScript wrapper around the native Rust NativeEntityIdMapper.
+ * All mapping operations execute synchronously in Rust (O(1) HashMap lookups).
+ * This wrapper handles async storage I/O (load from storage, persist to storage).
+ */
+import type { StorageAdapter } from '@soulcraft/brainy';
+export interface NativeEntityIdMapperWrapperOptions {
+    storage: StorageAdapter;
+    storageKey?: string;
+}
+/**
+ * Bidirectional UUID ↔ integer mapping for roaring bitmap integration.
+ * Delegates to native Rust implementation for all mapping operations.
+ */
+export declare class NativeEntityIdMapperWrapper {
+    private storage;
+    private storageKey;
+    private native;
+    constructor(options: NativeEntityIdMapperWrapperOptions);
+    /**
+     * Initialize the mapper by loading from storage
+     */
+    init(): Promise<void>;
+    /**
+     * Get integer ID for UUID, assigning a new ID if not exists
+     */
+    getOrAssign(uuid: string): number;
+    /**
+     * Get integer ID for UUID with immediate persistence guarantee
+     */
+    getOrAssignSync(uuid: string): Promise<number>;
+    /**
+     * Get UUID for integer ID
+     */
+    getUuid(intId: number): string | undefined;
+    /**
+     * Get integer ID for UUID (without assigning if not exists)
+     */
+    getInt(uuid: string): number | undefined;
+    /**
+     * Check if UUID has been assigned an integer ID
+     */
+    has(uuid: string): boolean;
+    /**
+     * Remove mapping for UUID
+     */
+    remove(uuid: string): boolean;
+    /**
+     * Get total number of mappings
+     */
+    get size(): number;
+    /**
+     * Convert array of UUIDs to array of integers
+     */
+    uuidsToInts(uuids: string[]): number[];
+    /**
+     * Convert array of integers to array of UUIDs
+     */
+    intsToUuids(ints: number[]): string[];
+    /**
+     * Convert iterable of integers to array of UUIDs (for roaring bitmap iteration)
+     */
+    intsIterableToUuids(ints: Iterable<number>): string[];
+    /**
+     * Flush mappings to storage
+     */
+    flush(): Promise<void>;
+    /**
+     * Clear all mappings
+     */
+    clear(): Promise<void>;
+    /**
+     * Get statistics about the mapper
+     */
+    getStats(): {
+        mappings: number;
+        nextId: number;
+        dirty: boolean;
+        memoryEstimate: number;
+    };
+}
+//# sourceMappingURL=nativeEntityIdMapper.d.ts.map

package/dist/utils/nativeEntityIdMapper.js

@@ -0,0 +1,134 @@
+/**
+ * EntityIdMapper — Bidirectional UUID ↔ integer mapping for roaring bitmaps
+ *
+ * Thin TypeScript wrapper around the native Rust NativeEntityIdMapper.
+ * All mapping operations execute synchronously in Rust (O(1) HashMap lookups).
+ * This wrapper handles async storage I/O (load from storage, persist to storage).
+ */
+import { loadNativeModule } from '../native/index.js';
+/**
+ * Bidirectional UUID ↔ integer mapping for roaring bitmap integration.
+ * Delegates to native Rust implementation for all mapping operations.
+ */
+export class NativeEntityIdMapperWrapper {
+    storage;
+    storageKey;
+    native;
+    constructor(options) {
+        this.storage = options.storage;
+        this.storageKey = options.storageKey || 'brainy:entityIdMapper';
+        const bindings = loadNativeModule();
+        this.native = new bindings.NativeEntityIdMapper();
+    }
+    /**
+     * Initialize the mapper by loading from storage
+     */
+    async init() {
+        try {
+            const metadata = await this.storage.getMetadata(this.storageKey);
+            if (metadata && metadata.nextId !== undefined) {
+                this.native.loadFromJson(JSON.stringify(metadata));
+            }
+        }
+        catch {
+            // First time initialization — native mapper starts empty
+        }
+    }
+    /**
+     * Get integer ID for UUID, assigning a new ID if not exists
+     */
+    getOrAssign(uuid) {
+        return this.native.getOrAssign(uuid);
+    }
+    /**
+     * Get integer ID for UUID with immediate persistence guarantee
+     */
+    async getOrAssignSync(uuid) {
+        const id = this.native.getOrAssign(uuid);
+        if (this.native.isDirty()) {
+            await this.flush();
+        }
+        return id;
+    }
+    /**
+     * Get UUID for integer ID
+     */
+    getUuid(intId) {
+        return this.native.getUuid(intId) ?? undefined;
+    }
+    /**
+     * Get integer ID for UUID (without assigning if not exists)
+     */
+    getInt(uuid) {
+        return this.native.getInt(uuid) ?? undefined;
+    }
+    /**
+     * Check if UUID has been assigned an integer ID
+     */
+    has(uuid) {
+        return this.native.has(uuid);
+    }
+    /**
+     * Remove mapping for UUID
+     */
+    remove(uuid) {
+        return this.native.remove(uuid);
+    }
+    /**
+     * Get total number of mappings
+     */
+    get size() {
+        return this.native.size;
+    }
+    /**
+     * Convert array of UUIDs to array of integers
+     */
+    uuidsToInts(uuids) {
+        return this.native.uuidsToInts(uuids);
+    }
+    /**
+     * Convert array of integers to array of UUIDs
+     */
+    intsToUuids(ints) {
+        return this.native.intsToUuids(ints);
+    }
+    /**
+     * Convert iterable of integers to array of UUIDs (for roaring bitmap iteration)
+     */
+    intsIterableToUuids(ints) {
+        return this.native.intsToUuids(Array.from(ints));
+    }
+    /**
+     * Flush mappings to storage
+     */
+    async flush() {
+        if (!this.native.isDirty()) {
+            return;
+        }
+        const json = this.native.saveToJson();
+        const data = JSON.parse(json);
+        await this.storage.saveMetadata(this.storageKey, data);
+        // Reload to clear dirty flag (native sets dirty=false on load)
+        this.native.loadFromJson(json);
+    }
+    /**
+     * Clear all mappings
+     */
+    async clear() {
+        this.native.clear();
+        await this.flush();
+    }
+    /**
+     * Get statistics about the mapper
+     */
+    getStats() {
+        const stats = this.native.getStats();
+        return {
+            mappings: stats.mappings,
+            nextId: stats.nextId,
+            dirty: stats.dirty,
+            memoryEstimate: stats.memoryEstimate,
+        };
+    }
+}
+//# sourceMappingURL=nativeEntityIdMapper.js.map