opfsql 0.0.2

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

@@ -0,0 +1,50 @@
+import type { SyncIPageStorage } from "../types.js";
+import type { ISyncFileHandle } from "./file-handle.js";
+export declare class WalStorage implements SyncIPageStorage {
+    private readonly main;
+    private readonly walHandle;
+    private readonly checkpointThreshold;
+    /** Committed WAL pages: pageNo → decoded value. */
+    private walIndex;
+    /** Frames buffered during current uncommitted batch (between writePage calls and flush). */
+    private pendingFrames;
+    /** Current write position in WAL file. */
+    private walOffset;
+    /** Next transaction id to assign. */
+    private currentTxId;
+    /** Committed nextPageId (from the latest commit record or main DB). */
+    private nextPageId;
+    /** Number of committed data frames in the WAL (for auto-checkpoint). */
+    private walFrameCount;
+    /** WAL epoch — incremented on each checkpoint. */
+    private epoch;
+    constructor(main: SyncIPageStorage, walHandle: ISyncFileHandle, checkpointThreshold?: number);
+    open(): Promise<void>;
+    close(): void;
+    /** Returns committed data only. Pending (unflushed) writes are not visible. */
+    readPage<T>(pageNo: number): T | null;
+    writePage(pageNo: number, value: unknown): void;
+    getNextPageId(): number;
+    writeHeader(nextPageId: number): void;
+    flush(): void;
+    getEpoch(): number;
+    checkpoint(): void;
+    /** Check if WAL has changed and catch up. Returns set of changed page numbers, or null if nothing changed. */
+    catchUp(): Set<number> | null;
+    private resetAfterCheckpoint;
+    private recover;
+    private readAndVerifyHeader;
+    /** Read epoch directly from WAL file header (for catch-up checks). */
+    private readEpochFromFile;
+    /**
+     * Read frames from startOffset to endOffset.
+     * Only advances walOffset to the end of the last valid commit record.
+     * Updates walIndex, nextPageId, currentTxId, walFrameCount.
+     * Returns set of committed page numbers.
+     */
+    private readFramesFrom;
+    /** Build a single buffer containing all data frames + commit record. */
+    private buildCommitBuffer;
+    private initWalHeader;
+    private computeChecksum;
+}

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+export type LogicalType = 'INTEGER' | 'BIGINT' | 'REAL' | 'TEXT' | 'BLOB' | 'BOOLEAN' | 'JSON' | 'NULL' | 'ANY';
+export type JsonValue = {
+    [key: string]: JsonValue;
+} | JsonValue[] | string | number | boolean | null;
+export type Value = string | number | boolean | null | JsonValue | Uint8Array;
+export type JsonPathSegment = {
+    type: 'field';
+    name: string;
+} | {
+    type: 'index';
+    value: number;
+};
+export interface ColumnDef {
+    name: string;
+    type: LogicalType;
+    nullable: boolean;
+    primaryKey: boolean;
+    unique: boolean;
+    autoIncrement: boolean;
+    defaultValue: Value;
+}
+export interface TableSchema {
+    name: string;
+    columns: ColumnDef[];
+    autoIncrementSeq?: number;
+    metaPageNo?: number;
+}
+export type IndexOperatorType = 'NOT' | 'IS_NULL' | 'IS_NOT_NULL' | 'NEGATE' | 'IN' | 'NOT_IN' | 'ADD' | 'SUBTRACT' | 'MULTIPLY' | 'DIVIDE' | 'MOD' | 'CONCAT';
+export interface IndexCaseCheck {
+    when: IndexExpression;
+    then: IndexExpression;
+}
+export type IndexComparisonType = 'EQUAL' | 'NOT_EQUAL' | 'LESS' | 'GREATER' | 'LESS_EQUAL' | 'GREATER_EQUAL';
+export type IndexExpression = {
+    type: 'column';
+    name: string;
+    returnType: LogicalType;
+} | {
+    type: 'json_access';
+    column: string;
+    path: JsonPathSegment[];
+    returnType: LogicalType;
+} | {
+    type: 'function';
+    name: string;
+    args: IndexExpression[];
+    returnType: LogicalType;
+} | {
+    type: 'cast';
+    child: IndexExpression;
+    castType: LogicalType;
+    returnType: LogicalType;
+} | {
+    type: 'operator';
+    operatorType: IndexOperatorType;
+    args: IndexExpression[];
+    returnType: LogicalType;
+} | {
+    type: 'comparison';
+    comparisonType: IndexComparisonType;
+    left: IndexExpression;
+    right: IndexExpression;
+    returnType: LogicalType;
+} | {
+    type: 'case';
+    checks: IndexCaseCheck[];
+    elseExpr: IndexExpression | null;
+    returnType: LogicalType;
+} | {
+    type: 'constant';
+    value: string | number | boolean | null;
+    returnType: LogicalType;
+};
+export interface IndexDef {
+    name: string;
+    tableName: string;
+    expressions: IndexExpression[];
+    unique: boolean;
+    metaPageNo?: number;
+}
+export interface CatalogData {
+    version: number;
+    tables: TableSchema[];
+    indexes: IndexDef[];
+}
+export type RowId = number;
+export type Row = Record<string, Value>;

