@alxia/core 0.1.0 → 0.2.0

package/dist/reply/problem.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Problem details for HTTP APIs (RFC 9457, which obsoletes RFC 7807): a
+ * JSON body sent as `application/problem+json`.
+ */
+import type { ClientErrorStatus, ServerErrorStatus } from '../types/status';
+import { Reply, type ReplyInit } from './reply';
+/**
+ * The members RFC 9457 defines. A problem may carry members of its own
+ * beside them, its extensions: `problem()` keeps their types.
+ */
+export interface ProblemDetails<Status extends ClientErrorStatus | ServerErrorStatus = ClientErrorStatus | ServerErrorStatus> {
+    /** A URI naming the problem type; absent, it is `about:blank`. */
+    readonly type?: string;
+    /** A short summary of the problem type, the same for every occurrence. */
+    readonly title?: string;
+    /** The status of the response, which `problem()` replies with. */
+    readonly status: Status;
+    /** What went wrong with this occurrence. */
+    readonly detail?: string;
+    /** A URI naming this occurrence. */
+    readonly instance?: string;
+}
+/**
+ * A reply whose body is a problem, with `status` as its status and
+ * `content-type: application/problem+json` unless `init` sets one. Any
+ * other member is an extension, kept as given and in the body's type:
+ *
+ * ```ts
+ * problem({ type: 'urn:ietf:params:jmap:error:limit', status: 413, limit: 'maxSizeRequest' });
+ * ```
+ */
+export declare function problem<const Body extends ProblemDetails>(body: Body, init?: ReplyInit): Reply<Body['status'], Body>;
+//# sourceMappingURL=problem.d.ts.map

package/dist/reply/problem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"problem.d.ts","sourceRoot":"","sources":["../../src/reply/problem.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,cAAc,CAC9B,MAAM,SAAS,iBAAiB,GAAG,iBAAiB,GACjD,iBAAiB,GACjB,iBAAiB;IAEpB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,KAAK,CAAC,IAAI,SAAS,cAAc,EACxD,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE,SAAS,GACd,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,CAM7B"}

package/dist/reply/reply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reply.d.ts","sourceRoot":"","sources":["../../src/reply/reply.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE5D,MAAM,WAAW,SAAS;IACzB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,qBAAa,KAAK,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM,EAAE,IAAI,GAAG,OAAO;IAChE;;;;OAIG;IACH,SAAiB,QAAQ,EAAE,IAAI,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,CAAC;gBAE9B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,SAAS;CAKxD;AAED,+CAA+C;AAC/C,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;CAUZ,CAAC;AAEX,uEAAuE;AACvE,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC;AAEzC,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG;IAC3B,QAAQ,EAAE,IAAI,IAAI,MAAM,SAAS,GAAG,IAAI,SAAS,WAAW,GACzD,CAAC,IAAI,CAAC,EAAE,SAAS,KAAK,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,GAC3C,CAAC,KAAK,CAAC,IAAI,GAAG,SAAS,EACvB,IAAI,CAAC,EAAE,IAAI,EACX,IAAI,CAAC,EAAE,SAAS,KACZ,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;CACnC,GAAG;IACH,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,SAAS,UAAU,EAC9C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,SAAS,KACZ,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAChC,KAAK,CAAC,MAAM,SAAS,UAAU,EAC/B,KAAK,CAAC,IAAI,GAAG,SAAS,EAEtB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,IAAI,EACX,IAAI,CAAC,EAAE,SAAS,KACZ,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,GACxB,aAAa,CAAC;AAkCf,eAAO,MAAM,WAAW,EAAE,iBAOzB,CAAC;AAUF;;;;GAIG;AACH,wBAAgB,UAAU,CACzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,WAAW,GAClB,QAAQ,CAiCV"}
+{"version":3,"file":"reply.d.ts","sourceRoot":"","sources":["../../src/reply/reply.ts"],"names":[],"mappings":"AAEA,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE5D,MAAM,WAAW,SAAS;IACzB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,qBAAa,KAAK,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM,EAAE,IAAI,GAAG,OAAO;IAChE;;;;OAIG;IACH,SAAiB,QAAQ,EAAE,IAAI,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,CAAC;gBAE9B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,SAAS;CAKxD;AAED,+CAA+C;AAC/C,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;CAUZ,CAAC;AAEX,uEAAuE;AACvE,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC;AAEzC,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG;IAC3B,QAAQ,EAAE,IAAI,IAAI,MAAM,SAAS,GAAG,IAAI,SAAS,WAAW,GACzD,CAAC,IAAI,CAAC,EAAE,SAAS,KAAK,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,GAC3C,CAAC,KAAK,CAAC,IAAI,GAAG,SAAS,EACvB,IAAI,CAAC,EAAE,IAAI,EACX,IAAI,CAAC,EAAE,SAAS,KACZ,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;CACnC,GAAG;IACH,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,SAAS,UAAU,EAC9C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,SAAS,KACZ,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAChC,KAAK,CAAC,MAAM,SAAS,UAAU,EAC/B,KAAK,CAAC,IAAI,GAAG,SAAS,EAEtB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,IAAI,EACX,IAAI,CAAC,EAAE,SAAS,KACZ,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,GACxB,aAAa,CAAC;AAkCf,eAAO,MAAM,WAAW,EAAE,iBAOzB,CAAC;AAUF;;;;GAIG;AACH,wBAAgB,UAAU,CACzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,WAAW,GAClB,QAAQ,CAiCV"}

