@shaferllc/keel 0.59.0 → 0.68.0

package/docs/examples/routing.ts

@@ -0,0 +1,186 @@
+// Type-check harness for docs/routing.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 run.
+import {
+  Router,
+  Route,
+  RouteGroup,
+  RouteResource,
+  matchers,
+  json,
+  text,
+  request,
+  type Ctx,
+  type RouteHandler,
+  type RouteDefinition,
+  type Method,
+  type Matcher,
+  type MiddlewareRef,
+} from "@shaferllc/keel/core";
+
+// The framework builds the Router and hands it to your routes file; users never
+// construct it, so we `declare` one here.
+declare const router: Router;
+declare const handler: RouteHandler;
+declare const auth: MiddlewareRef;
+declare const admin: MiddlewareRef;
+declare const logRequests: MiddlewareRef;
+declare const rateLimiterMw: MiddlewareRef;
+declare const user: unknown;
+declare const AboutPage: (props?: unknown) => unknown;
+
+// Controllers can be plain classes.
+class HomeController {
+  index(_c: Ctx) {
+    return "home";
+  }
+}
+class UserController {
+  show(c: Ctx) {
+    return c.json({ id: 1 });
+  }
+  store(_c: Ctx) {
+    return "created";
+  }
+  destroy(_c: Ctx) {
+    return "gone";
+  }
+}
+class PostController {}
+class CommentController {}
+class HookController {
+  handle(_c: Ctx) {
+    return "ok";
+  }
+}
+class MeController {
+  show(_c: Ctx) {
+    return "me";
+  }
+}
+
+export function verbs() {
+  router.get("/users/:id", [UserController, "show"]);
+  router.post("/users", [UserController, "store"]);
+  router.put("/users/:id", handler);
+  router.patch("/users/:id", handler);
+  router.delete("/users/:id", [UserController, "destroy"]);
+  router.any("/webhook", [HookController, "handle"]);
+  router.route(["GET", "POST"], "/search", handler);
+}
+
+export function handlerShapes() {
+  router.get("/a", (c: Ctx) => c.json({ ok: true })); // HandlerFn
+  router.get("/hi/:name", (c: Ctx) => c.text("hi")); // HandlerFn -> string
+  router.get("/b", [UserController, "show"]); // ControllerAction
+  router.get("/single", [HookController]); // [Controller] -> handle
+  router.get("/c", json({ up: true })); // Response
+  router.get("/robots.txt", text("User-agent: *"));
+}
+
+export function brisk() {
+  router.on("/old").redirect("/new");
+  router.on("/ext").redirectToPath("https://example.com", 301);
+  router.on("/posts").redirectToRoute("articles.index", {}, { qs: { page: 1 } });
+  router.on("/about").render(AboutPage, { title: "About" });
+  router.on("/dashboard").renderInertia("Dashboard", { user });
+}
+
+export function grouping() {
+  const g: RouteGroup = router
+    .group(() => {
+      router.get("/status", json({ up: true })).name("status");
+      router.get("/me", [MeController, "show"]).name("me");
+    })
+    .prefix("/api")
+    .middleware([auth])
+    .as("api");
+  g.where("id", matchers.uuid()).domain(":tenant.example.com").use([logRequests]);
+}
+
+export function routeConfig() {
+  router.get("/admin", handler).config({ scope: "admin", rateTier: "high" });
+  router
+    .group(() => {
+      router.get("/billing", handler);
+      router.get("/billing/export", handler).config({ heavy: true });
+    })
+    .config({ area: "billing" });
+  const cfg = request.route?.config; // { … } | undefined
+  void cfg;
+}
+
+export function resources() {
+  const res: RouteResource = router.resource("posts", PostController);
+  res.only(["index", "show"]);
+  res.except(["destroy"]);
+  res.apiOnly();
+  res.as("articles");
+  res.params({ posts: "post" });
+  res.use(["store", "update", "destroy"], "auth");
+  res.use("*", logRequests);
+
+  router.resource("posts.comments", CommentController); // nested
+}
+
+export function constraints() {
+  router.get("/users/:id", handler).where("id", /\d+/);
+  router.get("/u/:id", handler).where("id", matchers.number());
+  router.get("/a/:id", handler).where("id", matchers.uuid());
+  router.get("/s/:slug", handler).where("slug", matchers.slug());
+  router.get("/x/:id", handler).where("id", { match: /\d+/ });
+  router.where("id", matchers.number()); // global
+}
+
+export function routeChain() {
+  const r: Route = router.get("/users/:id", [UserController, "show"]);
+  r.name("users.show");
+  r.as("users.show");
+  r.middleware([auth]);
+  r.use(["auth", "admin"]);
+  r.where("id", /\d+/);
+  r.domain("blog.example.com");
+  const def: RouteDefinition = r.def;
+  return def;
+}
+
+export function named() {
+  const map: Parameters<typeof router.named>[0] = {};
+  router.named(map);
+  const mw = router.resolveMiddleware("auth");
+  return mw;
+}
+
+export function inspect() {
+  const routes: RouteDefinition[] = router.all();
+  for (const def of routes) {
+    console.log(def.methods.join("|"), def.path, def.name ?? "");
+  }
+  const fn = router.resolve([UserController, "show"]);
+  return { routes, fn };
+}
+
+// matchers stand-alone
+export function matcherValues() {
+  router.get("/u/:id", handler).where("id", matchers.number());
+  return [matchers.number(), matchers.uuid(), matchers.slug(), matchers.alpha()];
+}
+
+// Interface / type seams
+const aMatcher: Matcher = /\d+/;
+const bMatcher: Matcher = "\\d+";
+const cMatcher: Matcher = { match: /[a-z]+/ };
+const method: Method = "GET";
+const methods: Method[] = ["GET", "POST"];
+const ref: MiddlewareRef = "auth";
+const refFn: MiddlewareRef = rateLimiterMw;
+const routeDef: RouteDefinition = {
+  methods: ["GET"],
+  path: "/",
+  handler: (c: Ctx) => c.text("ok"),
+  middleware: [],
+  wheres: {},
+  config: {},
+};
+const someHandler: RouteHandler = (c: Ctx) => c.json({ ok: true });
+export { aMatcher, bMatcher, cMatcher, method, methods, ref, refFn, routeDef, someHandler, admin };