package/dist/worker/client.d.ts

@@ -0,0 +1,36 @@
+import type { Result } from "../engine/index.js";
+import type { CatalogData, Value } from "../types.js";
+import type { RequestPayload } from "./protocol.js";
+export declare class RemotePreparedStatement {
+    private readonly connection;
+    readonly stmtId: number;
+    constructor(connection: Connection, stmtId: number);
+    run(params?: Value[]): Promise<Result>;
+    free(): Promise<void>;
+}
+export declare class Connection {
+    private readonly engine;
+    readonly sessionId: string;
+    constructor(engine: WorkerEngine, sessionId: string);
+    exec(sql: string, params?: Value[]): Promise<Result[]>;
+    prepare(sql: string): Promise<RemotePreparedStatement>;
+    /** @internal used by RemotePreparedStatement */
+    run(stmtId: number, params: Value[]): Promise<Result>;
+    /** @internal used by RemotePreparedStatement */
+    freeStmt(stmtId: number): Promise<void>;
+    getSchema(): Promise<CatalogData>;
+    disconnect(): Promise<void>;
+}
+export declare class WorkerEngine {
+    private readonly worker;
+    private readonly pending;
+    private seq;
+    constructor(workerUrl: string | URL);
+    open(dbName: string): Promise<void>;
+    close(): Promise<void>;
+    connect(): Promise<Connection>;
+    /** @internal */
+    rpc<T = {
+        ok: true;
+    }>(payload: RequestPayload): Promise<T>;
+}

package/dist/worker/index.d.ts

@@ -0,0 +1 @@
+export { WorkerEngine, Connection, RemotePreparedStatement } from './client.js';

package/dist/worker/protocol.d.ts

@@ -0,0 +1,59 @@
+import type { Result } from "../engine/index.js";
+import type { CatalogData } from "../store/types.js";
+import type { Value } from "../types.js";
+export type RequestPayload = {
+    type: "open";
+    dbName: string;
+} | {
+    type: "close";
+} | {
+    type: "connect";
+} | {
+    type: "disconnect";
+    sessionId: string;
+} | {
+    type: "disconnect-all";
+} | {
+    type: "exec";
+    sessionId: string;
+    sql: string;
+    params?: Value[];
+} | {
+    type: "prepare";
+    sessionId: string;
+    sql: string;
+} | {
+    type: "run";
+    sessionId: string;
+    stmtId: number;
+    params?: Value[];
+} | {
+    type: "free";
+    sessionId: string;
+    stmtId: number;
+} | {
+    type: "schema";
+    sessionId: string;
+};
+export type RequestMessage = {
+    id: number;
+} & RequestPayload;
+export type ResponseMessage = {
+    id: number;
+    ok: true;
+} | {
+    id: number;
+    results: Result[];
+} | {
+    id: number;
+    sessionId: string;
+} | {
+    id: number;
+    stmtId: number;
+} | {
+    id: number;
+    schema: CatalogData;
+} | {
+    id: number;
+    error: string;
+};

package/dist/worker/worker.d.ts

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

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "opfsql",
+  "version": "0.0.2",
+  "description": "Lightweight SQL engine in TypeScript. ~40 KB gzipped, zero native deps. Runs in browser workers via OPFS.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "npx playwright test --config test/e2e/infra/config.ts",
+    "build": "cp ../README.md ./README.md && cp ../LICENSE ./LICENSE && esbuild src/index.ts --bundle --format=esm --outfile=dist/index.js --external:cbor-x --minify && tsc --emitDeclarationOnly --outDir dist"
+  },
+  "keywords": [
+    "sql",
+    "opfs",
+    "indexeddb",
+    "browser",
+    "database",
+    "sqlite",
+    "in-browser",
+    "worker",
+    "typescript"
+  ],
+  "author": "talerok",
+  "license": "MIT",
+  "homepage": "https://github.com/talerok/opfsql#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/talerok/opfsql.git",
+    "directory": "opfsql-lib"
+  },
+  "bugs": {
+    "url": "https://github.com/talerok/opfsql/issues"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.52.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "esbuild": "^0.28.0",
+    "opfs-mock": "^2.6.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "cbor-x": "^1.6.4"
+  }
+}