@benzenejs/results 0.0.0-stage → 0.1.0-beta.2

package/dist/BenzeneResult.d.ts

@@ -0,0 +1,49 @@
+import { BenzeneError, IBenzeneResultOf, VoidResult } from '@benzenejs/abstractions';
+import { ProblemDetails } from './ProblemDetails';
+export declare const BenzeneResult: {
+    /** Port of the C# `Set` overloads. */
+    readonly set: <T = VoidResult>(status: string, payload?: T, isSuccessful?: boolean) => IBenzeneResultOf<T>;
+    /**
+     * Port of C# `Set(status, params BenzeneError[] errors)` and its `string[]` sibling: accepts
+     * either, so `setErrors(status, 'a message')` and
+     * `setErrors(status, { message: 'a message', field: 'Name', code: 'NotEmpty' })` both work.
+     */
+    readonly setErrors: <T = VoidResult>(status: string, ...errors: (string | BenzeneError)[]) => IBenzeneResultOf<T>;
+    /**
+     * Builds a failed result carrying a deliberately-authored problem document - the port of C#
+     * `BenzeneResult.Problem<T>(ProblemDetails)`.
+     *
+     * The status comes from the document's `benzeneStatus`, which is required: a problem document
+     * with no status cannot be classified by anything downstream. The result's `errors` are projected
+     * from the document's own `errors`, and the result is always unsuccessful - this factory exists
+     * to fail deliberately with a richer document than the status-derived one, most often to set an
+     * application-owned `type` (wire-contracts.md §1.3).
+     */
+    readonly problem: <T = VoidResult>(problem: ProblemDetails) => IBenzeneResultOf<T>;
+    /**
+     * Builds a failed result for a problem document a CLIENT received off the wire - the port of C#
+     * `BenzeneResult.AttachReceivedProblem<T>` (internal there, reached from
+     * `Benzene.Clients.Common.ClientResultExtensions`; exported here because the clients live in another
+     * package). The status is the one the client decided - the document's `benzeneStatus` where it has one
+     * (wire-contracts §4.1), else the envelope/HTTP classification - and is taken as given here; `errors`
+     * are the ones rebuilt from the document
+     * (core-concepts §12 "Error fidelity", wire-contracts.md §1.3); and the document, when there is one,
+     * is attached so `ProblemTypes.from(result)` returns exactly what was received - an application's own
+     * problem `type` survives the hop.
+     */
+    readonly receivedProblem: <T = VoidResult>(status: string, errors: readonly BenzeneError[], problem?: ProblemDetails) => IBenzeneResultOf<T>;
+    readonly ok: <T = VoidResult>(payload?: T) => IBenzeneResultOf<T>;
+    readonly created: <T = VoidResult>(payload?: T) => IBenzeneResultOf<T>;
+    readonly accepted: <T = VoidResult>(payload?: T) => IBenzeneResultOf<T>;
+    readonly updated: <T = VoidResult>(payload?: T) => IBenzeneResultOf<T>;
+    readonly deleted: <T = VoidResult>(payload?: T) => IBenzeneResultOf<T>;
+    readonly ignored: <T = VoidResult>() => IBenzeneResultOf<T>;
+    readonly notFound: <T = VoidResult>(...errors: (string | BenzeneError)[]) => IBenzeneResultOf<T>;
+    readonly badRequest: <T = VoidResult>(...errors: (string | BenzeneError)[]) => IBenzeneResultOf<T>;
+    readonly unauthorized: <T = VoidResult>(...errors: (string | BenzeneError)[]) => IBenzeneResultOf<T>;
+    readonly forbidden: <T = VoidResult>(...errors: (string | BenzeneError)[]) => IBenzeneResultOf<T>;
+    readonly validationError: <T = VoidResult>(...errors: (string | BenzeneError)[]) => IBenzeneResultOf<T>;
+    readonly serviceUnavailable: <T = VoidResult>(...errors: (string | BenzeneError)[]) => IBenzeneResultOf<T>;
+    readonly tooManyRequests: <T = VoidResult>(...errors: (string | BenzeneError)[]) => IBenzeneResultOf<T>;
+    readonly unexpectedError: <T = VoidResult>(...errors: (string | BenzeneError)[]) => IBenzeneResultOf<T>;
+};