package/docs/examples/scheduling.ts

@@ -0,0 +1,62 @@
+// Type-check harness for docs/scheduling.md. Compile-only — never executed.
+import {
+  schedule,
+  scheduler,
+  setScheduler,
+  Scheduler,
+  cronMatches,
+  Job,
+  logger,
+} from "@shaferllc/keel/core";
+
+class PruneSessions extends Job {
+  async handle() {}
+}
+class SendDigest extends Job {
+  async handle() {}
+}
+declare function syncInventory(): Promise<void>;
+declare const job: Job;
+
+export function scheduling() {
+  schedule(new PruneSessions()).daily();
+  schedule(() => syncInventory()).everyFiveMinutes();
+  schedule(new SendDigest()).cron("0 9 * * 1");
+}
+
+export function cadences() {
+  const t = schedule(job);
+  t.everyMinute();
+  t.everyTenMinutes();
+  t.hourly();
+  t.hourlyAt(15);
+  t.daily();
+  t.dailyAt("13:30");
+  t.weekly(1);
+  t.monthly(15);
+  t.cron("*/10 9-17 * * 1-5");
+}
+
+// Cloudflare scheduled handler shape
+type ScheduledEvent = { scheduledTime: number };
+type ExecutionContext = { waitUntil(p: Promise<unknown>): void };
+export const worker = {
+  async scheduled(event: ScheduledEvent, _env: unknown, ctx: ExecutionContext) {
+    ctx.waitUntil(scheduler().runDue(new Date(event.scheduledTime)));
+  },
+};
+
+export function nodeInterval() {
+  setInterval(() => scheduler().runDue(new Date()), 60_000);
+}
+
+export function inspecting() {
+  schedule(job).named("prune-sessions").daily();
+  for (const t of scheduler().due(new Date())) logger().info("due", { task: t.name });
+}
+
+export function fresh(): Scheduler {
+  const s = setScheduler(new Scheduler());
+  const match: boolean = cronMatches("*/5 * * * *", new Date());
+  return match ? s : scheduler();
+}

package/docs/examples/sessions.ts

