nest-result 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mannkostir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,196 @@
-# Temporary Holding Version
+# nest-result
 
-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.
+Return typed errors from your NestJS handlers and let the compiler prove every one of them is mapped to an HTTP response.
+
+Built on [neverthrow](https://github.com/supermacro/neverthrow). Works with Express and Fastify, NestJS 11 and 12.
+
+**Status: pre-1.0 (`0.1.0`).** The public API may still change between versions.
+
+```bash
+npm install nest-result neverthrow
+```
+
+## In 60 seconds
+
+```ts
+import { Controller, Injectable, Module, Param, Post } from '@nestjs/common';
+import { TaggedError, MapErrors, ResultModule } from 'nest-result';
+import { err, ok, type Result } from 'neverthrow';
+
+export type Deal = { id: string; closed: boolean };
+
+export class DealNotFound extends TaggedError('DealNotFound')<{ dealId: string }> {}
+export class DealAlreadyClosed extends TaggedError('DealAlreadyClosed') {}
+
+@Injectable()
+export class DealsService {
+  private readonly deals = new Map<string, Deal>([['1', { id: '1', closed: false }]]);
+
+  close(id: string): Result<Deal, DealNotFound | DealAlreadyClosed> {
+    const deal = this.deals.get(id);
+    if (deal === undefined) return err(new DealNotFound({ dealId: id }));
+    if (deal.closed) return err(new DealAlreadyClosed());
+    return ok({ ...deal, closed: true });
+  }
+}
+
+@Controller('deals')
+export class DealsController {
+  constructor(private readonly deals: DealsService) {}
+
+  @Post(':id/close')
+  @MapErrors({ DealNotFound: 404, DealAlreadyClosed: 409 })
+  close(@Param('id') id: string): Result<Deal, DealNotFound | DealAlreadyClosed> {
+    return this.deals.close(id);
+  }
+}
+
+@Module({ imports: [ResultModule.forRoot()], controllers: [DealsController], providers: [DealsService] })
+export class AppModule {}
+```
+
+An `Ok` becomes the response body. An `Err` becomes its mapped status with this body:
+
+```json
+{ "statusCode": 409, "code": "DealAlreadyClosed", "message": "DealAlreadyClosed" }
+```
+
+Now add a third error to the service's return type and forget to map it. The build fails:
+
+```
+error TS1241: Unable to resolve signature of method decorator when called as an expression.
+  ...
+    Property '__missingErrorMapKeys' is missing in type ... but required in type 'MissingErrorMapKeys<"DealLocked">'.
+```
+
+Map a tag that can no longer happen and you get `StaleErrorMapKeys<"...">`. Return a plain `Error` and you get `UntaggedErrorsCannotBeMapped<Error>`.
+
+With `toHttp` a missing key shows as TypeScript's own `Property 'DealLocked' is missing in type ... but required in type ...` error instead of `MissingErrorMapKeys<...>`.
+
+## Tagged errors
+
+Any value with a literal `_tag` is a tagged error. `TaggedError` is a convenience, not a requirement:
+
+```ts
+class RateLimited extends TaggedError('RateLimited')<{ retryAfter: number; message: string }> {}
+const plain = { _tag: 'RateLimited' } as const;
+```
+
+`TaggedError` instances are real `Error`s with a stack trace, `name` equal to the tag, and `message` defaulting to the tag. Payloads may not declare `_tag` or `name`.
+
+The default error body is `statusCode`, `code` (the tag) and `message`. No other payload field is ever sent to the client. `message` is sent as-is, so for internal failures use a fixed message or a custom `body` rather than passing through driver or exception text.
+
+## Mapping errors
+
+### In the controller body: `toHttp`
+
+```ts
+@Get(':id')
+find(@Param('id') id: string): Promise<Deal> {
+  return toHttp(this.deals.find(id), { DealNotFound: 404 });
+}
+```
+
+`toHttp` accepts a `Result`, `ResultAsync` or `Promise<Result>`. An `Err` is thrown as a regular `HttpException`, so your existing exception filters keep working.
+
+### As a decorator: `MapErrors`
+
+`MapErrors` checks the method's return type against the map and converts the Result in a route-level interceptor. Because it runs innermost, global interceptors such as `ClassSerializerInterceptor` see the unwrapped value.
+
+### Custom bodies
+
+```ts
+@MapErrors({
+  DealNotFound: { status: 404, body: (e: DealNotFound) => ({ dealId: e.dealId }) },
+  DealAlreadyClosed: 409,
+})
+```
+
+With `toHttp` the parameter type is inferred. With `MapErrors` annotate it; the annotation is checked against the method's actual error type.
+
+### The safety net: `ResultModule`
+
+`ResultModule.forRoot()` registers a global interceptor. A route that returns a Result without `MapErrors` fails with 500 and a logged `MissingErrorMapError` instead of leaking `{ "value": ... }` to the client. A Result from a second copy of neverthrow in your dependency tree fails the same way with `DuplicateNeverthrowError`.
+
+## Swagger
+
+```ts
+import { MapErrors } from 'nest-result/swagger';
+```
+
+Same decorator, plus one `@ApiResponse` per mapped status, listing the tags that share it. Requires `@nestjs/swagger`.
+
+## Transactions that roll back on Err
+
+With [`@nestjs-cls/transactional`](https://papooch.github.io/nestjs-cls/plugins/available-plugins/transactional), a transaction rolls back when the method throws. A method that returns `Err` does not throw, so its partial writes are committed. `nest-result/transactional` fixes that. It works with any adapter, because it relies only on `@nestjs-cls/transactional`'s rollback-on-throw, and it is tested against TypeORM:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { TransactionHost } from '@nestjs-cls/transactional';
+import { TransactionalAdapterTypeOrm } from '@nestjs-cls/transactional-adapter-typeorm';
+import { TransactionalResult } from 'nest-result/transactional';
+import { err, type Result } from 'neverthrow';
+import { DealEntity } from './deal.entity';
+import { type Deal, DealAlreadyClosed, DealNotFound } from './deals';
+
+@Injectable()
+export class DealsService {
+  constructor(private readonly txHost: TransactionHost<TransactionalAdapterTypeOrm>) {}
+
+  @TransactionalResult()
+  async close(id: string): Promise<Result<Deal, DealNotFound | DealAlreadyClosed>> {
+    await this.txHost.tx.getRepository(DealEntity).update(id, { closed: true });
+    return err(new DealAlreadyClosed());
+  }
+}
+```
+
+`Ok` commits, `Err` rolls back and is returned unchanged, and a thrown exception rolls back and is rethrown. `@TransactionalResult` takes the same arguments as `@Transactional` and requires the method to return `Promise<Result>`. For the `ResultAsync` style, use the function form:
+
+```ts
+withResultTransaction(this.txHost, () => this.repository.close(id), { propagation: Propagation.RequiresNew });
+```
+
+### Nested transactions
+
+With the default `Required` propagation, an inner method joins the outer transaction and its `Err` is returned to the outer method as a value. The outer method decides:
+
+- if it returns `Err` too, everything rolls back;
+- if it recovers and returns `Ok`, everything commits, including the inner method's writes made before it failed.
+
+To discard the inner work independently, use `Propagation.Nested` (a savepoint) or `Propagation.RequiresNew`.
+
+## Migrating from a hand-rolled interceptor
+
+1. Replace your error base class with `TaggedError(...)` subclasses, or add a literal `readonly _tag` to existing errors.
+2. Add `ResultModule.forRoot()` to your root module and delete your interceptor.
+3. Add `@MapErrors({...})` to each route that returns a Result; the compiler lists every tag you still need to map.
+4. Remove `HttpException`s from your domain code; map domain errors at the controller instead.
+
+## Testing with Jest
+
+The package's implementation is ES modules. A CommonJS Jest setup, the NestJS 11 default, cannot `require` it unless Jest runs with Node's VM modules support. Start Jest through Node with the flag:
+
+```json
+{
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  }
+}
+```
+
+## Requirements
+
+Node 22.12+, TypeScript 5.5+, `experimentalDecorators`, NestJS 11 or 12, neverthrow 8.
+
+A CommonJS host on NestJS 12 needs a TypeScript version and `moduleResolution` that understand `require` of ES modules: TypeScript 5.8+ with `module: nodenext`. Older combinations report TS1479 on NestJS's own imports before they reach this package.
+
+On Node 22.12 a CommonJS host prints an `ExperimentalWarning` when it loads the package, because the CommonJS entry points `require()` the ES module build. The warning is harmless.
+
+## Example
+
+`examples/deals-api` is a runnable app. Build it against the packed package with `npm run example:build`, then start it with `npm --prefix examples/deals-api start`.
+
+## License
+
+MIT

package/dist/chunk-7QVYU63E.js

@@ -0,0 +1,7 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+export {
+  __name
+};
+//# sourceMappingURL=chunk-7QVYU63E.js.map

package/dist/chunk-7QVYU63E.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-PK6SKIKE.cjs

@@ -0,0 +1,7 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+
+
+exports.__name = __name;
+//# sourceMappingURL=chunk-PK6SKIKE.cjs.map

package/dist/chunk-PK6SKIKE.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/mannkostir/Documents/nodejs-result/dist/chunk-PK6SKIKE.cjs"],"names":[],"mappings":"AAAA,6EAAI,UAAU,EAAE,MAAM,CAAC,cAAc;AACrC,IAAI,OAAO,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;AACxF;AACA;AACE;AACF,wBAAC","file":"/Users/mannkostir/Documents/nodejs-result/dist/chunk-PK6SKIKE.cjs"}

package/dist/chunk-T2LT5Y2F.js

@@ -0,0 +1,234 @@
+import {
+  __name
+} from "./chunk-7QVYU63E.js";
+
+// src/core/tagged-error.ts
+function TaggedError(tag) {
+  let TaggedErrorBase = class TaggedErrorBase extends Error {
+    static {
+      __name(this, "TaggedErrorBase");
+    }
+    _tag;
+    constructor(payload) {
+      super(payload?.message ?? tag);
+      Object.assign(this, payload);
+      this._tag = tag;
+      this.name = tag;
+    }
+  };
+  return TaggedErrorBase;
+}
+__name(TaggedError, "TaggedError");
+
+// src/core/library-errors.ts
+var UnmappedErrorTagError = class _UnmappedErrorTagError extends TaggedError("UnmappedErrorTagError") {
+  static {
+    __name(this, "UnmappedErrorTagError");
+  }
+  static forTag(tag) {
+    return new _UnmappedErrorTagError({
+      tag,
+      message: `No HTTP mapping exists for error tag "${tag}"`
+    });
+  }
+};
+var UntaggedErrorValueError = class _UntaggedErrorValueError extends TaggedError("UntaggedErrorValueError") {
+  static {
+    __name(this, "UntaggedErrorValueError");
+  }
+  static forValue(value) {
+    return new _UntaggedErrorValueError({
+      value,
+      message: "An Err value without a string _tag cannot be mapped to HTTP"
+    });
+  }
+};
+var MissingErrorMapError = class _MissingErrorMapError extends TaggedError("MissingErrorMapError") {
+  static {
+    __name(this, "MissingErrorMapError");
+  }
+  static forHandler(handler) {
+    return new _MissingErrorMapError({
+      handler,
+      message: `${handler} returned a Result but has no @MapErrors`
+    });
+  }
+};
+var DuplicateNeverthrowError = class _DuplicateNeverthrowError extends TaggedError("DuplicateNeverthrowError") {
+  static {
+    __name(this, "DuplicateNeverthrowError");
+  }
+  static forHandler(handler) {
+    return new _DuplicateNeverthrowError({
+      handler,
+      message: `${handler} returned a Result from a different copy of neverthrow; deduplicate neverthrow in your dependency tree`
+    });
+  }
+};
+
+// src/http/result.interceptor.ts
+import { Inject, Injectable } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { from, mergeMap } from "rxjs";
+
+// src/core/result-detection.ts
+import { Err, Ok, ResultAsync } from "neverthrow";
+function isResult(value) {
+  return value instanceof Ok || value instanceof Err;
+}
+__name(isResult, "isResult");
+function isResultAsync(value) {
+  return value instanceof ResultAsync;
+}
+__name(isResultAsync, "isResultAsync");
+function looksLikeForeignResult(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  const hasSyncShape = typeof candidate["isOk"] === "function" && typeof candidate["isErr"] === "function";
+  const hasAsyncShape = typeof candidate["then"] === "function" && typeof candidate["andThen"] === "function" && typeof candidate["mapErr"] === "function";
+  return hasSyncShape || hasAsyncShape;
+}
+__name(looksLikeForeignResult, "looksLikeForeignResult");
+
+// src/http/error-map-metadata.ts
+var ERROR_MAP_METADATA = "nest-result:error-map";
+
+// src/http/exception-for.ts
+import { HttpException } from "@nestjs/common";
+
+// src/core/resolve-http-error.ts
+import { err, ok } from "neverthrow";
+function resolveHttpError(error, map) {
+  const tag = readTag(error);
+  if (tag === void 0) return err(UntaggedErrorValueError.forValue(error));
+  const spec = Object.hasOwn(map, tag) ? map[tag] : void 0;
+  if (spec === void 0) return err(UnmappedErrorTagError.forTag(tag));
+  return ok(toResponse(spec, tag, error));
+}
+__name(resolveHttpError, "resolveHttpError");
+function statusOf(spec) {
+  return typeof spec === "number" ? spec : spec.status;
+}
+__name(statusOf, "statusOf");
+function toResponse(spec, tag, error) {
+  if (typeof spec === "number") return {
+    status: spec,
+    body: defaultBody(spec, tag, error)
+  };
+  return {
+    status: spec.status,
+    body: spec.body(error)
+  };
+}
+__name(toResponse, "toResponse");
+function defaultBody(status, tag, error) {
+  return {
+    statusCode: status,
+    code: tag,
+    message: readMessage(error) ?? tag
+  };
+}
+__name(defaultBody, "defaultBody");
+function readTag(error) {
+  if (typeof error !== "object" || error === null) return void 0;
+  const tag = error._tag;
+  return typeof tag === "string" ? tag : void 0;
+}
+__name(readTag, "readTag");
+function readMessage(error) {
+  const message = error.message;
+  return typeof message === "string" && message.length > 0 ? message : void 0;
+}
+__name(readMessage, "readMessage");
+
+// src/http/exception-for.ts
+function exceptionFor(error, map) {
+  return resolveHttpError(error, map).match(({ status, body }) => new HttpException(body, status, {
+    cause: error
+  }), (libraryError) => libraryError);
+}
+__name(exceptionFor, "exceptionFor");
+
+// src/http/result.interceptor.ts
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata, "_ts_metadata");
+function _ts_param(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param, "_ts_param");
+var ResultInterceptor = class {
+  static {
+    __name(this, "ResultInterceptor");
+  }
+  reflector;
+  constructor(reflector) {
+    this.reflector = reflector;
+  }
+  intercept(context, next) {
+    const map = this.reflector.get(ERROR_MAP_METADATA, context.getHandler());
+    const handler = `${context.getClass().name}.${context.getHandler().name}`;
+    return next.handle().pipe(mergeMap((value) => from(unwrapResponse(value, map, handler))));
+  }
+};
+ResultInterceptor = _ts_decorate([
+  Injectable(),
+  _ts_param(0, Inject(Reflector)),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof Reflector === "undefined" ? Object : Reflector
+  ])
+], ResultInterceptor);
+async function unwrapResponse(value, map, handler) {
+  const settled = isResultAsync(value) ? await value : value;
+  if (!isResult(settled)) return passThrough(settled, handler);
+  if (map === void 0) throw MissingErrorMapError.forHandler(handler);
+  if (settled.isErr()) throw exceptionFor(settled.error, map);
+  return settled.value;
+}
+__name(unwrapResponse, "unwrapResponse");
+function passThrough(value, handler) {
+  if (looksLikeForeignResult(value)) throw DuplicateNeverthrowError.forHandler(handler);
+  return value;
+}
+__name(passThrough, "passThrough");
+
+// src/http/apply-error-map.ts
+import { SetMetadata, UseInterceptors } from "@nestjs/common";
+function applyErrorMap(map, target, key, descriptor) {
+  SetMetadata(ERROR_MAP_METADATA, map)(target, key, descriptor);
+  UseInterceptors(ResultInterceptor)(target, key, descriptor);
+}
+__name(applyErrorMap, "applyErrorMap");
+
+export {
+  TaggedError,
+  UnmappedErrorTagError,
+  UntaggedErrorValueError,
+  MissingErrorMapError,
+  DuplicateNeverthrowError,
+  statusOf,
+  exceptionFor,
+  ResultInterceptor,
+  applyErrorMap
+};
+//# sourceMappingURL=chunk-T2LT5Y2F.js.map

package/dist/chunk-T2LT5Y2F.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/tagged-error.ts","../src/core/library-errors.ts","../src/http/result.interceptor.ts","../src/core/result-detection.ts","../src/http/error-map-metadata.ts","../src/http/exception-for.ts","../src/core/resolve-http-error.ts","../src/http/apply-error-map.ts"],"sourcesContent":["export type TaggedErrorPayload = object & {\n  readonly message?: string;\n  readonly _tag?: never;\n  readonly name?: never;\n};\n\ntype ConstructorArgs<P> = {} extends P ? [payload?: P] : [payload: P];\n\nexport type TaggedErrorInstance<Tag extends string, P> = Error & {\n  readonly _tag: Tag;\n} & Readonly<Omit<P, 'message'>>;\n\nexport type TaggedErrorClass<Tag extends string> = new <P extends TaggedErrorPayload = {}>(\n  ...args: ConstructorArgs<P>\n) => TaggedErrorInstance<Tag, P>;\n\nexport function TaggedError<const Tag extends string>(tag: Tag): TaggedErrorClass<Tag> {\n  class TaggedErrorBase extends Error {\n    readonly _tag: Tag;\n\n    constructor(payload?: TaggedErrorPayload) {\n      super(payload?.message ?? tag);\n      Object.assign(this, payload);\n      this._tag = tag;\n      this.name = tag;\n    }\n  }\n  return TaggedErrorBase as TaggedErrorClass<Tag>;\n}\n","import { TaggedError } from './tagged-error.js';\n\nexport class UnmappedErrorTagError extends TaggedError('UnmappedErrorTagError')<{\n  readonly tag: string;\n  readonly message: string;\n}> {\n  static forTag(tag: string): UnmappedErrorTagError {\n    return new UnmappedErrorTagError({ tag, message: `No HTTP mapping exists for error tag \"${tag}\"` });\n  }\n}\n\nexport class UntaggedErrorValueError extends TaggedError('UntaggedErrorValueError')<{\n  readonly value: unknown;\n  readonly message: string;\n}> {\n  static forValue(value: unknown): UntaggedErrorValueError {\n    return new UntaggedErrorValueError({ value, message: 'An Err value without a string _tag cannot be mapped to HTTP' });\n  }\n}\n\nexport class MissingErrorMapError extends TaggedError('MissingErrorMapError')<{\n  readonly handler: string;\n  readonly message: string;\n}> {\n  static forHandler(handler: string): MissingErrorMapError {\n    return new MissingErrorMapError({ handler, message: `${handler} returned a Result but has no @MapErrors` });\n  }\n}\n\nexport class DuplicateNeverthrowError extends TaggedError('DuplicateNeverthrowError')<{\n  readonly handler: string;\n  readonly message: string;\n}> {\n  static forHandler(handler: string): DuplicateNeverthrowError {\n    return new DuplicateNeverthrowError({\n      handler,\n      message: `${handler} returned a Result from a different copy of neverthrow; deduplicate neverthrow in your dependency tree`,\n    });\n  }\n}\n","import { type CallHandler, type ExecutionContext, Inject, Injectable, type NestInterceptor } from '@nestjs/common';\nimport { Reflector } from '@nestjs/core';\nimport { from, mergeMap, type Observable } from 'rxjs';\nimport type { AnyErrorMap } from '../core/error-map.js';\nimport { DuplicateNeverthrowError, MissingErrorMapError } from '../core/library-errors.js';\nimport { isResult, isResultAsync, looksLikeForeignResult } from '../core/result-detection.js';\nimport { ERROR_MAP_METADATA } from './error-map-metadata.js';\nimport { exceptionFor } from './exception-for.js';\n\n@Injectable()\nexport class ResultInterceptor implements NestInterceptor {\n  constructor(@Inject(Reflector) private readonly reflector: Reflector) {}\n\n  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {\n    const map = this.reflector.get<AnyErrorMap | undefined>(ERROR_MAP_METADATA, context.getHandler());\n    const handler = `${context.getClass().name}.${context.getHandler().name}`;\n    return next.handle().pipe(mergeMap((value: unknown) => from(unwrapResponse(value, map, handler))));\n  }\n}\n\nasync function unwrapResponse(value: unknown, map: AnyErrorMap | undefined, handler: string): Promise<unknown> {\n  const settled = isResultAsync(value) ? await value : value;\n  if (!isResult(settled)) return passThrough(settled, handler);\n  if (map === undefined) throw MissingErrorMapError.forHandler(handler);\n  if (settled.isErr()) throw exceptionFor(settled.error, map);\n  return settled.value;\n}\n\nfunction passThrough(value: unknown, handler: string): unknown {\n  if (looksLikeForeignResult(value)) throw DuplicateNeverthrowError.forHandler(handler);\n  return value;\n}\n","import { Err, Ok, ResultAsync, type Result } from 'neverthrow';\n\nexport function isResult(value: unknown): value is Result<unknown, unknown> {\n  return value instanceof Ok || value instanceof Err;\n}\n\nexport function isResultAsync(value: unknown): value is ResultAsync<unknown, unknown> {\n  return value instanceof ResultAsync;\n}\n\nexport function looksLikeForeignResult(value: unknown): boolean {\n  if (typeof value !== 'object' || value === null) return false;\n  const candidate = value as Readonly<Record<string, unknown>>;\n  const hasSyncShape = typeof candidate['isOk'] === 'function' && typeof candidate['isErr'] === 'function';\n  const hasAsyncShape =\n    typeof candidate['then'] === 'function' &&\n    typeof candidate['andThen'] === 'function' &&\n    typeof candidate['mapErr'] === 'function';\n  return hasSyncShape || hasAsyncShape;\n}\n","export const ERROR_MAP_METADATA = 'nest-result:error-map';\n","import { HttpException } from '@nestjs/common';\nimport type { AnyErrorMap } from '../core/error-map.js';\nimport type { UnmappedErrorTagError, UntaggedErrorValueError } from '../core/library-errors.js';\nimport { resolveHttpError } from '../core/resolve-http-error.js';\n\nexport function exceptionFor(\n  error: unknown,\n  map: AnyErrorMap,\n): HttpException | UnmappedErrorTagError | UntaggedErrorValueError {\n  return resolveHttpError(error, map).match(\n    ({ status, body }) => new HttpException(body, status, { cause: error }),\n    (libraryError) => libraryError,\n  );\n}\n","import { err, ok, type Result } from 'neverthrow';\nimport type { AnyErrorMap, AnyHttpErrorSpec } from './error-map.js';\nimport { UnmappedErrorTagError, UntaggedErrorValueError } from './library-errors.js';\n\nexport type HttpErrorResponse = { readonly status: number; readonly body: object };\n\nexport function resolveHttpError(\n  error: unknown,\n  map: AnyErrorMap,\n): Result<HttpErrorResponse, UnmappedErrorTagError | UntaggedErrorValueError> {\n  const tag = readTag(error);\n  if (tag === undefined) return err(UntaggedErrorValueError.forValue(error));\n  const spec = Object.hasOwn(map, tag) ? map[tag] : undefined;\n  if (spec === undefined) return err(UnmappedErrorTagError.forTag(tag));\n  return ok(toResponse(spec, tag, error));\n}\n\nexport function statusOf(spec: AnyHttpErrorSpec): number {\n  return typeof spec === 'number' ? spec : spec.status;\n}\n\nfunction toResponse(spec: AnyHttpErrorSpec, tag: string, error: unknown): HttpErrorResponse {\n  if (typeof spec === 'number') return { status: spec, body: defaultBody(spec, tag, error) };\n  return { status: spec.status, body: spec.body(error as never) };\n}\n\nfunction defaultBody(status: number, tag: string, error: unknown): object {\n  return { statusCode: status, code: tag, message: readMessage(error) ?? tag };\n}\n\nfunction readTag(error: unknown): string | undefined {\n  if (typeof error !== 'object' || error === null) return undefined;\n  const tag: unknown = (error as { readonly _tag?: unknown })._tag;\n  return typeof tag === 'string' ? tag : undefined;\n}\n\nfunction readMessage(error: unknown): string | undefined {\n  const message: unknown = (error as { readonly message?: unknown }).message;\n  return typeof message === 'string' && message.length > 0 ? message : undefined;\n}\n","import { SetMetadata, UseInterceptors } from '@nestjs/common';\nimport type { AnyErrorMap } from '../core/error-map.js';\nimport { ERROR_MAP_METADATA } from './error-map-metadata.js';\nimport { ResultInterceptor } from './result.interceptor.js';\n\nexport function applyErrorMap(\n  map: AnyErrorMap,\n  target: object,\n  key: string | symbol,\n  descriptor: PropertyDescriptor,\n): void {\n  SetMetadata(ERROR_MAP_METADATA, map)(target, key, descriptor);\n  UseInterceptors(ResultInterceptor)(target, key, descriptor);\n}\n"],"mappings":";;;;;AAgBO,SAASA,YAAsCC,KAAQ;AAC5D,MAAMC,kBAAN,MAAMA,wBAAwBC,MAAAA;IADhC,OACgCA;;;IACnBC;IAET,YAAYC,SAA8B;AACxC,YAAMA,SAASC,WAAWL,GAAAA;AAC1BM,aAAOC,OAAO,MAAMH,OAAAA;AACpB,WAAKD,OAAOH;AACZ,WAAKQ,OAAOR;IACd;EACF;AACA,SAAOC;AACT;AAZgBF;;;ACdT,IAAMU,wBAAN,MAAMA,+BAA8BC,YAAY,uBAAA,EAAA;EAFvD,OAEuD;;;EAIrD,OAAOC,OAAOC,KAAoC;AAChD,WAAO,IAAIH,uBAAsB;MAAEG;MAAKC,SAAS,yCAAyCD,GAAAA;IAAO,CAAA;EACnG;AACF;AAEO,IAAME,0BAAN,MAAMA,iCAAgCJ,YAAY,yBAAA,EAAA;EAXzD,OAWyD;;;EAIvD,OAAOK,SAASC,OAAyC;AACvD,WAAO,IAAIF,yBAAwB;MAAEE;MAAOH,SAAS;IAA8D,CAAA;EACrH;AACF;AAEO,IAAMI,uBAAN,MAAMA,8BAA6BP,YAAY,sBAAA,EAAA;EApBtD,OAoBsD;;;EAIpD,OAAOQ,WAAWC,SAAuC;AACvD,WAAO,IAAIF,sBAAqB;MAAEE;MAASN,SAAS,GAAGM,OAAAA;IAAkD,CAAA;EAC3G;AACF;AAEO,IAAMC,2BAAN,MAAMA,kCAAiCV,YAAY,0BAAA,EAAA;EA7B1D,OA6B0D;;;EAIxD,OAAOQ,WAAWC,SAA2C;AAC3D,WAAO,IAAIC,0BAAyB;MAClCD;MACAN,SAAS,GAAGM,OAAAA;IACd,CAAA;EACF;AACF;;;ACvCA,SAAkDE,QAAQC,kBAAwC;AAClG,SAASC,iBAAiB;AAC1B,SAASC,MAAMC,gBAAiC;;;ACFhD,SAASC,KAAKC,IAAIC,mBAAgC;AAE3C,SAASC,SAASC,OAAc;AACrC,SAAOA,iBAAiBC,MAAMD,iBAAiBE;AACjD;AAFgBH;AAIT,SAASI,cAAcH,OAAc;AAC1C,SAAOA,iBAAiBI;AAC1B;AAFgBD;AAIT,SAASE,uBAAuBL,OAAc;AACnD,MAAI,OAAOA,UAAU,YAAYA,UAAU,KAAM,QAAO;AACxD,QAAMM,YAAYN;AAClB,QAAMO,eAAe,OAAOD,UAAU,MAAA,MAAY,cAAc,OAAOA,UAAU,OAAA,MAAa;AAC9F,QAAME,gBACJ,OAAOF,UAAU,MAAA,MAAY,cAC7B,OAAOA,UAAU,SAAA,MAAe,cAChC,OAAOA,UAAU,QAAA,MAAc;AACjC,SAAOC,gBAAgBC;AACzB;AATgBH;;;ACVT,IAAMI,qBAAqB;;;ACAlC,SAASC,qBAAqB;;;ACA9B,SAASC,KAAKC,UAAuB;AAM9B,SAASC,iBACdC,OACAC,KAAgB;AAEhB,QAAMC,MAAMC,QAAQH,KAAAA;AACpB,MAAIE,QAAQE,OAAW,QAAOC,IAAIC,wBAAwBC,SAASP,KAAAA,CAAAA;AACnE,QAAMQ,OAAOC,OAAOC,OAAOT,KAAKC,GAAAA,IAAOD,IAAIC,GAAAA,IAAOE;AAClD,MAAII,SAASJ,OAAW,QAAOC,IAAIM,sBAAsBC,OAAOV,GAAAA,CAAAA;AAChE,SAAOW,GAAGC,WAAWN,MAAMN,KAAKF,KAAAA,CAAAA;AAClC;AATgBD;AAWT,SAASgB,SAASP,MAAsB;AAC7C,SAAO,OAAOA,SAAS,WAAWA,OAAOA,KAAKQ;AAChD;AAFgBD;AAIhB,SAASD,WAAWN,MAAwBN,KAAaF,OAAc;AACrE,MAAI,OAAOQ,SAAS,SAAU,QAAO;IAAEQ,QAAQR;IAAMS,MAAMC,YAAYV,MAAMN,KAAKF,KAAAA;EAAO;AACzF,SAAO;IAAEgB,QAAQR,KAAKQ;IAAQC,MAAMT,KAAKS,KAAKjB,KAAAA;EAAgB;AAChE;AAHSc;AAKT,SAASI,YAAYF,QAAgBd,KAAaF,OAAc;AAC9D,SAAO;IAAEmB,YAAYH;IAAQI,MAAMlB;IAAKmB,SAASC,YAAYtB,KAAAA,KAAUE;EAAI;AAC7E;AAFSgB;AAIT,SAASf,QAAQH,OAAc;AAC7B,MAAI,OAAOA,UAAU,YAAYA,UAAU,KAAM,QAAOI;AACxD,QAAMF,MAAgBF,MAAsCuB;AAC5D,SAAO,OAAOrB,QAAQ,WAAWA,MAAME;AACzC;AAJSD;AAMT,SAASmB,YAAYtB,OAAc;AACjC,QAAMqB,UAAoBrB,MAAyCqB;AACnE,SAAO,OAAOA,YAAY,YAAYA,QAAQG,SAAS,IAAIH,UAAUjB;AACvE;AAHSkB;;;AD/BF,SAASG,aACdC,OACAC,KAAgB;AAEhB,SAAOC,iBAAiBF,OAAOC,GAAAA,EAAKE,MAClC,CAAC,EAAEC,QAAQC,KAAI,MAAO,IAAIC,cAAcD,MAAMD,QAAQ;IAAEG,OAAOP;EAAM,CAAA,GACrE,CAACQ,iBAAiBA,YAAAA;AAEtB;AARgBT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AHKT,IAAMU,oBAAN,MAAMA;SAAAA;;;;EACX,YAAgDC,WAAsB;SAAtBA,YAAAA;EAAuB;EAEvEC,UAAUC,SAA2BC,MAAwC;AAC3E,UAAMC,MAAM,KAAKJ,UAAUK,IAA6BC,oBAAoBJ,QAAQK,WAAU,CAAA;AAC9F,UAAMC,UAAU,GAAGN,QAAQO,SAAQ,EAAGC,IAAI,IAAIR,QAAQK,WAAU,EAAGG,IAAI;AACvE,WAAOP,KAAKQ,OAAM,EAAGC,KAAKC,SAAS,CAACC,UAAmBC,KAAKC,eAAeF,OAAOV,KAAKI,OAAAA,CAAAA,CAAAA,CAAAA;EACzF;AACF;;;;;;;;;AAEA,eAAeQ,eAAeF,OAAgBV,KAA8BI,SAAe;AACzF,QAAMS,UAAUC,cAAcJ,KAAAA,IAAS,MAAMA,QAAQA;AACrD,MAAI,CAACK,SAASF,OAAAA,EAAU,QAAOG,YAAYH,SAAST,OAAAA;AACpD,MAAIJ,QAAQiB,OAAW,OAAMC,qBAAqBC,WAAWf,OAAAA;AAC7D,MAAIS,QAAQO,MAAK,EAAI,OAAMC,aAAaR,QAAQS,OAAOtB,GAAAA;AACvD,SAAOa,QAAQH;AACjB;AANeE;AAQf,SAASI,YAAYN,OAAgBN,SAAe;AAClD,MAAImB,uBAAuBb,KAAAA,EAAQ,OAAMc,yBAAyBL,WAAWf,OAAAA;AAC7E,SAAOM;AACT;AAHSM;;;AK5BT,SAASS,aAAaC,uBAAuB;AAKtC,SAASC,cACdC,KACAC,QACAC,KACAC,YAA8B;AAE9BC,cAAYC,oBAAoBL,GAAAA,EAAKC,QAAQC,KAAKC,UAAAA;AAClDG,kBAAgBC,iBAAAA,EAAmBN,QAAQC,KAAKC,UAAAA;AAClD;AARgBJ;","names":["TaggedError","tag","TaggedErrorBase","Error","_tag","payload","message","Object","assign","name","UnmappedErrorTagError","TaggedError","forTag","tag","message","UntaggedErrorValueError","forValue","value","MissingErrorMapError","forHandler","handler","DuplicateNeverthrowError","Inject","Injectable","Reflector","from","mergeMap","Err","Ok","ResultAsync","isResult","value","Ok","Err","isResultAsync","ResultAsync","looksLikeForeignResult","candidate","hasSyncShape","hasAsyncShape","ERROR_MAP_METADATA","HttpException","err","ok","resolveHttpError","error","map","tag","readTag","undefined","err","UntaggedErrorValueError","forValue","spec","Object","hasOwn","UnmappedErrorTagError","forTag","ok","toResponse","statusOf","status","body","defaultBody","statusCode","code","message","readMessage","_tag","length","exceptionFor","error","map","resolveHttpError","match","status","body","HttpException","cause","libraryError","ResultInterceptor","reflector","intercept","context","next","map","get","ERROR_MAP_METADATA","getHandler","handler","getClass","name","handle","pipe","mergeMap","value","from","unwrapResponse","settled","isResultAsync","isResult","passThrough","undefined","MissingErrorMapError","forHandler","isErr","exceptionFor","error","looksLikeForeignResult","DuplicateNeverthrowError","SetMetadata","UseInterceptors","applyErrorMap","map","target","key","descriptor","SetMetadata","ERROR_MAP_METADATA","UseInterceptors","ResultInterceptor"]}

