@contractspec/lib.runtime-sandbox 0.11.0

package/dist/web/storage/indexeddb.js

@@ -0,0 +1,85 @@
+//#region src/web/storage/indexeddb.ts
+const DEFAULT_DB_NAME = "contractspec-runtime";
+const DEFAULT_STORE = "kv";
+const FALLBACK_STORE = /* @__PURE__ */ new Map();
+var LocalStorageService = class {
+	dbPromise;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	async init() {
+		await this.getDb();
+	}
+	async get(key, fallback) {
+		const db = await this.getDb();
+		if (!db) return FALLBACK_STORE.get(key) ?? fallback;
+		return new Promise((resolve, reject) => {
+			const request = db.transaction(this.storeName, "readonly").objectStore(this.storeName).get(key);
+			request.onsuccess = () => {
+				resolve(request.result ?? fallback);
+			};
+			request.onerror = () => reject(request.error);
+		});
+	}
+	async set(key, value) {
+		const db = await this.getDb();
+		if (!db) {
+			FALLBACK_STORE.set(key, value);
+			return;
+		}
+		await new Promise((resolve, reject) => {
+			const request = db.transaction(this.storeName, "readwrite").objectStore(this.storeName).put(value, key);
+			request.onsuccess = () => resolve();
+			request.onerror = () => reject(request.error);
+		});
+	}
+	async delete(key) {
+		const db = await this.getDb();
+		if (!db) {
+			FALLBACK_STORE.delete(key);
+			return;
+		}
+		await new Promise((resolve, reject) => {
+			const request = db.transaction(this.storeName, "readwrite").objectStore(this.storeName).delete(key);
+			request.onsuccess = () => resolve();
+			request.onerror = () => reject(request.error);
+		});
+	}
+	async clear() {
+		const db = await this.getDb();
+		if (!db) {
+			FALLBACK_STORE.clear();
+			return;
+		}
+		await new Promise((resolve, reject) => {
+			const request = db.transaction(this.storeName, "readwrite").objectStore(this.storeName).clear();
+			request.onsuccess = () => resolve();
+			request.onerror = () => reject(request.error);
+		});
+	}
+	get storeName() {
+		return this.options.storeName ?? DEFAULT_STORE;
+	}
+	async getDb() {
+		if (typeof indexedDB === "undefined") return null;
+		if (!this.dbPromise) this.dbPromise = this.openDb();
+		return this.dbPromise;
+	}
+	openDb() {
+		return new Promise((resolve, reject) => {
+			const request = indexedDB.open(this.options.dbName ?? DEFAULT_DB_NAME, this.options.version ?? 1);
+			request.onerror = () => reject(request.error);
+			request.onsuccess = () => {
+				resolve(request.result);
+			};
+			request.onupgradeneeded = () => {
+				const db = request.result;
+				if (!db.objectStoreNames.contains(this.storeName)) db.createObjectStore(this.storeName);
+			};
+		});
+	}
+};
+
+//#endregion
+export { LocalStorageService };
+//# sourceMappingURL=indexeddb.js.map

