@shaferllc/keel 0.66.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/container.ts

@@ -0,0 +1,134 @@
+// Type-check harness for docs/container.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 {
+  Container,
+  Application,
+  ServiceProvider,
+  bind,
+  singleton,
+  instance,
+  make,
+  bound,
+  alias,
+  swap,
+  restore,
+  type Ctx,
+  type Token,
+  type Constructor,
+  type Factory,
+} from "@shaferllc/keel/core";
+
+// Stand-ins for app-defined services referenced in the guide.
+class Mailer {
+  constructor(_dep?: unknown) {}
+}
+class ReportService {
+  constructor(private app: Container) {}
+}
+class Router {
+  constructor(_app?: unknown) {}
+}
+declare const fakeMailer: Mailer;
+
+declare const app: Container;
+
+export class AppServiceProvider extends ServiceProvider {
+  register(): void {
+    this.app.bind("clock", () => new Date());
+    this.app.singleton(Mailer, (app) => new Mailer(app.make("config")));
+    this.app.instance("version", "0.1.0");
+  }
+}
+
+export function globalHelpers() {
+  bind("clock", () => new Date());
+  singleton(Mailer, (app) => new Mailer(app));
+  instance("version", "0.6.0");
+
+  const mailer = make(Mailer);
+  const version = make<string>("version");
+  if (bound("clock")) {
+    /* … */
+  }
+  return { mailer, version };
+}
+
+export function resolving() {
+  const mailer = make(Mailer);
+  const version = make<string>("version");
+
+  const report = app.make(ReportService); // no explicit binding
+
+  make("nope"); // throws at runtime; type-checks fine
+  const clock = bound("clock") ? make<Date>("clock") : new Date();
+  return { mailer, version, report, clock };
+}
+
+export class InvoiceController {
+  constructor(private app: Container) {}
+
+  index(c: Ctx) {
+    const config = this.app.make(Application).config();
+    return c.json({ currency: config.get("app.currency", "USD") });
+  }
+}
+
+export function containerReference() {
+  app.bind("clock", () => new Date());
+  app.bind(Mailer, (c) => new Mailer(c.make("config")));
+  app.singleton(Mailer, (c) => new Mailer(c.make("config")));
+  const version = app.instance("version", "0.30.0");
+
+  const mailer = app.make(Mailer);
+  const ver = app.make<string>("version");
+  const same = app.get(Mailer);
+  const report = app.build(ReportService);
+  const isBound = app.bound("clock");
+
+  return { version, mailer, ver, same, report, isBound };
+}
+
+export function helperReference() {
+  bind("clock", () => new Date());
+  singleton(Mailer, (app) => new Mailer(app));
+  const version = instance("version", "0.30.0");
+  const mailer = make(Mailer);
+  const ver = make<string>("version");
+  const isBound = bound("clock");
+  return { version, mailer, ver, isBound };
+}
+
+export function aliasesAndSwapping() {
+  // Guide: Aliases
+  alias("router", Router);
+  const viaAlias = make(Router);
+
+  // Guide: Swapping bindings in tests (global-helper forms)
+  swap(Mailer, () => fakeMailer);
+  make(Mailer);
+  restore(Mailer);
+  restore();
+
+  return { viaAlias };
+}
+
+export function aliasesAndSwappingContainer() {
+  app.singleton(Router, () => new Router(app));
+  app.alias("router", Router);
+  const same = app.make("router") === app.make(Router);
+
+  app.swap(Mailer, () => fakeMailer);
+  app.make(Mailer);
+  app.restore(Mailer);
+  app.restore();
+  return { same };
+}
+
+// Type seams.
+const nameKey: Token<string> = "app.name";
+const svcKey: Token<Mailer> = Mailer;
+const ctor: Constructor<ReportService> = ReportService;
+const mailerFactory: Factory<Mailer> = (app) => new Mailer(app.make("config"));
+
+export { nameKey, svcKey, ctor, mailerFactory };

package/docs/examples/controllers.ts

