@shaferllc/keel 0.66.0 → 0.68.0

package/docs/examples/broadcasting.ts

@@ -0,0 +1,60 @@
+// Type-check harness for docs/broadcasting.md. Compile-only — never executed.
+import {
+  broadcast,
+  setBroadcaster,
+  getBroadcaster,
+  MemoryBroadcaster,
+  channelAuth,
+  authorizeChannel,
+  json,
+  request,
+  response,
+  auth,
+  type Broadcaster,
+} from "@shaferllc/keel/core";
+
+declare const sha: string;
+declare const socket: { send(data: string): void };
+
+type User = { id: number; name: string };
+
+export async function broadcasting() {
+  await broadcast("orders.42", "status", { state: "shipped" });
+  await broadcast(["team.7", "admins"], "deploy", { sha });
+  return getBroadcaster();
+}
+
+export function channels() {
+  channelAuth("orders.{orderId}", (user, params) => (user as User).id === Number(params.orderId));
+  channelAuth("presence.room.{room}", (user, params) => {
+    const u = user as User;
+    return { id: u.id, name: u.name, room: params.room };
+  });
+}
+
+export async function authEndpoint() {
+  const { channel } = (await request.all()) as { channel: string };
+  const ok = await authorizeChannel(channel, await auth().user());
+  if (!ok) response.abort("Forbidden", 403);
+  return json(ok);
+}
+
+export function fanOut() {
+  const bus = new MemoryBroadcaster();
+  setBroadcaster(bus);
+  const off = bus.subscribe("orders.42", (event, payload) =>
+    socket.send(JSON.stringify({ event, payload })),
+  );
+  off();
+}
+
+// A Pusher-style fetch driver
+export const pusher = (url: string, authorization: string): Broadcaster => ({
+  async publish(channels, event, payload) {
+    await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization },
+      body: JSON.stringify({ channels, name: event, data: JSON.stringify(payload) }),
+    });
+  },
+});

package/docs/examples/broker-cache-validate.ts

@@ -0,0 +1,34 @@
+// Type-check harness for the validating & caching sections of docs/broker.md.
+// Compile-only — never executed.
+import { Broker, Cache } from "@shaferllc/keel/core";
+import { z } from "zod";
+
+declare function createUser(p: unknown): unknown;
+declare function computeDaily(day: string): unknown;
+
+export function validating(broker: Broker) {
+  broker.createService({
+    name: "users",
+    actions: {
+      create: {
+        params: z.object({ email: z.string().email(), age: z.coerce.number().min(18) }),
+        handler: (ctx) => createUser(ctx.params),
+      },
+    },
+  });
+}
+
+export function caching(): Broker {
+  const broker = new Broker({ cacher: new Cache() });
+  broker.createService({
+    name: "stats",
+    actions: {
+      daily: {
+        cache: { ttl: 300, keys: ["day"] },
+        handler: (ctx: { params: { day: string } }) => computeDaily(ctx.params.day),
+      },
+      forever: { cache: true, handler: () => 1 },
+    },
+  });
+  return broker;
+}

package/docs/examples/broker-fault-tolerance.ts

@@ -0,0 +1,29 @@
+// Type-check harness for the fault-tolerance & registry sections of
+// docs/broker.md. Compile-only — never executed.
+import { Broker } from "@shaferllc/keel/core";
+
+declare const id: string;
+declare const cart: unknown;
+
+export async function faultTolerance(broker: Broker) {
+  await broker.call("orders.get", { id }, {
+    retries: 3,
+    fallback: { id, status: "unknown" },
+  });
+  await broker.call("pricing.quote", cart, {
+    timeout: 500,
+    fallback: (err: Error) => ({ error: err.message, price: null }),
+  });
+}
+
+export function defaults(): Broker {
+  return new Broker({ requestTimeout: 1000, retries: 2 });
+}
+
+export function introspection(broker: Broker) {
+  const has: boolean = broker.hasAction("users.find");
+  const actions: string[] = broker.listActions();
+  const services: string[] = broker.listServices();
+  const svc = broker.getService("users");
+  return { has, actions, services, name: svc?.name };
+}

