@shaferllc/keel 0.12.0 → 0.35.0

package/README.md

@@ -165,14 +165,33 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [The Service Container](./docs/container.md) | Binding and resolving services, DI |
 | [Service Providers](./docs/providers.md) | The register/boot lifecycle |
 | [Configuration](./docs/configuration.md) | `config/*.ts`, dot-notation, `env()` |
-| [Routing](./docs/routing.md) | Closures, controller tuples, parameters |
+| [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()` |
+| [Sessions](./docs/sessions.md) | Cookie-backed sessions, flash messages |
+| [Authentication](./docs/authentication.md) | Session auth, guards, user provider |
+| [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 |
+| [Events](./docs/events.md) | Emit/listen decoupling, async listeners |
+| [Cache](./docs/cache.md) | TTLs, the remember pattern, pluggable stores |
+| [Logger](./docs/logger.md) | Leveled structured logging, child loggers |
+| [Static Files](./docs/static-files.md) | serveStatic(), caching, dot-file safety |
 | [Views](./docs/views.md) | Hono JSX components, layouts, the View service |
 | [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 |
+| [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 |
 | [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 |
 
 ## Testing
 
@@ -207,8 +226,14 @@ config, and the console. On deck:
 - [x] First-class routing (groups, resources, named routes) — **v0.11.0**
 - [x] Domain routing, matchers, Inertia adapter — **v0.12.0**
 - [x] Test suite (~99% coverage)
-- [ ] ORM / query builder + migrations (wrapping Drizzle)
-- [ ] Queues (BullMQ), events, and mail
+- [x] Query builder (driver-agnostic) — **v0.28.0**
+- [x] Active-record Model layer — **v0.29.0**
+- [x] Migrations (schema builder) — **v0.30.0**
+- [x] Model relationships (hasMany / belongsTo / belongsToMany) — **v0.31.0**
+- [x] Factories & seeders (built-in Faker) — **v0.32.0**
+- [x] Model attribute casts + mass-assignment guarding — **v0.33.0**
+- [x] Mail (fluent mailer, pluggable transports) — **v0.34.0**
+- [x] Queues / background jobs (pluggable drivers) — **v0.35.0**
 - [ ] Publish `src/core` as the `@keel/core` package
 
 See [CHANGELOG.md](./CHANGELOG.md) for release history.

package/dist/core/application.js

@@ -11,6 +11,9 @@ import { Container } from "./container.js";
 import { Config } from "./config.js";
 import { Router } from "./http/router.js";
 import { View } from "./view.js";
+import { Events } from "./events.js";
+import { Cache } from "./cache.js";
+import { Logger } from "./logger.js";
 import { setApplication } from "./helpers.js";
 export class Application extends Container {
     basePath;
@@ -26,6 +29,12 @@ export class Application extends Container {
         this.singleton(Config, () => new Config());
         this.singleton(Router, (app) => new Router(app));
         this.singleton(View, () => new View());
+        this.singleton(Events, () => new Events());
+        this.singleton(Cache, () => new Cache());
+        this.singleton(Logger, (app) => new Logger({
+            level: app.config().get("logger.level", "info"),
+            pretty: Boolean(app.config().get("app.debug", false)),
+        }));
     }
     path(...segments) {
         return [this.basePath, ...segments].join("/");

package/dist/core/auth.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Session-based authentication. Builds on the session store — `login()` stashes
+ * the user id in the session, `user()` loads the full user through a provider
+ * you register. Pair it with `hash` for password checks.
+ *
+ *   const user = await findUserByEmail(email);
+ *   if (user && (await hash.verify(user.password, password))) {
+ *     auth().login(user.id);
+ *   }
+ *
+ *   auth().check();          // logged in?
+ *   await auth().user();      // the full user (via your provider)
+ */
+import type { MiddlewareHandler } from "hono";
+/** Loads a user by the id stored in the session. Register with setUserProvider. */
+export type UserProvider = (id: string) => unknown | Promise<unknown>;
+/** Tell Keel how to load the authenticated user from its id. */
+export declare function setUserProvider(fn: UserProvider): void;
+export declare class Auth {
+    /** Log a user in by id (stored in the session). */
+    login(id: string | number): void;
+    /** Log the current user out. */
+    logout(): void;
+    /** The authenticated user's id, or null. */
+    id(): string | null;
+    /** Whether a user is authenticated. */
+    check(): boolean;
+    /** Whether the request is unauthenticated. */
+    guest(): boolean;
+    /** Load the authenticated user via the registered provider. */
+    user<User = unknown>(): Promise<User | null>;
+}
+/** The auth accessor for the current request. */
+export declare function auth(): Auth;
+/**
+ * A guard middleware: rejects unauthenticated requests with a 401, or redirects
+ * if `redirectTo` is set.
+ */
+export declare function authGuard(options?: {
+    redirectTo?: string;
+}): MiddlewareHandler;

package/dist/core/auth.js

@@ -0,0 +1,70 @@
+/**
+ * Session-based authentication. Builds on the session store — `login()` stashes
+ * the user id in the session, `user()` loads the full user through a provider
+ * you register. Pair it with `hash` for password checks.
+ *
+ *   const user = await findUserByEmail(email);
+ *   if (user && (await hash.verify(user.password, password))) {
+ *     auth().login(user.id);
+ *   }
+ *
+ *   auth().check();          // logged in?
+ *   await auth().user();      // the full user (via your provider)
+ */
+import { session } from "./session.js";
+const KEY = "auth_id";
+let provider;
+/** Tell Keel how to load the authenticated user from its id. */
+export function setUserProvider(fn) {
+    provider = fn;
+}
+export class Auth {
+    /** Log a user in by id (stored in the session). */
+    login(id) {
+        session().put(KEY, String(id));
+    }
+    /** Log the current user out. */
+    logout() {
+        session().forget(KEY);
+    }
+    /** The authenticated user's id, or null. */
+    id() {
+        return session().get(KEY, null);
+    }
+    /** Whether a user is authenticated. */
+    check() {
+        return this.id() != null;
+    }
+    /** Whether the request is unauthenticated. */
+    guest() {
+        return !this.check();
+    }
+    /** Load the authenticated user via the registered provider. */
+    async user() {
+        const id = this.id();
+        if (id == null)
+            return null;
+        if (!provider) {
+            throw new Error("No user provider. Call setUserProvider((id) => findUser(id)).");
+        }
+        return (await provider(id));
+    }
+}
+/** The auth accessor for the current request. */
+export function auth() {
+    return new Auth();
+}
+/**
+ * A guard middleware: rejects unauthenticated requests with a 401, or redirects
+ * if `redirectTo` is set.
+ */
+export function authGuard(options = {}) {
+    return async (c, next) => {
+        if (new Auth().guest()) {
+            if (options.redirectTo)
+                return c.redirect(options.redirectTo);
+            return c.json({ error: "Unauthenticated", status: 401 }, 401);
+        }
+        await next();
+    };
+}

package/dist/core/cache.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A small cache with TTLs and the `remember` pattern. Memory-backed by default
+ * (per-process / per-isolate), with a pluggable store so you can swap in Redis,
+ * KV, or anything else. Bound as a singleton on the application; reach it with
+ * the global `cache()` helper.
+ *
+ *   const stats = await cache().remember("stats", 60, () => computeStats());
+ */
+export interface CacheStore {
+    get(key: string): Promise<unknown> | unknown;
+    set(key: string, value: unknown, ttlMs?: number): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+    clear(): Promise<void> | void;
+}
+/** The default in-memory store. */
+export declare class MemoryStore implements CacheStore {
+    private data;
+    get(key: string): unknown;
+    set(key: string, value: unknown, ttlMs?: number): void;
+    delete(key: string): void;
+    clear(): void;
+}
+export declare class Cache {
+    private store;
+    constructor(store?: CacheStore);
+    get<T = unknown>(key: string, fallback?: T): Promise<T>;
+    /** Store a value, optionally expiring after `ttlSeconds`. */
+    put(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    has(key: string): Promise<boolean>;
+    forget(key: string): Promise<void>;
+    /** Read and remove a value. */
+    pull<T = unknown>(key: string, fallback?: T): Promise<T>;
+    flush(): Promise<void>;
+    /**
+     * Return the cached value, or compute it with `factory`, cache it for
+     * `ttlSeconds`, and return it.
+     */
+    remember<T>(key: string, ttlSeconds: number, factory: () => T | Promise<T>): Promise<T>;
+    /** Like remember(), but cached forever (no TTL). */
+    rememberForever<T>(key: string, factory: () => T | Promise<T>): Promise<T>;
+}

package/dist/core/cache.js

@@ -0,0 +1,81 @@
+/**
+ * A small cache with TTLs and the `remember` pattern. Memory-backed by default
+ * (per-process / per-isolate), with a pluggable store so you can swap in Redis,
+ * KV, or anything else. Bound as a singleton on the application; reach it with
+ * the global `cache()` helper.
+ *
+ *   const stats = await cache().remember("stats", 60, () => computeStats());
+ */
+/** The default in-memory store. */
+export class MemoryStore {
+    data = new Map();
+    get(key) {
+        const entry = this.data.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expires && entry.expires < Date.now()) {
+            this.data.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttlMs) {
+        this.data.set(key, { value, expires: ttlMs ? Date.now() + ttlMs : 0 });
+    }
+    delete(key) {
+        this.data.delete(key);
+    }
+    clear() {
+        this.data.clear();
+    }
+}
+export class Cache {
+    store;
+    constructor(store = new MemoryStore()) {
+        this.store = store;
+    }
+    async get(key, fallback) {
+        const value = await this.store.get(key);
+        return (value === undefined ? fallback : value);
+    }
+    /** Store a value, optionally expiring after `ttlSeconds`. */
+    async put(key, value, ttlSeconds) {
+        await this.store.set(key, value, ttlSeconds ? ttlSeconds * 1000 : undefined);
+    }
+    async has(key) {
+        return (await this.store.get(key)) !== undefined;
+    }
+    async forget(key) {
+        await this.store.delete(key);
+    }
+    /** Read and remove a value. */
+    async pull(key, fallback) {
+        const value = await this.get(key, fallback);
+        await this.forget(key);
+        return value;
+    }
+    async flush() {
+        await this.store.clear();
+    }
+    /**
+     * Return the cached value, or compute it with `factory`, cache it for
+     * `ttlSeconds`, and return it.
+     */
+    async remember(key, ttlSeconds, factory) {
+        const existing = await this.store.get(key);
+        if (existing !== undefined)
+            return existing;
+        const value = await factory();
+        await this.put(key, value, ttlSeconds);
+        return value;
+    }
+    /** Like remember(), but cached forever (no TTL). */
+    async rememberForever(key, factory) {
+        const existing = await this.store.get(key);
+        if (existing !== undefined)
+            return existing;
+        const value = await factory();
+        await this.put(key, value);
+        return value;
+    }
+}

package/dist/core/casts.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Attribute casting for models. A model's `static casts` maps columns to a type;
+ * values are cast to real JS types when read (from the database or `fill`) and
+ * back to storable primitives when written. This is what lets a `boolean` column
+ * round-trip as `true`/`false` (not `1`/`0`) and a `json` column as an object.
+ *
+ *   class User extends Model {
+ *     static casts = { active: "boolean", meta: "json", joined_at: "date" };
+ *   }
+ */
+import type { Row } from "./database.js";
+export type CastType = "int" | "integer" | "float" | "number" | "boolean" | "bool" | "string" | "json" | "array" | "date";
+export type Casts = Record<string, CastType>;
+/** Raw storage value -> JS value. Tolerant of already-cast input. */
+export declare function castGet(value: unknown, type: CastType): unknown;
+/** JS value -> storable primitive (numbers, strings, 0/1, null). */
+export declare function castSet(value: unknown, type: CastType): unknown;
+/** Apply a caster to just the keys named in `casts`, leaving the rest as-is. */
+export declare function applyCasts(row: Row, casts: Casts, caster: (value: unknown, type: CastType) => unknown): Row;

package/dist/core/casts.js

@@ -0,0 +1,69 @@
+/**
+ * Attribute casting for models. A model's `static casts` maps columns to a type;
+ * values are cast to real JS types when read (from the database or `fill`) and
+ * back to storable primitives when written. This is what lets a `boolean` column
+ * round-trip as `true`/`false` (not `1`/`0`) and a `json` column as an object.
+ *
+ *   class User extends Model {
+ *     static casts = { active: "boolean", meta: "json", joined_at: "date" };
+ *   }
+ */
+/** Raw storage value -> JS value. Tolerant of already-cast input. */
+export function castGet(value, type) {
+    if (value === null || value === undefined)
+        return value;
+    switch (type) {
+        case "int":
+        case "integer":
+            return Math.trunc(Number(value));
+        case "float":
+        case "number":
+            return Number(value);
+        case "boolean":
+        case "bool":
+            return value === true || value === 1 || value === "1" || value === "true";
+        case "string":
+            return String(value);
+        case "json":
+        case "array":
+            return typeof value === "string" ? JSON.parse(value) : value;
+        case "date":
+            return value instanceof Date ? value : new Date(value);
+        default:
+            return value;
+    }
+}
+/** JS value -> storable primitive (numbers, strings, 0/1, null). */
+export function castSet(value, type) {
+    if (value === null || value === undefined)
+        return value;
+    switch (type) {
+        case "int":
+        case "integer":
+            return Math.trunc(Number(value));
+        case "float":
+        case "number":
+            return Number(value);
+        case "boolean":
+        case "bool":
+            return value ? 1 : 0;
+        case "string":
+            return String(value);
+        case "json":
+        case "array":
+            return typeof value === "string" ? value : JSON.stringify(value);
+        case "date":
+            return value instanceof Date ? value.toISOString() : value;
+        default:
+            return value;
+    }
+}
+/** Apply a caster to just the keys named in `casts`, leaving the rest as-is. */
+export function applyCasts(row, casts, caster) {
+    const out = { ...row };
+    for (const [key, type] of Object.entries(casts)) {
+        if (key in out)
+            out[key] = caster(out[key], type);
+    }
+    return out;
+}

package/dist/core/crypto.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Password hashing and value encryption — both built on the Web Crypto API, so
+ * they work the same on Node and the edge (no native bindings, no bcrypt).
+ *
+ *   const hashed = await hash.make(password);
+ *   await hash.verify(hashed, password);        // boolean
+ *
+ *   const token = await encryption.encrypt({ userId: 1 });
+ *   await encryption.decrypt(token);             // { userId: 1 } | null
+ */
+export declare const hash: {
+    /** Hash a password (PBKDF2-SHA256 with a random salt). */
+    make(password: string, iterations?: number): Promise<string>;
+    /** Verify a password against a stored hash. */
+    verify(hashed: string, password: string): Promise<boolean>;
+    /** Whether a hash was made with fewer iterations than the current default. */
+    needsRehash(hashed: string, iterations?: number): boolean;
+};
+export declare const encryption: {
+    /** Encrypt any JSON-serializable value (AES-GCM), keyed by config('app.key'). */
+    encrypt(value: unknown): Promise<string>;
+    /** Decrypt a value; returns null if the payload is tampered or invalid. */
+    decrypt<T = unknown>(payload: string): Promise<T | null>;
+};

package/dist/core/crypto.js

@@ -0,0 +1,97 @@
+/**
+ * Password hashing and value encryption — both built on the Web Crypto API, so
+ * they work the same on Node and the edge (no native bindings, no bcrypt).
+ *
+ *   const hashed = await hash.make(password);
+ *   await hash.verify(hashed, password);        // boolean
+ *
+ *   const token = await encryption.encrypt({ userId: 1 });
+ *   await encryption.decrypt(token);             // { userId: 1 } | null
+ */
+import { config } from "./helpers.js";
+/* --------------------------- shared utilities -------------------------- */
+function b64(bytes) {
+    let s = "";
+    for (const byte of bytes)
+        s += String.fromCharCode(byte);
+    return btoa(s);
+}
+function fromB64(str) {
+    const s = atob(str);
+    const arr = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++)
+        arr[i] = s.charCodeAt(i);
+    return arr;
+}
+function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++)
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return result === 0;
+}
+function appKey() {
+    const key = config("app.key", "");
+    if (!key)
+        throw new Error("Encryption requires config('app.key'). Set APP_KEY.");
+    return key;
+}
+/* ------------------------------- hashing ------------------------------- */
+const DEFAULT_ITERATIONS = 100_000;
+async function pbkdf2(password, salt, iterations) {
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(password), "PBKDF2", false, ["deriveBits"]);
+    const bits = await crypto.subtle.deriveBits({ name: "PBKDF2", salt: salt, iterations, hash: "SHA-256" }, key, 256);
+    return new Uint8Array(bits);
+}
+export const hash = {
+    /** Hash a password (PBKDF2-SHA256 with a random salt). */
+    async make(password, iterations = DEFAULT_ITERATIONS) {
+        const salt = crypto.getRandomValues(new Uint8Array(16));
+        const derived = await pbkdf2(password, salt, iterations);
+        return `pbkdf2_sha256$${iterations}$${b64(salt)}$${b64(derived)}`;
+    },
+    /** Verify a password against a stored hash. */
+    async verify(hashed, password) {
+        const [algo, iter, salt64, hash64] = hashed.split("$");
+        if (algo !== "pbkdf2_sha256" || !iter || !salt64 || !hash64)
+            return false;
+        const derived = await pbkdf2(password, fromB64(salt64), Number(iter));
+        return safeEqual(b64(derived), hash64);
+    },
+    /** Whether a hash was made with fewer iterations than the current default. */
+    needsRehash(hashed, iterations = DEFAULT_ITERATIONS) {
+        const iter = Number(hashed.split("$")[1]);
+        return !iter || iter < iterations;
+    },
+};
+/* ----------------------------- encryption ------------------------------ */
+async function aesKey() {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(appKey()));
+    return crypto.subtle.importKey("raw", digest, "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+export const encryption = {
+    /** Encrypt any JSON-serializable value (AES-GCM), keyed by config('app.key'). */
+    async encrypt(value) {
+        const iv = crypto.getRandomValues(new Uint8Array(12));
+        const data = new TextEncoder().encode(JSON.stringify(value));
+        const cipher = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: iv }, await aesKey(), data));
+        const packed = new Uint8Array(iv.length + cipher.length);
+        packed.set(iv);
+        packed.set(cipher, iv.length);
+        return b64(packed);
+    },
+    /** Decrypt a value; returns null if the payload is tampered or invalid. */
+    async decrypt(payload) {
+        try {
+            const bytes = fromB64(payload);
+            const iv = bytes.slice(0, 12);
+            const cipher = bytes.slice(12);
+            const plain = await crypto.subtle.decrypt({ name: "AES-GCM", iv: iv }, await aesKey(), cipher);
+            return JSON.parse(new TextDecoder().decode(plain));
+        }
+        catch {
+            return null;
+        }
+    },
+};

package/dist/core/database.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A small, driver-agnostic query builder. It generates parameterized SQL and
+ * runs it through a `Connection` you provide — so it works with any driver:
+ * Cloudflare D1, Neon/Postgres, PlanetScale, Turso/libSQL, better-sqlite3, pg.
+ * The core stays edge-safe because Keel never imports a database driver.
+ *
+ *   setConnection(myConnection, "postgres");
+ *   const active = await db("users").where("active", true).orderBy("name").get();
+ *   const user = await db("users").where("id", 1).first();
+ *   await db("users").insert({ email });
+ */
+export type Row = Record<string, unknown>;
+export interface WriteResult {
+    rowsAffected: number;
+    insertId?: number | string;
+}
+/** The bridge to your database driver. */
+export interface Connection {
+    /** Run a SELECT (or any row-returning query) and return the rows. */
+    select<T = Row>(sql: string, bindings: unknown[]): Promise<T[]>;
+    /** Run an INSERT/UPDATE/DELETE and return write metadata. */
+    write(sql: string, bindings: unknown[]): Promise<WriteResult>;
+}
+export type Dialect = "sqlite" | "mysql" | "postgres";
+export type Operator = "=" | "!=" | "<" | "<=" | ">" | ">=" | "like";
+/** Register the database connection (and dialect) used by `db()`. */
+export declare function setConnection(conn: Connection, driverDialect?: Dialect): void;
+export declare class QueryBuilder<T extends Row = Row> {
+    private table;
+    private wheres;
+    private orders;
+    private columns;
+    private _limit?;
+    private _offset?;
+    constructor(table: string);
+    select(...columns: string[]): this;
+    where(column: string, value: unknown): this;
+    where(column: string, operator: Operator, value: unknown): this;
+    orWhere(column: string, value: unknown): this;
+    orWhere(column: string, operator: Operator, value: unknown): this;
+    whereIn(column: string, values: unknown[]): this;
+    whereNull(column: string): this;
+    whereNotNull(column: string): this;
+    orderBy(column: string, direction?: "asc" | "desc"): this;
+    limit(n: number): this;
+    offset(n: number): this;
+    private whereClause;
+    get(): Promise<T[]>;
+    first(): Promise<T | null>;
+    count(): Promise<number>;
+    exists(): Promise<boolean>;
+    insert(data: Row): Promise<WriteResult>;
+    insertGetId(data: Row): Promise<number | string | undefined>;
+    update(data: Row): Promise<WriteResult>;
+    delete(): Promise<WriteResult>;
+}
+/** Start a query against a table. */
+export declare function db<T extends Row = Row>(table: string): QueryBuilder<T>;