@concavejs/docstore-expo-sqlite 0.0.1-alpha.8

package/dist/expo-sql-adapter.d.ts

@@ -0,0 +1,51 @@
+import { type PreparedStatement, type RowResult, type SqlParam, type SqliteAdapter, type TransactionFn } from "@concavejs/docstore-sqlite-base";
+export type ExpoSqlBindValues = unknown[] | Record<string, unknown>;
+export interface BusyRetryOptions {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffFactor?: number;
+}
+export interface ExpoSqlAdapterOptions {
+    applyPragmas?: boolean;
+    schemaVersion?: number;
+    metadataTableName?: string;
+    busyRetry?: BusyRetryOptions;
+}
+/**
+ * Minimal shape required from expo-sqlite database instances.
+ *
+ * This uses structural typing on purpose so the adapter doesn't need to import
+ * from expo-sqlite directly to build and test in non-Expo environments.
+ */
+export interface ExpoSqlDatabaseLike {
+    execAsync(source: string): Promise<unknown>;
+    runAsync(source: string, ...params: unknown[]): Promise<unknown>;
+    getAllAsync<T = RowResult>(source: string, ...params: unknown[]): Promise<T[]>;
+}
+export type ExpoSqlDatabase = ExpoSqlDatabaseLike;
+export declare function createExpoSqlDatabase(database: ExpoSqlDatabaseLike): ExpoSqlDatabase;
+export declare class ExpoSqlAdapter implements SqliteAdapter {
+    private readonly database;
+    private readonly runSerializedTransaction;
+    private readonly schemaVersion;
+    private readonly metadataTableName;
+    private readonly applyPragmas;
+    private readonly busyRetry;
+    private initPromise?;
+    constructor(database: ExpoSqlDatabase, options?: ExpoSqlAdapterOptions);
+    exec(sql: string): Promise<void>;
+    prepare(sql: string): PreparedStatement;
+    transaction<T>(fn: TransactionFn<T>): Promise<T>;
+    hexToBuffer(hex: string): SqlParam;
+    bufferToHex(buffer: unknown): string;
+    executeWithRetry(sql: string, bindValues?: ExpoSqlBindValues): Promise<void>;
+    selectWithRetry<T = RowResult>(sql: string, bindValues?: ExpoSqlBindValues): Promise<T[]>;
+    private ensureInitialized;
+    private initialize;
+    private migrate;
+    private withBusyRetry;
+    private executeRaw;
+    private selectRaw;
+    private tryExecRaw;
+}

package/dist/expo-sql-adapter.js

