@shaferllc/keel 0.59.0 → 0.68.0

package/docs/examples/transformer.ts

@@ -0,0 +1,141 @@
+// Type-check harness for docs/transformers.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 run.
+import {
+  Transformer,
+  Model,
+  auth,
+  json,
+  type Attributes,
+  type DocumentOptions,
+  type Ctx,
+} from "@shaferllc/keel/core";
+
+class Post extends Model {
+  static table = "posts";
+  declare id: number;
+  declare title: string;
+  declare author: User;
+}
+
+class User extends Model {
+  static table = "users";
+  declare id: number;
+  declare name: string;
+  declare email: string;
+  declare created_at: string;
+  declare admin: boolean;
+  declare role: string;
+  declare permissions: string[];
+}
+
+class PostTransformer extends Transformer<Post> {
+  transform(post: Post): Attributes {
+    return { id: post.id, title: post.title };
+  }
+}
+
+// Defining a transformer
+export class BasicUserTransformer extends Transformer<User> {
+  transform(user: User): Attributes {
+    return {
+      id: user.id,
+      name: user.name,
+      joined: user.created_at,
+    };
+  }
+}
+
+// Constructor context + conditional fields + nesting + relations
+export class UserTransformer extends Transformer<User> {
+  constructor(private viewerId: string | null) {
+    super();
+  }
+
+  transform(user: User): Attributes {
+    return {
+      id: user.id,
+      name: user.name,
+      email: this.when(String(user.id) === this.viewerId, user.email),
+      token: this.when(fresh, () => mintToken(user), null),
+      ...this.mergeWhen(user.admin, { role: user.role, permissions: user.permissions }),
+      author: new UserTransformer(this.viewerId).item(user),
+      posts: this.whenLoaded(user, "posts", new PostTransformer()),
+      roles: this.whenLoaded(user, "roles", (roles: { name: string }[]) =>
+        roles.map((r) => r.name),
+      ),
+    };
+  }
+}
+
+class WrappedUserTransformer extends Transformer<User> {
+  wrapKey = "user";
+  transform(user: User): Attributes {
+    return { id: user.id, name: user.name };
+  }
+}
+
+declare const user: User;
+declare const list: User[];
+declare const fresh: boolean;
+declare const fetchedAt: string;
+declare function mintToken(user: User): string;
+
+// Transforming
+export function transforming() {
+  const users = new UserTransformer(null);
+  json(users.item(user));
+  json(users.collection(list));
+  json(users.document(list, { meta: { total: list.length } }));
+}
+
+// item null passthrough
+export function nullable() {
+  const out: Attributes | null = new BasicUserTransformer().item(null);
+  return out;
+}
+
+// Passing viewer context through the constructor
+export function withViewer() {
+  return json(new UserTransformer(auth().id()).collection(list));
+}
+
+// Nesting / relations — load first, then transform
+export async function relations() {
+  const users = await User.all<User>();
+  await User.load(users, "posts");
+  return json(new UserTransformer(null).collection(users));
+}
+
+// Response documents
+export async function documents() {
+  const page = await User.all<User>();
+  json(
+    new UserTransformer(null).document(page, {
+      meta: { total: page.length, page: 1 },
+    }),
+  );
+
+  new WrappedUserTransformer().document(user); // { user: { … } }
+  new UserTransformer(null).document(user, { key: null, meta: { fetchedAt } });
+  new UserTransformer(null).document(user, { key: "records", meta: { total: 42 } });
+}
+
+// In a controller
+export class UserController {
+  async show(c: Ctx) {
+    const found = await User.findOrFail<User>(c.req.param("id"));
+    return c.json(new UserTransformer(auth().id()).item(found));
+  }
+
+  async index(c: Ctx) {
+    const users = await User.all<User>();
+    await User.load(users, "posts");
+    return c.json(new UserTransformer(auth().id()).document(users));
+  }
+}
+
+// Types
+const options: DocumentOptions = { key: "records", meta: { total: 42 } };
+const shape: Attributes = { id: 1, name: "Ada" };
+export { options, shape };

package/docs/examples/transformers.ts

