@shaferllc/keel 0.66.0 → 0.68.0

package/docs/examples/queues.ts

@@ -0,0 +1,254 @@
+// Type-check harness for docs/queues.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.
+// The Cloudflare "custom driver" snippet uses Cloudflare's own Queue/env types,
+// which aren't Keel exports, so it stays illustrative in the doc and is omitted
+// here.
+import {
+  Job,
+  Queue,
+  SyncDriver,
+  MemoryDriver,
+  dispatch,
+  work,
+  setQueue,
+  getQueue,
+  mail,
+  type Dispatchable,
+  type JobOptions,
+  type QueueDriver,
+  type Drainable,
+  type QueuedJob,
+} from "@shaferllc/keel/core";
+
+declare const user: { email: string };
+declare function rebuildSearchIndex(): Promise<void>;
+declare function doWork(): Promise<void>;
+declare function registerUser(): Promise<void>;
+
+export class SendWelcome extends Job {
+  constructor(private email: string) {
+    super();
+  }
+  async handle() {
+    await mail().to(this.email).subject("Welcome").text("Glad you're here").send();
+  }
+}
+
+export async function dispatching() {
+  await dispatch(new SendWelcome(user.email));
+  await dispatch(new SendWelcome(user.email), { delay: 60, queue: "emails" });
+  await dispatch(() => rebuildSearchIndex());
+}
+
+export function drivers() {
+  setQueue(new SyncDriver());
+  setQueue(new MemoryDriver());
+}
+
+export async function runningQueued() {
+  setQueue(new MemoryDriver());
+  await dispatch(new SendWelcome("a@x.com"));
+  await dispatch(new SendWelcome("b@x.com"));
+  const ran: number = await work();
+  return ran;
+}
+
+export async function inTests() {
+  const driver = new MemoryDriver();
+  setQueue(driver);
+  await registerUser();
+  const size: number = driver.size;
+  const first: boolean = driver.jobs[0]!.job instanceof SendWelcome;
+  await work();
+  return { size, first };
+}
+
+// --- API reference: top-level functions ---
+
+export async function topLevel() {
+  await dispatch(new SendWelcome("a@x.com"));
+  await dispatch(() => rebuildSearchIndex(), { delay: 60, queue: "emails" });
+
+  const ran: number = await work();
+
+  setQueue(new MemoryDriver());
+  const q: Queue = setQueue(new SyncDriver());
+
+  const driver: QueueDriver = getQueue().driver;
+  return { ran, q, driver };
+}
+
+// --- API reference: Job ---
+
+export class RebuildIndex extends Job {
+  async handle() {
+    await rebuildSearchIndex();
+  }
+}
+
+// --- API reference: Queue ---
+
+export async function queueClass() {
+  const q = new Queue(new MemoryDriver());
+  await q.dispatch(new SendWelcome("a@x.com"));
+  await q.dispatch(new SendWelcome("a@x.com"), { queue: "emails" });
+  const ran: number = await q.work();
+  const driver: QueueDriver = q.driver;
+  return { ran, driver };
+}
+
+// --- API reference: drivers ---
+
+export async function syncDriver() {
+  const d = new SyncDriver();
+  await d.push(() => doWork(), {});
+}
+
+export async function memoryDriver() {
+  const driver = new MemoryDriver();
+  setQueue(driver);
+  await dispatch(new SendWelcome("a@x.com"));
+  const size: number = driver.size;
+  const queued: Dispatchable = driver.jobs[0]!.job;
+  await driver.push(() => doWork(), { queue: "default" });
+  const ran: number = await driver.work();
+  return { size, queued, ran };
+}
+
+// --- API reference: interfaces & types ---
+
+export const a: Dispatchable = new SendWelcome("a@x.com");
+export const b: Dispatchable = () => rebuildSearchIndex();
+
+export const opts: JobOptions = { delay: 60, queue: "emails" };
+
+export const logDriver: QueueDriver = {
+  async push(job, options) {
+    void job;
+    console.log("queued", options.queue ?? "default");
+  },
+};
+
+export function registerLogDriver() {
+  setQueue(logDriver);
+}
+
+export class ArrayDriver implements QueueDriver, Drainable {
+  private q: Dispatchable[] = [];
+  get size() {
+    return this.q.length;
+  }
+  async push(job: Dispatchable) {
+    this.q.push(job);
+  }
+  async work() {
+    let n = 0;
+    for (const job of this.q.splice(0)) {
+      await (job instanceof Job ? job.handle() : job());
+      n++;
+    }
+    return n;
+  }
+}
+
+export function queuedJobEntry(driver: MemoryDriver) {
+  const entry: QueuedJob = driver.jobs[0]!;
+  const lane: string | undefined = entry.options.queue;
+  return lane;
+}
+
+/* --- Retries, backoff, failure, priority, context, faking --- */
+
+import {
+  fakeQueue,
+  restoreQueue,
+  exponentialBackoff,
+  linearBackoff,
+  fixedBackoff,
+  noBackoff,
+  type Backoff,
+  type JobContext,
+  type FailedJob,
+} from "@shaferllc/keel/core";
+
+declare const stripe: { charge(amount: number): Promise<void> };
+declare function notifyBilling(orderId: number, error: unknown): Promise<void>;
+declare function log(message: string, context: Record<string, unknown>): void;
+
+export class ChargeCard extends Job {
+  static override maxRetries = 5;
+  static override backoff = exponentialBackoff(1_000);
+  static override queue = "billing";
+  static override priority = -5;
+
+  constructor(
+    private amount: number,
+    private orderId: number,
+  ) {
+    super();
+  }
+
+  async handle(): Promise<void> {
+    await stripe.charge(this.amount);
+  }
+
+  override async failed(error: unknown): Promise<void> {
+    await notifyBilling(this.orderId, error);
+  }
+}
+
+export class ImportFile extends Job {
+  static override maxRetries = 3;
+
+  async handle(): Promise<void> {
+    const { jobId, attempt, queue }: JobContext = this.context!;
+    if (attempt > 1) log("retrying import", { jobId, attempt, queue });
+  }
+}
+
+export async function overridingPolicy() {
+  await dispatch(new ChargeCard(100, 1), { maxRetries: 1, backoff: noBackoff });
+}
+
+export function backoffStrategies(): Backoff[] {
+  return [
+    exponentialBackoff(1_000),
+    exponentialBackoff(1_000, 30_000),
+    linearBackoff(5_000),
+    fixedBackoff(2_000),
+    noBackoff,
+  ];
+}
+
+export async function priorities() {
+  await dispatch(new ChargeCard(100, 1), { priority: -10 });
+  await dispatch(() => {}, { priority: 10 });
+}
+
+export async function inspectFailures(): Promise<FailedJob[]> {
+  await work();
+  return getQueue().failed;
+}
+
+export async function faking() {
+  const queue = fakeQueue();
+
+  await dispatch(new ChargeCard(100, 7));
+
+  queue.assertPushed(ChargeCard);
+  queue.assertPushed(ChargeCard, (job) => job instanceof ChargeCard);
+  queue.assertPushedCount(1, ChargeCard);
+  queue.assertNotPushed(ImportFile);
+
+  const [entry] = queue.pushedJobs(ChargeCard);
+  void entry?.options.delay;
+
+  restoreQueue();
+}
+
+export function nothingPushed() {
+  const queue = fakeQueue();
+  queue.assertNothingPushed();
+  restoreQueue();
+}

