@shaferllc/keel 0.66.0 → 0.74.0

package/docs/examples/templates.ts

@@ -0,0 +1,58 @@
+// Type-check harness for docs/templates.md. Every type-checkable snippet is
+// exercised here against the real exports, so a renamed method or wrong argument
+// type fails `npm run typecheck:docs`. Compile-only — never executed.
+import {
+  templates,
+  render,
+  setTemplateEngine,
+  escapeHtml,
+  TemplateEngine,
+  html,
+  type Filter,
+} from "@shaferllc/keel/core";
+
+declare const user: { name: string; admin: boolean };
+declare function readFile(path: string, enc: string): Promise<string>;
+
+export async function rendering() {
+  templates().register("greeting", "Hello, {{ name }}!");
+  const out = await render("greeting", { name: "Ada" });
+  return html(out);
+}
+
+export async function registerAll() {
+  templates().registerAll({
+    layout: await readFile("views/layout.html", "utf8"),
+    home: await readFile("views/home.html", "utf8"),
+  });
+}
+
+export function customFilter() {
+  templates().filter("currency", (v, code) =>
+    new Intl.NumberFormat("en-US", { style: "currency", currency: String(code) }).format(Number(v)),
+  );
+}
+
+export function globals() {
+  templates()
+    .global("appName", "Keel")
+    .global("asset", (path: string) => `/static/${path}`);
+}
+
+export function ownEngine() {
+  const engine = new TemplateEngine();
+  engine.register("home", "…");
+  engine.registerAll({ a: "A", b: "B" });
+  engine.has("home");
+  engine.global("appName", "Keel");
+  engine.filter("upper", (v) => String(v).toUpperCase());
+  setTemplateEngine(engine);
+  return engine.render("home", { user });
+}
+
+// Interfaces & types
+const filter: Filter = (value, ...args) => `${String(value)}${args.length}`;
+
+export function escaping() {
+  return [escapeHtml("<b>&\"'</b>"), escapeHtml(null), escapeHtml(42), filter("x", 1)];
+}

package/docs/examples/testing.ts