@@ -0,0 +1,102 @@
+// Type-check harness for docs/sessions.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 run.
+import {
+  HttpKernel,
+  Application,
+  session,
+  sessionMiddleware,
+  Session,
+  redirect,
+  type SessionOptions,
+} from "@shaferllc/keel/core";
+
+declare const user: { id: number };
+
+export class Kernel extends HttpKernel {
+  constructor(app: Application) {
+    super(app);
+    this.use(sessionMiddleware());
+    this.use(sessionMiddleware({ cookieName: "sid", cookie: { secure: true } }));
+  }
+}
+
+export function useIt() {
+  session().put("userId", user.id);
+  const id = session().get("userId");
+  const id2 = session().get("userId", null);
+
+  session().has("userId");
+  session().forget("userId");
+  session().pull("cart");
+  session().increment("visits");
+  session().clear();
+  session().all();
+
+  return { id, id2 };
+}
+
+export function sharedData() {
+  session().put("step", 1);
+  return session().get("step");
+}
+
+export function flashMessages() {
+  session().flash("status", "Profile saved!");
+  const r = redirect("/profile");
+
+  const status = session().flashed("status");
+  return { r, status };
+}
+
+export function flashCompartments() {
+  session().flash("status", "Saved!");
+  const a = session().flashed("status");
+  const b = session().get("status");
+  return { a, b };
+}
+
+export function counters() {
+  session().increment("visits");
+  session().increment("credits", 10);
+  session().decrement("credits", 3);
+}
+
+// --- API reference ---
+
+export function sessionRef() {
+  session().put("userId", 1);
+}
+
+export function middlewareRef() {
+  return sessionMiddleware({ cookieName: "sid", cookie: { secure: true } });
+}
+
+export function sessionMethods() {
+  const s: Session = session();
+
+  const data = s.all();
+  const id = s.get<number>("userId");
+  const theme = s.get("theme", "light");
+  s.put("userId", 1).put("theme", "dark");
+  s.set("locale", "en");
+  const logged = s.has("userId");
+  s.forget("userId");
+  const cart = s.pull("cart", []);
+  s.increment("visits");
+  s.increment("credits", 25);
+  s.decrement("credits", 3);
+  s.clear();
+  s.flash("status", "Profile saved!");
+  const status = s.flashed("status");
+  const msg = s.flashed("msg", "");
+
+  return { data, id, theme, logged, cart, status, msg };
+}
+
+// Interface / type seams
+const opts: SessionOptions = {
+  cookieName: "sid",
+  cookie: { secure: true, maxAge: 60 * 60 * 24 },
+};
+export { opts };

package/docs/examples/static-files.ts

@@ -0,0 +1,63 @@
+// Type-check harness for docs/static-files.md. Every type-checkable snippet in
+// the guide is exercised here against the real exports, so a renamed option or
+// wrong signature fails `npm run typecheck:docs`. Compile-only — never executed.
+import {
+  HttpKernel,
+  serveStatic,
+  type Application,
+  type StaticOptions,
+} from "@shaferllc/keel/core";
+
+export class Kernel extends HttpKernel {
+  constructor(app: Application) {
+    super(app);
+    this.use(serveStatic()); // serves ./public
+  }
+}
+
+export function options() {
+  serveStatic({
+    root: "./public",
+    index: "index.html",
+    dotFiles: "ignore",
+    maxAge: 86400,
+    immutable: true,
+    headers: (path) =>
+      path.endsWith(".html") ? { "X-Frame-Options": "DENY" } : undefined,
+  });
+}
+
+export function immutableAssets(kernel: HttpKernel) {
+  kernel.use(serveStatic({ root: "./dist", maxAge: 31536000, immutable: true }));
+}
+
+export function perFileHeaders() {
+  serveStatic({
+    headers: (path): Record<string, string> | undefined => {
+      if (path.endsWith(".html")) return { "X-Frame-Options": "DENY" };
+      if (path.endsWith(".wasm")) return { "Cross-Origin-Embedder-Policy": "require-corp" };
+      return undefined;
+    },
+  });
+}
+
+export function reference(kernel: HttpKernel) {
+  const assets = serveStatic({ root: "./public", maxAge: 86400 });
+  kernel.use(assets);
+
+  // No-argument form is valid — all options default.
+  serveStatic();
+}
+
+// Interface / type seam
+const staticOpts: StaticOptions = {
+  root: "./dist",
+  index: "index.html",
+  dotFiles: "deny",
+  maxAge: 31536000,
+  immutable: true,
+  headers: (path) => (path.endsWith(".html") ? { "X-Frame-Options": "DENY" } : undefined),
+};
+serveStatic(staticOpts);
+
+export { staticOpts };

