@shaferllc/keel 0.66.0 → 0.74.0

package/docs/examples/mail.ts

@@ -0,0 +1,263 @@
+// Type-check harness for docs/mail.md. Every type-checkable snippet in the doc
+// 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 {
+  mail,
+  setMailer,
+  getMailer,
+  fetchTransport,
+  Mailer,
+  PendingMail,
+  ArrayTransport,
+  LogTransport,
+  type Message,
+  type Transport,
+  type MailerOptions,
+  type FetchTransportOptions,
+} from "@shaferllc/keel/core";
+
+declare const env: (key: string) => string;
+declare const apiKey: string;
+declare const message: Message;
+declare const myProviderSdk: { emails: { send(m: Message): Promise<void> } };
+
+export async function sending() {
+  await mail()
+    .to("ada@example.com")
+    .subject("Welcome aboard")
+    .html("<h1>Hi Ada</h1>")
+    .send();
+
+  await mail()
+    .to("a@x.com", "b@x.com")
+    .cc("team@x.com")
+    .bcc("audit@x.com")
+    .replyTo("support@x.com")
+    .from("hello@x.com")
+    .subject("Report")
+    .text("Plain-text body")
+    .html("<p>HTML body</p>")
+    .header("X-Campaign", "weekly")
+    .send();
+
+  await mail().fill({ to: "a@x.com", subject: "Hi", text: "body" }).send();
+
+  const sent = await mail().to("ada@example.com").subject("Hi").text("hey").send();
+  return { from: sent.from, to: sent.to };
+}
+
+export function configuring() {
+  setMailer(
+    fetchTransport({
+      url: "https://api.resend.com/emails",
+      headers: { Authorization: `Bearer ${env("RESEND_API_KEY")}` },
+      body: (m) => ({ from: m.from, to: m.to, subject: m.subject, html: m.html }),
+    }),
+    { from: "hello@myapp.com" },
+  );
+}
+
+export function ownTransport() {
+  const transport: Transport = {
+    async send(message) {
+      void message;
+    },
+  };
+  setMailer(transport, { from: "hello@myapp.com" });
+}
+
+export async function inTests() {
+  const transport = new ArrayTransport();
+  setMailer(transport, { from: "hi@app.com" });
+
+  await mail().to("ada@example.com").subject("Welcome").text("hi").send();
+
+  return { count: transport.sent.length, subject: transport.sent[0]?.subject };
+}
+
+export async function scopedMailer() {
+  const mailer = new Mailer(new ArrayTransport(), { from: "hi@app.com" });
+  await mailer.message().to("ada@example.com").subject("Hi").text("hey").send();
+}
+
+// ------------------------------- reference ---------------------------------
+
+export async function referenceFunctions() {
+  await mail().to("ada@example.com").subject("Hi").text("hey").send();
+
+  const m1: Mailer = setMailer(fetchTransport({ url: "https://x/emails" }), {
+    from: "hello@myapp.com",
+  });
+
+  const mailer: Mailer = getMailer();
+  await mailer.message().to("ada@example.com").subject("Hi").text("hey").send();
+
+  const transport: Transport = fetchTransport({
+    url: "https://api.resend.com/emails",
+    headers: { Authorization: `Bearer ${apiKey}` },
+    body: (m) => ({ from: m.from, to: m.to, subject: m.subject, html: m.html }),
+  });
+
+  return { m1, transport };
+}
+
+export async function referenceMailer() {
+  const mailer = new Mailer(new ArrayTransport(), { from: "hi@app.com" });
+  const pending: PendingMail = mailer.message();
+  const sent: Message = await mailer.send({
+    to: ["ada@x.com"],
+    subject: "Hi",
+    text: "hey",
+  });
+  return { pending, sent };
+}
+
+export function referencePendingMail() {
+  mail().to("a@x.com", "b@x.com");
+  mail().from("hello@x.com");
+  mail().cc("team@x.com").bcc("audit@x.com");
+  mail().replyTo("support@x.com");
+  mail().subject("Welcome aboard");
+  mail().text("Plain body").html("<p>Rich body</p>");
+  mail().header("X-Campaign", "weekly");
+  mail().fill({ to: ["a@x.com", "b@x.com"], subject: "Hi", text: "body" });
+}
+
+export async function referenceTransports() {
+  const transport = new ArrayTransport();
+  setMailer(transport);
+  transport.sent.length;
+  transport.sent[0]?.subject;
+  await new ArrayTransport().send(message);
+
+  setMailer(new LogTransport(), { from: "dev@localhost" });
+  await new LogTransport().send(message);
+}
+
+// ---------------------------- interface / type seams -----------------------
+
+const seamMessage: Message = {
+  to: ["ada@x.com"],
+  from: "hi@app.com",
+  subject: "Hi",
+  text: "hey",
+};
+
+const seamTransport: Transport = {
+  async send(message) {
+    await myProviderSdk.emails.send(message);
+  },
+};
+
+const seamOptions: MailerOptions = { from: "hello@myapp.com" };
+
+const seamFetchOptions: FetchTransportOptions = {
+  url: "https://api.resend.com/emails",
+  headers: { Authorization: `Bearer ${apiKey}` },
+  body: (m) => ({ from: m.from, to: m.to, subject: m.subject, html: m.html }),
+};
+
+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/middleware.ts