@@ -0,0 +1,215 @@
+// Type-check harness for docs/testing.md. Compile-only — never executed.
+import {
+  Application,
+  Router,
+  HttpKernel,
+  json,
+  testClient,
+  sessionMiddleware,
+  requestLogger,
+  type TestClient,
+  type TestResponse,
+} from "@shaferllc/keel/core";
+
+declare const body: unknown;
+
+type User = { id: number; email: string };
+
+async function makeApp() {
+  const app = new Application();
+  await app.boot([], { discoverConfig: false, config: { app: {} } });
+  app.make(Router).get("/health", () => json({ ok: true }));
+  return app;
+}
+
+export async function basic() {
+  const client: TestClient = testClient(await makeApp());
+  const res: TestResponse = await client.get("/health");
+  res.assertStatus(200).assertJson({ ok: true });
+}
+
+export async function requests(client: TestClient) {
+  await client.get("/users");
+  await client.get("/users?active=true");
+  await client.post("/users", { email: "a@b.com", name: "Ada" });
+  await client.put("/users/1", { name: "Grace" });
+  await client.delete("/users/1");
+  await client.request("/users", { method: "POST", headers: { authorization: "Bearer x" }, body: JSON.stringify(body) });
+}
+
+export async function responseShape(client: TestClient) {
+  const res = await client.get("/user");
+  const s: number = res.status;
+  const ct = res.header("content-type");
+  const t: string = res.text();
+  const u = res.json<User>();
+  return { s, ct, t, u, raw: res.raw };
+}
+
+export async function assertions(client: TestClient) {
+  const res = await client.post("/users", body);
+  res
+    .assertStatus(201)
+    .assertOk()
+    .assertJson({ id: 2 })
+    .assertText("")
+    .assertHeader("content-type", "application/json")
+    .assertRedirect("/login");
+}
+
+export async function withMiddleware() {
+  const app = await makeApp();
+  const kernel = new HttpKernel(app);
+  kernel.use(sessionMiddleware());
+  kernel.use(requestLogger());
+  return testClient(kernel);
+}
+
+/* --- Auth, forms, assertions, doubles, time, state, db, console --- */
+
+import {
+  spy,
+  spyOn,
+  restoreSpies,
+  freezeTime,
+  timeTravel,
+  restoreTime,
+  resetState,
+  truncate,
+  assertDatabaseHas,
+  assertDatabaseMissing,
+  assertDatabaseCount,
+  assertDatabaseEmpty,
+  runCommand,
+  fakeMail,
+  fakeQueue,
+  swap,
+  jwt,
+  Job,
+  type Spy,
+  type CommandResult,
+} from "@shaferllc/keel/core";
+
+declare const bytes: Blob;
+declare function notify(send: (message: string) => void): void;
+declare function registerUser(user: { email: string }): Promise<void>;
+declare const gateway: { charge(amount: number): string };
+declare const receipt: string;
+declare class PaymentGateway {}
+declare class FakeGateway {}
+declare class SendWelcome extends Job {
+  handle(): Promise<void>;
+}
+
+export async function authenticatedRequests(client: TestClient) {
+  const authed = client.withToken("tok_123");
+  await authed.get("/me");
+  await client.withBasicAuth("ada", "s3cret").get("/me");
+  await client.withHeader("x-tenant", "acme").get("/me");
+  await client.withHeaders({ "x-a": "1", "x-b": "2" }).get("/me");
+  await client.withCookie("session", "abc").get("/me");
+  await client.withCookies({ session: "abc" }).get("/me");
+  await client.acceptJson().get("/me");
+}
+
+export async function formsAndUploads(client: TestClient) {
+  await client.form("/login", { email: "a@b.com", password: "s3cret" });
+  await client.multipart("/avatar", { file: bytes, name: "ada" });
+}
+
+export async function moreAssertions(client: TestClient) {
+  const res = await client.get("/users/1");
+
+  res.assertOk();
+  res.assertCreated();
+  res.assertNoContent();
+  res.assertBadRequest();
+  res.assertUnauthorized();
+  res.assertForbidden();
+  res.assertNotFound();
+  res.assertUnprocessable();
+  res.assertServerError();
+
+  res.assertJsonContains({ user: { email: "a@b.com" } });
+  res.assertSee("Welcome back");
+  res.assertDontSee("Sign up");
+
+  res.assertHeader("content-type", "application/json");
+  res.assertHeaderMissing("x-debug");
+
+  res.assertCookie("session");
+  res.assertCookie("session", "abc123");
+  res.assertCookieMissing("admin");
+
+  res.assertValidationErrors("email", "password");
+  res.assertNoValidationError("name");
+
+  res.dump();
+  return res.cookies();
+}
+
+export async function doubles() {
+  const mailer = fakeMail();
+  const queue = fakeQueue();
+
+  await registerUser({ email: "ada@example.com" });
+
+  mailer.assertQueued((m) => m.subject === "Welcome");
+  queue.assertPushed(SendWelcome);
+
+  swap(PaymentGateway, () => new FakeGateway());
+}
+
+export function spies() {
+  const send: Spy<[string], void> = spy<[string], void>();
+  notify(send);
+  void send.callCount;
+  void send.calledWith("hello");
+
+  const charge = spyOn(gateway, "charge");
+  charge.returns(receipt);
+  restoreSpies();
+}
+
+export async function controllingTime() {
+  freezeTime("2026-07-11T12:00:00Z");
+
+  const token = await jwt.sign({ sub: "1" }, { expiresIn: "1h" });
+  await jwt.verify(token);
+
+  timeTravel(61 * 60 * 1000);
+  await jwt.verify(token);
+
+  restoreTime();
+}
+
+export async function stateReset() {
+  resetState();
+  await truncate("comments", "posts", "users");
+}
+
+export async function databaseAssertions() {
+  await assertDatabaseHas("users", { email: "ada@example.com" });
+  await assertDatabaseHas("users", { active: 1 }, 1);
+  await assertDatabaseMissing("users", { email: "deleted@example.com" });
+  await assertDatabaseCount("users", 1);
+  await assertDatabaseEmpty("sessions");
+}
+
+declare function run(argv: string[]): Promise<void>;
+
+export async function consoleTests(): Promise<CommandResult> {
+  const result = await runCommand(() => run(["node", "keel", "routes"]));
+
+  result
+    .assertSucceeded()
+    .assertOutputContains("GET  /users")
+    .assertOutputMatches(/POST\s+\/users/);
+
+  result.assertExitCode(0);
+  void result.stdout;
+  void result.stderr;
+  void result.exitCode;
+
+  return result;
+}

