@shaferllc/keel 0.36.0 → 0.58.0

package/README.md

@@ -163,33 +163,45 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 |-------|----------------|
 | [Getting Started](./docs/getting-started.md) | Install, run, first route and controller |
 | [The Service Container](./docs/container.md) | Binding and resolving services, DI |
-| [Service Providers](./docs/providers.md) | The register/boot lifecycle |
+| [Service Providers](./docs/providers.md) | Plugin system: register/boot lifecycle, options |
 | [Configuration](./docs/configuration.md) | `config/*.ts`, dot-notation, `env()` |
 | [Routing](./docs/routing.md) | Closures, controller tuples, groups, resources, domains |
 | [URL Builder](./docs/url-builder.md) | Named-route URLs, signed URLs |
 | [Hashing & Encryption](./docs/hashing.md) | Password hashing, AES value encryption |
 | [Controllers](./docs/controllers.md) | Classes, DI, single-action, lazy-loaded |
 | [Request & Response](./docs/request-response.md) | Input, cookies, output, `abort()` |
+| [Request Decorators](./docs/decorators.md) | Lazy, memoized per-request values |
+| [Lifecycle Hooks](./docs/hooks.md) | onReady/onShutdown, graceful shutdown, onRoute |
 | [Sessions](./docs/sessions.md) | Cookie-backed sessions, flash messages |
 | [Authentication](./docs/authentication.md) | Session auth, guards, user provider |
+| [Authorization](./docs/authorization.md) | Gates & policies, `can`/`authorize` |
 | [Database](./docs/database.md) | Driver-agnostic query builder |
 | [Models](./docs/models.md) | Active-record: find/create/save, casts, relations |
 | [Migrations](./docs/migrations.md) | Schema builder + migrator, dialect-aware |
 | [Factories & Seeders](./docs/factories.md) | Built-in Faker, model factories, seeders |
 | [Mail](./docs/mail.md) | Fluent mailer, pluggable transports, edge-safe |
 | [Queues & Jobs](./docs/queues.md) | Dispatch jobs, pluggable drivers, workers |
+| [Task Scheduling](./docs/scheduling.md) | Cron-style recurring tasks, one trigger |
 | [Notifications](./docs/notifications.md) | Multi-channel (mail/db), queueable |
+| [Broadcasting](./docs/broadcasting.md) | Real-time channels, pluggable, presence auth |
+| [Transformers](./docs/transformers.md) | Shape models into API JSON; conditional fields, relations |
 | [Events](./docs/events.md) | Emit/listen decoupling, async listeners |
+| [Service Broker](./docs/broker.md) | Moleculer-style services, call/emit, pluggable transport |
 | [Cache](./docs/cache.md) | TTLs, the remember pattern, pluggable stores |
-| [Logger](./docs/logger.md) | Leveled structured logging, child loggers |
+| [Redis](./docs/redis.md) | Pluggable client, memory driver, cache adapter |
+| [Logger](./docs/logger.md) | Structured logging, per-request `reqId`, redaction |
 | [Static Files](./docs/static-files.md) | serveStatic(), caching, dot-file safety |
+| [Storage](./docs/storage.md) | Pluggable disks (local/S3/R2), edge-safe |
 | [Views](./docs/views.md) | Hono JSX components, layouts, the View service |
+| [Templates](./docs/templates.md) | `{{ }}` + `@`-tag templating engine, edge-safe |
 | [Middleware](./docs/middleware.md) | Global middleware, writing your own |
 | [Rate Limiting](./docs/rate-limiting.md) | rateLimiter() middleware, per-key buckets |
 | [Errors](./docs/errors.md) | HTTP exceptions, debug page, custom handlers |
+| [Testing](./docs/testing.md) | Inject requests, fluent response assertions |
 | [Debugging](./docs/debugging.md) | dump() and dd() (dump-and-die) |
 | [Validation](./docs/validation.md) | `validate()` with Zod, auto-422 field errors |
 | [Inertia](./docs/inertia.md) | Server-side Inertia.js adapter |
+| [Vite](./docs/vite.md) | Frontend build: HMR in dev, hashed manifest in prod |
 | [The Console](./docs/console.md) | `serve`, `routes`, `make:*` generators |
 | [Architecture](./docs/architecture.md) | Container, kernel, request lifecycle |
 | [Built on Hono](./docs/hono.md) | The Hono layer underneath, and using it directly |

