@shaferllc/keel 0.66.0 → 0.68.0

package/docs/examples/container.ts

@@ -0,0 +1,134 @@
+// Type-check harness for docs/container.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 {
+  Container,
+  Application,
+  ServiceProvider,
+  bind,
+  singleton,
+  instance,
+  make,
+  bound,
+  alias,
+  swap,
+  restore,
+  type Ctx,
+  type Token,
+  type Constructor,
+  type Factory,
+} from "@shaferllc/keel/core";
+
+// Stand-ins for app-defined services referenced in the guide.
+class Mailer {
+  constructor(_dep?: unknown) {}
+}
+class ReportService {
+  constructor(private app: Container) {}
+}
+class Router {
+  constructor(_app?: unknown) {}
+}
+declare const fakeMailer: Mailer;
+
+declare const app: Container;
+
+export class AppServiceProvider extends ServiceProvider {
+  register(): void {
+    this.app.bind("clock", () => new Date());
+    this.app.singleton(Mailer, (app) => new Mailer(app.make("config")));
+    this.app.instance("version", "0.1.0");
+  }
+}
+
+export function globalHelpers() {
+  bind("clock", () => new Date());
+  singleton(Mailer, (app) => new Mailer(app));
+  instance("version", "0.6.0");
+
+  const mailer = make(Mailer);
+  const version = make<string>("version");
+  if (bound("clock")) {
+    /* … */
+  }
+  return { mailer, version };
+}
+
+export function resolving() {
+  const mailer = make(Mailer);
+  const version = make<string>("version");
+
+  const report = app.make(ReportService); // no explicit binding
+
+  make("nope"); // throws at runtime; type-checks fine
+  const clock = bound("clock") ? make<Date>("clock") : new Date();
+  return { mailer, version, report, clock };
+}
+
+export class InvoiceController {
+  constructor(private app: Container) {}
+
+  index(c: Ctx) {
+    const config = this.app.make(Application).config();
+    return c.json({ currency: config.get("app.currency", "USD") });
+  }
+}
+
+export function containerReference() {
+  app.bind("clock", () => new Date());
+  app.bind(Mailer, (c) => new Mailer(c.make("config")));
+  app.singleton(Mailer, (c) => new Mailer(c.make("config")));
+  const version = app.instance("version", "0.30.0");
+
+  const mailer = app.make(Mailer);
+  const ver = app.make<string>("version");
+  const same = app.get(Mailer);
+  const report = app.build(ReportService);
+  const isBound = app.bound("clock");
+
+  return { version, mailer, ver, same, report, isBound };
+}
+
+export function helperReference() {
+  bind("clock", () => new Date());
+  singleton(Mailer, (app) => new Mailer(app));
+  const version = instance("version", "0.30.0");
+  const mailer = make(Mailer);
+  const ver = make<string>("version");
+  const isBound = bound("clock");
+  return { version, mailer, ver, isBound };
+}
+
+export function aliasesAndSwapping() {
+  // Guide: Aliases
+  alias("router", Router);
+  const viaAlias = make(Router);
+
+  // Guide: Swapping bindings in tests (global-helper forms)
+  swap(Mailer, () => fakeMailer);
+  make(Mailer);
+  restore(Mailer);
+  restore();
+
+  return { viaAlias };
+}
+
+export function aliasesAndSwappingContainer() {
+  app.singleton(Router, () => new Router(app));
+  app.alias("router", Router);
+  const same = app.make("router") === app.make(Router);
+
+  app.swap(Mailer, () => fakeMailer);
+  app.make(Mailer);
+  app.restore(Mailer);
+  app.restore();
+  return { same };
+}
+
+// Type seams.
+const nameKey: Token<string> = "app.name";
+const svcKey: Token<Mailer> = Mailer;
+const ctor: Constructor<ReportService> = ReportService;
+const mailerFactory: Factory<Mailer> = (app) => new Mailer(app.make("config"));
+
+export { nameKey, svcKey, ctor, mailerFactory };

package/docs/examples/controllers.ts

