acrylblends 0.7.4 → 0.7.6

package/plugins/acryl-db-sqlite/src/facade/node.ts

@@ -0,0 +1,199 @@
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { StatementSync } from "node:sqlite";
+import { DatabaseSync } from "node:sqlite";
+import type { Db, DbExecutor, SqlValue } from "../../../acryl-db/src/index.ts";
+
+/** Node SQLite connection settings for a database file. */
+export type NodeSqliteDatabaseOptions = {
+	/** SQLite WAL auto-checkpoint threshold. SQLite and this adapter default to 1,000 pages; 0 disables it. */
+	readonly walAutoCheckpointPages?: number;
+	/** Time SQLite waits for a competing file lock. SQLite defaults to 0; this adapter defaults to 5,000 ms. */
+	readonly busyTimeoutMs?: number;
+};
+
+const DEFAULT_WAL_AUTO_CHECKPOINT_PAGES = 1_000;
+const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+
+type TransactionScope = { active: boolean };
+
+const ignore = (): void => {};
+
+/**
+ * Runs operations in call order. An operation starts immediately when nothing is running or waiting;
+ * otherwise it waits for everything before it. An asynchronous operation holds the queue until it settles.
+ */
+class SerialOperationQueue {
+	private tail: Promise<void> = Promise.resolve();
+	private pending = 0;
+
+	run<T>(operation: () => T): Promise<T> {
+		if (this.pending > 0) return this.enqueue(operation);
+		try {
+			return Promise.resolve(operation());
+		} catch (error) {
+			return Promise.reject(error);
+		}
+	}
+
+	runAsync<T>(operation: () => Promise<T>): Promise<T> {
+		if (this.pending > 0) return this.enqueue(operation);
+		this.pending++;
+		// Publish the barrier before the operation starts, so calls it makes synchronously wait behind it.
+		const { promise: barrier, resolve: releaseBarrier } = Promise.withResolvers<void>();
+		this.tail = barrier;
+		let started: Promise<T>;
+		try {
+			started = operation();
+		} catch (error) {
+			started = Promise.reject(error);
+		}
+		return started.finally(() => {
+			this.pending--;
+			releaseBarrier();
+		});
+	}
+
+	private enqueue<T>(operation: () => T | Promise<T>): Promise<T> {
+		this.pending++;
+		return this.release(this.tail.then(operation));
+	}
+
+	private release<T>(operation: Promise<T>): Promise<T> {
+		const settled = operation.finally(() => {
+			this.pending--;
+		});
+		this.tail = settled.then(ignore, ignore);
+		return settled;
+	}
+}
+
+/**
+ * Executes SQL on one connection. Prepared statements are cached per connection by SQL text, so the
+ * database and its transaction handles share them across transactions.
+ */
+abstract class NodeSqliteExecutor implements DbExecutor {
+	protected readonly database: DatabaseSync;
+	protected readonly statements: Map<string, StatementSync>;
+
+	constructor(database: DatabaseSync, statements: Map<string, StatementSync>) {
+		this.database = database;
+		this.statements = statements;
+	}
+
+	exec(sql: string): Promise<void> {
+		return this.runOperation(() => {
+			this.database.exec(sql);
+		});
+	}
+
+	run(sql: string, ...params: SqlValue[]): Promise<{ readonly changes: number }> {
+		return this.runOperation(() => ({ changes: Number(this.statement(sql).run(...params).changes) }));
+	}
+
+	get<T extends object>(sql: string, ...params: SqlValue[]): Promise<T | undefined> {
+		return this.runOperation(() => this.statement(sql).get(...params) as T | undefined);
+	}
+
+	all<T extends object>(sql: string, ...params: SqlValue[]): Promise<T[]> {
+		return this.runOperation(() => this.statement(sql).all(...params) as T[]);
+	}
+
+	protected abstract runOperation<T>(operation: () => T): Promise<T>;
+
+	private statement(sql: string): StatementSync {
+		let statement = this.statements.get(sql);
+		if (statement === undefined) {
+			statement = this.database.prepare(sql);
+			this.statements.set(sql, statement);
+		}
+		return statement;
+	}
+}
+
+class NodeSqliteTransaction extends NodeSqliteExecutor {
+	private readonly scope: TransactionScope;
+
+	constructor(database: DatabaseSync, statements: Map<string, StatementSync>, scope: TransactionScope) {
+		super(database, statements);
+		this.scope = scope;
+	}
+
+	protected async runOperation<T>(operation: () => T): Promise<T> {
+		if (!this.scope.active) throw new Error("SQLite transaction handle is no longer active");
+		return operation();
+	}
+}
+
+/** `Db` adapter backed by Node's built-in `node:sqlite`. */
+export class NodeSqliteDatabase extends NodeSqliteExecutor implements Db {
+	private readonly access = new SerialOperationQueue();
+	private closed = false;
+
+	constructor(database: DatabaseSync) {
+		super(database, new Map());
+	}
+
+	transaction<T>(callback: (transaction: DbExecutor) => Promise<T>): Promise<T> {
+		return this.access.runAsync(async () => {
+			this.database.exec("BEGIN IMMEDIATE");
+			const scope = { active: true };
+			try {
+				const result = await callback(new NodeSqliteTransaction(this.database, this.statements, scope));
+				scope.active = false;
+				this.database.exec("COMMIT");
+				return result;
+			} catch (error) {
+				scope.active = false;
+				try {
+					this.database.exec("ROLLBACK");
+				} catch (rollbackError) {
+					throw new AggregateError([error, rollbackError], "SQLite transaction failed and rollback failed");
+				}
+				throw error;
+			}
+		});
+	}
+
+	close(): Promise<void> {
+		return this.access.run(() => {
+			if (this.closed) return;
+			this.closed = true;
+			this.statements.clear();
+			try {
+				this.database.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+			} finally {
+				this.database.close();
+			}
+		});
+	}
+
+	protected runOperation<T>(operation: () => T): Promise<T> {
+		return this.access.run(operation);
+	}
+}
+
+/** Open and configure a Node-backed SQLite database facade. */
+export async function openNodeSqliteDatabase(
+	path: string,
+	options: NodeSqliteDatabaseOptions = {},
+): Promise<NodeSqliteDatabase> {
+	const checkpointPages = options.walAutoCheckpointPages ?? DEFAULT_WAL_AUTO_CHECKPOINT_PAGES;
+	const timeout = options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
+	if (path !== ":memory:") await mkdir(dirname(path), { recursive: true });
+	const database = new DatabaseSync(path, { timeout });
+	const adapter = new NodeSqliteDatabase(database);
+	try {
+		await adapter.exec("PRAGMA journal_mode = WAL");
+		await adapter.exec("PRAGMA synchronous = NORMAL");
+		await adapter.exec(`PRAGMA wal_autocheckpoint = ${checkpointPages}`);
+		return adapter;
+	} catch (error) {
+		try {
+			await adapter.close();
+		} catch {
+			// Preserve the configuration failure.
+		}
+		throw error;
+	}
+}

