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

package/src/utils/http/sse.ts

@@ -3,25 +3,25 @@
  *
  * Bakery had WebSockets and nothing for one-way streaming, which is the cheaper
  * half of that pair and the right shape for progress, notifications and tailing
- * — no upgrade, no protocol, reconnects handled by the browser.
+ *: no upgrade, no protocol, reconnects handled by the browser.
  *
  * A route could always return a `Response` wrapping a `ReadableStream` and it
  * would reach the client intact: `ETag.sendResponse` returns early without an
  * `ETag` header, and `injectIfHtml` ignores anything that is not HTML. What was
- * missing is the framing, and framing is where this goes wrong — a payload
+ * missing is the framing, and framing is where this goes wrong: a payload
  * containing a newline silently truncates unless every line is prefixed, and a
  * write after the client has gone throws where nobody is catching.
  */
 
 /** One event. Every field is optional except the payload. */
 export interface SSEMessage {
-  /** Serialised with `JSON.stringify` unless it is already a string. */
+  /** Serialized with `JSON.stringify` unless it is already a string. */
   data: unknown
-  /** `event:` — the client listens for this name instead of `message`. */
+  /** `event:`: the client listens for this name instead of `message`. */
   event?: string
-  /** `id:` — echoed back as `Last-Event-ID` when the browser reconnects. */
+  /** `id:`: echoed back as `Last-Event-ID` when the browser reconnects. */
   id?: string
-  /** `retry:` — how long the browser waits before reconnecting, in ms. */
+  /** `retry:`: how long the browser waits before reconnecting, in ms. */
   retry?: number
 }
 
