@shaferllc/keel 0.66.0 → 0.74.0

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

package/docs/examples/i18n.ts

@@ -0,0 +1,117 @@
+// Type-check harness for docs/i18n.md. Compile-only — never executed.
+import {
+  i18n,
+  t,
+  setI18n,
+  getI18n,
+  setTranslations,
+  detectLocale,
+  negotiateLocale,
+  formatMessage,
+  objectLoader,
+  I18n,
+  I18nManager,
+  HttpKernel,
+  ServiceProvider,
+  listen,
+  logger,
+  type TranslationsByLocale,
+  type TranslationLoader,
+  type I18nOptions,
+  type DetectLocaleOptions,
+} from "@shaferllc/keel/core";
+
+declare const order: { createdAt: Date };
+declare const post: { publishedAt: Date };
+declare const names: string[];
+
+export class I18nServiceProvider extends ServiceProvider {
+  boot(): void {
+    setI18n(new I18nManager({ defaultLocale: "en" }));
+
+    setTranslations({
+      en: { "cart.items": "{count, plural, one {# item} other {# items}}" },
+      fr: { "cart.items": "{count, plural, one {# article} other {# articles}}" },
+    });
+
+    this.app.make(HttpKernel).use(detectLocale());
+  }
+}
+
+export function translating() {
+  return [t("cart.items", { count: 3 }), i18n("fr").t("cart.items", { count: 3 })];
+}
+
+export function formatters() {
+  const l: I18n = i18n();
+  return {
+    number: l.formatNumber(1234.5),
+    currency: l.formatCurrency(9.5, "USD"),
+    date: l.formatDate(order.createdAt),
+    time: l.formatTime(order.createdAt),
+    relative: l.formatRelativeTime(post.publishedAt),
+    relativeUnit: l.formatRelativeTime(post.publishedAt, "hour"),
+    list: l.formatList(["a", "b", "c"]),
+    or: l.formatList(names, { type: "disjunction" }),
+    plural: l.formatPlural(5),
+    display: l.formatDisplayName("fr"),
+    has: l.has("cart.items"),
+    locale: l.locale,
+  };
+}
+
+export function detection(): DetectLocaleOptions[] {
+  return [{}, { query: "lang" }, { cookie: "locale" }, { header: false }, { resolve: () => "fr" }];
+}
+
+export function middleware() {
+  return [detectLocale(), detectLocale({ query: "lang", cookie: "locale" })];
+}
+
+export function negotiating() {
+  return negotiateLocale("fr-CA,fr;q=0.9,en;q=0.8", ["en", "fr"], "en");
+}
+
+export function messages() {
+  return [
+    formatMessage("Hello {name}!", { name: "Ada" }),
+    formatMessage("{count, plural, =0 {Empty} one {# item} other {# items}}", { count: 3 }, "en"),
+    formatMessage("{n, selectordinal, one {#st} other {#th}}", { n: 1 }, "en"),
+    formatMessage("{gender, select, male {He} other {They}}", { gender: "male" }),
+    formatMessage("{n, number, ::currency/USD}", { n: 9.5 }, "en-US"),
+  ];
+}
+
+export function fallbacks() {
+  setTranslations({
+    es: { greeting: "Hola", chair: "silla" },
+    "es-MX": { chair: "banca" },
+  });
+
+  return [i18n("es-MX").t("chair"), i18n("es-MX").t("greeting")];
+}
+
+export function missingKeys() {
+  listen("i18n.missing", (payload) => {
+    const { key, locale } = payload as { key: string; locale: string };
+    logger().warn("missing translation", { key, locale });
+  });
+
+  const options: I18nOptions = {
+    defaultLocale: "en",
+    supportedLocales: ["en", "fr"],
+    fallbackLocales: { "es-MX": "es" },
+    missing: (key, locale) => `[${locale}:${key}]`,
+  };
+  return new I18nManager(options);
+}
+
+export async function loaders() {
+  const data: TranslationsByLocale = { en: { hi: "Hi" } };
+  const loader: TranslationLoader = objectLoader(data);
+
+  const manager = new I18nManager();
+  await manager.load(loader);
+
+  return { manager, supported: manager.supported(), active: getI18n().defaultLocale };
+}

package/docs/examples/inertia.ts