package/plugins/acryl-db-sqlite/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * The SQLite provider of the `db` port (spec 049 slice 1): one `node:sqlite` file, opened with the ported facade's settings (WAL,
+ * `synchronous = NORMAL`, a busy timeout), migrated, and provided as `db`. App plugins declare `inject: ['db']` and import types from
+ * `acryl-db` only, so replacing this row with another provider does not touch them. The plugin is a thin wrapper over `openDb`
+ * (`acryl-db-sqlite/open`), the same opening for code without Cordis.
+ *
+ * Unloading withdraws `db` first, so consumers stop calling, and then closes the file: the close waits for running operations and
+ * transactions, checkpoints the WAL and releases the file.
+ */
+
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { DB_SERVICE } from '../../acryl-db/src/index.ts'
+import type {} from '../../acryl-db/src/cordis.ts'
+import { openDb } from './open.ts'
+
+export { NodeSqliteDatabase, openNodeSqliteDatabase, type NodeSqliteDatabaseOptions } from './facade/node.ts'
+export { openDb, type OpenDb, type OpenDbOptions } from './open.ts'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-db-sqlite'
+
+/**
+ * What this plugin reads of the runtime's optional `appInstance` service: its home folder. The service belongs to the runtime (and to an
+ * app's own instance plugin), so this plugin declares no type for it on Cordis' Context; it checks the one field it uses at runtime.
+ */
+interface AppHome {
+  readonly home: string
+}
+
+function isAppHome(value: unknown): value is AppHome {
+  return typeof value === 'object' && value !== null && 'home' in value && typeof value.home === 'string'
+}
+
+export interface Config {
+  path?: string
+  migrations?: string
+  busyTimeoutMs?: number
+  walAutoCheckpointPages?: number
+}
+
+export const Config: z<Config> = z.object({
+  path: z.string().description('The database file, absolute or relative to the app. Defaults to data.sqlite in the ACRYL app home; required where there is none.'),
+  migrations: z.string().description('A folder of NNN-name.sql files numbered from 1, absolute or relative to the app, applied in order on start.'),
+  busyTimeoutMs: z.natural().description('How long SQLite waits for a competing file lock, in milliseconds. Defaults to 5000.'),
+  walAutoCheckpointPages: z.natural().description('The WAL auto-checkpoint threshold in pages; 0 disables it. Defaults to 1000.'),
+})
+
+/** The file name used in the app home when `path` is not configured. */
+export const DEFAULT_FILE = 'data.sqlite'
+
+/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise. */
+function resolveFromApp(ctx: Context, path: string, option: string): string {
+  if (path.startsWith('file:')) return fileURLToPath(path)
+  if (isAbsolute(path)) return path
+  const base = ctx.baseUrl
+  if (base === undefined || !base.startsWith('file:')) {
+    throw new Error(`acryl-db-sqlite: ${option} ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`)
+  }
+  const appDir = base.endsWith('/') ? fileURLToPath(base) : dirname(fileURLToPath(base))
+  return resolve(appDir, path)
+}
+
+export async function apply(ctx: Context, rawConfig: Config = {}): Promise<void> {
+  const config = Config(rawConfig)
+  // The app home comes from the runtime's `appInstance` service when this runs inside an ACRYL app; a plain framework app names its file.
+  const appInstance: unknown = ctx.get('appInstance')
+  let file: string
+  if (config.path !== undefined) file = resolveFromApp(ctx, config.path, 'path')
+  else if (isAppHome(appInstance)) file = join(appInstance.home, DEFAULT_FILE)
+  else throw new Error('acryl-db-sqlite: no database path; set `path` in this row\'s config (there is no ACRYL app home to default to)')
+  const migrations = config.migrations === undefined ? undefined : resolveFromApp(ctx, config.migrations, 'migrations')
+  const options = {
+    path: file,
+    ...(migrations === undefined ? {} : { migrations }),
+    ...(config.busyTimeoutMs === undefined ? {} : { busyTimeoutMs: config.busyTimeoutMs }),
+    ...(config.walAutoCheckpointPages === undefined ? {} : { walAutoCheckpointPages: config.walAutoCheckpointPages }),
+  }
+
+  // Disposers run in reverse: the service is withdrawn before the file closes.
+  await ctx.effect(async function* () {
+    const opened = await openDb(options)
+    yield () => opened.close()
+    yield ctx.reflect.provide(DB_SERVICE, opened.db)
+  }, `acryl-db-sqlite: ${file}`)
+}

