@couimet/detailed-result 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Ouimet
+
+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

@@ -0,0 +1,43 @@
+# @couimet/detailed-result
+
+Functional Result type for explicit error handling paired with `@couimet/detailed-error`.
+
+## Usage
+
+Create results with the `ok()` and `err()` factories, then check `.success` before accessing `.value` or `.error`:
+
+```ts
+import { DetailedResult } from '@couimet/detailed-result';
+
+function divide(a: number, b: number): DetailedResult<number, string> {
+  if (b === 0) {
+    return DetailedResult.err('Division by zero');
+  }
+  return DetailedResult.ok(a / b);
+}
+
+const result = divide(10, 2);
+if (result.success) {
+  console.log(result.value); // 5
+} else {
+  console.error(result.error);
+}
+```
+
+**Pin the error type** by subclassing — override the factories, keep the constructor hidden:
+
+```ts
+class MyResult<T> extends DetailedResult<T, MyError> {
+  static ok<T>(value: T): MyResult<T> {
+    return new MyResult(true, value, undefined);
+  }
+  static err(error: MyError): MyResult<never> {
+    return new MyResult(false, undefined, error);
+  }
+}
+
+const result = MyResult.ok(42);
+// result.error is typed as MyError
+```
+
+Accessing `.value` on an error result (or `.error` on a success result) throws a `DetailedError` with a `DetailedResultErrorCodes` code — these are invariant violations that signal a bug in the calling code (missing `.success` check).

package/dist/index.d.mts