package/dist/web/storage/indexeddb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexeddb.js","names":[],"sources":["../../../src/web/storage/indexeddb.ts"],"sourcesContent":["export interface LocalStorageOptions {\n  dbName?: string;\n  storeName?: string;\n  version?: number;\n}\n\nconst DEFAULT_DB_NAME = 'contractspec-runtime';\nconst DEFAULT_STORE = 'kv';\nconst FALLBACK_STORE = new Map<string, unknown>();\n\nexport class LocalStorageService {\n  private dbPromise?: Promise<IDBDatabase | null>;\n\n  constructor(private readonly options: LocalStorageOptions = {}) {}\n\n  async init(): Promise<void> {\n    await this.getDb();\n  }\n\n  async get<TValue = unknown>(\n    key: string,\n    fallback?: TValue\n  ): Promise<TValue | undefined> {\n    const db = await this.getDb();\n    if (!db) {\n      return (FALLBACK_STORE.get(key) as TValue | undefined) ?? fallback;\n    }\n    return new Promise((resolve, reject) => {\n      const tx = db.transaction(this.storeName, 'readonly');\n      const store = tx.objectStore(this.storeName);\n      const request = store.get(key);\n      request.onsuccess = () => {\n        resolve((request.result as TValue | undefined) ?? fallback);\n      };\n      request.onerror = () => reject(request.error);\n    });\n  }\n\n  async set<TValue = unknown>(key: string, value: TValue): Promise<void> {\n    const db = await this.getDb();\n    if (!db) {\n      FALLBACK_STORE.set(key, value);\n      return;\n    }\n    await new Promise<void>((resolve, reject) => {\n      const tx = db.transaction(this.storeName, 'readwrite');\n      const store = tx.objectStore(this.storeName);\n      const request = store.put(value, key);\n      request.onsuccess = () => resolve();\n      request.onerror = () => reject(request.error);\n    });\n  }\n\n  async delete(key: string): Promise<void> {\n    const db = await this.getDb();\n    if (!db) {\n      FALLBACK_STORE.delete(key);\n      return;\n    }\n    await new Promise<void>((resolve, reject) => {\n      const tx = db.transaction(this.storeName, 'readwrite');\n      const store = tx.objectStore(this.storeName);\n      const request = store.delete(key);\n      request.onsuccess = () => resolve();\n      request.onerror = () => reject(request.error);\n    });\n  }\n\n  async clear(): Promise<void> {\n    const db = await this.getDb();\n    if (!db) {\n      FALLBACK_STORE.clear();\n      return;\n    }\n    await new Promise<void>((resolve, reject) => {\n      const tx = db.transaction(this.storeName, 'readwrite');\n      const store = tx.objectStore(this.storeName);\n      const request = store.clear();\n      request.onsuccess = () => resolve();\n      request.onerror = () => reject(request.error);\n    });\n  }\n\n  private get storeName() {\n    return this.options.storeName ?? DEFAULT_STORE;\n  }\n\n  private async getDb(): Promise<IDBDatabase | null> {\n    if (typeof indexedDB === 'undefined') {\n      return null;\n    }\n    if (!this.dbPromise) {\n      this.dbPromise = this.openDb();\n    }\n    return this.dbPromise;\n  }\n\n  private openDb(): Promise<IDBDatabase> {\n    return new Promise((resolve, reject) => {\n      const request = indexedDB.open(\n        this.options.dbName ?? DEFAULT_DB_NAME,\n        this.options.version ?? 1\n      );\n      request.onerror = () => reject(request.error);\n      request.onsuccess = () => {\n        resolve(request.result);\n      };\n      request.onupgradeneeded = () => {\n        const db = request.result;\n        if (!db.objectStoreNames.contains(this.storeName)) {\n          db.createObjectStore(this.storeName);\n        }\n      };\n    });\n  }\n}\n"],"mappings":";AAMA,MAAM,kBAAkB;AACxB,MAAM,gBAAgB;AACtB,MAAM,iCAAiB,IAAI,KAAsB;AAEjD,IAAa,sBAAb,MAAiC;CAC/B,AAAQ;CAER,YAAY,AAAiB,UAA+B,EAAE,EAAE;EAAnC;;CAE7B,MAAM,OAAsB;AAC1B,QAAM,KAAK,OAAO;;CAGpB,MAAM,IACJ,KACA,UAC6B;EAC7B,MAAM,KAAK,MAAM,KAAK,OAAO;AAC7B,MAAI,CAAC,GACH,QAAQ,eAAe,IAAI,IAAI,IAA2B;AAE5D,SAAO,IAAI,SAAS,SAAS,WAAW;GAGtC,MAAM,UAFK,GAAG,YAAY,KAAK,WAAW,WAAW,CACpC,YAAY,KAAK,UAAU,CACtB,IAAI,IAAI;AAC9B,WAAQ,kBAAkB;AACxB,YAAS,QAAQ,UAAiC,SAAS;;AAE7D,WAAQ,gBAAgB,OAAO,QAAQ,MAAM;IAC7C;;CAGJ,MAAM,IAAsB,KAAa,OAA8B;EACrE,MAAM,KAAK,MAAM,KAAK,OAAO;AAC7B,MAAI,CAAC,IAAI;AACP,kBAAe,IAAI,KAAK,MAAM;AAC9B;;AAEF,QAAM,IAAI,SAAe,SAAS,WAAW;GAG3C,MAAM,UAFK,GAAG,YAAY,KAAK,WAAW,YAAY,CACrC,YAAY,KAAK,UAAU,CACtB,IAAI,OAAO,IAAI;AACrC,WAAQ,kBAAkB,SAAS;AACnC,WAAQ,gBAAgB,OAAO,QAAQ,MAAM;IAC7C;;CAGJ,MAAM,OAAO,KAA4B;EACvC,MAAM,KAAK,MAAM,KAAK,OAAO;AAC7B,MAAI,CAAC,IAAI;AACP,kBAAe,OAAO,IAAI;AAC1B;;AAEF,QAAM,IAAI,SAAe,SAAS,WAAW;GAG3C,MAAM,UAFK,GAAG,YAAY,KAAK,WAAW,YAAY,CACrC,YAAY,KAAK,UAAU,CACtB,OAAO,IAAI;AACjC,WAAQ,kBAAkB,SAAS;AACnC,WAAQ,gBAAgB,OAAO,QAAQ,MAAM;IAC7C;;CAGJ,MAAM,QAAuB;EAC3B,MAAM,KAAK,MAAM,KAAK,OAAO;AAC7B,MAAI,CAAC,IAAI;AACP,kBAAe,OAAO;AACtB;;AAEF,QAAM,IAAI,SAAe,SAAS,WAAW;GAG3C,MAAM,UAFK,GAAG,YAAY,KAAK,WAAW,YAAY,CACrC,YAAY,KAAK,UAAU,CACtB,OAAO;AAC7B,WAAQ,kBAAkB,SAAS;AACnC,WAAQ,gBAAgB,OAAO,QAAQ,MAAM;IAC7C;;CAGJ,IAAY,YAAY;AACtB,SAAO,KAAK,QAAQ,aAAa;;CAGnC,MAAc,QAAqC;AACjD,MAAI,OAAO,cAAc,YACvB,QAAO;AAET,MAAI,CAAC,KAAK,UACR,MAAK,YAAY,KAAK,QAAQ;AAEhC,SAAO,KAAK;;CAGd,AAAQ,SAA+B;AACrC,SAAO,IAAI,SAAS,SAAS,WAAW;GACtC,MAAM,UAAU,UAAU,KACxB,KAAK,QAAQ,UAAU,iBACvB,KAAK,QAAQ,WAAW,EACzB;AACD,WAAQ,gBAAgB,OAAO,QAAQ,MAAM;AAC7C,WAAQ,kBAAkB;AACxB,YAAQ,QAAQ,OAAO;;AAEzB,WAAQ,wBAAwB;IAC9B,MAAM,KAAK,QAAQ;AACnB,QAAI,CAAC,GAAG,iBAAiB,SAAS,KAAK,UAAU,CAC/C,IAAG,kBAAkB,KAAK,UAAU;;IAGxC"}

