@shaferllc/keel 0.66.0 → 0.74.0

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 };
+}

package/docs/examples/events.ts

@@ -0,0 +1,204 @@
+// Type-check harness for docs/events.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 {
+  emit,
+  listen,
+  events,
+  Events,
+  EventBuffer,
+  ServiceProvider,
+  type Listener,
+  type RecordedEvent,
+} from "@shaferllc/keel/core";
+
+declare const user: { id: number };
+declare function sendWelcomeEmail(u: unknown): void;
+declare function step1(): Promise<void>;
+declare function step2(): Promise<void>;
+declare function audit(id: number): void;
+declare function fulfill(id: number): Promise<void>;
+declare const handler: Listener;
+declare const listener: Listener;
+declare class Fulfillment {
+  ship(order: unknown): void;
+}
+
+export async function listenAndEmit() {
+  listen("user.registered", (u) => {
+    sendWelcomeEmail(u);
+  });
+  await emit("user.registered", user);
+
+  const off = listen("tick", () => {});
+  off();
+}
+
+export async function typedPayloads() {
+  type OrderPaid = { id: number; total: number };
+
+  listen<OrderPaid>("order.paid", (order) => {
+    order.total; // number
+  });
+
+  await emit<OrderPaid>("order.paid", { id: 1, total: 4200 });
+}
+
+// --- The typed event registry ---
+
+declare module "@shaferllc/keel/core" {
+  interface EventsList {
+    "invoice.settled": { id: number; cents: number };
+  }
+}
+
+export async function typedRegistry() {
+  // The payload type comes from the registry — no type argument needed.
+  listen("invoice.settled", (invoice) => {
+    invoice.cents; // number
+  });
+
+  await emit("invoice.settled", { id: 1, cents: 4200 });
+
+  // @ts-expect-error — `cents` must be a number, and the registry now enforces it.
+  await emit("invoice.settled", { id: 1, cents: "4200" });
+
+  // @ts-expect-error — a declared event can't be fired without its payload.
+  await emit("invoice.settled");
+
+  // @ts-expect-error — the listener's payload is checked against the registry too.
+  listen("invoice.settled", (invoice: { nope: boolean }) => invoice.nope);
+}
+
+export class EventServiceProvider extends ServiceProvider {
+  boot(): void {
+    listen("order.paid", (order) => this.app.make(Fulfillment).ship(order));
+  }
+}
+
+export function fullApi() {
+  events().once("boot", () => {});
+  events().off("tick", listener);
+  events().listenerCount("tick");
+  events().clear("tick");
+  events().clear();
+}
+
+export async function orderingAndAwaiting() {
+  listen("deploy", async () => { await step1(); });
+  listen("deploy", async () => { await step2(); });
+  await emit("deploy");
+}
+
+export async function errorBehavior() {
+  try {
+    await emit("user.registered", user);
+  } catch (err) {
+    void err;
+  }
+}
+
+// --- Events methods ---
+
+export function eventsOn() {
+  const off = events().on<{ id: number }>("user.deleted", (u) => audit(u.id));
+  off();
+}
+
+export function eventsOnce() {
+  events().once("boot", () => console.log("started"));
+}
+
+export function eventsOff() {
+  events().off("tick", handler);
+}
+
+export async function eventsEmit() {
+  await events().emit("order.paid", { id: 1, total: 4200 });
+}
+
+export function eventsListenerCount() {
+  if (events().listenerCount("tick") === 0) {
+    /* startClock() */
+  }
+}
+
+export function eventsClear() {
+  events().clear("tick");
+  events().clear();
+}
+
+// --- Global helpers ---
+
+export function helperEvents() {
+  events().once("boot", () => {});
+}
+
+export async function helperEmit() {
+  await emit("user.registered", user);
+}
+
+export function helperListen() {
+  const off = listen<{ id: number }>("user.deleted", (u) => audit(u.id));
+  return off;
+}
+
+// --- Interfaces & types ---
+
+const onPaid: Listener<{ id: number }> = async (order) => {
+  await fulfill(order.id);
+};
+listen("order.paid", onPaid);
+
+// The Events class is resolved via events(); referenced here for completeness.
+export type EventsType = Events;
+
+// --- onError / onAny ---
+
+declare function log(event: string, payload: unknown): void;
+
+export function errorHandling() {
+  events().onError((event, error, payload) => {
+    void event;
+    void error;
+    void payload;
+  });
+}
+
+export function observeEveryEvent() {
+  const off = events().onAny((event, payload) => log(event, payload));
+  off();
+}
+
+export function clearEverything() {
+  events().clearAll();
+}
+
+// --- Faking ---
+
+export async function faking() {
+  const buffer = events().fake();
+
+  await emit("invoice.settled", { id: 1, cents: 4200 });
+
+  buffer.assertEmitted("invoice.settled");
+  buffer.assertEmitted("invoice.settled", (invoice) => invoice.cents === 4200);
+  buffer.assertEmittedCount("invoice.settled", 1);
+  buffer.assertNotEmitted("user.deleted");
+
+  const all: RecordedEvent[] = buffer.all();
+  const payloads = buffer.payloadsFor("invoice.settled"); // typed via the registry
+  payloads[0]?.cents;
+
+  events().restore();
+  return { all, payloads };
+}
+
+export function fakeSomeEvents() {
+  events().fake("invoice.settled");
+  events().fake(["invoice.settled", "tick"]);
+  events().fake().assertNoneEmitted();
+  events().restore();
+}
+
+export type BufferType = EventBuffer;