package/dist/core/application.d.ts

@@ -12,29 +12,85 @@ import { Config, type ConfigData } from "./config.js";
 import { Router } from "./http/router.js";
 import { View } from "./view.js";
 import { type ProviderClass } from "./provider.js";
+import type { Listener } from "./events.js";
+/** A configurator: a plain function that sets the app up and may return anything. */
+export type Configurator = (app: Application) => unknown;
 export interface BootOptions {
     /** Auto-load .env and config/*.ts from the filesystem. Default: true (Node). */
     discoverConfig?: boolean;
     /** Config to merge in directly — the way to configure on Workers. */
     config?: ConfigData;
 }
+/** A lifecycle hook — receives the application, may be async. */
+export type LifecycleHook = (app: Application) => void | Promise<void>;
 export declare class Application extends Container {
     readonly basePath: string;
     private providers;
     private booted;
+    private terminated;
+    private readyHooks;
+    private shutdownHooks;
     constructor(basePath?: string);
     path(...segments: string[]): string;
     config(): Config;
     router(): Router;
     view(): View;
+    /**
+     * Run a configurator function against the app and return the app for
+     * chaining — Feathers' lightweight plugin idiom, an inline alternative to a
+     * full `ServiceProvider`. The function may bind services, register routes, or
+     * merge config. Use `register()` when you need the register/boot two-phase
+     * lifecycle; use `configure()` for one-shot setup.
+     *
+     *   app.configure(rateLimit({ max: 100 })).configure(auth());
+     */
+    configure(configurator: Configurator): this;
+    /**
+     * Set an app-wide value — Feathers' `app.set`. Backed by the config
+     * repository, so `app.set("db.url", …)` and `config().get("db.url")` share
+     * one store. Chainable.
+     */
+    set(key: string, value: unknown): this;
+    /** Read an app-wide value set via `set()` (or any config key). */
+    get<T = unknown>(key: string, fallback?: T): T;
+    /**
+     * Subscribe to an app event — delegates to the `Events` singleton so
+     * `app.on(...)` and the global `listen()` helper reach the same emitter.
+     * Returns an unsubscribe function.
+     */
+    on<T = unknown>(event: string, listener: Listener<T>): () => void;
+    /** Subscribe for a single emission. Returns an unsubscribe function. */
+    once<T = unknown>(event: string, listener: Listener<T>): () => void;
+    /** Unsubscribe a listener registered with `on()`/`once()`. */
+    off<T = unknown>(event: string, listener: Listener<T>): this;
+    /** Emit an app event, awaiting every listener in registration order. */
+    emit<T = unknown>(event: string, payload?: T): Promise<void>;
     /** Merge a config object into the repository under its top-level keys. */
     private mergeConfig;
     /** Load .env via dotenv (Node only; no-op elsewhere). */
     private loadEnv;
     /** Load every /config/*.ts file under its filename key (Node only). */
     private loadConfig;
-    /** Register a provider instance (defers boot until boot()). */
-    register(Provider: ProviderClass): this;
+    /** Register a provider, optionally with options passed to its constructor. */
+    register(Provider: ProviderClass, options?: unknown): this;
     /** Load config, register providers, then boot them. */
     boot(providers?: ProviderClass[], options?: BootOptions): Promise<this>;
+    /**
+     * Run `hook` once the application has finished booting. If it's already
+     * booted, the hook runs immediately.
+     */
+    onReady(hook: LifecycleHook): this;
+    /**
+     * Register a shutdown hook — close database/Redis connections, flush queues,
+     * etc. Hooks run in reverse registration order (LIFO) on `terminate()`.
+     */
+    onShutdown(hook: LifecycleHook): this;
+    /**
+     * Gracefully shut the application down: run every shutdown hook (newest
+     * first). Idempotent — a second call is a no-op. A hook that throws doesn't
+     * stop the others; the first error is re-thrown after all have run.
+     */
+    terminate(): Promise<void>;
+    /** Whether `terminate()` has run. */
+    get isTerminated(): boolean;
 }

package/dist/core/application.js

