@xfcfam/xf-server-http 0.1.0

package/dist/src/api/general/WebSocketService.d.ts

@@ -0,0 +1,42 @@
+import { StatelessService } from '@xfcfam/xf';
+import type { WebSocketHandler } from '../../business/transfers/WebSocketConnection.js';
+/**
+ * Interaction-Layer Generalization for a WebSocket entry point.
+ *
+ * A WebSocket is a long-lived bidirectional channel, not a
+ * request → response exchange, so it does not extend `RestService` /
+ * `EntryService` (which model the request pipeline). Instead a
+ * `WebSocketService` registers connection handlers on the server and
+ * manages each {@link WebSocketConnection} directly.
+ *
+ * Concrete subclasses register their endpoints from `init()` with
+ * `B.server.ws(path, this.accept(this.onConnection))`. The server runs
+ * the WebSocket plugin on the same Fastify instance and the same port
+ * as the REST routes.
+ *
+ * @example
+ * ```ts
+ * import { WebSocketService, type WebSocketConnection } from '@xfcfam/xf-server-http'
+ * import { B } from '../../business/B.js'
+ *
+ * export class ChatService extends WebSocketService {
+ *   override async init(): Promise<void> {
+ *     B.server.ws('/chat', this.accept(this.onConnection))
+ *   }
+ *
+ *   private onConnection(conn: WebSocketConnection): void {
+ *     conn.onMessage((data) => conn.send(`echo: ${String(data)}`))
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class WebSocketService extends StatelessService {
+    init(): Promise<void>;
+    terminate(): Promise<void>;
+    /**
+     * Bind a connection handler to `this` so it is safe to pass directly
+     * to `B.server.ws(path, this.accept(this.onConnection))`.
+     */
+    protected accept(handler: WebSocketHandler): WebSocketHandler;
+}
+//# sourceMappingURL=WebSocketService.d.ts.map

package/dist/src/api/general/WebSocketService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketService.d.ts","sourceRoot":"","sources":["../../../../src/api/general/WebSocketService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAuB,gBAAgB,EAAE,MAAM,iDAAiD,CAAA;AAE5G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,8BAAsB,gBAAiB,SAAQ,gBAAgB;IAC9C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEzC;;;OAGG;IACH,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB;CAG9D"}

package/dist/src/api/general/WebSocketService.js

@@ -0,0 +1,45 @@
+import { StatelessService } from '@xfcfam/xf';
+/**
+ * Interaction-Layer Generalization for a WebSocket entry point.
+ *
+ * A WebSocket is a long-lived bidirectional channel, not a
+ * request → response exchange, so it does not extend `RestService` /
+ * `EntryService` (which model the request pipeline). Instead a
+ * `WebSocketService` registers connection handlers on the server and
+ * manages each {@link WebSocketConnection} directly.
+ *
+ * Concrete subclasses register their endpoints from `init()` with
+ * `B.server.ws(path, this.accept(this.onConnection))`. The server runs
+ * the WebSocket plugin on the same Fastify instance and the same port
+ * as the REST routes.
+ *
+ * @example
+ * ```ts
+ * import { WebSocketService, type WebSocketConnection } from '@xfcfam/xf-server-http'
+ * import { B } from '../../business/B.js'
+ *
+ * export class ChatService extends WebSocketService {
+ *   override async init(): Promise<void> {
+ *     B.server.ws('/chat', this.accept(this.onConnection))
+ *   }
+ *
+ *   private onConnection(conn: WebSocketConnection): void {
+ *     conn.onMessage((data) => conn.send(`echo: ${String(data)}`))
+ *   }
+ * }
+ * ```
+ */
+export class WebSocketService extends StatelessService {
+    async init() {
+        // Subclasses override and call B.server.ws(path, handler) inside.
+    }
+    async terminate() { }
+    /**
+     * Bind a connection handler to `this` so it is safe to pass directly
+     * to `B.server.ws(path, this.accept(this.onConnection))`.
+     */
+    accept(handler) {
+        return handler.bind(this);
+    }
+}
+//# sourceMappingURL=WebSocketService.js.map

package/dist/src/api/general/WebSocketService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketService.js","sourceRoot":"","sources":["../../../../src/api/general/WebSocketService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAG7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,OAAgB,gBAAiB,SAAQ,gBAAgB;IACpD,KAAK,CAAC,IAAI;QACjB,kEAAkE;IACpE,CAAC;IAEQ,KAAK,CAAC,SAAS,KAAmB,CAAC;IAE5C;;;OAGG;IACO,MAAM,CAAC,OAAyB;QACxC,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC3B,CAAC;CACF"}

