@dunx/http 3.6.0 → 3.8.0

package/README.md

@@ -62,6 +62,7 @@ The guide is canonical for every row; this table is the index.
 | Typed input             | `body`, `query`, `params` over Standard Schema              | [Validation](../../docs/guide/06-validation.md)                   |
 | Middleware and guards   | One extension point, `@UseGuards`, `@Roles`, `@Public`      | [Middleware and guards](../../docs/guide/08-middleware-and-guards.md) |
 | WebSocket gateways      | `@Gateway`, handlers, `PubSub`, multi-node relay            | [WebSockets](../../docs/guide/09-websockets.md)                   |
+| Server-sent events      | `@Sse`, `SseStream`, framing, heartbeats, `Last-Event-ID`   | [Controllers](../../docs/guide/05-controllers.md)                 |
 | Request logging         | One structured entry per request, on by default             | [Logging](../../docs/guide/13-logging.md)                         |
 | Trace context           | W3C `traceparent` adopted and propagated, on by default     | [Logging](../../docs/guide/13-logging.md)                         |
 | Metrics                 | Per-route counts and timings, off by default                | [Metrics](../../docs/guide/23-metrics.md)                         |
@@ -70,6 +71,7 @@ The guide is canonical for every row; this table is the index.
 | Outbound resilience     | `HttpRetryClassifier`: which statuses retry, and `Retry-After` | [Resilience](../../docs/guide/25-resilience.md)                |
 | Static files            | `Bun.file` behind a mount, with a cache policy              | [Deployment](../../docs/guide/20-deployment.md)                   |
 | Compression             | zstd and gzip on Bun's own compressors                      | [Deployment](../../docs/guide/20-deployment.md)                   |
+| RPC                     | protobuf over Connect and gRPC-Web, as middleware           | [RPC](../../docs/guide/27-rpc.md)                                 |
 
 ## Subpaths
 
@@ -77,6 +79,7 @@ The guide is canonical for every row; this table is the index.
 | ---------------------- | ----------------------------------------------------------------- |
 | `@dunx/http`           | Everything above                                                  |
 | `@dunx/http/client`    | The outbound half: `HttpService`, retry with backoff, `HttpModule` |
+| `@dunx/http/connect`   | protobuf services over Connect and gRPC-Web, mounted as middleware |
 | `@dunx/http/internal`  | The framework's own plumbing. No stability promise                |
 
 `@dunx/http/internal` holds route-table construction, the middleware fold, the
@@ -101,6 +104,12 @@ from, and it may change in any release.
   ns. W3C Trace Context is the only correlation id; there is no second one.
 - `metrics: true` adds per-route counts and a nanosecond histogram at +35.2 ns a
   request, folded into the `.then` request logging already allocates.
+- `@dunx/http/connect` serves Connect and gRPC-Web, not native gRPC. gRPC carries
+  `grpc-status` in an HTTP trailer and `Bun.serve` sends no trailers, so a request
+  with `content-type: application/grpc` gets a 415 that says so.
+  `@connectrpc/connect` and `@bufbuild/protobuf` are optional peers, and the
+  `.proto` toolchain stays yours. `ThrottleGuard` covers an RPC: it skips an
+  unmatched path nobody claims, and an RPC path is claimed.
 
 ## License
 

package/dist/chunk-08k9vq31.js