package/dist/request/limit.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The request with its body bounded to `limit` bytes, for every reader:
+ * the body parsers, a hook, a handler reading `request.body` as a stream.
+ * A `Content-Length` over the limit fails the first read without reading a
+ * byte; otherwise the bytes are counted as they arrive, and the read fails
+ * with a `ContentTooLargeError` once they pass the limit, so a chunked
+ * upload is never buffered whole. A request without a body, or whose body
+ * a global hook has already read, is returned as it is.
+ */
+export declare function limitBody(request: Request, limit: number): Request;
+/** Whether `limit` is a byte count a route can be given. */
+export declare function checkLimit(limit: number, where: string): number;
+//# sourceMappingURL=limit.d.ts.map

package/dist/request/limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limit.d.ts","sourceRoot":"","sources":["../../src/request/limit.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAwBlE;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAO/D"}

package/dist/request/read.d.ts

@@ -1,4 +1,4 @@
-import type { ValidationIssue } from '../errors/errors';
+import { type ValidationIssue } from '../errors/errors';
 /**
  * The query string as an object. A key given once is a string, a key given
  * more than once an array of them, so `z.array(...)` reads `?tag=a&tag=b`;
@@ -25,7 +25,8 @@ export type ReadBody = {
 /**
  * The request body, read by its `content-type`: by a parser the app added,
  * else JSON, a form (an object of its fields, a field given more than once
- * an array), text, or the bytes.
+ * an array), text, or the bytes. A body past the route's `bodyLimit` throws
+ * a `ContentTooLargeError`, a custom parser's included.
  */
 export declare function readBody(request: Request, parsers?: readonly BodyParser[]): Promise<ReadBody>;
 //# sourceMappingURL=read.d.ts.map

package/dist/request/read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/request/read.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CASrE;AAED,0DAA0D;AAC1D,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIpE;AAED,wCAAwC;AACxC,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIpE;AAED,iEAAiE;AACjE,MAAM,WAAW,UAAU;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;CAC9C;AAaD,MAAM,MAAM,QAAQ,GACjB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;CAAE,CAAC;AAE3D;;;;GAIG;AACH,wBAAsB,QAAQ,CAC7B,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,SAAS,UAAU,EAAO,GACjC,OAAO,CAAC,QAAQ,CAAC,CAsDnB"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/request/read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE9E;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CASrE;AAED,0DAA0D;AAC1D,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIpE;AAED,wCAAwC;AACxC,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIpE;AAED,iEAAiE;AACjE,MAAM,WAAW,UAAU;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;CAC9C;AAaD,MAAM,MAAM,QAAQ,GACjB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;CAAE,CAAC;AAE3D;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC7B,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,SAAS,UAAU,EAAO,GACjC,OAAO,CAAC,QAAQ,CAAC,CAuDnB"}

package/dist/sse/async-iterable.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether a body is a stream of events: any async iterable but a
+ * `ReadableStream`, which is sent as bytes.
+ */
+export declare function isAsyncIterable(value: unknown): value is AsyncIterable<unknown>;
+//# sourceMappingURL=async-iterable.d.ts.map