package/docs/examples/transformer.ts

@@ -0,0 +1,141 @@
+// Type-check harness for docs/transformers.md. Every type-checkable snippet in
+// the guide is exercised here against the real exports, so a renamed method or
+// wrong argument type fails `npm run typecheck:docs`. Compile-only — never run.
+import {
+  Transformer,
+  Model,
+  auth,
+  json,
+  type Attributes,
+  type DocumentOptions,
+  type Ctx,
+} from "@shaferllc/keel/core";
+
+class Post extends Model {
+  static table = "posts";
+  declare id: number;
+  declare title: string;
+  declare author: User;
+}
+
+class User extends Model {
+  static table = "users";
+  declare id: number;
+  declare name: string;
+  declare email: string;
+  declare created_at: string;
+  declare admin: boolean;
+  declare role: string;
+  declare permissions: string[];
+}
+
+class PostTransformer extends Transformer<Post> {
+  transform(post: Post): Attributes {
+    return { id: post.id, title: post.title };
+  }
+}
+
+// Defining a transformer
+export class BasicUserTransformer extends Transformer<User> {
+  transform(user: User): Attributes {
+    return {
+      id: user.id,
+      name: user.name,
+      joined: user.created_at,
+    };
+  }
+}
+
+// Constructor context + conditional fields + nesting + relations
+export class UserTransformer extends Transformer<User> {
+  constructor(private viewerId: string | null) {
+    super();
+  }
+
+  transform(user: User): Attributes {
+    return {
+      id: user.id,
+      name: user.name,
+      email: this.when(String(user.id) === this.viewerId, user.email),
+      token: this.when(fresh, () => mintToken(user), null),
+      ...this.mergeWhen(user.admin, { role: user.role, permissions: user.permissions }),
+      author: new UserTransformer(this.viewerId).item(user),
+      posts: this.whenLoaded(user, "posts", new PostTransformer()),
+      roles: this.whenLoaded(user, "roles", (roles: { name: string }[]) =>
+        roles.map((r) => r.name),
+      ),
+    };
+  }
+}
+
+class WrappedUserTransformer extends Transformer<User> {
+  wrapKey = "user";
+  transform(user: User): Attributes {
+    return { id: user.id, name: user.name };
+  }
+}
+
+declare const user: User;
+declare const list: User[];
+declare const fresh: boolean;
+declare const fetchedAt: string;
+declare function mintToken(user: User): string;
+
+// Transforming
+export function transforming() {
+  const users = new UserTransformer(null);
+  json(users.item(user));
+  json(users.collection(list));
+  json(users.document(list, { meta: { total: list.length } }));
+}
+
+// item null passthrough
+export function nullable() {
+  const out: Attributes | null = new BasicUserTransformer().item(null);
+  return out;
+}
+
+// Passing viewer context through the constructor
+export function withViewer() {
+  return json(new UserTransformer(auth().id()).collection(list));
+}
+
+// Nesting / relations — load first, then transform
+export async function relations() {
+  const users = await User.all<User>();
+  await User.load(users, "posts");
+  return json(new UserTransformer(null).collection(users));
+}
+
+// Response documents
+export async function documents() {
+  const page = await User.all<User>();
+  json(
+    new UserTransformer(null).document(page, {
+      meta: { total: page.length, page: 1 },
+    }),
+  );
+
+  new WrappedUserTransformer().document(user); // { user: { … } }
+  new UserTransformer(null).document(user, { key: null, meta: { fetchedAt } });
+  new UserTransformer(null).document(user, { key: "records", meta: { total: 42 } });
+}
+
+// In a controller
+export class UserController {
+  async show(c: Ctx) {
+    const found = await User.findOrFail<User>(c.req.param("id"));
+    return c.json(new UserTransformer(auth().id()).item(found));
+  }
+
+  async index(c: Ctx) {
+    const users = await User.all<User>();
+    await User.load(users, "posts");
+    return c.json(new UserTransformer(auth().id()).document(users));
+  }
+}
+
+// Types
+const options: DocumentOptions = { key: "records", meta: { total: 42 } };
+const shape: Attributes = { id: 1, name: "Ada" };
+export { options, shape };