@@ -0,0 +1,49 @@
+// Type-check harness for docs/transformers.md. Exercises every type-checkable
+// snippet against the real exports so a renamed method or wrong signature fails
+// `npm run typecheck:docs`. Compile-only — never executed.
+import {
+  Transformer,
+  json,
+  type Attributes,
+  type DocumentOptions,
+} from "@shaferllc/keel/core";
+
+type User = { id: number; name: string; email: string; role: string; admin: boolean };
+type Post = { id: number; title: string };
+
+declare const isSelf: boolean;
+declare const isAdmin: boolean;
+declare const fresh: boolean;
+declare function mint(): string;
+
+class PostTransformer extends Transformer<Post> {
+  transform(post: Post): Attributes {
+    return { id: post.id, title: post.title };
+  }
+}
+
+class UserTransformer extends Transformer<User> {
+  transform(user: User): Attributes {
+    return {
+      id: user.id,
+      name: user.name,
+      email: this.when(isSelf, user.email), // key vanishes for others
+      token: this.when(fresh, () => mint(), null), // explicit fallback
+      ...this.mergeWhen(isAdmin, { role: user.role }),
+      posts: this.whenLoaded(user, "posts", new PostTransformer()),
+      roles: this.whenLoaded(user, "roles", (rs: { name: string }[]) => rs.map((r) => r.name)),
+    };
+  }
+}
+
+export function usage(user: User, users: User[]) {
+  const one: Attributes | null = new UserTransformer().item(user);
+  const many: Attributes[] = new UserTransformer().collection(users);
+  const wrapped: Attributes = new UserTransformer().document(users, {
+    meta: { total: users.length },
+  });
+  const opts: DocumentOptions = { key: "data", meta: { page: 1 } };
+  const custom: Attributes = new UserTransformer().document(user, opts);
+  const unwrapped: Attributes = new UserTransformer().document(user, { key: null });
+  return [json(one), json(many), json(wrapped), json(custom), json(unwrapped)];
+}

package/docs/examples/url-builder.ts

@@ -0,0 +1,86 @@
+// Type-check harness for docs/url-builder.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
+// executed.
+import {
+  Router,
+  Container,
+  matchers,
+  type UrlOptions,
+  type SignedUrlOptions,
+  type Matcher,
+} from "@shaferllc/keel/core";
+
+// The router is resolved from the container in a real app; construct it
+// directly here (as the test suite does).
+const router = new Router(new Container());
+
+// Controllers referenced by the doc's route registrations.
+class UserController {}
+class FileController {}
+class PostController {}
+class TeamController {}
+class CodeController {}
+class XController {}
+
+export function building() {
+  router.get("/users/:id", [UserController, "show"]).name("users.show");
+
+  const a: string = router.url("users.show", { id: 42 });
+  const b: string = router.url("users.show", { id: 42 }, { qs: { tab: "posts", page: 2 } });
+
+  router.get("/files/:name", [FileController]).name("files.show");
+  const c: string = router.url("files.show", { name: "a/b c.txt" });
+
+  return { a, b, c };
+}
+
+export function optionalParams() {
+  router.get("/posts/:id?", [PostController, "show"]).name("posts.show");
+  const withId: string = router.url("posts.show", { id: 7 });
+  const without: string = router.url("posts.show", {});
+  return { withId, without };
+}
+
+export function errors() {
+  // Throws at runtime; type-checks fine.
+  return router.url("nope");
+}
+
+export async function signing() {
+  const url: string = await router.signedUrl("download", { id: 7 });
+  const expiring: string = await router.signedUrl(
+    "download",
+    { id: 7 },
+    { expiresIn: 3600 },
+  );
+  const valid: boolean = await router.hasValidSignature();
+  return { url, expiring, valid };
+}
+
+export function constraints() {
+  router.get("/users/:id", [UserController]).where("id", /\d+/);
+  router.get("/p/:slug", [PostController]).where("slug", { match: /[a-z0-9-]+/ });
+
+  router.get("/n/:id", [UserController]).where("id", matchers.number());
+  router.get("/t/:id", [TeamController]).where("id", matchers.uuid());
+  router.get("/s/:slug", [PostController]).where("slug", matchers.slug());
+  router.get("/c/:code", [CodeController]).where("code", matchers.alpha());
+
+  // Also reachable off the instance.
+  router.get("/i/:id", [XController]).where("id", router.matchers.number());
+}
+
+export function typeSeams() {
+  const opts: UrlOptions = { qs: { page: 2, tab: "posts" } };
+  router.url("users.show", { id: 1 }, opts);
+
+  const signed: SignedUrlOptions = { qs: { plan: "pro" }, expiresIn: 3600 };
+
+  const a: Matcher = /\d+/;
+  const b: Matcher = "[0-9]+";
+  const c: Matcher = { match: /[a-z-]+/ };
+  router.get("/x/:id", [XController]).where("id", a);
+
+  return { opts, signed, a, b, c };
+}

package/docs/examples/validation.ts