package/docs/examples/factories.ts

@@ -0,0 +1,84 @@
+// Type-check harness for docs/factories.md. Compile-only — never executed.
+import {
+  factory,
+  Faker,
+  Seeder,
+  seed,
+  Model,
+  setConnection,
+  ModelFactory,
+  type Definition,
+  type Connection,
+} from "@shaferllc/keel/core";
+
+class User extends Model {
+  static table = "users";
+  declare id: number;
+}
+class Post extends Model {
+  static table = "posts";
+}
+
+declare const myConnection: Connection;
+declare const testConnection: Connection;
+
+const users = factory(User, (f, i) => ({ name: f.name(), email: `u${i}@x.com` }));
+
+export async function building() {
+  users.make();
+  users.make({ name: "Ada" });
+  await users.create();
+  await users.create({ role: "admin" });
+  const ten = await users.count(10).create();
+  const drafts = users.count(3).make();
+  users.usingFaker(new Faker(42));
+  return { ten, drafts };
+}
+
+export function faker() {
+  const f = new Faker(42);
+  return [
+    f.name(),
+    f.firstName(),
+    f.lastName(),
+    f.email(),
+    f.word(),
+    f.words(3),
+    f.sentence(),
+    f.paragraph(),
+    f.number(1, 100),
+    f.boolean(),
+    f.pick(["a", "b", "c"]),
+    f.slug(),
+    f.uuid(),
+  ];
+}
+
+class UserSeeder extends Seeder {
+  async run() {
+    await factory(User, (f) => ({ name: f.name() })).count(10).create();
+  }
+}
+class DatabaseSeeder extends Seeder {
+  async run() {
+    await this.call([UserSeeder]);
+  }
+}
+
+export async function seeding() {
+  setConnection(myConnection, "postgres");
+  await seed(DatabaseSeeder);
+}
+
+export async function inTests() {
+  setConnection(testConnection, "sqlite");
+  const created = await factory(User, (f) => ({ name: f.name() })).count(1).create();
+  const author = (created as User[])[0]!;
+  await factory(Post, (f) => ({ title: f.sentence() })).create({ user_id: author.id });
+}
+
+// type seams
+const def: Definition<User> = (f, i) => ({ name: f.name(), i });
+const own = factory(User, (f) => ({ name: f.name() }));
+export type UserFactory = ModelFactory<User>;
+export { def, own };

package/docs/examples/hashing.ts

