@shaferllc/keel 0.36.0 → 0.58.0

package/dist/core/http/router.js

@@ -70,6 +70,11 @@ export class Route {
         this.def.domain = pattern;
         return this;
     }
+    /** Attach arbitrary metadata to the route — read it via `request.route.config`. */
+    config(data) {
+        Object.assign(this.def.config, data);
+        return this;
+    }
 }
 /** A group of routes sharing a prefix, middleware, and/or name prefix. */
 export class RouteGroup {
@@ -93,6 +98,12 @@ export class RouteGroup {
     use(mw) {
         return this.middleware(mw);
     }
+    /** Attach metadata to every route in the group (a route's own config wins). */
+    config(data) {
+        for (const r of this.routes)
+            r.config = { ...data, ...r.config };
+        return this;
+    }
     /** Constrain a parameter across every route in the group. */
     where(param, matcher) {
         for (const r of this.routes) {
@@ -317,10 +328,26 @@ export class Router {
             handler,
             middleware: [...this.group_mw],
             wheres: {},
+            config: {},
         };
         this.routes.push(def);
+        for (const hook of this.routeHooks)
+            hook(def);
         return new Route(def);
     }
+    routeHooks = [];
+    /**
+     * Observe route registration — called with each route's definition as it's
+     * added (and replayed for routes already registered). Handy for logging or
+     * building an API map. The `def` is live, so reading it later reflects fluent
+     * config (`.name()`, `.middleware()`) applied after registration.
+     */
+    onRoute(hook) {
+        for (const def of this.routes)
+            hook(def);
+        this.routeHooks.push(hook);
+        return this;
+    }
     /** Register a global parameter constraint, applied to every matching route. */
     where(param, matcher) {
         this.globalWheres[param] = matcherSource(matcher);
@@ -344,7 +371,9 @@ export class Router {
             throw new Error(`No route named [${name}].`);
         let path = def.path;
         for (const [k, v] of Object.entries(params)) {
-            path = path.replace(new RegExp(`:${k}\\??`), encodeURIComponent(String(v)));
+            // Global + word-boundary: replace every `:k` occurrence, and don't let
+            // `:id` match inside `:idx`.
+            path = path.replace(new RegExp(`:${k}\\b\\??`, "g"), encodeURIComponent(String(v)));
         }
         path = path.replace(/\/:[^/]+\?/g, "").replace(/:[^/]+/g, "");
         if (options.qs && Object.keys(options.qs).length) {

package/dist/core/index.d.ts

@@ -2,23 +2,27 @@
 export { Container } from "./container.js";
 export type { Token, Constructor, Factory } from "./container.js";
 export { Application } from "./application.js";
-export type { BootOptions } from "./application.js";
+export type { BootOptions, LifecycleHook, Configurator } from "./application.js";
 export { Config, env } from "./config.js";
-export { app, config, view, bind, singleton, instance, make, bound, events, emit, listen, cache, logger, } from "./helpers.js";
+export { app, config, view, bind, singleton, instance, make, bound, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
 export { Logger } from "./logger.js";
 export type { LogLevel, LoggerOptions } from "./logger.js";
+export { requestLogger, requestLog } from "./request-logger.js";
+export type { RequestLoggerOptions } from "./request-logger.js";
 export { Events } from "./events.js";
 export type { Listener } from "./events.js";
 export { Cache, MemoryStore } from "./cache.js";
 export type { CacheStore } from "./cache.js";
 export { serveStatic } from "./static.js";
 export type { StaticOptions } from "./static.js";
+export { Storage, MemoryDisk, storage, setDisk } from "./storage.js";
+export type { Disk, Contents } from "./storage.js";
 export { dump, dd } from "./debug.js";
 export { hash, encryption } from "./crypto.js";
 export { rateLimiter } from "./rate-limit.js";
 export type { RateLimiterOptions } from "./rate-limit.js";
 export { db, setConnection, QueryBuilder } from "./database.js";
-export type { Connection, WriteResult, Row, Dialect, Operator } from "./database.js";
+export type { Connection, WriteResult, Row, Dialect, Operator, Paginated } from "./database.js";
 export { Model } from "./model.js";
 export type { CastType, Casts } from "./casts.js";
 export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations.js";
@@ -28,14 +32,23 @@ export { Mailer, PendingMail, ArrayTransport, LogTransport, fetchTransport, mail
 export type { Message, Transport, MailerOptions, FetchTransportOptions } from "./mail.js";
 export { Job, Queue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, } from "./queue.js";
 export type { Dispatchable, JobOptions, QueueDriver, Drainable, QueuedJob } from "./queue.js";
+export { Scheduler, ScheduledTask, scheduler, setScheduler, schedule, cronMatches } from "./scheduler.js";
+export { MemoryBroadcaster, broadcast, setBroadcaster, getBroadcaster, channelAuth, authorizeChannel, clearChannels, } from "./broadcasting.js";
+export type { Broadcaster, Subscriber, ChannelAuthorizer } from "./broadcasting.js";
+export { Redis, MemoryRedis, redis, setRedis, redisStore } from "./redis.js";
+export type { RedisConnection, SetOptions } from "./redis.js";
 export { Notification, Notifier, MailChannel, DatabaseChannel, ArrayChannel, routeFor, notify, setNotifier, getNotifier, } from "./notification.js";
 export type { Notifiable, MailContent, Channel } from "./notification.js";
 export { SchemaBuilder, Migrator, TableBuilder, Column } from "./migrations.js";
 export type { Migration } from "./migrations.js";
 export { ctx, json, text, html, redirect, param, query, header, body, request, response, } from "./request.js";
+export { decorateRequest, hasRequestDecorator, decorated, setRequestValue, clearRequestDecorators, } from "./decorators.js";
+export type { RequestResolver } from "./decorators.js";
 export type { ConfigData } from "./config.js";
 export { View } from "./view.js";
 export type { Renderable, ViewConfig } from "./view.js";
+export { TemplateEngine, escapeHtml, templates, setTemplateEngine, render, } from "./template.js";
+export type { Filter, RenderContext } from "./template.js";
 export { ServiceProvider } from "./provider.js";
 export type { ProviderClass } from "./provider.js";
 export { Router, Route, RouteGroup, RouteResource, matchers } from "./http/router.js";
@@ -43,10 +56,19 @@ export type { Ctx, RouteHandler, RouteDefinition, Method, Matcher, MiddlewareRef
 export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
 export type { InertiaPage, InertiaOptions } from "./inertia.js";
 export { HttpKernel } from "./http/kernel.js";
-export { HttpException, NotFoundException, UnauthorizedException, ForbiddenException, ValidationException, STATUS_TEXT, } from "./exceptions.js";
-export { validate } from "./validation.js";
-export type { Schema } from "./validation.js";
+export { TestClient, TestResponse, testClient } from "./testing.js";
+export { HttpException, BadRequestException, UnauthorizedException, PaymentRequiredException, ForbiddenException, NotFoundException, MethodNotAllowedException, NotAcceptableException, RequestTimeoutException, ConflictException, LengthRequiredException, ValidationException, TooManyRequestsException, ServerErrorException, NotImplementedException, BadGatewayException, ServiceUnavailableException, createError, STATUS_TEXT, } from "./exceptions.js";
+export { validate, validateRequest, validated } from "./validation.js";
+export type { Schema, RequestSchemas } from "./validation.js";
 export { Session, session, sessionMiddleware } from "./session.js";
 export type { SessionOptions } from "./session.js";
 export { Auth, auth, authGuard, setUserProvider } from "./auth.js";
 export type { UserProvider } from "./auth.js";
+export { define, policy, gateBefore, setUserResolver, clearAuthorization, can, cannot, canFor, authorize, authorizeFor, } from "./authorization.js";
+export type { GateCallback, BeforeCallback } from "./authorization.js";
+export { Transformer } from "./transformer.js";
+export type { Attributes, DocumentOptions } from "./transformer.js";
+export { Broker, Service, LocalTransporter, ServiceNotFoundError, RequestTimeoutError, broker, setBroker, } from "./broker.js";
+export type { ServiceSchema, Context, ActionHandler, EventHandler, ActionDef, ActionSchema, ActionHooks, EventSchema, ServiceHooks, Visibility, EventType, BeforeHook, AfterHook, ErrorHook, Transporter, BrokerOptions, BrokerMiddleware, CallOptions, EmitOptions, MCallDefs, MCallOptions, } from "./broker.js";
+export { Vite, viteTags, viteAsset, viteReactRefresh } from "./vite.js";
+export type { ViteOptions, Manifest, ManifestChunk, Attributes as ViteAttributes, AttrValue, } from "./vite.js";

package/dist/core/index.js

@@ -2,11 +2,13 @@
 export { Container } from "./container.js";
 export { Application } from "./application.js";
 export { Config, env } from "./config.js";
-export { app, config, view, bind, singleton, instance, make, bound, events, emit, listen, cache, logger, } from "./helpers.js";
+export { app, config, view, bind, singleton, instance, make, bound, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
 export { Logger } from "./logger.js";
+export { requestLogger, requestLog } from "./request-logger.js";
 export { Events } from "./events.js";
 export { Cache, MemoryStore } from "./cache.js";
 export { serveStatic } from "./static.js";
+export { Storage, MemoryDisk, storage, setDisk } from "./storage.js";
 export { dump, dd } from "./debug.js";
 export { hash, encryption } from "./crypto.js";
 export { rateLimiter } from "./rate-limit.js";
@@ -16,15 +18,25 @@ export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations
 export { Faker, Factory as ModelFactory, factory, Seeder, seed } from "./factory.js";
 export { Mailer, PendingMail, ArrayTransport, LogTransport, fetchTransport, mail, setMailer, getMailer, } from "./mail.js";
 export { Job, Queue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, } from "./queue.js";
+export { Scheduler, ScheduledTask, scheduler, setScheduler, schedule, cronMatches } from "./scheduler.js";
+export { MemoryBroadcaster, broadcast, setBroadcaster, getBroadcaster, channelAuth, authorizeChannel, clearChannels, } from "./broadcasting.js";
+export { Redis, MemoryRedis, redis, setRedis, redisStore } from "./redis.js";
 export { Notification, Notifier, MailChannel, DatabaseChannel, ArrayChannel, routeFor, notify, setNotifier, getNotifier, } from "./notification.js";
 export { SchemaBuilder, Migrator, TableBuilder, Column } from "./migrations.js";
 export { ctx, json, text, html, redirect, param, query, header, body, request, response, } from "./request.js";
+export { decorateRequest, hasRequestDecorator, decorated, setRequestValue, clearRequestDecorators, } from "./decorators.js";
 export { View } from "./view.js";
+export { TemplateEngine, escapeHtml, templates, setTemplateEngine, render, } from "./template.js";
 export { ServiceProvider } from "./provider.js";
 export { Router, Route, RouteGroup, RouteResource, matchers } from "./http/router.js";
 export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
 export { HttpKernel } from "./http/kernel.js";
-export { HttpException, NotFoundException, UnauthorizedException, ForbiddenException, ValidationException, STATUS_TEXT, } from "./exceptions.js";
-export { validate } from "./validation.js";
+export { TestClient, TestResponse, testClient } from "./testing.js";
+export { HttpException, BadRequestException, UnauthorizedException, PaymentRequiredException, ForbiddenException, NotFoundException, MethodNotAllowedException, NotAcceptableException, RequestTimeoutException, ConflictException, LengthRequiredException, ValidationException, TooManyRequestsException, ServerErrorException, NotImplementedException, BadGatewayException, ServiceUnavailableException, createError, STATUS_TEXT, } from "./exceptions.js";
+export { validate, validateRequest, validated } from "./validation.js";
 export { Session, session, sessionMiddleware } from "./session.js";
 export { Auth, auth, authGuard, setUserProvider } from "./auth.js";
+export { define, policy, gateBefore, setUserResolver, clearAuthorization, can, cannot, canFor, authorize, authorizeFor, } from "./authorization.js";
+export { Transformer } from "./transformer.js";
+export { Broker, Service, LocalTransporter, ServiceNotFoundError, RequestTimeoutError, broker, setBroker, } from "./broker.js";
+export { Vite, viteTags, viteAsset, viteReactRefresh } from "./vite.js";

package/dist/core/logger.d.ts

@@ -14,6 +14,11 @@ export interface LoggerOptions {
     pretty?: boolean;
     /** Fields merged into every log line. */
     bindings?: Record<string, unknown>;
+    /**
+     * Field paths to redact from log output — top-level keys (`"password"`) or dot
+     * paths (`"req.headers.authorization"`). Matched values become `"[redacted]"`.
+     */
+    redact?: string[];
 }
 export declare class Logger {
     private options;

package/dist/core/logger.js

@@ -7,6 +7,24 @@
  *   logger().error("payment failed", { orderId, error });
  */
 const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+const REDACTED = "[redacted]";
+/** Return a copy of `obj` with `path` (dot-separated) redacted — clones only along the path. */
+function redactPath(obj, keys) {
+    const [head, ...rest] = keys;
+    if (head === undefined || !(head in obj))
+        return obj;
+    const clone = { ...obj };
+    if (rest.length === 0) {
+        clone[head] = REDACTED;
+    }
+    else {
+        const child = clone[head];
+        if (child && typeof child === "object") {
+            clone[head] = redactPath(child, rest);
+        }
+    }
+    return clone;
+}
 export class Logger {
     options;
     threshold;
@@ -18,13 +36,17 @@ export class Logger {
         if (LEVELS[level] < this.threshold)
             return;
         const time = new Date().toISOString();
+        let fields = { ...this.options.bindings, ...context };
+        for (const path of this.options.redact ?? []) {
+            fields = redactPath(fields, path.split("."));
+        }
         if (this.options.pretty) {
-            const extra = context ? " " + JSON.stringify(context) : "";
+            const extra = Object.keys(fields).length ? " " + JSON.stringify(fields) : "";
             const fn = level === "warn" ? console.warn : level === "error" ? console.error : console.log;
             fn(`[${time}] ${level.toUpperCase().padEnd(5)} ${message}${extra}`);
         }
         else {
-            console.log(JSON.stringify({ level, time, msg: message, ...this.options.bindings, ...context }));
+            console.log(JSON.stringify({ level, time, msg: message, ...fields }));
         }
     }
     debug(message, context) {

package/dist/core/migrations.js

@@ -165,11 +165,11 @@ export class Migrator {
     /** Names of migrations already applied. */
     async ran() {
         await this.ensure();
-        const rows = await this.conn.select("SELECT name FROM migrations", []);
+        const rows = (await this.conn.select("SELECT name FROM migrations", []));
         return rows.map((r) => String(r.name));
     }
     async maxBatch() {
-        const rows = await this.conn.select("SELECT MAX(batch) AS b FROM migrations", []);
+        const rows = (await this.conn.select("SELECT MAX(batch) AS b FROM migrations", []));
         return Number(rows[0]?.b ?? 0);
     }
     /** Run all pending migrations. Returns the names applied. */
@@ -196,7 +196,7 @@ export class Migrator {
         const batch = await this.maxBatch();
         if (!batch)
             return [];
-        const rows = await this.conn.select(this.ph("SELECT name FROM migrations WHERE batch = ?"), [batch]);
+        const rows = (await this.conn.select(this.ph("SELECT name FROM migrations WHERE batch = ?"), [batch]));
         const schema = new SchemaBuilder(this.conn, this.dialect);
         const rolled = [];
         for (const name of rows.map((r) => String(r.name)).reverse()) {

package/dist/core/model.d.ts

@@ -15,7 +15,7 @@
  *   user.email = "new@x.com";
  *   await user.save();
  */
-import { type QueryBuilder, type Row } from "./database.js";
+import { type QueryBuilder, type Row, type Paginated } from "./database.js";
 import { BelongsTo, BelongsToMany, HasMany, HasOne } from "./relations.js";
 import { type Casts } from "./casts.js";
 type ModelClass<T extends Model> = (new (attributes?: Row) => T) & typeof Model;
@@ -28,6 +28,10 @@ export declare class Model {
     static guarded: string[];
     /** Column -> cast type; values round-trip as real JS types. */
     static casts: Casts;
+    /** Auto-manage `created_at` / `updated_at` on write. Off by default. */
+    static timestamps: boolean;
+    static createdAtColumn: string;
+    static updatedAtColumn: string;
     [key: string]: unknown;
     constructor(attributes?: Row);
     /** A raw query builder scoped to this model's table. */
@@ -36,6 +40,8 @@ export declare class Model {
     static filterFillable(attributes: Row): Row;
     /** Cast attributes to their storable primitives for a write. */
     static toDatabase(attributes: Row): Row;
+    /** Stamp created_at/updated_at onto a write payload when timestamps are on. */
+    static stampTimestamps(data: Row, forInsert: boolean): Row;
     static all<T extends Model>(this: ModelClass<T>): Promise<T[]>;
     static find<T extends Model>(this: ModelClass<T>, id: unknown): Promise<T | null>;
     static findOrFail<T extends Model>(this: ModelClass<T>, id: unknown): Promise<T>;
@@ -43,6 +49,14 @@ export declare class Model {
     /** Fetch models matching a simple equality condition. */
     static where<T extends Model>(this: ModelClass<T>, column: string, value: unknown): Promise<T[]>;
     static create<T extends Model>(this: ModelClass<T>, attributes: Row): Promise<T>;
+    /** A page of models plus pagination metadata. */
+    static paginate<T extends Model>(this: ModelClass<T>, page?: number, perPage?: number): Promise<Paginated<T>>;
+    /** Find the first row matching `match`, or create one from `{ ...match, ...values }`. */
+    static firstOrCreate<T extends Model>(this: ModelClass<T>, match: Row, values?: Row): Promise<T>;
+    /** Update the first row matching `match` with `values`, or create it. */
+    static updateOrCreate<T extends Model>(this: ModelClass<T>, match: Row, values?: Row): Promise<T>;
+    /** A query scoped to every column/value in `match`. */
+    private static matching;
     /**
      * Eager-load relations onto an array of models with one extra query each —
      * the fix for N+1. Each name must be a relationship method on the model.
@@ -65,6 +79,10 @@ export declare class Model {
     getRelation<T = unknown>(name: string): T | undefined;
     /** Insert (no primary key) or update (has one). */
     save(): Promise<this>;
+    /** Mass-assign then save — `fill` + `save` in one call. */
+    update(attributes: Row): Promise<this>;
+    /** Reload this model's columns from the database. */
+    refresh(): Promise<this>;
     delete(): Promise<void>;
     /** Merge mass-assignable attributes into the model (cast, not saved). */
     fill(attributes: Row): this;

package/dist/core/model.js

@@ -40,6 +40,10 @@ export class Model {
     static guarded = [];
     /** Column -> cast type; values round-trip as real JS types. */
     static casts = {};
+    /** Auto-manage `created_at` / `updated_at` on write. Off by default. */
+    static timestamps = false;
+    static createdAtColumn = "created_at";
+    static updatedAtColumn = "updated_at";
     constructor(attributes = {}) {
         // Hydration is unguarded (rows come from the database) but always cast.
         Object.assign(this, applyCasts(attributes, this.constructor.casts, castGet));
@@ -70,6 +74,17 @@ export class Model {
     static toDatabase(attributes) {
         return applyCasts(attributes, this.casts, castSet);
     }
+    /** Stamp created_at/updated_at onto a write payload when timestamps are on. */
+    static stampTimestamps(data, forInsert) {
+        if (!this.timestamps)
+            return data;
+        const now = new Date().toISOString();
+        const out = { ...data };
+        if (forInsert)
+            out[this.createdAtColumn] = now;
+        out[this.updatedAtColumn] = now;
+        return out;
+    }
     static async all() {
         const rows = await db(this.table).get();
         return rows.map((row) => new this(row));
@@ -95,12 +110,46 @@ export class Model {
     }
     static async create(attributes) {
         const filtered = this.filterFillable(attributes);
-        const id = await db(this.table).insertGetId(this.toDatabase(filtered));
+        const write = this.stampTimestamps(this.toDatabase(filtered), true);
+        const id = await db(this.table).insertGetId(write);
         const model = new this(filtered);
+        if (this.timestamps) {
+            model[this.createdAtColumn] = write[this.createdAtColumn];
+            model[this.updatedAtColumn] = write[this.updatedAtColumn];
+        }
         if (id != null)
             model[this.primaryKey] = id;
         return model;
     }
+    /** A page of models plus pagination metadata. */
+    static async paginate(page = 1, perPage = 15) {
+        const result = await db(this.table).paginate(page, perPage);
+        return { ...result, data: result.data.map((row) => new this(row)) };
+    }
+    /** Find the first row matching `match`, or create one from `{ ...match, ...values }`. */
+    static async firstOrCreate(match, values = {}) {
+        const row = await this.matching(match).first();
+        if (row)
+            return new this(row);
+        return this.create({ ...match, ...values });
+    }
+    /** Update the first row matching `match` with `values`, or create it. */
+    static async updateOrCreate(match, values = {}) {
+        const row = await this.matching(match).first();
+        if (row) {
+            const model = new this(row);
+            await model.forceFill(values).save();
+            return model;
+        }
+        return this.create({ ...match, ...values });
+    }
+    /** A query scoped to every column/value in `match`. */
+    static matching(match) {
+        let q = db(this.table);
+        for (const [column, value] of Object.entries(match))
+            q = q.where(column, value);
+        return q;
+    }
     /**
      * Eager-load relations onto an array of models with one extra query each —
      * the fix for N+1. Each name must be a relationship method on the model.
@@ -161,10 +210,17 @@ export class Model {
     async save() {
         const ctor = this.ctor();
         const { table, primaryKey } = ctor;
-        const data = ctor.toDatabase({ ...this });
-        const idValue = data[primaryKey];
+        const idValue = this[primaryKey];
+        const forInsert = idValue == null;
+        const data = ctor.stampTimestamps(ctor.toDatabase({ ...this }), forInsert);
+        // Reflect the stamps back onto the instance.
+        if (ctor.timestamps) {
+            if (forInsert)
+                this[ctor.createdAtColumn] = data[ctor.createdAtColumn];
+            this[ctor.updatedAtColumn] = data[ctor.updatedAtColumn];
+        }
         delete data[primaryKey];
-        if (idValue != null) {
+        if (!forInsert) {
             await db(table).where(primaryKey, idValue).update(data);
         }
         else {
@@ -174,6 +230,18 @@ export class Model {
         }
         return this;
     }
+    /** Mass-assign then save — `fill` + `save` in one call. */
+    async update(attributes) {
+        return this.fill(attributes).save();
+    }
+    /** Reload this model's columns from the database. */
+    async refresh() {
+        const ctor = this.ctor();
+        const row = await db(ctor.table).where(ctor.primaryKey, this[ctor.primaryKey]).first();
+        if (row)
+            Object.assign(this, applyCasts(row, ctor.casts, castGet));
+        return this;
+    }
     async delete() {
         const { table, primaryKey } = this.ctor();
         await db(table).where(primaryKey, this[primaryKey]).delete();

package/dist/core/provider.d.ts

@@ -1,16 +1,25 @@
 /**
- * Service providers are the central place to configure the application.
+ * Service providers are the central place to configure the application — Keel's
+ * plugin system. A provider packages a slice of functionality and wires it in.
  *
  * register(): bind things into the container. Do NOT resolve other services
  *             here — nothing is guaranteed to be registered yet.
  * boot():     called after every provider has registered. Safe to resolve
  *             and wire things together here.
+ *
+ * Register with options to make a provider reusable:
+ *
+ *   class RateLimitProvider extends ServiceProvider<{ max: number }> {
+ *     boot() { this.app.make(HttpKernel).use(rateLimiter({ max: this.options.max })); }
+ *   }
+ *   app.register(RateLimitProvider, { max: 100 });
  */
 import type { Application } from "./application.js";
-export declare abstract class ServiceProvider {
+export declare abstract class ServiceProvider<O = Record<string, unknown>> {
     protected app: Application;
-    constructor(app: Application);
+    protected options: O;
+    constructor(app: Application, options?: O);
     register(): void | Promise<void>;
     boot(): void | Promise<void>;
 }
-export type ProviderClass = new (app: Application) => ServiceProvider;
+export type ProviderClass = new (app: Application, options?: any) => ServiceProvider;

package/dist/core/provider.js

@@ -1,15 +1,25 @@
 /**
- * Service providers are the central place to configure the application.
+ * Service providers are the central place to configure the application — Keel's
+ * plugin system. A provider packages a slice of functionality and wires it in.
  *
  * register(): bind things into the container. Do NOT resolve other services
  *             here — nothing is guaranteed to be registered yet.
  * boot():     called after every provider has registered. Safe to resolve
  *             and wire things together here.
+ *
+ * Register with options to make a provider reusable:
+ *
+ *   class RateLimitProvider extends ServiceProvider<{ max: number }> {
+ *     boot() { this.app.make(HttpKernel).use(rateLimiter({ max: this.options.max })); }
+ *   }
+ *   app.register(RateLimitProvider, { max: 100 });
  */
 export class ServiceProvider {
     app;
-    constructor(app) {
+    options;
+    constructor(app, options = {}) {
         this.app = app;
+        this.options = options;
     }
     register() { }
     boot() { }

package/dist/core/redis.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Redis integration. Like the database and mail layers, it's built on a small
+ * pluggable driver (`RedisConnection`) rather than a hard dependency — so the
+ * core imports no client and runs on Node and the edge. Point it at Upstash
+ * (HTTP/`fetch`), ioredis, node-redis, or the built-in `MemoryRedis` for tests.
+ *
+ *   setRedis(new MemoryRedis());          // or an Upstash/ioredis adapter
+ *   await redis().set("views", "1");
+ *   await redis().incr("views");          // 2
+ *   await redis().remember("user:1", 60, () => fetchUser(1));
+ *
+ * `Redis` adds JSON helpers and a `remember` cache pattern over the raw command
+ * seam; `redisStore()` exposes it as a `CacheStore` so the cache can be
+ * Redis-backed.
+ */
+import type { CacheStore } from "./cache.js";
+export interface SetOptions {
+    /** Expire after N seconds. */
+    ex?: number;
+    /** Expire after N milliseconds. */
+    px?: number;
+}
+/** The bridge to your Redis client — implement it once per driver. */
+export interface RedisConnection {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: SetOptions): Promise<void>;
+    del(...keys: string[]): Promise<number>;
+    exists(...keys: string[]): Promise<number>;
+    incrBy(key: string, amount: number): Promise<number>;
+    expire(key: string, seconds: number): Promise<boolean>;
+    ttl(key: string): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    flushAll(): Promise<void>;
+}
+/** An in-memory `RedisConnection` with TTL support — the default; ideal for tests. */
+export declare class MemoryRedis implements RedisConnection {
+    private store;
+    private live;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: SetOptions): Promise<void>;
+    del(...keys: string[]): Promise<number>;
+    exists(...keys: string[]): Promise<number>;
+    incrBy(key: string, amount: number): Promise<number>;
+    expire(key: string, seconds: number): Promise<boolean>;
+    ttl(key: string): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    flushAll(): Promise<void>;
+}
+export declare class Redis {
+    private conn;
+    constructor(conn: RedisConnection);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: SetOptions): Promise<void>;
+    del(...keys: string[]): Promise<number>;
+    exists(...keys: string[]): Promise<number>;
+    has(key: string): Promise<boolean>;
+    incr(key: string): Promise<number>;
+    decr(key: string): Promise<number>;
+    incrBy(key: string, amount: number): Promise<number>;
+    expire(key: string, seconds: number): Promise<boolean>;
+    ttl(key: string): Promise<number>;
+    keys(pattern?: string): Promise<string[]>;
+    flushAll(): Promise<void>;
+    /** Get a JSON value (parsed), or null if the key is unset. */
+    getJson<T>(key: string): Promise<T | null>;
+    /** Set a value as JSON. */
+    setJson(key: string, value: unknown, options?: SetOptions): Promise<void>;
+    /** Return the cached JSON value, or compute it, store it for `seconds`, and return it. */
+    remember<T>(key: string, seconds: number, factory: () => T | Promise<T>): Promise<T>;
+    /** The underlying driver, for raw access. */
+    get connection(): RedisConnection;
+}
+/** Expose a `Redis` client as a `CacheStore`, so the cache can be Redis-backed. */
+export declare function redisStore(client?: Redis): CacheStore;
+/** Register the default Redis driver used by `redis()`. */
+export declare function setRedis(conn: RedisConnection): Redis;
+/** The default Redis client. */
+export declare function redis(): Redis;