@@ -0,0 +1,119 @@
+// Type-check harness for docs/middleware.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 {
+  HttpKernel,
+  Application,
+  Router,
+  UnauthorizedException,
+  type MiddlewareRef,
+  type RouteHandler,
+} from "@shaferllc/keel/core";
+import type { MiddlewareHandler } from "hono";
+
+// Externals the snippets reference.
+declare const router: Router;
+declare const handler: RouteHandler;
+declare function lookupUser(auth?: string): Promise<{ id: number; name: string }>;
+
+// Example middleware — the shape everything else registers.
+export const requestLogger: MiddlewareHandler = async (c, next) => {
+  const start = performance.now();
+  await next();
+  const ms = (performance.now() - start).toFixed(1);
+  console.log(`  ${c.req.method} ${c.req.path} → ${c.res.status} (${ms}ms)`);
+};
+
+const cors: MiddlewareHandler = async (_c, next) => {
+  await next();
+};
+const requestId: MiddlewareHandler = async (_c, next) => {
+  await next();
+};
+
+// The HTTP kernel — global middleware + custom error handler.
+export class Kernel extends HttpKernel {
+  constructor(app: Application) {
+    super(app);
+    this.use(requestLogger).use(cors).use(requestId);
+    this.onError((err, c) => c.json({ error: String(err) }, 500));
+  }
+}
+
+export function buildKernel(app: Application) {
+  const kernel = new Kernel(app);
+  return kernel.build();
+}
+
+// Short-circuiting.
+export const requireApiKey: MiddlewareHandler = async (c, next) => {
+  if (c.req.header("x-api-key") !== process.env.API_KEY) {
+    return c.json({ error: "Unauthorized" }, 401);
+  }
+  await next();
+};
+
+class Auth {
+  check(): boolean {
+    return true;
+  }
+}
+export const requireAuth: MiddlewareHandler = async (c, next) => {
+  if (!c.get("app").make(Auth).check()) throw new UnauthorizedException();
+  await next();
+};
+
+// Sharing data with handlers.
+export const withUser: MiddlewareHandler = async (c, next) => {
+  c.set("user", await lookupUser(c.req.header("authorization")));
+  await next();
+};
+
+export const noCache: MiddlewareHandler = async (c, next) => {
+  await next();
+  c.header("Cache-Control", "no-store");
+};
+
+// Parameterized middleware via a factory.
+const role = (name: string): MiddlewareHandler => async (_c, next) => {
+  void name;
+  await next();
+};
+
+// Named middleware + applying refs to routes, groups, resources.
+class DashboardController {}
+class PostController {}
+class AdminController {}
+class ReportController {}
+const authMiddleware = requireAuth;
+const adminMiddleware = requireAuth;
+const auditLog = requestLogger;
+
+export function named() {
+  router.named({ auth: authMiddleware, admin: adminMiddleware });
+  router.named({ admin: role("admin"), editor: role("editor") });
+
+  router.get("/dashboard", [DashboardController, "index"]).use("auth");
+  router.group(() => {
+    /* … */
+  }).use(["auth", "admin"]);
+  router.resource("posts", PostController).use(["store", "update"], "auth");
+  router.resource("admin", AdminController).use("*", "admin");
+
+  router.get("/reports", [ReportController, "index"]).use(["auth", auditLog]);
+  router.get("/admin", handler).use(role("admin"));
+  router.get("/reports2", handler).middleware(["auth", auditLog]);
+
+  const mw = router.resolveMiddleware("auth");
+  return mw;
+}
+
+export function groupOrdering() {
+  router.group(() => {
+    router.get("/posts/:id/edit", handler).use("owns-post");
+  }).use("auth");
+}
+
+// Type seams.
+const guards: MiddlewareRef[] = ["auth", auditLog];
+export { guards };