package/docs/examples/transformers.ts

@@ -0,0 +1,49 @@
+// Type-check harness for docs/transformers.md. Exercises every type-checkable
+// snippet against the real exports so a renamed method or wrong signature fails
+// `npm run typecheck:docs`. Compile-only — never executed.
+import {
+  Transformer,
+  json,
+  type Attributes,
+  type DocumentOptions,
+} from "@shaferllc/keel/core";
+
+type User = { id: number; name: string; email: string; role: string; admin: boolean };
+type Post = { id: number; title: string };
+
+declare const isSelf: boolean;
+declare const isAdmin: boolean;
+declare const fresh: boolean;
+declare function mint(): string;
+
+class PostTransformer extends Transformer<Post> {
+  transform(post: Post): Attributes {
+    return { id: post.id, title: post.title };
+  }
+}
+
+class UserTransformer extends Transformer<User> {
+  transform(user: User): Attributes {
+    return {
+      id: user.id,
+      name: user.name,
+      email: this.when(isSelf, user.email), // key vanishes for others
+      token: this.when(fresh, () => mint(), null), // explicit fallback
+      ...this.mergeWhen(isAdmin, { role: user.role }),
+      posts: this.whenLoaded(user, "posts", new PostTransformer()),
+      roles: this.whenLoaded(user, "roles", (rs: { name: string }[]) => rs.map((r) => r.name)),
+    };
+  }
+}
+
+export function usage(user: User, users: User[]) {
+  const one: Attributes | null = new UserTransformer().item(user);
+  const many: Attributes[] = new UserTransformer().collection(users);
+  const wrapped: Attributes = new UserTransformer().document(users, {
+    meta: { total: users.length },
+  });
+  const opts: DocumentOptions = { key: "data", meta: { page: 1 } };
+  const custom: Attributes = new UserTransformer().document(user, opts);
+  const unwrapped: Attributes = new UserTransformer().document(user, { key: null });
+  return [json(one), json(many), json(wrapped), json(custom), json(unwrapped)];
+}

package/docs/examples/url-builder.ts

@@ -0,0 +1,86 @@
+// Type-check harness for docs/url-builder.md. Every type-checkable snippet in
+// the reference is exercised here against the real exports, so a renamed method
+// or wrong argument type fails `npm run typecheck:docs`. Compile-only — never
+// executed.
+import {
+  Router,
+  Container,
+  matchers,
+  type UrlOptions,
+  type SignedUrlOptions,
+  type Matcher,
+} from "@shaferllc/keel/core";
+
+// The router is resolved from the container in a real app; construct it
+// directly here (as the test suite does).
+const router = new Router(new Container());
+
+// Controllers referenced by the doc's route registrations.
+class UserController {}
+class FileController {}
+class PostController {}
+class TeamController {}
+class CodeController {}
+class XController {}
+
+export function building() {
+  router.get("/users/:id", [UserController, "show"]).name("users.show");
+
+  const a: string = router.url("users.show", { id: 42 });
+  const b: string = router.url("users.show", { id: 42 }, { qs: { tab: "posts", page: 2 } });
+
+  router.get("/files/:name", [FileController]).name("files.show");
+  const c: string = router.url("files.show", { name: "a/b c.txt" });
+
+  return { a, b, c };
+}
+
+export function optionalParams() {
+  router.get("/posts/:id?", [PostController, "show"]).name("posts.show");
+  const withId: string = router.url("posts.show", { id: 7 });
+  const without: string = router.url("posts.show", {});
+  return { withId, without };
+}
+
+export function errors() {
+  // Throws at runtime; type-checks fine.
+  return router.url("nope");
+}
+
+export async function signing() {
+  const url: string = await router.signedUrl("download", { id: 7 });
+  const expiring: string = await router.signedUrl(
+    "download",
+    { id: 7 },
+    { expiresIn: 3600 },
+  );
+  const valid: boolean = await router.hasValidSignature();
+  return { url, expiring, valid };
+}
+
+export function constraints() {
+  router.get("/users/:id", [UserController]).where("id", /\d+/);
+  router.get("/p/:slug", [PostController]).where("slug", { match: /[a-z0-9-]+/ });
+
+  router.get("/n/:id", [UserController]).where("id", matchers.number());
+  router.get("/t/:id", [TeamController]).where("id", matchers.uuid());
+  router.get("/s/:slug", [PostController]).where("slug", matchers.slug());
+  router.get("/c/:code", [CodeController]).where("code", matchers.alpha());
+
+  // Also reachable off the instance.
+  router.get("/i/:id", [XController]).where("id", router.matchers.number());
+}
+
+export function typeSeams() {
+  const opts: UrlOptions = { qs: { page: 2, tab: "posts" } };
+  router.url("users.show", { id: 1 }, opts);
+
+  const signed: SignedUrlOptions = { qs: { plan: "pro" }, expiresIn: 3600 };
+
+  const a: Matcher = /\d+/;
+  const b: Matcher = "[0-9]+";
+  const c: Matcher = { match: /[a-z-]+/ };
+  router.get("/x/:id", [XController]).where("id", a);
+
+  return { opts, signed, a, b, c };
+}

