@bakery-framework/core 1.0.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Kyle Cyrus Santos Obille
+
+The Software is provided subject to the standard MIT License, as detailed below, with the addition of the Commons Clause v1.0.
+
+The Commons Clause v1.0
+
+The Software is provided to you by the Licensor under the License, as defined below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights under the License will not include, and the License does not grant to you, the right to Sell the Software.
+
+For purposes of the foregoing, “Sell” means practicing any or all of the rights granted to you under the License to provide to third parties, for a fee or other consideration (including without limitation fees for hosting or consulting/support services related to the Software), a product or service whose value derives, entirely or substantially, from the functionality of the Software. Any license notice or attribution required by the License must also include this Commons Clause License Condition notice.
+
+Standard MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software (subject to the Commons Clause condition above), and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @bakery-framework/core
+
+The core of [Bakery](https://github.com/obillekyle/bakery): request handling,
+routing, sessions, caching and the server-side JSX runtime.
+
+**Bun only.** This package ships TypeScript source with no build step, and the
+runtime depends on Bun APIs throughout. It will not run on Node.
+
+```bash
+bun add @bakery-framework/core @bakery-framework/cli
+```
+
+`@bakery-framework/cli` owns the `bakery` binary that actually starts a server — core on
+its own is the library it starts.
+
+## Usage
+
+```ts
+// server.config.ts
+import { defineConfig } from '@bakery-framework/core'
+
+export default defineConfig({
+  root: 'src',
+  port: 3000,
+})
+```
+
+Every file under `root` is a route. A `.tsx` file is a page, a `.ts` file under
+`api/` is an endpoint:
+
+```ts
+// src/api/hello.ts
+import { defineRoute, response } from '@bakery-framework/core'
+
+export default defineRoute(async req => {
+  return response.json.success('ok', { method: req.method })
+})
+```
+
+## JSX setup
+
+Pages are rendered server-side through Bakery's own `createElement`, so an app's
+`tsconfig.json` must set the classic runtime **locally**:
+
+```json
+{
+  "extends": "@bakery-framework/core/tsconfig.app.json",
+  "compilerOptions": {
+    "jsx": "react",
+    "jsxFactory": "createElement",
+    "jsxFragmentFactory": "Fragment"
+  }
+}
+```
+
+`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
+perfectly happy, because it *does* follow the extends.
+
+The fastest way to get a correct setup is to let the scaffolder write one:
+
+```bash
+bun create bakery my-app
+```
+
+## Notes
+
+- No runtime dependencies.
+- An unconfigured app gets an on-by-default per-IP rate limit (100 burst,
+  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.
+
+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,
+
+**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
+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
+that check.
+modify and distribute freely; selling the software itself is not granted.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@bakery-framework/core",
+  "version": "1.0.0",
+  "description": "Bakery framework core: handlers, router, config, session, caches, logger, compiler.",
+  "keywords": [
+    "bakery",
+    "bun",
+    "framework",
+    "web-framework",
+    "server",
+    "http",
+    "router",
+    "ssr",
+    "jsx"
+  ],
+  "author": "obillekyle",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/obillekyle/bakery.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/obillekyle/bakery#readme",
+  "bugs": "https://github.com/obillekyle/bakery/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/core/index.ts",
+  "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",
+    "./cache/tiered": "./src/cache/tiered.ts",
+    "./compiler/tsconfig-sync": "./src/compiler/tsconfig-sync.ts",
+    "./core/plugins": "./src/core/plugins.ts",
+    "./core/config": "./src/core/config.ts",
+    "./core/init": "./src/core/init.ts",
+    "./core/port": "./src/core/port.ts",
+    "./router": "./src/router.ts",
+    "./utils/shared-pool": "./src/utils/shared-pool.ts",
+    "./global.d.ts": "./src/global.d.ts",
+    "./core/bakery": "./src/core/bakery.ts"
+  },
+  "files": [
+    "src",
+    "tsconfig.app.json",
+    "!src/**/*.test.ts",
+    "!src/tests"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/cache/index.ts

@@ -0,0 +1,8 @@
+import { Bakery } from '../core/bakery'
+export function initRoutes() {
+  for (const [, handlers] of Object.entries(Bakery.handlers)) {
+    for (const HandlerClass of handlers.list()) {
+      HandlerClass.initRoutes()
+    }
+  }
+}

package/src/cache/lru.ts

@@ -0,0 +1,41 @@
+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
+   * instance, otherwise leaks until the process exits.
+   */
+  private readonly onEvict?: (key: K, value: V) => void
+
+  constructor(
+    public readonly maxSize: number,
+    onEvict?: (key: K, value: V) => void,
+  ) {
+    super()
+    if (maxSize <= 0) throw new Error('LRUCache size must be greater than 0')
+    this.onEvict = onEvict
+  }
+
+  get(key: K): V | undefined {
+    const val = super.get(key)
+    // `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)
+    super.set(key, val as V)
+    return val
+  }
+
+  set(key: K, value: V): this {
+    if (super.has(key)) super.delete(key)
+    super.set(key, value)
+    if (this.size > this.maxSize) {
+      const first = this.keys().next().value
+      if (first !== undefined) {
+        const evicted = super.get(first!)
+        super.delete(first!)
+        if (evicted !== undefined) this.onEvict?.(first!, evicted)
+      }
+    }
+    return this
+  }
+}

