@shaferllc/keel 0.68.0 → 0.74.0

package/docs/examples/console.ts

@@ -0,0 +1,134 @@
+// Type-check harness for docs/console.md. Compile-only — never executed.
+import {
+  defineCommand,
+  arg,
+  flag,
+  ConsoleKernel,
+  createUi,
+  createPrompt,
+  startRepl,
+  stripAnsi,
+  type Application,
+  type Ui,
+  type Prompt,
+  type CommandDefinition,
+  type ReplHelper,
+} from "@shaferllc/keel/core";
+
+export const greet = defineCommand({
+  name: "greet",
+  description: "Greet someone",
+
+  args: { name: arg.string({ description: "who to greet" }) },
+  flags: { loud: flag.boolean({ alias: "l", description: "SHOUT IT" }) },
+
+  async run({ args, flags, ui }) {
+    // The inference is the point: these annotations must hold.
+    const name: string = args.name;
+    const loud: boolean = flags.loud;
+
+    const message = `Hello, ${name}!`;
+    ui.success(loud ? message.toUpperCase() : message);
+  },
+});
+
+export const everySpec = defineCommand({
+  name: "specs",
+  args: {
+    required: arg.string(),
+    optional: arg.string({ required: false }),
+    defaulted: arg.string({ default: "x" }),
+    count: arg.number(),
+    rest: arg.spread({ required: false }),
+  },
+  flags: {
+    on: flag.boolean(),
+    name: flag.string({ alias: "n" }),
+    needed: flag.string({ required: true }),
+    times: flag.number({ default: 1 }),
+    tags: flag.array(),
+  },
+  allowUnknownFlags: true,
+
+  run({ args, flags, rest }) {
+    const a: string = args.required;
+    const b: string | undefined = args.optional;
+    const c: string = args.defaulted;
+    const d: number = args.count;
+    const e: string[] = args.rest;
+
+    const f: boolean = flags.on;
+    const g: string | undefined = flags.name;
+    const h: string = flags.needed;
+    const i: number = flags.times;
+    const j: string[] = flags.tags;
+
+    void [a, b, c, d, e, f, g, h, i, j, rest];
+    return 0; // the exit code
+  },
+});
+
+export function terminalUi(ui: Ui) {
+  ui.info("Checking…");
+  ui.success("Migrated 3 tables");
+  ui.warning("Nothing to do");
+  ui.error("Failed");
+  ui.debug("verbose detail");
+
+  ui.action("create", "app/Models/User.ts");
+  ui.action("skip", "app/Models/Post.ts", "skipped");
+
+  ui.table(["Name", "Rows"]).row(["users", "42"]).row(["orgs", "7"]).render();
+
+  ui.sticker(["http://localhost:3000"], "Server running");
+  ui.instructions(["cd my-app", "npm install", "keel serve"], "Next steps");
+
+  return ui.colors("green", "done");
+}
+
+export async function tasks(ui: Ui) {
+  return ui
+    .tasks()
+    .add("Install dependencies", async (task) => {
+      task.update("resolving…");
+      return "42 packages";
+    })
+    .add("Run migrations", async () => "3 tables")
+    .run();
+}
+
+export async function prompts(prompt: Prompt) {
+  const name = await prompt.ask("Project name?", { default: "my-app" });
+  const secret = await prompt.secure("API key?");
+  const ok = await prompt.confirm("Delete everything?");
+  const driver = await prompt.choice("Database?", ["sqlite", "postgres"]);
+  const features = await prompt.multiple("Features?", ["auth", "queue", "mail"]);
+
+  return { name, secret, ok, driver, features };
+}
+
+export async function testingACommand(setup: CommandDefinition) {
+  const ui = createUi({ raw: true });
+  const prompt = createPrompt({ trap: true });
+  const kernel = new ConsoleKernel({ ui, prompt }).register(setup);
+
+  prompt.trap("Project name?").replyWith("keel-app");
+  prompt.trap("Database?").chooseOption(1);
+  prompt.trap("Write the config?").accept();
+
+  prompt
+    .trap("Email?")
+    .assertFails("", "Email is required")
+    .assertPasses("ada@example.com")
+    .replyWith("ada@example.com");
+
+  const code = await kernel.run(["setup"]);
+
+  prompt.assertAllTrapsUsed();
+
+  return { code, logs: ui.logs, errors: ui.errors, plain: stripAnsi(ui.logs.join("\n")) };
+}
+
+export async function repl(app: Application, helpers: ReplHelper[]) {
+  await startRepl(app, { helpers, prompt: "keel > " });
+}

