@danceroutine/tango-core 0.1.0 → 1.0.0

package/dist/http/TangoResponse.js

@@ -1,556 +0,0 @@
-import { TangoError } from '../errors/TangoError';
-import { isArrayBuffer, isBlob, isReadableStream } from '../runtime/index';
-import { TangoHeaders } from '../http/TangoHeaders';
-import { TangoBody } from './TangoBody';
-export class TangoResponse {
-    static BRAND = 'tango.http.response';
-    tangoBody;
-    okValue;
-    __tangoBrand = TangoResponse.BRAND;
-    headers;
-    redirected;
-    status;
-    statusText;
-    type;
-    url;
-    body;
-    static isTangoResponse(value) {
-        return (typeof value === 'object' &&
-            value !== null &&
-            value.__tangoBrand === TangoResponse.BRAND);
-    }
-    // bodySource proxy for legacy convenience, but prefer using TangoBody/headers directly.
-    get bodySource() {
-        return this.tangoBody.bodySource;
-    }
-    constructor(init = {}) {
-        this.headers = new TangoHeaders(init.headers);
-        this.redirected = Boolean(init.redirected);
-        this.status = typeof init.status === 'number' ? init.status : 200;
-        this.statusText = init.statusText || '';
-        this.type = init.type || 'default';
-        this.url = init.url || '';
-        this.okValue = typeof init.ok === 'boolean' ? init.ok : undefined;
-        this.tangoBody = new TangoBody(init.body ?? null, this.headers);
-        this.body = isReadableStream(this.tangoBody.bodySource) ? this.tangoBody.bodySource : null;
-    }
-    get ok() {
-        if (typeof this.okValue === 'boolean')
-            return this.okValue;
-        return this.status >= 200 && this.status < 300;
-    }
-    get bodyUsed() {
-        return this.tangoBody.bodyUsed;
-    }
-    setHeader(name, value) {
-        this.headers.set(name, value);
-    }
-    appendHeader(name, value) {
-        this.headers.append(name, value);
-    }
-    getHeader(name) {
-        return this.headers.get(name);
-    }
-    hasHeader(name) {
-        return this.headers.has(name);
-    }
-    deleteHeader(name) {
-        this.headers.delete(name);
-    }
-    vary(...fields) {
-        this.headers.vary(...fields);
-    }
-    setCookie(name, value, options) {
-        this.headers.setCookie(name, value, options);
-    }
-    appendCookie(name, value, options) {
-        this.headers.appendCookie(name, value, options);
-    }
-    deleteCookie(name, options) {
-        this.headers.deleteCookie(name, options);
-    }
-    cacheControl(control) {
-        this.headers.cacheControl(control);
-    }
-    location(url) {
-        this.headers.location(url);
-    }
-    contentType(mime) {
-        this.headers.contentType(mime);
-    }
-    // ---- Trace & Correlation helper methods ----
-    /**
-     * Set the X-Request-Id header (request correlation).
-     * Returns this for fluent chaining.
-     */
-    withRequestId(requestId) {
-        if (requestId != null && typeof requestId === 'string' && requestId !== '') {
-            this.headers.set('X-Request-Id', requestId);
-        }
-        return this;
-    }
-    /**
-     * Set the traceparent header (W3C Trace Context propagation).
-     * Returns this for fluent chaining.
-     */
-    withTraceparent(traceparent) {
-        if (traceparent != null && typeof traceparent === 'string' && traceparent !== '') {
-            this.headers.set('traceparent', traceparent);
-        }
-        return this;
-    }
-    /**
-     * Set the Server-Timing header.
-     * Accepts a string or array of timing metrics.
-     * Returns this for fluent chaining.
-     */
-    withServerTiming(timing) {
-        if (Array.isArray(timing)) {
-            this.headers.set('Server-Timing', timing.join(', '));
-        }
-        else if (typeof timing === 'string') {
-            this.headers.set('Server-Timing', timing);
-        }
-        return this;
-    }
-    /**
-     * Set the X-Response-Time header (in ms).
-     * Numeric or formatted string (e.g. "76ms").
-     * Returns this for fluent chaining.
-     */
-    withResponseTime(time) {
-        if (typeof time === 'number') {
-            this.headers.set('X-Response-Time', `${time}ms`);
-        }
-        else if (typeof time === 'string') {
-            this.headers.set('X-Response-Time', time);
-        }
-        return this;
-    }
-    /**
-     * Propagate common tracing/correlation headers from provided Headers, TangoHeaders, or plain object.
-     * Known headers: x-request-id, traceparent, server-timing
-     * Returns this for fluent chaining.
-     */
-    propagateTraceHeaders(input) {
-        const incoming = new TangoHeaders(input);
-        const traceHeaderNames = [
-            'x-request-id',
-            'traceparent',
-            'server-timing',
-            // If you want to propagate response time, add 'x-response-time',
-        ];
-        for (const name of traceHeaderNames) {
-            const value = incoming.get(name);
-            if (value != null)
-                this.headers.set(name, value);
-        }
-        return this;
-    }
-    static json(data, init) {
-        const headers = new TangoHeaders(init?.headers);
-        if (!headers.has('Content-Type')) {
-            headers.set('Content-Type', 'application/json; charset=utf-8');
-        }
-        const body = JSON.stringify(data);
-        if (!headers.has('Content-Length')) {
-            headers.set('Content-Length', new TextEncoder().encode(body).length.toString());
-        }
-        return new TangoResponse({
-            ...init,
-            body,
-            headers,
-        });
-    }
-    static text(text, init) {
-        const headers = new TangoHeaders(init?.headers);
-        if (!headers.has('Content-Type')) {
-            headers.set('Content-Type', 'text/plain; charset=utf-8');
-        }
-        if (!headers.has('Content-Length')) {
-            headers.set('Content-Length', new TextEncoder().encode(text).length.toString());
-        }
-        return new TangoResponse({
-            ...init,
-            body: text,
-            headers,
-        });
-    }
-    static html(html, init) {
-        const headers = new TangoHeaders(init?.headers);
-        if (!headers.has('Content-Type')) {
-            headers.set('Content-Type', 'text/html; charset=utf-8');
-        }
-        if (!headers.has('Content-Length')) {
-            headers.set('Content-Length', new TextEncoder().encode(html).length.toString());
-        }
-        return new TangoResponse({
-            ...init,
-            body: html,
-            headers,
-        });
-    }
-    static stream(stream, init) {
-        return new TangoResponse({
-            ...init,
-            body: stream,
-            headers: new TangoHeaders(init?.headers),
-        });
-    }
-    static redirect(url, status = 302, init) {
-        const headers = new TangoHeaders(init?.headers);
-        headers.set('Location', url);
-        return new TangoResponse({
-            ...init,
-            body: undefined,
-            status,
-            headers,
-            redirected: true,
-            url,
-        });
-    }
-    static noContent(init) {
-        const headers = new TangoHeaders(init?.headers);
-        return new TangoResponse({
-            ...init,
-            body: undefined,
-            status: 204,
-            headers,
-        });
-    }
-    static created(location, body, init) {
-        const headers = new TangoHeaders(init?.headers);
-        if (location) {
-            headers.set('Location', location);
-        }
-        let respBody;
-        if (body !== undefined) {
-            respBody = JSON.stringify(body);
-            if (!headers.has('Content-Type')) {
-                headers.set('Content-Type', 'application/json; charset=utf-8');
-            }
-        }
-        if (typeof respBody === 'string' && !headers.has('Content-Length')) {
-            headers.set('Content-Length', new TextEncoder().encode(respBody).length.toString());
-        }
-        else if (isArrayBuffer(respBody) && !headers.has('Content-Length')) {
-            headers.set('Content-Length', respBody.byteLength.toString());
-        }
-        else if (isBlob(respBody) && !headers.has('Content-Length')) {
-            headers.set('Content-Length', respBody.size.toString());
-        }
-        return new TangoResponse({
-            ...init,
-            body: respBody,
-            status: 201,
-            headers,
-        });
-    }
-    static error(error, init) {
-        let code;
-        let message;
-        let details = undefined;
-        let fields = undefined;
-        let status = init?.status ?? 500;
-        if (TangoError.isTangoError(error)) {
-            const envelope = error.toErrorEnvelope();
-            code = envelope.error.code;
-            message = envelope.error.message;
-            details = envelope.error.details;
-            fields = envelope.error.fields;
-            status = error.status;
-        }
-        else {
-            code = error.code;
-            message = error.message;
-            details = error.details;
-            fields = error.fields;
-        }
-        return TangoResponse.problem({
-            code,
-            message,
-            details,
-            fields,
-        }, {
-            ...init,
-            status,
-        });
-    }
-    static badRequest(detail, init) {
-        if (TangoError.isTangoError(detail) || TangoError.isProblemDetails(detail)) {
-            return TangoResponse.error(detail, { ...init, status: 400 });
-        }
-        if (typeof detail === 'string') {
-            return TangoResponse.error({
-                code: 'bad_request',
-                message: detail,
-            }, { ...init, status: 400 });
-        }
-        return TangoResponse.error({
-            code: 'bad_request',
-            message: 'Bad Request',
-        }, { ...init, status: 400 });
-    }
-    static unauthorized(detail, init) {
-        if (TangoError.isTangoError(detail) || TangoError.isProblemDetails(detail)) {
-            return TangoResponse.error(detail, { ...init, status: 401 });
-        }
-        if (typeof detail === 'string') {
-            return TangoResponse.error({
-                code: 'unauthorized',
-                message: detail,
-            }, { ...init, status: 401 });
-        }
-        return TangoResponse.error({
-            code: 'unauthorized',
-            message: 'Unauthorized',
-        }, { ...init, status: 401 });
-    }
-    static forbidden(detail, init) {
-        if (TangoError.isTangoError(detail) || TangoError.isProblemDetails(detail)) {
-            return TangoResponse.error(detail, { ...init, status: 403 });
-        }
-        if (typeof detail === 'string') {
-            return TangoResponse.error({
-                code: 'forbidden',
-                message: detail,
-            }, { ...init, status: 403 });
-        }
-        return TangoResponse.error({
-            code: 'forbidden',
-            message: 'Forbidden',
-        }, { ...init, status: 403 });
-    }
-    static notFound(detail, init) {
-        if (TangoError.isTangoError(detail) || TangoError.isProblemDetails(detail)) {
-            return TangoResponse.error(detail, { ...init, status: 404 });
-        }
-        if (typeof detail === 'string') {
-            return TangoResponse.error({
-                code: 'not_found',
-                message: detail,
-            }, { ...init, status: 404 });
-        }
-        return TangoResponse.error({
-            code: 'not_found',
-            message: 'Not Found',
-        }, { ...init, status: 404 });
-    }
-    static conflict(detail, init) {
-        if (TangoError.isTangoError(detail) || TangoError.isProblemDetails(detail)) {
-            return TangoResponse.error(detail, { ...init, status: 409 });
-        }
-        if (typeof detail === 'string') {
-            return TangoResponse.error({
-                code: 'conflict',
-                message: detail,
-            }, { ...init, status: 409 });
-        }
-        return TangoResponse.error({
-            code: 'conflict',
-            message: 'Conflict',
-        }, { ...init, status: 409 });
-    }
-    static unprocessableEntity(detail, init) {
-        if (TangoError.isTangoError(detail) || TangoError.isProblemDetails(detail)) {
-            return TangoResponse.error(detail, { ...init, status: 422 });
-        }
-        if (typeof detail === 'string') {
-            return TangoResponse.error({
-                code: 'unprocessable_entity',
-                message: detail,
-            }, { ...init, status: 422 });
-        }
-        return TangoResponse.error({
-            code: 'unprocessable_entity',
-            message: 'Unprocessable Entity',
-        }, { ...init, status: 422 });
-    }
-    static tooManyRequests(detail, init) {
-        if (TangoError.isTangoError(detail) || TangoError.isProblemDetails(detail)) {
-            return TangoResponse.error(detail, { ...init, status: 429 });
-        }
-        if (typeof detail === 'string') {
-            return TangoResponse.error({
-                code: 'too_many_requests',
-                message: detail,
-            }, { ...init, status: 429 });
-        }
-        return TangoResponse.error({
-            code: 'too_many_requests',
-            message: 'Too Many Requests',
-        }, { ...init, status: 429 });
-    }
-    static problem(problem, init) {
-        let status = init?.status ?? 500;
-        const headers = new TangoHeaders(init?.headers);
-        if (!headers.has('Content-Type')) {
-            headers.set('Content-Type', 'application/problem+json; charset=utf-8');
-        }
-        let code = 'error';
-        let message = 'An error occurred';
-        let details = undefined;
-        let fields;
-        if (TangoError.isTangoError(problem)) {
-            const envelope = problem.toErrorEnvelope();
-            status = problem.status;
-            code = envelope.error.code;
-            message = envelope.error.message;
-            details = envelope.error.details;
-            fields = envelope.error.fields;
-        }
-        else if (TangoError.isProblemDetails(problem)) {
-            code = problem.code;
-            message = problem.message;
-            details = problem.details;
-            fields = problem.fields;
-        }
-        else if (typeof problem === 'string') {
-            message = problem;
-        }
-        else if (problem && typeof problem === 'object') {
-            const extracted = problem;
-            if (typeof extracted.code === 'string')
-                code = extracted.code;
-            if (typeof extracted.message === 'string')
-                message = extracted.message;
-            details = extracted.details;
-            fields = extracted.fields;
-        }
-        const envelope = {
-            error: {
-                code,
-                message,
-                ...(details !== undefined ? { details } : {}),
-                ...(fields ? { fields } : {}),
-            },
-        };
-        const body = JSON.stringify(envelope);
-        if (!headers.has('Content-Length')) {
-            headers.set('Content-Length', new TextEncoder().encode(body).length.toString());
-        }
-        return new TangoResponse({
-            ...init,
-            headers,
-            status,
-            body,
-        });
-    }
-    clone() {
-        if (this.bodyUsed) {
-            throw new TypeError('Body has already been used');
-        }
-        const clonedBody = this.tangoBody.clone();
-        return new TangoResponse({
-            body: clonedBody.bodySource,
-            headers: this.headers.clone(),
-            ok: this.okValue,
-            redirected: this.redirected,
-            status: this.status,
-            statusText: this.statusText,
-            type: this.type,
-            url: this.url,
-        });
-    }
-    //---- Spec Response interface fields and methods ----
-    async arrayBuffer() {
-        return this.tangoBody.arrayBuffer();
-    }
-    async blob() {
-        return this.tangoBody.blob();
-    }
-    async bytes() {
-        return this.tangoBody.bytes();
-    }
-    async formData() {
-        return this.tangoBody.formData();
-    }
-    async json() {
-        return this.tangoBody.json();
-    }
-    async text() {
-        return this.tangoBody.text();
-    }
-    /**
-     * Returns a response for serving a file.
-     */
-    static file(file, opts) {
-        const headers = new TangoHeaders(opts?.init?.headers ?? {});
-        if (opts?.filename) {
-            // Serve as an attachment by default, but not 'download'
-            headers.setContentDispositionInline(opts.filename);
-        }
-        if (opts?.contentType && !headers.has('Content-Type')) {
-            headers.set('Content-Type', opts.contentType);
-        }
-        else if (!headers.has('Content-Type')) {
-            headers.setContentTypeByFile(file, opts?.filename);
-        }
-        if (!headers.has('Content-Length')) {
-            headers.setContentLengthFromBody(file);
-        }
-        return new TangoResponse({
-            ...opts?.init,
-            body: file,
-            headers,
-        });
-    }
-    /**
-     * Returns a response that prompts the user to download the file.
-     */
-    static download(file, opts) {
-        const headers = new TangoHeaders(opts?.init?.headers ?? {});
-        if (opts?.filename) {
-            headers.setContentDispositionAttachment(opts.filename);
-        }
-        else {
-            headers.set('Content-Disposition', 'attachment');
-        }
-        if (opts?.contentType && !headers.has('Content-Type')) {
-            headers.set('Content-Type', opts.contentType);
-        }
-        else if (!headers.has('Content-Type')) {
-            headers.setContentTypeByFile(file, opts?.filename);
-        }
-        if (!headers.has('Content-Length')) {
-            headers.setContentLengthFromBody(file);
-        }
-        return new TangoResponse({
-            ...opts?.init,
-            body: file,
-            headers,
-        });
-    }
-    /**
-     * Returns a plain object debug representation of this response: { status, headers: { ... }, bodyType: ... }.
-     * Intended for testing and debug tooling.
-     */
-    toJSON() {
-        return {
-            status: this.status,
-            headers: Object.fromEntries(this.headers.entries()),
-            bodyType: this.tangoBody ? this.tangoBody.bodyType : typeof this.bodySource,
-        };
-    }
-    /**
-     * Returns the original body for test/debug purposes *without* consuming the stream.
-     *
-     * @throws {Error} if called in a production environment. Provided only for test or debug.
-     * @remarks
-     * This method gives direct access to the original body as provided to the constructor,
-     * before consumption. It is primarily intended for use in test code, introspection, or
-     * advanced debug tools. **Do not rely on this in production.**
-     * In production (`process.env.NODE_ENV === 'production'`), using this method will throw.
-     *
-     * This method is _not_ part of the web Response interface, and is intentionally private/internal.
-     */
-    __peekBodyForTestOnly() {
-        // Strong guard against accidental shipping in production
-        if (typeof process !== 'undefined' &&
-            process.env &&
-            (process.env.NODE_ENV === 'production' || process.env.NODE_ENV === 'prod')) {
-            throw new Error('peekBody() is not available in production builds. For test/debug use only.');
-        }
-        return this.tangoBody.bodySource;
-    }
-}