@@ -0,0 +1,71 @@
+/**
+ * Functional error handling Value Object.
+ *
+ * Represents either a successful value or an error. Use {@link DetailedResult.ok} and
+ * {@link DetailedResult.err} factories to create instances, check `.success` before
+ * accessing `.value` or `.error`.
+ *
+ * The constructor is `protected` so subclasses can pin the error type by overriding
+ * the static factories.
+ *
+ * @typeParam T - The success value type.
+ * @typeParam E - The error type. Unconstrained — use plain `Error`, {@link DetailedError}, or a project-specific subclass.
+ */
+declare class DetailedResult<T, E> {
+    private readonly _success;
+    private readonly _value;
+    private readonly _error;
+    /**
+     * Not for public use. Use {@link DetailedResult.ok} or {@link DetailedResult.err} factories instead.
+     *
+     * Marked `protected` so subclasses can extend to pin the error type.
+     */
+    protected constructor(success: boolean, value: T | undefined, error: E | undefined);
+    /** Create a successful {@link DetailedResult} containing a value. */
+    static ok<T>(value: T): DetailedResult<T, never>;
+    /** Create an error {@link DetailedResult} containing an error. */
+    static err<E>(error: E): DetailedResult<never, E>;
+    /** Check if this {@link DetailedResult} is successful. Always check this before accessing `.value` or `.error`. */
+    get success(): boolean;
+    /**
+     * Get the success value. Throws a {@link DetailedError} with code
+     * {@link DetailedResultErrorCodes.RESULT_VALUE_ACCESS_ON_ERROR} if this is an error result.
+     */
+    get value(): T;
+    /**
+     * Get the error. Throws a {@link DetailedError} with code
+     * {@link DetailedResultErrorCodes.RESULT_ERROR_ACCESS_ON_SUCCESS} if this is a success result.
+     */
+    get error(): E;
+}
+
+/**
+ * Error codes for {@link DetailedResult} internal invariant violations.
+ *
+ * These codes are used when {@link DetailedResult} detects an invalid state,
+ * such as accessing `.value` on an error result or `.error` on a success result.
+ * They are not expected to appear in normal application flow — they signal a bug
+ * in the calling code (missing `.success` check before access).
+ */
+declare enum DetailedResultErrorCodes {
+    /**
+     * Attempted to access `.error` on a successful {@link DetailedResult}.
+     * Always check `.success` before accessing `.error`.
+     */
+    RESULT_ERROR_ACCESS_ON_SUCCESS = "RESULT_ERROR_ACCESS_ON_SUCCESS",
+    /**
+     * {@link DetailedResult} was constructed with an invalid combination of arguments:
+     * either a success result with an error defined, or an error result with a value defined.
+     * This should never happen through the public factory methods ({@link DetailedResult.ok} /
+     * {@link DetailedResult.err}); it can only be triggered by a subclass constructor
+     * passing inconsistent arguments.
+     */
+    RESULT_INVALID_STATE = "RESULT_INVALID_STATE",
+    /**
+     * Attempted to access `.value` on an error {@link DetailedResult}.
+     * Always check `.success` before accessing `.value`.
+     */
+    RESULT_VALUE_ACCESS_ON_ERROR = "RESULT_VALUE_ACCESS_ON_ERROR"
+}
+
+export { DetailedResult, DetailedResultErrorCodes };

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Functional error handling Value Object.
+ *
+ * Represents either a successful value or an error. Use {@link DetailedResult.ok} and
+ * {@link DetailedResult.err} factories to create instances, check `.success` before
+ * accessing `.value` or `.error`.
+ *
+ * The constructor is `protected` so subclasses can pin the error type by overriding
+ * the static factories.
+ *
+ * @typeParam T - The success value type.
+ * @typeParam E - The error type. Unconstrained — use plain `Error`, {@link DetailedError}, or a project-specific subclass.
+ */
+declare class DetailedResult<T, E> {
+    private readonly _success;
+    private readonly _value;
+    private readonly _error;
+    /**
+     * Not for public use. Use {@link DetailedResult.ok} or {@link DetailedResult.err} factories instead.
+     *
+     * Marked `protected` so subclasses can extend to pin the error type.
+     */
+    protected constructor(success: boolean, value: T | undefined, error: E | undefined);
+    /** Create a successful {@link DetailedResult} containing a value. */
+    static ok<T>(value: T): DetailedResult<T, never>;
+    /** Create an error {@link DetailedResult} containing an error. */
+    static err<E>(error: E): DetailedResult<never, E>;
+    /** Check if this {@link DetailedResult} is successful. Always check this before accessing `.value` or `.error`. */
+    get success(): boolean;
+    /**
+     * Get the success value. Throws a {@link DetailedError} with code
+     * {@link DetailedResultErrorCodes.RESULT_VALUE_ACCESS_ON_ERROR} if this is an error result.
+     */
+    get value(): T;
+    /**
+     * Get the error. Throws a {@link DetailedError} with code
+     * {@link DetailedResultErrorCodes.RESULT_ERROR_ACCESS_ON_SUCCESS} if this is a success result.
+     */
+    get error(): E;
+}
+
+/**
+ * Error codes for {@link DetailedResult} internal invariant violations.
+ *
+ * These codes are used when {@link DetailedResult} detects an invalid state,
+ * such as accessing `.value` on an error result or `.error` on a success result.
+ * They are not expected to appear in normal application flow — they signal a bug
+ * in the calling code (missing `.success` check before access).
+ */
+declare enum DetailedResultErrorCodes {
+    /**
+     * Attempted to access `.error` on a successful {@link DetailedResult}.
+     * Always check `.success` before accessing `.error`.
+     */
+    RESULT_ERROR_ACCESS_ON_SUCCESS = "RESULT_ERROR_ACCESS_ON_SUCCESS",
+    /**
+     * {@link DetailedResult} was constructed with an invalid combination of arguments:
+     * either a success result with an error defined, or an error result with a value defined.
+     * This should never happen through the public factory methods ({@link DetailedResult.ok} /
+     * {@link DetailedResult.err}); it can only be triggered by a subclass constructor
+     * passing inconsistent arguments.
+     */
+    RESULT_INVALID_STATE = "RESULT_INVALID_STATE",
+    /**
+     * Attempted to access `.value` on an error {@link DetailedResult}.
+     * Always check `.success` before accessing `.value`.
+     */
+    RESULT_VALUE_ACCESS_ON_ERROR = "RESULT_VALUE_ACCESS_ON_ERROR"
+}
+
+export { DetailedResult, DetailedResultErrorCodes };

package/dist/index.js

