@hashtree/dexie 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sirius Business Ltd.
+
+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/dist/index.d.ts

@@ -0,0 +1,42 @@
+import type { Store, Hash } from '@hashtree/core';
+/**
+ * Dexie-based Store implementation
+ * Drop-in replacement for IndexedDBStore with better error handling
+ */
+export declare class DexieStore implements Store {
+    private db;
+    constructor(dbName?: string);
+    put(hash: Hash, data: Uint8Array): Promise<boolean>;
+    get(hash: Hash): Promise<Uint8Array | null>;
+    has(hash: Hash): Promise<boolean>;
+    delete(hash: Hash): Promise<boolean>;
+    /**
+     * Get all stored hashes
+     */
+    keys(): Promise<Hash[]>;
+    /**
+     * Clear all data
+     */
+    clear(): Promise<void>;
+    /**
+     * Get count of stored items
+     */
+    count(): Promise<number>;
+    /**
+     * Get total bytes stored
+     */
+    totalBytes(): Promise<number>;
+    /**
+     * Evict least-recently-used entries until totalBytes is below maxBytes.
+     * Returns the number of entries deleted.
+     */
+    evict(maxBytes: number): Promise<number>;
+    /**
+     * Close the database connection
+     */
+    close(): void;
+    /**
+     * Delete the entire database
+     */
+    static deleteDatabase(dbName?: string): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,187 @@
+/**
+ * Dexie-based IndexedDB store for hashtree blobs
+ * More robust than raw IndexedDB - handles errors, upgrades, and stuck connections better
+ */
+import Dexie from 'dexie';
+import { toHex, fromHex } from '@hashtree/core';
+class HashTreeDB extends Dexie {
+    blobs;
+    constructor(dbName) {
+        super(dbName);
+        // Version 1: Original schema without lastAccess
+        this.version(1).stores({
+            blobs: '&hashHex',
+        });
+        // Version 2: Add lastAccess field for LRU eviction
+        this.version(2).stores({
+            blobs: '&hashHex, lastAccess',
+        }).upgrade(tx => {
+            // Add lastAccess to existing entries
+            const now = Date.now();
+            return tx.table('blobs').toCollection().modify(blob => {
+                blob.lastAccess = now;
+            });
+        });
+    }
+}
+/**
+ * Dexie-based Store implementation
+ * Drop-in replacement for IndexedDBStore with better error handling
+ */
+export class DexieStore {
+    db;
+    constructor(dbName = 'hashtree') {
+        this.db = new HashTreeDB(dbName);
+    }
+    async put(hash, data) {
+        const hashHex = toHex(hash);
+        try {
+            await this.db.blobs.put({ hashHex, data: new Uint8Array(data), lastAccess: Date.now() });
+            return true;
+        }
+        catch (e) {
+            console.error('[DexieStore] put error:', e);
+            return false;
+        }
+    }
+    async get(hash) {
+        if (!hash)
+            return null;
+        const hashHex = toHex(hash);
+        try {
+            const entry = await this.db.blobs.get(hashHex);
+            if (!entry)
+                return null;
+            // Update lastAccess timestamp for LRU tracking (fire-and-forget)
+            // We need to re-put the entry to avoid fake-indexeddb corruption issues with partial updates
+            this.db.blobs.put({ ...entry, lastAccess: Date.now() }).catch(() => { });
+            // Use slice to ensure we get exact data without extra buffer bytes
+            // IndexedDB can store the entire backing ArrayBuffer of a view
+            const data = entry.data;
+            return new Uint8Array(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength));
+        }
+        catch (e) {
+            console.error('[DexieStore] get error:', e);
+            return null;
+        }
+    }
+    async has(hash) {
+        const hashHex = toHex(hash);
+        try {
+            const entry = await this.db.blobs.get(hashHex);
+            return entry !== undefined;
+        }
+        catch (e) {
+            console.error('[DexieStore] has error:', e);
+            return false;
+        }
+    }
+    async delete(hash) {
+        const hashHex = toHex(hash);
+        try {
+            const existed = await this.has(hash);
+            if (existed) {
+                await this.db.blobs.delete(hashHex);
+                return true;
+            }
+            return false;
+        }
+        catch (e) {
+            console.error('[DexieStore] delete error:', e);
+            return false;
+        }
+    }
+    /**
+     * Get all stored hashes
+     */
+    async keys() {
+        try {
+            const hexKeys = await this.db.blobs.toCollection().primaryKeys();
+            return hexKeys.map(hex => fromHex(hex));
+        }
+        catch (e) {
+            console.error('[DexieStore] keys error:', e);
+            return [];
+        }
+    }
+    /**
+     * Clear all data
+     */
+    async clear() {
+        try {
+            await this.db.blobs.clear();
+        }
+        catch (e) {
+            console.error('[DexieStore] clear error:', e);
+        }
+    }
+    /**
+     * Get count of stored items
+     */
+    async count() {
+        try {
+            return await this.db.blobs.count();
+        }
+        catch (e) {
+            console.error('[DexieStore] count error:', e);
+            return 0;
+        }
+    }
+    /**
+     * Get total bytes stored
+     */
+    async totalBytes() {
+        try {
+            let total = 0;
+            await this.db.blobs.each(e => {
+                total += e.data.length;
+            });
+            return total;
+        }
+        catch (e) {
+            console.error('[DexieStore] totalBytes error:', e);
+            return 0;
+        }
+    }
+    /**
+     * Evict least-recently-used entries until totalBytes is below maxBytes.
+     * Returns the number of entries deleted.
+     */
+    async evict(maxBytes) {
+        try {
+            const currentBytes = await this.totalBytes();
+            if (currentBytes <= maxBytes)
+                return 0;
+            // Get entries sorted by lastAccess (oldest first)
+            const entries = await this.db.blobs.orderBy('lastAccess').toArray();
+            let bytesRemoved = 0;
+            let entriesRemoved = 0;
+            const targetRemoval = currentBytes - maxBytes;
+            for (const entry of entries) {
+                if (bytesRemoved >= targetRemoval)
+                    break;
+                await this.db.blobs.delete(entry.hashHex);
+                bytesRemoved += entry.data.length;
+                entriesRemoved++;
+            }
+            console.log(`[DexieStore] Evicted ${entriesRemoved} entries (${bytesRemoved} bytes)`);
+            return entriesRemoved;
+        }
+        catch (e) {
+            console.error('[DexieStore] evict error:', e);
+            return 0;
+        }
+    }
+    /**
+     * Close the database connection
+     */
+    close() {
+        this.db.close();
+    }
+    /**
+     * Delete the entire database
+     */
+    static async deleteDatabase(dbName = 'hashtree') {
+        await Dexie.delete(dbName);
+    }
+}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,220 @@
+/**
+ * Unit tests for DexieStore
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { DexieStore } from './index.js';
+// Helper to create a hash from data (simplified for tests)
+function makeHash(data) {
+    // Create a 32-byte hash-like value (not cryptographic, just for testing)
+    const hash = new Uint8Array(32);
+    for (let i = 0; i < data.length && i < 32; i++) {
+        hash[i] = data[i];
+    }
+    // Add some uniqueness based on length
+    hash[31] = data.length % 256;
+    return hash;
+}
+describe('DexieStore', () => {
+    let store;
+    const TEST_DB_NAME = 'test-dexie-store';
+    beforeEach(async () => {
+        // Delete any existing test database
+        await DexieStore.deleteDatabase(TEST_DB_NAME);
+        store = new DexieStore(TEST_DB_NAME);
+    });
+    afterEach(async () => {
+        store.close();
+        await DexieStore.deleteDatabase(TEST_DB_NAME);
+    });
+    describe('put and get', () => {
+        it('should store and retrieve data', async () => {
+            const data = new TextEncoder().encode('hello world');
+            const hash = makeHash(data);
+            await store.put(hash, data);
+            const retrieved = await store.get(hash);
+            expect(retrieved).not.toBeNull();
+            expect(new TextDecoder().decode(retrieved)).toBe('hello world');
+        });
+        it('should return null for non-existent hash', async () => {
+            const hash = makeHash(new Uint8Array([1, 2, 3]));
+            const retrieved = await store.get(hash);
+            expect(retrieved).toBeNull();
+        });
+        it('should handle empty data', async () => {
+            const data = new Uint8Array(0);
+            const hash = makeHash(data);
+            await store.put(hash, data);
+            const retrieved = await store.get(hash);
+            expect(retrieved).not.toBeNull();
+            expect(retrieved.length).toBe(0);
+        });
+        it('should handle binary data', async () => {
+            const data = new Uint8Array([0, 1, 127, 128, 255]);
+            const hash = makeHash(data);
+            await store.put(hash, data);
+            const retrieved = await store.get(hash);
+            expect(retrieved).not.toBeNull();
+            expect(Array.from(retrieved)).toEqual([0, 1, 127, 128, 255]);
+        });
+    });
+    describe('has', () => {
+        it('should return true for existing data', async () => {
+            const data = new TextEncoder().encode('test');
+            const hash = makeHash(data);
+            await store.put(hash, data);
+            expect(await store.has(hash)).toBe(true);
+        });
+        it('should return false for non-existent data', async () => {
+            const hash = makeHash(new Uint8Array([1, 2, 3]));
+            expect(await store.has(hash)).toBe(false);
+        });
+    });
+    describe('delete', () => {
+        it('should delete existing data', async () => {
+            const data = new TextEncoder().encode('to delete');
+            const hash = makeHash(data);
+            await store.put(hash, data);
+            expect(await store.has(hash)).toBe(true);
+            const deleted = await store.delete(hash);
+            expect(deleted).toBe(true);
+            expect(await store.has(hash)).toBe(false);
+        });
+        it('should return false for non-existent data', async () => {
+            const hash = makeHash(new Uint8Array([1, 2, 3]));
+            const deleted = await store.delete(hash);
+            expect(deleted).toBe(false);
+        });
+    });
+    describe('count and totalBytes', () => {
+        it('should count items correctly', async () => {
+            expect(await store.count()).toBe(0);
+            const data1 = new TextEncoder().encode('one');
+            const data2 = new TextEncoder().encode('two');
+            const data3 = new TextEncoder().encode('three');
+            await store.put(makeHash(data1), data1);
+            expect(await store.count()).toBe(1);
+            await store.put(makeHash(data2), data2);
+            expect(await store.count()).toBe(2);
+            await store.put(makeHash(data3), data3);
+            expect(await store.count()).toBe(3);
+        });
+        it('should calculate total bytes correctly', async () => {
+            expect(await store.totalBytes()).toBe(0);
+            const data1 = new Uint8Array(100);
+            const data2 = new Uint8Array(200);
+            data2[0] = 1; // Make it different from data1
+            await store.put(makeHash(data1), data1);
+            expect(await store.totalBytes()).toBe(100);
+            await store.put(makeHash(data2), data2);
+            expect(await store.totalBytes()).toBe(300);
+        });
+    });
+    describe('keys', () => {
+        it('should return all stored hashes', async () => {
+            const data1 = new TextEncoder().encode('one');
+            const data2 = new TextEncoder().encode('two');
+            const hash1 = makeHash(data1);
+            const hash2 = makeHash(data2);
+            await store.put(hash1, data1);
+            await store.put(hash2, data2);
+            const keys = await store.keys();
+            expect(keys.length).toBe(2);
+        });
+        it('should return empty array for empty store', async () => {
+            const keys = await store.keys();
+            expect(keys.length).toBe(0);
+        });
+    });
+    describe('clear', () => {
+        it('should remove all data', async () => {
+            const data1 = new TextEncoder().encode('one');
+            const data2 = new TextEncoder().encode('two');
+            await store.put(makeHash(data1), data1);
+            await store.put(makeHash(data2), data2);
+            expect(await store.count()).toBe(2);
+            await store.clear();
+            expect(await store.count()).toBe(0);
+        });
+    });
+    describe('persistence', () => {
+        it('should persist data across store instances', async () => {
+            const data = new TextEncoder().encode('persistent');
+            const hash = makeHash(data);
+            await store.put(hash, data);
+            store.close();
+            // Create new instance with same db name
+            const store2 = new DexieStore(TEST_DB_NAME);
+            const retrieved = await store2.get(hash);
+            expect(retrieved).not.toBeNull();
+            expect(new TextDecoder().decode(retrieved)).toBe('persistent');
+            store2.close();
+        });
+    });
+    describe('evict', () => {
+        it('should evict entries when over limit', async () => {
+            // Add 3 entries of 100 bytes each (300 bytes total)
+            const data1 = new Uint8Array(100);
+            const data2 = new Uint8Array(100);
+            const data3 = new Uint8Array(100);
+            data1[0] = 1;
+            data2[0] = 2;
+            data3[0] = 3;
+            const hash1 = makeHash(data1);
+            const hash2 = makeHash(data2);
+            const hash3 = makeHash(data3);
+            await store.put(hash1, data1);
+            // Small delay to ensure different lastAccess times
+            await new Promise(r => setTimeout(r, 10));
+            await store.put(hash2, data2);
+            await new Promise(r => setTimeout(r, 10));
+            await store.put(hash3, data3);
+            expect(await store.count()).toBe(3);
+            expect(await store.totalBytes()).toBe(300);
+            // Evict to max 150 bytes - should remove oldest entries
+            const evicted = await store.evict(150);
+            expect(evicted).toBeGreaterThan(0);
+            const remaining = await store.totalBytes();
+            expect(remaining).toBeLessThanOrEqual(150);
+        });
+        it('should not evict when under limit', async () => {
+            const data = new Uint8Array(100);
+            const hash = makeHash(data);
+            await store.put(hash, data);
+            const evicted = await store.evict(1000);
+            expect(evicted).toBe(0);
+            expect(await store.count()).toBe(1);
+        });
+        it('should evict least recently used first', async () => {
+            const data1 = new Uint8Array(100);
+            const data2 = new Uint8Array(100);
+            const data3 = new Uint8Array(100);
+            data1[0] = 1;
+            data2[0] = 2;
+            data3[0] = 3;
+            const hash1 = makeHash(data1);
+            const hash2 = makeHash(data2);
+            const hash3 = makeHash(data3);
+            // Put in order: 1, 2, 3 with delays to ensure different lastAccess times
+            await store.put(hash1, data1);
+            await new Promise(r => setTimeout(r, 50));
+            await store.put(hash2, data2);
+            await new Promise(r => setTimeout(r, 50));
+            await store.put(hash3, data3);
+            // Access hash1 to make it recently used
+            await new Promise(r => setTimeout(r, 50));
+            await store.get(hash1);
+            // Wait for the fire-and-forget lastAccess update to complete
+            await new Promise(r => setTimeout(r, 100));
+            // Evict to max 200 bytes - should remove hash2 (oldest after hash1 was accessed)
+            await store.evict(200);
+            // hash1 and hash3 should remain (most recently accessed/created)
+            expect(await store.has(hash1)).toBe(true);
+            expect(await store.has(hash2)).toBe(false);
+            expect(await store.has(hash3)).toBe(true);
+        });
+        it('should return 0 when store is empty', async () => {
+            const evicted = await store.evict(100);
+            expect(evicted).toBe(0);
+        });
+    });
+});

package/dist/test-setup.d.ts

@@ -0,0 +1 @@
+import 'fake-indexeddb/auto';

package/dist/test-setup.js

@@ -0,0 +1,2 @@
+// Setup fake-indexeddb for Dexie tests
+import 'fake-indexeddb/auto';

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@hashtree/dexie",
+  "version": "0.1.0",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Dexie-based IndexedDB store for hashtree",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "dexie": "^4.0.11",
+    "@hashtree/core": "0.1.0"
+  },
+  "devDependencies": {
+    "fake-indexeddb": "^6.0.0",
+    "jsdom": "^26.0.0",
+    "typescript": "^5.8.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}