package/dist/BenzeneResult.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BenzeneResult = void 0;
+const abstractions_1 = require("@benzenejs/abstractions");
+const BenzeneResultStatus_1 = require("./BenzeneResultStatus");
+/**
+ * Factory for creating result instances.
+ * Port of Benzene.Results.BenzeneResult.
+ *
+ * The C# generic/non-generic overload pairs (`Ok()` / `Ok<T>(payload)`) collapse
+ * into single functions with an optional payload defaulting to `VoidResult`
+ * (the port of C# `Void`). The status-specific factories mirror the C# names.
+ */
+class BenzeneResultInternal {
+    status;
+    payload;
+    errors;
+    isSuccessful;
+    constructor(status, payload, errors, isSuccessful) {
+        this.status = status;
+        this.payload = payload;
+        this.errors = errors;
+        this.isSuccessful = isSuccessful;
+    }
+    get payloadAsObject() {
+        return this.payload;
+    }
+}
+/**
+ * Widens the caller's errors to structured {@link BenzeneError}s. A plain string becomes
+ * `{ message }` - the shape a message-only failure has always had on the wire - so every existing
+ * call site that passes strings is unchanged, while a caller that has a `field` or `code` can now
+ * pass those through instead of losing them.
+ */
+function toBenzeneErrors(errors) {
+    return errors.map((error) => (typeof error === 'string' ? { message: error } : error));
+}
+function create(status, payload, errors = [], isSuccessful) {
+    return new BenzeneResultInternal(status, payload, errors, isSuccessful ?? BenzeneResultStatus_1.BenzeneResultStatus.isSuccess(status));
+}
+const voidPayload = new abstractions_1.VoidResult();
+exports.BenzeneResult = {
+    /** Port of the C# `Set` overloads. */
+    set(status, payload, isSuccessful) {
+        return create(status, (payload ?? voidPayload), [], isSuccessful);
+    },
+    /**
+     * Port of C# `Set(status, params BenzeneError[] errors)` and its `string[]` sibling: accepts
+     * either, so `setErrors(status, 'a message')` and
+     * `setErrors(status, { message: 'a message', field: 'Name', code: 'NotEmpty' })` both work.
+     */
+    setErrors(status, ...errors) {
+        return create(status, voidPayload, toBenzeneErrors(errors));
+    },
+    /**
+     * Builds a failed result carrying a deliberately-authored problem document - the port of C#
+     * `BenzeneResult.Problem<T>(ProblemDetails)`.
+     *
+     * The status comes from the document's `benzeneStatus`, which is required: a problem document
+     * with no status cannot be classified by anything downstream. The result's `errors` are projected
+     * from the document's own `errors`, and the result is always unsuccessful - this factory exists
+     * to fail deliberately with a richer document than the status-derived one, most often to set an
+     * application-owned `type` (wire-contracts.md §1.3).
+     */
+    problem(problem) {
+        if (problem.benzeneStatus === undefined || problem.benzeneStatus === '') {
+            throw new Error('problem.benzeneStatus is required to build a BenzeneResult.problem(...) - a problem ' +
+                'document with no status cannot be classified by anything downstream. Set ' +
+                'ProblemDetails.benzeneStatus before passing it here.');
+        }
+        const result = create(problem.benzeneStatus, voidPayload, [...(problem.errors ?? [])], false);
+        // The authored document travels alongside the result so the response mapper emits it verbatim
+        // rather than re-deriving one from the status - otherwise an application-owned `type` would be
+        // overwritten by the registry URI on the way out.
+        result.problem = problem;
+        return result;
+    },
+    /**
+     * Builds a failed result for a problem document a CLIENT received off the wire - the port of C#
+     * `BenzeneResult.AttachReceivedProblem<T>` (internal there, reached from
+     * `Benzene.Clients.Common.ClientResultExtensions`; exported here because the clients live in another
+     * package). The status is the one the client decided - the document's `benzeneStatus` where it has one
+     * (wire-contracts §4.1), else the envelope/HTTP classification - and is taken as given here; `errors`
+     * are the ones rebuilt from the document
+     * (core-concepts §12 "Error fidelity", wire-contracts.md §1.3); and the document, when there is one,
+     * is attached so `ProblemTypes.from(result)` returns exactly what was received - an application's own
+     * problem `type` survives the hop.
+     */
+    receivedProblem(status, errors, problem) {
+        const result = create(status, voidPayload, [...errors], false);
+        if (problem !== undefined) {
+            result.problem = problem;
+        }
+        return result;
+    },
+    ok(payload) {
+        return exports.BenzeneResult.set(BenzeneResultStatus_1.BenzeneResultStatus.ok, payload);
+    },
+    created(payload) {
+        return exports.BenzeneResult.set(BenzeneResultStatus_1.BenzeneResultStatus.created, payload);
+    },
+    accepted(payload) {
+        return exports.BenzeneResult.set(BenzeneResultStatus_1.BenzeneResultStatus.accepted, payload);
+    },
+    updated(payload) {
+        return exports.BenzeneResult.set(BenzeneResultStatus_1.BenzeneResultStatus.updated, payload);
+    },
+    deleted(payload) {
+        return exports.BenzeneResult.set(BenzeneResultStatus_1.BenzeneResultStatus.deleted, payload);
+    },
+    ignored() {
+        return exports.BenzeneResult.set(BenzeneResultStatus_1.BenzeneResultStatus.ignored);
+    },
+    notFound(...errors) {
+        return exports.BenzeneResult.setErrors(BenzeneResultStatus_1.BenzeneResultStatus.notFound, ...errors);
+    },
+    badRequest(...errors) {
+        return exports.BenzeneResult.setErrors(BenzeneResultStatus_1.BenzeneResultStatus.badRequest, ...errors);
+    },
+    unauthorized(...errors) {
+        return exports.BenzeneResult.setErrors(BenzeneResultStatus_1.BenzeneResultStatus.unauthorized, ...errors);
+    },
+    forbidden(...errors) {
+        return exports.BenzeneResult.setErrors(BenzeneResultStatus_1.BenzeneResultStatus.forbidden, ...errors);
+    },
+    validationError(...errors) {
+        return exports.BenzeneResult.setErrors(BenzeneResultStatus_1.BenzeneResultStatus.validationError, ...errors);
+    },
+    serviceUnavailable(...errors) {
+        return exports.BenzeneResult.setErrors(BenzeneResultStatus_1.BenzeneResultStatus.serviceUnavailable, ...errors);
+    },
+    tooManyRequests(...errors) {
+        return exports.BenzeneResult.setErrors(BenzeneResultStatus_1.BenzeneResultStatus.tooManyRequests, ...errors);
+    },
+    unexpectedError(...errors) {
+        return exports.BenzeneResult.setErrors(BenzeneResultStatus_1.BenzeneResultStatus.unexpectedError, ...errors);
+    },
+};

package/dist/BenzeneResultExtensions.d.ts

