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

package/src/plugins/types.ts

@@ -6,18 +6,20 @@ export type ValidResponses = Handler.Response
 /**
  * A TypeScript project a plugin contributes to the app.
  *
- * Written to `.cache/tsconfig/<name>.json` on every dev boot and referenced
- * from the app's root `tsconfig.json`, so the editor typechecks each file under
- * the project that owns it. Regenerated rather than committed: it is derived
- * from the plugin list and the app's config, and `.cache/` is the disposable
- * half of the two runtime directories.
+ * Written to `.cache/tsconfig/<name>.json` on every dev boot, as a standalone
+ * project invoked directly (`vue-tsc -p .cache/tsconfig/vue.json`). It is
+ * deliberately *not* referenced from the app's root `tsconfig.json`: a
+ * `references` entry to an unbuilt `noEmit` project makes `tsc -p <app>` fail
+ * (TS6305/6306/6310; see `compiler/tsconfig-sync.ts`). Regenerated rather
+ * than committed: it is derived from the plugin list and the app's config, and
+ * `.cache/` is the disposable half of the two runtime directories.
  */
 export interface PluginTsProject {
   /** File name under `.cache/tsconfig/`, and the project's identity. */
   name: string
   /** Usually one of core's three bases. Written through as-is. */
   extends: string
-  /** Globs, relative to the **app root** — the generator rewrites them. */
+  /** Globs, relative to the **app root**: the generator rewrites them. */
   include?: string[]
   exclude?: string[]
   /**
@@ -34,7 +36,7 @@ export interface PluginTsProject {
    *
    * Off by default, and that default is the correction: the generator used to
    * write those `paths` into *every* project on the reasoning that an alias is
-   * app-wide. It is not. `importMap` is a **browser** import map — the framework
+   * app-wide. It is not. `importMap` is a **browser** import map: the framework
    * serves it as `<script type="importmap">` and the browser is what resolves
    * its specifiers. An alias in the server project therefore typechecks an
    * import that only the browser can satisfy, which is the same class of bug the
@@ -47,13 +49,13 @@ export interface PluginTsProject {
    * Does code in this project run on the server?
    *
    * Declared, not inferred. The first version read `bun-types` out of the base
-   * config and treated that as the marker — true today, and an inference about
+   * config and treated that as the marker: true today, and an inference about
    * intent drawn from a detail that exists for another reason. A plugin saying
    * what its project *is* cannot drift out of step with itself.
    *
    * What it controls: the app's schema registration, so the ORM's tables are the
    * app's own rather than the permissive `any` fallback. Off for browser code on
-   * purpose — `@bakery-framework/orm` is server-only, so a `.ts` bound for the
+   * purpose: `@bakery-framework/orm` is server-only, so a `.ts` bound for the
    * browser importing `DB` should fail to typecheck rather than be helpfully
    * typed, and the package ships TypeScript source calling `Bun.*`, which a
    * client config cannot compile anyway.
@@ -63,7 +65,7 @@ export interface PluginTsProject {
 
 /** What a plugin contributes to the generated tsconfig projects. */
 export interface PluginTsConfig {
-  /** A project this plugin owns outright — Vue SFCs, for instance. */
+  /** A project this plugin owns outright: Vue SFCs, for instance. */
   project?: PluginTsProject
 }
 
@@ -77,7 +79,7 @@ export interface ServerPlugin {
    *
    * A plugin that brings its own file type or its own ambient globals needs a
    * project to typecheck them under. `@bakery-framework/plugin-vue` is the
-   * worked example — it owns `.vue` and declares `req`/`body` for SFC scope,
+   * worked example: it owns `.vue` and declares `req`/`body` for SFC scope,
    * globals core deliberately does not provide.
    */
   tsconfig?: PluginTsConfig

package/src/router.ts

@@ -27,11 +27,11 @@ import { parsedUrl } from './utils/http/url'
  * The origin check lives here rather than in each `canHandle` on purpose:
  * every socket a plugin or an app registers inherits it, instead of every
  * author having to remember. `/_analytics_ws` was the only handler that got it
- * right on its own, and it did so by authenticating — `/_livereload` had
+ * right on its own, and it did so by authenticating: `/_livereload` had
  * nothing, and `WebSocketHandler.canHandle` returns `true` by default, so the
  * base class was handing out sockets to anyone who asked.
  *
- * Returning `false` (rather than a 403) keeps the published signature — the
+ * Returning `false` (rather than a 403) keeps the published signature: the
  * caller below turns a refusal into `400 WebSocket Upgrade Failed`, which is
  * also what an unclaimed path gets. The reason reaches the log; the client is
  * told nothing it did not already know.
@@ -65,10 +65,10 @@ export async function upgradeWebsocket(
  * Whether the deny-list applies to whatever this handler is about to answer
  * with. `Bakery.config.blocked` exists to stop files on disk being served, so
  * handlers that read the request path as a route *name* opt out by declaring
- * `servesFiles = false` — `ApiHandler`, `ProxyHandler`, `MiddlewareHandler`.
+ * `servesFiles = false`: `ApiHandler`, `ProxyHandler`, `MiddlewareHandler`.
  *
  * Deny by default, and the direction matters. Naming only the obvious file
- * servers — Static, Public, NM — would have left `/schema.ts` and
+ * servers (Static, Public, NM) would have left `/schema.ts` and
  * `/server.config.ts` reachable through `TSHandler`, which compiles a source
  * file and serves the result. Anything that does not opt out, including a
  * plugin's handler, keeps the check.
@@ -94,7 +94,7 @@ export async function handleRequest(req: Request) {
   // One read of the config getter, not three: `Bakery.serveRoot` walks
   // `hostStore.getStore()?.config ?? getConfig()` on every access, and the
   // blocked-glob check below used to pay the same walk again. And no
-  // `fs.resolve` around the target — `isForbidden` normalises both arguments
+  // `fs.resolve` around the target: `isForbidden` normalizes both arguments
   // itself, so that was a second full path resolution of the same string on
   // every request.
   const config = Bakery.config
@@ -102,7 +102,7 @@ export async function handleRequest(req: Request) {
   // Before anything else, including the forbidden-path check: a preflight names
   // the route it is asking about in a *header*, not the path, so running it
   // through routing would answer a question nobody asked. The browser sends no
-  // credentials with it either, which is why it cannot be authorised.
+  // credentials with it either, which is why it cannot be authorized.
   //
   // Only when `cors` is configured. Absent, this is not reached at all and the
   // browser's own default applies.
@@ -136,7 +136,7 @@ export async function handleRequest(req: Request) {
   const handler = await Bakery.handlers.fetch.resolve(path, req)
   if (!handler) return new Response('Not Found', { status: 404 })
 
-  // `matchBlockedCached` memoises the verdict on the request store, so the
+  // `matchBlockedCached` memoizes the verdict on the request store, so the
   // re-check `StaticHandler.handle` keeps for its direct callers costs a map
   // hit instead of a second pair of glob matches.
   if (servesFiles(handler) && matchBlockedCached(config.blocked, path)) {
@@ -236,14 +236,14 @@ export const serveWebSocket: Bun.WebSocketHandler<any> = {
  * Make an error page answer with the error's status.
  *
  * The HTML and TSX error handlers end in `injectIfHtml`, which builds its
- * Response without one — so an app with `src/error-404.html` served its 404
+ * Response without one, so an app with `src/error-404.html` served its 404
  * page as `200 OK` and every crawler, cache and monitor believed it. Applied
  * here rather than inside `injectIfHtml` on purpose: the only status signal
  * available down there is `params`, which for a GET is the query string, and
  * `?errorCode=500` is not something a client gets to decide.
  *
  * A `JsonResponseData` (the `/api/` arm) carries its own `.status` that
- * `processResponse` reads, and a BunFile has no status at all — both pass
+ * `processResponse` reads, and a BunFile has no status at all: both pass
  * through untouched.
  */
 function applyErrorStatus(
@@ -277,7 +277,7 @@ export async function handleRequestError(
 
   // Wrapped for the same reason the registry call below it is: this is app
   // code. An `onError` that throws used to escape `Try.return`'s fallback in
-  // the caller — a fallback that itself rejects is not a fallback — so the one
+  // the caller (a fallback that itself rejects is not a fallback), so the one
   // hook whose job is to handle failure took the app's error page down with
   // it and the client got Bun's raw 500 instead.
   const [onErrorFailed, configError] = await Try.catch(() =>
@@ -353,8 +353,8 @@ export async function processResponse(
   // (e.g. an auth cookie from a login route) that must not be overwritten.
   sess && resp.headers.append('Set-Cookie', sess)
 
-  // Every response funnels through here — pages, API JSON, static files, error
-  // pages — so this is the one place that cannot miss one. Applied before ETag
+  // Every response funnels through here (pages, API JSON, static files, error
+  // pages), so this is the one place that cannot miss one. Applied before ETag
   // so the negotiated `Vary` sees the `Origin` entry and merges with it rather
   // than either overwriting the other.
   const cors = Bakery.config.cors

package/src/session.ts

@@ -7,7 +7,7 @@ import { DEFAULT_SESSION_PERSIST, DEFAULT_SESSION_TTL } from './utils/constants'
 /**
  * Keys under this prefix are framework-internal privilege markers. They share
  * the same bag as application data, so anything that writes a caller-supplied
- * key must refuse this prefix — otherwise a preferences endpoint (or the
+ * key must refuse this prefix: otherwise a preferences endpoint (or the
  * dashboard's own session editor) becomes a privilege-escalation primitive.
  */
 export const RESERVED_SESSION_PREFIX = '__bakery.'
@@ -17,7 +17,7 @@ export function isReservedSessionKey(key: string): boolean {
 }
 
 /**
- * Clock seam — the cookie half-life bookkeeping is time-based, and its tests
+ * Clock seam: the cookie half-life bookkeeping is time-based, and its tests
  * inject a clock instead of sleeping (see `__setTestDb` / `__setTestConfig`
  * for the pattern). Only the cookie-reissue math reads this; `createdAt` and
  * TTL expiry keep `Date.now()`.
@@ -47,7 +47,7 @@ export function newSessionId(): string {
  * The cache key for a session id under the current host.
  *
  * There is one `TieredCache('sessions')` for the whole process, and until this
- * existed every id went into it unqualified — so under a multi-tenant `hosts`
+ * existed every id went into it unqualified, so under a multi-tenant `hosts`
  * config one tenant's dashboard listed, read and deleted every other tenant's
  * sessions. `hostKey()` is the guard the five other per-tenant caches already
  * use; sessions were the one that never got it.
@@ -102,6 +102,19 @@ export class Session<
     return Session.cache.count
   }
 
+  /**
+   * Attach the session cookie to a response built outside the pipeline.
+   *
+   * **Takes the `Request`, and that is not incidental.** `getCookie` reads the
+   * session through `hasDeferredValue(req, 'session')`, which looks for a
+   * symbol the router installs, so the value has to come from the real
+   * request. There used to be an instance form, `session.bind(res)`, that
+   * called this with `{ session: this }`: a fake carrying no symbol, so the
+   * check failed, `getCookie` returned an empty string, and the cookie was
+   * never appended. It was a documented method that could not work, and it is
+   * gone rather than repaired: the session alone does not know whether the
+   * request it belongs to issued a cookie this turn.
+   */
   public static bind(req: Request, response?: Response) {
     if (!response) return response
 
@@ -116,7 +129,7 @@ export class Session<
     const session = req.session
 
     // Issue only when the session actually changed, or when the read path
-    // flagged a half-life refresh (see `markAccessed`) — not on every read.
+    // flagged a half-life refresh (see `markAccessed`), not on every read.
     // A per-request Set-Cookie made every session-carrying response unique,
     // defeating If-None-Match, and dirtied merely-read sessions into the
     // flush timer's write batch.
@@ -138,7 +151,7 @@ export class Session<
       ? Math.floor(DEFAULT_SESSION_PERSIST / 1000)
       : Math.floor(DEFAULT_SESSION_TTL / 1000)
 
-    // Only believe x-forwarded-proto behind a trusted proxy — the same rule
+    // Only believe x-forwarded-proto behind a trusted proxy: the same rule
     // getHostname and getClientIp already apply. In production default to
     // Secure, so a terminator that omits the header can't downgrade the cookie.
     const trustProxy = Bakery.config.trustProxy
@@ -178,7 +191,7 @@ export class Session<
     session.rawData = { ...metadata.data }
     session.data = session.initProxy()
     // Rows written before the field existed revive as 0 = "unknown", which
-    // `markAccessed` reads as long past half-life — at worst one extra
+    // `markAccessed` reads as long past half-life, at worst one extra
     // reissue, never a cookie that silently expires under an active user.
     session.cookieIssuedAt = metadata.cookieIssuedAt ?? 0
     return session
@@ -209,7 +222,7 @@ export class Session<
         if (existing.isExpired()) {
           Session.cache.delete(sessionKey(sessionId))
         } else {
-          // Accessed, not modified — see `markAccessed`. `touch()` here made
+          // Accessed, not modified. See `markAccessed`. `touch()` here made
           // every session read count as a write.
           existing.markAccessed()
           return existing
@@ -227,7 +240,7 @@ export class Session<
 
   /**
    * Epoch ms when `getCookie` last emitted `Set-Cookie` for this id; 0 means
-   * never (or unknown — a row written before the field existed). Persisted
+   * never (or unknown: a row written before the field existed). Persisted
    * through `toJSON`, so it only costs a write when a write is already
    * happening; while the instance lives in the memory tier it carries across
    * requests for free.
@@ -236,7 +249,7 @@ export class Session<
 
   /**
    * Set by `markAccessed` when the cookie has crossed half its Max-Age;
-   * cleared when `getCookie` issues. Deliberately not persisted — it is
+   * cleared when `getCookie` issues. Deliberately not persisted: it is
    * per-instance request bookkeeping, and losing it costs nothing (the next
    * read recomputes it from `cookieIssuedAt`).
    */
@@ -277,7 +290,7 @@ export class Session<
    * Force the session to count as modified: stored on the next flush and its
    * cookie re-issued. This is the published "force a cookie refresh" surface
    * (docs/guides/sessions.md) and keeps its dirty semantics. It is *not* the
-   * read path — `Session.from` uses `markAccessed`, which slides expiry
+   * read path: `Session.from` uses `markAccessed`, which slides expiry
    * without paying write costs.
    */
   public touch(): this {
@@ -286,18 +299,18 @@ export class Session<
   }
 
   /**
-   * The read-path bump — what `Session.from` does instead of `touch()`.
+   * The read-path bump, what `Session.from` does instead of `touch()`.
    * Reading a session must not dirty it: that made every read-only request
    * pay a JSON.stringify + synchronous SQLite write on the next flush and
    * re-issue Set-Cookie, which defeated If-None-Match caching.
    *
    * Liveness needs no work here: the `Session.cache.get` in `from` has
    * already re-stamped the memory tier's accessedAt. What this method owns is
-   * sliding cookie expiration — once more than half the cookie's Max-Age has
+   * sliding cookie expiration: once more than half the cookie's Max-Age has
    * elapsed since it was last issued, flag a reissue. `getCookie` then emits
    * the cookie *and* re-persists the session, which renews the DB row's
    * accessedAt at a cadence of at most maxAge/2 against the pruner's cutoff
-   * of maxAge — so active sessions never age out server-side either.
+   * of maxAge, so active sessions never age out server-side either.
    */
   private markAccessed(): void {
     const maxAgeMs = this.hasPersistedKeys()
@@ -350,10 +363,10 @@ export class Session<
    *
    * This is the missing anti-fixation primitive. `reset()` clears data but
    * keeps the id, so an app that does `req.session.set('userId', …)` on login
-   * finishes authentication on the *same* id the visitor arrived with —
+   * finishes authentication on the *same* id the visitor arrived with,
    * including one an attacker planted. Call it at the privilege boundary:
    *
-   * ```ts no-check — illustrative call site, not a compiled example
+   * ```ts no-check: illustrative call site, not a compiled example
    * req.session.regenerate().set('userId', user.id, true)
    * ```
    *
@@ -362,7 +375,7 @@ export class Session<
    * the same object `req.session` already holds, so the rest of the request
    * sees the new id.
    *
-   * `createdAt` is deliberately preserved — the session continues, only its
+   * `createdAt` is deliberately preserved: the session continues, only its
    * bearer token is replaced.
    */
   public regenerate(): this {
@@ -423,10 +436,6 @@ export class Session<
     return this
   }
 
-  public bind(response?: Response) {
-    return Session.bind({ session: this } as any, response)
-  }
-
   public destroy(): void {
     Session.delete(this.id)
   }
@@ -454,7 +463,7 @@ export class Session<
 
   /**
    * Every enumeration below filters to the current host and yields the bare
-   * session id, not the cache key — so `Session.keys()` still returns ids the
+   * session id, not the cache key, so `Session.keys()` still returns ids the
    * dashboard can hand back to `Session.get` / `Session.delete`.
    */
   static *entries(): IterableIterator<[string, Session<any>]> {
@@ -487,7 +496,7 @@ export class Session<
     // The check is on `hosts` and not on the scope, deliberately: `hostKey`
     // collapses to '' in the unconfigured case too, so the scope alone cannot
     // tell the two situations apart. This method used to compute one anyway and
-    // never read it — scoping lives in `Session.entries()`, which the slow path
+    // never read it: scoping lives in `Session.entries()`, which the slow path
     // below goes through.
     const hosts = Bakery.config.hosts
     if (!hosts || Object.keys(hosts).length === 0) {
@@ -495,7 +504,7 @@ export class Session<
     }
 
     // Scoped path: `TieredCache.search` pages in SQL across the whole table,
-    // which is every tenant's sessions, and it has no key-prefix predicate — so
+    // which is every tenant's sessions, and it has no key-prefix predicate, so
     // the filter has to happen before paging, in JS. Bounded by the session
     // table, which the pruner holds down to live sessions.
     const needle = options.search?.trim().toLowerCase() || ''
@@ -548,6 +557,15 @@ const sessionPruneTimer = setInterval(
   1000 * 60 * 15, // prune every 15 minutes
 )
 
+// Unref'd, like the two flush timers in `cache/`. A 15-minute prune is not a
+// reason a process cannot exit, and this one is module-level: importing
+// `session.ts` (which `core/index` does) held the event loop open for the
+// life of any process that touched core. The CLI never saw it because every
+// one of its paths ends in `process.exit`; a script, an embedder or a bare
+// `bun -e` that imported the barrel printed its answer and then hung.
+// `onShutdown` still clears it, which is what matters for an orderly stop.
+sessionPruneTimer.unref?.()
+
 Bakery.onShutdown(() => {
   clearInterval(sessionPruneTimer)
 })

package/src/shared.d.ts

@@ -5,7 +5,7 @@ import type { MapOf } from './types'
  *
  * These used to be declared twice, verbatim, in `global.d.ts` and
  * `client/globals.d.ts`. Nothing caught it: `skipLibCheck: true` suppresses
- * errors *inside* .d.ts files — including this project's own — so four TS2300
+ * errors *inside* .d.ts files (including this project's own), so four TS2300
  * duplicate-identifier errors sat there invisibly, and every tsconfig excluded
  * `src/client/**` on top of that.
  *
@@ -16,7 +16,7 @@ import type { MapOf } from './types'
  * declared in two ambient files again.
  *
  * `MapOf` and `Wrapped` have since moved out of the global scope entirely,
- * into `types.d.ts` — their names are generic enough to collide with a
+ * into `types.d.ts`: their names are generic enough to collide with a
  * consuming app's own. What stays global here is framework-specific enough
  * not to, and is needed by browser globals that are bound at runtime rather
  * than imported.
@@ -27,12 +27,12 @@ import type { MapOf } from './types'
 declare global {
   /**
    * Bound by `client/utils.ts` in the browser and `core/init.ts` on the
-   * server — the same isomorphic implementation either side, so code moving
+   * server: the same isomorphic implementation either side, so code moving
    * between an SFC browser script and a server block keeps the name.
    */
   var randomId: typeof import('./utils/isomorphic/misc').randomId
 
-  /** The one JSON envelope — see convention 7. */
+  /** The one JSON envelope. See convention 7. */
   type JsonResponse<T = any> = {
     time: number
     status: number
@@ -52,7 +52,7 @@ declare global {
     (value: any, type: 'undefined'): value is undefined
     // `Function` is the type being narrowed to, and there is no narrower
     // spelling of "callable" a predicate can promise. `noBannedTypes` is off
-    // repo-wide, so this needs no suppression — see MONOREPO.md for why.
+    // repo-wide, so this needs no suppression. See MONOREPO.md for why.
     (value: any, type: 'function'): value is Function
     (value: any, type?: string): boolean
     string(value: any): value is string

package/src/startup.ts

@@ -39,7 +39,7 @@ let pluginSetup: Promise<void> | null = null
  * Calling both meant every non-clustered worker set its plugins up twice.
  * Handler and mount registration is idempotent so that went unnoticed, but the
  * analytics plugin registers a shutdown hook and kicks off `loadAnalyticsData()`
- * from `setup()` — so it got two of each. Memoising the promise (not a boolean)
+ * from `setup()`, so it got two of each. Memoizing the promise (not a boolean)
  * also makes a concurrent second caller await the first run rather than race it.
  */
 export function setupPlugins(): Promise<void> {
@@ -96,7 +96,7 @@ export async function runStartupBanner(): Promise<void> {
   const host = Bakery.config.host
 
   // Ground truth first. The banner's job is to print where the server is
-  // listening, and `Bakery.server.port` is what the OS actually gave us —
+  // listening, and `Bakery.server.port` is what the OS actually gave us,
   // which is the only correct answer under `PORT=0`, and the only *honest*
   // one if the bound port and the requested one ever part company again.
   // `resolvePort` covers the callers that print a banner without a server
@@ -134,7 +134,7 @@ export async function runStartupBanner(): Promise<void> {
     // constant, and any user-supplied value replaces the reference. The
     // default limiter 429s load tests and shared-NAT offices with nothing
     // anywhere saying it exists, so this line is its one announcement. An
-    // app-configured value prints nothing — their choice, their knowledge.
+    // app-configured value prints nothing: their choice, their knowledge.
     if (Bakery.config.rateLimit === DEFAULT_RATE_LIMIT) {
       serveLog.RATE_LIMIT_DEFAULT(DEFAULT_RATE_LIMIT)
     }

package/src/types.d.ts

@@ -4,7 +4,7 @@
  * These were declared in `declare global`, which is fine inside one repo and a
  * hazard the moment the packages are published: the names are generic enough
  * that a consuming app is likely to define its own `MapOf`, and a global type
- * alias cannot be merged or opted out of — the app just gets a redeclaration
+ * alias cannot be merged or opted out of, the app just gets a redeclaration
  * error with nowhere to put the fix.
  *
  * Moving them cost 24 files an `import type` line and cost consumers nothing:
@@ -12,7 +12,7 @@
  * that they were always internal plumbing rather than DX.
  *
  * `verbatimModuleSyntax` makes the compiler reject a value-position import of
- * these, so nothing can accidentally introduce a runtime module edge — which
+ * these, so nothing can accidentally introduce a runtime module edge, which
  * matters because `client/utils.ts` is compiled into the browser bundle.
  */
 export type MapOf<T> = { [key: string]: T }
@@ -20,7 +20,7 @@ export type MapOf<T> = { [key: string]: T }
 /** A value, or a function producing it. */
 export type Wrapped<T, Args extends any[] = []> = T | ((...args: Args) => T)
 
-/** Awaited or not — the shape almost every framework hook returns. */
+/** Awaited or not: the shape almost every framework hook returns. */
 export type MixedPromise<T> = Promise<T> | T
 
 type ResolveMatchReturn<V, R> = R extends any
@@ -54,12 +54,12 @@ export type Match<D extends symbol> = {
 /**
  * The `body` a route module's default export receives: declared params merge
  * over a permissive base. `body.id` is `string` once you declare it, while
- * `body.anythingElse` stays reachable as `any` — the parse rules in
+ * `body.anythingElse` stays reachable as `any`: the parse rules in
  * `utils/http/body.ts` mean the framework genuinely cannot know every key, so
  * locking the object down would be a lie in the other direction.
  *
  * There is no filename-literal inference (`[id].ts` does not conjure
- * `{ id: string }` on its own — that needs codegen); the contract is that the
+ * `{ id: string }` on its own. That needs codegen); the contract is that the
  * author declares the shape once, at the `defineRoute` / `html` call, instead
  * of annotating the whole signature or settling for `any`.
  */
@@ -71,13 +71,13 @@ export type RouteBody<P = {}> = P & MapOf<any>
  * directory under the `!` form).
  *
  * Exists so a route over mixed or unknown segments can say
- * `defineRoute<MapOf<RouteParam>>` instead of hand-writing the union — and so
+ * `defineRoute<MapOf<RouteParam>>` instead of hand-writing the union, and so
  * the union has one definition to change if it ever grows.
  */
 export type RouteParam = string | string[]
 
 /**
- * What a route module may actually return — read off `processResponse`
+ * What a route module may actually return. Read off `processResponse`
  * (`router.ts`) and `ApiHandler.handle`: a `Response`, a `BunFile` (streamed
  * with an ETag), the JSON envelope, a plain data object or array (JSON-encoded
  * as-is), a string (HTML-sniffed) or number, or nothing (204; a 404 under
@@ -85,10 +85,10 @@ export type RouteParam = string | string[]
  *
  * Deliberately not `object` (which `Handler.Response` uses): `object` absorbs
  * `Response`, `BunFile` and `JsonResponse` into one member and the union stops
- * saying anything — the same trap `routeTable()`'s dispatch avoids. `MapOf<any>`
+ * saying anything, the same trap `routeTable()`'s dispatch avoids. `MapOf<any>`
  * is the narrowest thing that covers "a plain data object"; a target index
  * signature of `any` does still accept class instances, but that only matters
- * for inference targets — this union is a constraint on what an author may
+ * for inference targets: this union is a constraint on what an author may
  * return, and nothing consumes a route module's return type downstream, so the
  * members stay legible instead of collapsing.
  */
@@ -107,7 +107,7 @@ export type RouteResponse = MixedPromise<
 
 /**
  * A typed route module default export. `$dynamic.executeModule` calls it as
- * `(req, body, Bakery.server)` — the third argument is optional here because
+ * `(req, body, Bakery.server)`: the third argument is optional here because
  * `Bakery.server` is itself optional before `Bun.serve` runs, and almost no
  * handler wants it.
  *

package/src/utils/common/case.ts

@@ -1,5 +1,5 @@
 /**
- * `Case` moved to `utils/isomorphic/case` — the client bundle carried an
+ * `Case` moved to `utils/isomorphic/case`: the client bundle carried an
  * identical copy. `toHash` stays here: it calls `Bun.hash`, so it is server-only
  * and must not be pulled into the isomorphic layer.
  */

package/src/utils/common/match.ts

@@ -1,6 +1,6 @@
 /**
  * Moved to `utils/isomorphic/match` so the browser bundle and the server share
- * one implementation — the prototype-chain fix (`Object.hasOwn` rather than
+ * one implementation: the prototype-chain fix (`Object.hasOwn` rather than
  * `in`) previously had to be applied to both copies separately.
  */
 export * from '../isomorphic/match'

package/src/utils/common/misc.ts

@@ -1,5 +1,5 @@
 /**
- * `is`, `Math2` and `throws` moved to `utils/isomorphic/` — the client bundle
+ * `is`, `Math2` and `throws` moved to `utils/isomorphic/`: the client bundle
  * carried its own copies of all three. They are re-exported here so existing
  * `@server/utils` importers are unaffected.
  *

package/src/utils/constants.ts

@@ -12,7 +12,7 @@ export const DEFAULT_RATE_LIMIT = { max: 100, refill: 10 }
  * Files that must never be served off disk.
  *
  * These are matched against the file a *file-serving* handler is about to
- * return, not against every request path — see `servesFiles` in `router.ts`.
+ * return, not against every request path. See `servesFiles` in `router.ts`.
  * An API route or a proxied path is a name, not a file, and never had any
  * business being tested against this list.
  *
@@ -22,8 +22,8 @@ export const DEFAULT_RATE_LIMIT = { max: 100, refill: 10 }
  * on that attempt.
  *
  * Note what is *not* here: an extension-wide ban on JSON. It caught every
- * JSON document an app might legitimately publish — a web app manifest, a
- * `.well-known` document — and since `blocked` in config can only ever append,
+ * JSON document an app might legitimately publish: a web app manifest, a
+ * `.well-known` document, and since `blocked` in config can only ever append,
  * an app had no way to opt back out. What the list is actually protecting is
  * the handful of JSON files that describe the project, so those are named.
  */
@@ -46,9 +46,9 @@ export const DEFAULT_BLOCKED_GLOBS = [
   // trailing `**` collapses to a single segment: `{**/node_modules/**}` matches
   // `/node_modules/a` and then stops, so `/node_modules/pkg/index.js` was not
   // blocked by anything. Each pattern still matched on its own, which is why
-  // it survived — the defect only exists in the form the config actually uses.
+  // it survived: the defect only exists in the form the config actually uses.
   // `.cache` is the framework's disposable working dir and `bakery/` holds the
-  // database and its backups — the visible one is the precious one, so that a
+  // database and its backups: the visible one is the precious one, so that a
   // dotfile sweep cannot reach the data. `bakery/` being un-dotted is why it
   // needs naming here explicitly: `*.db` covers the database file itself, but
   // not the `.ts` schema snapshots under `bakery/backups/`.
@@ -67,17 +67,17 @@ export const DEFAULT_BLOCKED_GLOBS = [
 /**
  * A request path folded to the form the *filesystem* would resolve it to.
  *
- * Two normalisations, both of them things the OS does and the glob does not:
+ * Two normalizations, both of them things the OS does and the glob does not:
  *
  * - **Case.** NTFS and APFS are case-insensitive, so `/PACKAGE.JSON` opens the
- *   same bytes as `/package.json` — but `Bun.Glob` is case-sensitive, so only
+ *   same bytes as `/package.json`, but `Bun.Glob` is case-sensitive, so only
  *   the second one was blocked. Every file this list protects was reachable by
  *   holding down shift, and the static pipeline was verified to serve
  *   `/STYLES/GLOBAL.CSS` and `/styles/global.css` as the same 170 bytes.
  * - **Trailing dots and spaces.** Win32 strips both from each path component,
  *   so `/package.json.` and `/package.json ` are the same file too.
  *
- * `.`, `..` and any all-dots component are left intact — trimming those would
+ * `.`, `..` and any all-dots component are left intact: trimming those would
  * rewrite a relative segment into something else, and containment is
  * `fs.isForbidden`'s job, not this function's.
  */
@@ -93,14 +93,14 @@ export function normalizeBlockedPath(path: string): string {
  * Each path component truncated at its first `:`.
  *
  * Win32 resolves `x.ts::$DATA` to the bytes of `x.ts` and
- * `dir::$INDEX_ALLOCATION` to `dir` — NTFS alternate-data-stream syntax — and
+ * `dir::$INDEX_ALLOCATION` to `dir` (NTFS alternate-data-stream syntax), and
  * `new URL()` keeps the suffix in `pathname`, so a glob anchored on the real
  * name missed while the filesystem opened the file anyway. The directory form
  * matters independently: it defeats the `dir/**` patterns that the file form
  * cannot reach.
  *
  * Only ever used as an *extra* match candidate (see `matchBlocked`), never as
- * a replacement — colons are legal in POSIX filenames, and a real file named
+ * a replacement: colons are legal in POSIX filenames, and a real file named
  * `a:b.db` must stay blocked by `*.db` rather than being tested as `a`.
  */
 function stripStreamSuffix(path: string): string {
@@ -117,18 +117,18 @@ function stripStreamSuffix(path: string): string {
 /**
  * Whether `path` is refused by the blocked globs.
  *
- * Matched twice: once as written, once normalised. Both are needed, and for
- * different reasons. The normalised pass is what closes the case and
+ * Matched twice: once as written, once normalized. Both are needed, and for
+ * different reasons. The normalized pass is what closes the case and
  * trailing-dot variants above. The verbatim pass is what keeps an app's own
- * `blocked: ['**\/Secrets.txt']` working — `initConfig` appends user patterns
+ * `blocked: ['**\/Secrets.txt']` working, `initConfig` appends user patterns
  * to this list untouched, so folding only the path would quietly stop matching
  * the very patterns the app wrote.
  *
  * On a case-*sensitive* filesystem this over-blocks: a file genuinely named
  * `/PACKAGE.JSON`, distinct from `/package.json`, is refused. That is the
- * intended direction to be wrong in, and it is the reason this normalises the
+ * intended direction to be wrong in, and it is the reason this normalizes the
  * path rather than resolving the file. The router runs this check before it
- * knows which file — often before there is a file at all — so "ask the
+ * knows which file (often before there is a file at all), so "ask the
  * filesystem for the real name" is not available at the point the answer is
  * needed, and would cost a `realpath` per request where it was.
  */