@cavulsqa/create 2.9.3 → 2.10.0

package/templates/m3e-app/src/shared/database/candidates/types.ts

@@ -0,0 +1,56 @@
+import type { Dialect } from "kysely";
+
+/**
+ * Every engine this template offers, as values rather than only as a type.
+ *
+ * A types-only union cannot be read at runtime, and everything that needs the list had to invent
+ * its own copy: `@cavulsqa/create` was regexing this very file to populate `--engine`, and
+ * `localStorage`'s override was cast rather than checked.
+ */
+export const STORAGE_IDS = [
+  "sqlite-wasm-opfs-sahpool",
+  "wa-sqlite-access-handle-pool",
+  "wa-sqlite-opfs-async",
+  "wa-sqlite-idb-batch-atomic",
+  "capacitor-sqlite",
+] as const;
+
+export type StorageId = (typeof STORAGE_IDS)[number];
+
+export function isStorageId(value: string): value is StorageId {
+  return (STORAGE_IDS as readonly string[]).includes(value);
+}
+
+/**
+ * A union rather than an optional field, so an unsupported probe cannot forget its reason and a
+ * supported one cannot carry a stale one.
+ */
+export type StorageProbe = { supported: true } | { supported: false; reason: string };
+
+/**
+ * One way to persist SQLite, described well enough to choose between them without reading the code.
+ *
+ * A candidate is not a config flag: it owns its own capability check and its own lazy import, so a
+ * chain that never reaches the fourth entry never downloads the fourth entry's wasm.
+ */
+export interface StorageCandidate {
+  id: StorageId;
+  label: string;
+  /** What it costs. Every entry has one, and an entry claiming none is a lie. */
+  tradeoff: string;
+  durable: boolean;
+  /**
+   * Whether the numbers behind its position in the chain came from a device or from a vendor's
+   * README. Only one entry is currently `measured`, and the ordering says so rather than implying
+   * more confidence than we have.
+   */
+  evidence: "measured" | "expected";
+  probe: () => StorageProbe;
+  createDialect: () => Promise<Dialect>;
+}
+
+export interface StorageAttempt {
+  id: StorageId;
+  outcome: "opened" | "unsupported" | "failed";
+  detail?: string;
+}

package/templates/m3e-app/src/shared/database/candidates/waSqlite.ts

@@ -0,0 +1,56 @@
+import { createWaDialect, type WaVfsKind } from "@cavulsqa/mobile-db/wa";
+import WaWorker from "../wa.worker?worker";
+import { probeIndexedDb, probeOpfsCapable } from "../storage";
+import type { StorageCandidate } from "./types";
+
+/**
+ * wa-sqlite, once per virtual file system.
+ *
+ * The alternative to the official build, and the reason it is here: its VFS layer is JavaScript, so
+ * it reaches storage the official engine has no VFS for. IndexedDB in particular is the only durable
+ * option on a WebView too old for synchronous access handles - the Chromium 86 to 108 band, which
+ * runs this app's bundle perfectly well.
+ *
+ * All three share one worker file and one dialect; only `kind` differs, and it also decides which of
+ * wa-sqlite's two wasm builds gets loaded.
+ */
+function waCandidate(
+  kind: WaVfsKind,
+  fields: Pick<StorageCandidate, "id" | "label" | "tradeoff" | "probe">,
+): StorageCandidate {
+  return {
+    ...fields,
+    durable: true,
+    // Nothing below the official pool has been on a phone yet.
+    evidence: "expected",
+    createDialect: () =>
+      Promise.resolve(createWaDialect({ worker: new WaWorker(), name: "app-wa.sqlite3", kind })),
+  };
+}
+
+export const waAccessHandlePool = waCandidate("access-handle-pool", {
+  id: "wa-sqlite-access-handle-pool",
+  label: "wa-sqlite · OPFS access handle pool",
+  tradeoff:
+    "The same exclusive directory lock as the official pool, and the same serial worker. Here to " +
+    "measure one vendor's pool against the other's on identical storage.",
+  probe: probeOpfsCapable,
+});
+
+export const waOriginPrivateFileSystem = waCandidate("origin-private-file-system", {
+  id: "wa-sqlite-opfs-async",
+  label: "wa-sqlite · OPFS, no pool",
+  tradeoff:
+    "Runs on the Asyncify build, which wraps every call SQLite believes is synchronous - expected " +
+    "to cost raw speed and to handle concurrent access more gracefully than a pool that locks.",
+  probe: probeOpfsCapable,
+});
+
+export const waIdbBatchAtomic = waCandidate("idb-batch-atomic", {
+  id: "wa-sqlite-idb-batch-atomic",
+  label: "wa-sqlite · IndexedDB",
+  tradeoff:
+    "The slowest durable route: pages go through IndexedDB transactions rather than to a file. The " +
+    "only one that works without synchronous access handles at all.",
+  probe: probeIndexedDb,
+});

