@shaferllc/keel 0.83.0 → 0.83.2

package/docs/examples/query-builder.ts

@@ -0,0 +1,118 @@
+// Type-check harness for docs/query-builder.md. Compile-only — never executed.
+import { db, type Row } from "@shaferllc/keel/core";
+
+declare const email: string;
+declare const name: string;
+declare const id: number;
+declare const now: number;
+declare const search: string | undefined;
+declare const includeArchived: boolean;
+declare const key: string;
+declare const value: string;
+
+export async function retrieving() {
+  await db("users").get();
+  await db("users").where("id", 1).first();
+  await db("users").where("id", 1).firstOrFail();
+  await db("users").find(1);
+  await db("users").where("email", email).sole();
+  await db("users").where("id", 1).value("email");
+  await db("posts").pluck("title");
+  await db("tags").orderBy("name").implode("name", ", ");
+
+  await db("users")
+    .orderBy("id")
+    .chunk(500, async (rows) => {
+      for (const _row of rows) {
+        /* process */
+      }
+    });
+}
+
+export async function aggregates() {
+  await db("orders").count();
+  await db("orders").where("paid", true).sum("total");
+  await db("orders").avg("total");
+  await db("orders").min("total");
+  await db("orders").max("total");
+  await db("users").where("email", email).exists();
+  await db("users").where("banned", true).doesntExist();
+}
+
+export async function selectsAndWheres() {
+  db("users").select("id", "email");
+  db("users").select("id").addSelect("email");
+  db("orders").selectRaw("SUM(total) AS revenue");
+  db("users").distinct().select("country");
+
+  db("users").where("votes", 100);
+  db("users").where("votes", ">=", 100);
+  db("users").where("name", "like", "T%");
+  db("users").where("votes", 100).orWhere("name", "John");
+  db("users").whereNot("status", "cancelled");
+  db("users").whereIn("id", [1, 2, 3]).whereNotIn("id", [4]);
+  db("users").whereNull("deleted_at").whereNotNull("email_verified_at");
+  db("products").whereBetween("price", [10, 100]).whereNotBetween("stock", [0, 5]);
+  db("posts").whereLike("title", "%keel%");
+  db("events").whereColumn("updated_at", ">", "created_at");
+  db("users").whereRaw("score >= ? AND score <= ?", [10, 90]);
+
+  await db("users")
+    .where("active", true)
+    .where((q) => q.where("role", "admin").orWhere("role", "owner"))
+    .get();
+}
+
+export async function orderingJoinsWhen() {
+  db("users").orderBy("name").orderByDesc("created_at");
+  db("posts").latest();
+  db("posts").oldest();
+  db("posts").orderByRaw("LENGTH(title) DESC");
+  db("users").inRandomOrder();
+  db("users").reorder("name");
+  db("users").limit(10).offset(20);
+  db("users").take(10).skip(20);
+  db("users").forPage(3, 15);
+
+  await db("orders")
+    .select("user_id")
+    .selectRaw("SUM(total) AS spent")
+    .groupBy("user_id")
+    .having("spent", ">", 1000)
+    .get();
+
+  await db("posts")
+    .join("users", "posts.user_id", "users.id")
+    .leftJoin("images", "images.post_id", "posts.id")
+    .select("posts.title", "users.name")
+    .get();
+
+  await db("users")
+    .when(search, (q, term) => q.whereLike("name", `%${term}%`))
+    .unless(includeArchived, (q) => q.whereNull("archived_at"))
+    .get();
+}
+
+export async function writes() {
+  await db("users").insert({ email, name });
+  await db("users").insertGetId({ email, name });
+  await db("logs").insertOrIgnore({ key, value });
+  await db("users").upsert([{ id: 1, name: "Ada" }], ["id"], ["name"]);
+
+  await db("users").where("id", id).update({ name: "Grace" });
+  await db("users").updateOrInsert({ email }, { name });
+  await db("posts").where("id", id).increment("views");
+  await db("posts").where("id", id).decrement("stock", 3, { updated_at: now });
+  await db("counters").incrementEach({ hits: 1, misses: 2 });
+
+  await db("sessions").where("expires_at", "<", now).delete();
+  await db("cache").truncate();
+}
+
+export async function typed() {
+  type User = { id: number; email: string };
+  const row: User | null = await db<User>("users").where("id", 1).first();
+  const rows: User[] = await db<User>("users").get();
+  const raw: Row[] = await db("users").get();
+  return { row, rows, raw };
+}

package/docs/examples/security.ts

