npm - @shaferllc/keel - Versions diffs - 0.59.0 → 0.68.0 - Mend

@shaferllc/keel 0.59.0 → 0.68.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (166) hide show

package/AGENTS.md +167 -0
package/README.md +30 -1
package/bin/keel-mcp.mjs +9 -0
package/dist/core/application.d.ts +5 -5
package/dist/core/application.js +14 -2
package/dist/core/auth.d.ts +47 -0
package/dist/core/auth.js +77 -0
package/dist/core/authorization.d.ts +9 -1
package/dist/core/authorization.js +22 -2
package/dist/core/cache.d.ts +82 -5
package/dist/core/cache.js +181 -23
package/dist/core/cli/stubs.d.ts +12 -0
package/dist/core/cli/stubs.js +120 -0
package/dist/core/container.d.ts +20 -0
package/dist/core/container.js +52 -0
package/dist/core/cors.d.ts +29 -0
package/dist/core/cors.js +72 -0
package/dist/core/crypto.d.ts +40 -4
package/dist/core/crypto.js +66 -6
package/dist/core/csrf.d.ts +25 -0
package/dist/core/csrf.js +78 -0
package/dist/core/database.d.ts +49 -4
package/dist/core/database.js +89 -21
package/dist/core/events.d.ts +129 -5
package/dist/core/events.js +165 -7
package/dist/core/health.d.ts +141 -0
package/dist/core/health.js +226 -0
package/dist/core/helpers.d.ts +15 -3
package/dist/core/helpers.js +23 -3
package/dist/core/index.d.ts +33 -18
package/dist/core/index.js +16 -8
package/dist/core/lock.d.ts +139 -0
package/dist/core/lock.js +215 -0
package/dist/core/logger.d.ts +82 -4
package/dist/core/logger.js +141 -23
package/dist/core/mail.d.ts +128 -7
package/dist/core/mail.js +264 -16
package/dist/core/model.d.ts +2 -0
package/dist/core/model.js +16 -14
package/dist/core/provider.d.ts +7 -0
package/dist/core/provider.js +7 -0
package/dist/core/queue.d.ts +134 -9
package/dist/core/queue.js +304 -14
package/dist/core/rate-limit.js +3 -0
package/dist/core/relations.js +13 -13
package/dist/core/request.d.ts +26 -0
package/dist/core/request.js +77 -0
package/dist/core/shield.d.ts +39 -0
package/dist/core/shield.js +60 -0
package/dist/core/social.d.ts +173 -0
package/dist/core/social.js +337 -0
package/dist/core/storage.d.ts +159 -6
package/dist/core/storage.js +287 -7
package/dist/core/tokens.d.ts +74 -0
package/dist/core/tokens.js +155 -0
package/dist/db/d1.d.ts +32 -0
package/dist/db/d1.js +26 -0
package/dist/db/libsql.d.ts +29 -0
package/dist/db/libsql.js +32 -0
package/dist/db/pg.d.ts +29 -0
package/dist/db/pg.js +33 -0
package/dist/mcp/server.d.ts +19 -0
package/dist/mcp/server.js +355 -0
package/docs/ai-manifest.json +2472 -0
package/docs/ai.md +128 -0
package/docs/architecture.md +331 -0
package/docs/authentication.md +453 -0
package/docs/authorization.md +167 -0
package/docs/broadcasting.md +137 -0
package/docs/broker.md +500 -0
package/docs/cache.md +558 -0
package/docs/configuration.md +311 -0
package/docs/console.md +356 -0
package/docs/container.md +467 -0
package/docs/controllers.md +265 -0
package/docs/cors.md +51 -0
package/docs/database.md +530 -0
package/docs/debugging.md +129 -0
package/docs/decorators.md +127 -0
package/docs/errors.md +395 -0
package/docs/events.md +496 -0
package/docs/examples/architecture-app.ts +27 -0
package/docs/examples/authentication.ts +61 -0
package/docs/examples/authorization.ts +79 -0
package/docs/examples/broadcasting.ts +60 -0
package/docs/examples/broker-cache-validate.ts +34 -0
package/docs/examples/broker-fault-tolerance.ts +29 -0
package/docs/examples/broker-middleware.ts +27 -0
package/docs/examples/broker.ts +203 -0
package/docs/examples/cache.ts +222 -0
package/docs/examples/configuration.ts +81 -0
package/docs/examples/container.ts +134 -0
package/docs/examples/controllers.ts +86 -0
package/docs/examples/database.ts +118 -0
package/docs/examples/debugging.ts +41 -0
package/docs/examples/decorators.ts +40 -0
package/docs/examples/errors.ts +121 -0
package/docs/examples/events.ts +204 -0
package/docs/examples/factories.ts +84 -0
package/docs/examples/hashing.ts +71 -0
package/docs/examples/health.ts +94 -0
package/docs/examples/helpers.ts +171 -0
package/docs/examples/hooks.ts +54 -0
package/docs/examples/inertia.ts +81 -0
package/docs/examples/locks.ts +120 -0
package/docs/examples/logger.ts +92 -0
package/docs/examples/mail.ts +160 -0
package/docs/examples/middleware.ts +119 -0
package/docs/examples/migrations.ts +126 -0
package/docs/examples/models.ts +239 -0
package/docs/examples/notification.ts +124 -0
package/docs/examples/providers.ts +123 -0
package/docs/examples/queues.ts +254 -0
package/docs/examples/rate-limiting.ts +42 -0
package/docs/examples/redis.ts +99 -0
package/docs/examples/request-response.ts +197 -0
package/docs/examples/routing.ts +186 -0
package/docs/examples/scheduling.ts +62 -0
package/docs/examples/sessions.ts +102 -0
package/docs/examples/static-files.ts +63 -0
package/docs/examples/storage.ts +132 -0
package/docs/examples/templates.ts +58 -0
package/docs/examples/testing.ts +66 -0
package/docs/examples/transformer.ts +141 -0
package/docs/examples/transformers.ts +49 -0
package/docs/examples/url-builder.ts +86 -0
package/docs/examples/validation.ts +102 -0
package/docs/examples/views.tsx +62 -0
package/docs/examples/vite.ts +106 -0
package/docs/factories.md +166 -0
package/docs/getting-started.md +290 -0
package/docs/hashing.md +259 -0
package/docs/health.md +225 -0
package/docs/helpers.md +347 -0
package/docs/hono.md +186 -0
package/docs/hooks.md +118 -0
package/docs/inertia.md +241 -0
package/docs/locks.md +323 -0
package/docs/logger.md +290 -0
package/docs/mail.md +678 -0
package/docs/middleware.md +425 -0
package/docs/migrations.md +476 -0
package/docs/models.md +810 -0
package/docs/notifications.md +474 -0
package/docs/providers.md +363 -0
package/docs/queues.md +679 -0
package/docs/rate-limiting.md +155 -0
package/docs/redis.md +178 -0
package/docs/request-response.md +953 -0
package/docs/routing.md +804 -0
package/docs/scheduling.md +110 -0
package/docs/security.md +85 -0
package/docs/sessions.md +354 -0
package/docs/social-auth.md +174 -0
package/docs/static-files.md +211 -0
package/docs/storage.md +450 -0
package/docs/templates.md +315 -0
package/docs/testing.md +125 -0
package/docs/transformers.md +381 -0
package/docs/url-builder.md +295 -0
package/docs/validation.md +288 -0
package/docs/views.md +267 -0
package/docs/vite.md +434 -0
package/llms-full.txt +17694 -0
package/llms.txt +116 -0
package/package.json +38 -7

package/docs/examples/inertia.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -0,0 +1,92 @@
+// 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 };

package/docs/examples/mail.ts ADDED Viewed

@@ -0,0 +1,160 @@
+// 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 };

package/docs/examples/middleware.ts ADDED Viewed

@@ -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 ADDED Viewed

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