@bakery-framework/core 2.0.0-alpha.9 → 2.0.0-rc.1

package/README.md

@@ -10,7 +10,7 @@ runtime depends on Bun APIs throughout. It will not run on Node.
 bun add @bakery-framework/core @bakery-framework/cli
 ```
 
-`@bakery-framework/cli` owns the `bakery` binary that actually starts a server — core on
+`@bakery-framework/cli` owns the `bakery` binary that actually starts a server: core on
 its own is the library it starts.
 
 ## Usage
@@ -55,7 +55,7 @@ Pages are rendered server-side through Bakery's own `createElement`, so an app's
 
 `extends` alone is not enough. Bun's runtime does not follow `extends` into a
 package specifier, so without the three options repeated here every `.tsx` route
-fails with `Cannot find module 'react/jsx-dev-runtime'` — while `tsc` stays
+fails with `Cannot find module 'react/jsx-dev-runtime'`, while `tsc` stays
 perfectly happy, because it *does* follow the extends.
 
 The fastest way to get a correct setup is to let the scaffolder write one:
@@ -71,19 +71,19 @@ bun create bakery my-app
   10 req/s). The startup banner says so; `rateLimit: false` turns it off.
 - The export map is curated: only the subpaths it names can be imported, and
   everything else is private. If you need something that is not exposed, open an
-  issue rather than reaching for a deep path — it will not resolve.
+  issue rather than reaching for a deep path: it will not resolve.
 
 Full documentation lives in the
 [repository](https://github.com/obillekyle/bakery).
 
 ## License
 
-MIT with the Commons Clause v1.0 — see [LICENSE](./LICENSE). In short: use,
+MIT with the Commons Clause v1.0. See [LICENSE](./LICENSE). In short: use,
 
-**Not an OSI-approved licence.** The Commons Clause removes the right to *sell*
-the software — meaning to charge for a product or service whose value derives
+**Not an OSI-approved license.** The Commons Clause removes the right to *sell*
+the software: meaning to charge for a product or service whose value derives
 substantially from it, hosting and support included. Everything else the MIT
-licence grants is unchanged: use it, modify it, ship it inside your own product.
-If your organisation only permits OSI-approved dependencies, this will not pass
+license grants is unchanged: use it, modify it, ship it inside your own product.
+If your organization only permits OSI-approved dependencies, this will not pass
 that check.
 modify and distribute freely; selling the software itself is not granted.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/core",
-  "version": "2.0.0-alpha.9",
+  "version": "2.0.0-rc.1",
   "description": "Bakery framework core: handlers, router, config, session, caches, logger, compiler.",
   "keywords": [
     "bakery",
@@ -30,19 +30,16 @@
   "exports": {
     ".": "./src/core/index.ts",
     "./compiler": "./src/compiler/index.ts",
-    "./core": "./src/core/index.ts",
     "./handlers": "./src/handlers/index.ts",
     "./logger": "./src/logger/index.ts",
     "./utils": "./src/utils/index.ts",
     "./utils/common": "./src/utils/common/index.ts",
     "./utils/http": "./src/utils/http/index.ts",
-    "./utils/isomorphic": "./src/utils/isomorphic/index.ts",
     "./types": "./src/types.d.ts",
     "./package.json": "./package.json",
     "./startup": "./src/startup.ts",
     "./tsconfig.app.json": "./tsconfig.app.json",
     "./session": "./src/session.ts",
-    "./jsx": "./src/core/jsx.ts",
     "./plugins": "./src/plugins/index.ts",
     "./cache/lru": "./src/cache/lru.ts",
     "./cache/shared-db": "./src/cache/shared-db.ts",
@@ -68,6 +65,6 @@
     "!src/tests"
   ],
   "engines": {
-    "bun": ">=1.3.14"
+    "bun": ">=1.4.0"
   }
 }

package/src/cache/lru.ts

@@ -1,7 +1,7 @@
 export class LRUCache<K, V> extends Map<K, V> {
   /**
    * Called with the entry dropped to make room. Needed when values own a
-   * resource that must be released — an evicted prepared statement, for
+   * resource that must be released: an evicted prepared statement, for
    * instance, otherwise leaks until the process exits.
    */
   private readonly onEvict?: (key: K, value: V) => void
@@ -17,7 +17,7 @@ export class LRUCache<K, V> extends Map<K, V> {
 
   get(key: K): V | undefined {
     const val = super.get(key)
-    // `has` only to disambiguate a stored `undefined` from a miss — on the
+    // `has` only to disambiguate a stored `undefined` from a miss: on the
     // common hit this is two map operations instead of four.
     if (val === undefined && !super.has(key)) return undefined
     super.delete(key)

package/src/cache/shared-db.ts

@@ -2,14 +2,16 @@ import { Database } from 'bun:sqlite'
 import { dirname } from 'node:path'
 import { Bakery } from '../core/bakery'
 import { checkCacheVersion } from '../core/cache-version'
+import { serveLog } from '../logger/serve-log'
 import { fs } from '../utils'
+import { Try } from '../utils/common/try'
 
 /**
- * The tiered cache's spill-to-disk store — sessions and LRU overflow.
+ * The tiered cache's spill-to-disk store: sessions and LRU overflow.
  *
- * Under `Bakery.dataDir`, beside `server.db`. Rows here are *rebuildable* — a
+ * Under `Bakery.dataDir`, beside `server.db`. Rows here are *rebuildable*: a
  * session is a cookie plus whatever the app hung off it, and the LRU tier
- * refills from source on the next miss — but rebuildable is not the same as
+ * refills from source on the next miss, but rebuildable is not the same as
  * disposable-on-a-schedule, which is what living in `cacheDir` amounted to.
  * See the reversal below.
  *
@@ -17,7 +19,7 @@ import { fs } from '../utils'
  * this paragraph is the reversal.**
  *
  * The file lived under `Bakery.cacheDir`, so `checkCacheVersion` deleted it on
- * every version bump and every dev<->prod switch — logging every user out. The
+ * every version bump and every dev<->prod switch: logging every user out. The
  * argument for that was sound: a cache format written by an older framework
  * must never be read by a newer one, and the version wipe is what guarantees
  * it.
@@ -26,7 +28,7 @@ import { fs } from '../utils'
  * releases were cut by hand and rare; releases are now computed from commit
  * messages and published automatically, so a patch ships whenever a `fix:`
  * lands. Logging out every user of every app on every patch is a far worse
- * trade than it was, and it was never the *goal* — only the consequence of
+ * trade than it was, and it was never the *goal*: only the consequence of
  * keying durability on a version number that had nothing to do with the stored
  * format.
  *
@@ -35,7 +37,7 @@ import { fs } from '../utils'
  * a schema mismatch drops the tables, a framework bump does not.
  *
  * Two consequences worth knowing. An app with no ORM now creates a `bakery/`
- * directory where it previously created none — it is storing durable data, so
+ * directory where it previously created none: it is storing durable data, so
  * that is honest, but it means "no `bakery/` directory" is no longer evidence
  * that `initDB` never ran. And the LRU spill tier shares this file, so overflow
  * entries also survive; they are still rebuildable, just no longer discarded on
@@ -43,7 +45,7 @@ import { fs } from '../utils'
  *
  * **The `await` below is what makes that true, and it must stay here.** This
  * module opens the database at *import* time, so running the check anywhere
- * else — it used to run from `initConfig()` — leaves the process holding a
+ * else (it used to run from `initConfig()`) leaves the process holding a
  * handle inside the directory the wipe is about to delete. On Windows that
  * delete fails with `EBUSY`, node's recursive walk stops at the locked entry,
  * and whatever it had not reached yet survives. Awaiting here orders the two by
@@ -68,8 +70,8 @@ export const cacheDb = new Database(dbFilePath, { create: true })
 /**
  * Drop everything if the stored schema version is not this one.
  *
- * The safety property the cache wipe provided — a newer framework never reads
- * an older format — is preserved exactly, just keyed on the thing that actually
+ * The safety property the cache wipe provided (a newer framework never reads
+ * an older format) is preserved exactly, just keyed on the thing that actually
  * governs compatibility. A mismatch logs users out, which is the same outcome
  * as before; the difference is that it now happens when the format changes
  * rather than when any version number does.
@@ -90,8 +92,76 @@ if (!stored) {
   for (const { name } of tables) cacheDb.run(`DROP TABLE IF EXISTS "${name}"`)
   cacheDb.run('UPDATE __schema SET version = ?', [SCHEMA_VERSION])
 }
-const journalMode = process.platform === 'win32' ? 'DELETE' : 'WAL'
-cacheDb.run(`PRAGMA journal_mode = ${journalMode};`)
+/**
+ * **WAL first, DELETE only where WAL is actually refused.**
+ *
+ * This was `process.platform === 'win32' ? 'DELETE' : 'WAL'`, a rule whose
+ * reason was never written down. The standing hypothesis was that a Windows
+ * network path cannot host WAL, and that much is true: WAL needs a shared
+ * `-shm` mapping, which SMB and WebDAV do not provide. The rule was wrong in
+ * its scope rather than its premise. It applied to every Windows install,
+ * including the ordinary case of a local disk where WAL works perfectly.
+ *
+ * The cost of being wrong was paid on the request path, because sessions
+ * write there. Measured on this machine, four interleaved rounds with a
+ * CPU-bound control that stayed flat at 29-34 ms:
+ *
+ *     single autocommit write    DELETE 3629 us    WAL 36 us      100x
+ *     100-row transaction        DELETE 3.91 ms    WAL 0.13 ms     29x
+ *
+ * So the rule is replaced by an attempt and a check, which is what makes it
+ * safe to change without knowing why it was there. SQLite refuses WAL in
+ * exactly two observable ways, and both are handled here:
+ *
+ *   - it **returns the unchanged mode** in the pragma's own result row, which
+ *     is what an in-memory or anonymous-temp database does (`memory`); and
+ *   - it **throws**, which is what a read-only database does.
+ *
+ * Measured, not assumed: both shapes were reproduced before this was written.
+ * A pragma that silently did nothing would make the fallback unsafe, and it
+ * does not - the returned row is the authority, so a filesystem that cannot
+ * host WAL lands on DELETE and says so once instead of being guessed at in
+ * advance.
+ *
+ * Returning the effective mode rather than the requested one matters for the
+ * same reason: the log line has to name what the database is actually doing.
+ *
+ * Exported as a test seam rather than driven through the module's own
+ * import-time call: this file opens the real cache database when it loads, so
+ * the only way to assert on a *refusal* is to hand the function a database
+ * that produces one. `:memory:` is such a case and is what the test uses.
+ */
+export function applyJournalMode(db: Database, file: string): string {
+  const asked = Try.return(
+    () =>
+      db
+        .query<{ journal_mode: string }, []>('PRAGMA journal_mode = WAL;')
+        .get()?.journal_mode ?? '',
+    (error: Error) => `threw: ${error.message}`,
+  )
+  if (asked.toLowerCase() === 'wal') return 'wal'
+
+  // Wrapped as well. A database that refuses WAL by throwing will refuse the
+  // fallback the same way when the mode it is already in is not DELETE, and
+  // an unopenable cache is a far worse outcome than an untuned one.
+  const fell = Try.return(
+    () =>
+      db
+        .query<{ journal_mode: string }, []>('PRAGMA journal_mode = DELETE;')
+        .get()?.journal_mode ?? 'unknown',
+    () =>
+      db.query<{ journal_mode: string }, []>('PRAGMA journal_mode;').get()
+        ?.journal_mode ?? 'unknown',
+  )
+  serveLog.JOURNAL_WAL_REFUSED({
+    file,
+    answer: asked || '(no row)',
+    mode: fell,
+  })
+  return fell
+}
+
+applyJournalMode(cacheDb, dbFilePath)
 cacheDb.run('PRAGMA synchronous = NORMAL;')
 cacheDb.run('PRAGMA temp_store = memory;')
 // `core/init.ts` installs THREAD_WORKER as an accessor holding a **boolean**,

package/src/cache/string.ts

@@ -41,6 +41,10 @@ class StringCache {
 
     if (flushIntervalMs !== undefined) {
       this.flushTimer = setInterval(() => this.flushToDisk(), flushIntervalMs)
+      // Unref'd for the reason `tiered.ts` gives: `Strings` is constructed at
+      // module scope, so importing `compiler/compiler.ts` pinned the event
+      // loop open for the life of the process.
+      this.flushTimer.unref?.()
     }
 
     registerCache(this)

package/src/cache/tiered.ts

@@ -35,7 +35,7 @@ export function registerCache(cache: Flushable): void {
 }
 
 /**
- * Test seam — see `__setTestDb` / `__setTestConfig` for the pattern.
+ * Test seam. See `__setTestDb` / `__setTestConfig` for the pattern.
  *
  * Detaches the live registry so a test can drive `flushAllCaches()` against its
  * own caches without flushing and closing the process's real ones (`Strings`,
@@ -133,6 +133,12 @@ export class TieredCache<K extends string | number, V> {
         () => this.flushToDisk(),
         this.opts.flushInterval,
       )
+      // A flush timer must not be the reason a process cannot exit. Every
+      // cache here is module-level, so importing `session.ts` (or anything
+      // reaching it) left an interval holding the loop open forever: a script
+      // or a test that imported core printed its answer and then hung. The CLI
+      // never noticed because it calls `process.exit` on every path.
+      this.flushTimer.unref?.()
     }
 
     registerCache(this)
@@ -310,7 +316,7 @@ export class TieredCache<K extends string | number, V> {
     totalPages: number
   } {
     // Paging happens in SQL, so the dirty memory tier has to reach disk first.
-    // That was a third, hand-written copy of `flushToDisk` — same shape, but
+    // That was a third, hand-written copy of `flushToDisk`: same shape, but
     // looping over `stmt.insert` instead of `commitKey`, which is exactly the
     // bypass `flushAllToDisk` documents below having already been fixed once.
     // There is nothing search needs that the predicate would deny it: an entry
@@ -390,7 +396,7 @@ export class TieredCache<K extends string | number, V> {
     if (this.memoryStore.size === 0) return
     db.transaction(() => {
       // Through `commitKey`, not a raw insert. This is the shutdown flush, and
-      // it used to ignore `shouldPersist` — so the interval flush and eviction
+      // it used to ignore `shouldPersist`, so the interval flush and eviction
       // dropped a non-persisting entry while a clean stop wrote it. For the
       // session tier that predicate is "has persisted keys or has data", so
       // every shutdown wrote up to a thousand empty sessions, which then
@@ -417,7 +423,7 @@ export class TieredCache<K extends string | number, V> {
     const entry = this.memoryStore.get(key)
     if (!entry) return
     // `shouldPersist?.(v)` is `undefined` when the option is absent, and
-    // `!undefined` is `true` — so a cache configured without a predicate took
+    // `!undefined` is `true`, so a cache configured without a predicate took
     // the delete branch for every key. Since `enforceMemoryLimit` commits as
     // it evicts, that made eviction destroy the value rather than demote it
     // to disk. Absence of the option means "persist everything".
@@ -465,7 +471,7 @@ const logger = new Logger('tiered-cache')
  * database: this hook is registered at module-evaluation time and therefore
  * sits at index 0, while a plugin's shutdown hook is registered later during
  * plugin setup. Closing the handle here invalidated it for every plugin that
- * writes on the way out — the analytics flush bound the same `cacheDb`, so
+ * writes on the way out: the analytics flush bound the same `cacheDb`, so
  * every statement threw into an outer catch and up to a minute of page hits
  * plus the whole history delta was discarded on every clean stop, silently.
  *

package/src/client/globals.d.ts

@@ -7,19 +7,19 @@
  *
  * - `Try.throw` was declared with a synchronous overload it never had
  *   (`tryThrow` is `Promise.try(...).catch(...)`, so it always returns a
- *   Promise) — browser code writing `const n: number = Try.throw(() => 1)`
+ *   Promise): browser code writing `const n: number = Try.throw(() => 1)`
  *   typechecked and silently received a Promise.
  * - `Case` lost its callable form: the implementation is
  *   `Object.assign(function Case(type, str) {…}, {…})`, so `Case('kebab', s)`
  *   is real but was untypeable.
  * - `request` was `(url, method?, body?)` against an implementation of
- *   `(url, init: RequestJson | string = {}, bodyData?)` — the object-init form
+ *   `(url, init: RequestJson | string = {}, bodyData?)`. The object-init form
  *   was unreachable from the types.
  * - `randomId` was `() => string` against an implementation taking `length = 8`.
  *
  * So the shapes are no longer restated: each global is a `typeof import(...)`
  * of the module that actually provides it, which fixes all four at once and
- * cannot drift again. `typeof import(...)` inside a `.d.ts` is a type query —
+ * cannot drift again. `typeof import(...)` inside a `.d.ts` is a type query:
  * it is erased, and adds no runtime module edge into the browser bundle.
  *
  * Two globals genuinely cannot be derived, and stay hand-written:
@@ -31,7 +31,7 @@
 import type { MapOf } from '../types'
 
 declare global {
-  /** Server-side exports from `<script server>` — available at runtime in `<script setup>` and templates. */
+  /** Server-side exports from `<script server>`: available at runtime in `<script setup>` and templates. */
   const server: { [key: string]: any }
 
   const matchDefault: typeof import('../utils/isomorphic/match').matchDefault
@@ -52,7 +52,7 @@ declare global {
 
   // Not derivable: written inline in client/utils.ts's Object.assign call
   // rather than exported, so there is no module member to take `typeof` of.
-  // Verified against that literal — `version` is the BAKERY_VERSION define,
+  // Verified against that literal: `version` is the BAKERY_VERSION define,
   // `virtual` is `async virtual(path: string)`, `params` is generic.
   var Bakery: {
     version: string
@@ -62,13 +62,13 @@ declare global {
 
   // `ImportMeta.env` is declared once, by global.d.ts's ImportMetaEnv. This
   // file used to redeclare it with an incompatible shape, and to carry
-  // verbatim copies of Wrapped / MapOf / JsonResponse / ISFunction — all four
+  // verbatim copies of Wrapped / MapOf / JsonResponse / ISFunction: all four
   // now live in shared.d.ts, which is where anything the browser and the
   // server both need belongs.
 }
 
 // A `declare module '@client/utils'` block used to sit here re-exporting
-// '../utils'. It never resolved (TS2307 — relative specifiers inside an
+// '../utils'. It never resolved (TS2307: relative specifiers inside an
 // ambient module declaration do not resolve from the containing file), and
 // nothing in the codebase imports '@client/utils' from TypeScript: it is a
 // runtime importMap entry the browser resolves, mapped to /_client/utils.js.

package/src/client/livereload.ts

@@ -26,7 +26,7 @@ function hideOverlay() {
 
 /**
  * Full-viewport dev overlay for server-pushed errors and a dead dev server.
- * Built strictly with createElement/textContent — the title and body arrive
+ * Built strictly with createElement/textContent: the title and body arrive
  * over the wire and may contain markup-shaped text (stack traces quoting
  * generics, user file names); nothing here may pass through innerHTML.
  */
@@ -416,7 +416,7 @@ function connect() {
     // stopped dev server once a second, indefinitely and in lockstep.
     const delay = Math.min(1000 * 2 ** reconnectAttempts, 30_000)
     reconnectAttempts += 1
-    // A dead dev server used to mean silent reconnect attempts — the page just
+    // A dead dev server used to mean silent reconnect attempts: the page just
     // quietly stopped reloading. After a few failures (~7s of downtime with
     // the backoff above) say so; onopen dismisses it and reloads on reconnect.
     if (reconnectAttempts > 3) {

package/src/client/utils.ts

@@ -44,10 +44,10 @@ function processGetBody(
 
 // `randomId` and `request` are exported purely so `client/globals.d.ts` can
 // declare the globals as `typeof import('./utils').randomId` / `.request`
-// instead of restating their signatures — which is how both had drifted from
+// instead of restating their signatures, which is how both had drifted from
 // this file. Nothing imports them; the bundle entry's exports are inert.
 //
-// `randomId` moved to `utils/isomorphic/misc.ts` — it was never
+// `randomId` moved to `utils/isomorphic/misc.ts`: it was never
 // browser-specific, and a server block calling the "browser global" got a
 // ReferenceError. Imported (not re-exported directly) because the globals
 // object below needs the local binding too.
@@ -60,7 +60,7 @@ type RequestJson = RequestInit & { body?: any }
 /**
  * What `request()` throws for a non-2xx envelope.
  *
- * It used to throw a bare `Error` carrying only the envelope's `message` —
+ * It used to throw a bare `Error` carrying only the envelope's `message`,
  * which made every structured failure unusable: a 409 whose `data` lists the
  * conflicting rows, a 400 carrying per-field validation issues. Callers had to
  * drop to raw `fetch` precisely for the requests where the framework's
@@ -144,7 +144,12 @@ export async function request(
   return data
 }
 
-export function formatHTML(html: string, indentWidth: number = 2): string {
+/**
+ * File-local. It was exported and nothing imported it: `client/utils.ts` is
+ * not a published subpath, so the `export` widened nothing a consumer could
+ * reach and only made the name look like part of a surface.
+ */
+function formatHTML(html: string, indentWidth: number = 2): string {
   if (!html) return ''
 
   const cleanHtml = html
@@ -195,7 +200,7 @@ Object.assign(globalThis, {
   Bakery: {
     // **Cast rather than `import.meta.env` directly.** `ImportMeta.env` is
     // declared by `bun-types`, and this file is compiled by the *client*
-    // tsconfig, which deliberately has none — reaching for a Bun-provided type
+    // tsconfig, which deliberately has none: reaching for a Bun-provided type
     // here would undo the split it exists to enforce.
     //
     // Declaring `ImportMeta` in client/globals.d.ts instead would clash with
@@ -326,7 +331,7 @@ if (typeof document !== 'undefined') {
 
     // Prerender the same filtered list as prefetch, not every link on the page.
     // A `source: 'document'` rule with href_matches '/*' and eager eagerness
-    // ignored the exclusions above and fully loaded — and ran the JS of — every
+    // ignored the exclusions above and fully loaded (and ran the JS of) every
     // same-origin link, including things like /logout or a destructive GET.
     const urlList = Array.from(urls)
     specScript.textContent = JSON.stringify({