opfsql 0.0.2

package/dist/store/catalog.d.ts

@@ -0,0 +1,24 @@
+import type { CatalogData, ICatalog, IndexDef, TableSchema } from "./types.js";
+export declare class Catalog implements ICatalog {
+    private _version;
+    private tables;
+    private indexes;
+    get version(): number;
+    private key;
+    hasTable(name: string): boolean;
+    getTable(name: string): TableSchema | undefined;
+    addTable(schema: TableSchema): void;
+    removeTable(name: string): void;
+    updateTable(schema: TableSchema): void;
+    getAllTables(): TableSchema[];
+    hasIndex(name: string): boolean;
+    getIndex(name: string): IndexDef | undefined;
+    getTableIndexes(tableName: string): IndexDef[];
+    addIndex(index: IndexDef): void;
+    removeIndex(name: string): void;
+    prepareCommit(): CatalogData;
+    serialize(): CatalogData;
+    snapshot(): CatalogData;
+    clone(): Catalog;
+    static deserialize(data: CatalogData): Catalog;
+}

package/dist/store/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class StorageError extends Error {
+    readonly name = "StorageError";
+    constructor(message: string, cause?: unknown);
+}
+export declare function wrapStorageError(err: unknown): StorageError;

package/dist/store/index-btree/compare.d.ts

@@ -0,0 +1,3 @@
+import type { IndexKey } from "./types.js";
+export declare function compareIndexKeys(a: IndexKey, b: IndexKey): number;
+export declare function keyHasNull(key: IndexKey): boolean;

package/dist/store/index-btree/index-btree.d.ts

@@ -0,0 +1,53 @@
+import type { RowId, SyncIPageStore } from "../types.js";
+import type { IndexKey, RangeOptions } from "./types.js";
+export type { RangeOptions } from "./types.js";
+export declare class SyncBTree {
+    private readonly metaPageNo;
+    private readonly pageStore;
+    private readonly unique;
+    constructor(metaPageNo: number, pageStore: SyncIPageStore, unique?: boolean);
+    insert(userKey: IndexKey, rowId: RowId): void;
+    delete(userKey: IndexKey, rowId: RowId): void;
+    lookup(userKey: IndexKey): RowId[];
+    range(opts?: RangeOptions): RowId[];
+    bulkLoad(entries: Array<{
+        key: IndexKey;
+        rowId: RowId;
+    }>): void;
+    drop(): void;
+    /** Return the entry with the smallest non-null key, or null if empty. */
+    first(): {
+        key: IndexKey;
+        rowId: RowId;
+    } | null;
+    /** Return the entry with the largest non-null key, or null if empty. */
+    last(): {
+        key: IndexKey;
+        rowId: RowId;
+    } | null;
+    private insertIntoLeaf;
+    private removeFromLeaf;
+    private existsWithPrefix;
+    private findLeftmostLeaf;
+    private findRightmostLeaf;
+    private collectRange;
+    private isBelowLower;
+    private isAboveUpper;
+    private checkUniqueSorted;
+    private buildLeaves;
+    private linkAndWriteLeaves;
+    private buildInternalLevels;
+    private splitLeaf;
+    private propagateSplit;
+    private splitInternal;
+    private createNewRoot;
+    private findLeafPath;
+    private bisectLeft;
+    private bisectRight;
+    private freeSubtree;
+    private readMeta;
+    private writeMeta;
+    private readNode;
+    private writeNode;
+    private createLeaf;
+}

package/dist/store/index-btree/search-bounds.d.ts

@@ -0,0 +1,7 @@
+import type { IndexKeyValue, RangeOptions } from "./types.js";
+export interface SearchPredicate {
+    columnPosition: number;
+    comparisonType: "EQUAL" | "LESS" | "GREATER" | "LESS_EQUAL" | "GREATER_EQUAL";
+    value: IndexKeyValue;
+}
+export declare function computeBounds(predicates: SearchPredicate[]): RangeOptions;

