@contractspec/lib.runtime-sandbox 0.11.0

package/dist/_virtual/rolldown_runtime.js

@@ -0,0 +1,18 @@
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __exportAll = (all, symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll };

package/dist/adapters/pglite/adapter.js

@@ -0,0 +1,97 @@
+import { PGlite } from "@electric-sql/pglite";
+
+//#region src/adapters/pglite/adapter.ts
+/**
+* PGLite database adapter for browser sandbox runtime.
+*
+* Uses PGLite (PostgreSQL WASM) for in-browser database operations.
+* Supports in-memory or IndexedDB persistence.
+*/
+var PGLiteDatabaseAdapter = class {
+	client = null;
+	initialized = false;
+	async init(options) {
+		if (this.initialized) return;
+		const dataDir = options?.dataDir;
+		this.client = dataDir ? new PGlite(`idb://${dataDir}`) : new PGlite();
+		await this.client.waitReady;
+		this.initialized = true;
+	}
+	async close() {
+		if (this.client) {
+			await this.client.close();
+			this.client = null;
+			this.initialized = false;
+		}
+	}
+	isInitialized() {
+		return this.initialized;
+	}
+	async query(sql, params) {
+		const client = this.getClient();
+		const normalizedParams = this.normalizeParams(params);
+		const result = await client.query(sql, normalizedParams);
+		return {
+			rows: result.rows,
+			rowCount: result.rows.length
+		};
+	}
+	async execute(sql, params) {
+		const client = this.getClient();
+		const normalizedParams = this.normalizeParams(params);
+		await client.query(sql, normalizedParams);
+	}
+	async transaction(callback) {
+		const client = this.getClient();
+		await client.query("BEGIN");
+		try {
+			const result = await callback({ execute: async (sql, params) => {
+				const normalizedParams = this.normalizeParams(params);
+				await client.query(sql, normalizedParams);
+			} });
+			await client.query("COMMIT");
+			return result;
+		} catch (error) {
+			await client.query("ROLLBACK");
+			throw error;
+		}
+	}
+	async migrate(migrations) {
+		const client = this.getClient();
+		await client.query(`
+      CREATE TABLE IF NOT EXISTS _sandbox_migrations (
+        id TEXT PRIMARY KEY,
+        applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+		for (const migration of migrations) if ((await client.query("SELECT id FROM _sandbox_migrations WHERE id = $1", [migration.id])).rows.length === 0) {
+			await client.query(migration.sql);
+			await client.query("INSERT INTO _sandbox_migrations (id) VALUES ($1)", [migration.id]);
+		}
+	}
+	async export() {
+		this.getClient();
+		return new Uint8Array();
+	}
+	/**
+	* Get the initialized PGLite client.
+	* Throws if not initialized.
+	*/
+	getClient() {
+		if (!this.client || !this.initialized) throw new Error("PGLiteDatabaseAdapter not initialized. Call init() first.");
+		return this.client;
+	}
+	normalizeParams(params) {
+		if (!params) return [];
+		return params.map((value) => {
+			if (typeof value === "boolean") return value;
+			if (value instanceof Date) return value.toISOString();
+			if (value === void 0) return null;
+			return value;
+		});
+	}
+};
+
+//#endregion
+export { PGLiteDatabaseAdapter };
+//# sourceMappingURL=adapter.js.map

package/dist/adapters/pglite/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","names":[],"sources":["../../../src/adapters/pglite/adapter.ts"],"sourcesContent":["import { PGlite } from '@electric-sql/pglite';\n\nimport type { DatabasePort } from '../../ports/database.port';\nimport type {\n  DatabaseInitOptions,\n  DbRow,\n  DbValue,\n  Migration,\n  QueryResult,\n  TransactionContext,\n} from '../../types/database.types';\n\n/**\n * PGLite database adapter for browser sandbox runtime.\n *\n * Uses PGLite (PostgreSQL WASM) for in-browser database operations.\n * Supports in-memory or IndexedDB persistence.\n */\nexport class PGLiteDatabaseAdapter implements DatabasePort {\n  private client: PGlite | null = null;\n  private initialized = false;\n\n  async init(options?: DatabaseInitOptions): Promise<void> {\n    if (this.initialized) return;\n\n    // Create PGLite instance\n    // - undefined/empty = in-memory\n    // - 'idb://dbname' = IndexedDB persistence\n    const dataDir = options?.dataDir;\n    this.client = dataDir ? new PGlite(`idb://${dataDir}`) : new PGlite();\n\n    // Wait for PGLite to be ready\n    await this.client.waitReady;\n    this.initialized = true;\n  }\n\n  async close(): Promise<void> {\n    if (this.client) {\n      await this.client.close();\n      this.client = null;\n      this.initialized = false;\n    }\n  }\n\n  isInitialized(): boolean {\n    return this.initialized;\n  }\n\n  async query<T = DbRow>(\n    sql: string,\n    params?: DbValue[]\n  ): Promise<QueryResult<T>> {\n    const client = this.getClient();\n    const normalizedParams = this.normalizeParams(params);\n    const result = await client.query<T>(sql, normalizedParams);\n    return {\n      rows: result.rows,\n      rowCount: result.rows.length,\n    };\n  }\n\n  async execute(sql: string, params?: DbValue[]): Promise<void> {\n    const client = this.getClient();\n    const normalizedParams = this.normalizeParams(params);\n    await client.query(sql, normalizedParams);\n  }\n\n  async transaction<T>(\n    callback: (ctx: TransactionContext) => Promise<T>\n  ): Promise<T> {\n    const client = this.getClient();\n\n    await client.query('BEGIN');\n    try {\n      const ctx: TransactionContext = {\n        execute: async (sql: string, params?: DbValue[]) => {\n          const normalizedParams = this.normalizeParams(params);\n          await client.query(sql, normalizedParams);\n        },\n      };\n      const result = await callback(ctx);\n      await client.query('COMMIT');\n      return result;\n    } catch (error) {\n      await client.query('ROLLBACK');\n      throw error;\n    }\n  }\n\n  async migrate(migrations: Migration[]): Promise<void> {\n    const client = this.getClient();\n\n    // Create migrations tracking table if not exists\n    await client.query(`\n      CREATE TABLE IF NOT EXISTS _sandbox_migrations (\n        id TEXT PRIMARY KEY,\n        applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n      )\n    `);\n\n    // Apply each migration if not already applied\n    for (const migration of migrations) {\n      const existing = await client.query<{ id: string }>(\n        'SELECT id FROM _sandbox_migrations WHERE id = $1',\n        [migration.id]\n      );\n\n      if (existing.rows.length === 0) {\n        await client.query(migration.sql);\n        await client.query('INSERT INTO _sandbox_migrations (id) VALUES ($1)', [\n          migration.id,\n        ]);\n      }\n    }\n  }\n\n  async export(): Promise<Uint8Array> {\n    this.getClient(); // Ensure initialized\n    // PGLite doesn't support export the same way sql.js does\n    // For now, return empty array - can be implemented with pg_dump style later\n    return new Uint8Array();\n  }\n\n  /**\n   * Get the initialized PGLite client.\n   * Throws if not initialized.\n   */\n  private getClient(): PGlite {\n    if (!this.client || !this.initialized) {\n      throw new Error(\n        'PGLiteDatabaseAdapter not initialized. Call init() first.'\n      );\n    }\n    return this.client;\n  }\n\n  private normalizeParams(params?: DbValue[]): unknown[] {\n    if (!params) return [];\n    return params.map((value) => {\n      if (typeof value === 'boolean') {\n        return value;\n      }\n      if (value instanceof Date) {\n        return value.toISOString();\n      }\n      if (value === undefined) {\n        return null;\n      }\n      return value;\n    });\n  }\n}\n"],"mappings":";;;;;;;;;AAkBA,IAAa,wBAAb,MAA2D;CACzD,AAAQ,SAAwB;CAChC,AAAQ,cAAc;CAEtB,MAAM,KAAK,SAA8C;AACvD,MAAI,KAAK,YAAa;EAKtB,MAAM,UAAU,SAAS;AACzB,OAAK,SAAS,UAAU,IAAI,OAAO,SAAS,UAAU,GAAG,IAAI,QAAQ;AAGrE,QAAM,KAAK,OAAO;AAClB,OAAK,cAAc;;CAGrB,MAAM,QAAuB;AAC3B,MAAI,KAAK,QAAQ;AACf,SAAM,KAAK,OAAO,OAAO;AACzB,QAAK,SAAS;AACd,QAAK,cAAc;;;CAIvB,gBAAyB;AACvB,SAAO,KAAK;;CAGd,MAAM,MACJ,KACA,QACyB;EACzB,MAAM,SAAS,KAAK,WAAW;EAC/B,MAAM,mBAAmB,KAAK,gBAAgB,OAAO;EACrD,MAAM,SAAS,MAAM,OAAO,MAAS,KAAK,iBAAiB;AAC3D,SAAO;GACL,MAAM,OAAO;GACb,UAAU,OAAO,KAAK;GACvB;;CAGH,MAAM,QAAQ,KAAa,QAAmC;EAC5D,MAAM,SAAS,KAAK,WAAW;EAC/B,MAAM,mBAAmB,KAAK,gBAAgB,OAAO;AACrD,QAAM,OAAO,MAAM,KAAK,iBAAiB;;CAG3C,MAAM,YACJ,UACY;EACZ,MAAM,SAAS,KAAK,WAAW;AAE/B,QAAM,OAAO,MAAM,QAAQ;AAC3B,MAAI;GAOF,MAAM,SAAS,MAAM,SANW,EAC9B,SAAS,OAAO,KAAa,WAAuB;IAClD,MAAM,mBAAmB,KAAK,gBAAgB,OAAO;AACrD,UAAM,OAAO,MAAM,KAAK,iBAAiB;MAE5C,CACiC;AAClC,SAAM,OAAO,MAAM,SAAS;AAC5B,UAAO;WACA,OAAO;AACd,SAAM,OAAO,MAAM,WAAW;AAC9B,SAAM;;;CAIV,MAAM,QAAQ,YAAwC;EACpD,MAAM,SAAS,KAAK,WAAW;AAG/B,QAAM,OAAO,MAAM;;;;;MAKjB;AAGF,OAAK,MAAM,aAAa,WAMtB,MALiB,MAAM,OAAO,MAC5B,oDACA,CAAC,UAAU,GAAG,CACf,EAEY,KAAK,WAAW,GAAG;AAC9B,SAAM,OAAO,MAAM,UAAU,IAAI;AACjC,SAAM,OAAO,MAAM,oDAAoD,CACrE,UAAU,GACX,CAAC;;;CAKR,MAAM,SAA8B;AAClC,OAAK,WAAW;AAGhB,SAAO,IAAI,YAAY;;;;;;CAOzB,AAAQ,YAAoB;AAC1B,MAAI,CAAC,KAAK,UAAU,CAAC,KAAK,YACxB,OAAM,IAAI,MACR,4DACD;AAEH,SAAO,KAAK;;CAGd,AAAQ,gBAAgB,QAA+B;AACrD,MAAI,CAAC,OAAQ,QAAO,EAAE;AACtB,SAAO,OAAO,KAAK,UAAU;AAC3B,OAAI,OAAO,UAAU,UACnB,QAAO;AAET,OAAI,iBAAiB,KACnB,QAAO,MAAM,aAAa;AAE5B,OAAI,UAAU,OACZ,QAAO;AAET,UAAO;IACP"}

package/dist/adapters/pglite/index.js

@@ -0,0 +1,3 @@
+import { PGLiteDatabaseAdapter } from "./adapter.js";
+
+export { PGLiteDatabaseAdapter };

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { DatabaseInitOptions, DbRow, DbValue, Migration, QueryResult, TransactionContext } from "./types/database.types.js";
+import { DatabaseAdapterFactory, DatabasePort } from "./ports/database.port.js";
+import { index_d_exports } from "./web/index.js";
+
+//#region src/index.d.ts
+
+/**
+ * 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');
+ * ```
+ */
+declare function createPGLiteAdapter(): Promise<DatabasePort>;
+//#endregion
+export { type DatabaseAdapterFactory, type DatabaseInitOptions, type DatabasePort, type DbRow, type DbValue, type Migration, type QueryResult, type TransactionContext, createPGLiteAdapter, index_d_exports as web };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;iBAiCsB,mBAAA,CAAA,GAAuB,QAAJ,YAAA"}

package/dist/index.js

@@ -0,0 +1,24 @@
+import { web_exports } from "./web/index.js";
+
+//#region src/index.ts
+/**
+* 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');
+* ```
+*/
+async function createPGLiteAdapter() {
+	const { PGLiteDatabaseAdapter } = await import("./adapters/pglite/index.js");
+	return new PGLiteDatabaseAdapter();
+}
+
+//#endregion
+export { createPGLiteAdapter, web_exports as web };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @contractspec/lib.runtime-sandbox\n *\n * Sandbox runtime library providing database abstraction for browser environments.\n * Supports lazy-loading of PGLite for bundle optimization.\n */\n\n// Core ports (interfaces)\nexport { type DatabaseAdapterFactory, type DatabasePort } from './ports';\n\n// Types\nexport {\n  type DatabaseInitOptions,\n  type DbRow,\n  type DbValue,\n  type Migration,\n  type QueryResult,\n  type TransactionContext,\n} from './types';\n\n/**\n * Lazy-load the PGLite database adapter.\n *\n * This function dynamically imports PGLite and Drizzle only when called,\n * avoiding bundle bloat for consumers not using the sandbox runtime.\n *\n * @example\n * ```ts\n * const adapter = await createPGLiteAdapter();\n * await adapter.init();\n * const result = await adapter.query('SELECT * FROM users');\n * ```\n */\nexport async function createPGLiteAdapter(): Promise<\n  import('./ports').DatabasePort\n> {\n  const { PGLiteDatabaseAdapter } = await import('./adapters/pglite');\n  return new PGLiteDatabaseAdapter();\n}\n\nexport * as web from './web';\n"],"mappings":";;;;;;;;;;;;;;;;AAiCA,eAAsB,sBAEpB;CACA,MAAM,EAAE,0BAA0B,MAAM,OAAO;AAC/C,QAAO,IAAI,uBAAuB"}

package/dist/ports/database.port.d.ts

@@ -0,0 +1,70 @@
+import { DatabaseInitOptions, DbRow, DbValue, Migration, QueryResult, TransactionContext } from "../types/database.types.js";
+
+//#region src/ports/database.port.d.ts
+
+/**
+ * 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.
+ */
+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.
+ */
+type DatabaseAdapterFactory = (options?: DatabaseInitOptions) => Promise<DatabasePort>;
+//#endregion
+export { DatabaseAdapterFactory, DatabasePort };
+//# sourceMappingURL=database.port.d.ts.map

package/dist/ports/database.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.port.d.ts","names":[],"sources":["../../src/ports/database.port.ts"],"sourcesContent":[],"mappings":";;;;;;AAmBA;;;;;;;;AAuBqD,UAvBpC,YAAA,CAuBoC;EAQrB;;;EASgC,IAAA,CAAA,OAAA,CAAA,EApC/C,mBAoC+C,CAAA,EApCzB,OAoCyB,CAAA,IAAA,CAAA;EAAR;;;EAOlC,KAAA,EAAA,EAtCX,OAsCW,CAAA,IAAA,CAAA;EAAc;;;EAMjB,aAAA,EAAA,EAAA,OAAA;EAOP;;;;;;;YArCA,6BAA6B,YAAY,QAAQ,YAAY;;;;;;;gCAQzC,YAAY;;;;;;;;iCASX,uBAAuB,QAAQ,KAAK,QAAQ;;;;;;sBAOvD,cAAc;;;;;YAMxB,QAAQ;;;;;;KAOR,sBAAA,cACA,wBACP,QAAQ"}

package/dist/types/database.types.d.ts

@@ -0,0 +1,47 @@
+//#region src/types/database.types.d.ts
+/**
+ * Database value types supported by the sandbox runtime
+ */
+type DbValue = string | number | boolean | null | Uint8Array | Date | undefined;
+/**
+ * Generic row type for database results
+ */
+type DbRow = Record<string, DbValue>;
+/**
+ * Options for initializing a database adapter
+ */
+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
+ */
+interface QueryResult<T = DbRow> {
+  rows: T[];
+  rowCount: number;
+}
+/**
+ * Transaction context for atomic operations
+ */
+interface TransactionContext {
+  /**
+   * Execute raw SQL within the transaction
+   */
+  execute(sql: string, params?: DbValue[]): Promise<void>;
+}
+/**
+ * Migration definition
+ */
+interface Migration {
+  id: string;
+  sql: string;
+}
+//#endregion
+export { DatabaseInitOptions, DbRow, DbValue, Migration, QueryResult, TransactionContext };
+//# sourceMappingURL=database.types.d.ts.map

package/dist/types/database.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.types.d.ts","names":[],"sources":["../../src/types/database.types.ts"],"sourcesContent":[],"mappings":";;AAGA;AAYA;AAKiB,KAjBL,OAAA,GAiBK,MAAmB,GAAA,MAAA,GAAA,OAAA,GAAA,IAAA,GAZhC,UAYgC,GAXhC,IAWgC,GAAA,SAAA;AAapC;AAQA;AAUA;KApCY,KAAA,GAAQ,eAAe;;;;UAKlB,mBAAA;;;;;;;;;;;;UAaA,gBAAgB;QACzB;;;;;;UAOS,kBAAA;;;;gCAIe,YAAY;;;;;UAM3B,SAAA"}

package/dist/web/database/migrations.d.ts

@@ -0,0 +1,12 @@
+import { Migration } from "@contractspec/lib.runtime-sandbox";
+
+//#region src/web/database/migrations.d.ts
+
+/**
+ * All migrations for the sandbox runtime database.
+ * Each migration should be idempotent (CREATE TABLE IF NOT EXISTS).
+ */
+declare const SANDBOX_MIGRATIONS: Migration[];
+//#endregion
+export { SANDBOX_MIGRATIONS };
+//# sourceMappingURL=migrations.d.ts.map

package/dist/web/database/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","names":[],"sources":["../../../src/web/database/migrations.ts"],"sourcesContent":[],"mappings":";;;;;;;;cAYa,oBAAoB"}