npm - @shaferllc/keel - Versions diffs - 0.66.0 → 0.68.0 - Mend

@shaferllc/keel 0.66.0 → 0.68.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 (132) hide show

package/AGENTS.md +167 -0
package/README.md +30 -1
package/bin/keel-mcp.mjs +9 -0
package/dist/core/application.d.ts +5 -5
package/dist/core/application.js +2 -2
package/dist/core/cache.d.ts +82 -5
package/dist/core/cache.js +181 -23
package/dist/core/cli/stubs.d.ts +12 -0
package/dist/core/cli/stubs.js +120 -0
package/dist/core/events.d.ts +129 -5
package/dist/core/events.js +165 -7
package/dist/core/health.d.ts +141 -0
package/dist/core/health.js +226 -0
package/dist/core/helpers.d.ts +9 -3
package/dist/core/helpers.js +11 -3
package/dist/core/index.d.ts +15 -10
package/dist/core/index.js +7 -4
package/dist/core/lock.d.ts +139 -0
package/dist/core/lock.js +215 -0
package/dist/core/logger.d.ts +82 -4
package/dist/core/logger.js +141 -23
package/dist/core/mail.d.ts +128 -7
package/dist/core/mail.js +264 -16
package/dist/core/queue.d.ts +134 -9
package/dist/core/queue.js +304 -14
package/dist/core/storage.d.ts +159 -6
package/dist/core/storage.js +287 -7
package/dist/mcp/server.d.ts +19 -0
package/dist/mcp/server.js +355 -0
package/docs/ai-manifest.json +2472 -0
package/docs/ai.md +128 -0
package/docs/architecture.md +331 -0
package/docs/authentication.md +453 -0
package/docs/authorization.md +167 -0
package/docs/broadcasting.md +137 -0
package/docs/broker.md +500 -0
package/docs/cache.md +558 -0
package/docs/configuration.md +311 -0
package/docs/console.md +356 -0
package/docs/container.md +467 -0
package/docs/controllers.md +265 -0
package/docs/cors.md +51 -0
package/docs/database.md +530 -0
package/docs/debugging.md +129 -0
package/docs/decorators.md +127 -0
package/docs/errors.md +395 -0
package/docs/events.md +496 -0
package/docs/examples/architecture-app.ts +27 -0
package/docs/examples/authentication.ts +61 -0
package/docs/examples/authorization.ts +79 -0
package/docs/examples/broadcasting.ts +60 -0
package/docs/examples/broker-cache-validate.ts +34 -0
package/docs/examples/broker-fault-tolerance.ts +29 -0
package/docs/examples/broker-middleware.ts +27 -0
package/docs/examples/broker.ts +203 -0
package/docs/examples/cache.ts +222 -0
package/docs/examples/configuration.ts +81 -0
package/docs/examples/container.ts +134 -0
package/docs/examples/controllers.ts +86 -0
package/docs/examples/database.ts +118 -0
package/docs/examples/debugging.ts +41 -0
package/docs/examples/decorators.ts +40 -0
package/docs/examples/errors.ts +121 -0
package/docs/examples/events.ts +204 -0
package/docs/examples/factories.ts +84 -0
package/docs/examples/hashing.ts +71 -0
package/docs/examples/health.ts +94 -0
package/docs/examples/helpers.ts +171 -0
package/docs/examples/hooks.ts +54 -0
package/docs/examples/inertia.ts +81 -0
package/docs/examples/locks.ts +120 -0
package/docs/examples/logger.ts +92 -0
package/docs/examples/mail.ts +160 -0
package/docs/examples/middleware.ts +119 -0
package/docs/examples/migrations.ts +126 -0
package/docs/examples/models.ts +239 -0
package/docs/examples/notification.ts +124 -0
package/docs/examples/providers.ts +123 -0
package/docs/examples/queues.ts +254 -0
package/docs/examples/rate-limiting.ts +42 -0
package/docs/examples/redis.ts +99 -0
package/docs/examples/request-response.ts +197 -0
package/docs/examples/routing.ts +186 -0
package/docs/examples/scheduling.ts +62 -0
package/docs/examples/sessions.ts +102 -0
package/docs/examples/static-files.ts +63 -0
package/docs/examples/storage.ts +132 -0
package/docs/examples/templates.ts +58 -0
package/docs/examples/testing.ts +66 -0
package/docs/examples/transformer.ts +141 -0
package/docs/examples/transformers.ts +49 -0
package/docs/examples/url-builder.ts +86 -0
package/docs/examples/validation.ts +102 -0
package/docs/examples/views.tsx +62 -0
package/docs/examples/vite.ts +106 -0
package/docs/factories.md +166 -0
package/docs/getting-started.md +290 -0
package/docs/hashing.md +259 -0
package/docs/health.md +225 -0
package/docs/helpers.md +347 -0
package/docs/hono.md +186 -0
package/docs/hooks.md +118 -0
package/docs/inertia.md +241 -0
package/docs/locks.md +323 -0
package/docs/logger.md +290 -0
package/docs/mail.md +678 -0
package/docs/middleware.md +425 -0
package/docs/migrations.md +476 -0
package/docs/models.md +810 -0
package/docs/notifications.md +474 -0
package/docs/providers.md +363 -0
package/docs/queues.md +679 -0
package/docs/rate-limiting.md +155 -0
package/docs/redis.md +178 -0
package/docs/request-response.md +953 -0
package/docs/routing.md +804 -0
package/docs/scheduling.md +110 -0
package/docs/security.md +85 -0
package/docs/sessions.md +354 -0
package/docs/social-auth.md +174 -0
package/docs/static-files.md +211 -0
package/docs/storage.md +450 -0
package/docs/templates.md +315 -0
package/docs/testing.md +125 -0
package/docs/transformers.md +381 -0
package/docs/url-builder.md +295 -0
package/docs/validation.md +288 -0
package/docs/views.md +267 -0
package/docs/vite.md +434 -0
package/llms-full.txt +17694 -0
package/llms.txt +116 -0
package/package.json +26 -7

