@shaferllc/keel 0.66.0 → 0.74.0

package/docs/pages.md

@@ -0,0 +1,217 @@
+# Pages
+
+Page-based routing — **a file is a route**.
+
+```
+resources/pages/index.tsx           →  /
+resources/pages/about.tsx           →  /about
+resources/pages/users/index.tsx     →  /users
+resources/pages/users/[id].tsx      →  /users/:id
+resources/pages/docs/[...slug].tsx  →  /docs/*   (catch-all)
+```
+
+```tsx
+// resources/pages/users/[id].tsx
+import { db, type Ctx, type PageProps } from "@shaferllc/keel/core";
+
+export const loader = (c: Ctx) => db("users").where("id", c.req.param("id")).first();
+
+export default function UserPage({ params, data }: PageProps<{ id: string }, User>) {
+  return (
+    <Layout>
+      <h1>{data.name}</h1>
+      <p>User #{params.id}</p>
+    </Layout>
+  );
+}
+```
+
+That's the whole page. No route file to keep in sync, no controller, no wiring.
+
+## It doesn't replace the router — it drives it
+
+Every page becomes an **ordinary named route**. `url()` finds it, route middleware
+applies to it, and `keel routes` lists it. You can mix pages and hand-written
+routes freely, and reach for a controller the moment a page outgrows a file.
+
+That matters, because file-based routing is a lovely default and a bad prison.
+Here it's a *convenience over* the router, not a replacement for it.
+
+## Registering them
+
+In a service provider's `boot()`:
+
+```ts
+import { pages } from "@shaferllc/keel/core";
+
+export class PageServiceProvider extends ServiceProvider {
+  async boot(): Promise<void> {
+    await pages(); // scans resources/pages
+  }
+}
+```
+
+`pages()` reads the filesystem, so it's **Node-only**. On the edge, hand
+`definePages()` a build-time manifest instead — Vite's `import.meta.glob` produces
+exactly the map it wants:
+
+```ts
+definePages(import.meta.glob("./pages/**/*.tsx", { eager: true }));
+```
+
+Same behavior, no filesystem.
+
+## The file conventions
+
+| File | URL |
+|------|-----|
+| `index.tsx` | `/` |
+| `about.tsx` | `/about` |
+| `users/index.tsx` | `/users` |
+| `users/[id].tsx` | `/users/:id` |
+| `users/[id]/edit.tsx` | `/users/:id/edit` |
+| `teams/[team]/users/[id].tsx` | `/teams/:team/users/:id` |
+| `docs/[...slug].tsx` | `/docs/*` — a catch-all; `params.slug` is the whole rest |
+| `_layout.tsx` | **not a route** — a leading `_` keeps a file private |
+
+A trailing `index` names its directory rather than a child of it. A leading
+underscore is how layouts, partials, and helpers live *beside* your pages without
+becoming URLs.
+
+## Specificity is decided for you
+
+This is the part file-based routing usually gets wrong:
+
+```
+users/[id].tsx      →  /users/:id
+users/new.tsx       →  /users/new
+```
+
+Register `:id` first and `/users/new` is **unreachable forever** — `:id` happily
+matches `"new"`. Whether your app works would come down to the order the
+filesystem happened to hand back.
+
+So pages are **sorted before they're registered**: literal segments beat
+parameters, parameters beat catch-alls, and a catch-all is always the last resort.
+`/users/new` wins, and the file layout stops being a trap.
+
+## Loading data
+
+`loader` runs before the page renders; whatever it returns arrives as `data`.
+
+```tsx
+export const loader = async (c: Ctx) => {
+  const post = await db("posts").where("slug", c.req.param("slug")).first();
+  if (!post) throw new NotFoundException();
+  return post;
+};
+
+export default function PostPage({ data }: PageProps<{ slug: string }, Post>) {
+  return <article>{data.body}</article>;
+}
+```
+
+It takes the request context, so it can read params, query, headers, or the
+session. A page with no `loader` simply gets `data: undefined`.
+
+## Middleware
+
+Per page:
+
+```tsx
+export const middleware = [authGuard()];
+```
+
+Or for every page at once:
+
+```ts
+await pages({ middleware: [authGuard()] });
+```
+
+Both run before the `loader`, so a page that's refused never loads its data.
+
+## Names and URLs
+
+Each page gets a route name derived from its path — `users/[id].tsx` becomes
+`users.id` — so URL generation works without you naming anything:
+
+```ts
+router.url("users.id", { id: 5 }); // "/users/5"
+```
+
+Override it when the derived name is ugly:
+
+```tsx
+export const name = "users.show";
+```
+
+## Escape hatches
+
+Move a page's URL without moving the file:
+
+```tsx
+export const path = "/pricing"; // even though the file is at marketing/plans.tsx
+```
+
+Mount every page under a prefix:
+
+```ts
+await pages({ prefix: "/app" }); // index.tsx is now /app
+await pages({ dir: "app/pages" }); // ...or keep them somewhere else
+```
+
+---
+
+## API reference
+
+### `pages(options?)`
+
+`pages(options?: PagesOptions): Promise<RegisteredPage[]>`
+
+Scan a directory and register every page in it. **Node only** — it reads the
+filesystem (`node:fs` is imported dynamically, so the core still loads on the
+edge).
+
+### `definePages(modules, options?)`
+
+`definePages(modules: Record<string, PageModule>, options?: PagesOptions): RegisteredPage[]`
+
+Register pages from a `file path → module` map. The edge-safe half — pair it with
+`import.meta.glob`.
+
+### `PagesOptions`
+
+| Option | Meaning |
+|--------|---------|
+| `dir` | Where the pages live. Default `"resources/pages"` |
+| `prefix` | Prefix every page's URL |
+| `middleware` | Middleware applied to every page |
+| `router` | The router to register on. Defaults to the application's |
+
+### `PageModule`
+
+What a page file exports.
+
+| Export | Meaning |
+|--------|---------|
+| `default` | **Required.** The component. May be async |
+| `loader` | `(ctx) => data` — runs before the page renders |
+| `middleware` | Middleware for this page alone |
+| `name` | The route name. Defaults to one derived from the path |
+| `path` | Override the URL entirely |
+
+### `PageProps<P, D>`
+
+What the component receives: `params` (typed by `P`), `data` (whatever `loader`
+returned, typed by `D`), and `ctx`.
+
+### `RegisteredPage`
+
+`{ file, pattern, name }` — what `pages()` / `definePages()` return, so you can
+see exactly what got mounted.
+
+### `routePattern(file)` / `routeName(file)`
+
+The two pure functions behind the conventions, exported so you can test or reuse
+them. `routePattern("users/[id].tsx")` → `"/users/:id"`;
+`routeName("users/[id].tsx")` → `"users.id"`.

