@cavulsqa/create 2.5.0 → 2.7.0

package/lib/catalog.mjs

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * The workspace catalog, as a flat map of `name` to range.
+ *
+ * A deliberately small reader: the catalog is a block of `name: range` and nothing else.
+ */
+export function catalog(repoRoot) {
+  const entries = new Map();
+  let inside = false;
+  for (const line of readFileSync(join(repoRoot, "pnpm-workspace.yaml"), "utf8").split(/\r?\n/)) {
+    if (/^catalog:\s*$/.test(line)) {
+      inside = true;
+      continue;
+    }
+    if (inside && /^\S/.test(line)) break;
+    if (!inside) continue;
+    const match = /^\s+"?([^":]+)"?:\s*(.+?)\s*$/.exec(line);
+    if (match) entries.set(match[1], match[2].replace(/^["']|["']$/g, ""));
+  }
+  return entries;
+}

package/lib/pruneEngines.mjs

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Removes every storage engine the generated app did not ask for.
+ *
+ * Without this the choice is cosmetic: one template means one `package.json`, so picking OPFS still
+ * installed `@capacitor-community/sqlite` and put the native plugin in the APK for code that never
+ * runs - which is the whole reason the engine sits behind its own entry point in `mobile-db`.
+ *
+ * The template describes its own engines in `cavulsqa.engineModules`, so nothing here has a list of
+ * engine names in it. Each module is one candidate file, and every place that references it does so
+ * on a line of its own - a `STORAGE_IDS` entry, an `export` in the candidates barrel, an import
+ * specifier and an entry in `DEFAULT_ORDER`. Dropping whole lines is why this stays a few rules
+ * rather than a parser.
+ */
+export function pruneEngines(out, manifest, engine) {
+  const modules = manifest?.cavulsqa?.engineModules;
+  if (!modules || !engine) return { kept: null, dropped: [] };
+
+  const kept = Object.entries(modules).find(([, module]) => module.engines.includes(engine));
+  if (!kept) return { kept: null, dropped: [] };
+
+  const dropped = Object.entries(modules).filter(([name]) => name !== kept[0]);
+  if (dropped.length === 0) return { kept: kept[0], dropped: [] };
+
+  // A dependency two engines share is not removable, and neither is an engine id that survives.
+  const keptDeps = new Set(kept[1].dependencies ?? []);
+  const deadDeps = new Set();
+  const deadEngines = new Set();
+  const deadExports = new Set();
+  for (const [, module] of dropped) {
+    for (const dep of module.dependencies ?? []) if (!keptDeps.has(dep)) deadDeps.add(dep);
+    for (const id of module.engines) deadEngines.add(id);
+    for (const symbol of module.exports ?? []) deadExports.add(symbol);
+    const file = join(out, module.file);
+    if (existsSync(file)) rmSync(file);
+  }
+
+  dropLines(join(out, "src/shared/database/candidates/types.ts"), (line) =>
+    [...deadEngines].some((id) => line.trim() === `"${id}",`),
+  );
+  dropLines(join(out, "src/shared/database/candidates/index.ts"), (line) =>
+    dropped.some(([, module]) => line.includes(`"./${basenameOf(module.file)}"`)),
+  );
+  dropLines(join(out, "src/app/storage.config.ts"), (line) =>
+    [...deadExports].some((symbol) => line.trim() === `${symbol},`),
+  );
+
+  // `.env.example` documents every engine, one line each. An app that keeps the line for an engine
+  // it no longer has is documentation that lies, and `VITE_STORAGE_ENGINE` would name a candidate
+  // the chain cannot offer.
+  dropLines(join(out, ".env.example"), (line) =>
+    [...deadEngines].some((id) => line.startsWith(`#   ${id} `)),
+  );
+  rewriteLine(join(out, ".env.example"), /^VITE_STORAGE_ENGINE=/, `VITE_STORAGE_ENGINE=${engine}`);
+
+  pruneDependencies(join(out, "package.json"), deadDeps);
+  return { kept: kept[0], dropped: dropped.map(([name]) => name) };
+}
+
+function basenameOf(file) {
+  return file.split("/").pop().replace(/\.ts$/, "");
+}
+
+function dropLines(path, matches) {
+  if (!existsSync(path)) return;
+  const kept = readFileSync(path, "utf8")
+    .split("\n")
+    .filter((line) => !matches(line));
+  writeFileSync(path, kept.join("\n"));
+}
+
+function rewriteLine(path, matches, replacement) {
+  if (!existsSync(path)) return;
+  const lines = readFileSync(path, "utf8")
+    .split("\n")
+    .map((line) => (matches.test(line) ? replacement : line));
+  writeFileSync(path, lines.join("\n"));
+}
+
+function pruneDependencies(path, dead) {
+  if (!existsSync(path) || dead.size === 0) return;
+  const pkg = JSON.parse(readFileSync(path, "utf8"));
+  for (const group of ["dependencies", "devDependencies"]) {
+    if (!pkg[group]) continue;
+    for (const dep of dead) delete pkg[group][dep];
+  }
+  writeFileSync(path, `${JSON.stringify(pkg, null, 2)}\n`);
+}

package/lib/scaffold.mjs

@@ -1,3 +1,4 @@
+import { pruneEngines } from "./pruneEngines.mjs";
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 
@@ -90,6 +91,13 @@ export function scaffold({ templateDir, out, name, appId, appName, engine, pragm
    * and change, while the choice of engine for one deployment is configuration. `.env.example` is
    * copied in by the template and documents every value.
    */
+  // Before the .env: picking an engine also removes the ones you did not pick, so the app installs
+  // only the plugin or wasm it actually reaches.
+  if (engine) {
+    const templateManifest = JSON.parse(readFileSync(join(templateDir, "package.json"), "utf8"));
+    pruneEngines(out, templateManifest, engine);
+  }
+
   if (engine || pragmas) {
     const lines = ["# Written by @cavulsqa/create. See .env.example for what these mean.", ""];
     if (engine) lines.push(`VITE_STORAGE_ENGINE=${engine}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavulsqa/create",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Create a Vue + Framework7 + Capacitor + SQLite app from the cavulsqa templates.",
   "keywords": [
     "capacitor",
@@ -52,7 +52,7 @@
       }
     ]
   },
-  "templatesFingerprint": "sha256-cV0g/O7hz2eNNshfgmpNGWq7pcYKH/DRDVaeqkqVgjg=",
+  "templatesFingerprint": "sha256-FbgQOdRBk/8d4JoHOGyxK9/r8aLGGRY9ipzvKvfADNk=",
   "scripts": {
     "build": "node scripts/bundleTemplates.mjs",
     "check": "vp check",

package/templates/f7-app/.env.example

@@ -6,15 +6,11 @@
 # The engine tried first. The rest of the chain in src/app/storage.config.ts still follows it as
 # fallback, so this reorders rather than restricts.
 #
-#   sqlite-wasm-opfs-sahpool     official @sqlite.org/sqlite-wasm, OPFS pool. Faster at writes and
-#                                transactions, seeds ~1.8x quicker, and it is the SQLite team's own
-#                                build. The default for those reasons.
-#   wa-sqlite-access-handle-pool wa-sqlite, OPFS pool. Faster at joins and scans on measured
-#                                hardware; a single-maintainer project.
+#   sqlite-wasm-opfs-sahpool     official @sqlite.org/sqlite-wasm on an OPFS pool. Fastest measured, the SQLite team's own build, and the default.
+#   wa-sqlite-access-handle-pool wa-sqlite on an OPFS pool. Faster at joins and scans on measured hardware; a single-maintainer project.
 #   wa-sqlite-opfs-async         wa-sqlite over OPFS without the pool, on the Asyncify build.
-#   wa-sqlite-idb-batch-atomic   SQLite pages in IndexedDB. The slowest, and the only one that works
-#                                without synchronous access handles - the option for a WebView
-#                                between Chromium 86 and 108.
+#   wa-sqlite-idb-batch-atomic   SQLite pages in IndexedDB. The slowest, and the only durable route on a WebView below Chromium 109.
+#   capacitor-sqlite             the native plugin. Slower on every measured axis and it ships in the APK, but a read is not blocked by an in-flight write.
 VITE_STORAGE_ENGINE=sqlite-wasm-opfs-sahpool
 
 # PRAGMA profile. `safe` keeps SQLite's durability guarantee; `fast` trades it for speed by handing

package/templates/f7-app/package.json

@@ -12,6 +12,7 @@
     "check": "vp check"
   },
   "dependencies": {
+    "@capacitor-community/sqlite": "^8.1.1",
     "@capacitor/android": "^8.5.0",
     "@capacitor/app": "^8.0.0",
     "@capacitor/core": "^8.0.0",
@@ -19,9 +20,9 @@
     "@capacitor/preferences": "^8.0.0",
     "@capacitor/splash-screen": "^8.0.0",
     "@capacitor/status-bar": "^8.0.0",
-    "@cavulsqa/mobile-db": "^1.0.0",
-    "@cavulsqa/reactive-db": "^1.0.0",
-    "@cavulsqa/reactive-vue": "^1.0.0",
+    "@cavulsqa/mobile-db": "^1.1.0",
+    "@cavulsqa/reactive-db": "^1.1.0",
+    "@cavulsqa/reactive-vue": "^1.1.0",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@tailwindcss/vite": "^4.3.3",
     "@vueuse/core": "^14.4.0",
@@ -53,7 +54,50 @@
       "sqlite-wasm-opfs-sahpool",
       "wa-sqlite-access-handle-pool",
       "wa-sqlite-opfs-async",
-      "wa-sqlite-idb-batch-atomic"
-    ]
+      "wa-sqlite-idb-batch-atomic",
+      "capacitor-sqlite"
+    ],
+    "engineModules": {
+      "opfsSahPool": {
+        "file": "src/shared/database/candidates/opfsSahPool.ts",
+        "engines": [
+          "sqlite-wasm-opfs-sahpool"
+        ],
+        "exports": [
+          "opfsSahPool"
+        ],
+        "dependencies": [
+          "@sqlite.org/sqlite-wasm"
+        ]
+      },
+      "waSqlite": {
+        "file": "src/shared/database/candidates/waSqlite.ts",
+        "engines": [
+          "wa-sqlite-access-handle-pool",
+          "wa-sqlite-opfs-async",
+          "wa-sqlite-idb-batch-atomic"
+        ],
+        "exports": [
+          "waAccessHandlePool",
+          "waOriginPrivateFileSystem",
+          "waIdbBatchAtomic"
+        ],
+        "dependencies": [
+          "wa-sqlite"
+        ]
+      },
+      "capacitorSqlite": {
+        "file": "src/shared/database/candidates/capacitorSqlite.ts",
+        "engines": [
+          "capacitor-sqlite"
+        ],
+        "exports": [
+          "capacitorSqlite"
+        ],
+        "dependencies": [
+          "@capacitor-community/sqlite"
+        ]
+      }
+    }
   }
 }

package/templates/f7-app/src/app/storage.config.ts

@@ -1,4 +1,5 @@
 import {
+  capacitorSqlite,
   isStorageId,
   opfsSahPool,
   waAccessHandlePool,
@@ -10,11 +11,12 @@ import {
 
 /**
  * The knob. Walked in order, first candidate that opens wins, and the rest are never imported - so a
- * chain that stops at the first entry never downloads wa-sqlite's wasm.
+ * chain that stops at the first entry never downloads the others' wasm.
  *
- * Reorder freely to trade speed for reach: `waIdbBatchAtomic` first is the compatibility choice,
- * since IndexedDB is the only durable route on a WebView between Chromium 86 and 108. Only
- * `sqlite-wasm-opfs-sahpool` has been measured on a phone; the rest carry `evidence: "expected"`.
+ * Reorder freely to trade speed for reach: the entries lower down reach older WebViews, and each
+ * one states its own `tradeoff` and whether its `evidence` came from a device or a vendor's README.
+ * Read the list rather than this comment - `@cavulsqa/create` removes the engines an app did not
+ * ask for, so what is below is what this app actually has.
  *
  * No in-memory entry on purpose: a chain that ends somewhere data is not kept is worse than one that
  * fails and names every attempt.
@@ -24,6 +26,7 @@ export const DEFAULT_ORDER: StorageCandidate[] = [
   waAccessHandlePool,
   waOriginPrivateFileSystem,
   waIdbBatchAtomic,
+  capacitorSqlite,
 ];
 
 /**

package/templates/f7-app/src/shared/database/candidates/capacitorSqlite.ts

@@ -0,0 +1,47 @@
+import { Capacitor } from "@capacitor/core";
+import type { StorageCandidate, StorageProbe } from "./types";
+
+/**
+ * `@capacitor-community/sqlite`: a real file behind a native bridge.
+ *
+ * Slower than the OPFS engine on every axis measured on a device - batched writes about 2.4x, the
+ * app's own screen queries about 1.3x - and it needs the plugin in the APK. It is here for the one
+ * thing the worker cannot do: the worker is serial, so a read waits behind an in-flight write,
+ * where this dialect keeps reads outside the write lock. Choose it for an app that writes
+ * continuously while the UI reads, or that needs SQLCipher or native access to the file.
+ */
+function probeNativePlatform(): StorageProbe {
+  if (!Capacitor.isNativePlatform()) {
+    return {
+      supported: false,
+      reason: "the SQLite plugin is native-only; on web it needs jeep-sqlite and a separate store",
+    };
+  }
+  return { supported: true };
+}
+
+export const capacitorSqlite: StorageCandidate = {
+  id: "capacitor-sqlite",
+  label: "Capacitor SQLite · native plugin",
+  tradeoff:
+    "Needs the native plugin in the APK, and every statement crosses the bridge. Slower than the " +
+    "worker engines, but reads are not blocked by an in-flight write.",
+  durable: true,
+  evidence: "measured",
+  probe: probeNativePlatform,
+  createDialect: async () => {
+    const [{ CapacitorSQLite, SQLiteConnection }, { SharedConnectionSQLiteDialect }] =
+      await Promise.all([
+        import("@capacitor-community/sqlite"),
+        import("@cavulsqa/mobile-db/capacitor"),
+      ]);
+
+    const sqlite = new SQLiteConnection(CapacitorSQLite);
+    const name = "app.sqlite3";
+    await sqlite.createConnection(name, false, "no-encryption", 1, false);
+    const database = await sqlite.retrieveConnection(name, false);
+    await database.open();
+
+    return new SharedConnectionSQLiteDialect({ database, sqlite, name, serializeAccess: true });
+  },
+};

package/templates/f7-app/src/shared/database/candidates/index.ts

@@ -1,3 +1,4 @@
 export * from "./types";
 export { opfsSahPool } from "./opfsSahPool";
 export { waAccessHandlePool, waIdbBatchAtomic, waOriginPrivateFileSystem } from "./waSqlite";
+export { capacitorSqlite } from "./capacitorSqlite";

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

@@ -12,6 +12,7 @@ export const STORAGE_IDS = [
   "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];