package/docs/examples/database.ts

@@ -116,3 +116,93 @@ const dialect: Dialect = "postgres";
 const op: Operator = "like";
 const row: Row = { id: 1 };
 export { mock, dialect, op, row };
+
+/* --- Transactions --- */
+
+import {
+  transaction,
+  inTransaction,
+  type TransactionHandle,
+  type TransactionConnection,
+} from "@shaferllc/keel/core";
+
+declare const order: Record<string, unknown>;
+declare const item: Record<string, unknown>;
+declare const entry: Record<string, unknown>;
+declare const id: number;
+
+export async function committing() {
+  await transaction(async () => {
+    await db("orders").insert(order);
+    await db("stock").where("id", id).update({ count: 0 });
+  });
+}
+
+export async function explicitHandle() {
+  return transaction(async (tx: TransactionHandle) => {
+    await tx.table("orders").insert(order);
+    await tx.write("UPDATE stock SET count = count - 1 WHERE id = ?", [id]);
+    void tx.depth;
+    void tx.dialect;
+    return "done";
+  });
+}
+
+export async function abandoning() {
+  await transaction(async (tx) => {
+    await tx.table("orders").insert(order);
+    await tx.rollback();
+  });
+}
+
+export async function nesting() {
+  await transaction(async () => {
+    await db("orders").insert(order);
+
+    try {
+      await transaction(async () => {
+        await db("items").insert(item);
+        throw new Error("out of stock");
+      });
+    } catch {
+      // only the inner work was rolled back
+    }
+
+    await db("audit").insert(entry);
+  });
+}
+
+export function checking(): boolean {
+  return inTransaction();
+}
+
+export async function onANamedConnection() {
+  await transaction(async () => {
+    await db("events", "reporting").insert(entry);
+  }, "reporting");
+}
+
+/** A driver that pools must implement begin() — see the guide. */
+export function pooledDriver(): Connection {
+  const conn: Connection = {
+    async select() {
+      return [];
+    },
+    async write() {
+      return { rowsAffected: 0 };
+    },
+    async begin(): Promise<TransactionConnection> {
+      return {
+        async select() {
+          return [];
+        },
+        async write() {
+          return { rowsAffected: 0 };
+        },
+        async commit() {},
+        async rollback() {},
+      };
+    },
+  };
+  return conn;
+}

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/logger.ts

@@ -90,3 +90,77 @@ const options: LoggerOptions = {
 };
 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 });
+}

package/docs/examples/mail.ts

@@ -158,3 +158,106 @@ const seamFetchOptions: FetchTransportOptions = {
 };
 
 export { seamMessage, seamTransport, seamOptions, seamFetchOptions };