package/src/cache/shared-db.ts

@@ -0,0 +1,51 @@
+import { Database } from 'bun:sqlite'
+import { dirname } from 'node:path'
+import { Bakery } from '../core/bakery'
+import { checkCacheVersion } from '../core/cache-version'
+import { fs } from '../utils'
+
+/**
+ * The tiered cache's spill-to-disk store — sessions and LRU overflow.
+ *
+ * Under `Bakery.cacheDir`, not `dataDir`, because every row in it is
+ * rebuildable: a session is a cookie plus whatever the app chose to hang off
+ * it, and the LRU tier re-fills from source on the next miss. It used to sit
+ * beside `server.db` in the data directory, which put a disposable file behind
+ * the one durability guarantee the framework makes.
+ *
+ * **The consequence is that sessions do not survive a framework upgrade.**
+ * `checkCacheVersion` wipes the whole cache directory on every version bump and
+ * every dev<->prod switch, and this file goes with it — users are logged out.
+ * That is intended: the alternative is a cache format from an older framework
+ * version being read by a newer one, which is exactly the failure the version
+ * wipe exists to prevent. Anything that must outlive an upgrade belongs in the
+ * app's own tables under `Bakery.dataDir`.
+ *
+ * **That was aspirational until 2026-08-09, and the `await` below is what makes
+ * it true.** The check ran from `initConfig()`, while this module opens the
+ * database at *import* time — so the process already held a handle inside the
+ * directory the wipe was about to delete. On Windows the delete failed with
+ * `EBUSY`, node's recursive walk stopped at the locked entry, and whatever it
+ * had not reached yet survived: sessions *did* outlive upgrades, and so did
+ * `html/`, the compiled-page cache. Awaiting the check here orders the two by
+ * construction — the cache cannot be opened before it has been validated —
+ * rather than by hoping one import happens after another.
+ */
+await checkCacheVersion()
+
+const dbFilePath = `${Bakery.cacheDir}/shared-cache.db`
+if (!fs.exists(dbFilePath)) await fs.mkdir(dirname(dbFilePath))
+
+export const cacheDb = new Database(dbFilePath, { create: true })
+const journalMode = process.platform === 'win32' ? 'DELETE' : 'WAL'
+cacheDb.run(`PRAGMA journal_mode = ${journalMode};`)
+cacheDb.run('PRAGMA synchronous = NORMAL;')
+cacheDb.run('PRAGMA temp_store = memory;')
+// `core/init.ts` installs THREAD_WORKER as an accessor holding a **boolean**,
+// so the string comparison this used to carry (`!== 'false'`) was always true
+// and the flag worked by accident. Read it through `import.meta.env`, which is
+// where every other mode flag is read from.
+const isWorker = Boolean(import.meta.env.THREAD_WORKER)
+cacheDb.run(`PRAGMA cache_size = ${isWorker ? -256 : -2000};`)
+cacheDb.run('PRAGMA busy_timeout = 5000;')
+cacheDb.run('PRAGMA mmap_size = 0;')

package/src/cache/string.ts

