npm - @shaferllc/keel - Versions diffs - 0.36.0 → 0.58.0 - Mend

@shaferllc/keel 0.36.0 → 0.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (55) hide show

package/README.md +14 -2
package/dist/core/application.d.ts +58 -2
package/dist/core/application.js +99 -3
package/dist/core/authorization.d.ts +52 -0
package/dist/core/authorization.js +97 -0
package/dist/core/broadcasting.d.ts +49 -0
package/dist/core/broadcasting.js +84 -0
package/dist/core/broker.d.ts +398 -0
package/dist/core/broker.js +602 -0
package/dist/core/crypto.d.ts +1 -1
package/dist/core/crypto.js +12 -3
package/dist/core/database.d.ts +26 -1
package/dist/core/database.js +65 -2
package/dist/core/decorators.d.ts +39 -0
package/dist/core/decorators.js +72 -0
package/dist/core/exceptions.d.ts +77 -6
package/dist/core/exceptions.js +168 -10
package/dist/core/helpers.d.ts +6 -0
package/dist/core/helpers.js +12 -0
package/dist/core/http/kernel.js +14 -2
package/dist/core/http/router.d.ts +14 -0
package/dist/core/http/router.js +30 -1
package/dist/core/index.d.ts +28 -6
package/dist/core/index.js +15 -3
package/dist/core/logger.d.ts +5 -0
package/dist/core/logger.js +24 -2
package/dist/core/migrations.js +3 -3
package/dist/core/model.d.ts +19 -1
package/dist/core/model.js +72 -4
package/dist/core/provider.d.ts +13 -4
package/dist/core/provider.js +12 -2
package/dist/core/redis.d.ts +78 -0
package/dist/core/redis.js +176 -0
package/dist/core/request-logger.d.ts +26 -0
package/dist/core/request-logger.js +48 -0
package/dist/core/request.d.ts +17 -1
package/dist/core/request.js +27 -1
package/dist/core/scheduler.d.ts +60 -0
package/dist/core/scheduler.js +166 -0
package/dist/core/session.js +17 -2
package/dist/core/storage.d.ts +57 -0
package/dist/core/storage.js +98 -0
package/dist/core/template.d.ts +50 -0
package/dist/core/template.js +753 -0
package/dist/core/testing.d.ts +54 -0
package/dist/core/testing.js +141 -0
package/dist/core/transformer.d.ts +89 -0
package/dist/core/transformer.js +152 -0
package/dist/core/validation.d.ts +20 -0
package/dist/core/validation.js +52 -1
package/dist/core/vite.d.ts +117 -0
package/dist/core/vite.js +258 -0
package/dist/vite/index.d.ts +40 -0
package/dist/vite/index.js +146 -0
package/package.json +16 -1

package/dist/core/vite.js ADDED Viewed