package/docs/templates.md ADDED Viewed

@@ -0,0 +1,315 @@
+# Templates
+A string templating engine in the spirit of AdonisJS **Edge** — `{{ }}`
+interpolation and `@`-prefixed tags for logic, includes, layouts, and
+components. Reach for it when you want plain-text templates instead of (or
+alongside) [JSX views](./views.md).
+Unlike engines that compile a template to a function with `eval` /
+`new Function`, Keel **interprets** templates against a small, safe expression
+evaluator. No dynamic code generation, so the same templates run on Node **and**
+on Cloudflare Workers (where `eval` is forbidden).
+## Rendering
+Register a template by name, then render it with a state object:
+```ts
+import { templates, render } from "@shaferllc/keel/core";
+templates().register("greeting", "Hello, {{ name }}!");
+await render("greeting", { name: "Ada" }); // "Hello, Ada!"
+```
+`render()` returns a `Promise<string>` — hand it to a response or a [view](./views.md):
+```ts
+import { html, render } from "@shaferllc/keel/core";
+return html(await render("greeting", { name: "Ada" }));
+```
+Register many at once (e.g. a Node loader reads `.html` files and passes them in):
+```ts
+templates().registerAll({
+  layout: await readFile("views/layout.html", "utf8"),
+  home: await readFile("views/home.html", "utf8"),
+});
+```
+## Interpolation
+```html
+{{ user.name }}      {{-- escaped: HTML-safe --}}
+{{{ post.body }}}    {{-- raw: unescaped, for trusted HTML --}}
+{{-- this is a comment; it renders nothing --}}
+```
+Escaped `{{ }}` is the default and encodes `& < > " '`. Use raw `{{{ }}}` only for
+HTML you trust. A `null`/`undefined` value renders as an empty string.
+## Expressions
+Interpolation and tag conditions accept a practical subset of JavaScript —
+enough for real templates, without `eval`:
+```html
+{{ user.name }}                     {{-- property + index access --}}
+{{ items[0] }}
+{{ title.toUpperCase() }}           {{-- method calls --}}
+{{ items.join(", ") }}
+{{ price * qty }}                    {{-- + - * / % --}}
+{{ n > 3 && n < 10 }}               {{-- comparisons, && || ! ?? --}}
+{{ admin ? "Admin" : "User" }}      {{-- ternary --}}
+{{ [1, 2, 3].length }}              {{-- array / object literals --}}
+{{ { role: "admin" }.role }}
+```
+Not supported: assignment, arrow functions, and other statement-level JS. Keep
+logic in your controller and pass results in as state.
+### Filters
+Pipe a value through a filter with `|`:
+```html
+{{ name | upper }}
+{{ name | capitalize }}
+{{ items | length }}
+{{ price | currency("USD") }}    {{-- filters take arguments --}}
+```
+Built-in filters: `upper`, `lower`, `capitalize`, `json`, `length`. Register your
+own on the engine:
+```ts
+templates().filter("currency", (v, code) =>
+  new Intl.NumberFormat("en-US", { style: "currency", currency: String(code) }).format(Number(v)),
+);
+```
+## Conditionals
+```html
+@if(user.admin)
+  <span>Admin</span>
+@elseif(user.member)
+  <span>Member</span>
+@else
+  <span>Guest</span>
+@end
+```
+## Loops
+`@each` iterates arrays (or the values of an object). A `$loop` variable exposes
+positional info, and you can capture the index:
+```html
+<ul>
+@each(post in posts)
+  <li>{{ $loop.iteration }}. {{ post.title }}</li>
+@end
+</ul>
+@each(item, i in items)
+  {{ i }}: {{ item }}
+@end
+```
+`$loop` fields: `index` (0-based), `iteration` (1-based), `first`, `last`,
+`count`, `even`, `odd`.
+## Partials
+Pull one template into another with `@include` — it shares the current state:
+```html
+{{-- list.html --}}
+<ul>@each(item in items)@include("row")@end</ul>
+{{-- row.html --}}
+<li>{{ item }}</li>
+```
+`@includeIf(condition, "name")` includes only when the condition is truthy.
+## Layouts
+A page declares its layout and fills the layout's `@yield` slots with `@section`:
+```html
+{{-- layout.html --}}
+<!doctype html>
+<title>@yield("title")Keel@end</title>
+<body>@yield("body")@end</body>
+{{-- page.html --}}
+@layout("layout")
+@section("title"){{ page.title }} · Keel@end
+@section("body")<h1>{{ page.title }}</h1>@end
+```
+`@yield("name") … @end` renders the matching section, falling back to the content
+between `@yield` and `@end` when the page defines no such section.
+## Components
+Components are reusable templates rendered with props and slots. The content
+between `@component` and its `@end` becomes the `main` slot; `@slot("name")`
+defines named slots. Inside the component, slots arrive as pre-rendered HTML
+strings on a `slots` object:
+```html
+{{-- card.html --}}
+<div class="card">
+  <header>{{{ slots.header }}}</header>
+  <main>{{{ slots.main }}}</main>
+  <footer>{{ title }}</footer>
+</div>
+{{-- usage --}}
+@component("card", { title: "Welcome" })
+  @slot("header")<h2>Hi</h2>@end
+  <p>Body content goes to the main slot.</p>
+@end
+```
+Props are any expression evaluating to an object; they become the component's
+state (merged with globals).
+## Globals
+Expose values or helpers to every template:
+```ts
+templates()
+  .global("appName", "Keel")
+  .global("asset", (path: string) => `/static/${path}`);
+```
+```html
+<title>{{ appName }}</title>
+<img src="{{ asset('logo.svg') }}" />
+```
+## Debugging
+`@dump(value)` renders a `<pre>` of the value's JSON — handy while building a
+template.
+```html
+@dump(user)
+```
+## Escaping & safety
+- Escaped `{{ }}` encodes HTML; only use raw `{{{ }}}` for trusted content.
+- The evaluator blocks access to `__proto__`, `constructor`, and `prototype`, so
+  template state can't be used to reach the prototype chain.
+- There's no `eval`: a template can't execute arbitrary JavaScript, only the
+  expression subset above.
+## API reference
+### `templates()`
+`templates(): TemplateEngine`
+Returns the default engine — register templates, globals, and filters on it.
+```ts
+templates().register("home", "…");
+```
+**Notes:** module-global and shared. Swap it with `setTemplateEngine()` (e.g. for
+an isolated engine in a test).
+### `render(name, state?)`
+`render(name: string, state?: Record<string, unknown>): Promise<string>`
+Renders a registered template on the default engine.
+```ts
+await render("home", { user });
+```
+**Notes:** throws if `name` isn't registered. Async because includes, components,
+and layouts compose asynchronously.
+### `setTemplateEngine(engine)`
+`setTemplateEngine(engine: TemplateEngine): TemplateEngine`
+Replaces the default engine and returns it.
+**Notes:** the last call wins; useful to reset state between tests.
+### `escapeHtml(value)`
+`escapeHtml(value: unknown): string`
+HTML-escapes a value (`& < > " '`); `null`/`undefined` become `""`. This is what
+`{{ }}` uses internally.
+### `TemplateEngine`
+The engine class. Construct your own for isolation, or use `templates()`.
+#### `register(name, source)`
+`register(name: string, source: string): this`
+Parses and registers a template. Chainable.
+**Notes:** parsing happens here, so a malformed template throws at registration,
+not at render.
+#### `registerAll(sources)`
+`registerAll(sources: Record<string, string>): this`
+Registers many templates at once from a `name → source` map.
+#### `has(name)`
+`has(name: string): boolean`
+Whether a template is registered.
+#### `global(name, value)`
+`global(name: string, value: unknown): this`
+Exposes a value or function to every template as a global variable.
+#### `filter(name, fn)`
+`filter(name: string, fn: Filter): this`
+Registers a `{{ value | name }}` filter. `Filter` is
+`(value: unknown, ...args: unknown[]) => unknown`.
+#### `render(name, state?)`
+`render(name: string, state?: Record<string, unknown>): Promise<string>`
+Renders a registered template. Throws for an unknown template, tag, or filter.
+### Interfaces & types
+#### `Filter`
+`type Filter = (value: unknown, ...args: unknown[]) => unknown`
+A pipe filter: receives the piped value plus any `filter(arg)` arguments, returns
+the transformed value.
+#### `RenderContext`
+`interface RenderContext { sections: Record<string, string>; slots: Record<string, string> }`
+Internal per-render state threaded through layouts and components — you won't
+construct it directly.