@@ -0,0 +1,14 @@
+import { IBenzeneResultOf, VoidResult } from '@benzenejs/abstractions';
+/**
+ * Free-function ports of the `Benzene.Results.BenzeneResultExtensions` C# extension methods.
+ *
+ * Only the HTTP-status reverse mapping (`Convert(this HttpStatusCode)`) is ported here so far — the
+ * client-side mapping of an HTTP response code back to a Benzene result status
+ * (`wire-contracts.md` §4.1, the "reverse" table). The `As`/`AsTask` result-shape helpers are ported
+ * elsewhere as they are needed.
+ *
+ * TS bend: .NET keys the switch on the `System.Net.HttpStatusCode` enum; TypeScript has no such enum,
+ * so the port takes the numeric status code directly (`convertHttpStatusCode(204)`), which is how the
+ * conformance runner and HTTP clients already carry it. The mapping is byte-for-byte the same table.
+ */
+export declare function convertHttpStatusCode(httpStatusCode: number): IBenzeneResultOf<VoidResult>;

package/dist/BenzeneResultExtensions.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertHttpStatusCode = convertHttpStatusCode;
+const BenzeneResult_1 = require("./BenzeneResult");
+const BenzeneResultStatus_1 = require("./BenzeneResultStatus");
+/**
+ * Free-function ports of the `Benzene.Results.BenzeneResultExtensions` C# extension methods.
+ *
+ * Only the HTTP-status reverse mapping (`Convert(this HttpStatusCode)`) is ported here so far — the
+ * client-side mapping of an HTTP response code back to a Benzene result status
+ * (`wire-contracts.md` §4.1, the "reverse" table). The `As`/`AsTask` result-shape helpers are ported
+ * elsewhere as they are needed.
+ *
+ * TS bend: .NET keys the switch on the `System.Net.HttpStatusCode` enum; TypeScript has no such enum,
+ * so the port takes the numeric status code directly (`convertHttpStatusCode(204)`), which is how the
+ * conformance runner and HTTP clients already carry it. The mapping is byte-for-byte the same table.
+ */
+function convertHttpStatusCode(httpStatusCode) {
+    switch (httpStatusCode) {
+        case 202:
+            return BenzeneResult_1.BenzeneResult.accepted();
+        case 200:
+            return BenzeneResult_1.BenzeneResult.ok();
+        case 201:
+            return BenzeneResult_1.BenzeneResult.created();
+        case 204:
+            return BenzeneResult_1.BenzeneResult.deleted();
+        case 404:
+            return BenzeneResult_1.BenzeneResult.notFound();
+        case 400:
+            return BenzeneResult_1.BenzeneResult.badRequest();
+        case 409:
+            return BenzeneResult_1.BenzeneResult.setErrors(BenzeneResultStatus_1.BenzeneResultStatus.conflict);
+        case 403:
+            return BenzeneResult_1.BenzeneResult.forbidden();
+        case 401:
+            return BenzeneResult_1.BenzeneResult.unauthorized();
+        case 422:
+            return BenzeneResult_1.BenzeneResult.validationError();
+        case 429:
+            return BenzeneResult_1.BenzeneResult.tooManyRequests();
+        case 408:
+            return BenzeneResult_1.BenzeneResult.setErrors(BenzeneResultStatus_1.BenzeneResultStatus.timeout);
+        case 504:
+            return BenzeneResult_1.BenzeneResult.setErrors(BenzeneResultStatus_1.BenzeneResultStatus.timeout);
+        case 501:
+            return BenzeneResult_1.BenzeneResult.setErrors(BenzeneResultStatus_1.BenzeneResultStatus.notImplemented);
+        case 502:
+            return BenzeneResult_1.BenzeneResult.serviceUnavailable();
+        case 503:
+            return BenzeneResult_1.BenzeneResult.serviceUnavailable();
+        default:
+            return BenzeneResult_1.BenzeneResult.unexpectedError();
+    }
+}

package/dist/BenzeneResultStatus.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Well-known result statuses and their success/failure classification.
+ * Port of Benzene.Results.BenzeneResultStatus.
+ *
+ * The string VALUES are the normative **wire** status vocabulary from `docs/specification/wire-contracts.md`
+ * §3 - lowercase-kebab-case and case-sensitive (`ok`, `not-found`, `validation-error`), identical to the
+ * .NET constants. This is a cross-language contract: a Benzene service in any language writes these exact
+ * strings as the response envelope's `statusCode`, so a TypeScript service and a .NET service (or mesh
+ * aggregator) reading each other's responses classify statuses identically.
+ */
+export declare const BenzeneResultStatus: {
+    readonly accepted: "accepted";
+    readonly ok: "ok";
+    readonly created: "created";
+    readonly updated: "updated";
+    readonly deleted: "deleted";
+    readonly ignored: "ignored";
+    readonly notFound: "not-found";
+    readonly badRequest: "bad-request";
+    readonly validationError: "validation-error";
+    readonly serviceUnavailable: "service-unavailable";
+    readonly notImplemented: "not-implemented";
+    readonly unexpectedError: "unexpected-error";
+    readonly conflict: "conflict";
+    readonly forbidden: "forbidden";
+    readonly unauthorized: "unauthorized";
+    readonly tooManyRequests: "too-many-requests";
+    readonly timeout: "timeout";
+    readonly isSuccess: (status: string | undefined) => boolean;
+    readonly isFailure: (status: string | undefined) => boolean;
+    readonly isKnown: (status: string | undefined) => boolean;
+    readonly isTransient: (status: string | undefined) => boolean;
+};