@@ -0,0 +1,258 @@
+/**
+ * Vite integration. Wire a modern frontend build — bundling, hashed filenames,
+ * hot module reload — to Keel's server-rendered HTML, the way modern full-stack
+ * frameworks do. `Vite` is the *server* half: it emits the `<script>`/`<link>`
+ * tags for your entrypoints and resolves individual asset URLs, switching
+ * automatically between two modes:
+ *
+ *   • Dev — a `public/hot` file (written by the `keelVite()` plugin when the
+ *     Vite dev server starts) points at `http://localhost:5173`. Tags load
+ *     straight from that server, with HMR.
+ *   • Prod — no hot file, so it reads `public/assets/.vite/manifest.json` and
+ *     emits the hashed, split, preloaded production tags.
+ *
+ *   // in a service provider
+ *   const vite = await new Vite({ entrypoints: ["resources/js/app.ts"] }).loadFromDisk();
+ *   singleton(Vite, () => vite);
+ *
+ *   // in a JSX layout <head>
+ *   {viteReactRefresh()}
+ *   {viteTags("resources/js/app.ts")}
+ *
+ * Tag generation is pure string work over an in-memory manifest, so it's
+ * edge-safe: on Workers, skip `loadFromDisk` and hand the bundled manifest in
+ * with `useManifest(...)`. Only reading from disk touches `node:fs`, and that's
+ * imported dynamically (like the static server), so the core still loads on the
+ * edge.
+ */
+import { raw } from "hono/html";
+import { bound, make } from "./helpers.js";
+const STYLE_EXTENSIONS = /\.(css|less|sass|scss|styl|stylus|pcss|postcss)(\?|$)/;
+export class Vite {
+    entrypoints;
+    hotFile;
+    manifestFile;
+    assetsUrl;
+    scriptAttributes;
+    styleAttributes;
+    hotUrl = null;
+    parsed = null;
+    fs = null;
+    constructor(options = {}) {
+        this.entrypoints = normalizeList(options.entrypoints);
+        this.hotFile = options.hotFile ?? "public/hot";
+        const buildDirectory = trimSlashes(options.buildDirectory ?? "public/assets");
+        this.manifestFile = options.manifestFile ?? `${buildDirectory}/.vite/manifest.json`;
+        this.assetsUrl = (options.assetsUrl ?? "/assets").replace(/\/+$/, "");
+        this.scriptAttributes = options.scriptAttributes ?? {};
+        this.styleAttributes = options.styleAttributes ?? {};
+    }
+    /* ------------------------------- loading -------------------------------- */
+    /**
+     * Read the hot file (dev) or the build manifest (prod) from disk. Call once at
+     * boot from a service provider. Node only — uses `node:fs`.
+     */
+    async loadFromDisk() {
+        this.fs = await import("node:fs");
+        this.refreshHot();
+        if (!this.hotUrl) {
+            // No dev server — try the production manifest. Leave it null if there's no
+            // build yet; tag generation raises a clear error when it's actually used.
+            try {
+                this.parsed = JSON.parse(this.fs.readFileSync(this.manifestFile, "utf8"));
+            }
+            catch {
+                this.parsed = null;
+            }
+        }
+        return this;
+    }
+    /** Inject a manifest directly — for the edge, where there's no filesystem. */
+    useManifest(manifest) {
+        this.parsed = manifest;
+        return this;
+    }
+    /** Force the dev-server URL (or `null` for prod). Bypasses the hot file. */
+    useHotUrl(url) {
+        this.hotUrl = url ? url.replace(/\/+$/, "") : null;
+        return this;
+    }
+    /** Re-read the hot file if we're on Node and no manifest has claimed prod mode. */
+    refreshHot() {
+        if (!this.fs)
+            return;
+        try {
+            const contents = this.fs.readFileSync(this.hotFile, "utf8").trim();
+            this.hotUrl = contents ? contents.replace(/\/+$/, "") : null;
+        }
+        catch {
+            this.hotUrl = null;
+        }
+    }
+    /** The dev-server URL when running Vite, else `null` (production). */
+    hot() {
+        // A loaded manifest means we built for production — never dev.
+        if (this.parsed)
+            return null;
+        this.refreshHot();
+        return this.hotUrl;
+    }
+    /** The parsed production manifest. Throws if it hasn't been loaded. */
+    manifest() {
+        if (!this.parsed) {
+            throw new Error(`Vite manifest not found at "${this.manifestFile}". Run the client build ` +
+                `(e.g. \`vite build\`) or start the dev server.`);
+        }
+        return this.parsed;
+    }
+    /* ---------------------------- tag generation ---------------------------- */
+    /**
+     * The `<script>`/`<link>` tags for one or more entrypoints — dev-server URLs
+     * with HMR while developing, hashed + preloaded tags in production. Falls back
+     * to the entrypoints passed to the constructor.
+     */
+    generateEntryPointsTags(entrypoints) {
+        const entries = entrypoints !== undefined ? normalizeList(entrypoints) : this.entrypoints;
+        const hot = this.hot();
+        const tags = hot ? this.devTags(hot, entries) : this.productionTags(entries);
+        return raw(tags.join("\n"));
+    }
+    /** The public URL for a single asset (an image, a font) — dev or hashed prod. */
+    assetPath(asset) {
+        const hot = this.hot();
+        if (hot)
+            return `${hot}/${trimSlashes(asset)}`;
+        const chunk = this.manifest()[asset];
+        if (!chunk) {
+            throw new Error(`Unable to locate "${asset}" in the Vite manifest.`);
+        }
+        return `${this.assetsUrl}/${chunk.file}`;
+    }
+    /**
+     * The React Fast Refresh preamble — required before your entry script when
+     * using `@vitejs/plugin-react`. Empty in production.
+     */
+    reactHMR() {
+        const hot = this.hot();
+        if (!hot)
+            return raw("");
+        return raw(`<script type="module">\n` +
+            `import RefreshRuntime from "${hot}/@react-refresh"\n` +
+            `RefreshRuntime.injectIntoGlobalHook(window)\n` +
+            `window.$RefreshReg$ = () => {}\n` +
+            `window.$RefreshSig$ = () => (type) => type\n` +
+            `window.__vite_plugin_react_preamble_installed__ = true\n` +
+            `</script>`);
+    }
+    /* ------------------------------ internals ------------------------------- */
+    devTags(hot, entries) {
+        // The Vite client (its own module) drives HMR — always first.
+        const tags = [`<script type="module" src="${hot}/@vite/client"></script>`];
+        for (const entry of entries) {
+            const url = `${hot}/${trimSlashes(entry)}`;
+            tags.push(this.tagFor(entry, url));
+        }
+        return tags;
+    }
+    productionTags(entries) {
+        const manifest = this.manifest();
+        const styles = [];
+        const preloads = [];
+        const scripts = [];
+        const seen = new Set();
+        const walk = (name, isEntry) => {
+            const chunk = manifest[name];
+            if (!chunk || seen.has(name))
+                return;
+            seen.add(name);
+            for (const imported of chunk.imports ?? [])
+                walk(imported, false);
+            for (const css of chunk.css ?? []) {
+                const url = `${this.assetsUrl}/${css}`;
+                pushUnique(styles, this.styleTag(css, url));
+            }
+            const url = `${this.assetsUrl}/${chunk.file}`;
+            if (isEntry)
+                pushUnique(scripts, this.scriptTag(name, url));
+            else
+                pushUnique(preloads, `<link rel="modulepreload" href="${url}">`);
+        };
+        for (const entry of entries) {
+            const chunk = manifest[entry];
+            if (!chunk) {
+                throw new Error(`Entrypoint "${entry}" is not in the Vite manifest.`);
+            }
+            walk(entry, true);
+        }
+        // Styles, then preloads, then the entry scripts.
+        return [...styles, ...preloads, ...scripts];
+    }
+    /** In dev, a style entrypoint is a `<link>`; everything else a module script. */
+    tagFor(entry, url) {
+        return STYLE_EXTENSIONS.test(entry) ? this.styleTag(entry, url) : this.scriptTag(entry, url);
+    }
+    scriptTag(src, url) {
+        const attrs = renderAttributes({ type: "module", src: url, ...resolveAttributes(this.scriptAttributes, src, url) });
+        return `<script${attrs}></script>`;
+    }
+    styleTag(src, url) {
+        const attrs = renderAttributes({ rel: "stylesheet", href: url, ...resolveAttributes(this.styleAttributes, src, url) });
+        return `<link${attrs}>`;
+    }
+}
+/* -------------------------------- helpers --------------------------------- */
+function resolveAttributes(attributes, src, url) {
+    const resolved = typeof attributes === "function" ? attributes({ src, url }) : attributes;
+    return resolved ?? {};
+}
+function renderAttributes(attributes) {
+    const parts = [];
+    for (const [key, value] of Object.entries(attributes)) {
+        if (value === false || value == null)
+            continue;
+        if (value === true)
+            parts.push(key);
+        else
+            parts.push(`${key}="${escapeAttribute(String(value))}"`);
+    }
+    return parts.length ? ` ${parts.join(" ")}` : "";
+}
+function escapeAttribute(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/"/g, "&quot;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+function normalizeList(value) {
+    if (value == null)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+function trimSlashes(value) {
+    return value.replace(/^\/+|\/+$/g, "");
+}
+function pushUnique(list, value) {
+    if (!list.includes(value))
+        list.push(value);
+}
+/* -------------------------------- globals --------------------------------- */
+function resolveVite() {
+    if (!bound(Vite)) {
+        throw new Error("Vite is not configured. Bind it in a provider: " +
+            'singleton(Vite, () => new Vite({ entrypoints: ["resources/js/app.ts"] })).');
+    }
+    return make(Vite);
+}
+/** The entrypoint tags for the current app's Vite instance. Use in a JSX `<head>`. */
+export function viteTags(entrypoints) {
+    return resolveVite().generateEntryPointsTags(entrypoints);
+}
+/** The URL for a single asset through the current app's Vite instance. */
+export function viteAsset(asset) {
+    return resolveVite().assetPath(asset);
+}
+/** The React Fast Refresh preamble (dev only) for the current app's Vite instance. */
+export function viteReactRefresh() {
+    return resolveVite().reactHMR();
+}

package/dist/vite/index.d.ts ADDED Viewed

@@ -0,0 +1,40 @@
+/**
+ * The Keel Vite plugin — the build-time half of Keel's Vite integration. Drop it
+ * into `vite.config.ts` and it wires Vite to the `Vite` server service in
+ * `@shaferllc/keel/core`:
+ *
+ *   import { defineConfig } from "vite";
+ *   import { keelVite } from "@shaferllc/keel/vite";
+ *
+ *   export default defineConfig({
+ *     plugins: [keelVite({ entrypoints: ["resources/js/app.ts"] })],
+ *   });
+ *
+ * It does three things:
+ *   • Configures the build — manifest on, output to `public/assets`, your
+ *     entrypoints as the Rollup inputs, and `base` set to `assetsUrl` so hashed
+ *     asset URLs resolve in production.
+ *   • Writes a `public/hot` file with the dev-server URL while `vite` runs (and
+ *     removes it on exit) — the marker the `Vite` service reads to switch into
+ *     dev mode with HMR.
+ *   • Optionally triggers a full browser reload when files matching `reload`
+ *     globs change (e.g. server-rendered views Vite doesn't otherwise watch).
+ *
+ * This module runs only in the Node build environment (never on the edge), so it
+ * imports `node:fs`/`node:path` directly.
+ */
+import type { Plugin } from "vite";
+export interface KeelViteOptions {
+    /** Entry files, each producing its own bundle. Required. */
+    entrypoints: string | string[];
+    /** Build output directory (must match the server's `buildDirectory`). Default: `public/assets`. */
+    buildDirectory?: string;
+    /** The dev-server marker file the `Vite` service reads. Default: `public/hot`. */
+    hotFile?: string;
+    /** Public URL / CDN base for built assets. Default: `/assets`. */
+    assetsUrl?: string;
+    /** Glob patterns that trigger a full page reload when changed (e.g. views). */
+    reload?: string[];
+}
+/** The Keel Vite plugin(s). Spread-safe: returns an array to add to `plugins`. */
+export declare function keelVite(options: KeelViteOptions): Plugin[];

package/dist/vite/index.js ADDED Viewed

@@ -0,0 +1,146 @@
+/**
+ * The Keel Vite plugin — the build-time half of Keel's Vite integration. Drop it
+ * into `vite.config.ts` and it wires Vite to the `Vite` server service in
+ * `@shaferllc/keel/core`:
+ *
+ *   import { defineConfig } from "vite";
+ *   import { keelVite } from "@shaferllc/keel/vite";
+ *
+ *   export default defineConfig({
+ *     plugins: [keelVite({ entrypoints: ["resources/js/app.ts"] })],
+ *   });
+ *
+ * It does three things:
+ *   • Configures the build — manifest on, output to `public/assets`, your
+ *     entrypoints as the Rollup inputs, and `base` set to `assetsUrl` so hashed
+ *     asset URLs resolve in production.
+ *   • Writes a `public/hot` file with the dev-server URL while `vite` runs (and
+ *     removes it on exit) — the marker the `Vite` service reads to switch into
+ *     dev mode with HMR.
+ *   • Optionally triggers a full browser reload when files matching `reload`
+ *     globs change (e.g. server-rendered views Vite doesn't otherwise watch).
+ *
+ * This module runs only in the Node build environment (never on the edge), so it
+ * imports `node:fs`/`node:path` directly.
+ */
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+/** The Keel Vite plugin(s). Spread-safe: returns an array to add to `plugins`. */
+export function keelVite(options) {
+    const entrypoints = toArray(options.entrypoints);
+    if (entrypoints.length === 0) {
+        throw new Error("keelVite: `entrypoints` must list at least one entry file.");
+    }
+    const buildDirectory = trimTrailingSlash(options.buildDirectory ?? "public/assets");
+    const hotFile = options.hotFile ?? "public/hot";
+    const assetsUrl = options.assetsUrl ?? "/assets";
+    const plugins = [
+        {
+            name: "keel:vite",
+            enforce: "post",
+            config(user, env) {
+                const build = env.command === "build";
+                return {
+                    // Dev serves from the root; the build prefixes hashed assets with assetsUrl.
+                    base: build ? withTrailingSlash(assetsUrl) : "/",
+                    // Keel serves `public/` itself — don't let Vite copy it into the bundle.
+                    publicDir: user.publicDir ?? false,
+                    build: {
+                        manifest: user.build?.manifest ?? true,
+                        outDir: user.build?.outDir ?? buildDirectory,
+                        // Flat output: assetsUrl already namespaces the files, so don't nest
+                        // them under another `assets/` folder.
+                        assetsDir: user.build?.assetsDir ?? "",
+                        emptyOutDir: user.build?.emptyOutDir ?? true,
+                        rollupOptions: {
+                            ...user.build?.rollupOptions,
+                            input: user.build?.rollupOptions?.input ?? entrypoints,
+                        },
+                    },
+                };
+            },
+            configureServer(server) {
+                const write = () => {
+                    mkdirSync(dirname(hotFile), { recursive: true });
+                    writeFileSync(hotFile, devServerUrl(server));
+                };
+                const clean = () => {
+                    try {
+                        rmSync(hotFile);
+                    }
+                    catch {
+                        // already gone — nothing to do
+                    }
+                };
+                server.httpServer?.once("listening", write);
+                server.httpServer?.once("close", clean);
+                process.once("exit", clean);
+                for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+                    process.once(signal, () => {
+                        clean();
+                        process.exit();
+                    });
+                }
+            },
+        },
+    ];
+    if (options.reload && options.reload.length > 0) {
+        const matchers = options.reload.map(globToRegExp);
+        plugins.push({
+            name: "keel:vite-reload",
+            handleHotUpdate({ file, server }) {
+                if (matchers.some((re) => re.test(file))) {
+                    server.ws.send({ type: "full-reload", path: "*" });
+                }
+            },
+        });
+    }
+    return plugins;
+}
+/* -------------------------------- helpers --------------------------------- */
+function devServerUrl(server) {
+    const address = server.httpServer?.address();
+    const port = address && typeof address === "object" ? address.port : 5173;
+    const https = Boolean(server.config.server.https);
+    const protocol = https ? "https" : "http";
+    const configured = server.config.server.host;
+    const host = typeof configured === "string" ? configured : "localhost";
+    return `${protocol}://${host}:${port}`;
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+function withTrailingSlash(value) {
+    return value.endsWith("/") ? value : `${value}/`;
+}
+/** A small glob → RegExp for `reload` patterns: supports `**`, `*`, and `?`. */
+function globToRegExp(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i++) {
+        const char = glob[i];
+        if (char === "*") {
+            if (glob[i + 1] === "*") {
+                re += ".*";
+                i++;
+                if (glob[i + 1] === "/")
+                    i++; // collapse `**/`
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (char === "?") {
+            re += "[^/]";
+        }
+        else if ("\\^$.|+()[]{}".includes(char)) {
+            re += `\\${char}`;
+        }
+        else {
+            re += char;
+        }
+    }
+    return new RegExp(`${re}$`);
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.36.0",
+  "version": "0.58.0",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",
@@ -24,6 +24,10 @@
     "./core": {
       "types": "./dist/core/index.d.ts",
       "import": "./dist/core/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "import": "./dist/vite/index.js"
     }
   },
   "files": [
@@ -41,18 +45,29 @@
     "test": "node --import tsx --test tests/*.test.ts",
     "test:coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-exclude='tests/**' tests/*.test.ts",
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "dev:client": "vite",
+    "build:client": "vite build",
     "prepare": "npm run build"
   },
   "dependencies": {
     "dotenv": "^16.4.7",
     "hono": "^4.6.14"
   },
+  "peerDependencies": {
+    "vite": "^5 || ^6 || ^7"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@hono/node-server": "^1.13.7",
     "@types/node": "^26.1.1",
     "commander": "^12.1.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
+    "vite": "^6.4.3",
     "zod": "^4.4.3"
   }
 }