@fuzdev/fuz_app 0.132.1 → 0.134.0

package/dist/testing/db.d.ts

@@ -1,9 +1,5 @@
 import './assert_dev_env.js';
 import type { Db } from '../db/db.js';
-/**
- * CI detection — `CI=true` is set automatically by GitHub Actions, GitLab CI, etc.
- */
-export declare const IS_CI: boolean;
 /**
  * Factory interface for creating test database instances.
  */
@@ -15,75 +11,83 @@ export interface DbFactory {
     skip_reason?: string;
 }
 /**
- * Reset a test database to a clean state by dropping and recreating the public schema.
+ * Reset a test database to a clean slate by dropping and recreating the `public` schema.
  *
- * Removes all tables, sequences, indexes, types, and functions.
- * The database instance remains usable after reset. Despite the name it issues
- * plain SQL, so it also resets the other drivers the test factories hand out.
+ * `DROP SCHEMA public CASCADE; CREATE SCHEMA public` in plain SQL, so it resets
+ * every driver: the in-memory factories call it on each `create()`, and it is
+ * recommended at the start of `init_schema` callbacks for `create_pg_factory`,
+ * whose persistent databases accumulate stale DDL across fuz_app versions.
+ * Drift-proof — it wipes every table, type, and sequence regardless of
+ * namespace, so it needs no upkeep when the schema gains a table. The database
+ * instance remains usable after reset.
  *
  * @mutates db - drops the `public` schema and recreates it; all rows in all
  *   tables are gone after this returns.
  */
-export declare const reset_pglite: (db: Db) => Promise<void>;
+export declare const reset_public_schema: (db: Db) => Promise<void>;
 /**
- * Builds a `DbFactory` from a schema initializer — `create_pglite_factory`'s own shape.
+ * Builds a `DbFactory` from a schema initializer — the shape of every factory builder here.
  */
 export type DbFactoryBuilder = (init_schema: (db: Db) => Promise<void>) => DbFactory;
 /**
- * Options for `create_pglite_factory`.
+ * Create a PGlite (in-memory) database factory for tests.
+ *
+ * Always enabled — needs the optional `@electric-sql/pglite` peer installed.
+ * Shares one PGlite WASM instance across the PGlite factories this module
+ * builds; each `create()` resets the schema via `DROP SCHEMA public CASCADE`
+ * instead of paying the cold start again.
+ *
+ * @param init_schema - callback to initialize the database schema
  */
-export interface CreatePgliteFactoryOptions {
-    /**
-     * Whether an installed substitute (`set_substitute_db_factory`) may stand in
-     * for the PGlite factory at this call site. Defaults to `true`; pass `false`
-     * where PGlite itself is the subject under test.
-     */
-    substitutable?: boolean;
-}
+export declare const create_pglite_factory: DbFactoryBuilder;
 /**
- * Install a builder that stands in for `create_pglite_factory`, so suites
- * written against PGlite can run against another driver without being edited.
+ * Create a pglet-wasm (in-memory) database factory for tests.
+ *
+ * Always enabled — needs the optional `@fuzdev/pglet-wasm` peer installed.
+ * Shares one pglet instance across the pglet-wasm factories this module
+ * builds, created with fuz_app's value coercion (`PGLET_COERCION`); each
+ * `create()` resets the schema via `DROP SCHEMA public CASCADE`.
  *
- * Injected rather than selected here: the drivers a substitute wraps live in
- * test-side code this shipped module cannot import. A call site that passes
- * `{substitutable: false}` keeps PGlite regardless. Pass `null` to uninstall.
+ * @param init_schema - callback to initialize the database schema
+ */
+export declare const create_pglet_wasm_factory: DbFactoryBuilder;
+/**
+ * Install the builder `create_default_db_factory` uses, so suites written
+ * against the default run against another driver without being edited —
+ * `create_pglite_factory` to run them on PGlite. Pass `null` to restore
+ * pglet-wasm.
  *
  * The slot is read when a factory is built, not when it creates a database,
- * so install before the first `create_pglite_factory` call — a vitest
+ * so install before the first `create_default_db_factory` call — a vitest
  * `setupFiles` entry, which runs ahead of every test file's imports, is the
  * shape fuz_app's own `db` project uses. A factory built earlier (including
  * the module-level fallback in `testing/app_server.ts`) keeps the driver it
  * was built with, and uninstalling does not revert it.
  *
- * @param create_factory - the builder to install, or `null` to remove the installed one
+ * @param create_factory - the builder to install, or `null` to restore the default
+ * @returns the builder this replaced (`null` for pglet-wasm), so a caller can put it back
  */