package/dist/BenzeneResultStatus.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BenzeneResultStatus = void 0;
+/**
+ * Well-known result statuses and their success/failure classification.
+ * Port of Benzene.Results.BenzeneResultStatus.
+ *
+ * The string VALUES are the normative **wire** status vocabulary from `docs/specification/wire-contracts.md`
+ * §3 - lowercase-kebab-case and case-sensitive (`ok`, `not-found`, `validation-error`), identical to the
+ * .NET constants. This is a cross-language contract: a Benzene service in any language writes these exact
+ * strings as the response envelope's `statusCode`, so a TypeScript service and a .NET service (or mesh
+ * aggregator) reading each other's responses classify statuses identically.
+ */
+exports.BenzeneResultStatus = {
+    accepted: 'accepted',
+    ok: 'ok',
+    created: 'created',
+    updated: 'updated',
+    deleted: 'deleted',
+    ignored: 'ignored',
+    notFound: 'not-found',
+    badRequest: 'bad-request',
+    validationError: 'validation-error',
+    serviceUnavailable: 'service-unavailable',
+    notImplemented: 'not-implemented',
+    unexpectedError: 'unexpected-error',
+    conflict: 'conflict',
+    forbidden: 'forbidden',
+    unauthorized: 'unauthorized',
+    tooManyRequests: 'too-many-requests',
+    timeout: 'timeout',
+    isSuccess(status) {
+        return status !== undefined && successStatuses.has(status);
+    },
+    isFailure(status) {
+        return status !== undefined && failureStatuses.has(status);
+    },
+    isKnown(status) {
+        return exports.BenzeneResultStatus.isSuccess(status) || exports.BenzeneResultStatus.isFailure(status);
+    },
+    isTransient(status) {
+        return status !== undefined && transientStatuses.has(status);
+    },
+};
+const successStatuses = new Set(['ok', 'created', 'accepted', 'updated', 'deleted', 'ignored']);
+const failureStatuses = new Set([
+    'bad-request',
+    'validation-error',
+    'unauthorized',
+    'forbidden',
+    'not-found',
+    'conflict',
+    'too-many-requests',
+    'timeout',
+    'not-implemented',
+    'service-unavailable',
+    'unexpected-error',
+]);
+const transientStatuses = new Set(['service-unavailable', 'too-many-requests', 'timeout']);

package/dist/ProblemDetails.d.ts

@@ -0,0 +1,52 @@
+import { BenzeneError } from '@benzenejs/abstractions';
+/**
+ * An [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem document — the body of a failed
+ * result (wire-contracts.md §1.3). Port of Benzene.Results.ProblemDetails.
+ *
+ * Deviation: C# declares nullable auto-properties with `[JsonIgnore(WhenWritingNull)]`; the port
+ * types them optional (`| undefined`) so an unset member is simply omitted by `JSON.stringify`
+ * rather than serialized as an explicit `null` the way System.Text.Json would.
+ */
+export declare class ProblemDetails {
+    /**
+     * A URI reference identifying the problem *type*. Framework-produced failures use the registry
+     * URI for the status (`ProblemTypes`); applications should use their own absolute URI. Readers
+     * treat it as an **opaque identifier** — compare by string equality, never dereference.
+     */
+    type: string | undefined;
+    /** A short human summary of the *type*, fixed per type. Wording is never asserted by fixtures. */
+    title: string | undefined;
+    /**
+     * The **HTTP** response status code — HTTP bindings only, and a `number`, not the Benzene status.
+     * Must equal the actual HTTP response status when present, and must be **omitted** where no HTTP
+     * response exists (an envelope over a queue), which is why it is filled in by the HTTP-aware
+     * response mapper rather than by the transport-neutral `ProblemTypes.from`. Clients must not
+     * classify success/failure from this member — classification is envelope-first (§1.2).
+     */
+    status: number | undefined;
+    /**
+     * Human-readable detail for this occurrence — the result's error messages joined with `", "`.
+     * The compatibility member: every reader of the pre-RFC-9457 `ErrorPayload` shape used only this
+     * one and keeps working unchanged.
+     */
+    detail: string | undefined;
+    /** Optional, application-owned. The framework never fabricates a value. */
+    instance: string | undefined;
+    /**
+     * **Required on framework-produced documents.** The Benzene status string (§3), mirroring the
+     * envelope's `statusCode`. This is the transport-neutral discriminator — present on every
+     * transport, whereas {@link status} only exists on HTTP.
+     *
+     * It replaced a `status: string` member that carried the Benzene status and collided with RFC
+     * 9457's own `status` (defined as the integer HTTP code). The collision was resolved by rename,
+     * not by dropping the RFC alignment. The `benzene` marker is there because this member namespace
+     * is shared with RFC 9457 itself and with applications.
+     */
+    benzeneStatus: string | undefined;
+    /**
+     * The result's errors, when present — authoritative and ordered. Omitted from the wire when the
+     * result carries none; a reader without this member treats {@link detail} as a single opaque
+     * message.
+     */
+    errors: BenzeneError[] | undefined;
+}

