@shaferllc/keel 0.12.0 → 0.35.0

package/dist/core/queue.js

@@ -0,0 +1,88 @@
+/**
+ * A small queue for background work. Dispatch a `Job` (or a plain function) and
+ * a pluggable `QueueDriver` decides when it runs — immediately (the default),
+ * held in memory for a worker to drain, or handed to a real broker. The API
+ * mirrors the database and mail layers (`setQueue` / `dispatch` are to queues
+ * what `setConnection` / `db()` are to the database). The core imports no broker,
+ * so it stays edge-safe.
+ *
+ *   class SendWelcome extends Job {
+ *     constructor(private userId: number) { super(); }
+ *     async handle() { await mail().to(...).send(); }
+ *   }
+ *
+ *   await dispatch(new SendWelcome(user.id));   // runs now with the sync driver
+ *
+ *   // Defer instead, and drain with a worker:
+ *   setQueue(new MemoryDriver());
+ *   await dispatch(new SendWelcome(user.id));   // queued
+ *   await work();                               // runs everything pending
+ */
+/** A unit of background work. Subclass and implement `handle`. */
+export class Job {
+}
+function run(job) {
+    return Promise.resolve(job instanceof Job ? job.handle() : job());
+}
+/* -------------------------------- drivers --------------------------------- */
+/** Runs jobs the moment they're dispatched — the default; ideal for dev/tests. */
+export class SyncDriver {
+    async push(job, _options) {
+        await run(job);
+    }
+}
+/** Holds jobs in memory; `work()` drains them. Assert on `.jobs` in tests. */
+export class MemoryDriver {
+    jobs = [];
+    async push(job, options) {
+        this.jobs.push({ job, options });
+    }
+    get size() {
+        return this.jobs.length;
+    }
+    /** Run every pending job in FIFO order; returns how many ran. */
+    async work() {
+        let count = 0;
+        while (this.jobs.length) {
+            const next = this.jobs.shift();
+            await run(next.job);
+            count++;
+        }
+        return count;
+    }
+}
+/* --------------------------------- queue ---------------------------------- */
+export class Queue {
+    driver;
+    constructor(driver) {
+        this.driver = driver;
+    }
+    /** Place a job on the queue (the driver decides when it runs). */
+    async dispatch(job, options = {}) {
+        await this.driver.push(job, options);
+    }
+    /** Drain the driver if it holds jobs locally; returns how many ran. */
+    async work() {
+        const drainable = this.driver;
+        return typeof drainable.work === "function" ? drainable.work() : 0;
+    }
+}
+/* --------------------------------- global --------------------------------- */
+let queue = new Queue(new SyncDriver());
+/** Register the default queue driver used by `dispatch()`. */
+export function setQueue(driver) {
+    queue = new Queue(driver);
+    return queue;
+}
+/** The default queue instance. */
+export function getQueue() {
+    return queue;
+}
+/** Dispatch a job (or function) onto the default queue. */
+export function dispatch(job, options) {
+    return queue.dispatch(job, options);
+}
+/** Drain the default queue's pending jobs (no-op for immediate drivers). */
+export function work() {
+    return queue.work();
+}

package/dist/core/rate-limit.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A fixed-window rate-limiting middleware. Limits requests per key (the client
+ * IP by default) within a time window, and sets the standard `X-RateLimit-*`
+ * and `Retry-After` headers.
+ *
+ *   this.use(rateLimiter({ max: 60, window: 60 }));        // 60 req / minute
+ *   router.post("/login", handler).use(rateLimiter({ max: 5, window: 60 }));
+ *
+ * The default store is in-memory (per process / per isolate). For distributed
+ * limiting, pass a store backed by Redis/KV.
+ */
+import type { Context, MiddlewareHandler } from "hono";
+export interface RateLimiterOptions {
+    /** Max requests allowed per window. Default: 60. */
+    max?: number;
+    /** Window length in seconds. Default: 60. */
+    window?: number;
+    /** Derive the bucket key from the request. Default: client IP. */
+    key?: (c: Context) => string;
+    /** Response message on 429. */
+    message?: string;
+}
+export declare function rateLimiter(options?: RateLimiterOptions): MiddlewareHandler;

package/dist/core/rate-limit.js