-export declare const set_substitute_db_factory: (create_factory: DbFactoryBuilder | null) => void;
+export declare const set_default_db_factory: (create_factory: DbFactoryBuilder | null) => DbFactoryBuilder | null;
 /**
- * Create a pglite (in-memory) database factory for tests.
- *
- * Always enabled — no external dependencies required.
- * Shares a single PGlite WASM instance across the PGlite factories this module builds.
- * Subsequent `create()` calls reset the schema via `DROP SCHEMA public CASCADE`
- * instead of paying the WASM cold-start cost again.
+ * Create the default in-memory database factory for tests: pglet-wasm, or the
+ * builder `set_default_db_factory` installed.
  *
- * Returns the installed substitute's factory instead when one is installed and
- * `options.substitutable` is not `false` — see `set_substitute_db_factory`.
+ * The factory fuz_app's own test helpers fall back to when a suite passes none
+ * (`create_test_app_server`, `describe_rate_limiting_tests`,
+ * `describe_sse_route_tests`). Call `create_pglite_factory` or
+ * `create_pglet_wasm_factory` directly to pin a driver.
  *
  * @param init_schema - callback to initialize the database schema
- * @param options - `substitutable: false` pins this call site to PGlite
  */
-export declare const create_pglite_factory: (init_schema: (db: Db) => Promise<void>, options?: CreatePgliteFactoryOptions) => DbFactory;
+export declare const create_default_db_factory: DbFactoryBuilder;
 /**
  * Create a pg (PostgreSQL) database factory for tests.
  *
- * Skipped when `test_url` is not provided.
- * Drops `schema_version` before running `init_schema`, forcing migrations
- * to re-evaluate against the actual tables. Prevents stale tracker rows
- * from skipping migrations when DDL changes between test sessions.
- *
- * For full clean-slate behavior (recommended), call `drop_auth_schema(db)`
- * at the start of `init_schema` before running migrations. This handles
- * upstream schema changes that go beyond adding new tables/columns.
+ * Skipped when `test_url` is not provided. Each `create()` opens a pool,
+ * resets the `public` schema (`reset_public_schema`) and runs `init_schema` —
+ * the lifecycle every factory here shares, so a persistent test database never
+ * carries stale DDL or tracker rows from an earlier run or another suite's
+ * schema. Point `test_url` at a database used only for tests.
  *
  * @param init_schema - callback to initialize the database schema
  * @param test_url - PostgreSQL connection URL (e.g. from `TEST_DATABASE_URL`)
@@ -107,21 +111,6 @@ export declare const auth_truncate_tables: string[];
  * touch audit logging don't need to truncate it.
  */
 export declare const auth_integration_truncate_tables: string[];
