@cavulsqa/create 0.1.2 → 2.2.0

package/README.md

@@ -23,18 +23,20 @@ nothing, pnpm never sees a package name, and you get a 404 for something like `c
 There is no unscoped `create-cavulsqa`, so `pnpm create cavulsqa` is a 404 as well.
 
 ```bash
-pnpm create @cavulsqa --name caputa --app-id com.sig.caputa --yes
+pnpm create @cavulsqa --name caputa --app-id com.example.caputa --yes
 ```
 
-| flag         | default          |                                                        |
-| ------------ | ---------------- | ------------------------------------------------------ |
-| `--name`     | asked            | package and directory name                             |
-| `--template` | the only one     | which bundled template                                 |
-| `--dir`      | `./<name>`       | where to write it                                      |
-| `--app-name` | `Name`           | launcher name, window title, Settings screen           |
-| `--app-id`   | `com.ayb.<name>` | Android application id                                 |
-| `--from`     | —                | a template directory on disk, instead of a bundled one |
-| `--yes`      | —                | take the defaults, ask nothing                         |
+| flag         | default          |                                                         |
+| ------------ | ---------------- | ------------------------------------------------------- |
+| `--name`     | asked            | package and directory name                              |
+| `--template` | the only one     | which bundled template                                  |
+| `--dir`      | `./<name>`       | where to write it                                       |
+| `--app-name` | `Name`           | launcher name, window title, Settings screen            |
+| `--app-id`   | `com.ayb.<name>` | Android application id                                  |
+| `--engine`   | asked            | which storage engine the app prefers, written to `.env` |
+| `--pragmas`  | `safe`           | `safe` keeps durability, `fast` trades it for speed     |
+| `--from`     | —                | a template directory on disk, instead of a bundled one  |
+| `--yes`      | —                | take the defaults, ask nothing                          |
 
 ## What you get
 
@@ -51,6 +53,22 @@ nothing in a screen asks for a refresh.
 repository knows the architecture, the conventions, and the traps that have already cost someone a
 day.
 
+## Choosing an engine
+
+`--engine` writes a `.env`, it does not edit the config. The chain in `src/app/storage.config.ts`
+stays intact and the chosen engine is simply promoted to the front, so a device that cannot open it
+still falls back rather than failing.
+
+| id                             | when                                                                                          |
+| ------------------------------ | --------------------------------------------------------------------------------------------- |
+| `sqlite-wasm-opfs-sahpool`     | the default. The SQLite team's own build; faster at writes, transactions and seeding          |
+| `wa-sqlite-access-handle-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. Slowest, and the only one that needs no synchronous access handles |
+
+The ids come from the template itself, so a template that offers a different set is asked about
+correctly rather than validated against a list kept here.
+
 ## Versions
 
 The template's dependencies are resolved and pinned when this package is published, so a given

package/bin/create.mjs

@@ -42,6 +42,8 @@ Options:
   --dir PATH           where to write it (default: ./<name>)
   --app-name NAME      launcher name and window title (default: Name)
   --app-id ID          android application id (default: com.ayb.<name>)
+  --engine ID          which storage engine the app prefers, written to .env
+  --pragmas PROFILE    safe (default) or fast
   --from PATH          use a template directory on disk instead of the bundled ones
   --yes                take the defaults, ask nothing
   --help               this
@@ -65,6 +67,25 @@ function listTemplates() {
   }));
 }
 