@@ -0,0 +1,94 @@
+// @bun
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __name = (target, name) => {
+  Object.defineProperty(target, "name", {
+    value: name,
+    enumerable: false,
+    configurable: true
+  });
+  return target;
+};
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => (key in obj) ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateIn = (member, obj) => Object(obj) !== obj ? __typeError('Cannot use the "in" operator on this value') : member.has(obj);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+var __decoratorStart = (base) => [, , , __create(base?.[__knownSymbol("metadata")] ?? null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== undefined && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({
+  kind: __decoratorStrings[kind],
+  name,
+  metadata,
+  addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null))
+});
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length;i < n; i++)
+    flags & 1 ? fns[i].call(self) : value = fns[i].call(self, value);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var fn, it, done, ctx, access, k = flags & 7, s = !!(flags & 8), p = !!(flags & 16);
+  var j = k > 3 ? array.length + 1 : k ? s ? 1 : 2 : 0, key = __decoratorStrings[k + 5];
+  var initializers = k > 3 && (array[j - 1] = []), extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (!p && !s && (target = target.prototype), k < 5 && (k > 3 || !p) && __getOwnPropDesc(k < 4 ? target : {
+    get [name]() {
+      return __privateGet(this, extra);
+    },
+    set [name](x) {
+      __privateSet(this, extra, x);
+    }
+  }, name));
+  k ? p && k < 4 && __name(extra, (k > 2 ? "set " : k > 1 ? "get " : "") + name) : __name(target, name);
+  for (var i = decorators.length - 1;i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    if (k) {
+      ctx.static = s, ctx.private = p, access = ctx.access = { has: p ? (x) => __privateIn(target, x) : (x) => (name in x) };
+      if (k ^ 3)
+        access.get = p ? (x) => (k ^ 1 ? __privateGet : __privateMethod)(x, target, k ^ 4 ? extra : desc.get) : (x) => x[name];
+      if (k > 2)
+        access.set = p ? (x, y) => __privateSet(x, target, y, k ^ 4 ? extra : desc.set) : (x, y) => x[name] = y;
+    }
+    it = (0, decorators[i])(k ? k < 4 ? p ? extra : desc[key] : k > 4 ? undefined : { get: desc.get, set: desc.set } : target, ctx);
+    done._ = 1;
+    if (k ^ 4 || it === undefined)
+      __expectFn(it) && (k > 4 ? initializers.unshift(it) : k ? p ? extra = it : desc[key] = it : target = it);
+    else if (typeof it !== "object" || it === null)
+      __typeError("Object expected");
+    else
+      __expectFn(fn = it.get) && (desc.get = fn), __expectFn(fn = it.set) && (desc.set = fn), __expectFn(fn = it.init) && initializers.unshift(fn);
+  }
+  return k || __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+
+// src/route/claims.ts
+import { AppError } from "@dunx/core";
+
+class PathClaims {
+  #owners = new Map;
+  #noun;
+  #remedy;
+  constructor(noun, remedy) {
+    this.#noun = noun;
+    this.#remedy = remedy;
+  }
+  claim(key, owner) {
+    const existing = this.#owners.get(key);
+    if (existing !== undefined) {
+      throw new AppError(`${this.#noun} collision: ${key} is declared by ${existing} and by ` + `${owner}. ${this.#remedy}`);
+    }
+    this.#owners.set(key, owner);
+  }
+}
+Object.defineProperty(PathClaims, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "noun: string" }, { unresolved: "remedy: string" }] });
+
+export { __privateGet, __privateAdd, __decoratorStart, __decoratorMetadata, __runInitializers, __decorateElement, PathClaims };

package/dist/{chunk-p9hdmkm6.js → chunk-1jt27yka.js}

@@ -40,6 +40,8 @@ var ROLES2 = metaKey2("roles");
 var PUBLIC2 = metaKey2("public");
 var HIDDEN2 = metaKey2("hidden");
 var UNMATCHED2 = metaKey2("unmatched");
+var STREAMS2 = metaKey2("streams");
+var REQUEST_SERVER = metaKey2("request-server");
 var Roles2 = (...roles) => meta2(ROLES2, roles);
 var Public2 = () => meta2(PUBLIC2, true);
 var ApiHidden2 = () => meta2(HIDDEN2, true);
@@ -90,6 +92,11 @@ var discoverRoutes2 = (instance) => {
 };
 
 // src/route/prefix.ts