-/**
- * Reset the entire `public` schema for a clean slate before re-migration.
- *
- * Recommended at the start of `init_schema` callbacks for `create_pg_factory`.
- * Persistent test databases accumulate stale DDL across fuz_app versions;
- * `DROP SCHEMA public CASCADE; CREATE SCHEMA public` wipes every table, type,
- * and sequence regardless of namespace, so migrations always run against a
- * truly empty database. Drift-proof — unlike a hand-maintained drop list it
- * needs no upkeep when the schema gains a table. Despite the historical name,
- * this resets the whole schema, not just auth tables (the only documented use
- * is clean-slate re-migration, which always wanted a full reset).
- *
- * @mutates db - drops and recreates the `public` schema; all tables gone.
- */
-export declare const drop_auth_schema: (db: Db) => Promise<void>;
 /**
  * Create a `describe_db` function bound to specific factories and truncate tables.
  *

package/dist/testing/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/db.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AA8B7B,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAMtC;;GAEG;AACH,eAAO,MAAM,KAAK,SAA4B,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,OAAO,CAAC,EAAE,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAU,IAAI,EAAE,KAAG,OAAO,CAAC,IAAI,CAGvD,CAAC;AAQF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC;AAErF;;GAEG;AACH,MAAM,WAAW,0BAA0B;IAC1C;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB,GAAI,gBAAgB,gBAAgB,GAAG,IAAI,KAAG,IAEnF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GACjC,aAAa,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,EACtC,UAAU,0BAA0B,KAClC,SAyBF,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,aAAa,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,EACtC,WAAW,MAAM,KACf,SAgEF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,UAQhC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,UAAyC,CAAC;AAEvF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAAU,IAAI,EAAE,KAAG,OAAO,CAAC,IAAI,CAG3D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,GAC9B,WAAW,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,EACvC,iBAAiB,KAAK,CAAC,MAAM,CAAC,KAC5B,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,KAAK,IAAI,CAwBzD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAI,WAAW,KAAK,CAAC,SAAS,CAAC,KAAG,IAQnE,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB,GACrC,IAAI,EAAE,EACN,OAAO,MAAM,EACb,SAAS,aAAa,CAAC,MAAM,CAAC,KAC5B,OAAO,CAAC,IAAI,CAId,CAAC"}
+{"version":3,"file":"db.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/db.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AA8B7B,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAQtC;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,OAAO,CAAC,EAAE,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,GAAU,IAAI,EAAE,KAAG,OAAO,CAAC,IAAI,CAG9D,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC;AAgDrF;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,gBACqC,CAAC;AAE1E;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,EAAE,gBACyC,CAAC;AAKlF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,GAClC,gBAAgB,gBAAgB,GAAG,IAAI,KACrC,gBAAgB,GAAG,IAIrB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,EAAE,gBAC+B,CAAC;AAExE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,GAC7B,aAAa,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,EACtC,WAAW,MAAM,KACf,SA6DF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,UAQhC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,UAAyC,CAAC;AAEvF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,GAC9B,WAAW,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,EACvC,iBAAiB,KAAK,CAAC,MAAM,CAAC,KAC5B,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,KAAK,IAAI,CAwBzD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAI,WAAW,KAAK,CAAC,SAAS,CAAC,KAAG,IAQnE,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB,GACrC,IAAI,EAAE,EACN,OAAO,MAAM,EACb,SAAS,aAAa,CAAC,MAAM,CAAC,KAC5B,OAAO,CAAC,IAAI,CAId,CAAC"}

package/dist/testing/db.js

@@ -2,129 +2,153 @@ import './assert_dev_env.js';
 /**
  * Test database fixtures for parameterized testing.
  *
- * Provides factory builders for creating test databases with pglite (in-memory)
- * and pg (PostgreSQL) drivers. Consumer projects provide their own schema
- * initialization via `run_migrations` and compose factories into test suites.
+ * Provides factory builders for creating test databases with pglet-wasm (the
+ * in-memory default), PGlite (in-memory) and pg (PostgreSQL) drivers. Consumer
+ * projects provide their own schema initialization via `run_migrations` and
+ * compose factories into test suites.
  *
  * @example
  * ```ts
- * import {create_pglite_factory, create_pg_factory} from '@fuzdev/fuz_app/testing/db.ts';
+ * import {create_default_db_factory, create_pg_factory} from '@fuzdev/fuz_app/testing/db.ts';
  * import {run_migrations} from '@fuzdev/fuz_app/db/migrate.ts';
  * import {auth_migration_ns} from '@fuzdev/fuz_app/auth/migrations.ts';
  *
  * const init_schema = async (db) => {
  *   await run_migrations(db, [auth_migration_ns]);
  * };
- * const pglite_factory = create_pglite_factory(init_schema);
+ * const default_factory = create_default_db_factory(init_schema);
  * const pg_factory = create_pg_factory(init_schema, process.env.TEST_DATABASE_URL);
- * export const db_factories = [pglite_factory, pg_factory];
+ * export const db_factories = [default_factory, pg_factory];
  * ```
  *
  * @module
  */
 import { describe, beforeAll, beforeEach, afterAll, assert } from 'vitest';