@@ -0,0 +1,86 @@
+// Type-check harness for docs/controllers.md. Every type-checkable snippet in
+// the guide is exercised here against the real exports, so a renamed method or a
+// wrong handler shape fails `npm run typecheck:docs`. Compile-only — never run.
+import {
+  json,
+  param,
+  Container,
+  type Ctx,
+  type RouteHandler,
+} from "@shaferllc/keel/core";
+
+// A stand-in service the DI example resolves.
+class Mailer {
+  send() {}
+}
+
+// --- Basic controller: methods are actions, take Ctx or nothing ---
+export class PostController {
+  index() {
+    return json({ posts: [] });
+  }
+
+  // Take the context explicitly…
+  show(c: Ctx) {
+    return c.json({ id: c.req.param("id") });
+  }
+
+  // …or lean on the ambient helpers and drop the argument.
+  edit() {
+    return json({ id: param("id") });
+  }
+}
+
+// --- Dependency injection: constructor receives the container ---
+export class UserController {
+  constructor(private app: Container) {}
+
+  store() {
+    const mailer = this.app.make(Mailer);
+    return json({ sent: typeof mailer.send });
+  }
+
+  show(c: Ctx) {
+    const id = c.req.param("id");
+    const q = c.req.query("expand");
+    return c.json({ id, expand: q });
+  }
+}
+
+// --- Single-action controller: define handle() ---
+export class PublishPost {
+  handle() {
+    return json({ published: true });
+  }
+}
+
+// --- Resource controller: the seven conventional actions ---
+export class ResourcePostController {
+  index(c: Ctx) { return c.json({ action: "index" }); }
+  create(c: Ctx) { return c.json({ action: "create" }); }
+  store(c: Ctx) { return c.json({ action: "store" }); }
+  show(c: Ctx) { return c.json({ action: "show" }); }
+  edit(c: Ctx) { return c.json({ action: "edit" }); }
+  update(c: Ctx) { return c.json({ action: "update" }); }
+  destroy(c: Ctx) { return c.json({ action: "destroy" }); }
+}
+
+// --- Default export, for the lazy-loading snippet ---
+export default class ReportController {
+  index(c: Ctx) {
+    return c.json({ action: "index" });
+  }
+}
+
+// --- RouteHandler: every arm of the union type-checks ---
+export function handlerForms() {
+  const closure: RouteHandler = () => json({ ok: true });
+  const staticResp: RouteHandler = json({ status: "ok" });
+  const action: RouteHandler = [UserController, "show"];
+  const single: RouteHandler = [PublishPost];
+  const lazy: RouteHandler = [
+    () => Promise.resolve({ default: ReportController }),
+    "index",
+  ];
+  return { closure, staticResp, action, single, lazy };
+}

package/docs/examples/database.ts