@@ -19,6 +19,9 @@ export class Application extends Container {
     basePath;
     providers = [];
     booted = false;
+    terminated = false;
+    readyHooks = [];
+    shutdownHooks = [];
     constructor(basePath = ".") {
         super();
         this.basePath = basePath;
@@ -48,6 +51,53 @@ export class Application extends Container {
     view() {
         return this.make(View);
     }
+    /**
+     * Run a configurator function against the app and return the app for
+     * chaining — Feathers' lightweight plugin idiom, an inline alternative to a
+     * full `ServiceProvider`. The function may bind services, register routes, or
+     * merge config. Use `register()` when you need the register/boot two-phase
+     * lifecycle; use `configure()` for one-shot setup.
+     *
+     *   app.configure(rateLimit({ max: 100 })).configure(auth());
+     */
+    configure(configurator) {
+        configurator(this);
+        return this;
+    }
+    /**
+     * Set an app-wide value — Feathers' `app.set`. Backed by the config
+     * repository, so `app.set("db.url", …)` and `config().get("db.url")` share
+     * one store. Chainable.
+     */
+    set(key, value) {
+        this.config().set(key, value);
+        return this;
+    }
+    /** Read an app-wide value set via `set()` (or any config key). */
+    get(key, fallback) {
+        return this.config().get(key, fallback);
+    }
+    /**
+     * Subscribe to an app event — delegates to the `Events` singleton so
+     * `app.on(...)` and the global `listen()` helper reach the same emitter.
+     * Returns an unsubscribe function.
+     */
+    on(event, listener) {
+        return this.make(Events).on(event, listener);
+    }
+    /** Subscribe for a single emission. Returns an unsubscribe function. */
+    once(event, listener) {
+        return this.make(Events).once(event, listener);
+    }
+    /** Unsubscribe a listener registered with `on()`/`once()`. */
+    off(event, listener) {
+        this.make(Events).off(event, listener);
+        return this;
+    }
+    /** Emit an app event, awaiting every listener in registration order. */
+    async emit(event, payload) {
+        await this.make(Events).emit(event, payload);
+    }
     /** Merge a config object into the repository under its top-level keys. */
     mergeConfig(data) {
         const repo = this.make(Config);
@@ -91,9 +141,9 @@ export class Application extends Container {
             // No config dir or not on Node — fine.
         }
     }
-    /** Register a provider instance (defers boot until boot()). */
-    register(Provider) {
-        const provider = new Provider(this);
+    /** Register a provider, optionally with options passed to its constructor. */
+    register(Provider, options) {
+        const provider = new Provider(this, options);
         this.providers.push(provider);
         return this;
     }
@@ -119,6 +169,52 @@ export class Application extends Container {
             await provider.boot();
         }
         this.booted = true;
+        for (const hook of this.readyHooks)
+            await hook(this);
         return this;
     }
+    /**
+     * Run `hook` once the application has finished booting. If it's already
+     * booted, the hook runs immediately.
+     */
+    onReady(hook) {
+        if (this.booted)
+            void hook(this);
+        else
+            this.readyHooks.push(hook);
+        return this;
+    }
+    /**
+     * Register a shutdown hook — close database/Redis connections, flush queues,
+     * etc. Hooks run in reverse registration order (LIFO) on `terminate()`.
+     */
+    onShutdown(hook) {
+        this.shutdownHooks.push(hook);
+        return this;
+    }
+    /**
+     * Gracefully shut the application down: run every shutdown hook (newest
+     * first). Idempotent — a second call is a no-op. A hook that throws doesn't
+     * stop the others; the first error is re-thrown after all have run.
+     */
+    async terminate() {
+        if (this.terminated)
+            return;
+        this.terminated = true;
+        let firstError;
+        for (const hook of [...this.shutdownHooks].reverse()) {
+            try {
+                await hook(this);
+            }
+            catch (err) {
+                firstError ??= err;
+            }
+        }
+        if (firstError)
+            throw firstError;
+    }
+    /** Whether `terminate()` has run. */
+    get isTerminated() {
+        return this.terminated;
+    }
 }

package/dist/core/authorization.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Authorization — gates and policies over the top of authentication. Where
+ * `auth()` answers *who you are*, this answers *what you're allowed to do*.
+ *
+ *   // a gate: an ad-hoc ability
+ *   define("update-post", (user, post) => post.authorId === user.id);
+ *   if (await can("update-post", post)) { ... }
+ *   await authorize("update-post", post);        // throws 403 otherwise
+ *
+ *   // a policy: abilities grouped per model
+ *   class PostPolicy {
+ *     update(user, post) { return post.authorId === user.id; }
+ *     delete(user, post) { return user.admin || post.authorId === user.id; }
+ *   }
+ *   policy(Post, PostPolicy);
+ *   await can("update", post);                    // routes to PostPolicy.update
+ *
+ * The current user is resolved from `auth().user()` by default; override with
+ * `setUserResolver` (e.g. token auth) or check a specific user with `canFor`.
+ */
+type User = unknown;
+type Args = unknown[];
+type Constructor = new (...args: never[]) => object;
+/** A gate callback — receives the user and the checked arguments. */
+export type GateCallback = (user: User, ...args: Args) => boolean | Promise<boolean>;
+/** Runs before every check; return a boolean to short-circuit (e.g. admin bypass). */
+export type BeforeCallback = (user: User, ability: string, args: Args) => boolean | undefined | Promise<boolean | undefined>;
+/** Define a gate — an ad-hoc ability keyed by name. */
+export declare function define(ability: string, callback: GateCallback): void;
+/**
+ * Register a policy (instance or class) for a model — its methods are abilities.
+ * `impl` is intentionally loose (`object` / class) so a normally-typed policy
+ * class — `update(user: User, post: Post)` — fits without wrestling the compiler.
+ */
+export declare function policy(model: Constructor, impl: object | (new () => object)): void;
+/** Register a callback that runs before every check (return a boolean to decide). */
+export declare function gateBefore(callback: BeforeCallback): void;
+/** Override how the "current user" is resolved (default: `auth().user()`). */
+export declare function setUserResolver(resolver: () => User | Promise<User>): void;
+/** Reset gates, policies, the before-hook, and the resolver (test helper). */
+export declare function clearAuthorization(): void;
+/** Whether the current user is allowed the ability (with the given arguments). */
+export declare function can(ability: string, ...args: Args): Promise<boolean>;
+/** The negation of `can`. */
+export declare function cannot(ability: string, ...args: Args): Promise<boolean>;
+/** Like `can`, but for a specific user rather than the current one. */
+export declare function canFor(user: User, ability: string, ...args: Args): Promise<boolean>;
+/** Throw a 403 `ForbiddenException` unless the current user is allowed. */
+export declare function authorize(ability: string, ...args: Args): Promise<void>;
+/** Like `authorize`, but for a specific user. */
+export declare function authorizeFor(user: User, ability: string, ...args: Args): Promise<void>;
+export {};

package/dist/core/authorization.js

@@ -0,0 +1,97 @@
+/**
+ * Authorization — gates and policies over the top of authentication. Where
+ * `auth()` answers *who you are*, this answers *what you're allowed to do*.
+ *
+ *   // a gate: an ad-hoc ability
+ *   define("update-post", (user, post) => post.authorId === user.id);
+ *   if (await can("update-post", post)) { ... }
+ *   await authorize("update-post", post);        // throws 403 otherwise
+ *
+ *   // a policy: abilities grouped per model
+ *   class PostPolicy {
+ *     update(user, post) { return post.authorId === user.id; }
+ *     delete(user, post) { return user.admin || post.authorId === user.id; }
+ *   }
+ *   policy(Post, PostPolicy);
+ *   await can("update", post);                    // routes to PostPolicy.update
+ *
+ * The current user is resolved from `auth().user()` by default; override with
+ * `setUserResolver` (e.g. token auth) or check a specific user with `canFor`.
+ */
+import { ForbiddenException } from "./exceptions.js";
+import { auth } from "./auth.js";
+const gates = new Map();
+const policies = new Map();
+let beforeCallback;
+let userResolver = () => auth().user();
+/** Define a gate — an ad-hoc ability keyed by name. */
+export function define(ability, callback) {
+    gates.set(ability, callback);
+}
+/**
+ * Register a policy (instance or class) for a model — its methods are abilities.
+ * `impl` is intentionally loose (`object` / class) so a normally-typed policy
+ * class — `update(user: User, post: Post)` — fits without wrestling the compiler.
+ */
+export function policy(model, impl) {
+    const instance = typeof impl === "function" ? new impl() : impl;
+    policies.set(model, instance);
+}
+/** Register a callback that runs before every check (return a boolean to decide). */
+export function gateBefore(callback) {
+    beforeCallback = callback;
+}
+/** Override how the "current user" is resolved (default: `auth().user()`). */
+export function setUserResolver(resolver) {
+    userResolver = resolver;
+}
+/** Reset gates, policies, the before-hook, and the resolver (test helper). */
+export function clearAuthorization() {
+    gates.clear();
+    policies.clear();
+    beforeCallback = undefined;
+    userResolver = () => auth().user();
+}
+async function evaluate(user, ability, args) {
+    if (beforeCallback) {
+        const decided = await beforeCallback(user, ability, args);
+        if (typeof decided === "boolean")
+            return decided;
+    }
+    // Policy: the first argument is a model with a registered policy + matching method.
+    const subject = args[0];
+    if (subject && typeof subject === "object") {
+        const found = policies.get(subject.constructor);
+        const method = found?.[ability];
+        if (typeof method === "function")
+            return Boolean(await method.call(found, user, ...args));
+    }
+    const gate = gates.get(ability);
+    if (gate)
+        return Boolean(await gate(user, ...args));
+    return false; // unknown ability — deny by default
+}
+/** Whether the current user is allowed the ability (with the given arguments). */
+export async function can(ability, ...args) {
+    return evaluate(await userResolver(), ability, args);
+}
+/** The negation of `can`. */
+export async function cannot(ability, ...args) {
+    return !(await can(ability, ...args));
+}
+/** Like `can`, but for a specific user rather than the current one. */
+export async function canFor(user, ability, ...args) {
+    return evaluate(user, ability, args);
+}
+/** Throw a 403 `ForbiddenException` unless the current user is allowed. */
+export async function authorize(ability, ...args) {
+    if (!(await can(ability, ...args))) {
+        throw new ForbiddenException(`Unauthorized: ${ability}`);
+    }
+}
+/** Like `authorize`, but for a specific user. */
+export async function authorizeFor(user, ability, ...args) {
+    if (!(await canFor(user, ability, ...args))) {
+        throw new ForbiddenException(`Unauthorized: ${ability}`);
+    }
+}

package/dist/core/broadcasting.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Broadcasting — push events to clients over named channels, in real time. Like
+ * the database and mail layers it's built on a pluggable `Broadcaster`, so the
+ * core owns no socket: point it at Pusher/Ably (`fetch`), a Cloudflare Durable
+ * Object, or the built-in `MemoryBroadcaster` (in-process fan-out, for tests and
+ * single-instance workers).
+ *
+ *   await broadcast("orders.42", "status", { state: "shipped" });
+ *
+ * Private and presence channels are gated by `channelAuth` — register who may
+ * subscribe, then have your socket endpoint call `authorizeChannel`. It composes
+ * with `auth()` and the authorization layer.
+ */
+/** The bridge to a real-time backend — implement `publish` for your provider. */
+export interface Broadcaster {
+    publish(channels: string[], event: string, payload: unknown): Promise<void>;
+}
+/** A same-process subscriber (e.g. a Durable Object or an SSE loop). */
+export type Subscriber = (event: string, payload: unknown, channel: string) => void;
+/** In-process pub/sub — the default; fans out to local subscribers. Ideal for tests. */
+export declare class MemoryBroadcaster implements Broadcaster {
+    private subs;
+    publish(channels: string[], event: string, payload: unknown): Promise<void>;
+    /** Listen on a channel; returns an unsubscribe function. */
+    subscribe(channel: string, subscriber: Subscriber): () => void;
+}
+/**
+ * Decides whether `user` may join a channel. Return `false` to deny, `true` to
+ * allow, or an object of member data to allow *and* join a presence channel.
+ */
+export type ChannelAuthorizer = (user: unknown, params: Record<string, string>) => boolean | Record<string, unknown> | Promise<boolean | Record<string, unknown>>;
+/**
+ * Register an authorizer for a channel name pattern. `{param}` segments are
+ * captured and handed to the authorizer, e.g. `channelAuth("orders.{id}", …)`.
+ */
+export declare function channelAuth(pattern: string, authorizer: ChannelAuthorizer): void;
+/**
+ * Authorize `user` for `channel`. Runs the first matching `channelAuth` rule and
+ * returns its result; a channel with no rule is public and returns `true`.
+ */
+export declare function authorizeChannel(channel: string, user: unknown): Promise<boolean | Record<string, unknown>>;
+/** Clear all channel rules (test helper). */
+export declare function clearChannels(): void;
+/** Register the default broadcaster used by `broadcast()`. */
+export declare function setBroadcaster(instance: Broadcaster): Broadcaster;
+/** The default broadcaster. */
+export declare function getBroadcaster(): Broadcaster;
+/** Publish an event with a payload to one or more channels. */
+export declare function broadcast(channels: string | string[], event: string, payload?: unknown): Promise<void>;

package/dist/core/broadcasting.js

@@ -0,0 +1,84 @@
+/**
+ * Broadcasting — push events to clients over named channels, in real time. Like
+ * the database and mail layers it's built on a pluggable `Broadcaster`, so the
+ * core owns no socket: point it at Pusher/Ably (`fetch`), a Cloudflare Durable
+ * Object, or the built-in `MemoryBroadcaster` (in-process fan-out, for tests and
+ * single-instance workers).
+ *
+ *   await broadcast("orders.42", "status", { state: "shipped" });
+ *
+ * Private and presence channels are gated by `channelAuth` — register who may
+ * subscribe, then have your socket endpoint call `authorizeChannel`. It composes
+ * with `auth()` and the authorization layer.
+ */
+/* ---------------------------- memory broadcaster -------------------------- */
+/** In-process pub/sub — the default; fans out to local subscribers. Ideal for tests. */
+export class MemoryBroadcaster {
+    subs = new Map();
+    async publish(channels, event, payload) {
+        for (const channel of channels) {
+            const set = this.subs.get(channel);
+            if (set)
+                for (const cb of set)
+                    cb(event, payload, channel);
+        }
+    }
+    /** Listen on a channel; returns an unsubscribe function. */
+    subscribe(channel, subscriber) {
+        const set = this.subs.get(channel) ?? new Set();
+        set.add(subscriber);
+        this.subs.set(channel, set);
+        return () => {
+            set.delete(subscriber);
+            if (set.size === 0)
+                this.subs.delete(channel);
+        };
+    }
+}
+const rules = [];
+/**
+ * Register an authorizer for a channel name pattern. `{param}` segments are
+ * captured and handed to the authorizer, e.g. `channelAuth("orders.{id}", …)`.
+ */
+export function channelAuth(pattern, authorizer) {
+    const keys = [];
+    const source = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\\\{(\w+)\\\}/g, (_, k) => {
+        keys.push(k);
+        return "([^.]+)";
+    });
+    rules.push({ regex: new RegExp(`^${source}$`), keys, authorizer });
+}
+/**
+ * Authorize `user` for `channel`. Runs the first matching `channelAuth` rule and
+ * returns its result; a channel with no rule is public and returns `true`.
+ */
+export async function authorizeChannel(channel, user) {
+    for (const rule of rules) {
+        const match = rule.regex.exec(channel);
+        if (!match)
+            continue;
+        const params = {};
+        rule.keys.forEach((key, i) => (params[key] = match[i + 1]));
+        return rule.authorizer(user, params);
+    }
+    return true; // public channel
+}
+/** Clear all channel rules (test helper). */
+export function clearChannels() {
+    rules.length = 0;
+}
+/* -------------------------------- global ---------------------------------- */
+let broadcaster = new MemoryBroadcaster();
+/** Register the default broadcaster used by `broadcast()`. */
+export function setBroadcaster(instance) {
+    broadcaster = instance;
+    return broadcaster;
+}
+/** The default broadcaster. */
+export function getBroadcaster() {
+    return broadcaster;
+}
+/** Publish an event with a payload to one or more channels. */
+export function broadcast(channels, event, payload) {
+    return broadcaster.publish(Array.isArray(channels) ? channels : [channels], event, payload);
+}