package/docs/testing.md ADDED Viewed

@@ -0,0 +1,125 @@
+# Testing
+Test your app by **injecting requests** — no server, no port, no network — and
+asserting on the response. `testClient()` wraps your app's Hono instance (which
+already does fetch-style injection) with verb helpers and fluent assertions, the
+way Fastify's `inject()` works.
+## The client
+Build a client from an `Application` and fire requests:
+```ts
+import { test } from "node:test";
+import { Application, Router, json, testClient } from "@shaferllc/keel/core";
+async function makeApp() {
+  const app = new Application();
+  await app.boot([], { discoverConfig: false, config: { app: {} } });
+  app.make(Router).get("/health", () => json({ ok: true }));
+  return app;
+}
+test("health check", async () => {
+  const client = testClient(await makeApp());
+  const res = await client.get("/health");
+  res.assertStatus(200).assertJson({ ok: true });
+});
+```
+`testClient()` accepts an **`Application`** (built through a fresh kernel), an
+**`HttpKernel`** (use this if you need global middleware registered with
+`kernel.use(...)`), or anything with a `request()` (a built Hono instance).
+## Requests
+Verb helpers cover the common methods; `post` / `put` / `patch` take a body that's
+JSON-encoded automatically:
+```ts
+await client.get("/users");
+await client.get("/users?active=true");
+await client.post("/users", { email: "a@b.com", name: "Ada" }); // sends JSON
+await client.put("/users/1", { name: "Grace" });
+await client.delete("/users/1");
+// full control — pass a RequestInit for headers, custom bodies, etc.
+await client.request("/users", { method: "POST", headers: { authorization: "Bearer x" }, body });
+```
+## The response
+Every call resolves to a `TestResponse`. The body is **pre-buffered**, so reads
+are synchronous and repeatable (no "body already consumed"):
+```ts
+const res = await client.get("/user");
+res.status;            // 200
+res.header("content-type");
+res.text();            // the raw body
+res.json<User>();      // parsed (sync — the body is already read)
+```
+## Assertions
+Assertions are chainable and throw a descriptive error (including the body) on
+mismatch:
+```ts
+res.assertStatus(201);
+res.assertOk();                          // any 2xx
+res.assertJson({ id: 1, email });        // deep-equals the JSON body
+res.assertText("pong");
+res.assertHeader("content-type", "application/json");
+res.assertRedirect("/login");            // 3xx (+ optional Location)
+// chain them:
+(await client.post("/users", body)).assertStatus(201).assertJson({ id: 2, ...body });
+```
+## Testing with middleware
+When your test needs global middleware (sessions, request logging, auth), build
+the kernel yourself and hand it to `testClient`:
+```ts
+const app = await makeApp();
+const kernel = new HttpKernel(app);
+kernel.use(sessionMiddleware());
+kernel.use(requestLogger());
+const client = testClient(kernel);
+```
+## API reference
+### `testClient(target)`
+`testClient(target: Application | HttpKernel | { request(...) }): TestClient`
+Builds a `TestClient`. An `Application` is built through a fresh `HttpKernel`; pass
+a kernel to register global middleware first.
+### `TestClient`
+| Method | Signature |
+|--------|-----------|
+| `get` / `delete` | `(path, init?) => Promise<TestResponse>` |
+| `post` / `put` / `patch` | `(path, body?, init?) => Promise<TestResponse>` — body JSON-encoded |
+| `request` | `(path, init?) => Promise<TestResponse>` — the low-level form |
+### `TestResponse`
+Body pre-buffered; reads are synchronous.
+| Member | Notes |
+|--------|-------|
+| `status` | the response status |
+| `header(name)` | a response header, or `null` |
+| `text()` / `json<T>()` | the body (raw / parsed) |
+| `assertStatus(n)` / `assertOk()` | status is `n` / any 2xx |
+| `assertJson(v)` | JSON body deep-equals `v` |
+| `assertText(s)` / `assertHeader(n, v)` | exact body / header match |
+| `assertRedirect(location?)` | 3xx, optionally to `location` |
+| `raw` | the underlying `Response` |
+All assertions return `this` (chainable) and throw on mismatch.