package/docs/examples/broker-middleware.ts

@@ -0,0 +1,27 @@
+// Type-check harness for the Middlewares section of docs/broker.md.
+// Compile-only — never executed.
+import { Broker, logger, type BrokerMiddleware } from "@shaferllc/keel/core";
+
+const timing: BrokerMiddleware = {
+  name: "timing",
+  localAction(next, action) {
+    return async (ctx) => {
+      const start = performance.now();
+      try {
+        return await next(ctx);
+      } finally {
+        logger().debug("action", { action, ms: performance.now() - start });
+      }
+    };
+  },
+  started(broker) {
+    logger().info("broker up", { nodeID: broker.nodeID });
+  },
+  stopped() {
+    /* flush metrics, close connections */
+  },
+};
+
+export function withMiddleware(): Broker {
+  return new Broker({ middlewares: [timing, { name: "noop" }] });
+}

package/docs/examples/broker.ts

@@ -0,0 +1,203 @@
+// Type-check harness for docs/broker.md. Compile-only — never executed.
+import {
+  Broker,
+  setBroker,
+  broker,
+  type Context,
+  type Transporter,
+} from "@shaferllc/keel/core";
+
+export function defineService() {
+  broker().createService({
+    name: "users",
+    settings: { defaultRole: "member" },
+    metadata: { region: "us-east" },
+    actions: {
+      async get(this: any, ctx: Context<{ id: number }>) {
+        return { id: ctx.params.id, role: this.settings.defaultRole };
+      },
+      async create(ctx: Context<{ email: string }>) {
+        const user = { id: 1, email: ctx.params.email };
+        await ctx.emit("user.created", user);
+        return user;
+      },
+    },
+    events: {
+      "user.created": (_ctx: Context) => {},
+    },
+  });
+}
+
+export async function calling() {
+  await broker().call("users.create", { email: "ada@keel.dev" });
+  await broker().call("users.get", { id: 1 }, { meta: { locale: "en" } });
+  await broker().call("reports.build", {}, { timeout: 5000 });
+
+  const [a, b] = await broker().mcall<[unknown, unknown]>([
+    { action: "users.get", params: { id: 1 } },
+    { action: "users.get", params: { id: 2 } },
+  ]);
+  const { profile, posts } = await broker().mcall<{ profile: unknown; posts: unknown }>({
+    profile: { action: "users.get", params: { id: 1 } },
+    posts: { action: "posts.byUser", params: { id: 1 } },
+  });
+  return { a, b, profile, posts };
+}
+
+export async function contextSlots() {
+  await broker().call("reports.build", {}, {
+    headers: { "x-trace": "abc" },
+    requestID: "req-42",
+  });
+}
+
+export function contextTree() {
+  broker().createService({
+    name: "orders",
+    actions: {
+      place(ctx: Context) {
+        void ctx.id;
+        void ctx.parentID;
+        void ctx.level;
+        void ctx.caller;
+        void ctx.action?.name;
+        void ctx.toJSON();
+        return ctx.call("orders.notify");
+      },
+      notify: (_ctx: Context) => {},
+    },
+    events: {
+      "order.placed": (ctx: Context) => {
+        void ctx.eventName;
+        void ctx.eventType;
+        void ctx.eventGroups;
+      },
+    },
+  });
+}
+
+export async function events() {
+  await broker().emit("user.created", { id: 1 });
+  await broker().emit("user.created", { id: 1 }, { groups: ["notify"] });
+  await broker().broadcast("cache.flush");
+  await broker().broadcastLocal("cache.warm");
+  broker().hasEventListener("user.created");
+
+  broker().createService({
+    name: "mailer",
+    events: { "user.created": { group: "notify", handler: (_ctx: Context) => {} } },
+  });
+
+  broker().createService({
+    name: "registry",
+    events: {
+      "user.??eated": (_ctx: Context) => {},
+      "$services.changed": (ctx: Context) => void (ctx.params as { service: string }).service,
+      "$broker.started": (_ctx: Context) => {},
+      "$broker.stopped": (_ctx: Context) => {},
+    },
+  });
+}
+
+export function fullActionDefs() {
+  broker().createService({
+    name: "billing",
+    actions: {
+      quote: (_ctx: Context) => ({ cents: 999 }),
+      charge: {
+        visibility: "private",
+        timeout: 3000,
+        hooks: {
+          before: (_ctx) => {},
+          after: (_ctx, res) => res,
+        },
+        handler: (ctx: Context<{ cents: number }>) => ctx.params.cents,
+      },
+      checkout(this: any, ctx: Context<{ cents: number }>) {
+        return this.actions.charge({ cents: ctx.params.cents });
+      },
+    },
+  });
+}
+
+export function serviceHooks() {
+  broker().createService({
+    name: "users",
+    hooks: {
+      before: {
+        "*": (_ctx) => {},
+        "create|update": (_ctx) => {},
+        remove: (_ctx) => {},
+      },
+      after: {
+        get: (_ctx, res: any) => ({ ...res, fetchedAt: Date.now() }),
+      },
+      error: {
+        "*": (_ctx, err) => {
+          throw err;
+        },
+      },
+    },
+    actions: {
+      get: (_ctx: Context) => ({}),
+      create: (_ctx: Context) => ({}),
+      update: (_ctx: Context) => ({}),
+      remove: (_ctx: Context) => ({}),
+    },
+  });
+}
+
+const Timestamps = {
+  name: "timestamps",
+  settings: { softDelete: false },
+  methods: {
+    touch(this: any) {},
+  },
+};
+
+export function mixins() {
+  broker().createService({
+    mixins: [Timestamps],
+    name: "articles",
+    settings: { perPage: 10 },
+    actions: { list: () => [] },
+    merged(schema) {
+      void schema.name;
+    },
+  });
+}
+
+export function dependencies() {
+  broker().createService({
+    name: "api",
+    dependencies: ["db", "cache"],
+    async started(this: any) {
+      await this.waitForServices("mailer", 5000);
+    },
+  });
+}
+
+export async function lifecycleAndCluster() {
+  const b = broker();
+  b.createService({
+    name: "clock",
+    async started(this: any) {
+      this.timer = setInterval(() => this.broker.broadcast("tick"), 1000);
+    },
+    async stopped(this: any) {
+      clearInterval(this.timer);
+    },
+  });
+  await b.start();
+  await b.stop();
+
+  await broker().emit("user.created", { id: 1 });
+  await broker().broadcast("cache.flush");
+  broker().hasEventListener("user.created");
+
+  const nats: Transporter = {
+    async connect(_broker) {},
+    async disconnect() {},
+  };
+  setBroker(new Broker({ nodeID: "api-1", transporter: nats, requestTimeout: 10_000 }));
+}