package/docs/examples/validation.ts

@@ -0,0 +1,102 @@
+// Type-check harness for docs/validation.md. Every type-checkable snippet in the
+// guide is exercised here against the real exports, so a renamed method or wrong
+// argument type fails `npm run typecheck:docs`. Compile-only — never executed.
+import {
+  json,
+  validate,
+  validateRequest,
+  validated,
+  request,
+  response,
+  ValidationException,
+  Router,
+  type Schema,
+} from "@shaferllc/keel/core";
+import { z } from "zod";
+
+declare const Users: new (...a: unknown[]) => object;
+declare const Posts: new (...a: unknown[]) => object;
+
+export function declarative(router: Router) {
+  const NewUser = z.object({ email: z.string().email(), name: z.string().min(1) });
+  router.post("/users", [Users, "store"]).middleware([validateRequest({ body: NewUser })]);
+  router.get("/posts/:id", [Posts, "show"]).middleware([
+    validateRequest({
+      params: z.object({ id: z.coerce.number() }),
+      query: z.object({ page: z.coerce.number().min(1).default(1) }),
+    }),
+  ]);
+}
+
+export function readValidated() {
+  const user = validated<{ email: string; name: string }>("body");
+  const id = validated<{ id: number }>("params");
+  const page = validated<{ page: number }>("query");
+  return { user, id, page };
+}
+
+declare const email: string;
+declare const age: number;
+declare const err: unknown;
+
+const NewUser = z.object({
+  email: z.string().email(),
+  age: z.number().min(18),
+});
+
+export class UserController {
+  async store() {
+    const data = await validate(NewUser); // { email: string; age: number }
+    return json({ created: data.email }, 201);
+  }
+}
+
+const Search = z.object({ q: z.string().min(1), page: z.coerce.number().default(1) });
+
+export async function search() {
+  const { q, page } = await validate(Search, request.query());
+  return { q, page };
+}
+
+export async function mergedInput() {
+  const data = await validate(NewUser, await request.all());
+  return data;
+}
+
+export function handleError() {
+  if (err instanceof ValidationException) {
+    return response.json({ fields: err.errors }, 422);
+  }
+}
+
+export async function reference() {
+  const fromBody = await validate(NewUser);
+  const fromData = await validate(NewUser, { email, age });
+  return { fromBody, fromData };
+}
+
+// Schema<T> — hand-rolled implementation
+const Positive: Schema<number> = {
+  safeParse: (data) =>
+    typeof data === "number" && data > 0
+      ? { success: true, data }
+      : { success: false, error: { issues: [{ path: [], message: "must be > 0" }] } },
+};
+
+export async function customSchema() {
+  const n = await validate(Positive, 42); // number
+  return n;
+}
+
+// ValidationException seam
+export async function exceptionShape() {
+  try {
+    await validate(NewUser);
+  } catch (e) {
+    if (e instanceof ValidationException) {
+      const status: number = e.status;
+      const errors: Record<string, string[]> = e.errors;
+      return { status, errors };
+    }
+  }
+}