package/docs/examples/rate-limiting.ts

@@ -0,0 +1,42 @@
+// Type-check harness for docs/rate-limiting.md. Every type-checkable snippet in
+// the guide is exercised here against the real exports, so a renamed option or
+// wrong argument type fails `npm run typecheck:docs`. Compile-only — never run.
+import { rateLimiter, type RateLimiterOptions } from "@shaferllc/keel/core";
+import type { Context, MiddlewareHandler } from "hono";
+
+// Externals referenced by the narrative but not part of this module.
+declare const app: { use(mw: MiddlewareHandler): void };
+
+export function globalAndPerRoute() {
+  app.use(rateLimiter({ max: 60, window: 60 }));
+  app.use(rateLimiter({ max: 5, window: 60 }));
+}
+
+export function options() {
+  rateLimiter({
+    max: 60,
+    window: 60,
+    key: (c: Context) => c.req.header("x-api-key") ?? "anon",
+    message: "Slow down!",
+  });
+}
+
+export function defaults(): MiddlewareHandler {
+  // no arguments: 60 req / 60s, keyed by IP
+  return rateLimiter();
+}
+
+export function reused() {
+  const limit: MiddlewareHandler = rateLimiter({ max: 100, window: 60 });
+  return limit;
+}
+
+// Interface / type seam
+const perUser: RateLimiterOptions = {
+  max: 30,
+  window: 60,
+  key: (c) => c.req.header("authorization") ?? "anon",
+  message: "Easy there — try again shortly.",
+};
+const mw: MiddlewareHandler = rateLimiter(perUser);
+export { perUser, mw };

package/docs/examples/redis.ts

