feat(core): add neverthrow integration and ThatError type refinement

Added integration with the `neverthrow` library to enhance error-handling scenarios. Implemented new tests under `neverthrow.test.ts` to validate error inference using `neverthrow` APIs. Refined the `ThatError` type in `types.ts` to support better nominal typing and added detailed use-case examples for clarity.

Updated `package.json` to include `neverthrow` as a development dependency and added a `install:clean` script for workspace maintenance.

Author: tarnishablec

bun.lock

@@ -15,5 +15,8 @@
     },
     "engines": {
         "bun": ">=1.3"
+    },
+    "scripts": {
+        "install:clean": "rm -rf node_modules bun.lockb && bun install"
     }
 }

package.json

@@ -7,7 +7,7 @@ import {
     PayloadField,
     ScopeField,
     scopeOf,
-    That
+    That,
 } from "@thaterror/core"
 
 export const AppError = That({

packages/core/__tests__/define-error.test.ts

@@ -59,6 +59,5 @@ describe('ErrorFamily from native error testing', () => {
 
         const not_found = new HTTPException(404);
         expect(HttpBridgedError.from(not_found).cause).toBe(not_found);
-
     })
 })

packages/core/__tests__/from-error.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { PayloadField, type ThatError } from "@thaterror/core";
+import { err, fromPromise } from 'neverthrow'
+import { AppError } from './define-error.test'
+
+describe('neverthrow test', () => {
+    test('should infer Error type', () => {
+        const getNotFoundResult = () => {
+            const e = AppError.NotFound(404);
+            return err<string, ThatError<typeof AppError, "NotFound">>(e);
+        };
+
+        const result = getNotFoundResult();
+
+        expect(result.isErr()).toBe(true);
+
+        if (result.isErr()) {
+            const error = result.error;
+            expect(error.is(AppError.NotFound)).toBe(true);
+            expect(error[PayloadField]).toEqual([404]);
+        }
+    })
+
+    test('should infer Error type from async call', async () => {
+        const fetchData = () => {
+            const promise = Promise.reject(AppError.NotFound(404));
+
+            return fromPromise(
+                promise,
+                (e) => e as ThatError<typeof AppError, "NotFound">
+            );
+        };
+
+        const result = await fetchData();
+
+        expect(result.isErr()).toBe(true);
+
+        if (result.isErr()) {
+            expect(result.error.is(AppError.NotFound)).toBe(true);
+            expect(result.error[PayloadField][0]).toBe(404);
+        }
+    })
+})

packages/core/__tests__/neverthrow.test.ts

@@ -26,7 +26,8 @@
     "package.json"
   ],
   "devDependencies": {
-    "hono": "^4.11.3"
+    "hono": "^4.11.3",
+    "neverthrow": "^8.2.0"
   },
   "publishConfig": {
     "access": "public"

packages/core/package.json

@@ -173,3 +173,38 @@ export type ErrorMapOf<F> =
 export type ErrorUnionOf<F> =
     F extends ErrorFamily<infer M, infer _Es>
         ? ErrorUnionOfMap<M> : never
+
+
+/**
+ * Extracts a specific subset of DefinedError instances from an ErrorFamily.
+ * Strictly prohibits `any` to maintain nominal type integrity.
+ *
+ * @template F - The ErrorFamily instance (e.g., `typeof AppError`).
+ * @template K - Keys to extract from the ErrorMap. Defaults to all keys.
+ *
+ * @example
+ * ### USE CASE: Basic Usage
+ * ```ts
+ * type ErrType = ThatError<typeof AppError>;
+ * ```
+ *
+ * @example
+ * ### USE CASE: Integration with neverthrow
+ * ```ts
+ * function fetchData(): ResultAsync<string, ThatError<typeof AppError, 'Timeout' | 'Network'>> {
+ * return fromPromise(
+ * api.get('/data'),
+ * (e: unknown) => AppError.bridge(e as Error, (err, cases) => {
+ * if (err.message.includes('timeout')) return cases.Timeout();
+ * return cases.Network();
+ * }) as ThatError<typeof AppError, 'Timeout' | 'Network'>
+ * );
+ * }
+ * ```
+ */
+export type ThatError<
+    F,
+    K extends keyof ErrorMapOf<F> = keyof ErrorMapOf<F>
+> = ErrorUnionOfMap<{
+    [P in K & string]: ErrorMapOf<F>[P]
+}>