package/dist/ProblemDetails.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProblemDetails = void 0;
+/**
+ * An [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem document — the body of a failed
+ * result (wire-contracts.md §1.3). Port of Benzene.Results.ProblemDetails.
+ *
+ * Deviation: C# declares nullable auto-properties with `[JsonIgnore(WhenWritingNull)]`; the port
+ * types them optional (`| undefined`) so an unset member is simply omitted by `JSON.stringify`
+ * rather than serialized as an explicit `null` the way System.Text.Json would.
+ */
+class ProblemDetails {
+    /**
+     * A URI reference identifying the problem *type*. Framework-produced failures use the registry
+     * URI for the status (`ProblemTypes`); applications should use their own absolute URI. Readers
+     * treat it as an **opaque identifier** — compare by string equality, never dereference.
+     */
+    type;
+    /** A short human summary of the *type*, fixed per type. Wording is never asserted by fixtures. */
+    title;
+    /**
+     * The **HTTP** response status code — HTTP bindings only, and a `number`, not the Benzene status.
+     * Must equal the actual HTTP response status when present, and must be **omitted** where no HTTP
+     * response exists (an envelope over a queue), which is why it is filled in by the HTTP-aware
+     * response mapper rather than by the transport-neutral `ProblemTypes.from`. Clients must not
+     * classify success/failure from this member — classification is envelope-first (§1.2).
+     */
+    status;
+    /**
+     * Human-readable detail for this occurrence — the result's error messages joined with `", "`.
+     * The compatibility member: every reader of the pre-RFC-9457 `ErrorPayload` shape used only this
+     * one and keeps working unchanged.
+     */
+    detail;
+    /** Optional, application-owned. The framework never fabricates a value. */
+    instance;
+    /**
+     * **Required on framework-produced documents.** The Benzene status string (§3), mirroring the
+     * envelope's `statusCode`. This is the transport-neutral discriminator — present on every
+     * transport, whereas {@link status} only exists on HTTP.
+     *
+     * It replaced a `status: string` member that carried the Benzene status and collided with RFC
+     * 9457's own `status` (defined as the integer HTTP code). The collision was resolved by rename,
+     * not by dropping the RFC alignment. The `benzene` marker is there because this member namespace
+     * is shared with RFC 9457 itself and with applications.
+     */
+    benzeneStatus;
+    /**
+     * The result's errors, when present — authoritative and ordered. Omitted from the wire when the
+     * result carries none; a reader without this member treats {@link detail} as a single opaque
+     * message.
+     */
+    errors;
+}
+exports.ProblemDetails = ProblemDetails;

package/dist/ProblemTypes.d.ts

@@ -0,0 +1,58 @@
+import { IBenzeneResult } from '@benzenejs/abstractions';
+import { ProblemDetails } from './ProblemDetails';
+export declare const ProblemTypes: {
+    /** The {@link ProblemDetails.type} URI for `bad-request`. */
+    readonly badRequest: "https://benzene.app/problems/bad-request";
+    /** The {@link ProblemDetails.type} URI for `unauthorized`. */
+    readonly unauthorized: "https://benzene.app/problems/unauthorized";
+    /** The {@link ProblemDetails.type} URI for `forbidden`. */
+    readonly forbidden: "https://benzene.app/problems/forbidden";
+    /** The {@link ProblemDetails.type} URI for `not-found`. */
+    readonly notFound: "https://benzene.app/problems/not-found";
+    /** The {@link ProblemDetails.type} URI for `conflict`. */
+    readonly conflict: "https://benzene.app/problems/conflict";
+    /** The {@link ProblemDetails.type} URI for `validation-error`. */
+    readonly validationError: "https://benzene.app/problems/validation-error";
+    /** The {@link ProblemDetails.type} URI for `too-many-requests`. */
+    readonly tooManyRequests: "https://benzene.app/problems/too-many-requests";
+    /** The {@link ProblemDetails.type} URI for `unexpected-error`. */
+    readonly unexpectedError: "https://benzene.app/problems/unexpected-error";
+    /** The {@link ProblemDetails.type} URI for `not-implemented`. */
+    readonly notImplemented: "https://benzene.app/problems/not-implemented";
+    /** The {@link ProblemDetails.type} URI for `service-unavailable`. */
+    readonly serviceUnavailable: "https://benzene.app/problems/service-unavailable";
+    /** The {@link ProblemDetails.type} URI for `timeout`. */
+    readonly timeout: "https://benzene.app/problems/timeout";
+    /**
+     * The registry {@link ProblemDetails.type} URI for `status`, or `undefined` for an
+     * application-defined status the registry doesn't know (the application owns its own `type`, or
+     * omits one).
+     */
+    readonly typeFor: (status: string | undefined) => string | undefined;
+    /**
+     * The registry {@link ProblemDetails.title} for `status`, or `undefined` for an
+     * application-defined status the registry doesn't know.
+     */
+    readonly titleFor: (status: string | undefined) => string | undefined;
+    /**
+     * The HTTP status code the registry maps `status` to, or `500` for an application-defined status —
+     * the same "unknown status falls to the generic-error row" rule the {@link BenzeneResultStatus}-based
+     * HTTP mappings use elsewhere (e.g. `DefaultHttpStatusCodeMapper`).
+     */
+    readonly httpStatusFor: (status: string | undefined) => number;
+    /**
+     * Builds the problem document for a failed `result`: {@link ProblemDetails.type}/
+     * {@link ProblemDetails.title} from the registry (both `undefined` for an application-defined
+     * status), {@link ProblemDetails.detail} as the result's error messages joined with `", "`,
+     * {@link ProblemDetails.benzeneStatus} as the result's status, and {@link ProblemDetails.errors}
+     * as the result's structured errors when non-empty (else `undefined`, so the member is omitted
+     * from the wire). Deliberately never sets {@link ProblemDetails.status} — the numeric HTTP status
+     * is an HTTP-binding concern, filled in by the HTTP-aware response mapper, not this
+     * transport-neutral factory.
+     *
+     * A result built by `BenzeneResult.problem(...)` carries its authored document, which is returned
+     * verbatim: re-deriving one here would overwrite an application-owned `type` with the registry
+     * URI, which is the whole reason that factory exists (wire-contracts.md §1.3).
+     */
+    readonly from: (result: IBenzeneResult) => ProblemDetails;
+};

