@shaferllc/keel 0.66.0 → 0.68.0

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

package/docs/examples/helpers.ts

@@ -0,0 +1,171 @@
+// Type-check harness for docs/helpers.md. Every type-checkable snippet in the
+// guide is exercised here against the real exports, so a renamed helper or wrong
+// argument type fails `npm run typecheck:docs`. Compile-only — never executed.
+import {
+  app,
+  config,
+  view,
+  bind,
+  singleton,
+  instance,
+  make,
+  bound,
+  events,
+  emit,
+  listen,
+  cache,
+  logger,
+  Config,
+  type Listener,
+  type Token,
+  type Factory,
+  type Renderable,
+} from "@shaferllc/keel/core";
+
+// Stand-ins for app-defined values referenced in the guide.
+type User = { id: number };
+class Mailer {
+  constructor(_dep?: unknown) {}
+}
+
+declare const user: User;
+declare const order: { id: number };
+declare const code: string;
+declare const orderId: number;
+declare function computeStats(): Promise<{ total: number }>;
+declare function sendWelcome(u: User): void;
+declare function fulfil(id: number): void;
+declare function Welcome(props: { appName: string }): Renderable;
+declare function HomePage(): Renderable;
+
+// --- Intro ---
+export function intro() {
+  const name = config<string>("app.name", "Keel");
+  return name;
+}
+
+export async function introUsage() {
+  const stats = await cache().remember("stats", 60, () => computeStats());
+  await emit("user.registered", user);
+  logger().info("welcome sent", { userId: user.id });
+  return stats;
+}
+
+// --- Container helpers, up close ---
+export function containerHelpers() {
+  singleton(Mailer, (a) => new Mailer(a.make(Config)));
+  const mailer = make(Mailer);
+  if (bound("clock")) {
+    /* someone registered it */
+  }
+  return mailer;
+}
+
+// --- Events, cache, logger ---
+export async function servicesUpClose() {
+  listen("order.paid", (o: { id: number }) => fulfil(o.id));
+  await emit("order.paid", order);
+  events().listenerCount("order.paid");
+
+  await cache().put("otp", code, 300);
+  logger().warn("retrying", { attempt: 2 });
+}
+
+// --- Rendering a view ---
+function WelcomeInline({ appName }: { appName: string }): Renderable {
+  return `<h1>Welcome to ${appName}</h1>`;
+}
+
+export async function rendering() {
+  const a = await view(WelcomeInline, { appName: "Keel" });
+  const b = await view(HomePage);
+  return { a, b };
+}
+
+// --- API reference: app() ---
+export function appHelper() {
+  const port = app().config().get<number>("app.port", 3000);
+  return port;
+}
+
+// --- config() ---
+export function configHelper() {
+  const a = config<string>("app.name");
+  const b = config("app.port", 3000);
+  return { a, b };
+}
+
+// --- view() ---
+export async function viewHelper() {
+  const a = await view(Welcome, { appName: "Keel" });
+  const b = await view(HomePage);
+  return { a, b };
+}
+
+// --- bind() ---
+export function bindHelper() {
+  bind("clock", () => new Date());
+}
+
+// --- singleton() ---
+export function singletonHelper() {
+  singleton(Mailer, (a) => new Mailer(a.make(Config)));
+}
+
+// --- instance() ---
+export function instanceHelper() {
+  const version = instance("app.version", "0.30.0");
+  return version;
+}
+
+// --- make() ---
+export function makeHelper() {
+  const mailer = make(Mailer);
+  const version = make<string>("app.version");
+  return { mailer, version };
+}
+
+// --- bound() ---
+export function boundHelper() {
+  if (bound("clock")) return make<Date>("clock");
+  return new Date();
+}
+
+// --- events() ---
+export function eventsHelper() {
+  events().listenerCount("order.paid");
+  events().clear("order.paid");
+}
+
+// --- emit() ---
+export async function emitHelper() {
+  await emit("user.registered", user);
+}
+
+// --- listen() ---
+export function listenHelper() {
+  const off = listen("user.registered", (u: User) => sendWelcome(u));
+  off();
+}
+
+// --- cache() ---
+export async function cacheHelper() {
+  const stats = await cache().remember("stats", 60, () => computeStats());
+  await cache().put("otp", code, 300);
+  return stats;
+}
+
+// --- logger() ---
+export function loggerHelper() {
+  logger().info("user registered", { userId: user.id });
+  logger().error("payment failed", { orderId });
+}
+
+// --- Interfaces & types ---
+const onOrder: Listener<{ id: number }> = async (o) => fulfil(o.id);
+const strToken: Token<string> = "app.version";
+const svcToken: Token<Mailer> = Mailer;
+const mailerFactory: Factory<Mailer> = (a) => new Mailer(a.make(Config));
+const renderable: Renderable = "<p>hi</p>";
+
+export { onOrder, strToken, svcToken, mailerFactory, renderable };

package/docs/examples/hooks.ts

@@ -0,0 +1,54 @@
+// Type-check harness for docs/hooks.md. Compile-only — never executed.
+import {
+  Application,
+  Router,
+  onReady,
+  onShutdown,
+  terminate,
+  logger,
+  redis,
+  type LifecycleHook,
+} from "@shaferllc/keel/core";
+
+declare function warmCaches(): Promise<void>;
+
+export function globalHooks() {
+  onReady(async () => {
+    await warmCaches();
+    logger().info("app ready");
+  });
+  onShutdown(async () => {
+    await redis().flushAll();
+  });
+}
+
+export function signals() {
+  for (const signal of ["SIGINT", "SIGTERM"] as const) {
+    process.on(signal, async () => {
+      await terminate();
+      process.exit(0);
+    });
+  }
+}
+
+export async function methodForm() {
+  const app = new Application();
+  app
+    .onReady((a) => void a)
+    .onShutdown(async () => {});
+  await app.boot([], { discoverConfig: false, config: { app: {} } });
+  const done: boolean = app.isTerminated;
+  await app.terminate();
+  return done;
+}
+
+export function routeHook(app: Application) {
+  const router = app.make(Router);
+  router.onRoute((def) => {
+    logger().debug("route", { methods: def.methods, path: def.path, name: def.name });
+  });
+}
+
+// The hook type
+const ready: LifecycleHook = (app) => void app;
+export { ready };