@@ -42,7 +42,7 @@ export interface SSEOptions {
    * Milliseconds between automatic keep-alive comments. `0` disables them.
    *
    * Defaults to 15s because idle proxies and load balancers commonly cut a
-   * connection at 30–60s, and a dead SSE stream is invisible: the browser
+   * connection at 30 to 60s, and a dead SSE stream is invisible: the browser
    * reconnects silently, so the symptom is duplicated work on the server rather
    * than an error anyone sees.
    */
@@ -55,7 +55,7 @@ export interface SSEOptions {
  * Encode one message as an SSE frame.
  *
  * **Every line of `data` is prefixed.** A payload containing a newline is
- * otherwise cut short at that newline — the rest is read as a new field, and
+ * otherwise cut short at that newline: the rest is read as a new field, and
  * the client sees a truncated message rather than an error. Pretty-printed JSON
  * and stack traces both hit this.
  */
@@ -72,7 +72,7 @@ export function encodeSSE(message: SSEMessage): string {
       : JSON.stringify(message.data)
 
   // `?? ''` rather than skipping: `JSON.stringify(undefined)` is undefined, and
-  // a frame with no `data:` line at all is a comment to the client — the event
+  // a frame with no `data:` line at all is a comment to the client. The event
   // would vanish rather than arrive empty.
   for (const line of (payload ?? '').split('\n')) lines.push(`data: ${line}`)
 
@@ -116,7 +116,7 @@ export function sse(
       controller.enqueue(encoder.encode(chunk))
     } catch {
       // The client went away between the `closed` check and the enqueue. That
-      // is a normal race on every disconnect, not an error worth surfacing —
+      // is a normal race on every disconnect, not an error worth surfacing,
       // and throwing here would reject inside a timer callback, where nothing
       // is catching.
       finish()
@@ -192,7 +192,7 @@ export function sse(
       'Cache-Control': 'no-cache, no-transform',
       Connection: 'keep-alive',
       // nginx buffers proxied responses by default, which holds every event
-      // until the buffer fills — the stream appears to work in development and
+      // until the buffer fills: the stream appears to work in development and
       // to hang in production. This is the documented opt-out.
       'X-Accel-Buffering': 'no',
     },

package/src/utils/http/url.ts

@@ -2,7 +2,7 @@
  * The request's parsed URL, parsed at most once.
  *
  * Why memoize at all: `new URL` measures ~1.7µs, and the router, the body
- * parser and the proxy handler all want the same parse of the same request —
+ * parser and the proxy handler all want the same parse of the same request,
  * so the parse was hoisted into the server's `fetch` in `packages/cli/src/worker.ts`
  * and shared.
  *
@@ -10,12 +10,12 @@
  * `(req as any).__parsedUrl`: two writers, six readers across three packages,
  * every reader spelled `(req as any).__parsedUrl || new URL(req.url)` so that
  * it silently re-parsed whenever the writer had not run first. That is a
- * writer/reader ordering hazard with no way to observe it going wrong — a
+ * writer/reader ordering hazard with no way to observe it going wrong: a
  * missed write costs microseconds, not correctness, so nothing ever fails.
  * One function collapses both roles: there is no ordering left to get wrong,
  * no `any` cast anywhere, and no writer to forget. The map also keeps the
- * framework from mutating a `Request` object it does not own — a caller's
- * `Request` goes in and comes back unchanged — and holds its keys weakly, so
+ * framework from mutating a `Request` object it does not own (a caller's
+ * `Request` goes in and comes back unchanged), and holds its keys weakly, so
  * an entry dies with the request rather than needing eviction (convention 6).
  *
  * There is deliberately no setter. Nothing outside this module needs to say

package/src/utils/http/validate.ts

@@ -1,8 +1,7 @@
 /**
  * Request-body validation for route modules.
  *
- * `defineRoute<{ title: string }>` declares a body shape and enforces nothing —
- * the scaffolder's own template says so twice: *"declares the contract — it
+ * `defineRoute<{ title: string }>` declares a body shape and enforces nothing ( * the scaffolder's own template says so twice: *"declares the contract) it
  * does not validate it. The body is still client input."* Every route was left
  * to hand-check or not, and most did not.
  *
@@ -10,7 +9,7 @@
  * core` has zero runtime dependencies and that is worth keeping, so validation
  * accepts two shapes it can consume without knowing who produced them:
  *
- *   - **Standard Schema** (`~standard`) — the shared interface zod, valibot and
+ *   - **Standard Schema** (`~standard`): the shared interface zod, valibot and
  *     arktype all implement. Bring your own library; Bakery never imports it.
  *   - **A plain function** that returns the parsed value or throws.
  *
@@ -59,7 +58,7 @@ function isStandardSchema<T>(v: Validator<T>): v is StandardSchemaLike<T> {
 /**
  * Render a Standard Schema path as dotted notation.
  *
- * Segments may be plain keys or `{ key }` objects — the spec allows both, and a
+ * Segments may be plain keys or `{ key }` objects: the spec allows both, and a
  * library that uses the object form would otherwise render as `[object Object]`
  * in the very message meant to tell someone which field is wrong.
  */

package/src/utils/isomorphic/escape.ts

@@ -4,7 +4,7 @@
  * These live in `isomorphic/` because both sides need them: the HTML pipeline
  * and the Vue plugin escape on the way out, and the client bundle escapes when
  * building DOM strings. Nothing here may reference `Bun.*`, node builtins, or
- * DOM globals — this module is compiled into the browser bundle as-is.
+ * DOM globals: this module is compiled into the browser bundle as-is.
  */
 
 const HTML_ESCAPES: Record<string, string> = {

package/src/utils/isomorphic/is.ts

@@ -4,7 +4,7 @@
  * Two implementations of this used to exist. This one keeps the *callable*
  * shape from the client copy (`is(x, 'string')` as well as `is.string(x)`,
  * which is what the global `ISFunction` type has always described) and the
- * *semantics* of the server copy — notably `is.object([]) === true`, which
+ * *semantics* of the server copy, notably `is.object([]) === true`, which
  * `misc.test.ts` asserts and which callers like `router.ts` rely on to
  * JSON-encode array response bodies.
  */
@@ -16,7 +16,7 @@ const checks = {
   bigint: (v: any): v is bigint => typeof v === 'bigint',
   symbol: (v: any): v is symbol => typeof v === 'symbol',
   function: (v: any): v is Function => typeof v === 'function',
-  /** Arrays count as objects here — see the note above before changing this. */
+  /** Arrays count as objects here. See the note above before changing this. */
   object: (v: any): v is Record<string, any> =>
     v !== null && typeof v === 'object',
   array: Array.isArray,

package/src/utils/isomorphic/misc.ts

@@ -20,7 +20,7 @@ export function any<T = any>(value: any): T {
  *
  * Isomorphic, and moving it here is what made it so: it lived in
  * `client/utils.ts` as a browser global only, so the same call in a server
- * block was a ReferenceError — reported from an app. `crypto` is a global in
+ * block was a ReferenceError, reported from an app. `crypto` is a global in
  * both runtimes; nothing here is browser-specific.
  */
 export function randomId(length = 8) {

package/src/utils/isomorphic/stringify.ts

@@ -2,9 +2,8 @@
  * Circular-safe JSON helpers.
  *
  * Three copies of this logic existed: the client `$fmt` formatter, the
- * livereload log serializer, and ad-hoc replacers on the server. They drifted —
- * the `$fmt` one shipped with a one-parameter replacer that made every object
- * render as `""` — so the kernel lives here once and callers layer their own
+ * livereload log serializer, and ad-hoc replacers on the server. They drifted ( * the `$fmt` one shipped with a one-parameter replacer that made every object
+ * render as `""`), so the kernel lives here once and callers layer their own
  * extras on top.
  */
 

package/src/utils/isomorphic/try.ts

@@ -1,7 +1,7 @@
 import type { MixedPromise, Wrapped } from '../../types'
 import { is } from './is'
 
-// These were declared again, here, byte-for-byte identical to `types.d.ts` —
+// These were declared again, here, byte-for-byte identical to `types.d.ts`:
 // the second copy convention 5 exists to prevent. `isomorphic.test.ts` catches
 // a duplicated *value* by reference identity, and a type has no runtime
 // identity to compare, so nothing saw it.

package/src/utils/shared-pool.ts

@@ -22,11 +22,29 @@ export class SharedMemoryPool {
   header!: Int32Array
   counters!: Int32Array
   rateLimits!: Int32Array
-  dataPool!: Uint8Array
 
-  constructor(sizeOrBuffer: number | SharedArrayBuffer = 1024 * 1024) {
+  /**
+   * **The default is the layout's own size, not a megabyte.**
+   *
+   * It was `1024 * 1024`, and the layout uses 9,280 bytes of it: a 64-byte
+   * header, 1 KB of counters and 8 KB of rate-limit slots. The remaining
+   * 1,039,296 bytes were a `dataPool` region that **nothing read** - grep it
+   * across every package and app, and the only reference outside this file was
+   * a test asserting it was a `Uint8Array`. So 99.1% of a `SharedArrayBuffer`
+   * allocated at import in every server process existed for one assertion.
+   *
+   * The region is gone rather than shrunk. A scratch area with no consumer is
+   * not a feature waiting to be used; it is a number nobody can size, because
+   * there is nothing to size it against. Something that needs shared scratch
+   * later adds it along with the code that reads it.
+   *
+   * A larger size is still accepted and still honored, because `bind()` reads
+   * the size out of the header rather than trusting `byteLength` - so a
+   * cluster master that allocates more and shares it still works.
+   */
+  constructor(sizeOrBuffer: number | SharedArrayBuffer = BUFFER_START_OFFSET) {
     if (typeof sizeOrBuffer === 'number') {
-      const size = Math.max(sizeOrBuffer, BUFFER_START_OFFSET + 1024)
+      const size = Math.max(sizeOrBuffer, BUFFER_START_OFFSET)
       this.buffer = new SharedArrayBuffer(size)
       this.header = new Int32Array(this.buffer, 0, HEADER_INT_COUNT)
       this.counters = new Int32Array(
@@ -39,17 +57,11 @@ export class SharedMemoryPool {
         HEADER_BYTES + COUNTERS_BYTES,
         RATE_LIMIT_SLOT_COUNT * 2,
       )
-      this.dataPool = new Uint8Array(
-        this.buffer,
-        BUFFER_START_OFFSET,
-        size - BUFFER_START_OFFSET,
-      )
-
       Atomics.store(this.header, 0, 0x42414b45)
       Atomics.store(this.header, 1, size)
       Atomics.store(this.header, 2, BUFFER_START_OFFSET)
     } else {
-      // Adopting a buffer someone else laid out is exactly what `bind` does —
+      // Adopting a buffer someone else laid out is exactly what `bind` does:
       // it read the header for the size rather than trusting `byteLength`, and
       // so did the copy that used to sit here, character for character.
       this.bind(sizeOrBuffer)
@@ -70,12 +82,7 @@ export class SharedMemoryPool {
       HEADER_BYTES + COUNTERS_BYTES,
       RATE_LIMIT_SLOT_COUNT * 2,
     )
-    const size = Atomics.load(this.header, 1) || this.buffer.byteLength
-    this.dataPool = new Uint8Array(
-      this.buffer,
-      BUFFER_START_OFFSET,
-      size - BUFFER_START_OFFSET,
-    )
+
   }
 
   incrementCounter(slot: number, delta = 1): number {

package/tsconfig.app.json

@@ -1,12 +1,12 @@
 {
   "$comment": [
-    "**Client-side code** — the plain `.ts` under your source root that ends up",
+    "**Client-side code**, the plain `.ts` under your source root that ends up",
     "in the browser bundle. Extend it:",
     "  { \"extends\": \"@bakery-framework/core/tsconfig.app.json\" }",
     "",
     "BREAKING, 2.0.0: this file used to be the single config every app",
     "extended, and it carried `bun-types` and the JSX settings. It is now the",
-    "*browser* half of a three-way split — server code extends",
+    "*browser* half of a three-way split: server code extends",
     "tsconfig.server.json, Vue SFCs extend tsconfig.vue.json.",
     "",
     "**`types` is deliberately empty.** That is the entire reason the split",
@@ -18,7 +18,7 @@
     "tsconfig.server.json; a `.tsx` file compiled under this config would pick up",
     "the automatic runtime and fail at request time while typechecking clean."
   ],
-  "_files_note": "client/globals.d.ts declares the globals the browser runtime binds onto globalThis (request, escapeHTML, is, Try, Case, match, …). It states each as `typeof import(...)` of the isomorphic module that implements it, so the declaration cannot drift from the value. Those modules are pure by convention — no Bun, no node builtins, no DOM — which is what makes them safe to pull into a project that has no bun-types.",
+  "_files_note": "client/globals.d.ts declares the globals the browser runtime binds onto globalThis (request, escapeHTML, is, Try, Case, match, …). It states each as `typeof import(...)` of the isomorphic module that implements it, so the declaration cannot drift from the value. Those modules are pure by convention (no Bun, no node builtins, no DOM), which is what makes them safe to pull into a project that has no bun-types.",
   "files": [
     "./src/client/globals.d.ts",
     "./src/shared.d.ts",

package/tsconfig.vue.json

@@ -4,18 +4,18 @@
     "  { \"extends\": \"@bakery-framework/core/tsconfig.vue.json\" }",
     "",
     "SFCs get `bun-types` like server code does, because @bakery-framework/",
-    "plugin-vue compiles and can render them on the server — a `<script>` block",
+    "plugin-vue compiles and can render them on the server, a `<script>` block",
     "is not browser-only the way a plain `.ts` under the source root is.",
     "",
     "**`tsc` cannot parse `.vue`.** This config is for `vue-tsc`, which wraps tsc",
     "and understands SFCs. Pointing plain `tsc` at a project whose `include`",
     "matches `**/*.vue` gets you either silence or a parse error, depending on",
-    "version — neither of which is a typecheck.",
+    "version, neither of which is a typecheck.",
     "",
     "`jsx: preserve` rather than Bakery's classic runtime: inside an SFC, JSX (if",
     "used at all) belongs to Vue's own transform, not to `createElement`."
   ],
-  "_files_note": "Server ambients, same as tsconfig.server.json — an SFC can reach Bakery, AppConfig and the JSX namespace.",
+  "_files_note": "Server ambients, same as tsconfig.server.json. An SFC can reach Bakery, AppConfig and the JSX namespace.",
   "files": ["./src/global.d.ts", "./src/shared.d.ts", "./src/types.d.ts"],
   "compilerOptions": {
     "lib": ["ESNext", "DOM", "DOM.Iterable"],