package/dist/store/index-btree/types.d.ts

@@ -0,0 +1,27 @@
+export type IndexKeyValue = string | number | boolean | null;
+export type IndexKey = IndexKeyValue[];
+export interface BTreeLeafNode {
+    kind: "leaf";
+    nodeId: number;
+    keys: IndexKey[];
+    nextLeafId: number | null;
+}
+export interface BTreeInternalNode {
+    kind: "internal";
+    nodeId: number;
+    keys: IndexKey[];
+    children: number[];
+}
+export type BTreeNode = BTreeLeafNode | BTreeInternalNode;
+export interface BTreeMeta {
+    rootNodeId: number;
+    height: number;
+    size: number;
+}
+export interface RangeOptions {
+    lower?: IndexKey;
+    upper?: IndexKey;
+    lowerInclusive?: boolean;
+    upperInclusive?: boolean;
+}
+export declare const ORDER = 128;

package/dist/store/index-expression.d.ts

@@ -0,0 +1,5 @@
+import type { BoundExpression } from "../binder/types.js";
+import type { IndexExpression, TableSchema } from "../types.js";
+export declare function boundToIndexExpression(expr: BoundExpression, schema: TableSchema): IndexExpression;
+export declare function bindIndexExpression(expr: IndexExpression, schema: TableSchema, tableIndex: number): BoundExpression;
+export declare function getIndexColumns(expr: IndexExpression): string[];

package/dist/store/index-manager.d.ts

@@ -0,0 +1,23 @@
+import type { ICatalog, IndexKey, RowId, SearchPredicate, SyncIIndexManager, SyncIPageStore } from "./types.js";
+export declare class SyncIndexManager implements SyncIIndexManager {
+    private readonly ps;
+    private readonly getCatalog;
+    constructor(ps: SyncIPageStore, getCatalog: () => ICatalog);
+    private tree;
+    insert(indexName: string, key: IndexKey, rowId: RowId): void;
+    delete(indexName: string, key: IndexKey, rowId: RowId): void;
+    search(indexName: string, predicates: SearchPredicate[]): RowId[];
+    bulkLoad(indexName: string, entries: Array<{
+        key: IndexKey;
+        rowId: RowId;
+    }>, unique: boolean): number;
+    dropIndex(indexName: string): void;
+    first(indexName: string): {
+        key: IndexKey;
+        rowId: RowId;
+    } | null;
+    last(indexName: string): {
+        key: IndexKey;
+        rowId: RowId;
+    } | null;
+}

package/dist/store/index.d.ts

@@ -0,0 +1,10 @@
+export { SyncBTree } from "./index-btree/index-btree.js";
+export { SyncIndexManager } from "./index-manager.js";
+export { OPFSSyncStorage } from "./backend/opfs-storage.js";
+export { SessionStore } from "./session-store.js";
+export { Storage } from "./storage.js";
+export { SyncTableBTree } from "./table-btree.js";
+export { SyncTableManager } from "./table-manager.js";
+export { WalStorage } from "./wal/wal-storage.js";
+export type { ISyncFileHandle } from "./wal/file-handle.js";
+export type { CatalogData, ColumnDef, ICatalog, IndexDef, IndexKey, IndexKeyValue, LogicalType, Row, RowId, SearchPredicate, SyncIIndexManager, SyncIPageStore, SyncIPageStorage, SyncIRowManager, TableSchema, Value, } from "./types.js";

package/dist/store/memory-storage.d.ts

@@ -0,0 +1,13 @@
+import type { SyncIStorage } from "./types.js";
+/**
+ * Test-only in-memory SyncIStorage. Uses structuredClone to mimic real storage
+ * (no shared references between stored and returned values).
+ */
+export declare class MemoryStorage implements SyncIStorage {
+    private data;
+    open(): Promise<void>;
+    close(): void;
+    get<T>(key: string): T | null;
+    putMany(entries: Array<[string, unknown]>): void;
+    getAllKeys(prefix: string): string[];
+}