+/**
+ * The engine ids a template actually offers, read out of its own candidate list rather than kept in
+ * a second list here - a generator that knows more engines than the template does is a generator
+ * that writes a `.env` the app ignores.
+ */
+function listEngines(templateDir) {
+  try {
+    const source = readFileSync(
+      join(templateDir, "src/shared/database/candidates/types.ts"),
+      "utf8",
+    );
+    const union = /export type StorageId =([\s\S]*?);/.exec(source)?.[1] ?? "";
+    return [...union.matchAll(/"([a-z0-9-]+)"/g)].map((match) => match[1]);
+  } catch {
+    // A template without the candidate module simply has no engine choice to offer.
+    return [];
+  }
+}
+
 /** npm package names: lowercase, no spaces, no leading dot or underscore. */
 function validName(value) {
   return /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(value);
@@ -112,6 +133,20 @@ async function main() {
     const appId =
       flags.get("app-id") ?? (await ask("Android application id", `com.ayb.${bareName}`));
 
+    const engines = listEngines(join(BUNDLED, template));
+    let engine = flags.get("engine");
+    if (typeof engine !== "string" && engines.length > 1) {
+      engine = await ask(`Storage engine [${engines.join(", ")}]`, engines[0]);
+    }
+    if (typeof engine === "string" && engines.length && !engines.includes(engine)) {
+      throw new Error(`unknown engine "${engine}"; this template offers: ${engines.join(", ")}`);
+    }
+
+    const pragmas = flags.get("pragmas");
+    if (typeof pragmas === "string" && pragmas !== "safe" && pragmas !== "fast") {
+      throw new Error(`--pragmas must be "safe" or "fast", not "${pragmas}"`);
+    }
+
     const dir = flags.get("dir") ?? (await ask("Directory", `./${name}`));
     const out = isAbsolute(dir) ? dir : resolve(process.cwd(), dir);
 
@@ -119,7 +154,15 @@ async function main() {
     const templateDir =
       typeof from === "string" ? resolve(process.cwd(), from) : join(BUNDLED, template);
 
-    scaffold({ templateDir, out, name, appId, appName: String(appName) });
+    scaffold({
+      templateDir,
+      out,
+      name,
+      appId,
+      appName: String(appName),
+      engine: typeof engine === "string" ? engine : undefined,
+      pragmas: typeof pragmas === "string" ? pragmas : undefined,
+    });
 
     console.log(`
 ${appName} created in ${out}

package/lib/scaffold.mjs

@@ -58,7 +58,7 @@ function copyTree(from, to, transform) {
  * The template's dependencies are already concrete - `bundleTemplates.mjs` resolved them when the
  * creator was packed - so nothing here has to know about workspaces or catalogs.
  */
-export function scaffold({ templateDir, out, name, appId, appName }) {
+export function scaffold({ templateDir, out, name, appId, appName, engine, pragmas }) {
   if (!existsSync(templateDir)) throw new Error(`no template at ${templateDir}`);
   if (existsSync(out)) throw new Error(`${out} already exists`);
 
@@ -73,6 +73,20 @@ export function scaffold({ templateDir, out, name, appId, appName }) {
     return personalise(entry, text, { name: identity, appName });
   });
 
+  /**
+   * A real `.env` when the generator was told which engine to prefer.
+   *
+   * Written rather than editing `storage.config.ts`, because the config is code someone will read
+   * and change, while the choice of engine for one deployment is configuration. `.env.example` is
+   * copied in by the template and documents every value.
+   */
+  if (engine || pragmas) {
+    const lines = ["# Written by @cavulsqa/create. See .env.example for what these mean.", ""];
+    if (engine) lines.push(`VITE_STORAGE_ENGINE=${engine}`);
+    if (pragmas) lines.push(`VITE_PRAGMA_PROFILE=${pragmas}`);
+    writeFileSync(join(out, ".env"), `${lines.join("\n")}\n`);
+  }
+
   // pnpm will not finish an install while a dependency's build script is neither allowed nor
   // denied, and vite-plus pulls esbuild in. Without this every generated app fails its first
   // `pnpm install` with ERR_PNPM_IGNORED_BUILDS.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavulsqa/create",
-  "version": "0.1.2",
+  "version": "2.2.0",
   "description": "Create a Vue + Framework7 + Capacitor + SQLite app from the cavulsqa templates.",
   "keywords": [
     "capacitor",
@@ -52,7 +52,7 @@
       }
     ]
   },
-  "templatesFingerprint": "sha256-7SiAd2fNFtbBqL3RPdjFpJEM9CeKmmPWj/oet2rfeGk=",
+  "templatesFingerprint": "sha256-dj3zUrK7OwVRIwWJcrX/7pxRo/LsGJDBMolhJNIihUs=",
   "scripts": {
     "build": "node scripts/bundleTemplates.mjs",
     "check": "vp check",

package/templates/f7-app/.claude/rules/database.md

@@ -63,3 +63,42 @@ A schema change needs a test in `tests/` that runs the migration and the affecte
 sql.js. `tests/sales.repository.test.ts` is the pattern: build a Kysely on `createSqlJsDialect()`,
 migrate, then assert on real rows — including the arithmetic. A total that type-checks can still be
 computed wrong.
+
+## Writing a lot of rows
+
+Measured on a phone, at 100k rows, per row written:
+
+| how                                              | per row        |
+| ------------------------------------------------ | -------------- |
+| one insert per statement, each its own commit    | 8-13 ms        |
+| one insert per statement, inside one transaction | ~0.45 ms       |
+| multi-row insert, ~150 rows per statement        | 0.066-0.115 ms |
+
+Roughly a hundredfold between the worst and best way to write the same row. SQLite caps parameters
+per statement, so 150 rows of five columns is about the practical ceiling for one insert - chunk by
+parameter budget, not by a round number.
+
+## Why a big write freezes the screen, and what to do
+
+The database runs in one worker, and that worker is serial. A read cannot overtake a write already
+in flight; it waits for everything queued ahead of it. So the cost to the UI is not how fast the
+write is, it is **how much work the write committed to before the read arrived**.
+
+Time a screen's read waits when it lands during a 1000-row write:
+
+| write strategy                                 | read waits    |
+| ---------------------------------------------- | ------------- |
+| 1000 single inserts in one transaction         | ~350-690 ms   |
+| 150 rows per statement, one transaction        | ~36-53 ms     |
+| ten transactions of 100, awaited one at a time | **~21-32 ms** |
+
+A naive loop stalls the screen for most of a second. Chunked transactions bring it under the
+threshold anyone notices, and the reason is mechanical: awaiting each chunk means only one chunk is
+ever queued, so an arriving read waits for 100 rows instead of 1000.
+
+**So: write in chunks of about a hundred rows, use multi-row inserts inside each chunk, and await
+each chunk before starting the next.** Do not wrap a thousand rows in one transaction to be fast -
+it is faster in total and far worse for anyone looking at the screen while it runs.
+
+The Diagnostics benchmark measures all three strategies, so this is checkable on any device rather
+than taken on faith.

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

@@ -0,0 +1,23 @@
+# Which SQLite engine the app opens, and what it falls back to.
+#
+# Copy this file to `.env` and edit. Everything here is baked in at build time - Vite substitutes
+# `import.meta.env` when it bundles - so changing it means rebuilding, not restarting.
+
+# 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.
+#   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.
+VITE_STORAGE_ENGINE=sqlite-wasm-opfs-sahpool
+
+# PRAGMA profile. `safe` keeps SQLite's durability guarantee; `fast` trades it for speed by handing
+# the flush decision to the OS, which is right for a benchmark and wrong for data a person would
+# miss. Batched writes cost almost the same either way.
+VITE_PRAGMA_PROFILE=safe

package/templates/f7-app/CLAUDE.md

@@ -83,9 +83,14 @@ vp test           # the repository and icon tests
 pnpm type-check   # vue-tsc, the gate for anything touching .vue
 ```
 
-`vue-tsc` and `vp check` disagree by design: `vp check` compiles `vite.config.ts` under a separate
-tsconfig because vite-plus bundles its own Vite while the unplugins take it as a peer. Both must
-pass.
+`vp check` is the type gate for `vite.config.ts`; `vue-tsc` covers `src`. Both must pass.
+
+There is deliberately no `tsconfig.node.json`. A `tsc` project over `vite.config.ts` cannot be
+clean either way: with `skipLibCheck` on, Vite's deeply recursive `PluginOption` union blows the
+comparison depth limit on the plugin array; with it off, vite-plus-core's own declarations fail on
+optional peers it does not ship. Nothing in this repository runs `tsc`, and an editor with no
+project reports the file clean - so the config only ever added a red squiggle and a wrong
+explanation. `vp check` resolves it correctly and is the authority.
 
 **Type-checking is not verification for UI.** A screen that compiles can still render an empty
 box — that is how seven invisible icons and a blank-page bootstrap both shipped. If you changed

package/templates/f7-app/auto-imports.d.ts

@@ -103,6 +103,7 @@ declare global {
   const refManualReset: typeof import('@vueuse/core').refManualReset
   const refThrottled: typeof import('@vueuse/core').refThrottled
   const refWithControl: typeof import('@vueuse/core').refWithControl
+  const renderBootstrapError: typeof import('./src/plugins/bootstrapError').renderBootstrapError
   const request: typeof import('framework7/lite').request
   const resolveComponent: typeof import('vue').resolveComponent
   const seedPlugin: typeof import('./src/plugins/seed.plugin').seedPlugin
@@ -152,6 +153,7 @@ declare global {
   const useAttrs: typeof import('vue').useAttrs
   const useBase64: typeof import('@vueuse/core').useBase64
   const useBattery: typeof import('@vueuse/core').useBattery
+  const useBenchmark: typeof import('./src/modules/demo/composables/useBenchmark').useBenchmark
   const useBluetooth: typeof import('@vueuse/core').useBluetooth
   const useBreakpoints: typeof import('@vueuse/core').useBreakpoints
   const useBroadcastChannel: typeof import('@vueuse/core').useBroadcastChannel
@@ -336,6 +338,9 @@ declare global {
   export type { TabbarVisibility } from './src/shared/composables/useTabbarVisibility'
   import('./src/shared/composables/useTabbarVisibility')
   // @ts-ignore
+  export type { CaseComparison } from './src/modules/demo/composables/useBenchmark'
+  import('./src/modules/demo/composables/useBenchmark')
+  // @ts-ignore
   export type { BusEntry, PipelineResult } from './src/modules/demo/composables/useReactiveDemo'
   import('./src/modules/demo/composables/useReactiveDemo')
   // @ts-ignore
@@ -443,6 +448,7 @@ declare module 'vue' {
     readonly refManualReset: UnwrapRef<typeof import('@vueuse/core')['refManualReset']>
     readonly refThrottled: UnwrapRef<typeof import('@vueuse/core')['refThrottled']>
     readonly refWithControl: UnwrapRef<typeof import('@vueuse/core')['refWithControl']>
+    readonly renderBootstrapError: UnwrapRef<typeof import('./src/plugins/bootstrapError')['renderBootstrapError']>
     readonly request: UnwrapRef<typeof import('framework7/lite')['request']>
     readonly resolveComponent: UnwrapRef<typeof import('vue')['resolveComponent']>
     readonly seedPlugin: UnwrapRef<typeof import('./src/plugins/seed.plugin')['seedPlugin']>
@@ -492,6 +498,7 @@ declare module 'vue' {
     readonly useAttrs: UnwrapRef<typeof import('vue')['useAttrs']>
     readonly useBase64: UnwrapRef<typeof import('@vueuse/core')['useBase64']>
     readonly useBattery: UnwrapRef<typeof import('@vueuse/core')['useBattery']>
+    readonly useBenchmark: UnwrapRef<typeof import('./src/modules/demo/composables/useBenchmark')['useBenchmark']>
     readonly useBluetooth: UnwrapRef<typeof import('@vueuse/core')['useBluetooth']>
     readonly useBreakpoints: UnwrapRef<typeof import('@vueuse/core')['useBreakpoints']>
     readonly useBroadcastChannel: UnwrapRef<typeof import('@vueuse/core')['useBroadcastChannel']>

package/templates/f7-app/components.d.ts

@@ -12,6 +12,7 @@ export {}
 declare module 'vue' {
   export interface GlobalComponents {
     404: typeof import('./src/shared/components/error/404.vue')['default']
+    DemoBenchmark: typeof import('./src/modules/demo/components/DemoBenchmark.vue')['default']
     DemoBusLog: typeof import('./src/modules/demo/components/DemoBusLog.vue')['default']
     DemoCreateOrderSheet: typeof import('./src/modules/demo/components/DemoCreateOrderSheet.vue')['default']
     DemoOrderList: typeof import('./src/modules/demo/components/DemoOrderList.vue')['default']
@@ -47,6 +48,7 @@ declare module 'vue' {
     F7Tabs: typeof import('framework7-vue')['f7Tabs']
     F7Toggle: typeof import('framework7-vue')['f7Toggle']
     F7Toolbar: typeof import('framework7-vue')['f7Toolbar']
+    F7ToolbarPane: typeof import('framework7-vue')['f7ToolbarPane']
     F7View: typeof import('framework7-vue')['f7View']
     F7Views: typeof import('framework7-vue')['f7Views']
     FeatureDetailView: typeof import('./src/modules/home/views/FeatureDetailView.vue')['default']

package/templates/f7-app/package.json

@@ -12,7 +12,6 @@
     "check": "vp check"
   },
   "dependencies": {
-    "@capacitor-community/sqlite": "^7.0.2",
     "@capacitor/android": "^8.5.0",
     "@capacitor/app": "^8.0.0",
     "@capacitor/core": "^8.0.0",
@@ -20,24 +19,25 @@
     "@capacitor/preferences": "^8.0.0",
     "@capacitor/splash-screen": "^8.0.0",
     "@capacitor/status-bar": "^8.0.0",
-    "@cavulsqa/mobile-db": "^0.3.0",
+    "@cavulsqa/mobile-db": "^0.5.0",
     "@cavulsqa/reactive-db": "^0.2.0",
     "@cavulsqa/reactive-vue": "^0.2.0",
+    "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@tailwindcss/vite": "^4.3.3",
     "@vueuse/core": "^14.4.0",
     "framework7": "^9.0.2",
     "framework7-icons": "^5.0.5",
-    "framework7-vue": "^8.3.4",
+    "framework7-vue": "^9.1.2",
     "kysely": "^0.29.5",
-    "sql.js": "1.13.0",
     "tailwindcss": "^4.3.3",
     "vue": "^3.5.0",
-    "vue-i18n": "^11.2.2"
+    "vue-i18n": "^11.2.2",
+    "wa-sqlite": "^1.0.0"
   },
   "devDependencies": {
     "@capacitor/cli": "^8.0.0",
     "@intlify/unplugin-vue-i18n": "^11.2.5",
-    "@types/node": "^24",
+    "@types/node": "^24.12.2",
     "@vitejs/plugin-vue": "^6.0.3",
     "sql.js": "1.13.0",
     "typescript": "^5.9.3",

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

@@ -0,0 +1,51 @@
+/**
+ * PRAGMAs applied to every engine, identically, right after it opens.
+ *
+ * They live here rather than inside a candidate for one reason: SQLite's defaults are per-build, and
+ * two engines left on their own defaults are not comparable. Measuring them without pinning this
+ * produced a 1.47x "ranking" that may have been nothing but a difference in `synchronous`.
+ *
+ * `fast` is what a benchmark should use - both engines pushed as hard as they go, so the comparison
+ * is between engines rather than between journal settings. It is not a safe default for an app that
+ * holds a day's orders: `synchronous = OFF` means the OS, not SQLite, decides when bytes reach
+ * storage, so a crash or a battery pull can leave the database corrupt rather than merely stale.
+ *
+ * `safe` keeps SQLite's durability guarantee and pays for it on single writes, which the benchmark
+ * measures at 19-57 ms depending on engine. Both settings batch equally well - inside one
+ * transaction the cost per row falls under 3 ms either way - so an app that batches its writes gives
+ * up very little by staying safe.
+ */
+export type PragmaProfile = "fast" | "safe";
+
+const PROFILES: Record<PragmaProfile, readonly string[]> = {
+  fast: [
+    // No journal file to create, write and delete per transaction.
+    "PRAGMA journal_mode = MEMORY",
+    // The big one for single writes, and the one that trades away crash durability.
+    "PRAGMA synchronous = OFF",
+    "PRAGMA temp_store = MEMORY",
+    // Negative means KiB rather than pages: 16 MB of page cache.
+    "PRAGMA cache_size = -16000",
+  ],
+  safe: [
+    "PRAGMA journal_mode = TRUNCATE",
+    "PRAGMA synchronous = FULL",
+    "PRAGMA temp_store = MEMORY",
+    "PRAGMA cache_size = -16000",
+  ],
+};
+
+/**
+ * From `VITE_PRAGMA_PROFILE`, defaulting to `safe`.
+ *
+ * Safe by default because the cost is small once writes are batched - inside one transaction the
+ * per-row difference is under a millisecond - and the failure it prevents is a corrupt database
+ * rather than a slow one. Set `fast` when measuring, where the point is to compare engines rather
+ * than journal settings.
+ */
+export const pragmaProfile: PragmaProfile =
+  import.meta.env.VITE_PRAGMA_PROFILE === "fast" ? "fast" : "safe";
+
+export function pragmasFor(profile: PragmaProfile): readonly string[] {
+  return PROFILES[profile];
+}

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

@@ -0,0 +1,55 @@
+import {
+  opfsSahPool,
+  waAccessHandlePool,
+  waIdbBatchAtomic,
+  waOriginPrivateFileSystem,
+  type StorageCandidate,
+} from "@/shared/database/candidates";
+
+/**
+ * Which SQLite implementation this app uses, and what it falls back to.
+ *
+ * This is the knob. The list is walked in order: each candidate is asked whether the device supports
+ * it, then asked to open; the first that succeeds wins, and the rest are never imported - so a chain
+ * that stops at the first entry never downloads wa-sqlite's wasm at all.
+ *
+ * Ordered fastest-first, and that ordering is a claim worth being precise about. Only
+ * `sqlite-wasm-opfs-sahpool` has been measured on a phone; the three below it are placed on the
+ * vendor's own description of them and each says so through `evidence`. The Diagnostics benchmark
+ * exists to replace that guess with numbers.
+ *
+ * Reorder freely - this is the supported way to trade speed for reach:
+ *
+ * - Compatibility first: put `waIdbBatchAtomic` at the top. IndexedDB is the only durable route on a
+ *   WebView between Chromium 86 and 108, which runs this bundle but has no synchronous access
+ *   handles. Slowest, works almost everywhere.
+ * - One vendor only: drop `opfsSahPool` and keep the wa-sqlite three, or the reverse. Both engines
+ *   implement the same dialect contract, so nothing above this file changes either way.
+ *
+ * There is deliberately no in-memory entry. A chain that silently ends somewhere data is not kept is
+ * worse than one that fails and says why, and the error screen names every attempt.
+ */
+const DEFAULT_ORDER: StorageCandidate[] = [
+  opfsSahPool,
+  waAccessHandlePool,
+  waOriginPrivateFileSystem,
+  waIdbBatchAtomic,
+];
+
+/**
+ * `VITE_STORAGE_ENGINE` promotes one candidate to the front and leaves the rest as fallback, so the
+ * env var reorders the chain rather than replacing it - a device that cannot open the preferred
+ * engine still gets a working app.
+ *
+ * An unknown id is ignored rather than fatal: a typo in a `.env` should not brick the build's
+ * output, and the app reports which candidate actually opened in Settings.
+ */
+function preferredFirst(candidates: StorageCandidate[]): StorageCandidate[] {
+  const preferred = import.meta.env.VITE_STORAGE_ENGINE;
+  if (!preferred) return candidates;
+
+  const match = candidates.find((candidate) => candidate.id === preferred);
+  return match ? [match, ...candidates.filter((candidate) => candidate !== match)] : candidates;
+}
+
+export const storageChain: StorageCandidate[] = preferredFirst(DEFAULT_ORDER);