-import { to_error_message } from '@fuzdev/fuz_util/error.ts';
 import { create_pglite_db } from '../db/db_pglite.js';
+import { create_pglet_db_driver, create_pglet_instance } from '../db/db_pglet.js';
 import { assert_valid_sql_identifier } from '../db/sql_identifier.js';
 import { create_pg_db, register_pg_type_parsers } from '../db/db_pg.js';
 import { query_public_columns } from '../db/schema_ready.js';
+import { pg_error_code } from '../db/pg_error.js';
 /**
- * CI detection — `CI=true` is set automatically by GitHub Actions, GitLab CI, etc.
- */
-export const IS_CI = process.env.CI === 'true';
-/**
- * Reset a test database to a clean state by dropping and recreating the public schema.
+ * Reset a test database to a clean slate by dropping and recreating the `public` schema.
  *
- * Removes all tables, sequences, indexes, types, and functions.
- * The database instance remains usable after reset. Despite the name it issues
- * plain SQL, so it also resets the other drivers the test factories hand out.
+ * `DROP SCHEMA public CASCADE; CREATE SCHEMA public` in plain SQL, so it resets
+ * every driver: the in-memory factories call it on each `create()`, and it is
+ * recommended at the start of `init_schema` callbacks for `create_pg_factory`,
+ * whose persistent databases accumulate stale DDL across fuz_app versions.
+ * Drift-proof — it wipes every table, type, and sequence regardless of
+ * namespace, so it needs no upkeep when the schema gains a table. The database
+ * instance remains usable after reset.
  *
  * @mutates db - drops the `public` schema and recreates it; all rows in all
  *   tables are gone after this returns.
  */