package/plugins/acryl-db-sqlite/src/open.ts

@@ -0,0 +1,61 @@
+/**
+ * The plain way to open the SQLite provider, for code without Cordis (an acrylblends app): `openDb({ path, migrations })` opens one
+ * `node:sqlite` file with the ported facade's settings (WAL, `synchronous = NORMAL`, a busy timeout) and foreign keys enforced, applies the
+ * numbered migrations, and resolves the `db` port with the function that closes it. The Cordis plugin is a thin wrapper over this, so both
+ * run one code path.
+ * This entry imports nothing from Cordis.
+ */
+
+import { applyMigrations, MIGRATIONS_TABLE, readMigrationFiles, type Db, type SqlValue } from '../../acryl-db/src/index.ts'
+import { openNodeSqliteDatabase } from './facade/node.ts'
+
+export type { Db, DbExecutor, SqlValue } from '../../acryl-db/src/index.ts'
+
+export interface OpenDbOptions {
+  /** The database file, its folder created if missing; `:memory:` for a database that lives until `close`. */
+  readonly path: string
+  /** A folder of `NNN-name.sql` files numbered from 1, as a path or a file URL, applied in order before `openDb` resolves. */
+  readonly migrations?: string | URL
+  /** How long SQLite waits for a competing file lock, in milliseconds. Defaults to 5000. */
+  readonly busyTimeoutMs?: number
+  /** The WAL auto-checkpoint threshold in pages; 0 disables it. Defaults to 1000. */
+  readonly walAutoCheckpointPages?: number
+}
+
+/** An open database: the port, and the one function that closes it. */
+export interface OpenDb {
+  readonly db: Db
+  /** Waits for running operations and transactions, checkpoints the WAL and releases the file. Calling it again does nothing. */
+  close(): Promise<void>
+}
+
+/**
+ * Open, configure and migrate a SQLite database.
+ * @throws when the migration files are misnamed or misnumbered, or a migration fails (the file is closed, and unchanged), or the
+ *   database's schema is newer than the migrations.
+ */
+export async function openDb(options: OpenDbOptions): Promise<OpenDb> {
+  const migrations = options.migrations === undefined ? [] : await readMigrationFiles(options.migrations)
+  const database = await openNodeSqliteDatabase(options.path, {
+    ...(options.busyTimeoutMs === undefined ? {} : { busyTimeoutMs: options.busyTimeoutMs }),
+    ...(options.walAutoCheckpointPages === undefined ? {} : { walAutoCheckpointPages: options.walAutoCheckpointPages }),
+  })
+  try {
+    // Off by default in SQLite, per connection, and ignored inside a transaction: set here, before the migrations' transaction. The port
+    // promises it (`ON DELETE CASCADE` works on every provider).
+    await database.exec('PRAGMA foreign_keys = ON')
+    await applyMigrations(database, migrations, { table: MIGRATIONS_TABLE })
+  } catch (error) {
+    await database.close()
+    throw error
+  }
+  // The port, not the adapter: the code that receives `db` gets no `close`, which belongs to whoever opened it.
+  const db: Db = {
+    exec: sql => database.exec(sql),
+    run: (sql, ...params) => database.run(sql, ...params),
+    get: <T extends object>(sql: string, ...params: SqlValue[]) => database.get<T>(sql, ...params),
+    all: <T extends object>(sql: string, ...params: SqlValue[]) => database.all<T>(sql, ...params),
+    transaction: work => database.transaction(work),
+  }
+  return { db, close: () => database.close() }
+}

