@shaferllc/keel 0.83.0 → 0.83.2

package/llms-full.txt

@@ -1233,12 +1233,12 @@ app.register(RateLimitProvider, { max: 100 }); // parameterized, like a plugin
 The same provider class can be registered more than once with different options.
 Without options, `this.options` is an empty object.
 
-> Unlike Fastify plugins, Keel providers are **not encapsulated** — bindings,
-> decorators, and routes are registered into the one global container. That's a
-> deliberate simplification: there's a single, predictable scope, and no
-> plugin-boundary rules to reason about. For per-request behavior in the HTTP
-> pipeline (auth, logging, etc.), reach for [middleware](./middleware.md), which
-> *is* scoped to the routes you attach it to.
+> Keel providers are **not encapsulated** — bindings, decorators, and routes are
+> registered into the one global container. That's a deliberate simplification:
+> there's a single, predictable scope, and no plugin-boundary rules to reason
+> about. For per-request behavior in the HTTP pipeline (auth, logging, etc.),
+> reach for [middleware](./middleware.md), which *is* scoped to the routes you
+> attach it to.
 
 ## Generating a provider
 
@@ -3102,8 +3102,8 @@ and host (handy for building absolute links or forcing HTTPS).
 
 `all()` understands JSON and form bodies. For anything else — XML, CSV, a binary
 payload, a custom format — read the raw body and parse it yourself. There's no
-content-type parser registry to configure (unlike Fastify): parsing is explicit,
-so you call the accessor you want.
+content-type parser registry to configure: parsing is explicit, so you call the
+accessor you want.
 
 ```ts
 await request.text();          // the body as a string  (XML, CSV, …)
@@ -5559,10 +5559,9 @@ all gates/policies/hooks (a test helper).
 
 # Billing
 
-Keel Billing is a subscription-billing layer — a port of [Laravel
-Cashier](https://laravel.com/docs/13.x/billing) — for charging customers,
-managing subscriptions, and reconciling gateway state through webhooks. It ships
-as a Keel [package](./packages.md) and supports two gateways behind one API:
+Keel Billing is a subscription-billing layer for charging customers, managing
+subscriptions, and reconciling gateway state through webhooks. It ships as a
+Keel [package](./packages.md) and supports two gateways behind one API:
 **Stripe** and **Paddle**.
 
 It attaches to a model with a mixin. Your `User` becomes billable, gains a
@@ -5765,6 +5764,46 @@ resolveBillableUsing(async (customerId) => {
 });
 ```
 
+## A complete flow
+
+From "user signs up" to "they're subscribed", with the fake gateway for tests:
+
+```ts
+import { Model } from "@shaferllc/keel/core";
+import {
+  Billable,
+  BillingManager,
+  FakeGateway,
+  setBilling,
+} from "@shaferllc/keel/billing";
+
+class User extends Billable(Model) {
+  static table = "users";
+  declare email: string;
+}
+
+// In a test bootstrap:
+const fake = new FakeGateway();
+const manager = new BillingManager({
+  default: "fake",
+  currency: "usd",
+  billableModel: "User",
+  webhook: { path: "billing/webhook" },
+  gateways: { stripe: { key: "", webhookSecret: "" }, paddle: { key: "", webhookSecret: "" }, fake: {} },
+});
+manager.register("fake", () => fake);
+setBilling(manager);
+
+const user = await User.create({ email: "ada@example.com" });
+await user.newSubscription("default", "price_pro").trialDays(14).create();
+
+await user.subscribed(); // true
+fake.calls.some((c) => c.method === "createSubscription"); // true
+```
+
+In production you skip the fake manager — `BillingServiceProvider` wires the
+real gateway from `config/billing.ts` and `.env`.
+
 ## Gateway differences
 
 | Concern | Stripe | Paddle |