+
+/* --- Queueing, attachments, class mails, named mailers, faking, events --- */
+
+import {
+  mailer as namedMailer,
+  send as sendMail,
+  sendLater as queueMail,
+  fakeMail,
+  restoreMail,
+  BaseMail,
+  listen,
+  logger,
+  type PendingMail as PendingMailType,
+  type Attachment,
+  type RecordedMail,
+} from "@shaferllc/keel/core";
+
+declare const user2: { email: string; name: string };
+declare const body: string;
+declare const pdfBytes: Uint8Array;
+declare const logoBytes: Uint8Array;
+declare const postmark: Transport;
+declare const resend: Transport;
+
+export async function queueing() {
+  await mail().to(user2.email).subject("Welcome").html(body).sendLater();
+}
+
+export async function attachments() {
+  await mail()
+    .to("ada@example.com")
+    .subject("Your invoice")
+    .html('<p>Attached. <img src="cid:logo"></p>')
+    .attach("invoice.pdf", pdfBytes)
+    .attach("data.csv", "a,b,c", "text/csv")
+    .embed("logo", logoBytes, "logo.png")
+    .send();
+}
+
+export class WelcomeEmail extends BaseMail {
+  constructor(private user: { email: string; name: string }) {
+    super();
+  }
+
+  build(message: PendingMailType): void {
+    message
+      .to(this.user.email)
+      .subject(`Welcome, ${this.user.name}`)
+      .html(`<h1>Hi ${this.user.name}</h1>`);
+  }
+}
+
+export async function classBasedMails() {
+  await sendMail(new WelcomeEmail(user2));
+  await queueMail(new WelcomeEmail(user2));
+  await sendMail(new WelcomeEmail(user2), "marketing");
+}
+
+export async function namedMailers() {
+  setMailer(postmark, { from: "hi@app.com" });
+  setMailer(resend, { from: "news@app.com" }, "marketing");
+
+  await mail().to(user2.email).subject("Receipt").text(body).send();
+  await mail("marketing").to(user2.email).subject("This month").html(body).send();
+
+  return namedMailer("marketing");
+}
+
+export async function faking() {
+  const faked = fakeMail();
+
+  faked.assertSent();
+  faked.assertSent((m) => m.subject === "Welcome");
+  faked.assertSentCount(1);
+  faked.assertQueued((m) => m.to.includes("ada@example.com"));
+  faked.assertNotSent((m) => m.subject === "Password reset");
+  faked.assertNotQueued();
+  faked.assertQueuedCount(0);
+  faked.assertNothingSent();
+
+  const sent: Message[] = faked.sent();
+  const queued: Message[] = faked.queued();
+  const all: RecordedMail[] = faked.mails;
+
+  restoreMail();
+  restoreMail("marketing");
+
+  return { sent, queued, all };
+}
+
+export function mailEvents() {
+  listen("mail.sent", (message) => {
+    logger().info("mail sent", { subject: (message as Message).subject });
+  });
+}
+
+export function attachmentType(a: Attachment): string | undefined {
+  return a.contentType;
+}
+
+export function composed(): Message {
+  return mail().to("a@b.com").subject("x").text("y").toMessage();
+}

package/docs/examples/pages.ts

@@ -0,0 +1,82 @@
+// Type-check harness for docs/pages.md. Compile-only — never executed.
+// The .tsx page snippets in the guide are illustrative JSX; the exports they use
+// are exercised here against the real types.
+import {
+  pages,
+  definePages,
+  routePattern,
+  routeName,
+  db,
+  ServiceProvider,
+  authGuard,
+  Router,
+  make,
+  type Ctx,
+  type PageProps,
+  type PageModule,
+  type PagesOptions,
+  type RegisteredPage,
+} from "@shaferllc/keel/core";
+
+interface User {
+  id: number;
+  name: string;
+}
+
+export class PageServiceProvider extends ServiceProvider {
+  async boot(): Promise<void> {
+    await pages();
+  }
+}
+
+export async function registering(): Promise<RegisteredPage[]> {
+  const options: PagesOptions = {
+    dir: "app/pages",
+    prefix: "/app",
+    middleware: [authGuard()],
+  };
+
+  await pages();
+  await pages({ prefix: "/app" });
+  await pages({ dir: "app/pages" });
+  await pages({ middleware: [authGuard()] });
+
+  return pages(options);
+}
+
+/** What `definePages` takes — the shape `import.meta.glob(..., { eager: true })` gives. */
+export function edgeManifest(modules: Record<string, PageModule<never, never>>) {
+  return definePages(modules, { dir: "resources/pages" });
+}
+
+/** A page module, spelled out — the same exports the .tsx files in the guide use. */
+export const userPage: PageModule<{ id: string }, User> = {
+  name: "users.show",
+  path: "/users/:id",
+  middleware: [authGuard()],
+
+  loader: async (c: Ctx): Promise<User> => {
+    const row = await db("users").where("id", c.req.param("id")).first();
+    return row as unknown as User;
+  },
+
+  default: ({ params, data, ctx }: PageProps<{ id: string }, User>) => {
+    void ctx;
+    return `<h1>${data.name}</h1><p>User #${params.id}</p>`;
+  },
+};
+
+export function conventions() {
+  return {
+    root: routePattern("index.tsx"), // "/"
+    about: routePattern("about.tsx"), // "/about"
+    users: routePattern("users/index.tsx"), // "/users"
+    user: routePattern("users/[id].tsx"), // "/users/:id"
+    docs: routePattern("docs/[...slug].tsx"), // "/docs/:slug{.+}"
+    name: routeName("users/[id].tsx"), // "users.id"
+  };
+}
+
+export function urls(): string {
+  return make(Router).url("users.id", { id: 5 }); // "/users/5"
+}