@@ -0,0 +1,50 @@
+/**
+ * A fixed-window rate-limiting middleware. Limits requests per key (the client
+ * IP by default) within a time window, and sets the standard `X-RateLimit-*`
+ * and `Retry-After` headers.
+ *
+ *   this.use(rateLimiter({ max: 60, window: 60 }));        // 60 req / minute
+ *   router.post("/login", handler).use(rateLimiter({ max: 5, window: 60 }));
+ *
+ * The default store is in-memory (per process / per isolate). For distributed
+ * limiting, pass a store backed by Redis/KV.
+ */
+function defaultKey(c) {
+    return (c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
+        c.req.header("x-real-ip") ??
+        "global");
+}
+export function rateLimiter(options = {}) {
+    const max = options.max ?? 60;
+    const windowMs = (options.window ?? 60) * 1000;
+    const keyFor = options.key ?? defaultKey;
+    const buckets = new Map();
+    return async (c, next) => {
+        const now = Date.now();
+        const key = keyFor(c);
+        // Occasionally prune expired buckets to bound memory.
+        if (buckets.size > 10_000) {
+            for (const [k, b] of buckets)
+                if (b.reset <= now)
+                    buckets.delete(k);
+        }
+        let bucket = buckets.get(key);
+        if (!bucket || bucket.reset <= now) {
+            bucket = { count: 0, reset: now + windowMs };
+            buckets.set(key, bucket);
+        }
+        bucket.count++;
+        const remaining = Math.max(0, max - bucket.count);
+        if (bucket.count > max) {
+            return c.json({ error: options.message ?? "Too Many Requests", status: 429 }, 429, {
+                "X-RateLimit-Limit": String(max),
+                "X-RateLimit-Remaining": "0",
+                "Retry-After": String(Math.ceil((bucket.reset - now) / 1000)),
+            });
+        }
+        await next();
+        // Set headers on the final response (survives any handler type).
+        c.header("X-RateLimit-Limit", String(max));
+        c.header("X-RateLimit-Remaining", String(remaining));
+    };
+}