@@ -5780,8 +5819,8 @@ resolveBillableUsing(async (customerId) => {
 The migration is gateway-neutral: `subscriptions` (with `gateway`,
 `provider_id`, `provider_status`, `provider_price`, trial/grace timestamps),
 `subscription_items`, and columns on `users` (`billing_gateway`,
-`billing_customer_id`, `pm_type`, `pm_last_four`, `trial_ends_at`). Cashier
-targets the standard `users` billable table.
+`billing_customer_id`, `pm_type`, `pm_last_four`, `trial_ends_at`). The default
+migration targets the standard `users` billable table.
 
 ## Testing
 
@@ -7612,6 +7651,34 @@ router.group(() => { /* … */ }).use(cors({ origin: ["https://app.example.com"]
 With no options, `cors()` reflects the caller's origin — convenient in
 development. **Lock it down in production** with an explicit allowlist.
 
+## A production API group
+
+Typical setup for a JSON API served from `api.example.com` and called from a
+SPA on `app.example.com`:
+
+```ts
+// app/Http/Kernel.ts
+import { cors } from "@shaferllc/keel/core";
+
+this.use(
+  cors({
+    origin: ["https://app.example.com"],
+    credentials: true,          // cookies / Authorization
+    exposeHeaders: ["X-Request-Id"],
+  }),
+);
+```
+
+During local development, allow any localhost port with a predicate:
+
+```ts
+cors({
+  origin: (origin) =>
+    origin.startsWith("http://localhost:") || origin === "https://app.example.com",
+  credentials: true,
+});
+```
+
 ## Options
 
 ```ts
@@ -8162,10 +8229,9 @@ arguments still halts the request and renders an empty page.
 
 Attach named, computed values to the current request — `request.user`,
 `request.tenant`, `request.locale` — resolved **lazily** and **memoized for the
-life of the request**. Inspired by [Fastify's decorators](https://fastify.dev/docs/latest/Reference/Decorators/),
-but without the footguns: you register a resolver once, and Keel computes it on
+life of the request**. You register a resolver once, and Keel computes it on
 first access and caches it per request. No null-placeholder declaration, no
-`onRequest` hook to remember, no shared-state leak between requests.
+shared-state leak between requests.
 
 > Decorating the **application** is already the [service container's](./container.md)
 > job — `bind` / `singleton` / `instance` / `make`, with `bound()` as
@@ -8213,9 +8279,6 @@ setRequestValue("user", theAuthenticatedUser);
 const user = await decorated("user"); // returns the value set above, no re-lookup
 ```
 
-This is the clean version of Fastify's "declare a placeholder, set it in an
-`onRequest` hook" pattern.
-
 ## Why lazy + memoized
 
 Resolving the current user (or tenant, or locale, or a feature-flag set) is the
@@ -8479,7 +8542,7 @@ subclasses don't define either — they render through the default path.
 
 When all you want is a coded error class — a stable `code`, a message, a status —
 skip the boilerplate and mint one with `createError`. It's the ergonomic shortcut
-for the common case, inspired by Fastify's `@fastify/error`:
+for the common case:
 
 ```ts
 import { createError } from "@shaferllc/keel/core";
@@ -10418,9 +10481,7 @@ implementing anything — the same `fetch` handler just gets served over it.
 # Lifecycle Hooks
 
 Tap into the **application lifecycle** — run code once the app is ready, clean up
-on shutdown, and observe route registration. Inspired by
-[Fastify's hooks](https://fastify.dev/docs/latest/Reference/Hooks/), scoped to the
-parts Keel doesn't already cover.
+on shutdown, and observe route registration.
 
 > **Request-lifecycle hooks** (before/after a request, on error) are
 > [middleware](./middleware.md) in Keel — `HttpKernel.use()`, route/group
@@ -11585,8 +11646,8 @@ With no options it defaults to `level: "info"`, `pretty: false`, and no bindings
 
 `requestLogger()` is a built-in middleware that binds a **child logger with a
 generated `reqId` to each request**, so every log line within a request
-correlates — Fastify's `request.log`. Install it in your HTTP kernel, then reach
-the request's logger anywhere with `requestLog()`:
+correlates. Install it in your HTTP kernel, then reach the request's logger
+anywhere with `requestLog()`:
 
 ```ts
 import { requestLogger, requestLog } from "@shaferllc/keel/core";
@@ -14941,6 +15002,44 @@ query shapes without an ORM dependency. For a gnarly one-off report, reach for
 the [query builder](./query-builder.md) or a raw `connection().select(sql)`; the
 model layer never gets in the way.
 
+## A worked example
+
+A blog with authors and posts — enough to see CRUD, a relation, and eager loading
+together:
+
+```ts
+import { Model } from "@shaferllc/keel/core";
+
+class Post extends Model {
+  static table = "posts";
+  static fillable = ["title", "body"];
+  declare id: number;
+  declare title: string;
+  declare user_id: number;
+
+  author() { return this.belongsTo(User); }
+}
+
+class User extends Model {
+  static table = "users";
+  declare id: number;
+  declare email: string;
+
+  posts() { return this.hasMany(Post); }
+}
+
+const ada = await User.create({ email: "ada@example.com" });
+await ada.posts().create({ title: "Notes on engines", body: "…" });
+
+const withPosts = await User.with("posts").where("id", ada.id).first();
+for (const post of (withPosts as User & { posts: Post[] }).posts) {
+  console.log(post.title);
+}
+```
+
+For the full surface — casts, soft deletes, scopes, polymorphic relations —
+see [Models](./models.md).
+
 
 
 ---
@@ -14956,9 +15055,9 @@ adds the conventions a *shippable* package needs so it can carry its own schema
 and assets instead of asking the app to wire them by hand.
 
 [Keel Watch](./watch.md) — the debug dashboard — is a first-party package and the
-reference implementation of everything below. [Billing](./billing.md) (a Cashier
-port for Stripe and Paddle) is another, and shows a package contributing models,
-a schema migration, gateway drivers, and verified webhook routes.
+reference implementation of everything below. [Billing](./billing.md) (Stripe and
+Paddle subscriptions) is another, and shows a package contributing models, a
+schema migration, gateway drivers, and verified webhook routes.
 
 ## The shape of a package
 
@@ -17637,6 +17736,20 @@ to finish.
 | `app` *(default)* | Full-stack: views, sessions, register/login, password reset, two-factor. |
 | `saas` | `app` plus teams, roles, invitations, billing, and multi-tenancy. |
 
+## Pick a kit
+
+```bash
+npm create keeljs@latest my-app                 # app (default)
+npm create keeljs@latest my-api  -- --preset api
+npm create keeljs@latest my-saas -- --preset saas
+npm create keeljs@latest bare    -- --preset minimal
+cd my-app && npm install && npm run dev
+```
+
+Then open `http://localhost:3000`. The SaaS kit already has a team switcher,
+invites, and a billing stub wired through [teams](./teams.md) and
+[billing](./billing.md) — start by editing `app/Models` and `routes/web.ts`.
+
 ## Every database, Cloudflare first
 
 Each kit ships with all four drivers wired. Switching is `DB_CONNECTION` and nothing
@@ -19171,8 +19284,7 @@ construct it directly.
 
 Test your app by **injecting requests** — no server, no port, no network — and
 asserting on the response. `testClient()` wraps your app's Hono instance (which
-already does fetch-style injection) with verb helpers and fluent assertions, the
-way Fastify's `inject()` works.
+already does fetch-style injection) with verb helpers and fluent assertions.
 
 ## The client
 
@@ -20355,8 +20467,7 @@ router.get("/posts/:id", [Posts, "show"]).middleware([
 
 `validated(part)` returns the parsed, typed value for that part (defaults to
 `"body"`). Coercion (`z.coerce.number()`) is the schema's job — it applies before
-your handler sees the value. This is the declarative counterpart to Fastify's
-route schemas, on top of the same `validate()` engine.
+your handler sees the value. Built on the same `validate()` engine.
 
 ## Body parsing is JSON-only
 
@@ -21253,7 +21364,7 @@ Vite's `manifest.json`, as produced by the build. You rarely touch it directly
 
 # Watch
 
-Keel Watch is a debug dashboard — a Telescope for Keel. It records the requests,
+Keel Watch is a debug dashboard for Keel apps. It records the requests,
 queries, exceptions, logs, jobs, mail, notifications, cache lookups, events, and
 scheduled tasks flowing through your app, and shows them in a single-page UI at
 `/watch`, with every request linked to the queries and logs it produced.

package/llms.txt

@@ -15,7 +15,7 @@ Userland imports everything from `@shaferllc/keel/core`.
 - [Architecture](https://github.com/shaferllc/keel/blob/main/docs/architecture.md): Keel is small on purpose. This page maps the pieces and traces a request from socket to response. Nothing here is magic — every layer is a short, readable file in src/core/, and this guide is mostly a reading order for it.
 - [Authentication](https://github.com/shaferllc/keel/blob/main/docs/authentication.md): Session-based auth built on the pieces you already have: sessions hold the login, hashing checks passwords.
 - [Authorization](https://github.com/shaferllc/keel/blob/main/docs/authorization.md): Where authentication answers who you are, authorization answers what you're allowed to do.
-- [Billing](https://github.com/shaferllc/keel/blob/main/docs/billing.md): Keel Billing is a subscription-billing layer — a port of Laravel Cashier — for charging customers, managing subscriptions, and reconciling gateway state through webhooks.
+- [Billing](https://github.com/shaferllc/keel/blob/main/docs/billing.md): Keel Billing is a subscription-billing layer for charging customers, managing subscriptions, and reconciling gateway state through webhooks.
 - [Broadcasting](https://github.com/shaferllc/keel/blob/main/docs/broadcasting.md): Push events to clients in real time over named channels.
 - [Service Broker](https://github.com/shaferllc/keel/blob/main/docs/broker.md): Structure an application as services that talk to each other by name instead of by import.
 - [Cache](https://github.com/shaferllc/keel/blob/main/docs/cache.md): A small cache with TTLs and the remember pattern.
@@ -72,7 +72,7 @@ Userland imports everything from `@shaferllc/keel/core`.
 - [Validation](https://github.com/shaferllc/keel/blob/main/docs/validation.md): validate() parses request input against a schema and returns typed data.
 - [Views](https://github.com/shaferllc/keel/blob/main/docs/views.md): Keel renders HTML with Hono JSX — type-safe components that run identically on Node and on Cloudflare Workers (no filesystem templating, so it ports anywhere).
 - [Vite](https://github.com/shaferllc/keel/blob/main/docs/vite.md): Wire a modern frontend build — bundling, hashed filenames, hot module reload — to Keel's server-rendered HTML, the way modern full-stack frameworks do.
-- [Watch](https://github.com/shaferllc/keel/blob/main/docs/watch.md): Keel Watch is a debug dashboard — a Telescope for Keel.
+- [Watch](https://github.com/shaferllc/keel/blob/main/docs/watch.md): Keel Watch is a debug dashboard for Keel apps.
 
 ## Examples
 
@@ -82,6 +82,7 @@ Every topic has a runnable, type-checked example:
 - [API Resources example](https://github.com/shaferllc/keel/blob/main/docs/examples/api-resources.ts)
 - [Authentication example](https://github.com/shaferllc/keel/blob/main/docs/examples/authentication.ts)
 - [Authorization example](https://github.com/shaferllc/keel/blob/main/docs/examples/authorization.ts)
+- [Billing example](https://github.com/shaferllc/keel/blob/main/docs/examples/billing.ts)
 - [Broadcasting example](https://github.com/shaferllc/keel/blob/main/docs/examples/broadcasting.ts)
 - [Service Broker example](https://github.com/shaferllc/keel/blob/main/docs/examples/broker.ts)
 - [Cache example](https://github.com/shaferllc/keel/blob/main/docs/examples/cache.ts)
@@ -89,6 +90,7 @@ Every topic has a runnable, type-checked example:
 - [The Console example](https://github.com/shaferllc/keel/blob/main/docs/examples/console.ts)
 - [The Service Container example](https://github.com/shaferllc/keel/blob/main/docs/examples/container.ts)
 - [Controllers example](https://github.com/shaferllc/keel/blob/main/docs/examples/controllers.ts)
+- [CORS example](https://github.com/shaferllc/keel/blob/main/docs/examples/cors.ts)
 - [Database example](https://github.com/shaferllc/keel/blob/main/docs/examples/database.ts)
 - [Debugging example](https://github.com/shaferllc/keel/blob/main/docs/examples/debugging.ts)
 - [Request Decorators example](https://github.com/shaferllc/keel/blob/main/docs/examples/decorators.ts)
@@ -98,6 +100,7 @@ Every topic has a runnable, type-checked example:
 - [Hashing & Encryption example](https://github.com/shaferllc/keel/blob/main/docs/examples/hashing.ts)
 - [Health Checks example](https://github.com/shaferllc/keel/blob/main/docs/examples/health.ts)
 - [Helpers example](https://github.com/shaferllc/keel/blob/main/docs/examples/helpers.ts)
+- [Built on Hono example](https://github.com/shaferllc/keel/blob/main/docs/examples/hono.ts)
 - [Lifecycle Hooks example](https://github.com/shaferllc/keel/blob/main/docs/examples/hooks.ts)
 - [Internationalization example](https://github.com/shaferllc/keel/blob/main/docs/examples/i18n.ts)
 - [Inertia example](https://github.com/shaferllc/keel/blob/main/docs/examples/inertia.ts)
@@ -108,15 +111,22 @@ Every topic has a runnable, type-checked example:
 - [Migrations example](https://github.com/shaferllc/keel/blob/main/docs/examples/migrations.ts)
 - [Models example](https://github.com/shaferllc/keel/blob/main/docs/examples/models.ts)
 - [Notifications example](https://github.com/shaferllc/keel/blob/main/docs/examples/notification.ts)
+- [OpenAPI example](https://github.com/shaferllc/keel/blob/main/docs/examples/openapi.ts)
+- [ORM example](https://github.com/shaferllc/keel/blob/main/docs/examples/orm.ts)
+- [Packages example](https://github.com/shaferllc/keel/blob/main/docs/examples/packages.ts)
 - [Pages example](https://github.com/shaferllc/keel/blob/main/docs/examples/pages.ts)
 - [Service Providers example](https://github.com/shaferllc/keel/blob/main/docs/examples/providers.ts)
+- [Query Builder example](https://github.com/shaferllc/keel/blob/main/docs/examples/query-builder.ts)
 - [Queues & Jobs example](https://github.com/shaferllc/keel/blob/main/docs/examples/queues.ts)
 - [Rate Limiting example](https://github.com/shaferllc/keel/blob/main/docs/examples/rate-limiting.ts)
 - [Redis example](https://github.com/shaferllc/keel/blob/main/docs/examples/redis.ts)
 - [Request & Response example](https://github.com/shaferllc/keel/blob/main/docs/examples/request-response.ts)
 - [Routing example](https://github.com/shaferllc/keel/blob/main/docs/examples/routing.ts)
 - [Task Scheduling example](https://github.com/shaferllc/keel/blob/main/docs/examples/scheduling.ts)
+- [Securing SSR apps example](https://github.com/shaferllc/keel/blob/main/docs/examples/security.ts)
 - [Sessions example](https://github.com/shaferllc/keel/blob/main/docs/examples/sessions.ts)
+- [Social authentication example](https://github.com/shaferllc/keel/blob/main/docs/examples/social-auth.ts)
+- [Starter kits example](https://github.com/shaferllc/keel/blob/main/docs/examples/starter-kits.ts)
 - [Static Files example](https://github.com/shaferllc/keel/blob/main/docs/examples/static-files.ts)
 - [Storage example](https://github.com/shaferllc/keel/blob/main/docs/examples/storage.ts)
 - [Teams example](https://github.com/shaferllc/keel/blob/main/docs/examples/teams.ts)
@@ -128,6 +138,7 @@ Every topic has a runnable, type-checked example:
 - [Validation example](https://github.com/shaferllc/keel/blob/main/docs/examples/validation.ts)
 - [Views example](https://github.com/shaferllc/keel/blob/main/docs/examples/views.tsx)
 - [Vite example](https://github.com/shaferllc/keel/blob/main/docs/examples/vite.ts)
+- [Watch example](https://github.com/shaferllc/keel/blob/main/docs/examples/watch.ts)
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.83.0",
+  "version": "0.83.2",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",