@bakery-framework/core 1.0.0

package/src/utils/isomorphic/case.ts

@@ -0,0 +1,52 @@
+function toKebabCase(str: string): string {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase()
+}
+
+function toCamelCase(str: string): string {
+  return str
+    .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ''))
+    .replace(/^[A-Z]/, match => match.toLowerCase())
+}
+
+function toPascalCase(str: string): string {
+  const camel = toCamelCase(str)
+  return camel.charAt(0).toUpperCase() + camel.slice(1)
+}
+
+function toSnakeCase(str: string): string {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1_$2')
+    .replace(/[\s-]+/g, '_')
+    .toLowerCase()
+}
+
+type CaseType = 'kebab' | 'camel' | 'pascal' | 'snake'
+
+export const Case = Object.assign(
+  function Case(type: CaseType, str: string): string {
+    switch (type) {
+      case 'kebab':
+        return toKebabCase(str)
+      case 'camel':
+        return toCamelCase(str)
+      case 'pascal':
+        return toPascalCase(str)
+      case 'snake':
+        return toSnakeCase(str)
+      default:
+        return str
+    }
+  },
+  {
+    kebab: toKebabCase,
+    camel: toCamelCase,
+    pascal: toPascalCase,
+    snake: toSnakeCase,
+    upper: (str: string) => str.toUpperCase(),
+    lower: (str: string) => str.toLowerCase(),
+    caps: (str: string) => str.toUpperCase().replace(/[\s_-]+/g, ''),
+  },
+)

package/src/utils/isomorphic/escape.ts