@@ -0,0 +1,86 @@
+// Type-check harness for docs/controllers.md. Every type-checkable snippet in
+// the guide is exercised here against the real exports, so a renamed method or a
+// wrong handler shape fails `npm run typecheck:docs`. Compile-only — never run.
+import {
+  json,
+  param,
+  Container,
+  type Ctx,
+  type RouteHandler,
+} from "@shaferllc/keel/core";
+
+// A stand-in service the DI example resolves.
+class Mailer {
+  send() {}
+}
+
+// --- Basic controller: methods are actions, take Ctx or nothing ---
+export class PostController {
+  index() {
+    return json({ posts: [] });
+  }
+
+  // Take the context explicitly…
+  show(c: Ctx) {
+    return c.json({ id: c.req.param("id") });
+  }
+
+  // …or lean on the ambient helpers and drop the argument.
+  edit() {
+    return json({ id: param("id") });
+  }
+}
+
+// --- Dependency injection: constructor receives the container ---
+export class UserController {
+  constructor(private app: Container) {}
+
+  store() {
+    const mailer = this.app.make(Mailer);
+    return json({ sent: typeof mailer.send });
+  }
+
+  show(c: Ctx) {
+    const id = c.req.param("id");
+    const q = c.req.query("expand");
+    return c.json({ id, expand: q });
+  }
+}
+
+// --- Single-action controller: define handle() ---
+export class PublishPost {
+  handle() {
+    return json({ published: true });
+  }
+}
+
+// --- Resource controller: the seven conventional actions ---
+export class ResourcePostController {
+  index(c: Ctx) { return c.json({ action: "index" }); }
+  create(c: Ctx) { return c.json({ action: "create" }); }
+  store(c: Ctx) { return c.json({ action: "store" }); }
+  show(c: Ctx) { return c.json({ action: "show" }); }
+  edit(c: Ctx) { return c.json({ action: "edit" }); }
+  update(c: Ctx) { return c.json({ action: "update" }); }
+  destroy(c: Ctx) { return c.json({ action: "destroy" }); }
+}
+
+// --- Default export, for the lazy-loading snippet ---
+export default class ReportController {
+  index(c: Ctx) {
+    return c.json({ action: "index" });
+  }
+}
+
+// --- RouteHandler: every arm of the union type-checks ---
+export function handlerForms() {
+  const closure: RouteHandler = () => json({ ok: true });
+  const staticResp: RouteHandler = json({ status: "ok" });
+  const action: RouteHandler = [UserController, "show"];
+  const single: RouteHandler = [PublishPost];
+  const lazy: RouteHandler = [
+    () => Promise.resolve({ default: ReportController }),
+    "index",
+  ];
+  return { closure, staticResp, action, single, lazy };
+}

package/docs/examples/database.ts

@@ -0,0 +1,208 @@
+// Type-check harness for docs/database.md. Every 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 executed.
+import {
+  db,
+  setConnection,
+  type Connection,
+  type WriteResult,
+  type Row,
+  type Dialect,
+  type Operator,
+} from "@shaferllc/keel/core";
+
+declare const email: string;
+declare const name: string;
+declare const now: number;
+
+export async function connect() {
+  const d1 = {} as {
+    prepare(sql: string): {
+      bind(...b: unknown[]): {
+        all(): Promise<{ results: Row[]; meta: { changes: number; last_row_id: number } }>;
+        run(): Promise<{ meta: { changes: number; last_row_id: number } }>;
+      };
+    };
+  };
+
+  const connection: Connection = {
+    select: (sql, bindings) => d1.prepare(sql).bind(...bindings).all().then((r) => r.results),
+    write: async (sql, bindings) => {
+      const r = await d1.prepare(sql).bind(...bindings).run();
+      return { rowsAffected: r.meta.changes, insertId: r.meta.last_row_id };
+    },
+  };
+  setConnection(connection, "sqlite");
+  setConnection(connection, "postgres");
+}
+
+export async function querying() {
+  await db("users").where("active", true).orderBy("name").get();
+  await db("users").where("id", 1).first();
+  await db("users").where("age", ">", 18).count();
+  await db("posts").whereIn("id", [1, 2, 3]).get();
+  await db("posts").whereNull("deleted_at").limit(20).offset(40).get();
+  await db("orders").select("id", "total").where("status", "paid").orWhere("status", "shipped").get();
+}
+
+export async function writing() {
+  const id = await db("users").insertGetId({ email, name });
+  await db("users").where("id", id).update({ name: "Grace" });
+  await db("users").where("id", id).delete();
+}
+
+export async function typedRows() {
+  type User = {
+    id: number;
+    email: string;
+  };
+  const user = await db<User>("users").where("id", 1).first();
+  const all = await db<User>("users").get();
+  return { user, all };
+}
+
+export async function reference() {
+  db("users");
+  db<{ id: number }>("users");
+
+  db("users").select("id", "email").get();
+  db("users").where("active", true);
+  db("users").where("age", ">", 18);
+  db("users").where("email", "like", "%@example.com");
+  db("orders").where("status", "paid").orWhere("status", "shipped").get();
+  db("posts").whereIn("id", [1, 2, 3]).get();
+  db("posts").whereNull("deleted_at").get();
+  db("users").whereNotNull("verified_at").get();
+  db("users").orderBy("last_name").orderBy("created_at", "desc").get();
+  db("posts").limit(20).offset(40).get();
+
+  const rows = await db("users").where("active", true).get();
+  const first = await db("users").where("email", email).first();
+  const active = await db("users").where("active", true).count();
+  const taken = await db("users").where("email", email).exists();
+
+  const result: WriteResult = await db("users").insert({ email, name });
+  const newId = await db("users").insertGetId({ email, name });
+  const upd: WriteResult = await db("users").where("id", 1).update({ name: "Grace" });
+  await db("sessions").where("expires_at", "<", now).delete();
+
+  return { rows, first, active, taken, result, newId, upd };
+}
+
+export async function ormExtras() {
+  await db("posts").whereBetween("views", [10, 100]).get();
+  await db("posts").whereNotIn("id", [4, 5]).get();
+  await db("posts").whereLike("title", "%keel%").get();
+  await db("posts").latest().get();
+  await db("posts").oldest("published_at").get();
+
+  const total: number = await db("orders").where("paid", true).sum("total");
+  const a: number = await db("orders").avg("total");
+  const mn: number = await db("orders").min("total");
+  const mx: number = await db("orders").max("total");
+  const email = await db("users").where("id", 1).value<string>("email");
+  const titles = await db("posts").pluck<string>("title");
+  const page = await db("posts").latest().paginate(2, 15);
+  const rows = page.data;
+  return { total, a, mn, mx, email, titles, page: page.currentPage, last: page.lastPage, rows };
+}
+
+// Interface / type seams
+const mock: Connection = {
+  select: async () => [{ id: 1 }],
+  write: async (): Promise<WriteResult> => ({ rowsAffected: 1, insertId: 1 }),
+};
+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/debugging.ts