package/dist/store/opfs/opfs-storage.d.ts

@@ -0,0 +1,15 @@
+import type { IStorage } from '../types.js';
+export declare class OPFSStorage implements IStorage {
+    private readonly dbName;
+    private dir;
+    constructor(dbName: string);
+    open(): Promise<void>;
+    close(): void;
+    get<T>(key: string): Promise<T | null>;
+    put(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    putMany(entries: Array<[string, unknown]>): Promise<void>;
+    getAllKeys(prefix: string): Promise<string[]>;
+    private encodeKey;
+    private decodeKey;
+}

package/dist/store/opfs-storage.d.ts

@@ -0,0 +1,44 @@
+import type { SyncIStorage } from './types.js';
+interface FileSystemSyncAccessHandle {
+    getSize(): number;
+    read(buffer: Uint8Array, options?: {
+        at?: number;
+    }): number;
+    write(buffer: Uint8Array, options?: {
+        at?: number;
+    }): number;
+    truncate(size: number): void;
+    flush(): void;
+    close(): void;
+}
+declare global {
+    interface FileSystemFileHandle {
+        createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>;
+    }
+}
+export declare class OPFSSyncStorage implements SyncIStorage {
+    private readonly dbName;
+    private handle;
+    private pageSize;
+    private nextPageId;
+    private freeListHead;
+    private indexOffset;
+    private indexLength;
+    private index;
+    constructor(dbName: string);
+    open(): Promise<void>;
+    close(): void;
+    get<T>(key: string): T | null;
+    getAllKeys(prefix: string): string[];
+    putMany(entries: Array<[string, unknown]>): void;
+    private initNewFile;
+    private readHeader;
+    private writeHeader;
+    private readIndex;
+    private persistIndex;
+    private readPageData;
+    private writePageData;
+    private freePage;
+    private allocPage;
+}
+export {};

package/dist/store/page-manager.d.ts

@@ -0,0 +1,19 @@
+import type { SyncIPageStorage, SyncIPageStore } from "./types.js";
+export declare class SyncPageStore implements SyncIPageStore {
+    private readonly storage;
+    private wal;
+    private cache;
+    private nextPageId;
+    private freeList;
+    private allocatorDirty;
+    private snapNextPageId;
+    private snapFreeList;
+    constructor(storage: SyncIPageStorage, nextPageId: number, freeList: number[], cacheSize?: number);
+    readPage<T>(pageNo: number): T | null;
+    writePage(pageNo: number, value: unknown): void;
+    allocPage(): number;
+    freePage(pageNo: number): void;
+    commit(): void;
+    rollback(): void;
+    private ensureSnapshot;
+}

package/dist/store/row-manager.d.ts

@@ -0,0 +1,15 @@
+import type { IPageManager, IRowManager, Row, RowId } from './types.js';
+export declare class RowManager implements IRowManager {
+    private readonly pm;
+    constructor(pm: IPageManager);
+    prepareInsert(tableId: string, row: Row): Promise<RowId>;
+    prepareUpdate(tableId: string, rowId: RowId, row: Row): Promise<RowId>;
+    prepareDelete(tableId: string, rowId: RowId): Promise<void>;
+    scanTable(tableId: string): AsyncGenerator<{
+        rowId: RowId;
+        row: Row;
+    }>;
+    readRow(tableId: string, rowId: RowId): Promise<Row | null>;
+    private liveRowCount;
+    private requirePage;
+}

package/dist/store/session-store.d.ts

@@ -0,0 +1,20 @@
+import type { Storage } from "./storage.js";
+import type { CatalogData, SyncIPageStore } from "./types.js";
+export declare class SessionStore implements SyncIPageStore {
+    private readonly storage;
+    private readonly catalogPageNo;
+    private buffer;
+    private allocatorDirty;
+    private snapNextPageId;
+    private snapFreeList;
+    constructor(storage: Storage, catalogPageNo: number);
+    readPage<T>(pageNo: number): T | null;
+    writePage(pageNo: number, value: unknown): void;
+    allocPage(): number;
+    freePage(pageNo: number): void;
+    commit(): void;
+    rollback(): void;
+    writeCatalog(data: CatalogData): void;
+    private ensureSnapshot;
+    private clearSnapshot;
+}

package/dist/store/storage/memory-storage.d.ts

@@ -0,0 +1,11 @@
+import type { IStorage } from '../types.js';
+export declare class MemoryStorage implements IStorage {
+    private data;
+    open(): Promise<void>;
+    close(): void;
+    get<T>(key: string): Promise<T | null>;
+    put(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    putMany(entries: Array<[string, unknown]>): Promise<void>;
+    getAllKeys(prefix: string): Promise<string[]>;
+}

package/dist/store/storage/opfs-storage.d.ts

@@ -0,0 +1,15 @@
+import type { IStorage } from '../types.js';
+export declare class OPFSStorage implements IStorage {
+    private readonly dbName;
+    private dir;
+    constructor(dbName: string);
+    open(): Promise<void>;
+    close(): void;
+    get<T>(key: string): Promise<T | null>;
+    put(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    putMany(entries: Array<[string, unknown]>): Promise<void>;
+    getAllKeys(prefix: string): Promise<string[]>;
+    private encodeKey;
+    private decodeKey;
+}

package/dist/store/storage.d.ts

@@ -0,0 +1,28 @@
+import { SessionStore } from "./session-store.js";
+import type { CatalogData, SyncIPageStorage } from "./types.js";
+export interface CatchUpResult {
+    catalog: boolean;
+    data: boolean;
+}
+export declare class Storage {
+    private readonly backend;
+    private nextPageId;
+    private freeList;
+    constructor(backend: SyncIPageStorage);
+    open(): Promise<void>;
+    createSession(): SessionStore;
+    readPage<T>(pageNo: number): T | null;
+    allocPage(): number;
+    freePage(pageNo: number): void;
+    snapshotAllocator(): {
+        nextPageId: number;
+        freeList: number[];
+    };
+    restoreAllocator(nextPageId: number, freeList: number[]): void;
+    commitPages(dirtyPages: Map<number, unknown>, allocatorDirty: boolean): void;
+    readCatalog(): CatalogData | null;
+    catchUp(): CatchUpResult | null;
+    checkpoint(): void;
+    close(): void;
+    private refreshFromStorage;
+}

package/dist/store/table-btree.d.ts

@@ -0,0 +1,48 @@
+import type { Row, RowId, SyncIPageStore } from "./types.js";
+export interface TableLeafNode {
+    kind: "leaf";
+    nodeId: number;
+    keys: number[];
+    values: Row[];
+    nextLeafId: number | null;
+}
+export interface TableInternalNode {
+    kind: "internal";
+    nodeId: number;
+    keys: number[];
+    children: number[];
+}
+export type TableNode = TableLeafNode | TableInternalNode;
+export interface TableBTreeMeta {
+    rootNodeId: number;
+    height: number;
+    nextRowId: number;
+    size: number;
+}
+export declare class SyncTableBTree {
+    private readonly metaPageNo;
+    private readonly ps;
+    constructor(metaPageNo: number, ps: SyncIPageStore);
+    insert(row: Row): RowId;
+    get(rowId: RowId): Row | null;
+    update(rowId: RowId, row: Row): void;
+    delete(rowId: RowId): void;
+    scan(): Generator<{
+        rowId: RowId;
+        row: Row;
+    }>;
+    drop(): void;
+    private freeSubtree;
+    private splitLeaf;
+    private propagateSplit;
+    private splitInternal;
+    private createNewRoot;
+    private findLeafPath;
+    private findLeftmostLeaf;
+    private bisectLeft;
+    private bisectRight;
+    private readMeta;
+    private writeMeta;
+    private readNode;
+    private writeNode;
+}

package/dist/store/table-manager.d.ts

@@ -0,0 +1,17 @@
+import type { ICatalog, Row, RowId, SyncIPageStore, SyncIRowManager } from "./types.js";
+export declare class SyncTableManager implements SyncIRowManager {
+    private readonly ps;
+    private readonly getCatalog;
+    constructor(ps: SyncIPageStore, getCatalog: () => ICatalog);
+    private tree;
+    createTable(): number;
+    prepareInsert(tableId: string, row: Row): RowId;
+    prepareUpdate(tableId: string, rowId: RowId, row: Row): RowId;
+    prepareDelete(tableId: string, rowId: RowId): void;
+    scanTable(tableId: string): Generator<{
+        rowId: RowId;
+        row: Row;
+    }>;
+    readRow(tableId: string, rowId: RowId): Row | null;
+    deleteTableData(tableId: string): void;
+}

package/dist/store/tests/btree.test.d.ts

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

package/dist/store/tests/catalog.test.d.ts

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

package/dist/store/tests/compare.test.d.ts

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

package/dist/store/tests/index-btree.test.d.ts

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

package/dist/store/tests/index-expression.test.d.ts

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

package/dist/store/tests/index-manager.test.d.ts

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

package/dist/store/tests/lru-cache.test.d.ts

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

package/dist/store/tests/memory-storage.d.ts

@@ -0,0 +1,15 @@
+import type { IStorage } from '../types.js';
+/**
+ * Test-only MemoryStorage that uses structuredClone to mimic real storage
+ * (no shared references between stored and returned values).
+ */
+export declare class MemoryStorage implements IStorage {
+    private data;
+    open(): Promise<void>;
+    close(): void;
+    get<T>(key: string): Promise<T | null>;
+    put(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    putMany(entries: Array<[string, unknown]>): Promise<void>;
+    getAllKeys(prefix: string): Promise<string[]>;
+}

package/dist/store/tests/opfs-storage.test.d.ts

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

package/dist/store/tests/page-manager.test.d.ts

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

package/dist/store/tests/row-manager.test.d.ts

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

package/dist/store/tests/search-bounds.test.d.ts

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

package/dist/store/tests/storage.test.d.ts

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

package/dist/store/tests/table-btree.test.d.ts

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

package/dist/store/tests/vacuum.test.d.ts

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

package/dist/store/tests/wal-storage.test.d.ts

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

package/dist/store/types.d.ts

@@ -0,0 +1,75 @@
+export type { CatalogData, ColumnDef, IndexDef, IndexExpression, JsonValue, LogicalType, Row, RowId, TableSchema, Value, } from "../types.js";
+export type { SearchPredicate } from "./index-btree/search-bounds.js";
+export type { IndexKey, IndexKeyValue } from "./index-btree/types.js";
+import type { CatalogData, IndexDef, Row, RowId, TableSchema } from "../types.js";
+import type { SearchPredicate } from "./index-btree/search-bounds.js";
+import type { IndexKey } from "./index-btree/types.js";
+export interface ICatalog {
+    hasTable(name: string): boolean;
+    getTable(name: string): TableSchema | undefined;
+    addTable(schema: TableSchema): void;
+    removeTable(name: string): void;
+    updateTable(schema: TableSchema): void;
+    getAllTables(): TableSchema[];
+    hasIndex(name: string): boolean;
+    getIndex(name: string): IndexDef | undefined;
+    getTableIndexes(tableName: string): IndexDef[];
+    addIndex(index: IndexDef): void;
+    removeIndex(name: string): void;
+    serialize(): CatalogData;
+}
+export interface SyncIPageStorage {
+    open(): Promise<void>;
+    close(): void;
+    readPage<T>(pageNo: number): T | null;
+    writePage(pageNo: number, value: unknown): void;
+    getNextPageId(): number;
+    writeHeader(nextPageId: number): void;
+    flush(): void;
+    /** Shrink backing file to match nextPageId. Safe only after flush(). */
+    truncateToSize?(): void;
+    /** Catch up with changes made by other writers. Returns set of changed page numbers, or null if nothing changed. */
+    catchUp?(): Set<number> | null;
+    /** Merge WAL into main DB and reset WAL. */
+    checkpoint?(): void;
+}
+export interface SyncIPageStore {
+    readPage<T>(pageNo: number): T | null;
+    writePage(pageNo: number, value: unknown): void;
+    allocPage(): number;
+    freePage(pageNo: number): void;
+    commit(): void;
+    rollback(): void;
+}
+export interface SyncIRowManager {
+    createTable(): number;
+    prepareInsert(tableId: string, row: Row): RowId;
+    prepareUpdate(tableId: string, rowId: RowId, row: Row): RowId;
+    prepareDelete(tableId: string, rowId: RowId): void;
+    scanTable(tableId: string): Iterable<{
+        rowId: RowId;
+        row: Row;
+    }>;
+    readRow(tableId: string, rowId: RowId): Row | null;
+    deleteTableData(tableId: string): void;
+}
+export interface SyncIIndexManager {
+    insert(indexName: string, key: IndexKey, rowId: RowId): void;
+    delete(indexName: string, key: IndexKey, rowId: RowId): void;
+    search(indexName: string, predicates: SearchPredicate[]): RowId[];
+    bulkLoad(indexName: string, entries: Array<{
+        key: IndexKey;
+        rowId: RowId;
+    }>, unique: boolean): number;
+    dropIndex(indexName: string): void;
+    /** Smallest non-null key in the index, or null. */
+    first(indexName: string): {
+        key: IndexKey;
+        rowId: RowId;
+    } | null;
+    /** Largest non-null key in the index, or null. */
+    last(indexName: string): {
+        key: IndexKey;
+        rowId: RowId;
+    } | null;
+}

package/dist/store/vacuum.d.ts

@@ -0,0 +1,12 @@
+import type { IPageManager, ICatalog, IVacuum } from './types.js';
+import type { IIndexManager } from './index-manager.js';
+export declare class Vacuum implements IVacuum {
+    private readonly pm;
+    catalog?: ICatalog;
+    indexManager?: IIndexManager;
+    constructor(pm: IPageManager);
+    shouldVacuum(tableId: string): Promise<boolean>;
+    vacuumTable(tableId: string): Promise<void>;
+    vacuumIfNeeded(tableId: string): Promise<void>;
+    private rebuildIndexes;
+}

package/dist/store/wal/crc32.d.ts

@@ -0,0 +1 @@
+export declare function crc32(data: Uint8Array): number;

package/dist/store/wal/file-handle.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Abstraction over FileSystemSyncAccessHandle for testability.
+ * In OPFS workers, the real handle is used directly.
+ * In tests, MemoryFileHandle provides an ArrayBuffer-backed implementation.
+ */
+export interface ISyncFileHandle {
+    read(buffer: Uint8Array, options?: {
+        at?: number;
+    }): number;
+    write(buffer: Uint8Array, options?: {
+        at?: number;
+    }): number;
+    getSize(): number;
+    truncate(size: number): void;
+    flush(): void;
+    close(): void;
+}
+export declare class MemoryFileHandle implements ISyncFileHandle {
+    private buf;
+    private size;
+    constructor(initialCapacity?: number);
+    read(buffer: Uint8Array, options?: {
+        at?: number;
+    }): number;
+    write(buffer: Uint8Array, options?: {
+        at?: number;
+    }): number;
+    getSize(): number;
+    truncate(size: number): void;
+    flush(): void;
+    close(): void;
+    /** Test helper: return a copy of the underlying data. */
+    snapshot(): Uint8Array;
+}