@@ -0,0 +1,71 @@
+// Type-check harness for docs/hashing.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 { hash, encryption } from "@shaferllc/keel/core";
+
+declare const password: string;
+declare const plain: string;
+declare const submitted: string;
+declare const untrustedInput: string;
+declare const user: { password: string; save(): Promise<void> };
+declare function unauthorized(): Response;
+
+export async function hashingPasswords() {
+  const hashed = await hash.make(password); // store this
+  const ok = await hash.verify(hashed, password); // → true / false
+  return { hashed, ok };
+}
+
+export async function saltsDiffer() {
+  const a = await hash.make("hunter2");
+  const b = await hash.make("hunter2");
+  const sameString = a === b; // false — different salts
+  const va = await hash.verify(a, "hunter2");
+  const vb = await hash.verify(b, "hunter2");
+  return { sameString, va, vb };
+}
+
+export async function rotating() {
+  if (await hash.verify(user.password, plain)) {
+    if (hash.needsRehash(user.password)) {
+      user.password = await hash.make(plain);
+      await user.save();
+    }
+  }
+}
+
+export async function workFactor() {
+  const hashed = await hash.make(password, 200_000);
+  const atTarget = hash.needsRehash(hashed, 200_000); // false
+  const belowNew = hash.needsRehash(hashed, 300_000); // true
+  return { hashed, atTarget, belowNew };
+}
+
+export async function encryptingValues() {
+  const token = await encryption.encrypt({ userId: 1, scope: "reset" });
+  const data = await encryption.decrypt<{ userId: number }>(token);
+  return { token, data };
+}
+
+export async function decryptGuard() {
+  const value = await encryption.decrypt(untrustedInput);
+  if (value === null) return unauthorized();
+  return value;
+}
+
+export async function reference() {
+  const hashed = await hash.make(password);
+  const stronger = await hash.make(password, 200_000);
+
+  const authed = await hash.verify(user.password, submitted);
+
+  const needs = hash.needsRehash(user.password);
+  if (needs) {
+    user.password = await hash.make(plain);
+  }
+
+  const token = await encryption.encrypt({ userId: 1, scope: "reset" });
+  const decoded = await encryption.decrypt<{ userId: number }>(token);
+
+  return { hashed, stronger, authed, needs, token, decoded };
+}

package/docs/examples/health.ts

@@ -0,0 +1,94 @@
+// Type-check harness for docs/health.md. Compile-only — never executed.
+import {
+  health,
+  healthCheck,
+  check,
+  Result,
+  BaseCheck,
+  HealthChecks,
+  DatabaseCheck,
+  RedisCheck,
+  CacheCheck,
+  HttpKernel,
+  ServiceProvider,
+  type HealthReport,
+  type CheckReport,
+  type HealthStatus,
+} from "@shaferllc/keel/core";
+
+declare const env: { HEALTH_SECRET: string };
+declare function queue(): { size(): Promise<number> };
+
+export class HealthServiceProvider extends ServiceProvider {
+  boot(): void {
+    health().register([new DatabaseCheck(), new RedisCheck().cacheFor(30)]);
+
+    this.app.make(HttpKernel).use(healthCheck());
+  }
+}
+
+export function builtInChecks() {
+  health().register([
+    new DatabaseCheck(),
+    new DatabaseCheck("reporting"),
+    new RedisCheck(),
+    new CacheCheck(),
+  ]);
+}
+
+export function functionChecks() {
+  health().register([
+    check("stripe", async () => {
+      const res = await fetch("https://api.stripe.com/healthcheck");
+      return res.ok
+        ? Result.ok("Stripe is reachable")
+        : Result.failed(`Stripe returned ${res.status}`);
+    }),
+
+    check("queue-depth", async () => {
+      const depth = await queue().size();
+      if (depth > 10_000) return Result.failed(`Queue is backed up (${depth})`);
+      if (depth > 1_000) return Result.warning(`Queue is deep (${depth})`);
+      return Result.ok("Queue is keeping up").withMeta({ depth });
+    }),
+  ]);
+}
+
+export class QueueDepthCheck extends BaseCheck {
+  readonly name = "queue-depth";
+
+  constructor(private limit = 10_000) {
+    super();
+  }
+
+  async run(): Promise<Result> {
+    const depth = await queue().size();
+    return depth > this.limit
+      ? Result.failed(`Queue is backed up (${depth})`)
+      : Result.ok("Queue is keeping up").withMeta({ depth });
+  }
+}
+
+export function protectedEndpoint() {
+  return healthCheck({ secret: env.HEALTH_SECRET });
+}
+
+export function customBasePathAndRegistry() {
+  const checks = new HealthChecks().register([check("a", () => Result.ok("fine"))]);
+  return healthCheck({ basePath: "/_internal", checks });
+}
+
+export async function runningByHand(): Promise<{
+  report: HealthReport;
+  first: CheckReport | undefined;
+  status: HealthStatus;
+}> {
+  const report = await health().run();
+  return { report, first: report.checks[0], status: report.status };
+}
+
+export function inspectRegistry() {
+  const all: BaseCheck[] = health().all();
+  health().clear();
+  return all;
+}