package/dist/core/relations.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Model relationships over the query builder. Define a relationship as a method
+ * on your model that returns one of these, then read it lazily (`await`) or
+ * eager-load many at once with `Model.load()` to avoid N+1 queries.
+ *
+ *   class User extends Model {
+ *     static table = "users";
+ *     posts() { return this.hasMany(Post); }        // user_id on posts
+ *     profile() { return this.hasOne(Profile); }
+ *     roles() { return this.belongsToMany(Role); }  // role_user pivot
+ *   }
+ *   class Post extends Model {
+ *     static table = "posts";
+ *     author() { return this.belongsTo(User); }     // user_id on posts
+ *   }
+ *
+ *   const posts = await user.posts();               // relations are awaitable
+ *   const author = await post.author();
+ *
+ *   const users = await User.all();
+ *   await User.load(users, "posts");                // one extra query, not N
+ *   users[0].getRelation("posts");
+ *
+ * Every relation is edge-safe: it only uses the driver-agnostic query builder
+ * (belongsToMany runs two `whereIn` reads instead of a JOIN).
+ */
+import { type QueryBuilder, type Row } from "./database.js";
+import type { Model } from "./model.js";
+type ModelClass<T extends Model> = (new (attributes?: Row) => T) & typeof Model;
+/** Base class: a relationship is awaitable (resolves to its loaded result). */
+export declare abstract class Relation<TRelated extends Model, TResult> implements PromiseLike<TResult> {
+    protected parent: Model;
+    protected related: ModelClass<TRelated>;
+    constructor(parent: Model, related: ModelClass<TRelated>);
+    /** The query builder with the relationship constraint applied. */
+    abstract query(): QueryBuilder;
+    /** Load the relationship for this single parent. */
+    abstract get(): Promise<TResult>;
+    /** Batch-load this relationship onto many parents, then assign each result. */
+    abstract eager(models: Model[], name: string): Promise<void>;
+    then<R1 = TResult, R2 = never>(onFulfilled?: ((value: TResult) => R1 | PromiseLike<R1>) | null, onRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
+    protected hydrate(rows: Row[]): TRelated[];
+}
+export declare class HasMany<T extends Model> extends Relation<T, T[]> {
+    private foreignKey;
+    private localKey;
+    constructor(parent: Model, related: ModelClass<T>, foreignKey: string, localKey: string);
+    private localValue;
+    query(): QueryBuilder;
+    get(): Promise<T[]>;
+    eager(models: Model[], name: string): Promise<void>;
+}
+export declare class HasOne<T extends Model> extends Relation<T, T | null> {
+    private foreignKey;
+    private localKey;
+    constructor(parent: Model, related: ModelClass<T>, foreignKey: string, localKey: string);
+    private localValue;
+    query(): QueryBuilder;
+    get(): Promise<T | null>;
+    eager(models: Model[], name: string): Promise<void>;
+}
+export declare class BelongsTo<T extends Model> extends Relation<T, T | null> {
+    private foreignKey;
+    private ownerKey;
+    constructor(parent: Model, related: ModelClass<T>, foreignKey: string, ownerKey: string);
+    private foreignValue;
+    query(): QueryBuilder;
+    get(): Promise<T | null>;
+    eager(models: Model[], name: string): Promise<void>;
+}
+export declare class BelongsToMany<T extends Model> extends Relation<T, T[]> {
+    private pivotTable;
+    private foreignPivotKey;
+    private relatedPivotKey;
+    private parentKey;
+    private relatedKey;
+    constructor(parent: Model, related: ModelClass<T>, pivotTable: string, foreignPivotKey: string, relatedPivotKey: string, parentKey: string, relatedKey: string);
+    private parentValue;
+    /** The query against the related table, once pivot rows are known. */
+    query(): QueryBuilder;
+    get(): Promise<T[]>;
+    eager(models: Model[], name: string): Promise<void>;
+    /** Attach a related row by linking it through the pivot table. */
+    attach(id: unknown, extra?: Row): Promise<void>;
+    /** Detach one related row (or all, when no id is given). */
+    detach(id?: unknown): Promise<void>;
+    /** Make the pivot contain exactly `ids` (detach the rest, attach the new). */
+    sync(ids: unknown[]): Promise<void>;
+}
+export {};

package/dist/core/relations.js

@@ -0,0 +1,229 @@
+/**
+ * Model relationships over the query builder. Define a relationship as a method
+ * on your model that returns one of these, then read it lazily (`await`) or
+ * eager-load many at once with `Model.load()` to avoid N+1 queries.
+ *
+ *   class User extends Model {
+ *     static table = "users";
+ *     posts() { return this.hasMany(Post); }        // user_id on posts
+ *     profile() { return this.hasOne(Profile); }
+ *     roles() { return this.belongsToMany(Role); }  // role_user pivot
+ *   }
+ *   class Post extends Model {
+ *     static table = "posts";
+ *     author() { return this.belongsTo(User); }     // user_id on posts
+ *   }
+ *
+ *   const posts = await user.posts();               // relations are awaitable
+ *   const author = await post.author();
+ *
+ *   const users = await User.all();
+ *   await User.load(users, "posts");                // one extra query, not N
+ *   users[0].getRelation("posts");
+ *
+ * Every relation is edge-safe: it only uses the driver-agnostic query builder
+ * (belongsToMany runs two `whereIn` reads instead of a JOIN).
+ */
+import { db } from "./database.js";
+function unique(values) {
+    return [...new Set(values)];
+}
+/** Base class: a relationship is awaitable (resolves to its loaded result). */
+export class Relation {
+    parent;
+    related;
+    constructor(parent, related) {
+        this.parent = parent;
+        this.related = related;
+    }
+    then(onFulfilled, onRejected) {
+        return this.get().then(onFulfilled, onRejected);
+    }
+    hydrate(rows) {
+        return rows.map((row) => new this.related(row));
+    }
+}
+/* --------------------------------- has-many -------------------------------- */
+export class HasMany extends Relation {
+    foreignKey;
+    localKey;
+    constructor(parent, related, foreignKey, localKey) {
+        super(parent, related);
+        this.foreignKey = foreignKey;
+        this.localKey = localKey;
+    }
+    localValue() {
+        return this.parent[this.localKey];
+    }
+    query() {
+        return db(this.related.table).where(this.foreignKey, this.localValue());
+    }
+    async get() {
+        return this.hydrate(await this.query().get());
+    }
+    async eager(models, name) {
+        const keys = unique(models.map((m) => m[this.localKey]).filter((v) => v != null));
+        const rows = keys.length
+            ? await db(this.related.table).whereIn(this.foreignKey, keys).get()
+            : [];
+        const grouped = new Map();
+        for (const row of rows) {
+            const bucket = grouped.get(row[this.foreignKey]) ?? [];
+            bucket.push(new this.related(row));
+            grouped.set(row[this.foreignKey], bucket);
+        }
+        for (const m of models) {
+            m.setRelation(name, grouped.get(m[this.localKey]) ?? []);
+        }
+    }
+}
+/* --------------------------------- has-one --------------------------------- */
+export class HasOne extends Relation {
+    foreignKey;
+    localKey;
+    constructor(parent, related, foreignKey, localKey) {
+        super(parent, related);
+        this.foreignKey = foreignKey;
+        this.localKey = localKey;
+    }
+    localValue() {
+        return this.parent[this.localKey];
+    }
+    query() {
+        return db(this.related.table).where(this.foreignKey, this.localValue());
+    }
+    async get() {
+        const row = await this.query().first();
+        return row ? new this.related(row) : null;
+    }
+    async eager(models, name) {
+        const keys = unique(models.map((m) => m[this.localKey]).filter((v) => v != null));
+        const rows = keys.length
+            ? await db(this.related.table).whereIn(this.foreignKey, keys).get()
+            : [];
+        const byKey = new Map();
+        for (const row of rows) {
+            if (!byKey.has(row[this.foreignKey]))
+                byKey.set(row[this.foreignKey], new this.related(row));
+        }
+        for (const m of models) {
+            m.setRelation(name, byKey.get(m[this.localKey]) ?? null);
+        }
+    }
+}
+/* -------------------------------- belongs-to ------------------------------- */
+export class BelongsTo extends Relation {
+    foreignKey;
+    ownerKey;
+    constructor(parent, related, foreignKey, ownerKey) {
+        super(parent, related);
+        this.foreignKey = foreignKey;
+        this.ownerKey = ownerKey;
+    }
+    foreignValue() {
+        return this.parent[this.foreignKey];
+    }
+    query() {
+        return db(this.related.table).where(this.ownerKey, this.foreignValue());
+    }
+    async get() {
+        if (this.foreignValue() == null)
+            return null;
+        const row = await this.query().first();
+        return row ? new this.related(row) : null;
+    }
+    async eager(models, name) {
+        const keys = unique(models.map((m) => m[this.foreignKey]).filter((v) => v != null));
+        const rows = keys.length
+            ? await db(this.related.table).whereIn(this.ownerKey, keys).get()
+            : [];
+        const byKey = new Map();
+        for (const row of rows)
+            byKey.set(row[this.ownerKey], new this.related(row));
+        for (const m of models) {
+            m.setRelation(name, byKey.get(m[this.foreignKey]) ?? null);
+        }
+    }
+}
+/* ----------------------------- belongs-to-many ----------------------------- */
+export class BelongsToMany extends Relation {
+    pivotTable;
+    foreignPivotKey;
+    relatedPivotKey;
+    parentKey;
+    relatedKey;
+    constructor(parent, related, pivotTable, foreignPivotKey, relatedPivotKey, parentKey, relatedKey) {
+        super(parent, related);
+        this.pivotTable = pivotTable;
+        this.foreignPivotKey = foreignPivotKey;
+        this.relatedPivotKey = relatedPivotKey;
+        this.parentKey = parentKey;
+        this.relatedKey = relatedKey;
+    }
+    parentValue() {
+        return this.parent[this.parentKey];
+    }
+    /** The query against the related table, once pivot rows are known. */
+    query() {
+        return db(this.related.table);
+    }
+    async get() {
+        if (this.parentValue() == null)
+            return [];
+        const pivots = await db(this.pivotTable)
+            .where(this.foreignPivotKey, this.parentValue())
+            .get();
+        const relatedIds = unique(pivots.map((p) => p[this.relatedPivotKey]));
+        if (!relatedIds.length)
+            return [];
+        const rows = await db(this.related.table).whereIn(this.relatedKey, relatedIds).get();
+        return this.hydrate(rows);
+    }
+    async eager(models, name) {
+        const parentIds = unique(models.map((m) => m[this.parentKey]).filter((v) => v != null));
+        if (!parentIds.length) {
+            for (const m of models)
+                m.setRelation(name, []);
+            return;
+        }
+        const pivots = await db(this.pivotTable).whereIn(this.foreignPivotKey, parentIds).get();
+        const relatedIds = unique(pivots.map((p) => p[this.relatedPivotKey]));
+        const rows = relatedIds.length
+            ? await db(this.related.table).whereIn(this.relatedKey, relatedIds).get()
+            : [];
+        const relatedById = new Map(rows.map((row) => [row[this.relatedKey], row]));
+        const grouped = new Map();
+        for (const pivot of pivots) {
+            const row = relatedById.get(pivot[this.relatedPivotKey]);
+            if (!row)
+                continue;
+            const bucket = grouped.get(pivot[this.foreignPivotKey]) ?? [];
+            bucket.push(new this.related(row));
+            grouped.set(pivot[this.foreignPivotKey], bucket);
+        }
+        for (const m of models) {
+            m.setRelation(name, grouped.get(m[this.parentKey]) ?? []);
+        }
+    }
+    /** Attach a related row by linking it through the pivot table. */
+    async attach(id, extra = {}) {
+        await db(this.pivotTable).insert({
+            [this.foreignPivotKey]: this.parentValue(),
+            [this.relatedPivotKey]: id,
+            ...extra,
+        });
+    }
+    /** Detach one related row (or all, when no id is given). */
+    async detach(id) {
+        let q = db(this.pivotTable).where(this.foreignPivotKey, this.parentValue());
+        if (id !== undefined)
+            q = q.where(this.relatedPivotKey, id);
+        await q.delete();
+    }
+    /** Make the pivot contain exactly `ids` (detach the rest, attach the new). */
+    async sync(ids) {
+        await this.detach();
+        for (const id of ids)
+            await this.attach(id);
+    }
+}

package/dist/core/request.d.ts

@@ -11,7 +11,9 @@
  * These resolve the active context from async-context storage, which the HTTP
  * kernel enables for every request. They only work inside a request.
  */
+import { setCookie } from "hono/cookie";
 import type { Context } from "hono";
+type CookieOptions = Parameters<typeof setCookie>[3];
 /** The current request context. Throws if called outside a request. */
 export declare function ctx(): Context;
 export declare function json(data: unknown, status?: number): Response;
@@ -31,10 +33,28 @@ interface ResponseHelper {
     text(body: string, status?: number): Response;
     html(body: string, status?: number): Response;
     redirect(location: string, status?: number): Response;
+    /** Send a value — objects become JSON, everything else becomes text. */
+    send(data: unknown, status?: number): Response;
     /** Set the response status (chainable). */
     status(code: number): ResponseHelper;
     /** Set a response header (chainable). */
     header(name: string, value: string): ResponseHelper;
+    /** Set the Content-Type (chainable). */
+    type(mime: string): ResponseHelper;
+    /** Append a value to a (possibly multi-value) header (chainable). */
+    append(name: string, value: string): ResponseHelper;
+    /** Remove a response header (chainable). */
+    removeHeader(name: string): ResponseHelper;
+    /** Queue a Set-Cookie on the response (chainable). */
+    cookie(name: string, value: string, options?: CookieOptions): ResponseHelper;
+    /** Clear a cookie (chainable). */
+    clearCookie(name: string, options?: CookieOptions): ResponseHelper;
+    /** Abort the request with an HTTP exception. */
+    abort(message: string, status?: number): never;
+    /** Abort only if the condition is truthy. */
+    abortIf(condition: unknown, message: string, status?: number): void;
+    /** Abort unless the condition is truthy. */
+    abortUnless(condition: unknown, message: string, status?: number): void;
 }
 export declare const response: ResponseHelper;
 /**
@@ -60,12 +80,44 @@ export declare const request: {
     readonly route: {
         name?: string;
         pattern: string;
-        methods: import(".").Method[];
+        methods: import("./index.js").Method[];
     } | undefined;
     /** Whether the matched route has the given name. */
     routeIs(name: string): boolean;
     /** A subdomain parameter captured from a domain-bound route. */
     subdomain(name: string): string | undefined;
+    /** A request cookie by name, or all cookies when called with no argument. */
+    cookie(name?: string): string | undefined | Record<string, string>;
+    /** The client IP, from X-Forwarded-For / X-Real-IP. */
+    ip(): string | undefined;
+    /** All inputs — query string merged with the parsed body (async). */
+    all(): Promise<Record<string, unknown>>;
+    /** An uploaded file by field name (a web `File`), or undefined. */
+    file(name: string): Promise<File | undefined>;
+    /** All uploaded files for a field name. */
+    files(name: string): Promise<File[]>;
+    /** Every uploaded file, grouped by field name. */
+    allFiles(): Promise<Record<string, File | File[]>>;
+    /** True if the request declares a body. */
+    hasBody(): boolean;
+    /** All request headers as an object. */
+    headers(): Record<string, string>;
+    /** The full X-Forwarded-For chain (client first). */
+    ips(): string[];
+    /** The best of the offered content types per the Accept header, or null. */
+    accepts(types: string[]): string | null;
+    /** Accepted content types, ordered by preference. */
+    types(): string[];
+    /** The best of the offered languages per Accept-Language, or null. */
+    language(languages: string[]): string | null;
+    /** Accepted languages, ordered by preference. */
+    languages(): string[];
+    /** A single input (from query or body), with an optional fallback (async). */
+    input<T = unknown>(key: string, fallback?: T): Promise<T>;
+    /** Only the named inputs (async). */
+    only(keys: string[]): Promise<Record<string, unknown>>;
+    /** Every input except the named ones (async). */
+    except(keys: string[]): Promise<Record<string, unknown>>;
 };
 export declare function param(): Record<string, string>;
 export declare function param(name: string): string;