package/dist/index.cjs

@@ -0,0 +1 @@
+module.exports = require('./index.js');

package/dist/index.d.cts

@@ -0,0 +1,61 @@
+import { E as ErrorMap, R as ResultSource, a as ExactErrorMap } from './map-errors.decorator-_ik4VDK6.cjs';
+export { b as ErrorBodyParameterMismatch, H as HttpErrorSpec, M as MapErrors, c as MapErrorsDecorator, d as MissingErrorMapKeys, S as StaleErrorMapKeys, T as TagOf, e as Tagged, U as UntaggedErrorsCannotBeMapped } from './map-errors.decorator-_ik4VDK6.cjs';
+import { NestInterceptor, ExecutionContext, CallHandler, DynamicModule } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
+import 'neverthrow';
+
+type TaggedErrorPayload = object & {
+    readonly message?: string;
+    readonly _tag?: never;
+    readonly name?: never;
+};
+type ConstructorArgs<P> = {} extends P ? [payload?: P] : [payload: P];
+type TaggedErrorInstance<Tag extends string, P> = Error & {
+    readonly _tag: Tag;
+} & Readonly<Omit<P, 'message'>>;
+type TaggedErrorClass<Tag extends string> = new <P extends TaggedErrorPayload = {}>(...args: ConstructorArgs<P>) => TaggedErrorInstance<Tag, P>;
+declare function TaggedError<const Tag extends string>(tag: Tag): TaggedErrorClass<Tag>;
+
+declare const UnmappedErrorTagError_base: TaggedErrorClass<"UnmappedErrorTagError">;
+declare class UnmappedErrorTagError extends UnmappedErrorTagError_base<{
+    readonly tag: string;
+    readonly message: string;
+}> {
+    static forTag(tag: string): UnmappedErrorTagError;
+}
+declare const UntaggedErrorValueError_base: TaggedErrorClass<"UntaggedErrorValueError">;
+declare class UntaggedErrorValueError extends UntaggedErrorValueError_base<{
+    readonly value: unknown;
+    readonly message: string;
+}> {
+    static forValue(value: unknown): UntaggedErrorValueError;
+}
+declare const MissingErrorMapError_base: TaggedErrorClass<"MissingErrorMapError">;
+declare class MissingErrorMapError extends MissingErrorMapError_base<{
+    readonly handler: string;
+    readonly message: string;
+}> {
+    static forHandler(handler: string): MissingErrorMapError;
+}
+declare const DuplicateNeverthrowError_base: TaggedErrorClass<"DuplicateNeverthrowError">;
+declare class DuplicateNeverthrowError extends DuplicateNeverthrowError_base<{
+    readonly handler: string;
+    readonly message: string;
+}> {
+    static forHandler(handler: string): DuplicateNeverthrowError;
+}
+
+declare function toHttp<T, E, const M extends ErrorMap<E>>(source: ResultSource<T, E>, map: ExactErrorMap<E, M>): Promise<T>;
+
+declare class ResultInterceptor implements NestInterceptor {
+    private readonly reflector;
+    constructor(reflector: Reflector);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+
+declare class ResultModule {
+    static forRoot(): DynamicModule;
+}
+
+export { DuplicateNeverthrowError, ErrorMap, MissingErrorMapError, ResultInterceptor, ResultModule, TaggedError, type TaggedErrorClass, type TaggedErrorInstance, type TaggedErrorPayload, UnmappedErrorTagError, UntaggedErrorValueError, toHttp };

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import { E as ErrorMap, R as ResultSource, a as ExactErrorMap } from './map-errors.decorator-_ik4VDK6.js';
+export { b as ErrorBodyParameterMismatch, H as HttpErrorSpec, M as MapErrors, c as MapErrorsDecorator, d as MissingErrorMapKeys, S as StaleErrorMapKeys, T as TagOf, e as Tagged, U as UntaggedErrorsCannotBeMapped } from './map-errors.decorator-_ik4VDK6.js';
+import { NestInterceptor, ExecutionContext, CallHandler, DynamicModule } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
+import 'neverthrow';
+
+type TaggedErrorPayload = object & {
+    readonly message?: string;
+    readonly _tag?: never;
+    readonly name?: never;
+};
+type ConstructorArgs<P> = {} extends P ? [payload?: P] : [payload: P];
+type TaggedErrorInstance<Tag extends string, P> = Error & {
+    readonly _tag: Tag;
+} & Readonly<Omit<P, 'message'>>;
+type TaggedErrorClass<Tag extends string> = new <P extends TaggedErrorPayload = {}>(...args: ConstructorArgs<P>) => TaggedErrorInstance<Tag, P>;
+declare function TaggedError<const Tag extends string>(tag: Tag): TaggedErrorClass<Tag>;
+
+declare const UnmappedErrorTagError_base: TaggedErrorClass<"UnmappedErrorTagError">;
+declare class UnmappedErrorTagError extends UnmappedErrorTagError_base<{
+    readonly tag: string;
+    readonly message: string;
+}> {
+    static forTag(tag: string): UnmappedErrorTagError;
+}
+declare const UntaggedErrorValueError_base: TaggedErrorClass<"UntaggedErrorValueError">;
+declare class UntaggedErrorValueError extends UntaggedErrorValueError_base<{
+    readonly value: unknown;
+    readonly message: string;
+}> {
+    static forValue(value: unknown): UntaggedErrorValueError;
+}
+declare const MissingErrorMapError_base: TaggedErrorClass<"MissingErrorMapError">;
+declare class MissingErrorMapError extends MissingErrorMapError_base<{
+    readonly handler: string;
+    readonly message: string;
+}> {
+    static forHandler(handler: string): MissingErrorMapError;
+}
+declare const DuplicateNeverthrowError_base: TaggedErrorClass<"DuplicateNeverthrowError">;
+declare class DuplicateNeverthrowError extends DuplicateNeverthrowError_base<{
+    readonly handler: string;
+    readonly message: string;
+}> {
+    static forHandler(handler: string): DuplicateNeverthrowError;
+}
+
+declare function toHttp<T, E, const M extends ErrorMap<E>>(source: ResultSource<T, E>, map: ExactErrorMap<E, M>): Promise<T>;
+
+declare class ResultInterceptor implements NestInterceptor {
+    private readonly reflector;
+    constructor(reflector: Reflector);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+
+declare class ResultModule {
+    static forRoot(): DynamicModule;
+}
+
+export { DuplicateNeverthrowError, ErrorMap, MissingErrorMapError, ResultInterceptor, ResultModule, TaggedError, type TaggedErrorClass, type TaggedErrorInstance, type TaggedErrorPayload, UnmappedErrorTagError, UntaggedErrorValueError, toHttp };