package/dist/ProblemTypes.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProblemTypes = void 0;
+const BenzeneResultStatus_1 = require("./BenzeneResultStatus");
+const ProblemDetails_1 = require("./ProblemDetails");
+/**
+ * The problem-type registry: `type` URI / `title` / HTTP status keyed by the existing
+ * {@link BenzeneResultStatus} failure vocabulary — no new taxonomy (see
+ * `docs/specification/wire-contracts.md` §3.1 in the cross-language Benzene spec repo).
+ * Port of Benzene.Results.ProblemTypes.
+ *
+ * A pure, static, spec-pinned table, matching {@link BenzeneResultStatus}'s own pattern: C#'s
+ * `static class` of `const string` members plus static methods collapses into a frozen object
+ * literal here.
+ */
+const baseUri = 'https://benzene.app/problems/';
+const unknownHttpStatus = 500;
+// One row per failure status (docs/specification/wire-contracts.md §3.1). Success statuses have no
+// problem type - problems exist only on failure - so they're deliberately absent here.
+const registry = {
+    [BenzeneResultStatus_1.BenzeneResultStatus.badRequest]: { type: `${baseUri}bad-request`, title: 'Bad request', httpStatus: 400 },
+    [BenzeneResultStatus_1.BenzeneResultStatus.unauthorized]: { type: `${baseUri}unauthorized`, title: 'Unauthorized', httpStatus: 401 },
+    [BenzeneResultStatus_1.BenzeneResultStatus.forbidden]: { type: `${baseUri}forbidden`, title: 'Forbidden', httpStatus: 403 },
+    [BenzeneResultStatus_1.BenzeneResultStatus.notFound]: { type: `${baseUri}not-found`, title: 'Not found', httpStatus: 404 },
+    [BenzeneResultStatus_1.BenzeneResultStatus.conflict]: { type: `${baseUri}conflict`, title: 'Conflict', httpStatus: 409 },
+    [BenzeneResultStatus_1.BenzeneResultStatus.validationError]: { type: `${baseUri}validation-error`, title: 'Validation failed', httpStatus: 422 },
+    [BenzeneResultStatus_1.BenzeneResultStatus.tooManyRequests]: { type: `${baseUri}too-many-requests`, title: 'Too many requests', httpStatus: 429 },
+    [BenzeneResultStatus_1.BenzeneResultStatus.unexpectedError]: { type: `${baseUri}unexpected-error`, title: 'Unexpected error', httpStatus: 500 },
+    [BenzeneResultStatus_1.BenzeneResultStatus.notImplemented]: { type: `${baseUri}not-implemented`, title: 'Not implemented', httpStatus: 501 },
+    [BenzeneResultStatus_1.BenzeneResultStatus.serviceUnavailable]: { type: `${baseUri}service-unavailable`, title: 'Service unavailable', httpStatus: 503 },
+    [BenzeneResultStatus_1.BenzeneResultStatus.timeout]: { type: `${baseUri}timeout`, title: 'Timeout', httpStatus: 504 },
+};
+function rowFor(status) {
+    return status === undefined ? undefined : registry[status];
+}
+exports.ProblemTypes = {
+    /** The {@link ProblemDetails.type} URI for `bad-request`. */
+    badRequest: `${baseUri}bad-request`,
+    /** The {@link ProblemDetails.type} URI for `unauthorized`. */
+    unauthorized: `${baseUri}unauthorized`,
+    /** The {@link ProblemDetails.type} URI for `forbidden`. */
+    forbidden: `${baseUri}forbidden`,
+    /** The {@link ProblemDetails.type} URI for `not-found`. */
+    notFound: `${baseUri}not-found`,
+    /** The {@link ProblemDetails.type} URI for `conflict`. */
+    conflict: `${baseUri}conflict`,
+    /** The {@link ProblemDetails.type} URI for `validation-error`. */
+    validationError: `${baseUri}validation-error`,
+    /** The {@link ProblemDetails.type} URI for `too-many-requests`. */
+    tooManyRequests: `${baseUri}too-many-requests`,
+    /** The {@link ProblemDetails.type} URI for `unexpected-error`. */
+    unexpectedError: `${baseUri}unexpected-error`,
+    /** The {@link ProblemDetails.type} URI for `not-implemented`. */
+    notImplemented: `${baseUri}not-implemented`,
+    /** The {@link ProblemDetails.type} URI for `service-unavailable`. */
+    serviceUnavailable: `${baseUri}service-unavailable`,
+    /** The {@link ProblemDetails.type} URI for `timeout`. */
+    timeout: `${baseUri}timeout`,
+    /**
+     * The registry {@link ProblemDetails.type} URI for `status`, or `undefined` for an
+     * application-defined status the registry doesn't know (the application owns its own `type`, or
+     * omits one).
+     */
+    typeFor(status) {
+        return rowFor(status)?.type;
+    },
+    /**
+     * The registry {@link ProblemDetails.title} for `status`, or `undefined` for an
+     * application-defined status the registry doesn't know.
+     */
+    titleFor(status) {
+        return rowFor(status)?.title;
+    },
+    /**
+     * The HTTP status code the registry maps `status` to, or `500` for an application-defined status —
+     * the same "unknown status falls to the generic-error row" rule the {@link BenzeneResultStatus}-based
+     * HTTP mappings use elsewhere (e.g. `DefaultHttpStatusCodeMapper`).
+     */
+    httpStatusFor(status) {
+        return rowFor(status)?.httpStatus ?? unknownHttpStatus;
+    },
+    /**
+     * Builds the problem document for a failed `result`: {@link ProblemDetails.type}/
+     * {@link ProblemDetails.title} from the registry (both `undefined` for an application-defined
+     * status), {@link ProblemDetails.detail} as the result's error messages joined with `", "`,
+     * {@link ProblemDetails.benzeneStatus} as the result's status, and {@link ProblemDetails.errors}
+     * as the result's structured errors when non-empty (else `undefined`, so the member is omitted
+     * from the wire). Deliberately never sets {@link ProblemDetails.status} — the numeric HTTP status
+     * is an HTTP-binding concern, filled in by the HTTP-aware response mapper, not this
+     * transport-neutral factory.
+     *
+     * A result built by `BenzeneResult.problem(...)` carries its authored document, which is returned
+     * verbatim: re-deriving one here would overwrite an application-owned `type` with the registry
+     * URI, which is the whole reason that factory exists (wire-contracts.md §1.3).
+     */
+    from(result) {
+        const authored = result.problem;
+        if (authored !== undefined) {
+            return authored;
+        }
+        const errors = result.errors ?? [];
+        const detail = errors.map((error) => error.message).join(', ');
+        const problem = new ProblemDetails_1.ProblemDetails();
+        problem.type = exports.ProblemTypes.typeFor(result.status);
+        problem.title = exports.ProblemTypes.titleFor(result.status);
+        problem.detail = detail === '' ? undefined : detail;
+        problem.benzeneStatus = result.status;
+        problem.errors = errors.length > 0 ? [...errors] : undefined;
+        return problem;
+    },
+};