@@ -0,0 +1,102 @@
+// Type-check harness for docs/validation.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 {
+  json,
+  validate,
+  validateRequest,
+  validated,
+  request,
+  response,
+  ValidationException,
+  Router,
+  type Schema,
+} from "@shaferllc/keel/core";
+import { z } from "zod";
+
+declare const Users: new (...a: unknown[]) => object;
+declare const Posts: new (...a: unknown[]) => object;
+
+export function declarative(router: Router) {
+  const NewUser = z.object({ email: z.string().email(), name: z.string().min(1) });
+  router.post("/users", [Users, "store"]).middleware([validateRequest({ body: NewUser })]);
+  router.get("/posts/:id", [Posts, "show"]).middleware([
+    validateRequest({
+      params: z.object({ id: z.coerce.number() }),
+      query: z.object({ page: z.coerce.number().min(1).default(1) }),
+    }),
+  ]);
+}
+
+export function readValidated() {
+  const user = validated<{ email: string; name: string }>("body");
+  const id = validated<{ id: number }>("params");
+  const page = validated<{ page: number }>("query");
+  return { user, id, page };
+}
+
+declare const email: string;
+declare const age: number;
+declare const err: unknown;
+
+const NewUser = z.object({
+  email: z.string().email(),
+  age: z.number().min(18),
+});
+
+export class UserController {
+  async store() {
+    const data = await validate(NewUser); // { email: string; age: number }
+    return json({ created: data.email }, 201);
+  }
+}
+
+const Search = z.object({ q: z.string().min(1), page: z.coerce.number().default(1) });
+
+export async function search() {
+  const { q, page } = await validate(Search, request.query());
+  return { q, page };
+}
+
+export async function mergedInput() {
+  const data = await validate(NewUser, await request.all());
+  return data;
+}
+
+export function handleError() {
+  if (err instanceof ValidationException) {
+    return response.json({ fields: err.errors }, 422);
+  }
+}
+
+export async function reference() {
+  const fromBody = await validate(NewUser);
+  const fromData = await validate(NewUser, { email, age });
+  return { fromBody, fromData };
+}
+
+// Schema<T> — hand-rolled implementation
+const Positive: Schema<number> = {
+  safeParse: (data) =>
+    typeof data === "number" && data > 0
+      ? { success: true, data }
+      : { success: false, error: { issues: [{ path: [], message: "must be > 0" }] } },
+};
+
+export async function customSchema() {
+  const n = await validate(Positive, 42); // number
+  return n;
+}
+
+// ValidationException seam
+export async function exceptionShape() {
+  try {
+    await validate(NewUser);
+  } catch (e) {
+    if (e instanceof ValidationException) {
+      const status: number = e.status;
+      const errors: Record<string, string[]> = e.errors;
+      return { status, errors };
+    }
+  }
+}

package/docs/examples/views.tsx

@@ -0,0 +1,62 @@
+// Type-check harness for docs/views.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
+// executed. This file is .tsx so the JSX in the examples compiles (tsconfig
+// already routes JSX through hono/jsx).
+import { view, View, type Renderable, type ViewConfig } from "@shaferllc/keel/core";
+import type { FC, PropsWithChildren } from "hono/jsx";
+
+// A layout is just a component that wraps its children.
+const Layout: FC<PropsWithChildren<{ title: string }>> = ({ title, children }) => (
+  <html lang="en">
+    <head>
+      <meta charset="utf-8" />
+      <title>{title}</title>
+    </head>
+    <body>{children}</body>
+  </html>
+);
+
+const WelcomePage: FC<{ appName: string }> = ({ appName }) => (
+  <Layout title={appName}>
+    <h1>⚓ {appName}</h1>
+    <p>Your view is rendering.</p>
+  </Layout>
+);
+
+const HomePage: FC = () => <p>home</p>;
+
+// An async component: data-fetching happens inside, render() awaits it.
+declare function loadStats(userId: number): Promise<unknown>;
+const Dashboard: FC<{ userId: number }> = async ({ userId }) => {
+  const stats = await loadStats(userId);
+  return <pre>{JSON.stringify(stats)}</pre>;
+};
+
+const Fragment: FC = () => <span>fragment</span>;
+
+export async function helper() {
+  const withProps = await view(WelcomePage, { appName: "Keel" });
+  const noProps = await view(HomePage);
+  const dash = await view(Dashboard, { userId: 1 });
+  return { withProps, noProps, dash };
+}
+
+export async function service() {
+  const html = await new View().render(WelcomePage({ appName: "Keel" }));
+  const raw = await new View().render("<p>plain html</p>");
+  const frag = await new View({ doctype: false }).render(Fragment({}));
+
+  // null / undefined render just the doctype (or empty when doctype is off).
+  const shell = await new View().render(null);
+  const empty = await new View({ doctype: false }).render(undefined);
+
+  return { html, raw, frag, shell, empty };
+}
+
+// Interface / type seams
+const a: Renderable = "<h1>hi</h1>";
+const b: Renderable = Promise.resolve("<h1>hi</h1>");
+const c: Renderable = null;
+const config: ViewConfig = { doctype: false };
+export { a, b, c, config };