@@ -0,0 +1,99 @@
+// Type-check harness for docs/redis.md. Compile-only — never executed.
+import {
+  redis,
+  setRedis,
+  Redis,
+  MemoryRedis,
+  redisStore,
+  Cache,
+  type RedisConnection,
+} from "@shaferllc/keel/core";
+
+declare function computeStats(): Promise<unknown>;
+declare function renderHome(): string;
+declare function env(key: string): string;
+
+export async function using() {
+  setRedis(new MemoryRedis());
+  await redis().set("views", "1");
+  await redis().incr("views");
+  await redis().get("views");
+  await redis().set("token", "abc", { ex: 60 });
+  await redis().del("token");
+}
+
+export async function commands() {
+  const r = redis();
+  const s = await r.get("k");
+  await r.set("k", "v", { ex: 60 });
+  const removed = await r.del("a", "b");
+  const present = await r.exists("a");
+  const has = await r.has("k");
+  await r.incr("k");
+  await r.decr("k");
+  await r.incrBy("k", 5);
+  await r.expire("k", 60);
+  const ttl = await r.ttl("k");
+  const keys = await r.keys("user:*");
+  await r.flushAll();
+  return { s, removed, present, has, ttl, keys };
+}
+
+export async function jsonAndRemember() {
+  await redis().setJson("user:1", { id: 1, name: "Ada" });
+  const user = await redis().getJson<{ id: number; name: string }>("user:1");
+  const stats = await redis().remember("stats", 300, () => computeStats());
+  return { user, stats };
+}
+
+export async function asCacheStore() {
+  const cache = new Cache(redisStore(redis()));
+  return cache.remember("home", 60, () => renderHome());
+}
+
+export function upstashDriver() {
+  const upstash = (url: string, token: string): RedisConnection => {
+    const call = (...args: (string | number)[]) =>
+      fetch(url, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}` },
+        body: JSON.stringify(args),
+      }).then((r) => r.json() as Promise<{ result: unknown }>);
+    return {
+      async get(key) {
+        return ((await call("GET", key)).result as string) ?? null;
+      },
+      async set(key, value, o) {
+        await (o?.ex ? call("SET", key, value, "EX", o.ex) : call("SET", key, value));
+      },
+      async del(...keys) {
+        return (await call("DEL", ...keys)).result as number;
+      },
+      async exists(...keys) {
+        return (await call("EXISTS", ...keys)).result as number;
+      },
+      async incrBy(key, n) {
+        return (await call("INCRBY", key, n)).result as number;
+      },
+      async expire(key, s) {
+        return (await call("EXPIRE", key, s)).result === 1;
+      },
+      async ttl(key) {
+        return (await call("TTL", key)).result as number;
+      },
+      async keys(pattern) {
+        return (await call("KEYS", pattern)).result as string[];
+      },
+      async flushAll() {
+        await call("FLUSHALL");
+      },
+    };
+  };
+  setRedis(upstash(env("UPSTASH_URL"), env("UPSTASH_TOKEN")));
+}
+
+// Own client instance
+export function ownClient() {
+  const r = new Redis(new MemoryRedis());
+  return r.connection;
+}

package/docs/examples/request-response.ts

@@ -0,0 +1,197 @@
+// Type-check harness for docs/request-response.md. Every type-checkable snippet
+// in the reference is exercised here against the real exports, so a renamed
+// accessor or wrong argument type fails `npm run typecheck:docs`. Compile-only —
+// never executed. These accessors read an ambient request context, so the calls
+// only need to type-check, not run.
+import {
+  ctx,
+  json,
+  text,
+  html,
+  redirect,
+  request,
+  response,
+  param,
+  query,
+  header,
+  body,
+} from "@shaferllc/keel/core";
+
+declare const created: unknown;
+declare const rows: unknown;
+declare const csv: string;
+declare const token: string;
+declare const data: unknown;
+declare const user: { isAdmin: boolean } | undefined;
+declare function next(): Promise<void>;
+declare function log(path: string): void;
+declare function highlightNav(): void;
+declare function store(bytes: ArrayBuffer): Promise<void>;
+
+export async function readingInput() {
+  request.param("id");
+  request.query("q");
+  request.header("authorization");
+
+  await request.all();
+  await request.input("email");
+  const page = await request.input("page", 1); // number
+  await request.only(["email", "name"]);
+  await request.except(["password"]);
+
+  const body1 = await request.json<{ email: string }>();
+
+  // Raw body accessors for other content types.
+  const asText: string = await request.text();
+  const asBytes: ArrayBuffer = await request.arrayBuffer();
+  const asBlob: Blob = await request.blob();
+
+  return { page, body1, asText, asBytes, asBlob };
+}
+
+export function requestMeta() {
+  const method: string = request.method;
+  const path: string = request.path;
+  const url: string = request.url;
+  const status: number = request.status;
+  const raw: Request = request.raw;
+  const hasBody: boolean = request.hasBody();
+  const headers: Record<string, string> = request.headers();
+  const ip: string | undefined = request.ip();
+  const ips: string[] = request.ips();
+  return { method, path, url, status, raw, hasBody, headers, ip, ips };
+}
+
+export function requestUrl() {
+  const protocol: string = request.protocol;
+  const secure: boolean = request.secure;
+  const host: string = request.host;
+  const hostname: string = request.hostname;
+  const origin: string = request.origin;
+  const fullUrl: string = request.fullUrl;
+  const querystring: string = request.querystring;
+  return { protocol, secure, host, hostname, origin, fullUrl, querystring };
+}
+
+export async function middleware() {
+  await next();
+  if (request.status >= 500) log(request.path);
+}
+
+export function routeInfo() {
+  request.route;
+  const named: boolean = request.routeIs("users.show");
+  const tenant: string | undefined = request.subdomain("tenant");
+  if (request.routeIs("users.show")) highlightNav();
+  return { named, tenant };
+}
+
+export function cookiesRead() {
+  request.cookie("session");
+  request.cookie();
+}
+
+export async function fileUploads() {
+  const avatar = await request.file("avatar"); // File | undefined
+  const docs = await request.files("docs"); // File[]
+  const all = await request.allFiles(); // { field: File | File[] }
+
+  if (avatar) {
+    avatar.name;
+    avatar.size;
+    avatar.type;
+    const bytes = await avatar.arrayBuffer();
+    await store(bytes);
+  }
+  return { docs, all };
+}
+
+export function negotiation() {
+  const best: string | null = request.accepts([
+    "application/json",
+    "text/html",
+  ]);
+  const types: string[] = request.types();
+  const lang: string | null = request.language(["en", "fr"]);
+  const langs: string[] = request.languages();
+  const enc: string | null = request.encoding(["br", "gzip"]);
+  const encs: string[] = request.encodings();
+  const charset: string | null = request.charset(["utf-8"]);
+  const charsets: string[] = request.charsets();
+  return { best, types, lang, langs, enc, encs, charset, charsets };
+}
+
+export function negotiateSwitch(): Response {
+  switch (request.accepts(["application/json", "text/html"])) {
+    case "application/json":
+      return json(created);
+    case "text/html":
+      return html("<p>ok</p>");
+    default:
+      return response.abort("Not acceptable", 406);
+  }
+}
+
+export function responseBuilders() {
+  ctx().req.raw;
+
+  json({ ok: true });
+  json({ error: "nope" }, 422);
+  text("pong");
+  text("rate limited", 429);
+  html("<h1>Hi</h1>");
+  redirect("/login");
+  redirect("/", 301);
+}
+
+export function writingOutput() {
+  response.json({ ok: true });
+  response.text("hello");
+  response.html("<h1>Hi</h1>");
+  response.redirect("/login");
+  response.send(data);
+
+  response.status(201).json(created);
+  response.header("x-total", "42").json(rows);
+  response.headers({ "x-total": "42", "cache-control": "no-store" });
+  const ct: string | null = response.getHeader("content-type");
+  const has: boolean = response.hasHeader("cache-control");
+  void ct;
+  void has;
+  response.type("text/csv").append("vary", "accept");
+  response.removeHeader("x-powered-by");
+  response.cookie("flash", "saved").redirect("/");
+
+  response.cookie("session", token, { httpOnly: true, maxAge: 3600 });
+  response.clearCookie("session");
+
+  response.status(202).json({ queued: true });
+  response.type("text/csv").send(csv);
+  response.attachment("report.csv").type("text/csv").send(csv);
+  response.attachment().text("x");
+  response.back();
+  response.back("/dashboard");
+  redirect("back");
+  response.append("vary", "accept").append("vary", "accept-language");
+  response.send({ ok: true });
+  response.send("pong");
+}
+
+export function guards() {
+  response.abort("Not found", 404);
+}
+
+export function conditionalGuards() {
+  response.abortIf(!user, "Not found", 404);
+  response.abortUnless(user?.isAdmin, "Forbidden", 403);
+}
+
+export async function standaloneShortcuts() {
+  const id: string = param("id");
+  const allParams: Record<string, string> = param();
+  const q: string | undefined = query("q");
+  const allQuery: Record<string, string> = query();
+  const auth: string | undefined = header("authorization");
+  const payload = await body<{ email: string }>();
+  return { id, allParams, q, allQuery, auth, payload };
+}