package/dist/src/api/utils/FileResponseUtils.d.ts

@@ -0,0 +1,66 @@
+import type { HttpResponse } from '../../business/transfers/HttpResponse.js';
+/**
+ * Body shape acceptable for `FileResponseUtils` builders. Mirrors what
+ * `HttpResponse.body` already supports — every helper just wraps it
+ * with the right `Content-Type` and `Content-Disposition` headers.
+ */
+export type FileBody = Uint8Array | ReadableStream<Uint8Array> | string;
+/**
+ * Static utility — ergonomic builders for HTTP responses that
+ * deliver files (downloads, photos, videos, PDFs, exports). Pure
+ * (no I/O) — these are just `HttpResponse` literal factories with
+ * the right headers preset.
+ *
+ * Two patterns are commonly distinguished:
+ *
+ *  - **`attachment`**: the client should save the file with the given
+ *    name. Use for downloads (PDFs, CSV exports, archives).
+ *  - **`inline`**: the client may render the file in place (images
+ *    in `<img>`, PDFs in the browser viewer, videos in `<video>`).
+ *
+ * Both helpers accept a `Uint8Array` (small/buffered files), a
+ * `ReadableStream<Uint8Array>` (streaming downloads / large files),
+ * or a `string` (text-based content). The server pipeline writes the
+ * body verbatim — no extra serialisation.
+ */
+export declare class FileResponseUtils {
+    private constructor();
+    /**
+     * Build an HTTP response that prompts the client to download and
+     * save the file under `filename`.
+     *
+     * @example
+     * ```ts
+     * const stream = await B.docs.openStream(req.params.id)
+     * return FileResponseUtils.attachment(stream, 'report.pdf', 'application/pdf')
+     * ```
+     */
+    static attachment(body: FileBody, filename: string, mimeType: string, status?: number): HttpResponse<FileBody>;
+    /**
+     * Build an HTTP response that the client may render in place
+     * (images, embeddable PDFs, video). The optional `filename` hint
+     * is included so user agents can name the file if the user
+     * decides to save it.
+     *
+     * @example
+     * ```ts
+     * const stream = await B.photos.openStream(req.params.id)
+     * return FileResponseUtils.inline(stream, 'photo.jpg', 'image/jpeg')
+     * ```
+     */
+    static inline(body: FileBody, filenameOrMime: string, mimeType?: string, status?: number): HttpResponse<FileBody>;
+    /**
+     * Build a streaming response with a custom `Content-Type` and
+     * **no** `Content-Disposition`. For SSE, NDJSON, audio/video
+     * progressive streams, anything the client consumes incrementally.
+     *
+     * @example
+     * ```ts
+     * return FileResponseUtils.stream(eventStream, 'text/event-stream')
+     * ```
+     */
+    static stream(body: ReadableStream<Uint8Array>, mimeType: string, status?: number): HttpResponse<ReadableStream<Uint8Array>>;
+    /** Escape a filename for safe inclusion in a `Content-Disposition` header. */
+    private static escapeFilename;
+}
+//# sourceMappingURL=FileResponseUtils.d.ts.map

package/dist/src/api/utils/FileResponseUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileResponseUtils.d.ts","sourceRoot":"","sources":["../../../../src/api/utils/FileResponseUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAA;AAE5E;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAChB,UAAU,GACV,cAAc,CAAC,UAAU,CAAC,GAC1B,MAAM,CAAA;AAEV;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO;IAEP;;;;;;;;;OASG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAM,GAAG,YAAY,CAAC,QAAQ,CAAC;IAW3G;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,SAAM,GAAG,YAAY,CAAC,QAAQ,CAAC;IAY9G;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAM,GAAG,YAAY,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IAIzH,8EAA8E;IAC9E,OAAO,CAAC,MAAM,CAAC,cAAc;CAG9B"}

package/dist/src/api/utils/FileResponseUtils.js