package/dist/web/utils/id.d.ts

@@ -0,0 +1,5 @@
+//#region src/web/utils/id.d.ts
+declare function generateId(prefix?: string): string;
+//#endregion
+export { generateId };
+//# sourceMappingURL=id.d.ts.map

package/dist/web/utils/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","names":[],"sources":["../../../src/web/utils/id.ts"],"sourcesContent":[],"mappings":";iBAAgB,UAAA"}

package/dist/web/utils/id.js

@@ -0,0 +1,9 @@
+//#region src/web/utils/id.ts
+function generateId(prefix) {
+	const base = typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : Math.random().toString(36).slice(2, 10);
+	return prefix ? `${prefix}_${base}` : base;
+}
+
+//#endregion
+export { generateId };
+//# sourceMappingURL=id.js.map

package/dist/web/utils/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","names":[],"sources":["../../../src/web/utils/id.ts"],"sourcesContent":["export function generateId(prefix?: string): string {\n  const base =\n    typeof crypto !== 'undefined' && 'randomUUID' in crypto\n      ? crypto.randomUUID()\n      : Math.random().toString(36).slice(2, 10);\n  return prefix ? `${prefix}_${base}` : base;\n}\n"],"mappings":";AAAA,SAAgB,WAAW,QAAyB;CAClD,MAAM,OACJ,OAAO,WAAW,eAAe,gBAAgB,SAC7C,OAAO,YAAY,GACnB,KAAK,QAAQ,CAAC,SAAS,GAAG,CAAC,MAAM,GAAG,GAAG;AAC7C,QAAO,SAAS,GAAG,OAAO,GAAG,SAAS"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@contractspec/lib.runtime-sandbox",
+  "version": "0.11.0",
+  "type": "module",
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "clean": "rm -rf dist",
+    "lint": "bun run lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "build": "bun run build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun run build:bundle --watch"
+  },
+  "peerDependencies": {
+    "@electric-sql/pglite": "^0.3.14",
+    "drizzle-orm": "^0.38.4"
+  },
+  "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@contractspec/tool.typescript": "1.56.0",
+    "@contractspec/tool.tsdown": "1.56.0",
+    "typescript": "^5.9.3",
+    "@electric-sql/pglite": "^0.3.14",
+    "drizzle-orm": "^0.45.1",
+    "tsdown": "^0.19.0",
+    "@types/bun": "~1.3.5"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./*"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "src/*"
+      ]
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./ports": "./dist/ports/index.mjs",
+      "./types": "./dist/types/index.mjs",
+      "./adapters/pglite": "./dist/adapters/pglite/index.mjs",
+      "./*": "./*"
+    }
+  },
+  "dependencies": {
+    "@apollo/client": "^4.0.12",
+    "@graphql-tools/schema": "^10.0.31",
+    "graphql": "^16.12.0"
+  }
+}

package/src/adapters/pglite/adapter.ts

@@ -0,0 +1,152 @@
+import { PGlite } from '@electric-sql/pglite';
+
+import type { DatabasePort } from '../../ports/database.port';
+import type {
+  DatabaseInitOptions,
+  DbRow,
+  DbValue,
+  Migration,
+  QueryResult,
+  TransactionContext,
+} from '../../types/database.types';
+
+/**
+ * PGLite database adapter for browser sandbox runtime.
+ *
+ * Uses PGLite (PostgreSQL WASM) for in-browser database operations.
+ * Supports in-memory or IndexedDB persistence.
+ */
+export class PGLiteDatabaseAdapter implements DatabasePort {
+  private client: PGlite | null = null;
+  private initialized = false;
+
+  async init(options?: DatabaseInitOptions): Promise<void> {
+    if (this.initialized) return;
+
+    // Create PGLite instance
+    // - undefined/empty = in-memory
+    // - 'idb://dbname' = IndexedDB persistence
+    const dataDir = options?.dataDir;
+    this.client = dataDir ? new PGlite(`idb://${dataDir}`) : new PGlite();
+
+    // Wait for PGLite to be ready
+    await this.client.waitReady;
+    this.initialized = true;
+  }
+
+  async close(): Promise<void> {
+    if (this.client) {
+      await this.client.close();
+      this.client = null;
+      this.initialized = false;
+    }
+  }
+
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  async query<T = DbRow>(
+    sql: string,
+    params?: DbValue[]
+  ): Promise<QueryResult<T>> {
+    const client = this.getClient();
+    const normalizedParams = this.normalizeParams(params);
+    const result = await client.query<T>(sql, normalizedParams);
+    return {
+      rows: result.rows,
+      rowCount: result.rows.length,
+    };
+  }
+
+  async execute(sql: string, params?: DbValue[]): Promise<void> {
+    const client = this.getClient();
+    const normalizedParams = this.normalizeParams(params);
+    await client.query(sql, normalizedParams);
+  }
+
+  async transaction<T>(
+    callback: (ctx: TransactionContext) => Promise<T>
+  ): Promise<T> {
+    const client = this.getClient();
+
+    await client.query('BEGIN');
+    try {
+      const ctx: TransactionContext = {
+        execute: async (sql: string, params?: DbValue[]) => {
+          const normalizedParams = this.normalizeParams(params);
+          await client.query(sql, normalizedParams);
+        },
+      };
+      const result = await callback(ctx);
+      await client.query('COMMIT');
+      return result;
+    } catch (error) {
+      await client.query('ROLLBACK');
+      throw error;
+    }
+  }
+
+  async migrate(migrations: Migration[]): Promise<void> {
+    const client = this.getClient();
+
+    // Create migrations tracking table if not exists
+    await client.query(`
+      CREATE TABLE IF NOT EXISTS _sandbox_migrations (
+        id TEXT PRIMARY KEY,
+        applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+
+    // Apply each migration if not already applied
+    for (const migration of migrations) {
+      const existing = await client.query<{ id: string }>(
+        'SELECT id FROM _sandbox_migrations WHERE id = $1',
+        [migration.id]
+      );
+
+      if (existing.rows.length === 0) {
+        await client.query(migration.sql);
+        await client.query('INSERT INTO _sandbox_migrations (id) VALUES ($1)', [
+          migration.id,
+        ]);
+      }
+    }
+  }
+
+  async export(): Promise<Uint8Array> {
+    this.getClient(); // Ensure initialized
+    // PGLite doesn't support export the same way sql.js does
+    // For now, return empty array - can be implemented with pg_dump style later
+    return new Uint8Array();
+  }
+
+  /**
+   * Get the initialized PGLite client.
+   * Throws if not initialized.
+   */
+  private getClient(): PGlite {
+    if (!this.client || !this.initialized) {
+      throw new Error(
+        'PGLiteDatabaseAdapter not initialized. Call init() first.'
+      );
+    }
+    return this.client;
+  }
+
+  private normalizeParams(params?: DbValue[]): unknown[] {
+    if (!params) return [];
+    return params.map((value) => {
+      if (typeof value === 'boolean') {
+        return value;
+      }
+      if (value instanceof Date) {
+        return value.toISOString();
+      }
+      if (value === undefined) {
+        return null;
+      }
+      return value;
+    });
+  }
+}

package/src/adapters/pglite/index.ts

@@ -0,0 +1 @@
+export { PGLiteDatabaseAdapter } from './adapter';

package/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @contractspec/lib.runtime-sandbox
+ *
+ * Sandbox runtime library providing database abstraction for browser environments.
+ * Supports lazy-loading of PGLite for bundle optimization.
+ */
+
+// Core ports (interfaces)
+export { type DatabaseAdapterFactory, type DatabasePort } from './ports';
+
+// Types
+export {
+  type DatabaseInitOptions,
+  type DbRow,
+  type DbValue,
+  type Migration,
+  type QueryResult,
+  type TransactionContext,
+} from './types';
+
+/**
+ * Lazy-load the PGLite database adapter.
+ *
+ * This function dynamically imports PGLite and Drizzle only when called,
+ * avoiding bundle bloat for consumers not using the sandbox runtime.
+ *
+ * @example
+ * ```ts
+ * const adapter = await createPGLiteAdapter();
+ * await adapter.init();
+ * const result = await adapter.query('SELECT * FROM users');
+ * ```
+ */
+export async function createPGLiteAdapter(): Promise<
+  import('./ports').DatabasePort
+> {
+  const { PGLiteDatabaseAdapter } = await import('./adapters/pglite');
+  return new PGLiteDatabaseAdapter();
+}
+
+export * as web from './web';

package/src/ports/database.port.ts

@@ -0,0 +1,82 @@
+import type {
+  DatabaseInitOptions,
+  DbRow,
+  DbValue,
+  Migration,
+  QueryResult,
+  TransactionContext,
+} from '../types/database.types';
+
+/**
+ * Database port interface for sandbox runtime.
+ *
+ * This interface abstracts the database layer, allowing:
+ * - PGLite adapter for browser sandbox
+ * - Prisma/Drizzle adapter for production
+ * - Mock adapter for testing
+ *
+ * All implementations must be lazy-loadable to avoid bundle bloat.
+ */
+export interface DatabasePort {
+  /**
+   * Initialize the database connection and run migrations.
+   */
+  init(options?: DatabaseInitOptions): Promise<void>;
+
+  /**
+   * Close the database connection and release resources.
+   */
+  close(): Promise<void>;
+
+  /**
+   * Check if the database is initialized.
+   */
+  isInitialized(): boolean;
+
+  /**
+   * Execute a SELECT query and return rows.
+   *
+   * @param sql - SQL query string with $1, $2, etc. placeholders
+   * @param params - Query parameters
+   * @returns Query result with typed rows
+   */
+  query<T = DbRow>(sql: string, params?: DbValue[]): Promise<QueryResult<T>>;
+
+  /**
+   * Execute an INSERT/UPDATE/DELETE statement.
+   *
+   * @param sql - SQL statement with $1, $2, etc. placeholders
+   * @param params - Statement parameters
+   */
+  execute(sql: string, params?: DbValue[]): Promise<void>;
+
+  /**
+   * Run a callback within a database transaction.
+   * Automatically commits on success, rolls back on error.
+   *
+   * @param callback - Function to execute within transaction
+   * @returns Result of the callback
+   */
+  transaction<T>(callback: (ctx: TransactionContext) => Promise<T>): Promise<T>;
+
+  /**
+   * Run schema migrations.
+   *
+   * @param migrations - Array of migrations to apply
+   */
+  migrate(migrations: Migration[]): Promise<void>;
+
+  /**
+   * Export the current database state as a binary blob.
+   * Useful for backup/restore in browser context.
+   */
+  export(): Promise<Uint8Array>;
+}
+
+/**
+ * Factory function type for creating database adapters.
+ * Used for lazy-loading adapters.
+ */
+export type DatabaseAdapterFactory = (
+  options?: DatabaseInitOptions
+) => Promise<DatabasePort>;

package/src/ports/index.ts

@@ -0,0 +1,4 @@
+export {
+  type DatabaseAdapterFactory,
+  type DatabasePort,
+} from './database.port';

package/src/types/database.types.ts

@@ -0,0 +1,55 @@
+/**
+ * Database value types supported by the sandbox runtime
+ */
+export type DbValue =
+  | string
+  | number
+  | boolean
+  | null
+  | Uint8Array
+  | Date
+  | undefined;
+
+/**
+ * Generic row type for database results
+ */
+export type DbRow = Record<string, DbValue>;
+
+/**
+ * Options for initializing a database adapter
+ */
+export interface DatabaseInitOptions {
+  /**
+   * Data directory for persistence (optional).
+   * - Browser: uses IndexedDB when specified
+   * - Node/Bun: uses file system when specified
+   * - If omitted, uses in-memory storage
+   */
+  dataDir?: string;
+}
+
+/**
+ * Query builder result type
+ */
+export interface QueryResult<T = DbRow> {
+  rows: T[];
+  rowCount: number;
+}
+
+/**
+ * Transaction context for atomic operations
+ */
+export interface TransactionContext {
+  /**
+   * Execute raw SQL within the transaction
+   */
+  execute(sql: string, params?: DbValue[]): Promise<void>;
+}
+
+/**
+ * Migration definition
+ */
+export interface Migration {
+  id: string;
+  sql: string;
+}

package/src/types/index.ts

@@ -0,0 +1 @@
+export * from './database.types';