@@ -0,0 +1,81 @@
+// Type-check harness for docs/inertia.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 {
+  ServiceProvider,
+  singleton,
+  Inertia,
+  inertia,
+  inertiaPageAttr,
+  type InertiaPage,
+  type InertiaOptions,
+} from "@shaferllc/keel/core";
+
+declare const user: { id: number; name: string };
+declare const stats: unknown;
+declare const notifications: unknown;
+declare const activity: unknown;
+declare const page: InertiaPage;
+declare const rootView: (page: InertiaPage) => string;
+
+// Configure it
+export class InertiaServiceProvider extends ServiceProvider {
+  register(): void {
+    singleton(
+      Inertia,
+      () =>
+        new Inertia({
+          version: "1",
+          rootView: (page) =>
+            `<!DOCTYPE html><html><head><meta charset="utf-8"></head>` +
+            `<body><div id="app" data-page="${inertiaPageAttr(page)}"></div>` +
+            `<script src="/assets/app.js"></script></body></html>`,
+        }),
+    );
+  }
+}
+
+// Render a page
+export function render() {
+  const a: Response | string = inertia("Users/Show", { user });
+  const b: Response | string = inertia("Dashboard");
+  return { a, b };
+}
+
+// Partial reload example
+export function partial() {
+  return inertia("Dashboard", { stats, notifications, activity });
+}
+
+// Reference: inertiaPageAttr
+export function attr() {
+  return `<div id="app" data-page="${inertiaPageAttr(page)}"></div>`;
+}
+
+// Reference: Inertia class
+export function classUsage() {
+  const i = new Inertia({
+    version: "1",
+    rootView: (page) => `<div id="app" data-page="${inertiaPageAttr(page)}"></div>`,
+  });
+  const html: Response | string = i.render("Dashboard", { title: "Welcome" });
+  const noProps: Response | string = i.render("Dashboard");
+  return { html, noProps };
+}
+
+// Interface / type seams
+const options: InertiaOptions = {
+  version: "abc123",
+  rootView: (page) => `<div id="app" data-page="${inertiaPageAttr(page)}"></div>`,
+};
+
+const pageSeam: InertiaPage = {
+  component: "Users/Show",
+  props: { user },
+  url: "/users/1",
+  version: "1",
+};
+
+const _rootView = rootView;
+
+export { options, pageSeam, _rootView };

package/docs/examples/locks.ts

@@ -0,0 +1,120 @@
+// Type-check harness for docs/locks.md. Compile-only — never executed.
+import {
+  lock,
+  restoreLock,
+  setLockStore,
+  getLockStore,
+  Lock,
+  MemoryLockStore,
+  LockNotHeldError,
+  type LockStore,
+  type AcquireOptions,
+} from "@shaferllc/keel/core";
+
+declare const invoice: { id: number };
+declare function charge(invoice: { id: number }): Promise<void>;
+declare function rebuild(): Promise<void>;
+declare function process(batch: unknown): Promise<void>;
+declare const batches: unknown[];
+
+export async function running() {
+  const [ran, result] = await lock("invoice:42").run(() => charge(invoice));
+  if (!ran) return undefined;
+  return result;
+}
+
+export async function waiting() {
+  const options: AcquireOptions = { timeout: 5_000, retryDelay: 100 };
+  const [ran] = await lock("report").run(() => rebuild(), options);
+
+  const [immediate] = await lock("report").runImmediately(() => rebuild());
+  return { ran, immediate };
+}
+
+export async function ttlAndExtend() {
+  const l = lock("import", 60_000);
+  await l.run(async () => {
+    for (const batch of batches) {
+      await process(batch);
+      await l.extend();
+    }
+  });
+}
+
+export async function manualAcquisition() {
+  const l = lock("invoice:42");
+  if (!(await l.acquire({ timeout: 2_000 }))) return;
+
+  try {
+    await charge(invoice);
+  } finally {
+    await l.release();
+  }
+}
+
+export async function handoff(): Promise<string> {
+  const l = lock("import:99", 60_000);
+  await l.acquire();
+  return l.serialize();
+}
+
+export async function resume(serialized: string) {
+  const l = restoreLock(serialized);
+  await l.extend(60_000);
+  await l.release();
+}
+
+export async function inspecting() {
+  const l = lock("k");
+  return {
+    locked: await l.isLocked(),
+    expired: await l.isExpired(),
+    remaining: await l.getRemainingTime(),
+  };
+}
+
+export function testing() {
+  setLockStore(new MemoryLockStore());
+  return getLockStore();
+}
+
+export function errors(err: unknown) {
+  return err instanceof LockNotHeldError;
+}
+
+// A custom store (the shape of the Redis / database recipes).
+export function customStore(): LockStore {
+  const entries = new Map<string, { owner: string; expiresAt: number }>();
+  return {
+    async acquire(key, owner, ttlMs) {
+      const existing = entries.get(key);
+      if (existing && existing.expiresAt > Date.now()) return false;
+      entries.set(key, { owner, expiresAt: Date.now() + ttlMs });
+      return true;
+    },
+    async release(key, owner) {
+      const entry = entries.get(key);
+      if (!entry || entry.owner !== owner) return false;
+      entries.delete(key);
+      return true;
+    },
+    async extend(key, owner, ttlMs) {
+      const entry = entries.get(key);
+      if (!entry || entry.owner !== owner) return false;
+      entry.expiresAt = Date.now() + ttlMs;
+      return true;
+    },
+    async isLocked(key) {
+      const entry = entries.get(key);
+      return !!entry && entry.expiresAt > Date.now();
+    },
+    async remainingTime(key) {
+      const entry = entries.get(key);
+      return entry ? entry.expiresAt - Date.now() : null;
+    },
+  };
+}
+
+export function direct(): Lock {
+  return new Lock("k", 1_000, new MemoryLockStore());
+}