package/docs/examples/vite.ts

@@ -0,0 +1,106 @@
+// Type-check harness for docs/vite.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 run.
+//
+// The `vite.config.ts` / `keelVite` snippets aren't covered here (they live in
+// the `@shaferllc/keel/vite` entry and need Vite's own types); tests/vite.test.ts
+// type-checks that plugin API instead.
+import {
+  ServiceProvider,
+  singleton,
+  serveStatic,
+  Vite,
+  viteTags,
+  viteAsset,
+  viteReactRefresh,
+  type ViteOptions,
+  type ViteAttributes,
+  type Manifest,
+  type ManifestChunk,
+} from "@shaferllc/keel/core";
+
+// Constructing + options
+export function constructing() {
+  const basic = new Vite({ entrypoints: ["resources/js/app.ts"], assetsUrl: "/assets" });
+
+  const cdn = new Vite({
+    entrypoints: ["resources/js/app.ts", "resources/js/admin.ts"],
+    assetsUrl: "https://cdn.example.com",
+  });
+
+  const withAttrs = new Vite({
+    entrypoints: ["resources/js/app.ts"],
+    scriptAttributes: { defer: true, crossorigin: "anonymous" },
+    styleAttributes: ({ src }) =>
+      src.includes("admin") ? { "data-turbo-track": "reload" } : undefined,
+  });
+
+  return { basic, cdn, withAttrs };
+}
+
+// Loading + injection
+export async function loading() {
+  const disk = await new Vite({ entrypoints: ["resources/js/app.ts"] }).loadFromDisk();
+
+  const manifest: Manifest = {
+    "resources/js/app.ts": { file: "app-abc123.js", isEntry: true, css: ["app-ghi.css"] },
+  };
+  const edge = new Vite({ entrypoints: ["resources/js/app.ts"] }).useManifest(manifest);
+  const forced = new Vite({}).useHotUrl("http://localhost:5173");
+
+  return { disk, edge, forced };
+}
+
+// Tag generation + resolution
+export function rendering() {
+  const vite = new Vite({ entrypoints: ["resources/js/app.ts"] }).useHotUrl("http://localhost:5173");
+  const one = vite.generateEntryPointsTags("resources/js/app.ts");
+  const many = vite.generateEntryPointsTags(["resources/js/app.ts", "resources/js/admin.ts"]);
+  const preamble = vite.reactHMR();
+  const asset = vite.assetPath("resources/images/logo.png");
+  const hot: string | null = vite.hot();
+  return { one, many, preamble, asset, hot };
+}
+
+export function manifestAccess() {
+  const vite = new Vite({}).useManifest({ "a.ts": { file: "a.hash.js" } });
+  const manifest: Manifest = vite.manifest();
+  const chunk: ManifestChunk | undefined = manifest["a.ts"];
+  return chunk;
+}
+
+// Binding in a provider
+export class AppServiceProvider extends ServiceProvider {
+  register(): void {
+    singleton(Vite, () => new Vite({ entrypoints: ["resources/js/app.ts"] }));
+  }
+  async boot(): Promise<void> {
+    await this.app.make(Vite).loadFromDisk();
+  }
+}
+
+// Serving the build in production
+export function serving() {
+  return serveStatic({ root: "./public" });
+}
+
+// Free helpers used in views
+export function helpers() {
+  const refresh = viteReactRefresh();
+  const tags = viteTags("resources/js/app.ts");
+  const many = viteTags(["resources/js/app.ts", "resources/js/admin.ts"]);
+  const logo = viteAsset("resources/images/logo.png");
+  return { refresh, tags, many, logo };
+}
+
+// Types
+const options: ViteOptions = {
+  entrypoints: ["resources/js/app.ts"],
+  hotFile: "public/hot",
+  buildDirectory: "public/assets",
+  assetsUrl: "/assets",
+};
+
+const attributes: ViteAttributes = ({ src, url }) => ({ "data-src": src, "data-url": url });
+
+export { options, attributes };