go-go-try 7.2.1 → 7.4.0

package/AGENTS.md

@@ -5,25 +5,35 @@
 **go-go-try** is a TypeScript utility library for error handling inspired by Go's error handling pattern. It provides a functional approach to try/catch operations by returning a tuple `[error, value]` instead of throwing exceptions.
 
 - **Name**: go-go-try
-- **Version**: 6.2.0
+- **Version**: 7.2.1
 - **License**: MIT
 - **Repository**: thelinuxlich/go-go-try
 - **Node.js Requirements**: >= 16
 
+### Key Features
+
+- Zero runtime dependencies
+- Dual package support (CommonJS and ESM)
+- Full TypeScript support with precise type inference
+- Support for sync/async functions, promises, and direct values
+- Parallel execution utilities with optional concurrency control
+- Tagged errors for discriminated union pattern matching
+
 ## Technology Stack
 
-- **Language**: TypeScript 5.8.3
+- **Language**: TypeScript 5.9.3
 - **Build Tool**: [pkgroll](https://github.com/privatenumber/pkgroll) - A zero-config TypeScript package bundler
 - **Linter**: [Biome](https://biomejs.dev/) - Fast linter and formatter
 - **Test Framework**: [Vitest](https://vitest.dev/) - Vite-native unit test framework
 - **Type Testing**: [@ark/attest](https://github.com/arktypeio/arktype) - Runtime type assertions for TypeScript
+- **Git Hooks**: [Husky](https://typicode.github.io/husky/) + [lint-staged](https://github.com/lint-staged/lint-staged)
 
 ## Project Structure
 
 ```
 .
 ├── src/
-│   ├── index.ts        # Main source file - exports goTry, goTryRaw, and utility types
+│   ├── index.ts        # Main source file - exports all functions and types
 │   └── index.test.ts   # Comprehensive test suite with runtime and type tests
 ├── dist/               # Build output (generated by pkgroll)
 │   ├── index.cjs       # CommonJS build
@@ -32,10 +42,12 @@
 │   └── index.d.mts     # ES Module type definitions
 ├── .github/workflows/
 │   └── main.yml        # CI configuration for GitHub Actions
+├── .husky/
+│   └── pre-commit      # Git pre-commit hook (runs lint-staged)
 ├── .attest/            # Ark attest cache directory
 ├── package.json        # Package configuration with dual CJS/ESM exports
 ├── tsconfig.json       # TypeScript strict configuration
-├── vitest.config.ts    # Vitest configuration with type checking enabled
+├── vitest.config.ts    # Vitest configuration with type checking and coverage
 ├── setupVitest.ts      # Vitest global setup for @ark/attest
 └── README.md           # User-facing documentation
 ```
@@ -51,17 +63,20 @@ npm run lint
 
 # Run the full test suite (build + lint + vitest)
 npm test
+
+# Run tests with coverage report
+npm run test:coverage
 ```
 
-The test script is a composite that:
+The `npm test` script is a composite that:
 1. Builds the project
 2. Runs the linter
-3. Executes Vitest tests
+3. Executes Vitest tests with type checking
 
 ## Code Style Guidelines
 
-- **Linter**: Biome is used for linting and formatting
-- **Configuration**: Uses Biome's default configuration (no biome.json present)
+- **Linter**: Biome is used for linting and formatting with default configuration (no biome.json present)
+- **Pre-commit**: Husky runs `lint-staged` which lints all staged `.ts` files via Biome
 - **Strict TypeScript**: The `tsconfig.json` enforces strict mode with additional checks:
   - `noUnusedLocals`: true
   - `noUnusedParameters`: true
@@ -78,8 +93,8 @@ Tests are co-located with source code in `src/index.test.ts` using Vitest.
 
 ### Test Types
 
-1. **Runtime Tests**: Standard unit tests verifying behavior
-2. **Type Tests**: Using `@ark/attest` to verify TypeScript type inference at runtime
+1. **Runtime Tests**: Standard unit tests verifying behavior using Vitest's `assert` and `test`
+2. **Type Tests**: Using `@ark/attest` to verify TypeScript type inference at runtime with `attest<T>(value)`
 
 ### Key Testing Patterns
 
@@ -107,33 +122,60 @@ npx vitest run
 
 # Run tests in watch mode (during development)
 npx vitest
+
+# Run with coverage
+npx vitest run --coverage
 ```
 
-### Global Setup
+### Coverage Configuration
 
-The `setupVitest.ts` file configures `@ark/attest` for type assertions in tests.
+Coverage is provided by `@vitest/coverage-v8` with reporters: text, json, html, and lcov. Excluded paths:
+- `node_modules/`
+- `dist/`
+- `**/*.test.ts`
+- `setupVitest.ts`
 
 ## API Design
 
 ### Core Functions
 
-- **`goTry<T>(value)`**: Returns `[string | undefined, T | undefined]` - error is the message string
-- **`goTryRaw<T, E>(value)`**: Returns `[E | undefined, T | undefined]` - error is the raw Error object
+| Function | Description | Error Type |
+|----------|-------------|------------|
+| `goTry<T>(value)` | Returns `[string \| undefined, T \| undefined]` | Error message string |
+| `goTryRaw<T, E>(value, ErrorClass?)` | Returns `[E \| undefined, T \| undefined]` | Raw Error object or tagged error |
+| `goTryOr<T>(value, defaultValue)` | Returns `[string \| undefined, T]` | Error message with fallback default |
+| `goTryAll<T>(items, options?)` | Parallel execution, returns `[errors[], results[]]` | Error message strings |
+| `goTryAllRaw<T>(items, options?)` | Parallel execution, returns `[Error[], results[]]` | Raw Error objects |
+
+### Input Handling
+
+All `goTry*` functions accept:
+- Direct values
+- Functions (sync or async)
+- Promises
 
 ### Type Helpers
 
-- **`Result<E, T>`**: The tuple type `[E | undefined, T | undefined]`
+- **`Result<E, T>`**: The tuple type `[E \| undefined, T \| undefined]`
 - **`Success<T>`**: `[undefined, T]`
 - **`Failure<E>`**: `[E, undefined]`
+- **`TaggedError<T>`**: Interface for discriminated errors with `_tag` property
+- **`TaggedUnion<T>`**: Creates union type from multiple tagged error classes
 - **`isSuccess(result)`**: Type guard to check if result is success
 - **`isFailure(result)`**: Type guard to check if result is failure
+- **`success(value)`**: Helper to create Success tuple
+- **`failure(error)`**: Helper to create Failure tuple
 
-### Input Handling
+### Tagged Errors
 
-Both functions accept:
-- Direct values
-- Functions (sync or async)
-- Promises
+The `taggedError(tag)` function creates error classes with a `_tag` property for discriminated union pattern matching:
+
+```typescript
+const DatabaseError = taggedError('DatabaseError')
+const err = new DatabaseError('connection failed')
+// err._tag === 'DatabaseError'
+// err instanceof Error === true
+```
 
 ## Dual Package Support
 
@@ -141,6 +183,7 @@ The package supports both CommonJS and ESM consumers:
 
 ```json
 {
+  "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
@@ -153,17 +196,28 @@ The package supports both CommonJS and ESM consumers:
 
 ## CI/CD
 
-GitHub Actions workflow (`.github/workflows/main.yml`) runs on every push and PR:
+GitHub Actions workflow (`.github/workflows/main.yml`):
 
-- Tests against Node.js versions: 12, 14, 16, 18
-- Uses `yarn install` and `yarn test`
+### Test Job
+- Runs on every push and PR to `main`/`master`
+- Tests against Node.js versions: 18, 20, 22
+- Steps: checkout → setup Node → install → build → test with coverage
 - `fail-fast: false` to see results for all Node versions
+- Coverage uploaded to Codecov (Node 22 only)
+
+### Publish Job
+- Runs only on tag pushes (refs/tags/v*)
+- Depends on successful test job
+- Publishes to npm with provenance
+- Requires `NPM_TOKEN` secret
 
 ## Security Considerations
 
 - Zero runtime dependencies - reduces supply chain attack surface
 - Dev dependencies are locked via `package-lock.json`
 - Uses `type: "module"` for native ESM support
+- npm publishing uses provenance for supply chain security
+- CI has minimal permissions (`contents: read`, `id-token: write`)
 
 ## Development Workflow
 
@@ -171,6 +225,7 @@ GitHub Actions workflow (`.github/workflows/main.yml`) runs on every push and PR
 2. Add/update tests in `src/index.test.ts`
 3. Run `npm test` to verify build, lint, and tests pass
 4. The CI will test against multiple Node.js versions on push
+5. To release: push a version tag (e.g., `v7.2.1`) to trigger npm publish
 
 ## Notes for AI Agents
 
@@ -180,3 +235,6 @@ GitHub Actions workflow (`.github/workflows/main.yml`) runs on every push and PR
 - Maintain dual CJS/ESM compatibility when making changes
 - Follow the existing function overload patterns for type inference
 - Error handling should preserve the Go-style tuple return pattern
+- Use `taggedError()` for creating discriminated error types
+- The `goTryAll` function supports both promise arrays and factory function arrays for lazy execution
+- When adding new functions, include both runtime tests and type tests with `attest()`

package/README.md

@@ -46,10 +46,10 @@ const [err, todos = []] = await goTry(fetchTodos()) // err is string | undefined
 if (err) sendToErrorTrackingService(err)
 
 // goTry extracts the error message from the error object, if you want the raw error object, use goTryRaw
-const [err, value] = goTryRaw(() => JSON.parse('{/}')) // err is Error | undefined, value is T | undefined
+const [err, value] = goTryRaw(() => JSON.parse('{/}')) // err is UnknownError | undefined, value is T | undefined
 
 // fetch todos, fallback to empty array, send error to your error tracking service
-const [err, todos = []] = await goTryRaw(fetchTodos()) // err is Error | undefined
+const [err, todos = []] = await goTryRaw(fetchTodos()) // err is UnknownError | undefined
 if (err) sendToErrorTrackingService(err)
 ```
 
@@ -233,10 +233,10 @@ type AppErrorVerbose =
 
 // Use in functions with typed error returns
 async function fetchUser(id: string): Promise<Result<AppError, User>> {
-  const [dbErr, user] = await goTryRaw(queryDatabase(id), DatabaseError)
+  const [dbErr, user] = await goTryRaw(queryDatabase(id), { errorClass: DatabaseError })
   if (dbErr) return failure(dbErr)
   
-  const [netErr, enriched] = await goTryRaw(enrichUserData(user!), NetworkError)
+  const [netErr, enriched] = await goTryRaw(enrichUserData(user!), { errorClass: NetworkError })
   if (netErr) return failure(netErr)
   
   return [undefined, enriched] as const
@@ -318,32 +318,51 @@ Executes a function, promise, or value and returns a Result type with error mess
 function goTry<T>(value: T | Promise<T> | (() => T | Promise<T>)): Result<string, T> | Promise<Result<string, T>>
 ```
 
-### `goTryRaw<T, E>(value, ErrorClass?)`
+### `goTryRaw<T, E>(value, options?)`
 
 Like `goTry` but returns the raw Error object instead of just the message.
 
-Optionally accepts an error constructor to wrap caught errors - useful with `taggedError` for discriminated unions.
+By default, errors are wrapped in `UnknownError` (a tagged error class). You can customize this behavior with the options object:
 
 ```ts
-// Without ErrorClass - err is Error | undefined
-function goTryRaw<T, E = Error>(value: T | Promise<T> | (() => T | Promise<T>)): Result<E, T> | Promise<Result<E, T>>
+type GoTryRawOptions<E> =
+  | { errorClass: ErrorConstructor<E> }           // Wrap ALL errors in this class
+  | { systemErrorClass: ErrorConstructor<E> }     // Only wrap non-tagged errors
+  | {}                                            // Use defaults
+```
+
+> **Note:** `errorClass` and `systemErrorClass` are **mutually exclusive**. TypeScript will show an error if you try to pass both.
+> - Use `errorClass` when you want all errors wrapped in a specific type
+> - Use `systemErrorClass` when you want tagged errors to pass through and only wrap untagged errors
+
+```ts
+// Without options - err is UnknownError | undefined
+function goTryRaw<T>(value: T | Promise<T> | (() => T | Promise<T>)): Result<UnknownError, T> | Promise<Result<UnknownError, T>>
 
-// With ErrorClass - err is E | undefined (e.g., DatabaseError | undefined)
-function goTryRaw<T, E>(value: T | Promise<T> | (() => T | Promise<T>), ErrorClass: ErrorConstructor<E>): Result<E, T> | Promise<Result<E, T>>
+// With options object - err is E | undefined
+function goTryRaw<T, E>(value: T | Promise<T> | (() => T | Promise<T>), options: GoTryRawOptions<E>): Result<E, T> | Promise<Result<E, T>>
 ```
 
-**Example:**
+**Examples:**
+
 ```ts
 const DatabaseError = taggedError('DatabaseError')
+const NetworkError = taggedError('NetworkError')
 
-// Raw error (default)
+// Default - errors wrapped in UnknownError
 const [err1, data1] = await goTryRaw(fetchData())
-// err1 is Error | undefined
+// err1 is UnknownError | undefined
+// err1?._tag === 'UnknownError'
 
-// Tagged error
-const [err2, data2] = await goTryRaw(fetchData(), DatabaseError)
+// Options object - wrap all errors
+const [err2, data2] = await goTryRaw(fetchData(), { errorClass: DatabaseError })
 // err2 is DatabaseError | undefined
-// err2._tag is 'DatabaseError' - enables discriminated unions
+// err2?._tag === 'DatabaseError'
+
+// Options object - systemErrorClass only wraps non-tagged errors
+const [err3, data3] = await goTryRaw(fetchData(), { systemErrorClass: NetworkError })
+// If fetchData throws a tagged error (e.g., DatabaseError), it passes through
+// If fetchData throws a plain Error, it gets wrapped in NetworkError
 ```
 
 ### `goTryAll<T>(items, options?)`
@@ -453,6 +472,47 @@ console.log(err.name)    // 'DatabaseError'
 console.log(err.cause)   // originalError
 ```
 
+### `UnknownError`
+
+A default tagged error class used by `goTryRaw` when no options are provided, or when `systemErrorClass` is not specified in the options object.
+
+```ts
+import { UnknownError, goTryRaw } from 'go-go-try'
+
+// Errors are automatically wrapped in UnknownError
+const [err, data] = goTryRaw(() => {
+  throw new Error('something went wrong')
+})
+
+if (err) {
+  console.log(err._tag)    // 'UnknownError'
+  console.log(err.message) // 'something went wrong'
+  console.log(err.cause)   // original Error
+}
+```
+
+Since `UnknownError` is the default for `systemErrorClass`, you can distinguish between known tagged errors and unexpected system errors without specifying any options:
+
+```ts
+const DatabaseError = taggedError('DatabaseError')
+
+function fetchData() {
+  // Operations that might throw DatabaseError should use errorClass to wrap them
+  const [err1, data1] = goTryRaw(() => queryDatabase(), { errorClass: DatabaseError })
+  
+  // Other operations use the default behavior - non-tagged errors become UnknownError
+  const [err2, data2] = goTryRaw(() => parseData(data1))
+  // err2 is UnknownError | undefined
+  
+  // Now you can distinguish between known and unknown error types
+  if (err1) {
+    console.log('Known DB error:', err1.message)
+  } else if (err2) {
+    console.log('Unexpected error:', err2.message)
+  }
+}
+```
+
 ### `TaggedUnion<T>`
 
 Creates a union type from multiple tagged error classes.
@@ -487,11 +547,11 @@ When using `goTryRaw` with different error classes in the same function, TypeScr
 // No explicit return type needed!
 async function fetchUserData(id: string) {
   // First operation might fail with DatabaseError
-  const [dbErr, user] = await goTryRaw(queryDb(id), DatabaseError)
+  const [dbErr, user] = await goTryRaw(queryDb(id), { errorClass: DatabaseError })
   if (dbErr) return failure(dbErr)  // returns Failure<DatabaseError>
 
   // Second operation might fail with NetworkError  
-  const [netErr, enriched] = await goTryRaw(enrichUser(user!), NetworkError)
+  const [netErr, enriched] = await goTryRaw(enrichUser(user!), { errorClass: NetworkError })
   if (netErr) return failure(netErr)  // returns Failure<NetworkError>
 
   return success(enriched)  // returns Success<User>
@@ -525,6 +585,12 @@ type Result<E, T> = Success<T> | Failure<E>
 type TaggedInstance<T> = T extends ErrorConstructor<infer E> ? E : never
 type TaggedUnion<T extends readonly ErrorConstructor<unknown>[]> = 
   { [K in keyof T]: T[K] extends ErrorConstructor<infer E> ? E : never }[number]
+
+// Options for goTryRaw (errorClass and systemErrorClass are mutually exclusive)
+type GoTryRawOptions<E> =
+  | { errorClass: ErrorConstructor<E>; systemErrorClass?: never }
+  | { errorClass?: never; systemErrorClass: ErrorConstructor<E> }
+  | { errorClass?: never; systemErrorClass?: never }
 ```
 
 ## License

package/dist/index.cjs

@@ -1,15 +1,5 @@
 'use strict';
 
-function taggedError(tag) {
-  return class TaggedErrorClass extends Error {
-    constructor(message, options) {
-      super(message);
-      this._tag = tag;
-      this.name = tag;
-      this.cause = options?.cause;
-    }
-  };
-}
 function isSuccess(result) {
   return result[0] === void 0;
 }
@@ -22,9 +12,101 @@ function success(value) {
 function failure(error) {
   return [error, void 0];
 }
+function assertNever(value) {
+  throw new Error(`Unhandled case: ${String(value)}`);
+}
+
+function getErrorMessage(error) {
+  if (error === void 0) return "undefined";
+  if (typeof error === "string") return error;
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    return error.message;
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+function isPromise(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+function isError(value) {
+  return value instanceof Error;
+}
 function resolveDefault(defaultValue) {
   return typeof defaultValue === "function" ? defaultValue() : defaultValue;
 }
+
+function goTry(value) {
+  try {
+    const result = typeof value === "function" ? value() : value;
+    if (isPromise(result)) {
+      return result.then((resolvedValue) => success(resolvedValue)).catch((err) => failure(getErrorMessage(err)));
+    }
+    return success(result);
+  } catch (err) {
+    return failure(getErrorMessage(err));
+  }
+}
+
+function taggedError(tag) {
+  return class TaggedErrorClass extends Error {
+    constructor(message, options) {
+      super(message);
+      this._tag = tag;
+      this.name = tag;
+      this.cause = options?.cause;
+    }
+  };
+}
+
+const UnknownError = taggedError("UnknownError");
+
+function isTaggedError(err) {
+  return isError(err) && "_tag" in err && typeof err._tag === "string";
+}
+function goTryRaw(value, options) {
+  const { errorClass, systemErrorClass } = options || {};
+  const actualSystemErrorClass = systemErrorClass ?? UnknownError;
+  const wrapError = (err) => {
+    if (errorClass) {
+      if (err === void 0) {
+        return new errorClass("undefined");
+      }
+      if (isError(err)) {
+        return new errorClass(err.message, { cause: err });
+      }
+      return new errorClass(String(err));
+    }
+    if (actualSystemErrorClass) {
+      if (isTaggedError(err)) {
+        return err;
+      }
+      if (err === void 0) {
+        return new actualSystemErrorClass("undefined");
+      }
+      if (isError(err)) {
+        return new actualSystemErrorClass(err.message, { cause: err });
+      }
+      return new actualSystemErrorClass(String(err));
+    }
+    if (err === void 0) {
+      return new Error("undefined");
+    }
+    return isError(err) ? err : new Error(String(err));
+  };
+  try {
+    const result = typeof value === "function" ? value() : value;
+    if (isPromise(result)) {
+      return result.then((resolvedValue) => success(resolvedValue)).catch((err) => failure(wrapError(err)));
+    }
+    return success(result);
+  } catch (err) {
+    return failure(wrapError(err));
+  }
+}
+
 function goTryOr(value, defaultValue) {
   try {
     const result = typeof value === "function" ? value() : value;
@@ -36,6 +118,7 @@ function goTryOr(value, defaultValue) {
     return [getErrorMessage(err), resolveDefault(defaultValue)];
   }
 }
+
 async function runWithConcurrency(items, concurrency) {
   if (items.length === 0) {
     return [];
@@ -99,62 +182,22 @@ async function goTryAllRaw(items, options) {
   }
   return [errors, results];
 }
-function getErrorMessage(error) {
-  if (error === void 0) return "undefined";
-  if (typeof error === "string") return error;
-  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
-    return error.message;
-  }
-  try {
-    return JSON.stringify(error);
-  } catch {
-    return String(error);
-  }
-}
-function isPromise(value) {
-  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
-}
-function isError(value) {
-  return value instanceof Error;
-}
-function goTry(value) {
-  try {
-    const result = typeof value === "function" ? value() : value;
-    if (isPromise(result)) {
-      return result.then((resolvedValue) => success(resolvedValue)).catch((err) => failure(getErrorMessage(err)));
-    }
-    return success(result);
-  } catch (err) {
-    return failure(getErrorMessage(err));
-  }
-}
-function goTryRaw(value, ErrorClass) {
-  const wrapError = (err) => {
-    if (ErrorClass) {
-      if (err === void 0) {
-        return new ErrorClass("undefined");
-      }
-      if (isError(err)) {
-        return new ErrorClass(err.message, { cause: err });
-      }
-      return new ErrorClass(String(err));
-    }
-    if (err === void 0) {
-      return new Error("undefined");
+
+function assert(condition, errorOrClass, message) {
+  if (!condition) {
+    if (typeof errorOrClass === "string") {
+      throw new Error(errorOrClass);
     }
-    return isError(err) ? err : new Error(String(err));
-  };
-  try {
-    const result = typeof value === "function" ? value() : value;
-    if (isPromise(result)) {
-      return result.then((resolvedValue) => success(resolvedValue)).catch((err) => failure(wrapError(err)));
+    if (typeof errorOrClass === "function" && message !== void 0) {
+      throw new errorOrClass(message);
     }
-    return success(result);
-  } catch (err) {
-    return failure(wrapError(err));
+    throw errorOrClass;
   }
 }
 
+exports.UnknownError = UnknownError;
+exports.assert = assert;
+exports.assertNever = assertNever;
 exports.failure = failure;
 exports.goTry = goTry;
 exports.goTryAll = goTryAll;