package/docs/examples/logger.ts

@@ -0,0 +1,166 @@
+// Type-check harness for docs/logger.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 {
+  logger,
+  Logger,
+  requestLogger,
+  requestLog,
+  HttpKernel,
+  type LoggerOptions,
+  type LogLevel,
+} from "@shaferllc/keel/core";
+
+declare const user: { id: number };
+declare const key: string;
+declare const orderId: number;
+declare const err: unknown;
+declare const sql: string;
+declare const ms: number;
+declare const requestId: string;
+declare const jobId: string;
+
+export function logging() {
+  logger().info("user registered", { userId: user.id });
+  logger().warn("cache miss", { key });
+  logger().error("payment failed", { orderId, error: String(err) });
+  logger().debug("query", { sql, ms });
+}
+
+export function levels() {
+  const threshold: LogLevel = "warn";
+  new Logger({ level: threshold });
+}
+
+export function childLoggers() {
+  const log = logger().child({ requestId });
+  log.info("handling");
+  log.info("done");
+
+  const base = logger().child({ service: "billing" });
+  const job = base.child({ jobId });
+  job.info("start");
+}
+
+export function constructing() {
+  const log = new Logger({ level: "debug", pretty: true, bindings: { env: "dev" } });
+  log.debug("boot", { pid: 1 });
+
+  const bare = new Logger();
+  bare.info("no options");
+}
+
+export function reference() {
+  logger().info("ready");
+
+  const log = new Logger({ level: "warn", pretty: true });
+  log.debug("cache lookup", { key });
+  log.info("user registered", { userId: 42 });
+  log.warn("cache miss", { key });
+  log.error("payment failed", { orderId, error: String(err) });
+
+  const reqLog = logger().child({ requestId });
+  reqLog.info("handling");
+}
+
+export function redaction() {
+  const log = new Logger({ redact: ["password", "req.headers.authorization"] });
+  log.info("login", {
+    user: "ada",
+    password: "s3cret",
+    req: { headers: { authorization: "Bearer x" } },
+  });
+}
+
+export function perRequest(kernel: HttpKernel) {
+  kernel.use(requestLogger());
+  kernel.use(requestLogger({ idHeader: "x-request-id", logRequests: false }));
+}
+
+export function inRequest() {
+  requestLog().info("charging card", { orderId: 1 });
+}
+
+// Interface / type seams
+const options: LoggerOptions = {
+  level: "debug",
+  pretty: true,
+  bindings: { app: "api" },
+  redact: ["password"],
+};
+const level: LogLevel = "warn";
+export { options, level };
+
+/* --- Levels, sinks, named loggers, redaction options --- */
+
+import {
+  MemorySink,
+  consoleSink,
+  setLogger,
+  namedLogger,
+  type Sink,
+  type LogRecord,
+  type RedactOptions,
+} from "@shaferllc/keel/core";
+
+declare function expensiveSnapshot(): unknown;
+declare const auditSink: Sink;
+declare const userId: number;
+
+export function allLevels() {
+  const log = new Logger({ level: "trace" });
+  log.trace("t");
+  log.debug("d");
+  log.info("i");
+  log.warn("w");
+  log.error("e");
+  log.fatal("f");
+  log.log("warn", "dynamic");
+}
+
+export function gating() {
+  if (logger().isLevelEnabled("debug")) {
+    logger().debug("state", { snapshot: expensiveSnapshot() });
+  }
+  logger().ifLevelEnabled("debug", (log) =>
+    log.debug("state", { snapshot: expensiveSnapshot() }),
+  );
+}
+
+export function sinks() {
+  const httpSink: Sink = (record: LogRecord) => {
+    void fetch("https://logs.example.com", { method: "POST", body: JSON.stringify(record) });
+  };
+  new Logger({ sink: httpSink });
+  new Logger({ sink: consoleSink(true) });
+  new Logger({ enabled: false });
+}
+
+export function memorySink() {
+  const sink = new MemorySink();
+  const log = new Logger({ level: "trace", sink: sink.sink });
+
+  log.info("hello", { userId: 1 });
+
+  const messages = sink.messages();
+  const infos = sink.at("info");
+  const fields = sink.records[0]?.fields;
+  sink.clear();
+
+  return { messages, infos, fields };
+}
+
+export function named() {
+  setLogger(new Logger({ level: "trace", sink: auditSink }), "audit");
+  namedLogger("audit").trace("permission granted", { userId });
+}
+
+export function redactionOptions() {
+  new Logger({ redact: ["password", "req.headers.authorization"] });
+  new Logger({ redact: ["*.password", "creds.*.token"] });
+
+  const censor: RedactOptions = { paths: ["password"], censor: "***" };
+  const remove: RedactOptions = { paths: ["password"], remove: true };
+  new Logger({ redact: censor });
+  new Logger({ redact: remove });
+}