@@ -0,0 +1,43 @@
+/**
+ * Escaping primitives shared by the server pipeline and the browser runtime.
+ *
+ * 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.
+ */
+
+const HTML_ESCAPES: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+}
+
+/**
+ * Escape the five HTML-significant characters. Nullish input yields an empty
+ * string rather than throwing, so it is safe to call on optional values.
+ */
+export function escapeHtml(value: unknown): string {
+  if (value === null || value === undefined) return ''
+  return String(value).replace(/[&<>"']/g, char => HTML_ESCAPES[char] || char)
+}
+
+/**
+ * Serialize for embedding inside a `<script>` tag. Escaping `<` stops a
+ * `</script>` in the data from closing the tag; U+2028/2029 are line terminators
+ * to a JS parser but legal raw inside JSON.
+ *
+ * `utils/http/dom.ts` used to carry its own copy of this and is now a caller.
+ */
+export function escapeScriptJson(value: unknown): string {
+  const json = JSON.stringify(value, (_key, val) =>
+    val === undefined ? null : val,
+  )
+  if (json === undefined) return 'null'
+  return json
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029')
+}

package/src/utils/isomorphic/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Pure utilities shared by the server and the browser bundle.
+ *
+ * Rule for this directory: no `Bun.*`, no node builtins, no DOM globals. These
+ * modules are compiled into the client bundle as-is, so anything that reaches
+ * for a runtime API belongs one layer up in `utils/` or in `client/`.
+ */
+export * from './case'
+export * from './escape'
+export * from './is'
+export * from './match'
+export * from './math'
+export * from './misc'
+export * from './stringify'
+export * from './try'

package/src/utils/isomorphic/is.ts

@@ -0,0 +1,36 @@
+/**
+ * Type predicates, shared by the server and the browser bundle.
+ *
+ * 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
+ * `misc.test.ts` asserts and which callers like `router.ts` rely on to
+ * JSON-encode array response bodies.
+ */
+
+const checks = {
+  string: (v: any): v is string => typeof v === 'string',
+  number: (v: any): v is number => typeof v === 'number',
+  boolean: (v: any): v is boolean => typeof v === 'boolean',
+  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. */
+  object: (v: any): v is Record<string, any> =>
+    v !== null && typeof v === 'object',
+  array: Array.isArray,
+  null: (v: any): v is null => v === null,
+  undefined: (v: any): v is undefined => v === undefined,
+}
+
+export const is: ISFunction = Object.assign(function is(
+  value: any,
+  type?: string,
+) {
+  if (!type) return value !== null && value !== undefined
+  // Delegate to the table rather than falling through to `typeof`, so that
+  // is(null, 'object') agrees with is.object(null) instead of contradicting it.
+  const check = (checks as any)[type]
+  return check ? check(value) : typeof value === type
+}, checks) as ISFunction

package/src/utils/isomorphic/match.ts

@@ -0,0 +1,50 @@
+import type { Match } from '../../types'
+
+const matchDefault = Symbol('matchDefault')
+
+function handleStringCases(value: any, cases: any): any {
+  // hasOwn, not `in`: `in` walks the prototype chain, so match('toString', {…})
+  // would find and invoke Object.prototype.toString.
+  if (Object.hasOwn(cases, value)) {
+    const handler = cases[value]
+    return typeof handler === 'function' ? handler(value) : handler
+  }
+  if (matchDefault in cases) {
+    const handler = cases[matchDefault]
+    return typeof handler === 'function' ? handler(value) : handler
+  }
+  return undefined
+}
+
+function handleArrayCases(value: any, cases: any[]): any {
+  for (const [predicate, result] of cases) {
+    const isMatch =
+      predicate === match ||
+      predicate === matchDefault ||
+      predicate === value ||
+      (typeof predicate === 'function' && Boolean(predicate(value)))
+
+    if (isMatch) {
+      return typeof result === 'function' ? result(value) : result
+    }
+  }
+  return undefined
+}
+
+export const match: Match<typeof matchDefault> = ((value: any, cases: any) => {
+  const isString = typeof value === 'string'
+  const isArray = Array.isArray(cases)
+
+  if (isString && !isArray) {
+    return handleStringCases(value, cases)
+  }
+  if (isArray) {
+    return handleArrayCases(value, cases)
+  }
+  return undefined
+}) as any
+
+match.default = matchDefault
+match[Symbol.toPrimitive] = () => matchDefault
+
+export { matchDefault }

package/src/utils/isomorphic/math.ts

@@ -0,0 +1,11 @@
+export const Math2 = {
+  clamp(value: number, min?: number, max?: number): number {
+    min ??= -Infinity
+    max ??= Infinity
+    return Math.min(Math.max(value, min), max)
+  },
+
+  step(value: number, step: number): number {
+    return Math.round(value / step) * step
+  },
+}

package/src/utils/isomorphic/misc.ts

@@ -0,0 +1,22 @@
+import { is } from './is'
+
+export function throws(message: string | Error): never {
+  throw is.string(message) ? new Error(message) : message
+}
+
+export function assert(condition: any, message?: string): asserts condition {
+  if (!condition) {
+    throw new Error(message || 'Assertion failed')
+  }
+}
+
+/** Escape hatch for casting through `any` without spelling it out each time. */
+export function any<T = any>(value: any): T {
+  return value
+}
+
+export function repeat(n: number): number[]
+export function repeat<T>(n: number, fn: (i: number) => T): T[]
+export function repeat<T>(n: number, fn?: (i: number) => T): unknown[] {
+  return Array.from({ length: n }, (_, k) => (fn ? fn(k) : k))
+}

package/src/utils/isomorphic/stringify.ts

@@ -0,0 +1,42 @@
+/**
+ * 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
+ * extras on top.
+ */
+
+/**
+ * Build a `JSON.stringify` replacer that substitutes `'[Circular]'` for repeat
+ * references. `extra` runs after the cycle check and can rewrite values further.
+ *
+ * Note the two-parameter signature: `JSON.stringify` calls a replacer as
+ * `(key, value)`, so a single-parameter function silently binds to *key*.
+ */
+export function circularReplacer(
+  extra?: (key: string, value: any) => any,
+): (key: string, value: any) => any {
+  const seen = new WeakSet<object>()
+  return (key, value) => {
+    if (typeof value === 'object' && value !== null) {
+      if (seen.has(value)) return '[Circular]'
+      seen.add(value)
+    }
+    return extra ? extra(key, value) : value
+  }
+}
+
+/**
+ * Best-effort string form of any value, safe against cycles and throwing
+ * `toJSON`/getters. Primitives pass through `String()` unchanged.
+ */
+export function safeStringify(value: unknown): string {
+  if (typeof value !== 'object' || value === null) return String(value)
+  try {
+    return JSON.stringify(value, circularReplacer()) ?? String(value)
+  } catch {
+    return Object.prototype.toString.call(value)
+  }
+}

package/src/utils/isomorphic/try.ts

@@ -0,0 +1,94 @@
+import type { MixedPromise, Wrapped } from '../../types'
+import { is } from './is'
+
+// 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.
+//
+// A type-only import is safe in an isomorphic module: `verbatimModuleSyntax`
+// makes the compiler reject a value-position import of these, so it cannot
+// become a runtime module edge into the browser bundle.
+
+type CatchReturn<T extends MixedPromise<any>> =
+  T extends Promise<infer V>
+    ? Promise<[Error, null] | [null, V]>
+    : MixedPromise<[Error, null] | [null, T]>
+
+function tryThrow<T>(
+  callback: () => MixedPromise<T>,
+  error?: string | Error,
+): Promise<T> {
+  return Promise.try(callback).catch((err: any) => {
+    throw is.string(error) ? new Error(error) : error || err
+  })
+}
+
+function tryReturn<T extends MixedPromise<any>, D extends MixedPromise<any>>(
+  value: Wrapped<T>,
+  defaultValue: Wrapped<D, [Error]>,
+): T | D {
+  try {
+    const unwrapped = is.function(value) ? (value as any)() : value
+    if (
+      unwrapped instanceof Promise ||
+      (is.object(unwrapped) && is.function((unwrapped as any).catch))
+    ) {
+      return (unwrapped as any).catch((error: any) =>
+        is.function(defaultValue) ? (defaultValue as any)(error) : defaultValue,
+      ) as any
+    }
+    return unwrapped
+  } catch (error: any) {
+    const unwrappedDefault = is.function(defaultValue)
+      ? (defaultValue as any)(error)
+      : defaultValue
+    return unwrappedDefault
+  }
+}
+
+function trySilent<T extends MixedPromise<any>>(value: Wrapped<T>): T | null {
+  return tryReturn(value, null as any)
+}
+
+type TryType = {
+  <T extends MixedPromise<any>>(value: Wrapped<T>): T | null
+  catch<T extends MixedPromise<any>>(value: Wrapped<T>): CatchReturn<T>
+  return<T extends MixedPromise<any>, D extends MixedPromise<any>>(
+    value: Wrapped<T>,
+    defaultValue: Wrapped<D, [Error]>,
+  ): T | D
+  throw: typeof tryThrow
+  /**
+   * Alias for calling `Try` directly. Kept because the browser global has
+   * always exposed it; unifying the two copies is not the place to shrink a
+   * published surface.
+   */
+  silent<T extends MixedPromise<any>>(value: Wrapped<T>): T | null
+}
+
+export const Try: TryType = Object.assign(
+  function Try<T extends MixedPromise<any>>(value: Wrapped<T>): T | null {
+    return trySilent(value)
+  },
+  {
+    catch<T extends MixedPromise<any>>(value: Wrapped<T>): CatchReturn<T> {
+      if (is.function(value)) {
+        return Promise.try(value as any)
+          .then(data => [null, data])
+          .catch(error => [error, null]) as any
+      }
+      if (value instanceof Promise) {
+        return value
+          .then(data => [null, data])
+          .catch(error => [error, null]) as any
+      }
+      return [null, value] as any
+    },
+    return: tryReturn,
+    throw: tryThrow,
+    silent: trySilent,
+  },
+)
+
+export const tryCatch = Try.catch

package/src/utils/jsonc.ts

@@ -0,0 +1,10 @@
+export function parseJSONC(jsonc: string): any {
+  if (!jsonc.trim()) return null
+
+  const clean = jsonc.replace(
+    /("(?:\\.|[^"\\])*")|(\/\/.*|\/\*[\s\S]*?\*\/)|,\s*(?=[\]}])/g,
+    (_, stringLiteral) => (stringLiteral ? stringLiteral : ''),
+  )
+
+  return JSON.parse(clean)
+}

package/src/utils/shared-pool.ts

@@ -0,0 +1,193 @@
+const HEADER_INT_COUNT = 16
+const COUNTERS_INT_COUNT = 256
+const RATE_LIMIT_SLOT_COUNT = 1024
+const HEADER_BYTES = HEADER_INT_COUNT * 4
+const COUNTERS_BYTES = COUNTERS_INT_COUNT * 4
+const RATE_LIMIT_BYTES = RATE_LIMIT_SLOT_COUNT * 2 * 4
+const BUFFER_START_OFFSET = HEADER_BYTES + COUNTERS_BYTES + RATE_LIMIT_BYTES
+
+export const COUNTER_SLOTS = {
+  TOTAL_REQUESTS: 0,
+  TOTAL_ERRORS: 1,
+  ACTIVE_CONNECTIONS: 2,
+  LATENCY_SUM_MS: 3,
+} as const
+
+export class SharedMemoryPool {
+  // Definite-assignment assertions because the adopt-an-existing-buffer path
+  // assigns all five through `bind()`, and TypeScript's initialization
+  // analysis does not follow a method call out of the constructor. Both
+  // constructor paths do assign every one of them before returning.
+  buffer!: SharedArrayBuffer
+  header!: Int32Array
+  counters!: Int32Array
+  rateLimits!: Int32Array
+  dataPool!: Uint8Array
+
+  constructor(sizeOrBuffer: number | SharedArrayBuffer = 1024 * 1024) {
+    if (typeof sizeOrBuffer === 'number') {
+      const size = Math.max(sizeOrBuffer, BUFFER_START_OFFSET + 1024)
+      this.buffer = new SharedArrayBuffer(size)
+      this.header = new Int32Array(this.buffer, 0, HEADER_INT_COUNT)
+      this.counters = new Int32Array(
+        this.buffer,
+        HEADER_BYTES,
+        COUNTERS_INT_COUNT,
+      )
+      this.rateLimits = new Int32Array(
+        this.buffer,
+        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 —
+      // 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)
+    }
+  }
+
+  /** Point every view at `buffer`, taking its size from the header it carries. */
+  bind(buffer: SharedArrayBuffer): void {
+    this.buffer = buffer
+    this.header = new Int32Array(this.buffer, 0, HEADER_INT_COUNT)
+    this.counters = new Int32Array(
+      this.buffer,
+      HEADER_BYTES,
+      COUNTERS_INT_COUNT,
+    )
+    this.rateLimits = new Int32Array(
+      this.buffer,
+      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 {
+    if (slot < 0 || slot >= COUNTERS_INT_COUNT) return 0
+    return Atomics.add(this.counters, slot, delta) + delta
+  }
+
+  decrementCounter(slot: number, delta = 1): number {
+    if (slot < 0 || slot >= COUNTERS_INT_COUNT) return 0
+    return Atomics.sub(this.counters, slot, delta) - delta
+  }
+
+  getCounter(slot: number): number {
+    if (slot < 0 || slot >= COUNTERS_INT_COUNT) return 0
+    return Atomics.load(this.counters, slot)
+  }
+
+  setCounter(slot: number, value: number): number {
+    if (slot < 0 || slot >= COUNTERS_INT_COUNT) return 0
+    return Atomics.store(this.counters, slot, value)
+  }
+
+  consumeToken(
+    slot: number,
+    maxTokens: number,
+    refillRatePerSec: number,
+    tokensRequested = 1,
+  ): boolean {
+    if (slot < 0 || slot >= RATE_LIMIT_SLOT_COUNT) return false
+    const tokenIndex = slot * 2
+    const timeIndex = slot * 2 + 1
+
+    const nowSec = Math.floor(Date.now() / 1000)
+
+    while (true) {
+      const currentTokens = Atomics.load(this.rateLimits, tokenIndex)
+      const lastTime = Atomics.load(this.rateLimits, timeIndex)
+
+      if (lastTime === 0 && currentTokens === 0) {
+        const initTokens = Math.max(0, maxTokens - tokensRequested)
+        if (
+          Atomics.compareExchange(this.rateLimits, timeIndex, 0, nowSec) === 0
+        ) {
+          Atomics.store(this.rateLimits, tokenIndex, initTokens)
+          return tokensRequested <= maxTokens
+        }
+        continue
+      }
+
+      let availableTokens = currentTokens
+      const elapsed = Math.max(0, nowSec - lastTime)
+      if (elapsed > 0) {
+        availableTokens = Math.min(
+          maxTokens,
+          currentTokens + elapsed * refillRatePerSec,
+        )
+      }
+
+      if (availableTokens < tokensRequested) {
+        if (elapsed > 0) {
+          Atomics.compareExchange(this.rateLimits, timeIndex, lastTime, nowSec)
+          Atomics.compareExchange(
+            this.rateLimits,
+            tokenIndex,
+            currentTokens,
+            availableTokens,
+          )
+        }
+        return false
+      }
+
+      const newTokens = availableTokens - tokensRequested
+      if (
+        Atomics.compareExchange(
+          this.rateLimits,
+          tokenIndex,
+          currentTokens,
+          newTokens,
+        ) === currentTokens
+      ) {
+        if (elapsed > 0) {
+          Atomics.compareExchange(this.rateLimits, timeIndex, lastTime, nowSec)
+        }
+        return true
+      }
+    }
+  }
+
+  allocateBuffer(length: number): { offset: number; view: Uint8Array } | null {
+    if (length <= 0) return null
+    const totalSize = Atomics.load(this.header, 1)
+    while (true) {
+      const currentOffset = Atomics.load(this.header, 2)
+      if (currentOffset + length > totalSize) {
+        return null
+      }
+      const newOffset = currentOffset + length
+      if (
+        Atomics.compareExchange(this.header, 2, currentOffset, newOffset) ===
+        currentOffset
+      ) {
+        return {
+          offset: currentOffset,
+          view: new Uint8Array(this.buffer, currentOffset, length),
+        }
+      }
+    }
+  }
+
+  getBufferView(offset: number, length: number): Uint8Array | null {
+    const totalSize = Atomics.load(this.header, 1)
+    if (offset < BUFFER_START_OFFSET || offset + length > totalSize) return null
+    return new Uint8Array(this.buffer, offset, length)
+  }
+}

package/tsconfig.app.json

@@ -0,0 +1,34 @@
+{
+  "$comment": [
+    "Base tsconfig for applications built on Bakery. Extend it:",
+    "  { \"extends\": \"@bakery-framework/core/tsconfig.app.json\" }",
+    "",
+    "The JSX settings are not optional. Bakery renders JSX server-side to a",
+    "string through its own `createElement`, so without these Bun falls back to",
+    "the automatic runtime and every .tsx page fails with",
+    "'Cannot find module react/jsx-dev-runtime'."
+  ],
+  "_files_note": "Paths in an extended config resolve relative to THIS file, so extending packages inherit core ambient declarations (createElement, Fragment, the JSX namespace, Bakery, AppConfig) without naming a node_modules path. shared.d.ts carries the handful of types the browser runtime needs too (MapOf, Wrapped, JsonResponse, ISFunction) and is declared there exactly once.",
+  "files": ["./src/global.d.ts", "./src/shared.d.ts", "./src/types.d.ts"],
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+    "types": ["bun-types"],
+
+    "jsx": "react",
+    "jsxFactory": "createElement",
+    "jsxFragmentFactory": "Fragment",
+
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}