package/docs/examples/storage.ts

@@ -0,0 +1,132 @@
+// Type-check harness for docs/storage.md. Compile-only — never executed.
+import {
+  storage,
+  setDisk,
+  fakeDisk,
+  restoreDisk,
+  serveStorage,
+  signStorageUrl,
+  verifyStorageUrl,
+  contentTypeFor,
+  MemoryDisk,
+  Storage,
+  HttpKernel,
+  type Application,
+  type Disk,
+  type FileMetadata,
+} from "@shaferllc/keel/core";
+
+declare const bytes: Uint8Array;
+declare const data: string;
+declare const svg: string;
+
+export async function usage() {
+  setDisk(new MemoryDisk());
+  await storage().put("avatars/1.png", bytes);
+  const got = await storage().get("avatars/1.png");
+  const text = await storage().getText("notes/todo.md");
+  const has = await storage().exists("avatars/1.png");
+  await storage().delete("avatars/1.png");
+  const files = await storage().list("avatars/");
+  const url = storage().url("avatars/1.png");
+  return { got, text, has, files, url };
+}
+
+export async function writing() {
+  // The content type is inferred from the extension — this is stored as image/png.
+  await storage().put("avatars/1.png", bytes);
+
+  // ...or set it, along with the rest of the object's metadata.
+  await storage().put("exports/report.csv", data, {
+    contentType: "text/csv",
+    cacheControl: "public, max-age=3600",
+    visibility: "private",
+    metadata: { uploadedBy: "42" },
+  });
+
+  return contentTypeFor("avatars/1.png"); // "image/png"
+}
+
+export async function inspecting() {
+  const meta: FileMetadata | null = await storage().metadata("avatars/1.png");
+  const size = await storage().size("avatars/1.png");
+
+  await storage().copy("avatars/1.png", "avatars/1-backup.png");
+  await storage().move("tmp/upload.png", "avatars/2.png");
+
+  return { meta, size };
+}
+
+export async function signing() {
+  // A temporary URL for a private file.
+  const url = await storage().signedUrl("invoices/42.pdf", { expiresIn: 300 });
+
+  // A URL the browser PUTs to directly — the bytes never transit the app.
+  const upload = await storage().signedUploadUrl("uploads/clip.mp4", {
+    expiresIn: 600,
+    contentType: "video/mp4",
+  });
+
+  // Sign and verify any URL yourself.
+  const signed = await signStorageUrl("/storage/invoices/42.pdf", 300);
+  const valid = await verifyStorageUrl(signed);
+
+  return { url, upload, valid };
+}
+
+export class Kernel extends HttpKernel {
+  constructor(app: Application) {
+    super(app);
+    this.use(serveStorage()); // public files under /storage
+    this.use(serveStorage({ disk: "r2", basePath: "/private", signed: true, maxAge: 60 }));
+  }
+}
+
+export async function testing() {
+  const disk = fakeDisk(); // swap the real disk for an in-memory one
+
+  await storage().put("avatars/1.png", bytes);
+
+  await disk.assertExists("avatars/1.png");
+  await disk.assertMissing("avatars/2.png");
+  await disk.assertContents("notes/todo.md", "buy milk");
+  await disk.assertCount(1, "avatars/");
+
+  restoreDisk();
+}
+
+export function named(local: Disk, r2: Disk) {
+  setDisk(local, "local");
+  setDisk(r2, "r2");
+  return Promise.all([
+    storage("local").put("cache/x", data),
+    storage("r2").put("public/logo.svg", svg),
+  ]);
+}
+
+// A minimal custom disk (the shape of the local/R2 examples)
+function makeDisk(): Disk {
+  const store = new Map<string, Uint8Array>();
+  return {
+    async put(path, b) {
+      store.set(path, b);
+    },
+    async get(path) {
+      return store.get(path) ?? null;
+    },
+    async exists(path) {
+      return store.has(path);
+    },
+    async delete(path) {
+      store.delete(path);
+    },
+    async list(prefix = "") {
+      return [...store.keys()].filter((k) => k.startsWith(prefix));
+    },
+    url: (path) => `https://cdn.example/${path}`,
+  };
+}
+
+export function wrap(): Storage {
+  return new Storage(makeDisk());
+}

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,66 @@
+// 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);
+}