package/dist/sse/async-iterable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-iterable.d.ts","sourceRoot":"","sources":["../../src/sse/async-iterable.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,OAAO,GACZ,KAAK,IAAI,aAAa,CAAC,OAAO,CAAC,CAOjC"}

package/dist/sse/event-stream.d.ts

@@ -4,28 +4,51 @@
  * The client reads the same values back as an async iterable.
  */
 import { type InferInput, type InferOutput, type StandardSchemaV1 } from '../schema/standard-schema';
+import { type EventSchemas, type NamedEventStreamSchema } from './named-events';
 /** A response schema whose body is a stream of events, each one checked by `item`. */
 export interface EventStreamSchema<Item extends StandardSchemaV1> extends StandardSchemaV1<AsyncIterable<InferInput<Item>>, AsyncIterable<InferOutput<Item>>> {
     readonly '~eventStream': Item;
 }
 /**
- * The schema of a reply that streams events: each value the handler yields
- * is checked by `item`, and sent as its output.
+ * The schema of a reply that streams events.
+ *
+ * Given one schema, each value the handler yields is checked by it and sent
+ * as its output, on `data:` lines alone:
  *
  * ```ts
  * app.get('/ticks', { response: { 200: eventStream(Tick) } }, ({ reply }) =>
  *   reply(200, (async function* () { yield { n: 1 }; })()));
  * ```
+ *
+ * Given a schema per event name, the handler yields `{ event, data, id?,
+ * retry? }`: only a declared name, with data its schema accepts. Each is
+ * sent with its `event:` line, and the client reads `{ event, data, id? }`:
+ *
+ * ```ts
+ * const Push = eventStream({ state: StateChange, ping: Ping });
+ * app.get('/push', { response: { 200: Push } }, ({ reply }) =>
+ *   reply(200, (async function* () { yield { event: 'ping', data: { interval: 30 } }; })()));
+ * ```
+ *
+ * An event name that is empty or holds a line break throws a `TypeError`.
  */
 export declare function eventStream<Item extends StandardSchemaV1>(item: Item): EventStreamSchema<Item>;
-export declare function isAsyncIterable(value: unknown): value is AsyncIterable<unknown>;
+export declare function eventStream<Events extends EventSchemas>(events: Events & Declarable<Events>): NamedEventStreamSchema<Events>;
+/**
+ * `unknown` for a map of events the stream can write, `never` for one with
+ * no event or an empty name: a compile error, as it is a `TypeError` at run
+ * time.
+ */
+type Declarable<Events> = [keyof Events] extends [never] ? never : '' extends keyof Events ? never : unknown;
 export declare function isEventStreamSchema(schema: StandardSchemaV1): schema is EventStreamSchema<StandardSchemaV1>;
 /** How often a comment keeps an idle stream open: Bun closes a silent one. */
 export declare const KEEP_ALIVE_MS = 8000;
 /**
- * The events of `values` as a `text/event-stream` body: each value as one
- * `data:` line of JSON, a comment while nothing is sent, and the iterator
- * closed when the client goes away.
+ * The events of `values` as a `text/event-stream` body: each value as
+ * `data:` lines of JSON, after its `event:`, `id:` and `retry:` lines on a
+ * named stream, a comment while nothing is sent, and the iterator closed
+ * when the client goes away.
  */
 export declare function toEventStream(values: AsyncIterable<unknown>, signal?: AbortSignal): ReadableStream<Uint8Array>;
+export {};
 //# sourceMappingURL=event-stream.d.ts.map