@@ -0,0 +1,133 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DetailedResult: () => DetailedResult,
+  DetailedResultErrorCodes: () => DetailedResultErrorCodes
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/DetailedResultErrorCodes.ts
+var DetailedResultErrorCodes = /* @__PURE__ */ ((DetailedResultErrorCodes2) => {
+  DetailedResultErrorCodes2["RESULT_ERROR_ACCESS_ON_SUCCESS"] = "RESULT_ERROR_ACCESS_ON_SUCCESS";
+  DetailedResultErrorCodes2["RESULT_INVALID_STATE"] = "RESULT_INVALID_STATE";
+  DetailedResultErrorCodes2["RESULT_VALUE_ACCESS_ON_ERROR"] = "RESULT_VALUE_ACCESS_ON_ERROR";
+  return DetailedResultErrorCodes2;
+})(DetailedResultErrorCodes || {});
+
+// src/DetailedResult.ts
+var import_detailed_error = require("@couimet/detailed-error");
+var DetailedResult = class _DetailedResult {
+  _success;
+  _value;
+  _error;
+  /**
+   * Not for public use. Use {@link DetailedResult.ok} or {@link DetailedResult.err} factories instead.
+   *
+   * Marked `protected` so subclasses can extend to pin the error type.
+   */
+  constructor(success, value, error) {
+    if (success && error !== void 0) {
+      throw new import_detailed_error.DetailedError({
+        code: "RESULT_INVALID_STATE" /* RESULT_INVALID_STATE */,
+        message: "DetailedResult marked as success cannot have an error defined",
+        functionName: "DetailedResult.constructor",
+        details: {
+          success,
+          hasValue: value !== void 0,
+          hasError: error !== void 0
+        }
+      });
+    }
+    if (!success && value !== void 0) {
+      throw new import_detailed_error.DetailedError({
+        code: "RESULT_INVALID_STATE" /* RESULT_INVALID_STATE */,
+        message: "DetailedResult marked as error cannot have a value defined",
+        functionName: "DetailedResult.constructor",
+        details: {
+          success,
+          hasValue: value !== void 0,
+          hasError: error !== void 0
+        }
+      });
+    }
+    if (!success && error === void 0) {
+      throw new import_detailed_error.DetailedError({
+        code: "RESULT_INVALID_STATE" /* RESULT_INVALID_STATE */,
+        message: "DetailedResult marked as error must have an error defined",
+        functionName: "DetailedResult.constructor",
+        details: {
+          success,
+          hasValue: value !== void 0,
+          hasError: error !== void 0
+        }
+      });
+    }
+    this._success = success;
+    this._value = value;
+    this._error = error;
+  }
+  /** Create a successful {@link DetailedResult} containing a value. */
+  static ok(value) {
+    return new _DetailedResult(true, value, void 0);
+  }
+  /** Create an error {@link DetailedResult} containing an error. */
+  static err(error) {
+    return new _DetailedResult(false, void 0, error);
+  }
+  /** Check if this {@link DetailedResult} is successful. Always check this before accessing `.value` or `.error`. */
+  get success() {
+    return this._success;
+  }
+  /**
+   * Get the success value. Throws a {@link DetailedError} with code
+   * {@link DetailedResultErrorCodes.RESULT_VALUE_ACCESS_ON_ERROR} if this is an error result.
+   */
+  get value() {
+    if (!this._success) {
+      throw new import_detailed_error.DetailedError({
+        code: "RESULT_VALUE_ACCESS_ON_ERROR" /* RESULT_VALUE_ACCESS_ON_ERROR */,
+        message: "Cannot access value on an error DetailedResult. Check .success before accessing .value",
+        functionName: "DetailedResult.value"
+      });
+    }
+    return this._value;
+  }
+  /**
+   * Get the error. Throws a {@link DetailedError} with code
+   * {@link DetailedResultErrorCodes.RESULT_ERROR_ACCESS_ON_SUCCESS} if this is a success result.
+   */
+  get error() {
+    if (this._success) {
+      throw new import_detailed_error.DetailedError({
+        code: "RESULT_ERROR_ACCESS_ON_SUCCESS" /* RESULT_ERROR_ACCESS_ON_SUCCESS */,
+        message: "Cannot access error on a successful DetailedResult. Check .success before accessing .error",
+        functionName: "DetailedResult.error"
+      });
+    }
+    return this._error;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DetailedResult,
+  DetailedResultErrorCodes
+});

package/dist/index.mjs