@@ -0,0 +1,118 @@
+// Type-check harness for docs/database.md. Every 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 {
+  db,
+  setConnection,
+  type Connection,
+  type WriteResult,
+  type Row,
+  type Dialect,
+  type Operator,
+} from "@shaferllc/keel/core";
+
+declare const email: string;
+declare const name: string;
+declare const now: number;
+
+export async function connect() {
+  const d1 = {} as {
+    prepare(sql: string): {
+      bind(...b: unknown[]): {
+        all(): Promise<{ results: Row[]; meta: { changes: number; last_row_id: number } }>;
+        run(): Promise<{ meta: { changes: number; last_row_id: number } }>;
+      };
+    };
+  };
+
+  const connection: Connection = {
+    select: (sql, bindings) => d1.prepare(sql).bind(...bindings).all().then((r) => r.results),
+    write: async (sql, bindings) => {
+      const r = await d1.prepare(sql).bind(...bindings).run();
+      return { rowsAffected: r.meta.changes, insertId: r.meta.last_row_id };
+    },
+  };
+  setConnection(connection, "sqlite");
+  setConnection(connection, "postgres");
+}
+
+export async function querying() {
+  await db("users").where("active", true).orderBy("name").get();
+  await db("users").where("id", 1).first();
+  await db("users").where("age", ">", 18).count();
+  await db("posts").whereIn("id", [1, 2, 3]).get();
+  await db("posts").whereNull("deleted_at").limit(20).offset(40).get();
+  await db("orders").select("id", "total").where("status", "paid").orWhere("status", "shipped").get();
+}
+
+export async function writing() {
+  const id = await db("users").insertGetId({ email, name });
+  await db("users").where("id", id).update({ name: "Grace" });
+  await db("users").where("id", id).delete();
+}
+
+export async function typedRows() {
+  type User = {
+    id: number;
+    email: string;
+  };
+  const user = await db<User>("users").where("id", 1).first();
+  const all = await db<User>("users").get();
+  return { user, all };
+}
+
+export async function reference() {
+  db("users");
+  db<{ id: number }>("users");
+
+  db("users").select("id", "email").get();
+  db("users").where("active", true);
+  db("users").where("age", ">", 18);
+  db("users").where("email", "like", "%@example.com");
+  db("orders").where("status", "paid").orWhere("status", "shipped").get();
+  db("posts").whereIn("id", [1, 2, 3]).get();
+  db("posts").whereNull("deleted_at").get();
+  db("users").whereNotNull("verified_at").get();
+  db("users").orderBy("last_name").orderBy("created_at", "desc").get();
+  db("posts").limit(20).offset(40).get();
+
+  const rows = await db("users").where("active", true).get();
+  const first = await db("users").where("email", email).first();
+  const active = await db("users").where("active", true).count();
+  const taken = await db("users").where("email", email).exists();
+
+  const result: WriteResult = await db("users").insert({ email, name });
+  const newId = await db("users").insertGetId({ email, name });
+  const upd: WriteResult = await db("users").where("id", 1).update({ name: "Grace" });
+  await db("sessions").where("expires_at", "<", now).delete();
+
+  return { rows, first, active, taken, result, newId, upd };
+}
+
+export async function ormExtras() {
+  await db("posts").whereBetween("views", [10, 100]).get();
+  await db("posts").whereNotIn("id", [4, 5]).get();
+  await db("posts").whereLike("title", "%keel%").get();
+  await db("posts").latest().get();
+  await db("posts").oldest("published_at").get();
+
+  const total: number = await db("orders").where("paid", true).sum("total");
+  const a: number = await db("orders").avg("total");
+  const mn: number = await db("orders").min("total");
+  const mx: number = await db("orders").max("total");
+  const email = await db("users").where("id", 1).value<string>("email");
+  const titles = await db("posts").pluck<string>("title");
+  const page = await db("posts").latest().paginate(2, 15);
+  const rows = page.data;
+  return { total, a, mn, mx, email, titles, page: page.currentPage, last: page.lastPage, rows };
+}
+
+// Interface / type seams
+const mock: Connection = {
+  select: async () => [{ id: 1 }],
+  write: async (): Promise<WriteResult> => ({ rowsAffected: 1, insertId: 1 }),
+};
+const dialect: Dialect = "postgres";
+const op: Operator = "like";
+const row: Row = { id: 1 };
+export { mock, dialect, op, row };

package/docs/examples/debugging.ts

@@ -0,0 +1,41 @@
+// Type-check harness for docs/debugging.md. Every type-checkable snippet in the
+// reference is exercised here against the real exports, so a renamed function or
+// wrong argument type fails `npm run typecheck:docs`. Compile-only — never run.
+import { dump, dd } from "@shaferllc/keel/core";
+
+declare const user: { id: number; name: string };
+declare const order: { total: number };
+declare const request: {
+  all(): Promise<Record<string, unknown>>;
+  headers(): Record<string, string>;
+};
+declare function computeTotal(): number;
+declare function save(): Promise<{ id: number }>;
+
+export function dumpBasics() {
+  dump(user, order); // logs both, returns `user`
+
+  const total = dump(computeTotal()); // logs the total AND uses it
+  return total;
+}
+
+export async function dumpInline() {
+  return dump(await save()); // inspect the saved value, still return it
+}
+
+export function dumpReference() {
+  const first = dump(user, order, request); // returns `user`
+  first.name; // typed as the first argument's type
+  return first;
+}
+
+export async function ddBasics() {
+  dd(await request.all(), request.headers());
+  // unreachable — dd() throws
+}
+
+export async function ddReference() {
+  // `dd` returns `never`, so TS treats everything after it as unreachable.
+  const value = await request.all();
+  dd(value);
+}

package/docs/examples/decorators.ts

@@ -0,0 +1,40 @@
+// Type-check harness for docs/decorators.md. Compile-only — never executed.
+import {
+  decorateRequest,
+  decorated,
+  setRequestValue,
+  hasRequestDecorator,
+  clearRequestDecorators,
+  type RequestResolver,
+} from "@shaferllc/keel/core";
+
+type User = { id: number; name: string };
+declare function findUser(auth: string | undefined): Promise<User | null>;
+
+export function registering() {
+  decorateRequest("locale", (c) => c.req.header("accept-language") ?? "en");
+  decorateRequest("user", async (c) => findUser(c.req.header("authorization")));
+  decorateRequest("tenant", (c) => c.req.header("x-tenant") ?? "public");
+}
+
+export async function accessing() {
+  const locale = await decorated<string>("locale");
+  const user = await decorated<User | null>("user");
+  const tenant = await decorated<string>("tenant");
+  return { locale, user, tenant };
+}
+
+export async function setting(theUser: User) {
+  setRequestValue("user", theUser);
+  return decorated<User>("user");
+}
+
+export function introspection() {
+  const has = hasRequestDecorator("user");
+  clearRequestDecorators();
+  return has;
+}
+
+// The resolver type
+const resolver: RequestResolver<string> = (c) => c.req.path;
+export { resolver };