package/dist/sse/event-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-stream.d.ts","sourceRoot":"","sources":["../../src/sse/event-stream.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAEN,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,MAAM,2BAA2B,CAAC;AAEnC,sFAAsF;AACtF,MAAM,WAAW,iBAAiB,CAAC,IAAI,SAAS,gBAAgB,CAC/D,SAAQ,gBAAgB,CACvB,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,EAC/B,aAAa,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAChC;IACD,QAAQ,CAAC,cAAc,EAAE,IAAI,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,SAAS,gBAAgB,EACxD,IAAI,EAAE,IAAI,GACR,iBAAiB,CAAC,IAAI,CAAC,CAkBzB;AAqBD,wBAAgB,eAAe,CAC9B,KAAK,EAAE,OAAO,GACZ,KAAK,IAAI,aAAa,CAAC,OAAO,CAAC,CAOjC;AAED,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,gBAAgB,GACtB,MAAM,IAAI,iBAAiB,CAAC,gBAAgB,CAAC,CAE/C;AAED,8EAA8E;AAC9E,eAAO,MAAM,aAAa,OAAQ,CAAC;AAEnC;;;;GAIG;AACH,wBAAgB,aAAa,CAC5B,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAC9B,MAAM,CAAC,EAAE,WAAW,GAClB,cAAc,CAAC,UAAU,CAAC,CA2D5B"}
+{"version":3,"file":"event-stream.d.ts","sourceRoot":"","sources":["../../src/sse/event-stream.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAEN,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAE3B,MAAM,gBAAgB,CAAC;AAExB,sFAAsF;AACtF,MAAM,WAAW,iBAAiB,CAAC,IAAI,SAAS,gBAAgB,CAC/D,SAAQ,gBAAgB,CACvB,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,EAC/B,aAAa,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAChC;IACD,QAAQ,CAAC,cAAc,EAAE,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,IAAI,SAAS,gBAAgB,EACxD,IAAI,EAAE,IAAI,GACR,iBAAiB,CAAC,IAAI,CAAC,CAAC;AAC3B,wBAAgB,WAAW,CAAC,MAAM,SAAS,YAAY,EACtD,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,GACjC,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAqClC;;;;GAIG;AACH,KAAK,UAAU,CAAC,MAAM,IAAI,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,GACrD,KAAK,GACL,EAAE,SAAS,MAAM,MAAM,GACtB,KAAK,GACL,OAAO,CAAC;AAUZ,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,gBAAgB,GACtB,MAAM,IAAI,iBAAiB,CAAC,gBAAgB,CAAC,CAE/C;AAED,8EAA8E;AAC9E,eAAO,MAAM,aAAa,OAAQ,CAAC;AAEnC;;;;;GAKG;AACH,wBAAgB,aAAa,CAC5B,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAC9B,MAAM,CAAC,EAAE,WAAW,GAClB,cAAc,CAAC,UAAU,CAAC,CAmD5B"}

package/dist/sse/frame.d.ts

@@ -0,0 +1,35 @@
+/**
+ * One event of a `text/event-stream` body as it is written: its `event:`,
+ * `id:` and `retry:` fields, then its data as JSON on `data:` lines.
+ */
+import type { ValidationIssue } from '../errors/errors';
+/**
+ * An event with fields of its own, as a named stream's validator gives it
+ * to the writer. A plain value yielded by any other stream is sent as its
+ * `data` alone, so a `{ event }` object a handler yields without a named
+ * schema stays JSON.
+ */
+export declare class Frame {
+    readonly event: string;
+    readonly data: unknown;
+    readonly id: string | undefined;
+    readonly retry: number | undefined;
+    constructor(event: string, data: unknown, id: string | undefined, retry: number | undefined);
+}
+/**
+ * `value` as the text of one event: a `Frame`'s fields, then its data, each
+ * line of it on a `data:` line of its own, and the blank line ending it.
+ */
+export declare function frameText(value: unknown): string;
+/**
+ * The error of an event its schema refuses, each issue at its path, under
+ * the event's name on a named stream.
+ */
+export declare function mismatch(issues: readonly ValidationIssue[], name?: string): TypeError;
+/** Why `name` cannot be an event's name, or `undefined` when it can. */
+export declare function refuseName(name: string): string | undefined;
+/** Why `id` cannot be an event's id, or `undefined` when it can. */
+export declare function refuseId(id: unknown): string | undefined;
+/** Why `retry` cannot be an event's retry, or `undefined` when it can. */
+export declare function refuseRetry(retry: unknown): string | undefined;
+//# sourceMappingURL=frame.d.ts.map

package/dist/sse/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/sse/frame.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD;;;;;GAKG;AACH,qBAAa,KAAK;IACjB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;gBAGlC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,OAAO,EACb,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,KAAK,EAAE,MAAM,GAAG,SAAS;CAO1B;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYhD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CACvB,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,IAAI,CAAC,EAAE,MAAM,GACX,SAAS,CASX;AAKD,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM3D;AAED,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAOxD;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAM9D"}

package/dist/sse/named-events.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Server-sent events with names: `eventStream({ state: State, ping: Ping })`
+ * maps each event name to the schema of its data. The handler yields
+ * `{ event, data, id?, retry? }`, and the client reads `{ event, data, id? }`,
+ * a union discriminated by `event`.
+ */
+import { type InferInput, type InferOutput, type StandardSchemaV1 } from '../schema/standard-schema';
+import { Frame } from './frame';
+/** The schema of each event's data, by event name. */
+export type EventSchemas = Readonly<Record<string, StandardSchemaV1>>;
+/** The schemas by name of `Of`: itself, or those of the named stream it is. */
+type SchemasOf<Of> = Of extends {
+    readonly '~events': infer Events;
+} ? Events : Of;
+/**
+ * What a handler yields on a named stream: one of the declared events, with
+ * data its schema accepts. `id` sets the client's last event id; `retry`, in
+ * milliseconds, how long an `EventSource` waits before it reconnects. `Of`
+ * is the stream's schema, `EventInput<typeof Push>`, or its schemas by name.
+ */
+export type EventInput<Of extends EventSchemas | AnyNamedEventStream> = {
+    [Name in keyof SchemasOf<Of> & string]: {
+        readonly event: Name;
+        readonly data: InferInput<Extract<SchemasOf<Of>[Name], StandardSchemaV1>>;
+        readonly id?: string;
+        readonly retry?: number;
+    };
+}[keyof SchemasOf<Of> & string];
+/** What the client reads of a named stream: the event, its data as its schema gives it back, and its id when it had one. */
+export type EventOutput<Of extends EventSchemas | AnyNamedEventStream> = {
+    [Name in keyof SchemasOf<Of> & string]: {
+        readonly event: Name;
+        readonly data: InferOutput<Extract<SchemasOf<Of>[Name], StandardSchemaV1>>;
+        readonly id?: string;
+    };
+}[keyof SchemasOf<Of> & string];
+/** Any named stream, whatever its events. */
+interface AnyNamedEventStream {
+    readonly '~events': EventSchemas;
+}
+/** The fields an event may carry besides its name and data. */
+export interface EventFields {
+    readonly id?: string;
+    readonly retry?: number;
+}
+/** A response schema whose body is a stream of named events, each one's data checked by the schema of its name. */
+export interface NamedEventStreamSchema<Events extends EventSchemas> extends StandardSchemaV1<AsyncIterable<EventInput<Events>>, AsyncIterable<EventOutput<Events>>> {
+    readonly '~events': Events;
+    /**
+     * One event to yield, typed by the schema of its name: its data is
+     * checked, and its literals kept, where a plain `{ event, data }` object
+     * yielded from a generator would widen `event` to `string`.
+     *
+     * ```ts
+     * yield Push.event('ping', { interval: 30 });
+     * ```
+     */
+    event<Name extends keyof Events & string>(event: Name, data: InferInput<Events[Name]>, fields?: EventFields): EventInput<Pick<Events, Name>>;
+}
+export declare function namedEventStream<Events extends EventSchemas>(events: Events): NamedEventStreamSchema<Events>;
+export declare function isNamedEventStreamSchema(schema: StandardSchemaV1): schema is NamedEventStreamSchema<EventSchemas>;
+/**
+ * Each value of `values` as a `Frame`: its name declared, its id and retry
+ * safe to write, and, when `validate`, its data checked by its schema. The
+ * fields are checked even when responses are not validated: a line break in
+ * one would write a frame the handler never yielded.
+ */
+export declare function toFrames(events: EventSchemas, values: AsyncIterable<unknown>, validate: boolean): AsyncGenerator<Frame>;
+export {};
+//# sourceMappingURL=named-events.d.ts.map

package/dist/sse/named-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"named-events.d.ts","sourceRoot":"","sources":["../../src/sse/named-events.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -9,9 +9,9 @@ a realistic example for each.
 | Page | Read it when |
 | --- | --- |
 | [Getting started](guide/getting-started.md) | writing a first app, and testing it without a server |
-| [Routes and schemas](guide/routes.md) | declaring paths, validating params, query, headers, cookies or a body, or reading a 400 |
-| [Replies](guide/replies.md) | answering with a status, a file, a header, a cookie or a redirect, or turning an error into a response |
-| [Hooks](guide/hooks.md) | authenticating, adding to the context, timing or tracing a request, or editing every response |
+| [Routes and schemas](guide/routes.md) | declaring paths, validating params, query, headers, cookies or a body, capping a body's size, or reading a 400 or a 413 |
+| [Replies](guide/replies.md) | answering with a status, a file, a header, a cookie, a redirect or an RFC 9457 problem, or turning an error into a response |
+| [Hooks](guide/hooks.md) | authenticating, adding to the context, answering a refused request in your own format, timing or tracing a request, or editing every response |
 | [Groups and plugins](guide/groups-and-plugins.md) | scoping hooks to some routes, splitting the app across files, or reading what `use` mounts |
 | [Writing a plugin](guide/writing-a-plugin.md) | writing a plugin: an app, a `Plugin` function, or a `definePlugin` that reads what an earlier plugin added |
 | [Static files](guide/static-files.md) | serving a directory, one file, a single-page app, or a Bun HTML bundle |

package/docs/guide/groups-and-plugins.md

@@ -73,9 +73,12 @@ A plugin is either an **app** or a **function**.
 
 | | Adds | Type of the app after `use` |
 | --- | --- | --- |
-| an app, `use(otherApp)` | routes, route hooks, context, typed replies, global hooks | grows: its routes and context are added |
+| an app, `use(otherApp)` | routes, route hooks, context, typed replies, global hooks, its [`bodyLimit()`](routes.md#body-size-bodylimit) | grows: its routes and context are added |
 | a function, `use(plugin)` | global hooks | unchanged |
 
+The app's own `bodyLimit()` does not reach an app plugin's routes: they
+keep the limit they were declared with ([Routes](routes.md#body-size-bodylimit)).
+
 ### An app as a plugin
 
 ```ts
@@ -88,6 +91,10 @@ use(plugin: Alxia<PluginCtx, PluginRoutes, PluginPrefix, PluginShortcuts>): Alxi
 - Its **route hooks** then apply to the routes declared on this app after
   `use`: an `auth` plugin can be a `derive` and nothing else.
 - Its **`onError` hooks** are tried before this app's, for its own routes.
+- Its **`onRefusal` hook** answers its own routes' refused requests. Its
+  routes without one take this app's, declared before `use`. The plugin's
+  hook then replaces this app's for the routes declared after `use`
+  ([Hooks](hooks.md#onrefusal)).
 - Its **global hooks**, body parsers and [pages](static-files.md#bun-html-bundles)
   become this app's.
 

package/docs/guide/hooks.md

@@ -23,7 +23,7 @@ const app = alxia()
 
 | | Applies to | Declared with |
 | --- | --- | --- |
-| route hooks | the routes declared **after** them, in the same app or [group](groups-and-plugins.md#groups) | `decorate`, `derive`, `wrap`, `onError` |
+| route hooks | the routes declared **after** them, in the same app or [group](groups-and-plugins.md#groups) | `decorate`, `derive`, `wrap`, `onError`, `onRefusal` |
 | global hooks | every request to the app, wherever they are declared | `around`, `onRequest`, `onResponse`, `onStart`, `onStop`, `parser` |
 
 The order of the chain is the order of the request, at runtime and in the
@@ -37,12 +37,17 @@ around (first declared outermost)
 └─ onRequest hooks           ← a Response here is sent as it is
    └─ routing                ← 404, 405, 426
       └─ route hooks, in order: derive / decorate / wrap
-         └─ validation       ← 400
+         └─ validation       ← 400, or the onRefusal hook's reply
             └─ handler
          onError hooks       ← for what any of the above threw
    onResponse hooks          ← every response, 404s included
 ```
 
+A body read past its route's `bodyLimit` is a `body_limit` refusal,
+answered by [`onRefusal`](#onrefusal) or with a 413, wherever it is read: a
+route hook, validation or the handler ([Routes](routes.md#body-size-bodylimit)). A global hook reads it
+unbounded, and the route's limit is then skipped.
+
 Route hooks run **before validation**: they read `pathParams`, the path
 parameters as they arrived, not `params`.
 
@@ -152,6 +157,126 @@ const app = alxia()
 The context is `Partial<Ctx>`: the error may have been thrown before a
 `derive` added its part.
 
+## `onRefusal`
+
+```ts
+onRefusal<Result extends Reply<ClientErrorStatus, any> | undefined | void>(
+	hook: (refusal: Refusal, ctx: BaseContext & Ctx) => MaybePromise<Result>,
+): Alxia<…>
+onRefusal<Responses extends RefusalResponses, Result extends DeclaredReply<Responses> | undefined | void>(
+	schema: { response: Responses; contentType?: string },
+	hook: (refusal: Refusal, ctx: Omit<BaseContext, 'reply'> & Ctx & { reply: TypedReplyFunction<Responses> }) => MaybePromise<Result>,
+): Alxia<…>
+```
+
+Answers a request that a route declared after it refuses before its
+handler runs. There are two kinds of refusal, each with its default:
+
+| `kind` | When | Default |
+| --- | --- | --- |
+| `validation` | the route's schemas refuse the request | `400 { "error": "validation", "issues": […] }` ([The 400](routes.md#the-400)) |
+| `body_limit` | the body is larger than the route's [`bodyLimit`](routes.md#body-size-bodylimit) | `413 { "error": "content_too_large", "limit": … }` |
+
+The hook reads the refusal and the context. It returns a reply with a 4xx
+status, or nothing to send that kind's default.
+
+```ts
+interface ValidationRefusal {
+	readonly kind: 'validation';
+	readonly part: 'params' | 'query' | 'headers' | 'cookies' | 'body'; // the first that failed
+	readonly issues: readonly ValidationIssue[];                         // every one, each with its target
+}
+interface BodyLimitRefusal {
+	readonly kind: 'body_limit';
+	readonly limit: number; // the route's limit, in bytes
+}
+type Refusal = ValidationRefusal | BodyLimitRefusal; // told apart by `kind`
+```
+
+Only a `validation` refusal has a `part` and `issues`: check `kind` before
+reading them. A kind added later reaches every hook too, and a hook that
+returns nothing for it sends its default.
+
+An API whose errors are RFC 9457 problems, as JMAP's are, answers them
+with [`problem`](replies.md#problem-details-problem):
+
+```ts
+import { alxia, problem, type Refusal } from '@alxia/core';
+import { z } from 'zod';
+
+const jmapProblem = (refusal: Refusal) =>
+	refusal.kind === 'body_limit'
+		? problem({ type: 'urn:ietf:params:jmap:error:limit', status: 413, limit: 'maxSizeRequest' })
+		: problem({
+				type: refusal.issues.some((issue) => issue.code === 'invalid_json')
+					? 'urn:ietf:params:jmap:error:notJSON'
+					: 'urn:ietf:params:jmap:error:notRequest',
+				status: 400,
+				detail: `the ${refusal.part} is invalid`,
+			});
+
+const app = alxia()
+	.onRefusal(jmapProblem)
+	.post('/jmap', { body: z.object({ using: z.array(z.string()) }), bodyLimit: 10_000_000 }, ({ reply }) =>
+		reply(200, { methodResponses: [] }),
+	)
+	.get('/download/:blobId', { params: z.object({ blobId: z.string().min(1) }) }, ({ reply }) =>
+		reply(200, 'blob'),
+	);
+```
+
+A body that is not JSON gets `notJSON`, and a body or a path parameter its
+schema refuses gets `notRequest`. A body past 10 MB gets JMAP's `limit`
+problem, whether its `Content-Length` says so or the bytes counted do. It
+is sent with 413 here, the app's choice; RFC 8620's own example of that
+problem answers 400. Each is sent as
+`application/problem+json`, with its `detail` naming the part.
+
+**Order is meaning.** The last `onRefusal` declared before a route is the
+one in force. A route declared before any keeps the default, and a
+[group](groups-and-plugins.md#groups)'s hook stays inside the group. A
+plugin given to `use` keeps its own hook for its routes. Its routes without
+one take the hook of the app using it, and the plugin's hook then applies to
+the routes declared after `use`, as its `derive`s do.
+
+**Typed.** The hook's reply replaces the default 400 in the type of every
+route after it that validates part of its request, so
+[`@alxia/client`](https://www.npmjs.com/package/@alxia/client) reads the
+problem. A route under a `bodyLimit` may be refused too, and its type
+gains the hook's replies in place of the default 413. A route that neither
+validates nor has a `bodyLimit` is never refused, and its type gains
+nothing. A hook that may return nothing keeps the default of each kind the
+route may refuse with — the 400, the 413 — in the type beside its own
+reply. A status other than 400 replaces it: a hook that answers 422 makes
+the route's outcomes 422 and no 400. The hook's type does not say which
+reply answers which kind, so every reply it may return is in the type of
+every route it may refuse: the JMAP hook above puts its 413 in the type of
+`/download/:blobId` too, though only `/jmap` has a limit.
+
+**With schemas.** Given `{ response, contentType? }` first, the hook's
+`reply` is typed by those schemas, as a route's is. Its reply is checked by
+the schema of its status and sent as that schema's output, and a reply the
+schema refuses is a 500, as a handler's is ([`validateResponses`](replies.md#validateresponses)).
+`contentType` is set on the reply unless it sets its own.
+[`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi) documents
+each declared status under that content type. Without schemas it documents
+a `4XX` whose body it does not know.
+
+```ts
+const Problem = z.object({ type: z.string(), status: z.literal(400), detail: z.string() });
+
+const documented = alxia()
+	.onRefusal({ response: { 400: Problem }, contentType: 'application/problem+json' }, (refusal, { reply }) =>
+		reply(400, { type: 'urn:ietf:params:jmap:error:notRequest', status: 400, detail: refusal.kind }),
+	)
+	.post('/jmap', { body: z.object({ using: z.array(z.string()) }) }, ({ reply }) => reply(200, 'ok'));
+```
+
+A hook that throws reaches the route's `onError` hooks, as a handler's
+error does. A socket route's upgrade is refused through the same hook. A
+message the socket refuses is answered on the socket, as before
+([WebSockets](websockets.md)).
+
 ## Global hooks
 
 ### `around`
@@ -264,7 +389,7 @@ interface RequestContext {               // around, onRequest, onResponse
 	readonly error: unknown;                          // once a route has failed
 }
 
-interface BaseContext extends RequestContext {   // derive, wrap, onError, handlers
+interface BaseContext extends RequestContext {   // derive, wrap, onError, onRefusal, handlers
 	readonly route: string;                          // as declared: /users/:id
 	readonly pathParams: Readonly<Record<string, string>>;
 	readonly set: ResponseSettings;                  // { headers: Headers; cookies: Bun.CookieMap }

package/docs/guide/replies.md

@@ -258,11 +258,17 @@ const app = alxia()
 ```ts
 class HttpError<Status extends number = number, Body = unknown> extends Error {
 	constructor(status: Status, body: Body, message?: string);
+	readonly name: string; // 'HttpError', or a subclass's own
 	readonly status: Status;
 	readonly body: Body;
 }
 ```
 
+Core throws one subclass of its own, `ContentTooLargeError`, for a body past
+its route's `bodyLimit` ([Routes](routes.md#body-size-bodylimit)). The route
+answers it as a refusal, through [`onRefusal`](hooks.md#onrefusal), before
+any `onError` hook. Test for it with `instanceof`, not by `name`.
+
 An `onError` reply is added to the type of the routes after it. A thrown
 `HttpError` is not: the client reads it as a status the route never
 declared.
@@ -270,6 +276,40 @@ declared.
 Every route's type includes `500 { error: 'internal' }`
 (`InternalErrorBody`), so a client always handles it.
 
+## Problem details: `problem`
+
+`problem(details, init?)` is a reply whose body is a problem as RFC 9457
+(which obsoletes RFC 7807) defines it. Its status is the problem's
+`status`, and its `content-type` is `application/problem+json` unless
+`init` sets one. Every other member is an extension, kept as given and in
+the body's type:
+
+```ts
+import { alxia, problem } from '@alxia/core';
+
+const app = alxia().post('/upload', ({ request }) =>
+	Number(request.headers.get('content-length')) > 50_000_000
+		? problem({ type: 'urn:ietf:params:jmap:error:limit', status: 413, limit: 'maxSizeRequest' })
+		: problem({ type: 'about:blank', status: 501, title: 'Not Implemented' }),
+);
+// the client reads 413 { type: 'urn:ietf:params:jmap:error:limit'; status: 413; limit: 'maxSizeRequest' }
+```
+
+```ts
+interface ProblemDetails<Status extends ClientErrorStatus | ServerErrorStatus> {
+	readonly type?: string;     // a URI; absent, it is about:blank
+	readonly title?: string;
+	readonly status: Status;    // the response's status
+	readonly detail?: string;
+	readonly instance?: string;
+}
+```
+
+On a route with `response` schemas, a problem is a reply like any other:
+its status must be declared and its body accepted by that status's schema.
+[`onRefusal`](hooks.md#onrefusal) answers a refused request with one.
+`@alxia/client` reads `application/problem+json` as JSON.
+
 ## Types
 
 ```ts