+var normalizePrefix = (path) => {
+  const trimmed = path.split("/").filter(Boolean).join("/");
+  return trimmed === "" ? "/" : `/${trimmed}`;
+};
+
 class RoutePrefix2 {
   #value = "";
   get value() {
@@ -103,86 +110,4 @@ class RoutePrefix2 {
   }
 }
 
-// src/ws/marker.ts
-var HANDLER = Symbol.for("dunx.ws.handler");
-var GATEWAY = Symbol.for("dunx.ws.gateway");
-var HandlerKind = Object.freeze({
-  UPGRADE: "upgrade",
-  OPEN: "open",
-  MESSAGE: "message",
-  CLOSE: "close",
-  DRAIN: "drain",
-  PING: "ping",
-  PONG: "pong"
-});
-var markHandler = (target, meta) => {
-  Object.defineProperty(target, HANDLER, { value: meta, configurable: true });
-};
-var handlerMetaOf = (value) => typeof value === "function" ? value[HANDLER] : undefined;
-var markGateway = (target, path) => {
-  Object.defineProperty(target, GATEWAY, { value: path, configurable: true });
-};
-var gatewayPathOf = (target) => target[GATEWAY] ?? "/";
-var isGateway2 = (target) => target[GATEWAY] !== undefined;
-
-// src/server/context.ts
-var EMPTY = new Map;
-var buildContext2 = (route) => {
-  const record = route.meta ?? EMPTY;
-  return Object.freeze({
-    controller: route.controller,
-    handler: route.handlerName,
-    method: route.method,
-    path: route.path,
-    parsesBody: route.options?.body !== undefined,
-    get: (key) => record.get(key.id)
-  });
-};
-
-// src/ws/discover.ts
-import {
-  AppError,
-  classOf,
-  markedMethods as markedMethods2
-} from "@dunx/core";
-var normalizePath = (path) => {
-  const joined = `/${path}`.replace(/\/{2,}/g, "/");
-  return joined.length > 1 ? joined.replace(/\/$/, "") : "/";
-};
-var eachHandler = (start) => markedMethods2(start, handlerMetaOf);
-var discoverGateway = (instance) => {
-  const klass = instance.constructor;
-  const members = instance;
-  return {
-    name: klass.name,
-    path: normalizePath(gatewayPathOf(klass)),
-    handlers: eachHandler(Object.getPrototypeOf(instance)).map(({ name, meta }) => ({
-      kind: meta.kind,
-      event: meta.event,
-      method: name,
-      invoke: members[name].bind(instance)
-    }))
-  };
-};
-var findHandlerMethod = (ctor) => eachHandler(ctor.prototype)[0]?.name;
-var discoverGateways = (modules, resolve) => {
-  const discovered = [];
-  for (const module of modules) {
-    for (const entry of module.options.providers ?? []) {
-      const candidate = classOf(entry);
-      if (!candidate)
-        continue;
-      if (isGateway2(candidate.ctor)) {
-        discovered.push(discoverGateway(resolve(candidate.token)));
-        continue;
-      }
-      const orphan = findHandlerMethod(candidate.ctor);
-      if (orphan !== undefined) {
-        throw new AppError(`${candidate.ctor.name}.${orphan}() is a websocket handler, but ` + `${candidate.ctor.name} is not a gateway. Decorate the class with ` + "@Gateway(path), or drop the handler decorator.");
-      }
-    }
-  }
-  return discovered;
-};
-
-export { defaultStatusFor2, markRoute, markController, metaKey2, meta2, ROLES2, PUBLIC2, HIDDEN2, UNMATCHED2, Roles2, Public2, ApiHidden2, UseGuards2, metaOf2, mergeMeta2, joinPath2, discoverRoutes2, RoutePrefix2, HandlerKind, markHandler, markGateway, isGateway2, discoverGateway, discoverGateways, buildContext2 };
+export { defaultStatusFor2, markRoute, markController, metaKey2, meta2, ROLES2, PUBLIC2, HIDDEN2, UNMATCHED2, STREAMS2, REQUEST_SERVER, Roles2, Public2, ApiHidden2, UseGuards2, metaOf2, mergeMeta2, joinPath2, discoverRoutes2, normalizePrefix, RoutePrefix2 };

package/dist/chunk-3eecdh6d.js

@@ -0,0 +1,160 @@
+// @bun
+import {
+  normalizePrefix
+} from "./chunk-1jt27yka.js";
+
+// src/ws/marker.ts
+var HANDLER = Symbol.for("dunx.ws.handler");
+var GATEWAY = Symbol.for("dunx.ws.gateway");
+var HandlerKind = Object.freeze({
+  UPGRADE: "upgrade",
+  OPEN: "open",
+  MESSAGE: "message",
+  CLOSE: "close",
+  DRAIN: "drain",
+  PING: "ping",
+  PONG: "pong"
+});
+var markHandler = (target, meta) => {
+  Object.defineProperty(target, HANDLER, { value: meta, configurable: true });
+};
+var handlerMetaOf = (value) => typeof value === "function" ? value[HANDLER] : undefined;
+var markGateway = (target, path) => {
+  Object.defineProperty(target, GATEWAY, { value: path, configurable: true });
+};
+var gatewayPathOf = (target) => target[GATEWAY] ?? "/";
+var isGateway2 = (target) => target[GATEWAY] !== undefined;
+
+// src/server/context.ts
+var EMPTY = new Map;
+var buildContext2 = (route) => {
+  const record = route.meta ?? EMPTY;
+  return Object.freeze({
+    controller: route.controller,
+    handler: route.handlerName,
+    method: route.method,
+    path: route.path,
+    parsesBody: route.options?.body !== undefined,
+    get: (key) => record.get(key.id)
+  });
+};
+
+// src/static/options.ts
+class StaticOptions2 {
+  root;
+  path;
+  maxAge;
+  immutable;
+  constructor(init) {
+    this.root = init.root;
+    this.path = normalizePrefix(init.path ?? "/");
+    this.maxAge = init.maxAge ?? 60;
+    this.immutable = init.immutable ?? (() => false);
+  }
+}
+Object.defineProperty(StaticOptions2, Symbol.for("dunx.deps"), { value: () => [{ unresolved: "init: StaticOptionsInit" }] });
+
+// src/static/files.ts
+import { join, normalize, resolve } from "path";
+var IMMUTABLE_CACHE_CONTROL2 = "public, max-age=31536000, immutable";
+
+class StaticFiles2 {
+  #options;
+  #root;
+  #prefix;
+  constructor(options) {
+    this.#options = options;
+    this.#root = resolve(options.root);
+    this.#prefix = options.path === "/" ? "/" : `${options.path}/`;
+  }
+  resolvePath(pathname) {
+    const relative = pathname.startsWith(this.#prefix) ? pathname.slice(this.#prefix.length) : pathname.slice(this.#options.path.length);
+    let decoded;
+    try {
+      decoded = decodeURIComponent(relative);
+    } catch {
+      return;
+    }
+    if (decoded.includes("\x00"))
+      return;
+    const candidate = resolve(join(this.#root, normalize(decoded)));
+    if (candidate !== this.#root && !candidate.startsWith(`${this.#root}/`)) {
+      return;
+    }
+    return candidate;
+  }
+  #cacheControl(pathname) {
+    const { immutable, maxAge } = this.#options;
+    return immutable(pathname) ? IMMUTABLE_CACHE_CONTROL2 : `public, max-age=${maxAge}`;
+  }
+  async handle(req, _ctx, next) {
+    const { pathname } = new URL(req.url);
+    if (pathname !== this.#options.path && !pathname.startsWith(this.#prefix)) {
+      return next();
+    }
+    if (req.method !== "GET" && req.method !== "HEAD")
+      return next();
+    const path = this.resolvePath(pathname);
+    if (path === undefined)
+      return next();
+    const file = Bun.file(path);
+    if (!await file.exists())
+      return next();
+    return new Response(file, {
+      headers: {
+        "cache-control": this.#cacheControl(pathname),
+        ...file.type === "" ? { "content-type": "application/octet-stream" } : {},
+        "x-content-type-options": "nosniff"
+      }
+    });
+  }
+}
+Object.defineProperty(StaticFiles2, Symbol.for("dunx.deps"), { value: () => [StaticOptions2] });
+
+// src/ws/discover.ts
+import {
+  AppError,
+  classOf,
+  markedMethods
+} from "@dunx/core";
+var normalizePath = (path) => {
+  const joined = `/${path}`.replace(/\/{2,}/g, "/");
+  return joined.length > 1 ? joined.replace(/\/$/, "") : "/";
+};
+var eachHandler = (start) => markedMethods(start, handlerMetaOf);
+var discoverGateway = (instance) => {
+  const klass = instance.constructor;
+  const members = instance;
+  return {
+    name: klass.name,
+    path: normalizePath(gatewayPathOf(klass)),
+    handlers: eachHandler(Object.getPrototypeOf(instance)).map(({ name, meta }) => ({
+      kind: meta.kind,
+      event: meta.event,
+      method: name,
+      invoke: members[name].bind(instance)
+    }))
+  };
+};
+var findHandlerMethod = (ctor) => eachHandler(ctor.prototype)[0]?.name;
+var discoverGateways = (modules, resolve) => {
+  const discovered = [];
+  for (const module of modules) {
+    for (const entry of module.options.providers ?? []) {
+      const candidate = classOf(entry);
+      if (!candidate)
+        continue;
+      if (isGateway2(candidate.ctor)) {
+        discovered.push(discoverGateway(resolve(candidate.token)));
+        continue;
+      }
+      const orphan = findHandlerMethod(candidate.ctor);
+      if (orphan !== undefined) {
+        throw new AppError(`${candidate.ctor.name}.${orphan}() is a websocket handler, but ` + `${candidate.ctor.name} is not a gateway. Decorate the class with ` + "@Gateway(path), or drop the handler decorator.");
+      }
+    }
+  }
+  return discovered;
+};
+
+export { HandlerKind, markHandler, markGateway, isGateway2, discoverGateway, discoverGateways, buildContext2, StaticOptions2, IMMUTABLE_CACHE_CONTROL2, StaticFiles2 };

package/dist/chunk-cx4btdwe.js

@@ -0,0 +1,56 @@
+// @bun
+// src/server/trace-context.ts
+import {
+  DEFAULT_TRACE_FLAGS,
+  formatTraceparent,
+  isSampled,
+  mintSpanId,
+  mintTraceId,
+  parseTraceparent,
+  TRACEPARENT_HEADER as TRACEPARENT_HEADER2,
+  TRACESTATE_HEADER as TRACESTATE_HEADER2
+} from "@dunx/core";
+var TRACERESPONSE_HEADER2 = "traceresponse";
+var TRACE = Symbol.for("dunx.http.trace");
+var EXPOSE = Symbol.for("dunx.http.trace.expose");
+
+class TraceContext2 {
+  static adopt(req, expose = true) {
+    const inbound = parseTraceparent(req.headers.get(TRACEPARENT_HEADER2));
+    const state = req.headers.get(TRACESTATE_HEADER2);
+    const trace = inbound === undefined ? {
+      traceId: mintTraceId(),
+      spanId: mintSpanId(),
+      flags: DEFAULT_TRACE_FLAGS
+    } : {
+      traceId: inbound.traceId,
+      spanId: mintSpanId(),
+      parentSpanId: inbound.spanId,
+      flags: inbound.flags,
+      ...state === null ? {} : { state }
+    };
+    req[TRACE] = trace;
+    if (expose)
+      req[EXPOSE] = true;
+    return trace;
+  }
+  static of(req) {
+    return req[TRACE];
+  }
+  static header(trace) {
+    return formatTraceparent(trace);
+  }
+  static stamp(response, req) {
+    const traced = req;
+    const trace = traced[TRACE];
+    if (trace !== undefined && traced[EXPOSE] === true) {
+      response.headers.set(TRACERESPONSE_HEADER2, TraceContext2.header(trace));
+    }
+    return response;
+  }
+  static sampled(trace) {
+    return isSampled(trace);
+  }
+}
+
+export { TRACEPARENT_HEADER2, TRACESTATE_HEADER2, TRACERESPONSE_HEADER2, TraceContext2 };

package/dist/client/service.d.ts

@@ -1,6 +1,7 @@
 import { Logger, RequestContext } from '@dunx/core';
 import { UrlHelper, type ParamsType } from '@arkv/shared';
 import type { HttpMethod } from '../route/marker.js';
+import { type SseMessage } from './sse.js';
 import { HttpClientOptions } from './options.js';
 import { type HttpRetryOptions } from './retry.js';
 /** The client speaks two more verbs than a route can declare. */
@@ -41,6 +42,10 @@ export interface RequestConfig<TRequest = unknown, TResponse = unknown> {
     readonly signal?: AbortSignal;
 }
 type BaseOptions<TRequest, TResponse> = Omit<RequestConfig<TRequest, TResponse>, 'method' | 'url' | 'payload'>;
+/** What both SSE readers take: no retry, and only the verbs a stream uses. */
+type SseConfig<TRequest> = Omit<RequestConfig<TRequest>, 'method' | 'retry'> & {
+    readonly method?: 'GET' | 'POST';
+};
 /**
  * A `fetch` client with a per-request timeout, retry with backoff, W3C Trace
  * Context propagation and one log line per call. `fetch` and nothing else, so there is no
@@ -61,21 +66,19 @@ export declare class HttpService extends UrlHelper {
     put<TRequest = unknown, TResponse = unknown>(url?: string | URL, payload?: TRequest, options?: BaseOptions<TRequest, TResponse>): Promise<TResponse>;
     patch<TRequest = unknown, TResponse = unknown>(url?: string | URL, payload?: TRequest, options?: BaseOptions<TRequest, TResponse>): Promise<TResponse>;
     delete<TResponse = unknown>(url?: string | URL, options?: BaseOptions<never, TResponse>): Promise<TResponse>;
+    /** Each `data:` payload of an event stream, `[DONE]` consumed rather than
+     * yielded. {@link streamSseEvents} keeps the envelope too. */
+    streamSse<TRequest = unknown>(config: SseConfig<TRequest>): AsyncGenerator<string>;
     /**
-     * Yields each `data:` payload of a Server-Sent-Events response, consuming the
-     * terminating `[DONE]` sentinel rather than yielding it.
+     * The same response, each event whole: the joined `data` plus whatever `event`,
+     * `id` and `retry` it carried. `id` is what a reconnect sends as `Last-Event-ID`.
      *
      * **No retry**, deliberately: a partially consumed stream cannot be replayed, so
      * retrying would re-deliver events the caller has already seen. The timeout
-     * covers the connect only - it is dropped once headers arrive, or a long-lived
-     * stream would be cut off mid-flight.
-     *
-     * Hand-rolled rather than delegated: Bun exposes no `EventSource` global and no
-     * SSE parser, which was measured rather than assumed.
+     * covers the connect only - dropped once headers arrive, or a long-lived stream
+     * would be cut off mid-flight.
      */
-    streamSse<TRequest = unknown>(config: Omit<RequestConfig<TRequest>, 'method' | 'retry'> & {
-        readonly method?: 'GET' | 'POST';
-    }): AsyncGenerator<string>;
+    streamSseEvents<TRequest = unknown>(config: SseConfig<TRequest>): AsyncGenerator<SseMessage>;
     /**
      * Resolves the target: an absolute url, a path relative to `baseUrl`, or
      * `baseUrl` plus an explicit `path`.

package/dist/client/sse.d.ts

@@ -1,13 +1,27 @@
+/** One dispatched event as it arrived. Not `SseEvent`, the write side, where
+ * `data` is any value rather than the text off the wire. */
+export interface SseMessage {
+    /** The `data:` lines of one event, joined with `\n` as the spec requires. */
+    readonly data: string;
+    /** The `event:` name, absent for the default `message`. */
+    readonly event?: string;
+    readonly id?: string;
+    /** The reconnection delay the server asked for, in milliseconds. */
+    readonly retry?: number;
+}
 /**
- * The `data:` payloads of a server-sent-events body, in order, ending when the
- * stream does or when a line reads `[DONE]`.
- *
- * Async iteration rather than `getReader()`: it acquires the reader and releases
- * it on completion, on a `break` in the consumer, and on the `[DONE]` return,
- * which is the case the manual form needed a `releaseLock()` in a `finally` for.
+ * Every event of a server-sent-events body, in order, ending with the stream or
+ * with `[DONE]`. One still being read when the body ends is dropped, per spec.
  *
- * Hand-rolled because Bun exposes no `EventSource` global and no SSE parser,
- * which was measured rather than assumed.
+ * `getReader()` rather than async iteration, so the last read is told apart from
+ * a chunk boundary: a trailing `\r` is half a `\r\n` in one and a line ending in
+ * the other. `releaseLock` in a `finally` covers a `break` and `[DONE]`.
+ * Hand-rolled: Bun exposes no `EventSource` and no SSE parser, measured.
+ */
+export declare function sseMessages(body: ReadableStream<Uint8Array>): AsyncGenerator<SseMessage>;
+/**
+ * The `data:` payloads alone, one string per event rather than per line, so a
+ * multi-line payload arrives as it was sent.
  */
 export declare function sseData(body: ReadableStream<Uint8Array>): AsyncGenerator<string>;
 /**

package/dist/client.d.ts

@@ -17,3 +17,5 @@ export type { BackoffOptions, RetryOptions } from '@dunx/core';
 export { HttpRetryClassifier, type HttpRetryOptions } from './client/retry.js';
 export { httpClient, HttpModule, type ClientTarget } from './client/module.js';
 export { HttpService, type HeaderFactory, type RequestConfig, type RequestMethod, } from './client/service.js';
+/** What `streamSseEvents` yields: one dispatched event, envelope included. */
+export type { SseMessage } from './client/sse.js';