package/plugins/acryl-db-sqlite/upstream.json

@@ -0,0 +1,21 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-db-sqlite",
+    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 9,
+  "digest": "sha256:853af986073e5721c9b8fb5626b46bcd1ca8a6c5f936c4ac11fc3c21f3c5c0ef",
+  "testsNotRun": {
+    "tests/loader.spec.ts": "loads the plugin through the real Loader (@deepseek-ai/cordis-plugin-loader), which generated apps do not install; the plain opener it wraps is tested here by open.spec.ts and conformance.spec.ts",
+    "tests/plain-entry-imports.spec.ts": "a copy vendored into an app (with relative imports, no build of its own) has neither `lib/`; the app's own typecheck is what proves the copy names no Cordis type it does not provide."
+  },
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/acryl-inspect/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-inspect",
-    "commit": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
+    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
   },
   "vendored": [
     "src",

package/plugins/acryl-node-server/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-node-server",
-    "commit": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
+    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
   },
   "vendored": [
     "src",

package/plugins/acryl-router/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router",
-    "commit": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
+    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
   },
   "vendored": [
     "src",

package/plugins/acryl-router-http/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router-http",
-    "commit": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
+    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
   },
   "vendored": [
     "src",

package/plugins/acryl-state/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-state",
-    "commit": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
+    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
   },
   "vendored": [
     "src",

package/plugins/desktop/upstream.json

@@ -5,7 +5,7 @@
       "apps/acryl-desktop/src/shell/desktop-user-data.ts": "user-data.ts",
       "apps/acryl-desktop/src/shell/shutdown.ts": "shutdown.ts"
     },