@@ -0,0 +1,82 @@
+/**
+ * Static utility — ergonomic builders for HTTP responses that
+ * deliver files (downloads, photos, videos, PDFs, exports). Pure
+ * (no I/O) — these are just `HttpResponse` literal factories with
+ * the right headers preset.
+ *
+ * Two patterns are commonly distinguished:
+ *
+ *  - **`attachment`**: the client should save the file with the given
+ *    name. Use for downloads (PDFs, CSV exports, archives).
+ *  - **`inline`**: the client may render the file in place (images
+ *    in `<img>`, PDFs in the browser viewer, videos in `<video>`).
+ *
+ * Both helpers accept a `Uint8Array` (small/buffered files), a
+ * `ReadableStream<Uint8Array>` (streaming downloads / large files),
+ * or a `string` (text-based content). The server pipeline writes the
+ * body verbatim — no extra serialisation.
+ */
+export class FileResponseUtils {
+    constructor() { }
+    /**
+     * Build an HTTP response that prompts the client to download and
+     * save the file under `filename`.
+     *
+     * @example
+     * ```ts
+     * const stream = await B.docs.openStream(req.params.id)
+     * return FileResponseUtils.attachment(stream, 'report.pdf', 'application/pdf')
+     * ```
+     */
+    static attachment(body, filename, mimeType, status = 200) {
+        return {
+            status,
+            headers: {
+                'content-type': mimeType,
+                'content-disposition': `attachment; filename="${FileResponseUtils.escapeFilename(filename)}"`,
+            },
+            body,
+        };
+    }
+    /**
+     * Build an HTTP response that the client may render in place
+     * (images, embeddable PDFs, video). The optional `filename` hint
+     * is included so user agents can name the file if the user
+     * decides to save it.
+     *
+     * @example
+     * ```ts
+     * const stream = await B.photos.openStream(req.params.id)
+     * return FileResponseUtils.inline(stream, 'photo.jpg', 'image/jpeg')
+     * ```
+     */
+    static inline(body, filenameOrMime, mimeType, status = 200) {
+        // Allow `inline(body, 'image/jpeg')` shorthand when no filename
+        // hint is meaningful (e.g. on-the-fly generated previews).
+        const filename = mimeType === undefined ? undefined : filenameOrMime;
+        const ct = mimeType ?? filenameOrMime;
+        const headers = { 'content-type': ct };
+        headers['content-disposition'] = filename === undefined
+            ? 'inline'
+            : `inline; filename="${FileResponseUtils.escapeFilename(filename)}"`;
+        return { status, headers, body };
+    }
+    /**
+     * Build a streaming response with a custom `Content-Type` and
+     * **no** `Content-Disposition`. For SSE, NDJSON, audio/video
+     * progressive streams, anything the client consumes incrementally.
+     *
+     * @example
+     * ```ts
+     * return FileResponseUtils.stream(eventStream, 'text/event-stream')
+     * ```
+     */
+    static stream(body, mimeType, status = 200) {
+        return { status, headers: { 'content-type': mimeType }, body };
+    }
+    /** Escape a filename for safe inclusion in a `Content-Disposition` header. */
+    static escapeFilename(filename) {
+        return filename.replace(/[\\"]/g, '\\$&');
+    }
+}
+//# sourceMappingURL=FileResponseUtils.js.map

package/dist/src/api/utils/FileResponseUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileResponseUtils.js","sourceRoot":"","sources":["../../../../src/api/utils/FileResponseUtils.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,iBAAiB;IAC5B,gBAAuB,CAAC;IAExB;;;;;;;;;OASG;IACH,MAAM,CAAC,UAAU,CAAC,IAAc,EAAE,QAAgB,EAAE,QAAgB,EAAE,MAAM,GAAG,GAAG;QAChF,OAAO;YACL,MAAM;YACN,OAAO,EAAE;gBACP,cAAc,EAAE,QAAQ;gBACxB,qBAAqB,EAAE,yBAAyB,iBAAiB,CAAC,cAAc,CAAC,QAAQ,CAAC,GAAG;aAC9F;YACD,IAAI;SACL,CAAA;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,CAAC,IAAc,EAAE,cAAsB,EAAE,QAAiB,EAAE,MAAM,GAAG,GAAG;QACnF,gEAAgE;QAChE,2DAA2D;QAC3D,MAAM,QAAQ,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAA;QACpE,MAAM,EAAE,GAAG,QAAQ,IAAI,cAAc,CAAA;QACrC,MAAM,OAAO,GAA2B,EAAE,cAAc,EAAE,EAAE,EAAE,CAAA;QAC9D,OAAO,CAAC,qBAAqB,CAAC,GAAG,QAAQ,KAAK,SAAS;YACrD,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,qBAAqB,iBAAiB,CAAC,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAA;QACtE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IAClC,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,CAAC,IAAgC,EAAE,QAAgB,EAAE,MAAM,GAAG,GAAG;QAC5E,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAA;IAChE,CAAC;IAED,8EAA8E;IACtE,MAAM,CAAC,cAAc,CAAC,QAAgB;QAC5C,OAAO,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IAC3C,CAAC;CACF"}

package/dist/src/api/utils/HttpStatusUtils.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Static utility — canonical HTTP status code constants. Pure data,
+ * no I/O. Use these instead of magic numbers in handlers and hooks:
+ * `return { status: HttpStatusUtils.OK, body: ... }`.
+ *
+ * Only the codes the typical REST service emits are listed. Less
+ * common codes (1xx informational, 3xx redirects beyond 301/302,
+ * 5xx beyond 500/502/503/504) can be used as numeric literals when
+ * needed — the response carries `status: number`, not an enum.
+ */
+export declare class HttpStatusUtils {
+    private constructor();
+    static readonly OK = 200;
+    static readonly CREATED = 201;
+    static readonly ACCEPTED = 202;
+    static readonly NO_CONTENT = 204;
+    static readonly MOVED_PERMANENTLY = 301;
+    static readonly FOUND = 302;
+    static readonly NOT_MODIFIED = 304;
+    static readonly BAD_REQUEST = 400;
+    static readonly UNAUTHORIZED = 401;
+    static readonly FORBIDDEN = 403;
+    static readonly NOT_FOUND = 404;
+    static readonly METHOD_NOT_ALLOWED = 405;
+    static readonly CONFLICT = 409;
+    static readonly GONE = 410;
+    static readonly UNSUPPORTED_MEDIA_TYPE = 415;
+    static readonly UNPROCESSABLE_ENTITY = 422;
+    static readonly TOO_MANY_REQUESTS = 429;
+    static readonly INTERNAL_SERVER_ERROR = 500;
+    static readonly NOT_IMPLEMENTED = 501;
+    static readonly BAD_GATEWAY = 502;
+    static readonly SERVICE_UNAVAILABLE = 503;
+    static readonly GATEWAY_TIMEOUT = 504;
+}
+//# sourceMappingURL=HttpStatusUtils.d.ts.map

package/dist/src/api/utils/HttpStatusUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpStatusUtils.d.ts","sourceRoot":"","sources":["../../../../src/api/utils/HttpStatusUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,OAAO;IAGP,MAAM,CAAC,QAAQ,CAAC,EAAE,OAAM;IACxB,MAAM,CAAC,QAAQ,CAAC,OAAO,OAAM;IAC7B,MAAM,CAAC,QAAQ,CAAC,QAAQ,OAAM;IAC9B,MAAM,CAAC,QAAQ,CAAC,UAAU,OAAM;IAGhC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,OAAM;IACvC,MAAM,CAAC,QAAQ,CAAC,KAAK,OAAM;IAC3B,MAAM,CAAC,QAAQ,CAAC,YAAY,OAAM;IAGlC,MAAM,CAAC,QAAQ,CAAC,WAAW,OAAM;IACjC,MAAM,CAAC,QAAQ,CAAC,YAAY,OAAM;IAClC,MAAM,CAAC,QAAQ,CAAC,SAAS,OAAM;IAC/B,MAAM,CAAC,QAAQ,CAAC,SAAS,OAAM;IAC/B,MAAM,CAAC,QAAQ,CAAC,kBAAkB,OAAM;IACxC,MAAM,CAAC,QAAQ,CAAC,QAAQ,OAAM;IAC9B,MAAM,CAAC,QAAQ,CAAC,IAAI,OAAM;IAC1B,MAAM,CAAC,QAAQ,CAAC,sBAAsB,OAAM;IAC5C,MAAM,CAAC,QAAQ,CAAC,oBAAoB,OAAM;IAC1C,MAAM,CAAC,QAAQ,CAAC,iBAAiB,OAAM;IAGvC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,OAAM;IAC3C,MAAM,CAAC,QAAQ,CAAC,eAAe,OAAM;IACrC,MAAM,CAAC,QAAQ,CAAC,WAAW,OAAM;IACjC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,OAAM;IACzC,MAAM,CAAC,QAAQ,CAAC,eAAe,OAAM;CACtC"}

package/dist/src/api/utils/HttpStatusUtils.js

@@ -0,0 +1,40 @@
+/**
+ * Static utility — canonical HTTP status code constants. Pure data,
+ * no I/O. Use these instead of magic numbers in handlers and hooks:
+ * `return { status: HttpStatusUtils.OK, body: ... }`.
+ *
+ * Only the codes the typical REST service emits are listed. Less
+ * common codes (1xx informational, 3xx redirects beyond 301/302,
+ * 5xx beyond 500/502/503/504) can be used as numeric literals when
+ * needed — the response carries `status: number`, not an enum.
+ */
+export class HttpStatusUtils {
+    constructor() { }
+    // ── 2xx Success ──
+    static OK = 200;
+    static CREATED = 201;
+    static ACCEPTED = 202;
+    static NO_CONTENT = 204;
+    // ── 3xx Redirection ──
+    static MOVED_PERMANENTLY = 301;
+    static FOUND = 302;
+    static NOT_MODIFIED = 304;
+    // ── 4xx Client error ──
+    static BAD_REQUEST = 400;
+    static UNAUTHORIZED = 401;
+    static FORBIDDEN = 403;
+    static NOT_FOUND = 404;
+    static METHOD_NOT_ALLOWED = 405;
+    static CONFLICT = 409;
+    static GONE = 410;
+    static UNSUPPORTED_MEDIA_TYPE = 415;
+    static UNPROCESSABLE_ENTITY = 422;
+    static TOO_MANY_REQUESTS = 429;
+    // ── 5xx Server error ──
+    static INTERNAL_SERVER_ERROR = 500;
+    static NOT_IMPLEMENTED = 501;
+    static BAD_GATEWAY = 502;
+    static SERVICE_UNAVAILABLE = 503;
+    static GATEWAY_TIMEOUT = 504;
+}
+//# sourceMappingURL=HttpStatusUtils.js.map

package/dist/src/api/utils/HttpStatusUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpStatusUtils.js","sourceRoot":"","sources":["../../../../src/api/utils/HttpStatusUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,OAAO,eAAe;IAC1B,gBAAuB,CAAC;IAExB,oBAAoB;IACpB,MAAM,CAAU,EAAE,GAAG,GAAG,CAAA;IACxB,MAAM,CAAU,OAAO,GAAG,GAAG,CAAA;IAC7B,MAAM,CAAU,QAAQ,GAAG,GAAG,CAAA;IAC9B,MAAM,CAAU,UAAU,GAAG,GAAG,CAAA;IAEhC,wBAAwB;IACxB,MAAM,CAAU,iBAAiB,GAAG,GAAG,CAAA;IACvC,MAAM,CAAU,KAAK,GAAG,GAAG,CAAA;IAC3B,MAAM,CAAU,YAAY,GAAG,GAAG,CAAA;IAElC,yBAAyB;IACzB,MAAM,CAAU,WAAW,GAAG,GAAG,CAAA;IACjC,MAAM,CAAU,YAAY,GAAG,GAAG,CAAA;IAClC,MAAM,CAAU,SAAS,GAAG,GAAG,CAAA;IAC/B,MAAM,CAAU,SAAS,GAAG,GAAG,CAAA;IAC/B,MAAM,CAAU,kBAAkB,GAAG,GAAG,CAAA;IACxC,MAAM,CAAU,QAAQ,GAAG,GAAG,CAAA;IAC9B,MAAM,CAAU,IAAI,GAAG,GAAG,CAAA;IAC1B,MAAM,CAAU,sBAAsB,GAAG,GAAG,CAAA;IAC5C,MAAM,CAAU,oBAAoB,GAAG,GAAG,CAAA;IAC1C,MAAM,CAAU,iBAAiB,GAAG,GAAG,CAAA;IAEvC,yBAAyB;IACzB,MAAM,CAAU,qBAAqB,GAAG,GAAG,CAAA;IAC3C,MAAM,CAAU,eAAe,GAAG,GAAG,CAAA;IACrC,MAAM,CAAU,WAAW,GAAG,GAAG,CAAA;IACjC,MAAM,CAAU,mBAAmB,GAAG,GAAG,CAAA;IACzC,MAAM,CAAU,eAAe,GAAG,GAAG,CAAA"}

package/dist/src/api/utils/ResponseUtils.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Static utility — classifiers for the `body` field of an
+ * `HttpResponse` (or `HttpRequest`). Pure (no I/O).
+ *
+ * The XF doctrine for `xf-server` unifies `body` to a single type:
+ * it may be a JS value (object/array/primitive), a `Uint8Array`, a
+ * `ReadableStream<Uint8Array>`, a `string`, or null/undefined. The
+ * pipeline treats each shape differently: object bodies are
+ * serialised by `ObjectRestService`, streams are piped through,
+ * bytes are written verbatim, strings are sent as text.
+ *
+ * Cross-cutting hooks (`onResponse` on either `RestService` or
+ * `HttpServerBusiness`) need to branch on these cases — typically to
+ * apply a wrapper envelope to object responses while letting
+ * streams/files/bytes pass through. This Utility provides the
+ * classifiers so the branching is a single readable line:
+ *
+ * ```ts
+ * override async onResponse(_req, res) {
+ *   if (!ResponseUtils.isObject(res.body)) return res   // stream / file / bytes
+ *   return { ...res, body: { code: '0', description: 'OK', data: res.body } }
+ * }
+ * ```
+ *
+ * The classifier set is **exhaustive and disjoint** for non-`undefined`
+ * bodies: every body is exactly one of stream / binary / textual / object.
+ * `undefined` returns `false` from every classifier (no body to act on).
+ */
+export declare class ResponseUtils {
+    private constructor();
+    /**
+     * True when `body` is a `ReadableStream<Uint8Array>` — the
+     * streaming case (downloads, SSE, large exports).
+     */
+    static isStream(body: unknown): body is ReadableStream<Uint8Array>;
+    /**
+     * True when `body` is raw bytes — `Uint8Array` (covers
+     * `Buffer` subtypes too, since `Buffer` extends `Uint8Array`).
+     */
+    static isBinary(body: unknown): body is Uint8Array;
+    /**
+     * True when `body` is a plain string — sent as-is to the client.
+     * Does NOT cover `string`-encoded JSON: by the time a wrapper hook
+     * sees the response, an object body has not yet been serialised.
+     */
+    static isTextual(body: unknown): body is string;
+    /**
+     * True when `body` is a JS value that will be JSON-serialised
+     * downstream (object, array, number, boolean, or `null`). The
+     * exception is `undefined`, which represents an empty response —
+     * not a wrappable object.
+     *
+     * The check is **complementary** to {@link isStream},
+     * {@link isBinary} and {@link isTextual}: if a body is not a
+     * stream, not bytes and not a string, it is treated as an object.
+     */
+    static isObject(body: unknown): boolean;
+    /** True when there is no body to send (`undefined` or empty status). */
+    static isEmpty(body: unknown): boolean;
+}
+//# sourceMappingURL=ResponseUtils.d.ts.map

package/dist/src/api/utils/ResponseUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResponseUtils.d.ts","sourceRoot":"","sources":["../../../../src/api/utils/ResponseUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,aAAa;IACxB,OAAO;IAEP;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,cAAc,CAAC,UAAU,CAAC;IAMlE;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,UAAU;IAIlD;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM;IAI/C;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO;IAQvC,wEAAwE;IACxE,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO;CAGvC"}

package/dist/src/api/utils/ResponseUtils.js

@@ -0,0 +1,81 @@
+/**
+ * Static utility — classifiers for the `body` field of an
+ * `HttpResponse` (or `HttpRequest`). Pure (no I/O).
+ *
+ * The XF doctrine for `xf-server` unifies `body` to a single type:
+ * it may be a JS value (object/array/primitive), a `Uint8Array`, a
+ * `ReadableStream<Uint8Array>`, a `string`, or null/undefined. The
+ * pipeline treats each shape differently: object bodies are
+ * serialised by `ObjectRestService`, streams are piped through,
+ * bytes are written verbatim, strings are sent as text.
+ *
+ * Cross-cutting hooks (`onResponse` on either `RestService` or
+ * `HttpServerBusiness`) need to branch on these cases — typically to
+ * apply a wrapper envelope to object responses while letting
+ * streams/files/bytes pass through. This Utility provides the
+ * classifiers so the branching is a single readable line:
+ *
+ * ```ts
+ * override async onResponse(_req, res) {
+ *   if (!ResponseUtils.isObject(res.body)) return res   // stream / file / bytes
+ *   return { ...res, body: { code: '0', description: 'OK', data: res.body } }
+ * }
+ * ```
+ *
+ * The classifier set is **exhaustive and disjoint** for non-`undefined`
+ * bodies: every body is exactly one of stream / binary / textual / object.
+ * `undefined` returns `false` from every classifier (no body to act on).
+ */
+export class ResponseUtils {
+    constructor() { }
+    /**
+     * True when `body` is a `ReadableStream<Uint8Array>` — the
+     * streaming case (downloads, SSE, large exports).
+     */
+    static isStream(body) {
+        return typeof body === 'object'
+            && body !== null
+            && typeof body.getReader === 'function';
+    }
+    /**
+     * True when `body` is raw bytes — `Uint8Array` (covers
+     * `Buffer` subtypes too, since `Buffer` extends `Uint8Array`).
+     */
+    static isBinary(body) {
+        return body instanceof Uint8Array;
+    }
+    /**
+     * True when `body` is a plain string — sent as-is to the client.
+     * Does NOT cover `string`-encoded JSON: by the time a wrapper hook
+     * sees the response, an object body has not yet been serialised.
+     */
+    static isTextual(body) {
+        return typeof body === 'string';
+    }
+    /**
+     * True when `body` is a JS value that will be JSON-serialised
+     * downstream (object, array, number, boolean, or `null`). The
+     * exception is `undefined`, which represents an empty response —
+     * not a wrappable object.
+     *
+     * The check is **complementary** to {@link isStream},
+     * {@link isBinary} and {@link isTextual}: if a body is not a
+     * stream, not bytes and not a string, it is treated as an object.
+     */
+    static isObject(body) {
+        if (body === undefined)
+            return false;
+        if (ResponseUtils.isStream(body))
+            return false;
+        if (ResponseUtils.isBinary(body))
+            return false;
+        if (ResponseUtils.isTextual(body))
+            return false;
+        return true;
+    }
+    /** True when there is no body to send (`undefined` or empty status). */
+    static isEmpty(body) {
+        return body === undefined;
+    }
+}
+//# sourceMappingURL=ResponseUtils.js.map

package/dist/src/api/utils/ResponseUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResponseUtils.js","sourceRoot":"","sources":["../../../../src/api/utils/ResponseUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,aAAa;IACxB,gBAAuB,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAa;QAC3B,OAAO,OAAO,IAAI,KAAK,QAAQ;eAC1B,IAAI,KAAK,IAAI;eACb,OAAQ,IAAgC,CAAC,SAAS,KAAK,UAAU,CAAA;IACxE,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAa;QAC3B,OAAO,IAAI,YAAY,UAAU,CAAA;IACnC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,IAAa;QAC5B,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAA;IACjC,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAa;QAC3B,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,KAAK,CAAA;QACpC,IAAI,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAA;QAC9C,IAAI,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAA;QAC9C,IAAI,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAA;QAC/C,OAAO,IAAI,CAAA;IACb,CAAC;IAED,wEAAwE;IACxE,MAAM,CAAC,OAAO,CAAC,IAAa;QAC1B,OAAO,IAAI,KAAK,SAAS,CAAA;IAC3B,CAAC;CACF"}

package/dist/src/api/utils/SchemaValidatorUtils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Shape any schema must expose for `SchemaValidatorUtils` to use it. Modeled
+ * directly on `zod`'s `.safeParse(value)` API but **not coupled to
+ * zod** — any library that emits a result of shape
+ * `{ success: boolean, data?, error? }` works (valibot, arktype with
+ * adapter, hand-rolled validators, …).
+ */
+export interface Schema<T> {
+    safeParse(value: unknown): SchemaParseResult<T>;
+}
+export interface SchemaParseResult<T> {
+    success: boolean;
+    data?: T;
+    error?: {
+        issues?: readonly unknown[];
+        message?: string;
+    } | unknown;
+}
+/**
+ * Static utility — duck-typed validation helper. Drop-in for zod
+ * users but doesn't drag zod into the package. Pure (no I/O).
+ *
+ * The intended usage is inside an HTTP handler:
+ *
+ * ```ts
+ * const dto = SchemaValidatorUtils.parse(UserCreateSchema, req.body)
+ * ```
+ *
+ * On validation failure, raises {@link BadRequestException} with the
+ * schema's issue list in the response body. The server pipeline
+ * translates that into a `400 Bad Request`.
+ */
+export declare class SchemaValidatorUtils {
+    private constructor();
+    /**
+     * Validate `value` against `schema`. Returns the parsed value on
+     * success; throws {@link BadRequestException} on failure.
+     */
+    static parse<T>(schema: Schema<T>, value: unknown): T;
+    /**
+     * Validate `value` and return `null` on failure instead of
+     * throwing. Useful when the handler wants to branch on validity
+     * rather than propagate.
+     */
+    static tryParse<T>(schema: Schema<T>, value: unknown): T | null;
+    private static extractIssues;
+}
+//# sourceMappingURL=SchemaValidatorUtils.d.ts.map

package/dist/src/api/utils/SchemaValidatorUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaValidatorUtils.d.ts","sourceRoot":"","sources":["../../../../src/api/utils/SchemaValidatorUtils.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,WAAW,MAAM,CAAC,CAAC;IACvB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAA;CAChD;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,CAAC,CAAA;IACR,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAA;CACpE;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,oBAAoB;IAC/B,OAAO;IAEP;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC;IAWrD;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,GAAG,IAAI;IAK/D,OAAO,CAAC,MAAM,CAAC,aAAa;CAQ7B"}

package/dist/src/api/utils/SchemaValidatorUtils.js

@@ -0,0 +1,52 @@
+import { BadRequestException } from '../../business/transfers/BadRequestException.js';
+/**
+ * Static utility — duck-typed validation helper. Drop-in for zod
+ * users but doesn't drag zod into the package. Pure (no I/O).
+ *
+ * The intended usage is inside an HTTP handler:
+ *
+ * ```ts
+ * const dto = SchemaValidatorUtils.parse(UserCreateSchema, req.body)
+ * ```
+ *
+ * On validation failure, raises {@link BadRequestException} with the
+ * schema's issue list in the response body. The server pipeline
+ * translates that into a `400 Bad Request`.
+ */
+export class SchemaValidatorUtils {
+    constructor() { }
+    /**
+     * Validate `value` against `schema`. Returns the parsed value on
+     * success; throws {@link BadRequestException} on failure.
+     */
+    static parse(schema, value) {
+        const result = schema.safeParse(value);
+        if (result.success === true) {
+            // `data` is guaranteed when `success`; non-null assertion is
+            // safe because the schema contract requires it.
+            return result.data;
+        }
+        const issues = SchemaValidatorUtils.extractIssues(result.error);
+        throw new BadRequestException('Validation failed', { errors: issues });
+    }
+    /**
+     * Validate `value` and return `null` on failure instead of
+     * throwing. Useful when the handler wants to branch on validity
+     * rather than propagate.
+     */
+    static tryParse(schema, value) {
+        const result = schema.safeParse(value);
+        return result.success === true ? result.data : null;
+    }
+    static extractIssues(err) {
+        if (err === null || err === undefined)
+            return [];
+        if (typeof err === 'object' && err !== null && 'issues' in err) {
+            const issues = err.issues;
+            if (Array.isArray(issues))
+                return issues;
+        }
+        return [{ message: String(err.message ?? err) }];
+    }
+}
+//# sourceMappingURL=SchemaValidatorUtils.js.map

package/dist/src/api/utils/SchemaValidatorUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaValidatorUtils.js","sourceRoot":"","sources":["../../../../src/api/utils/SchemaValidatorUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iDAAiD,CAAA;AAmBrF;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,oBAAoB;IAC/B,gBAAuB,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAI,MAAiB,EAAE,KAAc;QAC/C,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;QACtC,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC5B,6DAA6D;YAC7D,gDAAgD;YAChD,OAAO,MAAM,CAAC,IAAS,CAAA;QACzB,CAAC;QACD,MAAM,MAAM,GAAG,oBAAoB,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAC/D,MAAM,IAAI,mBAAmB,CAAC,mBAAmB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IACxE,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAI,MAAiB,EAAE,KAAc;QAClD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;QACtC,OAAO,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAE,MAAM,CAAC,IAAU,CAAC,CAAC,CAAC,IAAI,CAAA;IAC5D,CAAC;IAEO,MAAM,CAAC,aAAa,CAAC,GAAY;QACvC,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,EAAE,CAAA;QAChD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,QAAQ,IAAI,GAAG,EAAE,CAAC;YAC/D,MAAM,MAAM,GAAI,GAA4B,CAAC,MAAM,CAAA;YACnD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;gBAAE,OAAO,MAAM,CAAA;QAC1C,CAAC;QACD,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,CAAE,GAA4B,CAAC,OAAO,IAAI,GAAG,CAAC,EAAE,CAAC,CAAA;IAC5E,CAAC;CACF"}