@shaferllc/keel 0.12.0 → 0.36.0

package/dist/core/notification.js

@@ -0,0 +1,129 @@
+/**
+ * Notifications — send a message to a recipient over one or more channels
+ * (mail, database, or your own), inline or through the queue. This is where the
+ * mail and queue layers compose: a notification declares *what* to say and
+ * *which channels* carry it, and each channel decides *how*.
+ *
+ *   class InvoicePaid extends Notification {
+ *     constructor(private amount: number) { super(); }
+ *     via() { return ["mail", "database"]; }
+ *     toMail() { return { subject: "Payment received", text: `Thanks for $${this.amount}.` }; }
+ *     toArray() { return { amount: this.amount }; }
+ *   }
+ *
+ *   await notify(user, new InvoicePaid(4200));   // user.email routes the mail
+ *
+ * Set `shouldQueue = true` on a notification to deliver it from a queued job
+ * instead of inline. Channels are pluggable, so `array` (for tests) or a custom
+ * push-to-provider channel slot in the same way transports and drivers do.
+ */
+import { db } from "./database.js";
+import { getMailer } from "./mail.js";
+import { dispatch } from "./queue.js";
+export class Notification {
+    /** Deliver from a queued job instead of inline. */
+    shouldQueue = false;
+    /** Channels to deliver on. Default: mail. */
+    via(_notifiable) {
+        return ["mail"];
+    }
+}
+/** Resolve where a notifiable receives a given channel. */
+export function routeFor(notifiable, channel) {
+    if (typeof notifiable.routeNotificationFor === "function") {
+        const route = notifiable.routeNotificationFor(channel);
+        if (route !== undefined && route !== null)
+            return route;
+    }
+    if (channel === "mail")
+        return notifiable.email;
+    return notifiable.id;
+}
+/* -------------------------------- channels -------------------------------- */
+/** Delivers via the mailer, using the notification's `toMail`. */
+export class MailChannel {
+    async send(notifiable, notification) {
+        if (!notification.toMail) {
+            throw new Error(`${notification.constructor.name} has no toMail() for the mail channel.`);
+        }
+        const content = notification.toMail(notifiable);
+        const to = content.to ?? routeFor(notifiable, "mail");
+        if (!to) {
+            throw new Error("Notification: no mail route (set `email` or `routeNotificationFor`).");
+        }
+        const message = getMailer().message().to(String(to)).subject(content.subject);
+        if (content.from)
+            message.from(content.from);
+        if (content.text)
+            message.text(content.text);
+        if (content.html)
+            message.html(content.html);
+        await message.send();
+    }
+}
+/** Persists the notification's `toArray` payload to a table via the query builder. */
+export class DatabaseChannel {
+    table;
+    constructor(table = "notifications") {
+        this.table = table;
+    }
+    async send(notifiable, notification) {
+        const data = notification.toArray ? notification.toArray(notifiable) : {};
+        await db(this.table).insert({
+            type: notification.constructor.name,
+            notifiable_id: routeFor(notifiable, "database") ?? null,
+            data: JSON.stringify(data),
+        });
+    }
+}
+/** Collects deliveries in memory — for tests. */
+export class ArrayChannel {
+    sent = [];
+    async send(notifiable, notification) {
+        this.sent.push({ notifiable, notification });
+    }
+}
+/* -------------------------------- notifier -------------------------------- */
+export class Notifier {
+    channels = new Map([["mail", new MailChannel()]]);
+    /** Register (or replace) a channel by name. */
+    channel(name, channel) {
+        this.channels.set(name, channel);
+        return this;
+    }
+    async deliver(notifiable, notification) {
+        for (const name of notification.via(notifiable)) {
+            const channel = this.channels.get(name);
+            if (!channel)
+                throw new Error(`No notification channel "${name}" registered.`);
+            await channel.send(notifiable, notification);
+        }
+    }
+    /** Send a notification to one or many recipients. */
+    async send(notifiables, notification) {
+        const recipients = Array.isArray(notifiables) ? notifiables : [notifiables];
+        const run = async () => {
+            for (const recipient of recipients)
+                await this.deliver(recipient, notification);
+        };
+        if (notification.shouldQueue)
+            await dispatch(run);
+        else
+            await run();
+    }
+}
+/* --------------------------------- global --------------------------------- */
+let notifier = new Notifier();
+/** Register the default notifier used by `notify()`. */
+export function setNotifier(instance) {
+    notifier = instance;
+    return notifier;
+}
+/** The default notifier instance (register channels on it). */
+export function getNotifier() {
+    return notifier;
+}
+/** Send a notification to one or many notifiables via the default notifier. */
+export function notify(notifiables, notification) {
+    return notifier.send(notifiables, notification);
+}

package/dist/core/queue.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 declare abstract class Job {
+    abstract handle(): void | Promise<void>;
+}
+/** Anything dispatchable: a `Job` instance or a plain function. */
+export type Dispatchable = Job | (() => void | Promise<void>);
+export interface JobOptions {
+    /** Seconds to wait before the job becomes available (drivers may honor it). */
+    delay?: number;
+    /** Named queue/lane to place the job on. */
+    queue?: string;
+}
+/** The bridge to your queue backend. */
+export interface QueueDriver {
+    push(job: Dispatchable, options: JobOptions): Promise<void>;
+}
+/** A driver that holds jobs locally and can run them on demand. */
+export interface Drainable {
+    readonly size: number;
+    work(): Promise<number>;
+}
+/** Runs jobs the moment they're dispatched — the default; ideal for dev/tests. */
+export declare class SyncDriver implements QueueDriver {
+    push(job: Dispatchable, _options: JobOptions): Promise<void>;
+}
+export interface QueuedJob {
+    job: Dispatchable;
+    options: JobOptions;
+}
+/** Holds jobs in memory; `work()` drains them. Assert on `.jobs` in tests. */
+export declare class MemoryDriver implements QueueDriver, Drainable {
+    readonly jobs: QueuedJob[];
+    push(job: Dispatchable, options: JobOptions): Promise<void>;
+    get size(): number;
+    /** Run every pending job in FIFO order; returns how many ran. */
+    work(): Promise<number>;
+}
+export declare class Queue {
+    readonly driver: QueueDriver;
+    constructor(driver: QueueDriver);
+    /** Place a job on the queue (the driver decides when it runs). */
+    dispatch(job: Dispatchable, options?: JobOptions): Promise<void>;
+    /** Drain the driver if it holds jobs locally; returns how many ran. */
+    work(): Promise<number>;
+}
+/** Register the default queue driver used by `dispatch()`. */
+export declare function setQueue(driver: QueueDriver): Queue;
+/** The default queue instance. */
+export declare function getQueue(): Queue;
+/** Dispatch a job (or function) onto the default queue. */
+export declare function dispatch(job: Dispatchable, options?: JobOptions): Promise<void>;
+/** Drain the default queue's pending jobs (no-op for immediate drivers). */
+export declare function work(): Promise<number>;

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);
+    }
+}