@@ -0,0 +1,264 @@
+import { arrayBufferToHex, hexToArrayBuffer } from "@concavejs/core/utils";
+import { createSerializedTransactionRunner, } from "@concavejs/docstore-sqlite-base";
+const DEFAULT_SCHEMA_VERSION = 1;
+const SCHEMA_VERSION_KEY = "docstore_schema_version";
+const DEFAULT_METADATA_TABLE = "concave_meta";
+const NATIVE_TIMERS_SYMBOL = Symbol.for("@concavejs/core/native-timers");
+export function createExpoSqlDatabase(database) {
+    return {
+        execAsync: (source) => database.execAsync(source),
+        runAsync: (source, ...params) => database.runAsync(source, ...params),
+        getAllAsync: (source, ...params) => database.getAllAsync(source, ...params),
+    };
+}
+class ExpoPreparedStatement {
+    constructor(adapter, sql) {
+        this.adapter = adapter;
+        this.sql = sql;
+    }
+    async get(...params) {
+        const rows = await this.adapter.selectWithRetry(this.sql, normalizeSqlParams(params));
+        return rows[0] ?? null;
+    }
+    async all(...params) {
+        return this.adapter.selectWithRetry(this.sql, normalizeSqlParams(params));
+    }
+    async run(...params) {
+        await this.adapter.executeWithRetry(this.sql, normalizeSqlParams(params));
+    }
+}
+export class ExpoSqlAdapter {
+    constructor(database, options = {}) {
+        this.database = database;
+        this.schemaVersion = normalizeSchemaVersion(options.schemaVersion ?? DEFAULT_SCHEMA_VERSION);
+        this.metadataTableName = sanitizeIdentifier(options.metadataTableName ?? DEFAULT_METADATA_TABLE);
+        this.applyPragmas = options.applyPragmas !== false;
+        this.busyRetry = normalizeBusyRetryOptions(options.busyRetry);
+        this.runSerializedTransaction = createSerializedTransactionRunner({
+            begin: async () => {
+                await this.executeWithRetry("BEGIN IMMEDIATE");
+            },
+            commit: async () => {
+                await this.executeWithRetry("COMMIT");
+            },
+            rollback: async () => {
+                await this.executeWithRetry("ROLLBACK");
+            },
+        });
+    }
+    async exec(sql) {
+        for (const statement of splitSqlStatements(sql)) {
+            await this.executeWithRetry(statement);
+        }
+    }
+    prepare(sql) {
+        return new ExpoPreparedStatement(this, sql);
+    }
+    async transaction(fn) {
+        return this.runSerializedTransaction(fn);
+    }
+    hexToBuffer(hex) {
+        return new Uint8Array(hexToArrayBuffer(hex));
+    }
+    bufferToHex(buffer) {
+        return arrayBufferToHex(coerceSqlBlob(buffer));
+    }
+    async executeWithRetry(sql, bindValues) {
+        await this.ensureInitialized();
+        await this.withBusyRetry(async () => {
+            await this.executeRaw(sql, bindValues);
+            return undefined;
+        });
+    }
+    async selectWithRetry(sql, bindValues) {
+        await this.ensureInitialized();
+        return this.withBusyRetry(() => this.selectRaw(sql, bindValues));
+    }
+    async ensureInitialized() {
+        if (!this.initPromise) {
+            this.initPromise = this.initialize();
+        }
+        await this.initPromise;
+    }
+    async initialize() {
+        await this.withBusyRetry(() => this.executeRaw(`CREATE TABLE IF NOT EXISTS ${this.metadataTableName} (key TEXT PRIMARY KEY, value TEXT NOT NULL)`));
+        const rows = await this.withBusyRetry(() => this.selectRaw(`SELECT value FROM ${this.metadataTableName} WHERE key = ?`, [SCHEMA_VERSION_KEY]));
+        const existingVersion = rows.length > 0 ? Number(rows[0]?.value) : undefined;
+        if (existingVersion === undefined || !Number.isFinite(existingVersion)) {
+            await this.withBusyRetry(() => this.executeRaw(`INSERT OR REPLACE INTO ${this.metadataTableName} (key, value) VALUES (?, ?)`, [SCHEMA_VERSION_KEY, String(this.schemaVersion)]));
+        }
+        else if (!Number.isInteger(existingVersion) || existingVersion <= 0) {
+            throw new Error(`Invalid persisted docstore schema version: ${rows[0]?.value}`);
+        }
+        else if (existingVersion > this.schemaVersion) {
+            throw new Error(`Persisted docstore schema version ${existingVersion} is newer than supported version ${this.schemaVersion}`);
+        }
+        else if (existingVersion < this.schemaVersion) {
+            await this.migrate(existingVersion, this.schemaVersion);
+            await this.withBusyRetry(() => this.executeRaw(`UPDATE ${this.metadataTableName} SET value = ? WHERE key = ?`, [String(this.schemaVersion), SCHEMA_VERSION_KEY]));
+        }
+        if (this.applyPragmas) {
+            await this.tryExecRaw("PRAGMA journal_mode = WAL");
+            await this.tryExecRaw("PRAGMA synchronous = NORMAL");
+        }
+    }
+    async migrate(fromVersion, toVersion) {
+        if (fromVersion === toVersion) {
+            return;
+        }
+        // Placeholder for future adapter-level metadata migrations.
+        // BaseSqliteDocStore still owns runtime schema tables and indexes.
+    }
+    async withBusyRetry(operation) {
+        let attempt = 0;
+        let delayMs = this.busyRetry.initialDelayMs;
+        while (true) {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                attempt += 1;
+                if (!isBusyError(error) || attempt >= this.busyRetry.maxAttempts) {
+                    throw error;
+                }
+                await sleep(delayMs);
+                delayMs = Math.min(this.busyRetry.maxDelayMs, Math.ceil(delayMs * this.busyRetry.backoffFactor));
+            }
+        }
+    }
+    async executeRaw(sql, bindValues) {
+        await callExpoStatement(this.database.runAsync.bind(this.database), sql, bindValues);
+    }
+    async selectRaw(sql, bindValues) {
+        return callExpoSelect(this.database.getAllAsync.bind(this.database), sql, bindValues);
+    }
+    async tryExecRaw(sql) {
+        try {
+            await this.database.execAsync(sql);
+        }
+        catch {
+            // Some SQLite builds may not support all pragmas.
+        }
+    }
+}
+function callExpoStatement(statement, source, bindValues) {
+    if (bindValues === undefined) {
+        return statement(source);
+    }
+    if (Array.isArray(bindValues)) {
+        return statement(source, ...bindValues);
+    }
+    return statement(source, bindValues);
+}
+function callExpoSelect(statement, source, bindValues) {
+    if (bindValues === undefined) {
+        return statement(source);
+    }
+    if (Array.isArray(bindValues)) {
+        return statement(source, ...bindValues);
+    }
+    return statement(source, bindValues);
+}
+function splitSqlStatements(sql) {
+    return sql
+        .split(";")
+        .map((statement) => statement.trim())
+        .filter((statement) => statement.length > 0);
+}
+function normalizeSqlParams(params) {
+    return params.map((param) => {
+        if (typeof param === "boolean") {
+            return param ? 1 : 0;
+        }
+        if (typeof param === "bigint") {
+            return Number(param);
+        }
+        if (param instanceof ArrayBuffer) {
+            return new Uint8Array(param);
+        }
+        if (ArrayBuffer.isView(param)) {
+            return new Uint8Array(param.buffer, param.byteOffset, param.byteLength).slice();
+        }
+        return param;
+    });
+}
+function coerceSqlBlob(value) {
+    if (value instanceof ArrayBuffer) {
+        return value;
+    }
+    if (ArrayBuffer.isView(value)) {
+        return new Uint8Array(value.buffer, value.byteOffset, value.byteLength).slice().buffer;
+    }
+    if (Array.isArray(value)) {
+        return new Uint8Array(value).buffer;
+    }
+    if (isSerializedBuffer(value)) {
+        return new Uint8Array(value.data).buffer;
+    }
+    throw new Error("Unexpected SQL blob value shape");
+}
+function isSerializedBuffer(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "data" in value &&
+        Array.isArray(value.data));
+}
+function isBusyError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const message = error.message.toLowerCase();
+    return message.includes("database is locked") || message.includes("database is busy") || message.includes("busy");
+}
+function normalizeSchemaVersion(value) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`Invalid schemaVersion: ${value}`);
+    }
+    return value;
+}
+function sanitizeIdentifier(value) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+        throw new Error(`Invalid SQLite identifier: ${value}`);
+    }
+    return value;
+}
+function normalizeBusyRetryOptions(options) {
+    return {
+        maxAttempts: normalizePositiveInt(options?.maxAttempts ?? 5, "busyRetry.maxAttempts"),
+        initialDelayMs: normalizePositiveInt(options?.initialDelayMs ?? 4, "busyRetry.initialDelayMs"),
+        maxDelayMs: normalizePositiveInt(options?.maxDelayMs ?? 80, "busyRetry.maxDelayMs"),
+        backoffFactor: normalizePositiveNumber(options?.backoffFactor ?? 2, "busyRetry.backoffFactor"),
+    };
+}
+function normalizePositiveInt(value, field) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`${field} must be a positive integer`);
+    }
+    return value;
+}
+function normalizePositiveNumber(value, field) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${field} must be a positive number`);
+    }
+    return value;
+}
+function resolveNativeSetTimeout() {
+    const globalWithTimers = globalThis;
+    const nativeTimers = globalWithTimers[NATIVE_TIMERS_SYMBOL];
+    if (nativeTimers && typeof nativeTimers.setTimeout === "function") {
+        return nativeTimers.setTimeout;
+    }
+    return null;
+}
+const nativeSetTimeout = resolveNativeSetTimeout();
+function sleep(ms) {
+    if (!Number.isFinite(ms) || ms <= 0) {
+        return Promise.resolve();
+    }
+    if (!nativeSetTimeout) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        nativeSetTimeout(() => resolve(), ms);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { SqliteDocStore, type SqliteDocStoreOptions } from "./sqlite-docstore";
+export { ExpoSqlAdapter, type BusyRetryOptions, type ExpoSqlAdapterOptions, type ExpoSqlBindValues, type ExpoSqlDatabase, type ExpoSqlDatabaseLike, createExpoSqlDatabase, } from "./expo-sql-adapter";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { SqliteDocStore } from "./sqlite-docstore";
+export { ExpoSqlAdapter, createExpoSqlDatabase, } from "./expo-sql-adapter";

package/dist/sqlite-docstore.d.ts

@@ -0,0 +1,12 @@
+import { BaseSqliteDocStore } from "@concavejs/docstore-sqlite-base";
+import { type BusyRetryOptions, type ExpoSqlAdapterOptions, type ExpoSqlDatabase } from "./expo-sql-adapter";
+export interface SqliteDocStoreOptions extends Omit<ExpoSqlAdapterOptions, "busyRetry"> {
+    busyRetry?: BusyRetryOptions;
+}
+/**
+ * SQLite DocStore backed by an Expo SQLite-compatible database.
+ */
+export declare class SqliteDocStore extends BaseSqliteDocStore {
+    constructor(database: ExpoSqlDatabase, options?: SqliteDocStoreOptions);
+    close(): Promise<void>;
+}

package/dist/sqlite-docstore.js

@@ -0,0 +1,14 @@
+import { BaseSqliteDocStore } from "@concavejs/docstore-sqlite-base";
+import { ExpoSqlAdapter, } from "./expo-sql-adapter";
+/**
+ * SQLite DocStore backed by an Expo SQLite-compatible database.
+ */
+export class SqliteDocStore extends BaseSqliteDocStore {
+    constructor(database, options = {}) {
+        const adapter = new ExpoSqlAdapter(database, options);
+        super(adapter);
+    }
+    async close() {
+        // Expo SQLite does not require explicit close for common usage.
+    }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@concavejs/docstore-expo-sqlite",
+  "version": "0.0.1-alpha.8",
+  "license": "FSL-1.1-Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bunx tsc -p tsconfig.json --declaration --declarationMap false --outDir dist",
+    "test": "bun test --run --passWithNoTests"
+  },
+  "dependencies": {
+    "@concavejs/core": "0.0.1-alpha.8",
+    "@concavejs/docstore-sqlite-base": "0.0.1-alpha.8",
+    "convex": "^1.27.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}