package/docs/examples/cache.ts

@@ -0,0 +1,222 @@
+// Type-check harness for docs/cache.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 {
+  cache,
+  Cache,
+  MemoryStore,
+  singleton,
+  type CacheStore,
+  type RememberOptions,
+  type PutOptions,
+} from "@shaferllc/keel/core";
+import { db } from "@shaferllc/keel/core";
+
+type User = { id: number; name: string };
+
+declare const user: User;
+declare const code: string;
+declare const cfg: unknown;
+declare const config: unknown;
+declare const id: number;
+declare const name: string;
+declare const fallback: string;
+
+declare function computeExpensiveStats(): Promise<{ total: number }>;
+declare function loadConfig(): { url: string };
+declare function fetchRates(): Promise<Record<string, number>>;
+declare function runJobOnce(): Promise<void>;
+declare function warmProfile(id: number): Promise<void>;
+declare const requests: unknown[];
+declare function runExpensiveReport(): Promise<{ rows: number }>;
+
+export async function basics() {
+  await cache().put("user:1", user);
+  await cache().put("otp", code, 300);
+  await cache().add("otp", code, 300);
+  await cache().get("user:1");
+  await cache().get("missing", fallback);
+  await cache().has("otp");
+  await cache().missing("otp");
+  await cache().forget("otp");
+  await cache().forgetMany(["otp", "user:1"]);
+  await cache().pull("otp");
+  await cache().flush();
+}
+
+export async function stampedeAndGrace() {
+  await Promise.all(
+    requests.map(() => cache().remember("report", 300, runExpensiveReport)),
+  );
+
+  const rates = await cache().remember("fx.rates", 60, fetchRates, { grace: 3600 });
+  return rates;
+}
+
+export async function newMethods() {
+  if (await cache().add("job:lock", 1, 30)) {
+    await runJobOnce();
+  }
+  if (await cache().missing("profile:1")) await warmProfile(1);
+  await cache().forgetMany(["user:1", "user:1:posts", "user:1:stats"]);
+}
+
+export async function tags() {
+  await cache().put("post:1", user, 600, { tags: ["posts"] });
+  await cache().remember("feed:home", 300, computeExpensiveStats, { tags: ["posts"] });
+  await cache().put("post:2", user, 600, { tags: ["posts", "featured"] });
+  await cache().deleteByTag(["posts"]);
+}
+
+export async function namespaces() {
+  const users = cache().namespace("users");
+  const posts = cache().namespace("posts");
+  await users.put("1", user); // "users:1"
+  await posts.put("1", user); // "posts:1"
+  await users.flush(); // scoped
+  await posts.get("1");
+
+  // Nested, with the full API.
+  const team = cache().namespace("org").namespace("team");
+  await team.remember("count", 60, () => 1, { grace: 30, tags: ["team"] });
+  await team.flush();
+}
+
+// Type seams for the options bags.
+const graceOpts: RememberOptions = { grace: 3600, tags: ["posts"] };
+const putOpts: PutOptions = { tags: ["posts"] };
+export { graceOpts, putOpts };
+
+export async function remember() {
+  const stats = await cache().remember("dashboard.stats", 60, async () => {
+    return computeExpensiveStats();
+  });
+  const conf = await cache().rememberForever("app.config", () => loadConfig());
+  return { stats, conf };
+}
+
+export async function readThroughThenInvalidate() {
+  const token = await cache().pull<string>("reset:jane", "");
+
+  await db("users").where("id", id).update({ name });
+  await cache().forget(`user:${id}`);
+  return token;
+}
+
+export async function ttls() {
+  await cache().put("otp", code, 300);
+  await cache().put("app.config", cfg);
+}
+
+// --- Custom store (narrative) ---
+class RedisStore implements CacheStore {
+  async get(key: string) {
+    return key;
+  }
+  async set(key: string, value: unknown, ttlMs?: number) {
+    void key;
+    void value;
+    void ttlMs;
+  }
+  async delete(key: string) {
+    void key;
+  }
+  async clear() {}
+}
+
+export function customStore() {
+  singleton(Cache, () => new Cache(new RedisStore()));
+}
+
+// --- API reference: cache() / Cache construction ---
+export async function cacheHelper() {
+  await cache().put("user:1", user);
+}
+
+export function construction() {
+  const c = new Cache();
+  const r = new Cache(new MemoryStore());
+  return { c, r };
+}
+
+export async function cacheGet() {
+  const u = await cache().get<User>("user:1");
+  const port = await cache().get("app.port", 3000);
+  return { u, port };
+}
+
+export async function cachePut() {
+  await cache().put("otp", code, 300);
+  await cache().put("user:1", user);
+}
+
+export async function cacheHas() {
+  if (await cache().has("otp")) {
+    /* still valid */
+  }
+}
+
+export async function cacheForget() {
+  await cache().forget("user:1");
+}
+
+export async function cachePull() {
+  const token = await cache().pull<string>("reset:jane", "");
+  return token;
+}
+
+export async function cacheFlush() {
+  await cache().flush();
+}
+
+export async function cacheRemember() {
+  const stats = await cache().remember("dashboard.stats", 60, () =>
+    computeExpensiveStats(),
+  );
+  return stats;
+}
+
+export async function cacheRememberForever() {
+  const conf = await cache().rememberForever("app.config", () => loadConfig());
+  return conf;
+}
+
+// --- MemoryStore methods ---
+export function memoryStore() {
+  const store = new MemoryStore();
+  store.set("k", 1, 1000);
+  const v = store.get("k");
+  store.set("otp", code, 300_000);
+  store.set("cfg", config);
+  store.delete("otp");
+  store.clear();
+  return v;
+}
+
+// --- Interfaces & types: CacheStore (KV example) ---
+type KV = {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, ttlMs?: number): Promise<void>;
+  delete(key: string): Promise<void>;
+};
+declare const kv: KV;
+
+class KVStore implements CacheStore {
+  constructor(private kv: KV) {}
+  async get(key: string) {
+    return (await this.kv.get(key)) ?? undefined;
+  }
+  async set(key: string, value: unknown, ttlMs?: number) {
+    await this.kv.put(key, JSON.stringify(value), ttlMs);
+  }
+  async delete(key: string) {
+    await this.kv.delete(key);
+  }
+  async clear() {
+    /* KV has no bulk clear — list + delete, or skip */
+  }
+}
+
+export function kvStore() {
+  singleton(Cache, () => new Cache(new KVStore(kv)));
+}