-export const reset_pglite = async (db) => {
+export const reset_public_schema = async (db) => {
     await db.query('DROP SCHEMA public CASCADE');
     await db.query('CREATE SCHEMA public');
 };
-// Module-level PGlite cache — one instance shared by the PGlite factories this
-// module builds, for as long as the module is loaded. Under the `db` project's
-// `isolate: false` + `fileParallelism: false` that is the whole run; a project
-// that isolates its files gets one per worker instead.
-let module_db = null;
-// The installed stand-in for `create_pglite_factory`, `null` when none is installed.
-let substitute_db_factory = null;
 /**
- * Install a builder that stands in for `create_pglite_factory`, so suites
- * written against PGlite can run against another driver without being edited.
+ * Build a factory over one module-level instance per driver: the first
+ * `create()` creates it, and each `create()` resets its `public` schema and
+ * runs `init_schema`, so only the first pays the WASM cold start.
  *
- * Injected rather than selected here: the drivers a substitute wraps live in
- * test-side code this shipped module cannot import. A call site that passes
- * `{substitutable: false}` keeps PGlite regardless. Pass `null` to uninstall.
+ * The instance lives as long as this module stays loaded — under the `db`
+ * project's `isolate: false` + `fileParallelism: false` that is the whole run;
+ * a project that isolates its files gets one per worker. A promise rather than
+ * a value, so two concurrent first `create()` calls build one instance, and a
+ * failed first load is the error every later `create()` reports.
+ */
+const create_shared_instance_factory = (name, resolve_db, init_schema) => {
+    return {
+        name,
+        skip: false,
+        async create() {
+            const db = await resolve_db();
+            // the instance is shared with every factory of this driver, so it may hold any schema
+            await reset_public_schema(db);
+            await init_schema(db);
+            return db;
+        },
+        async close() {
+            // No-op: the instance is module-level, so it lives as long as this module
+            // stays loaded. Nothing frees it earlier.
+        }
+    };
+};
+// The module-level instances the shared factories hand out, created on first use.
+let pglite_db = null;
+let pglet_wasm_db = null;
+const resolve_pglite_db = () => (pglite_db ??= (async () => {
+    const { PGlite } = await import('@electric-sql/pglite');
+    return create_pglite_db(new PGlite()).db;
+})());
+const resolve_pglet_wasm_db = () => (pglet_wasm_db ??= create_pglet_instance().then((pglet) => create_pglet_db_driver(pglet).db));
+/**
+ * Create a PGlite (in-memory) database factory for tests.
+ *
+ * Always enabled — needs the optional `@electric-sql/pglite` peer installed.
+ * Shares one PGlite WASM instance across the PGlite factories this module
+ * builds; each `create()` resets the schema via `DROP SCHEMA public CASCADE`
+ * instead of paying the cold start again.
+ *
+ * @param init_schema - callback to initialize the database schema
+ */
+export const create_pglite_factory = (init_schema) => create_shared_instance_factory('pglite', resolve_pglite_db, init_schema);
+/**
+ * Create a pglet-wasm (in-memory) database factory for tests.
+ *
+ * Always enabled — needs the optional `@fuzdev/pglet-wasm` peer installed.
+ * Shares one pglet instance across the pglet-wasm factories this module
+ * builds, created with fuz_app's value coercion (`PGLET_COERCION`); each
+ * `create()` resets the schema via `DROP SCHEMA public CASCADE`.
+ *
+ * @param init_schema - callback to initialize the database schema
+ */
+export const create_pglet_wasm_factory = (init_schema) => create_shared_instance_factory('pglet-wasm', resolve_pglet_wasm_db, init_schema);
+// The builder `create_default_db_factory` uses, `null` for pglet-wasm.
+let default_db_factory_builder = null;
+/**
+ * Install the builder `create_default_db_factory` uses, so suites written
+ * against the default run against another driver without being edited —
+ * `create_pglite_factory` to run them on PGlite. Pass `null` to restore
+ * pglet-wasm.
  *
  * The slot is read when a factory is built, not when it creates a database,
- * so install before the first `create_pglite_factory` call — a vitest
+ * so install before the first `create_default_db_factory` call — a vitest
  * `setupFiles` entry, which runs ahead of every test file's imports, is the
  * shape fuz_app's own `db` project uses. A factory built earlier (including
  * the module-level fallback in `testing/app_server.ts`) keeps the driver it
  * was built with, and uninstalling does not revert it.
  *
- * @param create_factory - the builder to install, or `null` to remove the installed one
+ * @param create_factory - the builder to install, or `null` to restore the default
+ * @returns the builder this replaced (`null` for pglet-wasm), so a caller can put it back
  */
-export const set_substitute_db_factory = (create_factory) => {
-    substitute_db_factory = create_factory;
+export const set_default_db_factory = (create_factory) => {
+    const previous = default_db_factory_builder;
+    default_db_factory_builder = create_factory;
+    return previous;
 };
 /**
- * Create a pglite (in-memory) database factory for tests.
- *
- * Always enabled — no external dependencies required.
- * Shares a single PGlite WASM instance across the PGlite factories this module builds.
- * Subsequent `create()` calls reset the schema via `DROP SCHEMA public CASCADE`
- * instead of paying the WASM cold-start cost again.
+ * Create the default in-memory database factory for tests: pglet-wasm, or the
+ * builder `set_default_db_factory` installed.
  *
- * Returns the installed substitute's factory instead when one is installed and
- * `options.substitutable` is not `false` — see `set_substitute_db_factory`.
+ * The factory fuz_app's own test helpers fall back to when a suite passes none
+ * (`create_test_app_server`, `describe_rate_limiting_tests`,
+ * `describe_sse_route_tests`). Call `create_pglite_factory` or
+ * `create_pglet_wasm_factory` directly to pin a driver.
  *
  * @param init_schema - callback to initialize the database schema
- * @param options - `substitutable: false` pins this call site to PGlite
  */
-export const create_pglite_factory = (init_schema, options) => {
-    if (substitute_db_factory && options?.substitutable !== false) {
-        return substitute_db_factory(init_schema);
-    }
-    return {
-        name: 'pglite',
-        skip: false,
-        async create() {
-            if (module_db) {
-                await reset_pglite(module_db);
-            }
-            else {
-                const { PGlite } = await import('@electric-sql/pglite');
-                const pglite = new PGlite();
-                module_db = create_pglite_db(pglite).db;
-            }
-            await init_schema(module_db);
-            return module_db;
-        },
-        async close() {
-            // No-op: the instance is the module-level cache above, so it lives as long
-            // as this module stays loaded — under the `db` project's `isolate: false` +
-            // `fileParallelism: false` that is the whole run. Nothing frees the PGlite
-            // instance earlier.
-        }
-    };
-};
+export const create_default_db_factory = (init_schema) => (default_db_factory_builder ?? create_pglet_wasm_factory)(init_schema);
 /**
  * Create a pg (PostgreSQL) database factory for tests.
  *
- * Skipped when `test_url` is not provided.
- * Drops `schema_version` before running `init_schema`, forcing migrations
- * to re-evaluate against the actual tables. Prevents stale tracker rows
- * from skipping migrations when DDL changes between test sessions.
- *
- * For full clean-slate behavior (recommended), call `drop_auth_schema(db)`
- * at the start of `init_schema` before running migrations. This handles
- * upstream schema changes that go beyond adding new tables/columns.
+ * Skipped when `test_url` is not provided. Each `create()` opens a pool,
+ * resets the `public` schema (`reset_public_schema`) and runs `init_schema` —
+ * the lifecycle every factory here shares, so a persistent test database never
+ * carries stale DDL or tracker rows from an earlier run or another suite's
+ * schema. Point `test_url` at a database used only for tests.
  *
  * @param init_schema - callback to initialize the database schema
  * @param test_url - PostgreSQL connection URL (e.g. from `TEST_DATABASE_URL`)
@@ -166,17 +190,14 @@ export const create_pg_factory = (init_schema, test_url) => {
             pool_ref = pool;
             const { db } = create_pg_db(pool);
             try {
-                // Drop schema_version so migrations re-evaluate against the actual
-                // tables. Prevents stale tracker rows from skipping migrations
-                // when DDL changes between test sessions. Migrations use
-                // IF NOT EXISTS guards, so re-running is safe.
-                await db.query('DROP TABLE IF EXISTS schema_version');
+                await reset_public_schema(db);
                 await init_schema(db);
             }
             catch (error) {
                 await pool.end();
-                const msg = to_error_message(error);
-                if (msg.includes('does not exist')) {
+                // 3D000 invalid_catalog_name — the database itself is missing, not
+                // something a migration referenced
+                if (pg_error_code(error) === '3D000') {
                     const db_name = test_url.split('/').pop()?.split('?')[0] ?? 'test_db';
                     throw new Error(`Database "${db_name}" does not exist. Create it with: createdb ${db_name}`);
                 }
@@ -219,24 +240,6 @@ export const auth_truncate_tables = [
  * touch audit logging don't need to truncate it.
  */
 export const auth_integration_truncate_tables = [...auth_truncate_tables, 'audit_log'];
-/**
- * Reset the entire `public` schema for a clean slate before re-migration.
- *
- * Recommended at the start of `init_schema` callbacks for `create_pg_factory`.
- * Persistent test databases accumulate stale DDL across fuz_app versions;
- * `DROP SCHEMA public CASCADE; CREATE SCHEMA public` wipes every table, type,
- * and sequence regardless of namespace, so migrations always run against a
- * truly empty database. Drift-proof — unlike a hand-maintained drop list it
- * needs no upkeep when the schema gains a table. Despite the historical name,
- * this resets the whole schema, not just auth tables (the only documented use
- * is clean-slate re-migration, which always wanted a full reset).
- *
- * @mutates db - drops and recreates the `public` schema; all tables gone.
- */
-export const drop_auth_schema = async (db) => {
-    await db.query('DROP SCHEMA public CASCADE');
-    await db.query('CREATE SCHEMA public');
-};
 /**
  * Create a `describe_db` function bound to specific factories and truncate tables.
  *

package/dist/testing/rate_limiting.d.ts

@@ -16,7 +16,8 @@ export interface RateLimitingTestOptions {
     /** Optional overrides for `AppServerOptions`. */
     app_options?: SuiteAppOptions;
     /**
-     * Database factories to run tests against. Default: pglite only.
+     * Database factories to run tests against. Default: the default factory
+     * (`create_default_db_factory`) only.
      */
     db_factories?: Array<DbFactory>;
     /**

package/dist/testing/rate_limiting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate_limiting.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/rate_limiting.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AA0B7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAIvD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAIhE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;OAEG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,uBAAuB,CAAC;CACxC;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,uBAAuB,KAAG,IAqK/E,CAAC"}
+{"version":3,"file":"rate_limiting.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/rate_limiting.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AA0B7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAIvD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAIhE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,uBAAuB,CAAC;CACxC;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,uBAAuB,KAAG,IAqK/E,CAAC"}

package/dist/testing/rate_limiting.js

@@ -25,7 +25,7 @@ import { RateLimiter } from '../rate_limiter.js';
 import { RateLimitError } from '../http/error_schemas.js';
 import { auth_migration_ns } from '../auth/migrations.js';
 import { create_test_app } from './app_server.js';
-import { create_pglite_factory, create_describe_db, auth_integration_truncate_tables } from './db.js';
+import { create_default_db_factory, create_describe_db, auth_integration_truncate_tables } from './db.js';
 import { find_auth_route, assert_rate_limit_retry_after_header } from './integration_helpers.js';
 import { run_migrations } from '../db/migrate.js';
 /**
@@ -49,7 +49,7 @@ export const describe_rate_limiting_tests = (options) => {
     const init_schema = async (db) => {
         await run_migrations(db, [auth_migration_ns]);
     };
-    const factories = options.db_factories ?? [create_pglite_factory(init_schema)];
+    const factories = options.db_factories ?? [create_default_db_factory(init_schema)];
     const describe_db = create_describe_db(factories, auth_integration_truncate_tables);
     /** Create a tight rate limiter for testing — low attempt count, long window. */
     const create_test_rate_limiter = () => new RateLimiter({ max_attempts, window_ms: 60_000, cleanup_interval_ms: 0 });

package/dist/testing/sse_round_trip.d.ts

@@ -41,7 +41,7 @@ export interface SseRouteTestOptions {
     create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
     /** Optional overrides for `AppServerOptions`. */
     app_options?: SuiteAppOptions;
-    /** Database factories to run tests against. Default: pglite only. */
+    /** Database factories to run tests against. Default: the default factory (`create_default_db_factory`) only. */
     db_factories?: Array<DbFactory>;
     /**
      * Backend audit event callback — threaded to `create_test_app_server`.

package/dist/testing/sse_round_trip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/sse_round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAmB7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,oBAAoB,CAAC;AAGrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAGjE,OAAO,EAEN,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAyB,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAEhE,OAAO,EAIN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAO1B,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAChC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E;;;OAGG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IACnC,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,qDAAqD;IACrD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,qEAAqE;IACrE,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAChD;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC,8BAA8B;IAC9B,MAAM,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;CAChC;AAmDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,mBAAmB,KAAG,IAkIvE,CAAC"}
+{"version":3,"file":"sse_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/sse_round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAmB7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,oBAAoB,CAAC;AAGrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAGjE,OAAO,EAEN,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpE,OAAO,EAIN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAO1B,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAChC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E;;;OAGG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IACnC,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,qDAAqD;IACrD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,gHAAgH;IAChH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAChD;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC,8BAA8B;IAC9B,MAAM,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;CAChC;AAmDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,mBAAmB,KAAG,IAkIvE,CAAC"}

package/dist/testing/sse_round_trip.js

@@ -18,7 +18,7 @@ import { SSE_CONNECTED_COMMENT } from '../realtime/sse_constants.js';
 import { ROLE_ADMIN } from '../auth/role_schema.js';
 import { create_audit_emitter } from '../auth/audit_emitter.js';
 import { create_test_app } from './app_server.js';
-import { create_pglite_factory } from './db.js';
+import { create_default_db_factory } from './db.js';
 import { find_route_spec, pick_auth_headers } from './integration_helpers.js';
 import { rpc_call, require_rpc_endpoint_path, resolve_rpc_endpoints_for_setup } from './rpc_helpers.js';
 import { run_migrations } from '../db/migrate.js';
@@ -74,7 +74,7 @@ export const describe_sse_route_tests = (options) => {
     const init_schema = async (db) => {
         await run_migrations(db, [auth_migration_ns]);
     };
-    const factories = options.db_factories ?? [create_pglite_factory(init_schema)];
+    const factories = options.db_factories ?? [create_default_db_factory(init_schema)];
     for (const factory of factories) {
         const describe_fn = factory.skip ? describe.skip : describe;
         describe_fn(`SSE validation (${factory.name})`, () => {

package/dist/testing/stubs.js

@@ -160,7 +160,7 @@ export const create_stub_app_deps = () => ({
  * @param options - the deps and `close` to use in place of the defaults
  */
 export const create_stub_app_backend = (options) => ({
-    db_type: 'pglite-memory',
+    db_type: 'pglet-memory',
     db_name: 'test',
     migration_results: [],
     close: options?.close ?? (async () => { }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.132.1",
+  "version": "0.134.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",
@@ -35,6 +35,7 @@
     "@fuzdev/blake3-wasm": ">=0.2.0",
     "@fuzdev/fuz_css": ">=0.65.0",
     "@fuzdev/fuz_util": ">=0.70.0",
+    "@fuzdev/pglet-wasm": ">=0.1.1",
     "@hono/bun": ">=1",
     "@hono/deno": ">=1",
     "@hono/node-server": ">=1",
@@ -55,6 +56,9 @@
     "@fuzdev/fuz_css": {
       "optional": true
     },
+    "@fuzdev/pglet-wasm": {
+      "optional": true
+    },
     "@hono/bun": {
       "optional": true
     },
@@ -86,12 +90,13 @@
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.8",
     "@fuzdev/blake3-wasm": "^0.2.0",
-    "@fuzdev/fuz_code": "^0.50.0",
+    "@fuzdev/fuz_code": "^0.52.1",
     "@fuzdev/fuz_css": "^0.66.1",
     "@fuzdev/fuz_ui": "^0.213.0",
     "@fuzdev/fuz_util": "^0.72.0",
     "@fuzdev/gro": "^0.216.0",
     "@fuzdev/mdz": "^0.4.0",
+    "@fuzdev/pglet-wasm": "^0.1.1",
     "@hono/bun": "^1.0.1",
     "@hono/deno": "^1.0.3",
     "@hono/node-server": "^1.19.14",
@@ -116,7 +121,7 @@
     "pg": "^8.20.0",
     "svelte": "^5.57.2",
     "svelte-check": "^4.7.6",
-    "svelte-docinfo": "^0.8.1",
+    "svelte-docinfo": "^0.9.0",
     "svelte2tsx": "^0.7.52",
     "tslib": "^2.8.1",
     "typescript": "^6.0.3",