package/templates/m3e-app/src/shared/database/database.ts

@@ -0,0 +1,219 @@
+import { Kysely, sql, type Dialect } from "kysely";
+import { Migrator } from "kysely/migration";
+import { runWrite, type MobileDatabase } from "@cavulsqa/mobile-db";
+import { createChangeBus, createReactiveDb } from "@cavulsqa/reactive-db";
+import { pragmaProfile, pragmasFor } from "@/app/pragmas.config";
+import { preferredEngine, storageChain } from "@/app/storage.config";
+import { isStorageId, type StorageAttempt, type StorageCandidate } from "./candidates";
+import { migrations } from "./migrations";
+import { describeOpenFailure } from "./storage";
+import type { Database } from "./schema";
+
+/** Writes and reactive queries must share one instance, so it is created here and passed outward. */
+export const changeBus = createChangeBus<Database>();
+
+const RETRY_DELAY_MS = 400;
+
+let database: MobileDatabase<Database> | null = null;
+let opening: Promise<MobileDatabase<Database>> | null = null;
+let chosen: StorageCandidate | null = null;
+let attempts: StorageAttempt[] = [];
+let applied: readonly string[] = [];
+
+interface OpenedDatabase {
+  handle: MobileDatabase<Database>;
+  pragmas: readonly string[];
+}
+
+/**
+ * Wraps a Kysely instance in the shape the app consumes, and runs the migrations. Shared by every
+ * candidate: they differ in how bytes reach storage and in nothing above it, which is what makes the
+ * chain swappable at all.
+ */
+async function fromDialect(candidate: StorageCandidate, dialect: Dialect): Promise<OpenedDatabase> {
+  const db = new Kysely<Database>({ dialect });
+
+  // Before the migrations, and identically for every engine - see pragmas.config.ts for why.
+  const pragmas: string[] = [];
+  for (const pragma of pragmasFor(pragmaProfile)) {
+    try {
+      await sql.raw(pragma).execute(db);
+      pragmas.push(pragma);
+    } catch (error) {
+      // A VFS that refuses a journal mode is worth knowing about, not worth failing over.
+      pragmas.push(`${pragma} -> rejected: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+  }
+
+  // `migrateToLatest` reports failure in its return value rather than throwing, so an unchecked
+  // call boots an app whose tables were never created - it surfaced as "no such table" much later.
+  const migration = await new Migrator({
+    db,
+    provider: { getMigrations: () => Promise.resolve(migrations) },
+  }).migrateToLatest();
+
+  if (migration.error) {
+    const failed = migration.results?.find((result) => result.status === "Error")?.migrationName;
+    // kysely types the error as unknown, and a non-Error would stringify to [object Object].
+    const detail =
+      migration.error instanceof Error ? migration.error.message : JSON.stringify(migration.error);
+    throw new Error(`migration failed${failed ? ` at ${failed}` : ""}: ${detail}`);
+  }
+
+  return {
+    pragmas,
+    handle: {
+      db,
+      write: (ctx, work) =>
+        runWrite(ctx, () => db.transaction().execute((trx) => work(trx)), {
+          runInTransaction: <R>(task: () => Promise<R>) => task(),
+          emitTableChange: (table) => changeBus.emit(table, "bulk"),
+        }),
+      close: () => db.destroy(),
+    },
+  };
+}
+
+/** Which candidate the open database is using, for anything that reports or measures. */
+export function activeStorage(): StorageCandidate {
+  if (!chosen) throw new Error("openDatabase() must be awaited before the storage is known");
+  return chosen;
+}
+
+export function activeStorageLabel(): string {
+  return activeStorage().label;
+}
+
+/** The PRAGMAs that actually took, so a measurement can state its own configuration. */
+export function activePragmas(): readonly string[] {
+  return applied;
+}
+
+/** Every step of the walk, including the candidates that were skipped and why. */
+export function storageAttempts(): readonly StorageAttempt[] {
+  return attempts;
+}
+
+// Every step is recorded, because a silent fallback to a slower engine gets discovered weeks later
+// by someone wondering why the app is slow.
+const FORCE_KEY = "app.storage.force";
+
+/**
+ * Pins the chain to one candidate for benchmarking: the *only* one tried, not merely promoted, since
+ * a benchmark that fell through to another engine would report the wrong engine's numbers.
+ */
+function forcedChain(): StorageCandidate[] {
+  let forced: string | null = null;
+  try {
+    forced = localStorage.getItem(FORCE_KEY);
+  } catch {
+    // Storage disabled; the full chain is the right answer anyway.
+  }
+  if (!forced || !isStorageId(forced)) return storageChain;
+
+  const pinned = storageChain.find((candidate) => candidate.id === forced);
+  return pinned ? [pinned] : storageChain;
+}
+
+/**
+ * Memoised on the promise, not the result. Two callers in the same tick both passed a `if (database)`
+ * guard and both walked the chain - and since the pool VFSes hold their OPFS directory exclusively,
+ * the second collided with the first and fell through to a slower engine the app then reported as
+ * its choice.
+ */
+export function openDatabase(): Promise<MobileDatabase<Database>> {
+  if (database) return Promise.resolve(database);
+  opening ??= walkStorageChain();
+  return opening;
+}
+
+async function walkStorageChain(): Promise<MobileDatabase<Database>> {
+  try {
+    return await tryEveryCandidate();
+  } finally {
+    opening = null;
+  }
+}
+
+async function tryEveryCandidate(): Promise<MobileDatabase<Database>> {
+  if (!storageChain.length) throw new Error("storageChain is empty: nothing can open the database");
+
+  attempts = [];
+
+  const chain = forcedChain();
+
+  for (const candidate of chain) {
+    const probe = candidate.probe();
+    if (!probe.supported) {
+      attempts.push({ id: candidate.id, outcome: "unsupported", detail: probe.reason });
+      continue;
+    }
+
+    try {
+      const opened = await openCandidate(candidate);
+      database = opened.handle;
+      applied = opened.pragmas;
+      chosen = candidate;
+      attempts.push({ id: candidate.id, outcome: "opened" });
+      // Every launch names its engine. A preference that never arrived - a `.env` the build could
+      // not parse, a typo - otherwise looks exactly like one that was applied, and the app reports
+      // an engine nobody chose.
+      console.info(
+        `[storage] opened on ${candidate.id}` +
+          (preferredEngine ? ` (VITE_STORAGE_ENGINE=${preferredEngine})` : " (no preference set)"),
+        attempts,
+      );
+      return database;
+    } catch (error) {
+      attempts.push({ id: candidate.id, outcome: "failed", detail: describeOpenFailure(error) });
+    }
+  }
+
+  // Every candidate's reason, because "the database would not open" on its own helps nobody.
+  const summary = attempts
+    .map(
+      (attempt) =>
+        `${attempt.id}: ${attempt.outcome}${attempt.detail ? ` - ${attempt.detail}` : ""}`,
+    )
+    .join("; ");
+  throw new Error(`No storage engine could open the database. ${summary}`);
+}
+
+/**
+ * One retry, because the usual reason a pool VFS's directory lock is held is a process on its way out
+ * - its handles are released when that process dies, so the same open succeeds a moment later. Past
+ * one, the chain moving on is the better answer.
+ */
+async function openCandidate(candidate: StorageCandidate): Promise<OpenedDatabase> {
+  try {
+    return await fromDialect(candidate, await candidate.createDialect());
+  } catch (first) {
+    await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+    try {
+      return await fromDialect(candidate, await candidate.createDialect());
+    } catch {
+      // The first error is the honest one; the retry's is a duplicate of it.
+      throw first;
+    }
+  }
+}
+
+export function getDatabase(): MobileDatabase<Database> {
+  if (!database) throw new Error("openDatabase() must be awaited before the database is used");
+  return database;
+}
+
+/** Writes go through this so every mutation announces its tables without the caller remembering. */
+export const rdb = createReactiveDb<Database>({
+  getDb: () => getDatabase().db,
+  emitChange: changeBus.emit,
+});
+
+export async function closeDatabase(): Promise<void> {
+  await database?.close();
+  database = null;
+  opening = null;
+  chosen = null;
+  attempts = [];
+  applied = [];
+}

package/templates/m3e-app/src/shared/database/index.ts

@@ -0,0 +1,3 @@
+export * from "./database";
+export * from "./queries";
+export type { Database } from "./schema";

package/templates/m3e-app/src/shared/database/migrations.ts

@@ -0,0 +1,223 @@
+import { createTableWithDefaults, type MigrationSet } from "@cavulsqa/mobile-db";
+import { sql } from "kysely";
+
+/**
+ * Keys are ordered lexically and recorded once applied, so they are numbered and never renamed:
+ * renaming one makes it run again on a database that already has it.
+ *
+ * Foreign keys are declared for the shape, and indexed on the columns the screens actually filter
+ * and join by - without them every dashboard aggregate is a full scan.
+ */
+export const migrations: MigrationSet = {
+  "001_sales": {
+    up: async (db) => {
+      await createTableWithDefaults(db, "customer")
+        .addColumn("name", "text", (col) => col.notNull())
+        .addColumn("city", "text", (col) => col.notNull().defaultTo(""))
+        .execute();
+
+      await createTableWithDefaults(db, "product")
+        .addColumn("name", "text", (col) => col.notNull())
+        .addColumn("price_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .execute();
+
+      await createTableWithDefaults(db, "sales_order")
+        .addColumn("customer_id", "integer", (col) =>
+          col.notNull().references("customer.id").onDelete("cascade"),
+        )
+        .addColumn("reference", "text", (col) => col.notNull())
+        .addColumn("status", "text", (col) => col.notNull().defaultTo("draft"))
+        .execute();
+
+      await db.schema
+        .createTable("order_line")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("order_id", "integer", (col) =>
+          col.notNull().references("sales_order.id").onDelete("cascade"),
+        )
+        .addColumn("product_id", "integer", (col) => col.notNull().references("product.id"))
+        .addColumn("quantity", "integer", (col) => col.notNull().defaultTo(1))
+        .addColumn("unit_price_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .execute();
+
+      await db.schema
+        .createTable("tag")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("label", "text", (col) => col.notNull().unique())
+        .execute();
+
+      await db.schema
+        .createTable("customer_tag")
+        .addColumn("customer_id", "integer", (col) =>
+          col.notNull().references("customer.id").onDelete("cascade"),
+        )
+        .addColumn("tag_id", "integer", (col) =>
+          col.notNull().references("tag.id").onDelete("cascade"),
+        )
+        .addPrimaryKeyConstraint("customer_tag_pk", ["customer_id", "tag_id"])
+        .execute();
+
+      await db.schema
+        .createIndex("idx_sales_order_customer")
+        .on("sales_order")
+        .column("customer_id")
+        .execute();
+      await db.schema
+        .createIndex("idx_order_line_order")
+        .on("order_line")
+        .column("order_id")
+        .execute();
+      await db.schema
+        .createIndex("idx_order_line_product")
+        .on("order_line")
+        .column("product_id")
+        .execute();
+      await db.schema.createIndex("idx_customer_city").on("customer").column("city").execute();
+
+      // SQLite ignores foreign keys unless asked, and the plugin opens with them off.
+      await sql`PRAGMA foreign_keys = ON`.execute(db);
+    },
+  },
+
+  /**
+   * A tombstone, and it has to stay.
+   *
+   * This migration created the two-table benchmark that 003 replaced. Deleting the entry rather than
+   * emptying it is what broke the app: kysely records applied migrations by key, finds one recorded
+   * that the provider no longer offers, calls the history corrupted and applies *nothing* - so 003
+   * never ran and the first query failed with "no such table: bench_order_line".
+   *
+   * An applied migration is a fact about databases in the world. It can stop doing anything; it
+   * cannot stop existing.
+   */
+  "002_benchmark": {
+    up: async () => {
+      // Its tables are created and dropped by 003; there is nothing left for this to do.
+    },
+  },
+
+  /**
+   * The benchmark's tables, replacing the two-table version outright - this is R&D and nothing
+   * depends on the old shape.
+   *
+   * Indexed where a screen would index: foreign keys, the columns joins and filters use, and one
+   * composite for the stock lookup. `bench_customer.notes` is deliberately left unindexed so the
+   * LIKE case measures a genuine scan, and `bench_order.total_cents` too, so one case has to sort
+   * without help.
+   */
+  "003_benchmark_scale": {
+    up: async (db) => {
+      await db.schema.dropTable("bench_child").ifExists().execute();
+      await db.schema.dropTable("bench_parent").ifExists().execute();
+
+      await db.schema
+        .createTable("bench_region")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("name", "text", (col) => col.notNull())
+        .execute();
+
+      await db.schema
+        .createTable("bench_city")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("region_id", "integer", (col) => col.notNull().references("bench_region.id"))
+        .addColumn("name", "text", (col) => col.notNull())
+        .execute();
+
+      await db.schema
+        .createTable("bench_customer")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("city_id", "integer", (col) => col.notNull().references("bench_city.id"))
+        .addColumn("code", "text", (col) => col.notNull().unique())
+        .addColumn("name", "text", (col) => col.notNull())
+        .addColumn("notes", "text", (col) => col.notNull().defaultTo(""))
+        .addColumn("credit_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .addColumn("created_at", "text", (col) => col.notNull())
+        .execute();
+
+      await db.schema
+        .createTable("bench_category")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("name", "text", (col) => col.notNull())
+        .execute();
+
+      await db.schema
+        .createTable("bench_product")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("category_id", "integer", (col) => col.notNull().references("bench_category.id"))
+        .addColumn("sku", "text", (col) => col.notNull().unique())
+        .addColumn("name", "text", (col) => col.notNull())
+        .addColumn("price_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .execute();
+
+      await db.schema
+        .createTable("bench_warehouse")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("name", "text", (col) => col.notNull())
+        .execute();
+
+      await db.schema
+        .createTable("bench_stock")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("warehouse_id", "integer", (col) =>
+          col.notNull().references("bench_warehouse.id"),
+        )
+        .addColumn("product_id", "integer", (col) => col.notNull().references("bench_product.id"))
+        .addColumn("quantity", "integer", (col) => col.notNull().defaultTo(0))
+        .execute();
+
+      await db.schema
+        .createTable("bench_order")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("customer_id", "integer", (col) =>
+          col.notNull().references("bench_customer.id").onDelete("cascade"),
+        )
+        .addColumn("reference", "text", (col) => col.notNull())
+        .addColumn("status", "text", (col) => col.notNull().defaultTo("draft"))
+        .addColumn("created_at", "text", (col) => col.notNull())
+        .addColumn("total_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .execute();
+
+      await db.schema
+        .createTable("bench_order_line")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("order_id", "integer", (col) =>
+          col.notNull().references("bench_order.id").onDelete("cascade"),
+        )
+        .addColumn("product_id", "integer", (col) => col.notNull().references("bench_product.id"))
+        .addColumn("quantity", "integer", (col) => col.notNull().defaultTo(1))
+        .addColumn("unit_price_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .execute();
+
+      await db.schema
+        .createTable("bench_payment")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("order_id", "integer", (col) =>
+          col.notNull().references("bench_order.id").onDelete("cascade"),
+        )
+        .addColumn("amount_cents", "integer", (col) => col.notNull().defaultTo(0))
+        .addColumn("method", "text", (col) => col.notNull())
+        .addColumn("created_at", "text", (col) => col.notNull())
+        .execute();
+
+      for (const [name, table, column] of [
+        ["idx_bench_city_region", "bench_city", "region_id"],
+        ["idx_bench_customer_city", "bench_customer", "city_id"],
+        ["idx_bench_product_category", "bench_product", "category_id"],
+        ["idx_bench_order_customer", "bench_order", "customer_id"],
+        ["idx_bench_order_status", "bench_order", "status"],
+        ["idx_bench_line_order", "bench_order_line", "order_id"],
+        ["idx_bench_line_product", "bench_order_line", "product_id"],
+        ["idx_bench_payment_order", "bench_payment", "order_id"],
+      ] as const) {
+        await db.schema.createIndex(name).on(table).column(column).execute();
+      }
+
+      // Composite, because a stock lookup filters on both and neither alone is selective enough.
+      await db.schema
+        .createIndex("idx_bench_stock_warehouse_product")
+        .on("bench_stock")
+        .columns(["warehouse_id", "product_id"])
+        .execute();
+    },
+  },
+};

package/templates/m3e-app/src/shared/database/opfs.worker.ts

@@ -0,0 +1,5 @@
+import { runOpfsWorker } from "@cavulsqa/mobile-db/opfs";
+
+// The whole worker. It lives in the app rather than the package because only the app's bundler can
+// emit a worker and the sqlite3.wasm it loads; the logic is all in @cavulsqa/mobile-db.
+runOpfsWorker();

package/templates/m3e-app/src/shared/database/queries.ts

@@ -0,0 +1,26 @@
+import { createReactiveQuery, createVueQueryMetrics } from "@cavulsqa/reactive-vue";
+import { usePageVisibility } from "@cavulsqa/reactive-vue/framework7";
+import { changeBus } from "./database";
+import type { Database } from "./schema";
+
+const metrics = createVueQueryMetrics({
+  exposeOnWindowAs: import.meta.env.DEV ? "__appMetrics" : undefined,
+});
+
+/**
+ * The composables every screen uses. They are built once, here, because the change bus and the
+ * metrics recorder are app-wide singletons - a query created with a different bus would never hear
+ * about a write.
+ *
+ * Typed on `Database`, so every `tables` entry is checked against the schema. A misspelt table name
+ * is otherwise invisible: the query subscribes to a table nobody writes to and never refetches.
+ */
+export const { useReactiveQuery, useStructuralQuery, useStaticQuery } =
+  createReactiveQuery<Database>({
+    onTableChange: changeBus.on,
+    metrics: metrics.recorder,
+    // Without this a tab the user cannot see keeps refetching in the background.
+    useVisibility: usePageVisibility,
+  });
+
+export const { useQueryMetrics } = metrics;