local-lite 0.0.19 → 0.0.20

package/dist/storage/driver.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeFileDriver = exports.MemoryFileDriver = void 0;
+/**
+ * Universal in-memory driver (ideal for tests, memory caches, and browser storage fallback).
+ */
+class MemoryFileDriver {
+    files = new Map();
+    async write(key, data) {
+        this.files.set(key, new Uint8Array(data));
+        return `memory://${key}`;
+    }
+    async read(key) {
+        const file = this.files.get(key);
+        return file ? new Uint8Array(file) : null;
+    }
+    async delete(key) {
+        this.files.delete(key);
+    }
+    async exists(key) {
+        return this.files.has(key);
+    }
+    clear() {
+        this.files.clear();
+    }
+}
+exports.MemoryFileDriver = MemoryFileDriver;
+/**
+ * Node.js filesystem driver for writing blobs to disk.
+ */
+class NodeFileDriver {
+    baseDir;
+    constructor(baseDir = './.local-lite-blobs') {
+        this.baseDir = baseDir;
+    }
+    async getFs() {
+        try {
+            const fs = await import('node:fs/promises');
+            const path = await import('node:path');
+            return { fs, path };
+        }
+        catch {
+            throw new Error('NodeFileDriver is only supported in Node.js environments.');
+        }
+    }
+    async getResolvedPath(key) {
+        const { path } = await this.getFs();
+        // sanitize key to prevent directory traversal
+        const safeKey = key.replace(/\.\./g, '_');
+        return path.resolve(this.baseDir, safeKey);
+    }
+    async write(key, data) {
+        const { fs, path } = await this.getFs();
+        const filePath = await this.getResolvedPath(key);
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, data);
+        return filePath;
+    }
+    async read(key) {
+        const { fs } = await this.getFs();
+        const filePath = await this.getResolvedPath(key);
+        try {
+            const buffer = await fs.readFile(filePath);
+            return new Uint8Array(buffer);
+        }
+        catch {
+            return null;
+        }
+    }
+    async delete(key) {
+        const { fs } = await this.getFs();
+        const filePath = await this.getResolvedPath(key);
+        try {
+            await fs.unlink(filePath);
+        }
+        catch {
+            // file might already be removed
+        }
+    }
+    async exists(key) {
+        const { fs } = await this.getFs();
+        const filePath = await this.getResolvedPath(key);
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.NodeFileDriver = NodeFileDriver;

package/dist/storage/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './driver.js';
+export * from './store.js';
+export * from './manager.js';

package/dist/storage/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./driver.js"), exports);
+__exportStar(require("./store.js"), exports);
+__exportStar(require("./manager.js"), exports);

package/dist/storage/manager.d.ts

@@ -0,0 +1,48 @@
+import { DBExecutable } from '../core/schema-manager.js';
+import { BlobRecord, BlobStorageManagerOptions, BlobUploadStatus, FileDriver, RemoteStorageUploader, SaveBlobOptions } from './types.js';
+export declare class BlobStorageManager {
+    private db;
+    private driver;
+    private uploader?;
+    private network?;
+    private tableName;
+    constructor(db: DBExecutable, options?: BlobStorageManagerOptions);
+    initialize(): Promise<void>;
+    setDriver(driver: FileDriver): void;
+    setUploader(uploader: RemoteStorageUploader): void;
+    /**
+     * Saves a binary blob or file locally. Records metadata in SQLite and writes binary to driver.
+     * If online and uploader configured, can immediately trigger upload.
+     */
+    save(key: string, data: Uint8Array | string, options?: SaveBlobOptions): Promise<BlobRecord>;
+    /**
+     * Retrieves blob record and raw binary data.
+     */
+    get(key: string): Promise<{
+        record: BlobRecord;
+        data: Uint8Array;
+    } | null>;
+    /**
+     * Reads raw binary data for key.
+     */
+    getData(key: string): Promise<Uint8Array | null>;
+    /**
+     * Retrieves blob metadata record.
+     */
+    getRecord(key: string): Promise<BlobRecord | null>;
+    /**
+     * Lists blob metadata records, optionally filtered by upload status.
+     */
+    list(status?: BlobUploadStatus): Promise<BlobRecord[]>;
+    /**
+     * Deletes the blob binary and metadata record.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Flushes and syncs pending or failed uploads to the remote storage uploader.
+     */
+    syncPending(): Promise<{
+        uploaded: number;
+        failed: number;
+    }>;
+}

package/dist/storage/manager.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlobStorageManager = void 0;
+const sha2_js_1 = require("@noble/hashes/sha2.js");
+const utils_js_1 = require("@noble/hashes/utils.js");
+const uuid_js_1 = require("../utils/uuid.js");
+const store_js_1 = require("./store.js");
+const driver_js_1 = require("./driver.js");
+class BlobStorageManager {
+    db;
+    driver;
+    uploader;
+    network;
+    tableName;
+    constructor(db, options = {}) {
+        this.db = db;
+        this.driver = options.driver ?? new driver_js_1.MemoryFileDriver();
+        this.uploader = options.uploader;
+        this.network = options.network;
+        this.tableName = options.tableName ?? store_js_1.DEFAULT_BLOBS_TABLE;
+    }
+    async initialize() {
+        await store_js_1.BlobStore.ensureSchema(this.db, this.tableName);
+    }
+    setDriver(driver) {
+        this.driver = driver;
+    }
+    setUploader(uploader) {
+        this.uploader = uploader;
+    }
+    /**
+     * Saves a binary blob or file locally. Records metadata in SQLite and writes binary to driver.
+     * If online and uploader configured, can immediately trigger upload.
+     */
+    async save(key, data, options = {}) {
+        const bytes = typeof data === 'string' ? (0, utils_js_1.utf8ToBytes)(data) : data;
+        const hash = (0, utils_js_1.bytesToHex)((0, sha2_js_1.sha256)(bytes));
+        const now = Date.now();
+        const localPath = await this.driver.write(key, bytes);
+        const existing = await store_js_1.BlobStore.getByKey(this.db, this.tableName, key);
+        const id = existing ? existing.id : (0, uuid_js_1.generateUUID)();
+        const record = {
+            id,
+            key,
+            name: options.name || key.split('/').pop() || key,
+            mimeType: options.mimeType || 'application/octet-stream',
+            size: bytes.byteLength,
+            localPath,
+            remoteUrl: existing?.remoteUrl || null,
+            status: 'PENDING',
+            sha256: hash,
+            metadata: options.metadata || existing?.metadata,
+            createdAt: existing ? existing.createdAt : now,
+            updatedAt: now,
+        };
+        await store_js_1.BlobStore.insertOrUpdate(this.db, this.tableName, record);
+        if (options.autoUpload !== false && this.uploader) {
+            const isOnline = this.network ? await this.network.isOnline() : true;
+            if (isOnline) {
+                // Fire and update status
+                try {
+                    await store_js_1.BlobStore.updateStatus(this.db, this.tableName, id, 'UPLOADING');
+                    const res = await this.uploader.upload(record, bytes);
+                    record.status = 'UPLOADED';
+                    record.remoteUrl = res.remoteUrl;
+                    await store_js_1.BlobStore.updateStatus(this.db, this.tableName, id, 'UPLOADED', res.remoteUrl);
+                }
+                catch {
+                    record.status = 'FAILED';
+                    await store_js_1.BlobStore.updateStatus(this.db, this.tableName, id, 'FAILED');
+                }
+            }
+        }
+        return record;
+    }
+    /**
+     * Retrieves blob record and raw binary data.
+     */
+    async get(key) {
+        const record = await store_js_1.BlobStore.getByKey(this.db, this.tableName, key);
+        if (!record)
+            return null;
+        const data = await this.driver.read(key);
+        if (!data)
+            return null;
+        return { record, data };
+    }
+    /**
+     * Reads raw binary data for key.
+     */
+    async getData(key) {
+        return await this.driver.read(key);
+    }
+    /**
+     * Retrieves blob metadata record.
+     */
+    async getRecord(key) {
+        return await store_js_1.BlobStore.getByKey(this.db, this.tableName, key);
+    }
+    /**
+     * Lists blob metadata records, optionally filtered by upload status.
+     */
+    async list(status) {
+        return await store_js_1.BlobStore.list(this.db, this.tableName, status);
+    }
+    /**
+     * Deletes the blob binary and metadata record.
+     */
+    async delete(key) {
+        await this.driver.delete(key);
+        await store_js_1.BlobStore.deleteByKey(this.db, this.tableName, key);
+    }
+    /**
+     * Flushes and syncs pending or failed uploads to the remote storage uploader.
+     */
+    async syncPending() {
+        if (!this.uploader) {
+            return { uploaded: 0, failed: 0 };
+        }
+        const isOnline = this.network ? await this.network.isOnline() : true;
+        if (!isOnline) {
+            return { uploaded: 0, failed: 0 };
+        }
+        const pending = await store_js_1.BlobStore.list(this.db, this.tableName, 'PENDING');
+        const failedList = await store_js_1.BlobStore.list(this.db, this.tableName, 'FAILED');
+        const queue = [...pending, ...failedList];
+        let uploaded = 0;
+        let failed = 0;
+        for (const item of queue) {
+            try {
+                const data = await this.driver.read(item.key);
+                if (!data) {
+                    failed++;
+                    continue;
+                }
+                await store_js_1.BlobStore.updateStatus(this.db, this.tableName, item.id, 'UPLOADING');
+                const res = await this.uploader.upload(item, data);
+                await store_js_1.BlobStore.updateStatus(this.db, this.tableName, item.id, 'UPLOADED', res.remoteUrl);
+                uploaded++;
+            }
+            catch {
+                await store_js_1.BlobStore.updateStatus(this.db, this.tableName, item.id, 'FAILED');
+                failed++;
+            }
+        }
+        return { uploaded, failed };
+    }
+}
+exports.BlobStorageManager = BlobStorageManager;

package/dist/storage/store.d.ts

@@ -0,0 +1,14 @@
+import { DBExecutable } from '../core/schema-manager.js';
+import { BlobRecord, BlobUploadStatus } from './types.js';
+export declare const DEFAULT_BLOBS_TABLE = "_local_blobs";
+export declare function mapBlobRow(r: any): BlobRecord;
+export declare class BlobStore {
+    static ensureSchema(db: DBExecutable, tableName?: string): Promise<void>;
+    static insertOrUpdate(db: DBExecutable, tableName: string | undefined, record: BlobRecord): Promise<void>;
+    static getByKey(db: DBExecutable, tableName: string | undefined, key: string): Promise<BlobRecord | null>;
+    static getById(db: DBExecutable, tableName: string | undefined, id: string): Promise<BlobRecord | null>;
+    static list(db: DBExecutable, tableName?: string, status?: BlobUploadStatus): Promise<BlobRecord[]>;
+    static updateStatus(db: DBExecutable, tableName: string | undefined, id: string, status: BlobUploadStatus, remoteUrl?: string | null): Promise<void>;
+    static deleteByKey(db: DBExecutable, tableName: string | undefined, key: string): Promise<void>;
+    static clear(db: DBExecutable, tableName?: string): Promise<void>;
+}

package/dist/storage/store.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlobStore = exports.DEFAULT_BLOBS_TABLE = void 0;
+exports.mapBlobRow = mapBlobRow;
+exports.DEFAULT_BLOBS_TABLE = '_local_blobs';
+function mapBlobRow(r) {
+    let meta;
+    if (r.metadata) {
+        try {
+            meta = typeof r.metadata === 'string' ? JSON.parse(r.metadata) : r.metadata;
+        }
+        catch {
+            meta = undefined;
+        }
+    }
+    return {
+        id: r.id,
+        key: r.key,
+        name: r.name,
+        mimeType: r.mime_type,
+        size: Number(r.size || 0),
+        localPath: r.local_path,
+        remoteUrl: r.remote_url || null,
+        status: r.status || 'PENDING',
+        sha256: r.sha256 || null,
+        metadata: meta,
+        createdAt: Number(r.created_at || 0),
+        updatedAt: Number(r.updated_at || 0),
+    };
+}
+class BlobStore {
+    static async ensureSchema(db, tableName = exports.DEFAULT_BLOBS_TABLE) {
+        await db.execute(`CREATE TABLE IF NOT EXISTS ${tableName} (
+        id TEXT PRIMARY KEY,
+        key TEXT UNIQUE NOT NULL,
+        name TEXT NOT NULL,
+        mime_type TEXT NOT NULL,
+        size INTEGER NOT NULL,
+        local_path TEXT NOT NULL,
+        remote_url TEXT,
+        status TEXT NOT NULL,
+        sha256 TEXT,
+        metadata TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );`);
+        await db.execute(`CREATE INDEX IF NOT EXISTS idx_${tableName}_status ON ${tableName} (status);`);
+        await db.execute(`CREATE INDEX IF NOT EXISTS idx_${tableName}_key ON ${tableName} (key);`);
+    }
+    static async insertOrUpdate(db, tableName = exports.DEFAULT_BLOBS_TABLE, record) {
+        const metaStr = record.metadata ? JSON.stringify(record.metadata) : null;
+        await db.execute(`INSERT INTO ${tableName} (id, key, name, mime_type, size, local_path, remote_url, status, sha256, metadata, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(key) DO UPDATE SET
+         name = excluded.name,
+         mime_type = excluded.mime_type,
+         size = excluded.size,
+         local_path = excluded.local_path,
+         remote_url = excluded.remote_url,
+         status = excluded.status,
+         sha256 = excluded.sha256,
+         metadata = excluded.metadata,
+         updated_at = excluded.updated_at;`, [
+            record.id,
+            record.key,
+            record.name,
+            record.mimeType,
+            record.size,
+            record.localPath,
+            record.remoteUrl ?? null,
+            record.status,
+            record.sha256 ?? null,
+            metaStr,
+            record.createdAt,
+            record.updatedAt,
+        ]);
+    }
+    static async getByKey(db, tableName = exports.DEFAULT_BLOBS_TABLE, key) {
+        const rows = await db.execute(`SELECT * FROM ${tableName} WHERE key = ? LIMIT 1;`, [key]);
+        if (!rows || rows.length === 0)
+            return null;
+        return mapBlobRow(rows[0]);
+    }
+    static async getById(db, tableName = exports.DEFAULT_BLOBS_TABLE, id) {
+        const rows = await db.execute(`SELECT * FROM ${tableName} WHERE id = ? LIMIT 1;`, [id]);
+        if (!rows || rows.length === 0)
+            return null;
+        return mapBlobRow(rows[0]);
+    }
+    static async list(db, tableName = exports.DEFAULT_BLOBS_TABLE, status) {
+        let rows;
+        if (status) {
+            rows = await db.execute(`SELECT * FROM ${tableName} WHERE status = ? ORDER BY created_at DESC;`, [status]);
+        }
+        else {
+            rows = await db.execute(`SELECT * FROM ${tableName} ORDER BY created_at DESC;`);
+        }
+        return (rows || []).map(mapBlobRow);
+    }
+    static async updateStatus(db, tableName = exports.DEFAULT_BLOBS_TABLE, id, status, remoteUrl) {
+        const now = Date.now();
+        if (remoteUrl !== undefined) {
+            await db.execute(`UPDATE ${tableName} SET status = ?, remote_url = ?, updated_at = ? WHERE id = ?;`, [status, remoteUrl, now, id]);
+        }
+        else {
+            await db.execute(`UPDATE ${tableName} SET status = ?, updated_at = ? WHERE id = ?;`, [status, now, id]);
+        }
+    }
+    static async deleteByKey(db, tableName = exports.DEFAULT_BLOBS_TABLE, key) {
+        await db.execute(`DELETE FROM ${tableName} WHERE key = ?;`, [key]);
+    }
+    static async clear(db, tableName = exports.DEFAULT_BLOBS_TABLE) {
+        await db.execute(`DELETE FROM ${tableName};`);
+    }
+}
+exports.BlobStore = BlobStore;

package/dist/storage/types.d.ts

@@ -0,0 +1,44 @@
+export type BlobUploadStatus = 'PENDING' | 'UPLOADING' | 'UPLOADED' | 'FAILED';
+export interface BlobRecord {
+    id: string;
+    key: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    localPath: string;
+    remoteUrl?: string | null;
+    status: BlobUploadStatus;
+    sha256?: string | null;
+    metadata?: Record<string, any>;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface SaveBlobOptions {
+    name?: string;
+    mimeType?: string;
+    metadata?: Record<string, any>;
+    /**
+     * If true and an uploader is configured and online, triggers immediate upload.
+     * Default: true
+     */
+    autoUpload?: boolean;
+}
+export interface FileDriver {
+    write(key: string, data: Uint8Array): Promise<string>;
+    read(key: string): Promise<Uint8Array | null>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+}
+export interface RemoteStorageUploader {
+    upload(blob: BlobRecord, data: Uint8Array): Promise<{
+        remoteUrl: string;
+    }>;
+}
+export interface BlobStorageManagerOptions {
+    driver?: FileDriver;
+    uploader?: RemoteStorageUploader;
+    network?: {
+        isOnline(): boolean | Promise<boolean>;
+    };
+    tableName?: string;
+}

package/dist/storage/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-lite",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "description": "Never let a lost connection break a promise. Local-first sync that faithfully keeps data safe until you're back online.",
   "license": "MIT",
   "main": "dist/index.js",
@@ -105,6 +105,31 @@
       "types": "./dist/actions/index.d.ts",
       "import": "./dist/actions/index.js",
       "default": "./dist/actions/index.js"
+    },
+    "./keys": {
+      "types": "./dist/keys/index.d.ts",
+      "import": "./dist/keys/index.js",
+      "default": "./dist/keys/index.js"
+    },
+    "./kv": {
+      "types": "./dist/kv/index.d.ts",
+      "import": "./dist/kv/index.js",
+      "default": "./dist/kv/index.js"
+    },
+    "./search": {
+      "types": "./dist/search/index.d.ts",
+      "import": "./dist/search/index.js",
+      "default": "./dist/search/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.js",
+      "default": "./dist/storage/index.js"
+    },
+    "./scheduler": {
+      "types": "./dist/scheduler/index.d.ts",
+      "import": "./dist/scheduler/index.js",
+      "default": "./dist/scheduler/index.js"
     }
   },
   "scripts": {