package/docs/examples/errors.ts

@@ -0,0 +1,121 @@
+// Type-check harness for docs/errors.md. Every type-checkable snippet in the
+// reference is exercised here against the real exports, so a renamed field or a
+// wrong constructor signature fails `npm run typecheck:docs`. Compile-only —
+// never executed.
+import {
+  HttpException,
+  NotFoundException,
+  UnauthorizedException,
+  ForbiddenException,
+  ValidationException,
+  createError,
+  STATUS_TEXT,
+  HttpKernel,
+  Application,
+} from "@shaferllc/keel/core";
+import type { Context } from "hono";
+
+// createError --------------------------------------------------------------
+export const InsufficientFunds = createError("E_FUNDS", "Balance too low: need %s", 402);
+export const TenantSuspended = createError("E_TENANT_SUSPENDED", "Tenant %s is suspended.", 403);
+export const RateExceeded = createError("E_RATE", "Slow down.", 429);
+
+export function throwCoded(): never {
+  const err = new InsufficientFunds("$40");
+  const isHttp: boolean = err instanceof HttpException;
+  void isHttp;
+  throw err;
+}
+
+// HTTP exceptions ----------------------------------------------------------
+export function httpExceptions(): never {
+  throw new NotFoundException("Widget not found"); // 404
+}
+
+export function moreThrows() {
+  const throwers: Array<() => never> = [
+    () => {
+      throw new UnauthorizedException();
+    },
+    () => {
+      throw new ForbiddenException();
+    },
+    () => {
+      throw new HttpException(429, "Slow down");
+    },
+    () => {
+      throw new HttpException(503, "Down for maintenance", { "Retry-After": "120" });
+    },
+    () => {
+      throw new HttpException(429, "Slow down", { "Retry-After": "30" });
+    },
+    () => {
+      throw new HttpException(409, "That email is taken");
+    },
+    () => {
+      throw new HttpException(429); // message defaults to "Too Many Requests"
+    },
+  ];
+  return throwers;
+}
+
+// Validation ---------------------------------------------------------------
+export function validation(): never {
+  throw new ValidationException({
+    email: ["The email is invalid."],
+    password: ["Too short.", "Must contain a number."],
+  });
+}
+
+export function readsErrors() {
+  const ex = new ValidationException({ email: ["nope"] });
+  const fields: Record<string, string[]> = ex.errors;
+  return fields;
+}
+
+// Fields the kernel reads --------------------------------------------------
+export function fields() {
+  const ex = new HttpException(503, "Down", { "Retry-After": "120" });
+  const status: number = ex.status;
+  const headers: Record<string, string> | undefined = ex.headers;
+  ex.code = "E_DOWN";
+  const code: string | undefined = ex.code;
+  return { status, headers, code };
+}
+
+// Custom exception with self-render / self-report --------------------------
+declare const metrics: { increment(name: string): void };
+
+export class PaymentRequiredException extends HttpException {
+  code = "E_PAYMENT_REQUIRED";
+
+  constructor() {
+    super(402, "Payment is required to continue.");
+  }
+
+  handle(c: Context) {
+    // hono's `json` wants a status-code literal; the exception's numeric
+    // `status` is asserted to it (402 here).
+    return c.json({ error: this.message, code: this.code, upgrade: "/billing" }, this.status as 402);
+  }
+
+  report() {
+    metrics.increment("payment_required");
+  }
+}
+
+// Custom error handler on the kernel ---------------------------------------
+export class Kernel extends HttpKernel {
+  constructor(app: Application) {
+    super(app);
+    this.onError((_err, c) => c.json({ oops: true }, 500));
+  }
+}
+
+// STATUS_TEXT --------------------------------------------------------------
+export function statusText() {
+  const notFound: string | undefined = STATUS_TEXT[404]; // "Not Found"
+  const expired: string | undefined = STATUS_TEXT[419]; // "Page Expired"
+  const fallback: string = STATUS_TEXT[418] ?? "Error"; // not in the map
+  return { notFound, expired, fallback };
+}