package/dist/TransportFailure.d.ts

@@ -0,0 +1,40 @@
+import { IBenzeneResultOf } from '@benzenejs/abstractions';
+/**
+ * transport-bindings.md §1 (spec 1.1): a send that fails in transport - no connection, a refused or reset
+ * request, the client's own deadline - before any reply arrives (or, for a one-way client, before the broker
+ * accepts the message) SHOULD yield a result rather than an exception: `timeout` when the deadline elapsed,
+ * otherwise `service-unavailable`, so a caller handles a dead peer as it handles every other failure. These
+ * functions are that rule, shared by every client in the port - reply-receiving and one-way alike.
+ *
+ * What counts as "the deadline elapsed", for the errors a Node client actually sees:
+ * - an aborted call (`AbortError`, or the `TimeoutError` an `AbortSignal.timeout(ms)` aborts with): in
+ *   JavaScript an `AbortSignal` is how a caller bounds a `fetch` (it has no timeout option of its own), so an
+ *   abort is the caller's own deadline;
+ * - an error whose name ends in `TimeoutError` (the AWS SDK's request/connection timeouts, kafkajs's
+ *   `KafkaJSRequestTimeoutError`);
+ * - a timeout code: undici/Node's (`UND_ERR_CONNECT_TIMEOUT`, `UND_ERR_HEADERS_TIMEOUT`, `UND_ERR_BODY_TIMEOUT`,
+ *   `ETIMEDOUT`, `ESOCKETTIMEDOUT`) or the Azure messaging SDKs' (`ServiceTimeout`, `OperationTimeoutError`);
+ * - a gRPC-shaped error (numeric `code` beside a string `details`, as the Pub/Sub client throws) whose code is
+ *   4, `DEADLINE_EXCEEDED`;
+ *
+ * each looked for on the error and its `cause` chain - `fetch` rejects with `TypeError('fetch failed')` and
+ * puts the socket error in `cause`.
+ *
+ * Everything else - `ECONNREFUSED`, `ECONNRESET`, a DNS failure, a TLS failure - is `service-unavailable`.
+ */
+export declare function transportFailureStatus(error: unknown): string;
+/**
+ * The failed result for a call that failed before any reply arrived: {@link transportFailureStatus}'s status,
+ * with one error carrying the failure's message (and its `cause`'s, which is where `fetch` puts the socket
+ * error), so the reason is not lost with the exception.
+ */
+export declare function transportFailureResult<T>(error: unknown): IBenzeneResultOf<T>;
+/**
+ * The result for a one-way send whose SDK call rejected. When the broker itself answered - an AWS SDK service
+ * exception (`$metadata.httpStatusCode`) or an Azure `RestError` (`statusCode`), 400 or above - the message
+ * was refused, not lost in transport, so that native status maps through the reverse HTTP table
+ * (wire-contracts §4.1: `403` → `forbidden`, `404` → `not-found`, `429` → `too-many-requests`, ...).
+ * Otherwise the send failed before the broker accepted it: {@link transportFailureResult}. Either way the
+ * one error carries the failure's message.
+ */
+export declare function failedSendResult<T>(error: unknown): IBenzeneResultOf<T>;