@@ -0,0 +1,150 @@
+import type { Statement } from 'bun:sqlite'
+import { db, type Milliseconds, registerCache } from './tiered'
+
+type StringEntry = { value: string; accessedAt: number }
+
+class StringCache {
+  private forwardMap = new Map<string, StringEntry>()
+  private reverseMap = new Map<string, string>()
+  private dirtyKeys = new Set<string>()
+  private flushTimer?: ReturnType<typeof setInterval>
+  private tableName: string
+  private stmt: Record<string, Statement>
+
+  constructor(tableId: string, flushIntervalMs?: Milliseconds) {
+    this.tableName = tableId.replace(/[^a-zA-Z0-9_]/g, '')
+
+    db.run(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        key TEXT PRIMARY KEY,
+        value TEXT UNIQUE,
+        accessedAt INTEGER
+      )
+    `)
+    db.run(
+      `CREATE INDEX IF NOT EXISTS idx_${this.tableName}_value ON ${this.tableName}(value)`,
+    )
+
+    // prettier-ignore
+    this.stmt = {
+      insert: db.prepare(
+        `INSERT OR REPLACE INTO ${this.tableName} (key, value, accessedAt) VALUES (?, ?, ?)`,
+      ),
+      delete: db.prepare(`DELETE FROM ${this.tableName} WHERE key = ?`),
+      byKey: db.prepare(
+        `SELECT value, accessedAt FROM ${this.tableName} WHERE key = ?`,
+      ),
+      byVal: db.prepare(
+        `SELECT key, accessedAt FROM ${this.tableName} WHERE value = ?`,
+      ),
+    }
+
+    if (flushIntervalMs !== undefined) {
+      this.flushTimer = setInterval(() => this.flushToDisk(), flushIntervalMs)
+    }
+
+    registerCache(this)
+  }
+
+  set(key: string, value: string): void {
+    const existingVal = this.forwardMap.get(key)?.value
+    const existingKey = this.reverseMap.get(value)
+
+    if (existingVal === value) {
+      // already mapped
+    } else if (existingKey !== undefined && existingKey !== key) {
+      throw new Error(
+        `Collision! Value '${value}' is already mapped to key '${existingKey}'`,
+      )
+    } else if (existingVal !== undefined && existingVal !== value) {
+      this.reverseMap.delete(existingVal)
+    }
+
+    const now = Date.now()
+    this.forwardMap.set(key, { value, accessedAt: now })
+    this.reverseMap.set(value, key)
+    this.dirtyKeys.add(key)
+  }
+
+  getValue(key: string): string | undefined {
+    if (this.forwardMap.has(key)) {
+      const entry = this.forwardMap.get(key)!
+      entry.accessedAt = Date.now()
+      return entry.value
+    }
+
+    const row = this.stmt.byKey.get(key) as StringEntry | null
+    if (!row) return undefined
+
+    this.forwardMap.set(key, { value: row.value, accessedAt: Date.now() })
+    this.reverseMap.set(row.value, key)
+    return row.value
+  }
+
+  getKey(value: string): string | undefined {
+    if (this.reverseMap.has(value)) {
+      const key = this.reverseMap.get(value)!
+      this.forwardMap.get(key)!.accessedAt = Date.now()
+      return key
+    }
+
+    const row = this.stmt.byVal.get(value) as {
+      key: string
+      accessedAt: number
+    } | null
+    if (!row) return undefined
+
+    this.forwardMap.set(row.key, { value, accessedAt: Date.now() })
+    this.reverseMap.set(value, row.key)
+    return row.key
+  }
+
+  deleteByKey(key: string): boolean {
+    const entry = this.forwardMap.get(key)
+
+    if (entry) {
+      this.reverseMap.delete(entry.value)
+      this.forwardMap.delete(key)
+    }
+
+    this.dirtyKeys.delete(key)
+    const info = this.stmt.delete.run(key)
+    return entry !== undefined || info.changes > 0
+  }
+
+  flushToDisk(): void {
+    if (this.dirtyKeys.size === 0) return
+    const keys = new Set(this.dirtyKeys)
+    this.dirtyKeys.clear()
+    db.transaction(() => {
+      for (const key of keys) {
+        const entry = this.forwardMap.get(key)
+        if (!entry) continue
+        this.stmt.insert.run(key, entry.value, entry.accessedAt)
+      }
+    })()
+  }
+
+  flushAllToDisk(): void {
+    if (this.forwardMap.size === 0) return
+    db.transaction(() => {
+      for (const [key, entry] of this.forwardMap) {
+        this.stmt.insert.run(key, entry.value, entry.accessedAt)
+      }
+      this.dirtyKeys.clear()
+    })()
+  }
+
+  close(): void {
+    clearInterval(this.flushTimer)
+    this.flushTimer = undefined
+    this.forwardMap.clear()
+    this.reverseMap.clear()
+  }
+
+  [Symbol.dispose](): void {
+    this.close()
+  }
+}
+
+export const Strings = new StringCache('string-cache', 30 * 60 * 1000)