@@ -0,0 +1,31 @@
+// Type-check harness for docs/security.md. Compile-only — never executed.
+import type { MiddlewareHandler } from "hono";
+import {
+  securityHeaders,
+  csrf,
+  csrfField,
+  csrfToken,
+  sessionMiddleware,
+} from "@shaferllc/keel/core";
+
+export function headers(): MiddlewareHandler[] {
+  return [
+    securityHeaders(),
+    securityHeaders({
+      csp: { defaultSrc: ["'self'"], scriptSrc: ["'self'", "https://cdn.example.com"] },
+      hsts: { maxAge: 15552000, includeSubDomains: true },
+      frameGuard: "DENY",
+    }),
+  ];
+}
+
+export function csrfStack(): MiddlewareHandler[] {
+  return [sessionMiddleware(), csrf(), csrf({ except: ["/billing/webhook/*"] })];
+}
+
+export function forms() {
+  return {
+    field: csrfField(),
+    token: csrfToken(),
+  };
+}

package/docs/examples/social-auth.ts

@@ -0,0 +1,76 @@
+// Type-check harness for docs/social-auth.md. Compile-only — never executed.
+import {
+  social,
+  session,
+  redirect,
+  request,
+  auth,
+  ForbiddenException,
+  Model,
+  config,
+} from "@shaferllc/keel/core";
+
+class User extends Model {
+  static override table = "users";
+  declare id: number;
+  declare email: string | null;
+  declare name: string | null;
+  declare github_id: string;
+  declare twitter_id: string;
+}
+
+const github = social.github({
+  clientId: config("services.github.id") as string,
+  clientSecret: config("services.github.secret") as string,
+  redirectUri: "https://app.example.com/auth/github/callback",
+});
+
+const twitter = social.twitter({
+  clientId: config("services.twitter.key") as string,
+  clientSecret: config("services.twitter.secret") as string,
+  redirectUri: "https://app.example.com/auth/twitter/callback",
+});
+
+export function redirectToGithub() {
+  const state = social.state();
+  session().put("oauth_state", state);
+  return redirect(github.redirect({ state }));
+}
+
+export async function githubCallback() {
+  const state = String(request.query("state") ?? "");
+  if (state !== session().pull("oauth_state")) {
+    throw new ForbiddenException("Invalid OAuth state");
+  }
+
+  const code = String(request.query("code") ?? "");
+  const gh = await github.user(code);
+  const existing = await User.query().where("github_id", gh.id).first();
+  const user =
+    existing ??
+    (await User.create({ github_id: gh.id, email: gh.email, name: gh.name }));
+
+  auth().login(user.id as number);
+  return redirect("/dashboard");
+}
+
+export async function twitterFlow() {
+  const requestToken = await twitter.requestToken();
+  session().put("twitter_secret", requestToken.tokenSecret);
+  const toProvider = redirect(twitter.redirect(requestToken));
+
+  const tw = await twitter.user(
+    String(request.query("oauth_token") ?? ""),
+    String(request.query("oauth_verifier") ?? ""),
+    String(session().pull("twitter_secret") ?? ""),
+  );
+  const user = await User.firstOrCreate({ twitter_id: tw.id }, { name: tw.name });
+  auth().login(user.id as number);
+  return { toProvider, user };
+}
+
+export async function tokenReuse() {
+  const code = String(request.query("code") ?? "");
+  const token = await github.exchangeCode(code);
+  return github.userFromToken(token);
+}

package/docs/examples/starter-kits.ts

@@ -0,0 +1,14 @@
+// Type-check harness for docs/starter-kits.md. Compile-only — never executed.
+import { TenantModel } from "@shaferllc/keel/teams";
+
+class Project extends TenantModel {
+  static override table = "projects";
+  declare id: number;
+  declare name: string;
+}
+
+export async function tenantScoped() {
+  await Project.all();
+  await Project.create({ name: "Hi" });
+  await Project.find(1); // null if another team's
+}

package/docs/examples/watch.ts

@@ -0,0 +1,10 @@
+// Type-check harness for docs/watch.md. Compile-only — never executed.
+import { Application } from "@shaferllc/keel/core";
+import { WatchServiceProvider, Watch } from "@shaferllc/keel/watch";
+
+export function install() {
+  const app = new Application();
+  app.register(WatchServiceProvider);
+  Watch.auth((c) => c.req.header("x-watch-key") === "secret");
+  return app;
+}

package/docs/hooks.md

@@ -1,9 +1,7 @@
 # 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

package/docs/logger.md

@@ -156,8 +156,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";

package/docs/orm.md

@@ -55,3 +55,42 @@ The ORM is deliberately small — enough for CRUD, relationships, and the common
 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).
+

package/docs/packages.md

@@ -7,9 +7,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
 

package/docs/providers.md

@@ -111,12 +111,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
 

package/docs/request-response.md

@@ -51,8 +51,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, …)

package/docs/starter-kits.md

@@ -14,6 +14,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

package/docs/testing.md

@@ -2,8 +2,7 @@
 
 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
 

package/docs/validation.md

@@ -112,8 +112,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
 

package/docs/watch.md

@@ -1,6 +1,6 @@
 # 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.