package/dist/TransportFailure.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transportFailureStatus = transportFailureStatus;
+exports.transportFailureResult = transportFailureResult;
+exports.failedSendResult = failedSendResult;
+const BenzeneResult_1 = require("./BenzeneResult");
+const BenzeneResultExtensions_1 = require("./BenzeneResultExtensions");
+const BenzeneResultStatus_1 = require("./BenzeneResultStatus");
+/**
+ * transport-bindings.md §1 (spec 1.1): a send that fails in transport - no connection, a refused or reset
+ * request, the client's own deadline - before any reply arrives (or, for a one-way client, before the broker
+ * accepts the message) SHOULD yield a result rather than an exception: `timeout` when the deadline elapsed,
+ * otherwise `service-unavailable`, so a caller handles a dead peer as it handles every other failure. These
+ * functions are that rule, shared by every client in the port - reply-receiving and one-way alike.
+ *
+ * What counts as "the deadline elapsed", for the errors a Node client actually sees:
+ * - an aborted call (`AbortError`, or the `TimeoutError` an `AbortSignal.timeout(ms)` aborts with): in
+ *   JavaScript an `AbortSignal` is how a caller bounds a `fetch` (it has no timeout option of its own), so an
+ *   abort is the caller's own deadline;
+ * - an error whose name ends in `TimeoutError` (the AWS SDK's request/connection timeouts, kafkajs's
+ *   `KafkaJSRequestTimeoutError`);
+ * - a timeout code: undici/Node's (`UND_ERR_CONNECT_TIMEOUT`, `UND_ERR_HEADERS_TIMEOUT`, `UND_ERR_BODY_TIMEOUT`,
+ *   `ETIMEDOUT`, `ESOCKETTIMEDOUT`) or the Azure messaging SDKs' (`ServiceTimeout`, `OperationTimeoutError`);
+ * - a gRPC-shaped error (numeric `code` beside a string `details`, as the Pub/Sub client throws) whose code is
+ *   4, `DEADLINE_EXCEEDED`;
+ *
+ * each looked for on the error and its `cause` chain - `fetch` rejects with `TypeError('fetch failed')` and
+ * puts the socket error in `cause`.
+ *
+ * Everything else - `ECONNREFUSED`, `ECONNRESET`, a DNS failure, a TLS failure - is `service-unavailable`.
+ */
+function transportFailureStatus(error) {
+    for (const link of causeChain(error)) {
+        if (typeof link !== 'object' || link === null) {
+            continue;
+        }
+        const { name, code, details } = link;
+        if (name === 'AbortError' || (typeof name === 'string' && name.endsWith('TimeoutError'))) {
+            return BenzeneResultStatus_1.BenzeneResultStatus.timeout;
+        }
+        if (typeof code === 'string' && TimeoutCodes.has(code)) {
+            return BenzeneResultStatus_1.BenzeneResultStatus.timeout;
+        }
+        if (code === GrpcDeadlineExceeded && typeof details === 'string') {
+            return BenzeneResultStatus_1.BenzeneResultStatus.timeout;
+        }
+    }
+    return BenzeneResultStatus_1.BenzeneResultStatus.serviceUnavailable;
+}
+/**
+ * The failed result for a call that failed before any reply arrived: {@link transportFailureStatus}'s status,
+ * with one error carrying the failure's message (and its `cause`'s, which is where `fetch` puts the socket
+ * error), so the reason is not lost with the exception.
+ */
+function transportFailureResult(error) {
+    return BenzeneResult_1.BenzeneResult.setErrors(transportFailureStatus(error), transportFailureMessage(error));
+}
+/**
+ * The result for a one-way send whose SDK call rejected. When the broker itself answered - an AWS SDK service
+ * exception (`$metadata.httpStatusCode`) or an Azure `RestError` (`statusCode`), 400 or above - the message
+ * was refused, not lost in transport, so that native status maps through the reverse HTTP table
+ * (wire-contracts §4.1: `403` → `forbidden`, `404` → `not-found`, `429` → `too-many-requests`, ...).
+ * Otherwise the send failed before the broker accepted it: {@link transportFailureResult}. Either way the
+ * one error carries the failure's message.
+ */
+function failedSendResult(error) {
+    const brokerStatus = brokerHttpStatus(error);
+    return brokerStatus === undefined
+        ? transportFailureResult(error)
+        : BenzeneResult_1.BenzeneResult.setErrors((0, BenzeneResultExtensions_1.convertHttpStatusCode)(brokerStatus).status, transportFailureMessage(error));
+}
+/** The HTTP status a broker answered a rejected SDK call with, when it answered at all. */
+function brokerHttpStatus(error) {
+    if (typeof error !== 'object' || error === null) {
+        return undefined;
+    }
+    const { $metadata, statusCode } = error;
+    const status = $metadata?.httpStatusCode ?? statusCode;
+    return typeof status === 'number' && status >= 400 ? status : undefined;
+}
+const TimeoutCodes = new Set([
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_BODY_TIMEOUT',
+    'ETIMEDOUT',
+    'ESOCKETTIMEDOUT',
+    'ServiceTimeout',
+    'OperationTimeoutError',
+]);
+/** gRPC's `DEADLINE_EXCEEDED`. */
+const GrpcDeadlineExceeded = 4;
+function transportFailureMessage(error) {
+    const messages = [];
+    for (const link of causeChain(error)) {
+        const message = link instanceof Error ? link.message : typeof link === 'string' ? link : undefined;
+        if (message !== undefined && message !== '' && !messages.includes(message)) {
+            messages.push(message);
+        }
+    }
+    return messages.length > 0 ? messages.join(': ') : 'The call failed before any reply arrived';
+}
+/** `error`, then each `cause` beneath it (bounded, so a cyclic chain cannot loop). */
+function causeChain(error) {
+    const chain = [];
+    let current = error;
+    while (current !== undefined && current !== null && chain.length < 8 && !chain.includes(current)) {
+        chain.push(current);
+        current = typeof current === 'object' ? current.cause : undefined;
+    }
+    return chain;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { BenzeneError } from '@benzenejs/abstractions';
+export * from './BenzeneResult';
+export * from './BenzeneResultExtensions';
+export * from './BenzeneResultStatus';
+export * from './ProblemDetails';
+export * from './ProblemTypes';
+export * from './TransportFailure';

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./BenzeneResult"), exports);
+__exportStar(require("./BenzeneResultExtensions"), exports);
+__exportStar(require("./BenzeneResultStatus"), exports);
+__exportStar(require("./ProblemDetails"), exports);
+__exportStar(require("./ProblemTypes"), exports);
+__exportStar(require("./TransportFailure"), exports);

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@benzenejs/results",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.2",
+  "description": "TypeScript port of Benzene.Results",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@benzenejs/abstractions": "0.1.0-beta.2"
+  },
+  "files": [
+    "dist"
+  ]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.