@@ -0,0 +1,105 @@
+// src/DetailedResultErrorCodes.ts
+var DetailedResultErrorCodes = /* @__PURE__ */ ((DetailedResultErrorCodes2) => {
+  DetailedResultErrorCodes2["RESULT_ERROR_ACCESS_ON_SUCCESS"] = "RESULT_ERROR_ACCESS_ON_SUCCESS";
+  DetailedResultErrorCodes2["RESULT_INVALID_STATE"] = "RESULT_INVALID_STATE";
+  DetailedResultErrorCodes2["RESULT_VALUE_ACCESS_ON_ERROR"] = "RESULT_VALUE_ACCESS_ON_ERROR";
+  return DetailedResultErrorCodes2;
+})(DetailedResultErrorCodes || {});
+
+// src/DetailedResult.ts
+import { DetailedError } from "@couimet/detailed-error";
+var DetailedResult = class _DetailedResult {
+  _success;
+  _value;
+  _error;
+  /**
+   * Not for public use. Use {@link DetailedResult.ok} or {@link DetailedResult.err} factories instead.
+   *
+   * Marked `protected` so subclasses can extend to pin the error type.
+   */
+  constructor(success, value, error) {
+    if (success && error !== void 0) {
+      throw new DetailedError({
+        code: "RESULT_INVALID_STATE" /* RESULT_INVALID_STATE */,
+        message: "DetailedResult marked as success cannot have an error defined",
+        functionName: "DetailedResult.constructor",
+        details: {
+          success,
+          hasValue: value !== void 0,
+          hasError: error !== void 0
+        }
+      });
+    }
+    if (!success && value !== void 0) {
+      throw new DetailedError({
+        code: "RESULT_INVALID_STATE" /* RESULT_INVALID_STATE */,
+        message: "DetailedResult marked as error cannot have a value defined",
+        functionName: "DetailedResult.constructor",
+        details: {
+          success,
+          hasValue: value !== void 0,
+          hasError: error !== void 0
+        }
+      });
+    }
+    if (!success && error === void 0) {
+      throw new DetailedError({
+        code: "RESULT_INVALID_STATE" /* RESULT_INVALID_STATE */,
+        message: "DetailedResult marked as error must have an error defined",
+        functionName: "DetailedResult.constructor",
+        details: {
+          success,
+          hasValue: value !== void 0,
+          hasError: error !== void 0
+        }
+      });
+    }
+    this._success = success;
+    this._value = value;
+    this._error = error;
+  }
+  /** Create a successful {@link DetailedResult} containing a value. */
+  static ok(value) {
+    return new _DetailedResult(true, value, void 0);
+  }
+  /** Create an error {@link DetailedResult} containing an error. */
+  static err(error) {
+    return new _DetailedResult(false, void 0, error);
+  }
+  /** Check if this {@link DetailedResult} is successful. Always check this before accessing `.value` or `.error`. */
+  get success() {
+    return this._success;
+  }
+  /**
+   * Get the success value. Throws a {@link DetailedError} with code
+   * {@link DetailedResultErrorCodes.RESULT_VALUE_ACCESS_ON_ERROR} if this is an error result.
+   */
+  get value() {
+    if (!this._success) {
+      throw new DetailedError({
+        code: "RESULT_VALUE_ACCESS_ON_ERROR" /* RESULT_VALUE_ACCESS_ON_ERROR */,
+        message: "Cannot access value on an error DetailedResult. Check .success before accessing .value",
+        functionName: "DetailedResult.value"
+      });
+    }
+    return this._value;
+  }
+  /**
+   * Get the error. Throws a {@link DetailedError} with code
+   * {@link DetailedResultErrorCodes.RESULT_ERROR_ACCESS_ON_SUCCESS} if this is a success result.
+   */
+  get error() {
+    if (this._success) {
+      throw new DetailedError({
+        code: "RESULT_ERROR_ACCESS_ON_SUCCESS" /* RESULT_ERROR_ACCESS_ON_SUCCESS */,
+        message: "Cannot access error on a successful DetailedResult. Check .success before accessing .error",
+        functionName: "DetailedResult.error"
+      });
+    }
+    return this._error;
+  }
+};
+export {
+  DetailedResult,
+  DetailedResultErrorCodes
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@couimet/detailed-result",
+  "version": "0.1.0",
+  "description": "Functional Result type for explicit error handling paired with @couimet/detailed-error",
+  "homepage": "https://github.com/couimet/ts-npm-packages/tree/main/packages/detailed-result#readme",
+  "bugs": {
+    "url": "https://github.com/couimet/ts-npm-packages/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:couimet/ts-npm-packages.git",
+    "directory": "packages/detailed-result"
+  },
+  "license": "MIT",
+  "author": "Charles Ouimet <charles.ouimet@gmail.com>",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "prettier": "@couimet/eslint-config/prettier",
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^24.13.2",
+    "eslint": "^10.4.1",
+    "jest": "^29.7.0",
+    "prettier": "^3.8.4",
+    "ts-jest": "^29.4.11",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "@couimet/detailed-error": "1.0.0",
+    "@couimet/detailed-error-testing": "0.1.4",
+    "@couimet/eslint-config": "0.6.2"
+  },
+  "peerDependencies": {
+    "@couimet/detailed-error": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist coverage *.tsbuildinfo",
+    "clean:all": "pnpm clean && rm -rf node_modules .eslintcache *.log",
+    "clean:deps": "rm -rf node_modules",
+    "format": "prettier --check .",
+    "test": "jest --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}