@@ -0,0 +1,41 @@
+// Type-check harness for docs/debugging.md. Every type-checkable snippet in the
+// reference is exercised here against the real exports, so a renamed function or
+// wrong argument type fails `npm run typecheck:docs`. Compile-only — never run.
+import { dump, dd } from "@shaferllc/keel/core";
+
+declare const user: { id: number; name: string };
+declare const order: { total: number };
+declare const request: {
+  all(): Promise<Record<string, unknown>>;
+  headers(): Record<string, string>;
+};
+declare function computeTotal(): number;
+declare function save(): Promise<{ id: number }>;
+
+export function dumpBasics() {
+  dump(user, order); // logs both, returns `user`
+
+  const total = dump(computeTotal()); // logs the total AND uses it
+  return total;
+}
+
+export async function dumpInline() {
+  return dump(await save()); // inspect the saved value, still return it
+}
+
+export function dumpReference() {
+  const first = dump(user, order, request); // returns `user`
+  first.name; // typed as the first argument's type
+  return first;
+}
+
+export async function ddBasics() {
+  dd(await request.all(), request.headers());
+  // unreachable — dd() throws
+}
+
+export async function ddReference() {
+  // `dd` returns `never`, so TS treats everything after it as unreachable.
+  const value = await request.all();
+  dd(value);
+}

package/docs/examples/decorators.ts

@@ -0,0 +1,40 @@
+// Type-check harness for docs/decorators.md. Compile-only — never executed.
+import {
+  decorateRequest,
+  decorated,
+  setRequestValue,
+  hasRequestDecorator,
+  clearRequestDecorators,
+  type RequestResolver,
+} from "@shaferllc/keel/core";
+
+type User = { id: number; name: string };
+declare function findUser(auth: string | undefined): Promise<User | null>;
+
+export function registering() {
+  decorateRequest("locale", (c) => c.req.header("accept-language") ?? "en");
+  decorateRequest("user", async (c) => findUser(c.req.header("authorization")));
+  decorateRequest("tenant", (c) => c.req.header("x-tenant") ?? "public");
+}
+
+export async function accessing() {
+  const locale = await decorated<string>("locale");
+  const user = await decorated<User | null>("user");
+  const tenant = await decorated<string>("tenant");
+  return { locale, user, tenant };
+}
+
+export async function setting(theUser: User) {
+  setRequestValue("user", theUser);
+  return decorated<User>("user");
+}
+
+export function introspection() {
+  const has = hasRequestDecorator("user");
+  clearRequestDecorators();
+  return has;
+}
+
+// The resolver type
+const resolver: RequestResolver<string> = (c) => c.req.path;
+export { resolver };