package/docs/examples/migrations.ts

@@ -0,0 +1,126 @@
+// Type-check harness for docs/migrations.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 {
+  Migrator,
+  SchemaBuilder,
+  TableBuilder,
+  Column,
+  type Migration,
+  type Connection,
+  type Dialect,
+} from "@shaferllc/keel/core";
+
+// A mock connection. `as Connection` is needed because `select` is declared
+// generic (`select<T = Row>(…): Promise<T[]>`) — see docs/database.md.
+const connection = {
+  select: async () => [],
+  write: async () => ({ rowsAffected: 1, insertId: 1 }),
+} as Connection;
+
+export const migrations: Migration[] = [
+  {
+    name: "01_create_users",
+    up: (schema) =>
+      schema.createTable("users", (t) => {
+        t.id();
+        t.string("email").unique();
+        t.string("name");
+        t.boolean("active").default(true);
+        t.timestamps();
+      }),
+    down: (schema) => schema.dropTable("users"),
+  },
+];
+
+export async function columnTypes() {
+  await new SchemaBuilder(connection, "sqlite").createTable("posts", (t) => {
+    t.id();
+    t.integer("user_id");
+    t.string("slug", 120).unique();
+    t.text("body").nullable();
+    t.json("meta").nullable();
+    t.boolean("published").default(false);
+    t.timestamps();
+  });
+}
+
+export async function defaults(schema: SchemaBuilder) {
+  await schema.createTable("accounts", (t) => {
+    t.string("role").default("member");
+    t.boolean("active").default(true);
+    t.integer("retries").default(0);
+  });
+}
+
+export async function rawExamples(schema: SchemaBuilder) {
+  await schema.raw("CREATE INDEX idx_posts_user ON posts (user_id)");
+  await schema.raw("UPDATE users SET active = ? WHERE active IS NULL", [true]);
+}
+
+export async function runAndRollBack() {
+  const migrator = new Migrator(connection, "postgres");
+
+  const applied = await migrator.up(migrations);
+  const rolled = await migrator.down(migrations);
+  const names = await migrator.ran();
+
+  const pending = migrations.filter((m) => !names.includes(m.name));
+  return { applied, rolled, names, pending };
+}
+
+export async function migratorDefaults() {
+  const migrator = new Migrator(connection); // dialect defaults to "sqlite"
+  return migrator.ran();
+}
+
+// SchemaBuilder reference
+export async function schemaBuilderRef(schema: SchemaBuilder) {
+  await schema.createTable("users", (t) => {
+    t.id();
+    t.string("email").unique();
+    t.timestamps();
+  });
+  await schema.dropTable("users");
+  await schema.raw("CREATE INDEX idx ON users (email)");
+  await schema.raw("UPDATE users SET active = ? WHERE id = ?", [true, 1]);
+}
+
+// TableBuilder reference
+export function tableBuilderRef() {
+  const t = new TableBuilder();
+  t.id();
+  t.id("uuid");
+  t.string("email");
+  t.string("slug", 120);
+  t.text("body");
+  t.integer("user_id");
+  t.bigInteger("view_count");
+  t.boolean("active").default(true);
+  t.timestamp("published_at").nullable();
+  t.json("meta").nullable();
+  t.timestamps();
+  const cols: Column[] = t.columns;
+  const sql: string = t.toCreateSql("users", "postgres");
+  return { cols, sql };
+}
+
+// Column reference
+export function columnRef(t: TableBuilder) {
+  t.text("bio").nullable();
+  t.string("email").unique();
+  t.boolean("active").default(true);
+  t.string("role").default("member");
+  const fragment: string = new Column("email", "string").unique().toSql("sqlite");
+  return fragment;
+}
+
+// Migration type seam
+export const indexMigration: Migration = {
+  name: "03_add_index",
+  up: (s) => s.raw("CREATE INDEX idx_users_email ON users (email)"),
+  down: (s) => s.raw("DROP INDEX idx_users_email"),
+};
+
+const d: Dialect = "mysql";
+export { d };