-    "commit": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
+    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
   },
   "rewrittenSpecifiers": 0,
   "digest": "sha256:7dfe960a8bbb476c35540d2202a7aaa62b33492c2ac3e34314e2ecfca45f32f2"

package/plugins/desktop-web/main.ts

@@ -1,5 +1,5 @@
 /**
- * The desktop shell of a plain Acryl app: `npm run desktop` serves the app (`src/app.ts`, `export default app`) on a free loopback port from this Electron main process and
+ * The desktop shell of a plain Acryl app: `npm run desktop` serves the app (`src/app.ts`: `export default app`, and optionally `export const close` for a database to close) on a free loopback port from this Electron main process and
  * opens one window on it. Nothing in the app imports electron; every Electron call is in this file and `window.ts`, so a different shell is a change here only.
  *
  * Order matters: the user-data folder is set before anything else (and before the single-instance lock), so one app never shares window state, logs or the lock with
@@ -36,13 +36,19 @@ if (!app.requestSingleInstanceLock()) {
 } else {
   let server: ReturnType<typeof serve> | undefined
   let window: BrowserWindow | undefined
+  /** The app module's optional `close`, for an app that owns a database: called once the server has stopped. */
+  let closeApp: (() => Promise<void>) | undefined
 
   const shutdown = createDesktopShutdown(
     () =>
       new Promise<void>((done) => {
         if (server === undefined) return done()
         server.close(() => {
-          done()
+          const closing = closeApp?.() ?? Promise.resolve()
+          closing.then(
+            () => done(),
+            () => done(),
+          )
         })
         // Open streams and keep-alive connections would hold close() open: end them.
         ;(server as { closeAllConnections?: () => void }).closeAllConnections?.()
@@ -67,7 +73,11 @@ if (!app.requestSingleInstanceLock()) {
 
   void app.whenReady().then(async () => {
     // The hook above is registered before the app's modules are loaded, so the app may have .tsx pages: they are loaded here, not as a static import.
-    const { default: acrylApp } = await import('../../app.ts')
+    const { default: acrylApp, close } = (await import('../../app.ts')) as {
+      default: { fetch: Parameters<typeof serve>[0]['fetch'] }
+      close?: () => Promise<void>
+    }
+    closeApp = close
     const port = await new Promise<number>((resolve) => {
       server = serve(
         { fetch: acrylApp.fetch, port: 0, hostname: '127.0.0.1' },

package/plugins/desktop-web/upstream.json

@@ -5,7 +5,7 @@
       "apps/acryl-desktop/src/shell/desktop-user-data.ts": "user-data.ts",
       "apps/acryl-desktop/src/shell/shutdown.ts": "shutdown.ts"
     },
-    "commit": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
+    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
   },
   "rewrittenSpecifiers": 0,
   "digest": "sha256:7dfe960a8bbb476c35540d2202a7aaa62b33492c2ac3e34314e2ecfca45f32f2"

package/plugins/tsconfig.json

@@ -23,6 +23,7 @@
     "acryl-*/src/**/*.case.ts",
     "acryl-node-server/tests/adapter",
     "acryl-router/tests/loader.spec.ts",
+    "acryl-db-sqlite/tests/loader.spec.ts",
     "acryl-state/src/react.ts",
     "acryl-state/tests/react.spec.ts",
     "acryl-router-http/tests/adapter.spec.ts",

package/templates/todo/upstream.json

@@ -5,7 +5,7 @@
       "examples/acryl-todo/src/index.ts": "src/todo.ts",
       "examples/acryl-todo/src/page.ts": "src/page.ts"
     },
-    "commit": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
+    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
   },
   "rewrittenSpecifiers": 4,
   "digest": "sha256:9093704776563001f7f472f94cc5c2fdd79206342c1cb59c11fce62aa74df3ed"