package/docs/examples/configuration.ts

@@ -0,0 +1,81 @@
+// Type-check harness for docs/configuration.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 {
+  env,
+  config,
+  app,
+  Config,
+  type ConfigData,
+} from "@shaferllc/keel/core";
+
+// A stand-in for a user's service, used only for `app().make(...)`.
+class SomeService {}
+
+export function envHelper() {
+  const name = env("APP_NAME"); // string
+  const debug = env("APP_DEBUG", false); // boolean
+  const port = env("APP_PORT", 3000); // number
+  const fallback = env("MISSING", "default"); // string
+
+  const portStr = env("APP_PORT"); // string (no numeric fallback)
+  const portNum = env("APP_PORT", 0); // number
+  const debugBool = env("APP_DEBUG"); // string (declared) / boolean (runtime)
+
+  return { name, debug, port, fallback, portStr, portNum, debugBool };
+}
+
+// config/app.ts — a config file's default export.
+export function configFile() {
+  return {
+    name: env("APP_NAME", "Keel"),
+    env: env("APP_ENV", "local"),
+    debug: env("APP_DEBUG", true),
+    url: env("APP_URL", "http://localhost:3000"),
+    port: env("APP_PORT", 3000),
+  };
+}
+
+export function readingConfig() {
+  const a = config("app.name"); // unknown
+  const b = config("app.port", 3000); // number
+  const c = config("services.stripe.key"); // unknown
+  const d = config<number>("app.port", 3000);
+  const e = config("services.stripe.key", ""); // string
+  const f = config("nope.at.all"); // unknown | undefined
+  return { a, b, c, d, e, f };
+}
+
+export function containerHelper() {
+  app().make(SomeService);
+  app().config().get("app.name");
+}
+
+export function longForm() {
+  const cfg = app().make(Config);
+
+  cfg.get("app.name");
+  cfg.get("app.port", 3000);
+  cfg.get("services.stripe.key");
+  cfg.get<string>("services.stripe.key");
+  cfg.set("app.debug", false);
+  cfg.all();
+
+  if (cfg.get("services.stripe.key") !== undefined) {
+    // configured
+  }
+}
+
+export function configClass() {
+  const repo = new Config({ app: { name: "Keel", port: 3000 } });
+  const port = repo.get("app.port"); // unknown
+  repo.set("services.stripe.key", "sk_test_…"); // creates `services`
+  const tree: ConfigData = repo.all();
+  return { port, tree };
+}
+
+// Interface / type seams
+const data: ConfigData = {
+  app: { name: "Keel", port: 3000 },
+};
+export { data };