package/docs/providers.md

@@ -0,0 +1,363 @@
+# Service Providers
+
+Service providers are the central place to configure your application. Nearly
+everything Keel boots — config, routing, your own services — is wired up in a
+provider.
+
+## The lifecycle
+
+A provider has four hooks, run across the application's lifecycle. Only
+`register()` and `boot()` are needed day-to-day; `ready()` and `shutdown()` are
+there for work that must happen once the whole app is live, or as it stops:
+
+```ts
+import { ServiceProvider } from "@shaferllc/keel/core";
+
+export class AppServiceProvider extends ServiceProvider {
+  register(): void {
+    // Phase 1. Bind things into the container.
+    // Do NOT resolve other services here — nothing is guaranteed
+    // to be registered yet.
+  }
+
+  boot(): void {
+    // Phase 2. Runs after EVERY provider has registered.
+    // Safe to resolve services and wire them together.
+  }
+
+  ready(): void {
+    // Phase 3. Runs after every provider has booted and the app is fully up.
+    // For work that needs a live app — warm a cache, attach to the server.
+  }
+
+  shutdown(): void {
+    // Phase 4. Runs on graceful termination, in reverse registration order.
+    // Close connections, flush queues, cancel timers.
+  }
+}
+```
+
+The `Application` runs **all** `register()` methods first, then **all** `boot()`
+methods, then **all** `ready()` methods — that ordering is what lets providers
+depend on each other without worrying about load order. On `app.terminate()`
+(wired to SIGINT/SIGTERM by `keel serve`), every `shutdown()` runs in **reverse**
+registration order (LIFO), so a provider tears down before the ones it depended
+on. All four hooks may be `async` — the application awaits them. `ready()` and
+`shutdown()` are optional and map onto the app's `onReady()` / `onShutdown()`
+hooks, so a provider's `shutdown()` runs alongside any it registered by hand.
+
+## The `app` reference
+
+Every provider is handed the `Application` at construction and holds it as
+`this.app` (a `protected` field). The `Application` **is** the service container,
+so `this.app` gives you `bind`, `singleton`, `instance`, `make`, and `bound`
+directly, plus the framework accessors `config()`, `router()`, and `view()`:
+
+```ts
+import { ServiceProvider } from "@shaferllc/keel/core";
+import { SearchIndex } from "../Services/SearchIndex.js";
+
+export class SearchServiceProvider extends ServiceProvider {
+  register(): void {
+    this.app.singleton("search", () => new SearchIndex());
+  }
+
+  boot(): void {
+    const debug = this.app.config().get("app.debug", false);
+    this.app.router().get("/health", () => "ok");
+  }
+}
+```
+
+You never construct a provider yourself — the `Application` does it for you when
+you register the class. It calls `new Provider(app)`, so `this.app` is always the
+live application instance.
+
+## Registering a provider
+
+Add your provider class to `bootstrap/providers.ts`:
+
+```ts
+import type { ProviderClass } from "@shaferllc/keel/core";
+import { AppServiceProvider } from "../app/Providers/AppServiceProvider.js";
+import { BillingServiceProvider } from "../app/Providers/BillingServiceProvider.js";
+
+export const providers: ProviderClass[] = [
+  AppServiceProvider,
+  BillingServiceProvider,
+];
+```
+
+Providers boot in array order. Under the hood, `app.boot(providers)` calls
+`app.register(Provider)` for each class — which does `new Provider(app)` and
+stashes the instance — then runs the two phases across the whole set.
+
+## Providers are Keel's plugin system
+
+A service provider is Keel's answer to a **plugin**: a self-contained slice of
+functionality you register into the app. To make one **reusable**, register it
+with **options** — they arrive as `this.options`, typed via the generic:
+
+```ts
+class RateLimitProvider extends ServiceProvider<{ max: number }> {
+  boot() {
+    this.app.make(HttpKernel).use(rateLimiter({ max: this.options.max }));
+  }
+}
+
+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.
+
+## Generating a provider
+
+```bash
+npm run keel make:provider Billing
+```
+
+Writes `app/Providers/BillingServiceProvider.ts`. Remember to add it to
+`bootstrap/providers.ts`.
+
+## A realistic example
+
+```ts
+import { ServiceProvider, Config } from "@shaferllc/keel/core";
+import { StripeClient } from "../Services/StripeClient.js";
+
+export class BillingServiceProvider extends ServiceProvider {
+  register(): void {
+    this.app.singleton(StripeClient, (app) => {
+      const key = app.make(Config).get<string>("services.stripe.key");
+      return new StripeClient(key);
+    });
+  }
+
+  boot(): void {
+    // e.g. register webhooks, warm a cache, etc.
+  }
+}
+```
+
+Now any controller or service can `this.app.make(StripeClient)` and get the same
+configured instance.
+
+## Async providers
+
+Both phases may return a promise, and the application `await`s each one before
+moving on. Reach for this when a binding needs to open a connection or fetch a
+remote manifest:
+
+```ts
+import { ServiceProvider } from "@shaferllc/keel/core";
+import { SearchClient } from "../Services/SearchClient.js";
+
+export class SearchServiceProvider extends ServiceProvider {
+  async register(): Promise<void> {
+    const client = await SearchClient.connect(process.env.SEARCH_URL!);
+    this.app.instance(SearchClient, client);
+  }
+
+  async boot(): Promise<void> {
+    await this.app.make(SearchClient).warm();
+  }
+}
+```
+
+Because every `register()` is awaited before any `boot()` runs, an async
+`register()` in one provider still completes before another provider's `boot()`
+tries to resolve what it bound.
+
+## Error behavior
+
+`register()` and `boot()` run inside `app.boot()`, which awaits each call in
+sequence. If any provider throws (or rejects), `app.boot()` rejects and the
+remaining providers never run — so a bad binding fails the whole boot loudly
+rather than leaving a half-wired container. Booting is also idempotent: once
+`app.boot()` has completed, calling it again returns immediately without
+re-running any provider.
+
+## Rules of thumb
+
+- **`register()` binds. `boot()` uses.** Resolving a service in `register()` is
+  the most common mistake — the thing you need may not be bound yet.
+- **Keep providers focused.** One provider per concern (billing, auth, search)
+  reads better than one giant `AppServiceProvider`.
+- **Order matters only for `boot()` side effects**, since all registration
+  happens before any booting.
+
+## Related
+
+Providers wire services into the [container](./container.md); the
+[Application](./architecture.md) kernel constructs and boots them. See
+[configuration](./configuration.md) for what `this.app.config()` reads.
+
+---
+
+## API reference
+
+### `ServiceProvider`
+
+The abstract base class every provider extends. You never instantiate it
+directly — you subclass it and register the subclass (via `bootstrap/providers.ts`
+or `app.register()`), and the `Application` constructs it for you. Override
+`register()` and/or `boot()`; both are no-ops by default.
+
+```ts
+import { ServiceProvider } from "@shaferllc/keel/core";
+
+export class AppServiceProvider extends ServiceProvider {
+  register(): void {
+    this.app.bind("clock", () => new Date().toISOString());
+  }
+}
+```
+
+**Notes:** `abstract`, so it can't be `new`ed on its own. A subclass needn't
+override both methods — leave one off to inherit the empty default.
+
+#### `constructor(app, options?)`
+
+`constructor(app: Application, options?: O)` (on `ServiceProvider<O>`)
+
+Receives the live `Application` (stored as `protected this.app`) and the options
+passed to `register` (stored as `protected this.options`, `{}` if none). The
+`Application` invokes this for you; you don't call it.
+
+```ts
+class RateLimitProvider extends ServiceProvider<{ max: number }> {
+  boot() {
+    this.app.make(HttpKernel).use(rateLimiter({ max: this.options.max }));
+  }
+}
+app.register(RateLimitProvider, { max: 100 });
+```
+
+**Notes:** `app` and `options` are `protected` — reachable from subclass methods,
+not from outside. Type the options via the class generic `ServiceProvider<O>`.
+
+#### `app.register(Provider, options?)`
+
+`register(Provider: ProviderClass, options?: unknown): this`
+
+Registers a provider, optionally with options handed to its constructor. Chainable.
+`app.boot([Providers])` registers each without options.
+
+#### `register()`
+
+`register(): void | Promise<void>`
+
+Phase-one hook: bind services into the container. Called for every provider
+before any `boot()` runs. Default implementation is empty.
+
+```ts
+register(): void {
+  this.app.singleton(StripeClient, (app) =>
+    new StripeClient(app.make(Config).get<string>("services.stripe.key")),
+  );
+}
+```
+
+**Notes:** do **not** resolve other services here — another provider may not have
+bound them yet. May be `async`; the application awaits it. Throwing rejects
+`app.boot()`.
+
+#### `boot()`
+
+`boot(): void | Promise<void>`
+
+Phase-two hook: runs after **every** provider has registered, so it's safe to
+resolve services and wire them together. Default implementation is empty.
+
+```ts
+async boot(): Promise<void> {
+  await this.app.make(SearchClient).warm();
+}
+```
+
+**Notes:** providers boot in registration (array) order — the only place order
+matters, since all `register()` calls finish first. May be `async`; the
+application awaits it. Throwing rejects `app.boot()`.
+
+#### `ready()`
+
+`ready(): void | Promise<void>`
+
+Phase-three hook: runs after **every** provider has booted and the app is fully
+up (after the app's own `onReady` hooks). For work that needs a live app —
+warming a cache, attaching to the running server. Default implementation is
+empty.
+
+```ts
+async ready(): Promise<void> {
+  await this.app.make(Cache).warm(["home", "pricing"]);
+}
+```
+
+**Notes:** runs in registration order, once, at the end of `app.boot()`. Optional
+— omit it and nothing runs. May be `async`; the application awaits it.
+
+#### `shutdown()`
+
+`shutdown(): void | Promise<void>`
+
+Cleanup hook: runs on `app.terminate()` (which `keel serve` wires to SIGINT and
+SIGTERM) in **reverse** registration order. Close database/Redis connections,
+flush logs, cancel timers. Default implementation is empty.
+
+```ts
+async shutdown(): Promise<void> {
+  await this.app.make(Redis).quit();
+}
+```
+
+**Notes:** LIFO — the last provider registered shuts down first, so a provider
+tears down before the ones it depends on. It joins the app's `onShutdown` hooks,
+so a hook a provider registered by hand and its `shutdown()` both run. A throw
+doesn't stop the others; the first error is re-thrown after all have run.
+
+#### `app` (protected property)
+
+`protected app: Application`
+
+The application/container this provider configures. Use it in `register()` to
+bind and in `boot()` to resolve.
+
+```ts
+boot(): void {
+  const level = this.app.config().get("logger.level", "info");
+}
+```
+
+**Notes:** it's the same `Application` instance across every provider, exposing
+the container methods (`bind`, `singleton`, `instance`, `make`, `bound`) plus
+`config()`, `router()`, and `view()`. Being `protected`, it's only visible to
+subclass code.
+
+### Interfaces & types
+
+#### `ProviderClass`
+
+`type ProviderClass = new (app: Application) => ServiceProvider`
+
+The constructor type of a provider — a class (not an instance) that takes an
+`Application` and yields a `ServiceProvider`. Use it to type the array you export
+from `bootstrap/providers.ts` and anywhere you pass provider classes around.
+
+```ts
+import type { ProviderClass } from "@shaferllc/keel/core";
+import { AppServiceProvider } from "../app/Providers/AppServiceProvider.js";
+
+export const providers: ProviderClass[] = [AppServiceProvider];
+```
+
+**Notes:** it references the class itself, so entries are the class name with no
+`new` and no parentheses. `app.register()` and `app.boot()` both accept these.