go-go-try 7.0.0 → 7.2.0

package/AGENTS.md

@@ -0,0 +1,182 @@
+# go-go-try - Agent Guide
+
+## Project Overview
+
+**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
+- **License**: MIT
+- **Repository**: thelinuxlich/go-go-try
+- **Node.js Requirements**: >= 16
+
+## Technology Stack
+
+- **Language**: TypeScript 5.8.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
+
+## Project Structure
+
+```
+.
+├── src/
+│   ├── index.ts        # Main source file - exports goTry, goTryRaw, and utility types
+│   └── index.test.ts   # Comprehensive test suite with runtime and type tests
+├── dist/               # Build output (generated by pkgroll)
+│   ├── index.cjs       # CommonJS build
+│   ├── index.mjs       # ES Module build
+│   ├── index.d.cts     # CommonJS type definitions
+│   └── index.d.mts     # ES Module type definitions
+├── .github/workflows/
+│   └── main.yml        # CI configuration for GitHub Actions
+├── .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
+├── setupVitest.ts      # Vitest global setup for @ark/attest
+└── README.md           # User-facing documentation
+```
+
+## Build and Test Commands
+
+```bash
+# Build the project (generates dist/ with CJS, ESM, and type definitions)
+npm run build
+
+# Run linting with auto-fix
+npm run lint
+
+# Run the full test suite (build + lint + vitest)
+npm test
+```
+
+The test script is a composite that:
+1. Builds the project
+2. Runs the linter
+3. Executes Vitest tests
+
+## Code Style Guidelines
+
+- **Linter**: Biome is used for linting and formatting
+- **Configuration**: Uses Biome's default configuration (no biome.json present)
+- **Strict TypeScript**: The `tsconfig.json` enforces strict mode with additional checks:
+  - `noUnusedLocals`: true
+  - `noUnusedParameters`: true
+  - `allowUnreachableCode`: false
+  - `noUncheckedIndexedAccess`: true
+  - `noFallthroughCasesInSwitch`: true
+  - `forceConsistentCasingInFileNames`: true
+
+## Testing Instructions
+
+### Test Structure
+
+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
+
+### Key Testing Patterns
+
+```typescript
+// Runtime test
+import { assert, test } from 'vitest'
+test('description', () => {
+  const result = goTry(() => 'value')
+  assert.equal(result[1], 'value')
+})
+
+// Type test
+import { attest } from '@ark/attest'
+test('types are correct', () => {
+  const result = goTry('value')
+  attest<Result<string, string>>(result)
+})
+```
+
+### Running Tests
+
+```bash
+# Run all tests with type checking
+npx vitest run
+
+# Run tests in watch mode (during development)
+npx vitest
+```
+
+### Global Setup
+
+The `setupVitest.ts` file configures `@ark/attest` for type assertions in tests.
+
+## 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
+
+### Type Helpers
+
+- **`Result<E, T>`**: The tuple type `[E | undefined, T | undefined]`
+- **`Success<T>`**: `[undefined, T]`
+- **`Failure<E>`**: `[E, undefined]`
+- **`isSuccess(result)`**: Type guard to check if result is success
+- **`isFailure(result)`**: Type guard to check if result is failure
+
+### Input Handling
+
+Both functions accept:
+- Direct values
+- Functions (sync or async)
+- Promises
+
+## Dual Package Support
+
+The package supports both CommonJS and ESM consumers:
+
+```json
+{
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" },
+    "import": { "types": "./dist/index.d.mts", "default": "./dist/index.mjs" }
+  }
+}
+```
+
+## CI/CD
+
+GitHub Actions workflow (`.github/workflows/main.yml`) runs on every push and PR:
+
+- Tests against Node.js versions: 12, 14, 16, 18
+- Uses `yarn install` and `yarn test`
+- `fail-fast: false` to see results for all Node versions
+
+## 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
+
+## Development Workflow
+
+1. Make changes to `src/index.ts`
+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
+
+## Notes for AI Agents
+
+- Always run `npm test` after making changes to ensure build, lint, and tests pass
+- Type tests with `@ark/attest` are as important as runtime tests
+- The library has zero dependencies - avoid adding any
+- 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

package/README.md

@@ -99,8 +99,8 @@ const [errors, results] = await goTryAll([
   fetchComments(userId)
 ])
 
-// errors is (string | undefined)[]
-// results is (User | Posts | Comments | undefined)[]
+// errors is [string | undefined, string | undefined, string | undefined]
+// results is [User | undefined, Posts | undefined, Comments | undefined]
 
 const [user, posts, comments] = results
 ```
@@ -202,6 +202,88 @@ if (err === undefined) {
 }
 ```
 
+### Tagged Errors for Discriminated Unions
+
+Create typed errors with a `_tag` property for pattern matching and discriminated unions:
+
+```ts
+import { taggedError, goTryRaw, failure, type Result } from 'go-go-try'
+
+// Define error types
+const DatabaseError = taggedError('DatabaseError')
+const NetworkError = taggedError('NetworkError')
+const ValidationError = taggedError('ValidationError')
+
+// Create a union type
+import type { TaggedUnion } from 'go-go-try'
+
+// Option 1: Using TaggedUnion helper (cleaner)
+const DatabaseError = taggedError('DatabaseError')
+const NetworkError = taggedError('NetworkError')
+const ValidationError = taggedError('ValidationError')
+
+type AppError = TaggedUnion<[typeof DatabaseError, typeof NetworkError, typeof ValidationError]>
+// Equivalent to: DatabaseError | NetworkError | ValidationError
+
+// Option 2: Using InstanceType (standard TypeScript)
+type AppErrorVerbose = 
+  | InstanceType<typeof DatabaseError>
+  | InstanceType<typeof NetworkError>
+  | InstanceType<typeof ValidationError>
+
+// Use in functions with typed error returns
+async function fetchUser(id: string): Promise<Result<AppError, User>> {
+  const [dbErr, user] = await goTryRaw(queryDatabase(id), DatabaseError)
+  if (dbErr) return failure(dbErr)
+  
+  const [netErr, enriched] = await goTryRaw(enrichUserData(user!), NetworkError)
+  if (netErr) return failure(netErr)
+  
+  return [undefined, enriched] as const
+}
+
+// Pattern matching on errors
+const [err, user] = await fetchUser('123')
+if (err) {
+  switch (err._tag) {
+    case 'DatabaseError':
+      console.error('Database failed:', err.message)
+      break
+    case 'NetworkError':
+      console.error('Network issue:', err.message)
+      break
+    case 'ValidationError':
+      console.error('Invalid data:', err.message)
+      break
+  }
+}
+
+// Exhaustive switch with compile-time safety
+function assertNever(value: never): never {
+  throw new Error(`Unhandled case: ${String(value)}`)
+}
+
+function handleError(err: AppError): string {
+  switch (err._tag) {
+    case 'DatabaseError':
+      return `DB: ${err.message}`
+    case 'NetworkError':
+      return `NET: ${err.message}`
+    case 'ValidationError':
+      return `VAL: ${err.message}`
+    default:
+      // TypeScript will error here if any case is missing above
+      return assertNever(err)
+  }
+}
+```
+
+The `taggedError` function creates an error class with:
+- `_tag`: A readonly string literal for discriminated unions
+- `message`: The error message
+- `cause`: Optional cause for error chaining
+- `name`: Set to the tag value
+
 ### Helper Functions
 
 Build custom utilities on top of the primitives:
@@ -236,22 +318,86 @@ 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)`
+### `goTryRaw<T, E>(value, ErrorClass?)`
 
 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.
+
 ```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>>
+
+// 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>>
 ```
 
-### `goTryAll<T>(promises)`
+**Example:**
+```ts
+const DatabaseError = taggedError('DatabaseError')
 
-Executes multiple promises in parallel. Returns a tuple of `[errors, results]`.
+// Raw error (default)
+const [err1, data1] = await goTryRaw(fetchData())
+// err1 is Error | undefined
+
+// Tagged error
+const [err2, data2] = await goTryRaw(fetchData(), DatabaseError)
+// err2 is DatabaseError | undefined
+// err2._tag is 'DatabaseError' - enables discriminated unions
+```
+
+### `goTryAll<T>(items, options?)`
+
+Executes multiple promises or factory functions with optional concurrency limit. Returns a tuple of `[errors, results]` with fixed tuple types preserving input order.
 
 ```ts
+interface GoTryAllOptions {
+  concurrency?: number  // 0 = unlimited (default), 1 = sequential, N = max concurrent
+}
+
 function goTryAll<T extends readonly unknown[]>(
-  promises: { [K in keyof T]: Promise<T[K]> }
-): Promise<[string[] | undefined, { [K in keyof T]: T[K] | undefined }]>
+  items: { [K in keyof T]: Promise<T[K]> | (() => Promise<T[K]>) },
+  options?: GoTryAllOptions
+): Promise<[{ [K in keyof T]: string | undefined }, { [K in keyof T]: T[K] | undefined }]>
+```
+
+**Promise mode** (pass promises directly):
+```ts
+// Run all in parallel (default):
+const [errors, results] = await goTryAll([
+  fetchUser(1),      // Promise<User>
+  fetchUser(2),      // Promise<User>
+  fetchUser(3),      // Promise<User>
+])
+// errors: [string | undefined, string | undefined, string | undefined]
+// results: [User | undefined, User | undefined, User | undefined]
+```
+
+**Factory mode** (pass functions that return promises):
+```ts
+// True lazy execution - factories only called when a slot is available
+const [errors, results] = await goTryAll([
+  () => fetchUser(1),  // Only called when concurrency slot available
+  () => fetchUser(2),  // Only called when concurrency slot available
+  () => fetchUser(3),  // Only called when concurrency slot available
+  () => fetchUser(4),  // Only called when concurrency slot available
+], { concurrency: 2 })
+
+// Use factory mode when you need to:
+// - Rate limit API calls (don't start HTTP requests until allowed)
+// - Control database connection limits
+// - Limit expensive computation resources
+```
+
+### `goTryAllRaw<T>(items, options?)`
+
+Like `goTryAll`, but returns raw Error objects instead of error messages.
+
+```ts
+function goTryAllRaw<T extends readonly unknown[]>(
+  items: { [K in keyof T]: Promise<T[K]> | (() => Promise<T[K]>) },
+  options?: GoTryAllOptions
+): Promise<[{ [K in keyof T]: Error | undefined }, { [K in keyof T]: T[K] | undefined }]>
 ```
 
 ### `goTryOr<T>(value, defaultValue)`
@@ -281,12 +427,120 @@ function success<T>(value: T): Success<T>
 function failure<E>(error: E): Failure<E>
 ```
 
+### `taggedError<T>(tag)`
+
+Creates a tagged error class for discriminated error handling. Returns a class constructor that extends `Error` and includes a readonly `_tag` property.
+
+```ts
+function taggedError<T extends string>(tag: T): TaggedErrorClass<T>
+
+// Returned class interface:
+class TaggedErrorClass<T> extends Error implements TaggedError<T> {
+  readonly _tag: T
+  readonly cause?: unknown
+  constructor(message: string, options?: { cause?: unknown })
+}
+```
+
+**Example:**
+```ts
+const DatabaseError = taggedError('DatabaseError')
+const err = new DatabaseError('connection failed', { cause: originalError })
+
+console.log(err._tag)    // 'DatabaseError'
+console.log(err.message) // 'connection failed'
+console.log(err.name)    // 'DatabaseError'
+console.log(err.cause)   // originalError
+```
+
+### `TaggedInstance<T>`
+
+Extracts the instance type from a tagged error class. Cleaner alternative to `InstanceType<typeof ErrorClass>`.
+
+```ts
+type TaggedInstance<T extends ErrorConstructor<unknown>> = 
+  T extends ErrorConstructor<infer E> ? E : never
+```
+
+**Example:**
+```ts
+const DatabaseError = taggedError('DatabaseError')
+type DbError = TaggedInstance<typeof DatabaseError>
+// Equivalent to: InstanceType<typeof DatabaseError>
+```
+
+### `TaggedUnion<T>`
+
+Creates a union type from multiple tagged error classes.
+
+```ts
+type TaggedUnion<T extends readonly ErrorConstructor<unknown>[]> = 
+  { [K in keyof T]: T[K] extends ErrorConstructor<infer E> ? E : never }[number]
+```
+
+**Example:**
+```ts
+const DatabaseError = taggedError('DatabaseError')
+const NetworkError = taggedError('NetworkError')
+const ValidationError = taggedError('ValidationError')
+
+// Before (verbose):
+type AppErrorVerbose = 
+  | InstanceType<typeof DatabaseError>
+  | InstanceType<typeof NetworkError>
+  | InstanceType<typeof ValidationError>
+
+// After (clean):
+type AppError = TaggedUnion<[typeof DatabaseError, typeof NetworkError, typeof ValidationError]>
+// Results in: DatabaseError | NetworkError | ValidationError
+```
+
+#### Automatic Union Inference
+
+When using `goTryRaw` with different error classes in the same function, TypeScript **automatically infers** the union type without needing explicit type annotations:
+
+```ts
+// No explicit return type needed!
+async function fetchUserData(id: string) {
+  // First operation might fail with DatabaseError
+  const [dbErr, user] = await goTryRaw(queryDb(id), DatabaseError)
+  if (dbErr) return failure(dbErr)  // returns Failure<DatabaseError>
+
+  // Second operation might fail with NetworkError  
+  const [netErr, enriched] = await goTryRaw(enrichUser(user!), NetworkError)
+  if (netErr) return failure(netErr)  // returns Failure<NetworkError>
+
+  return success(enriched)  // returns Success<User>
+}
+
+// TypeScript infers: Promise<Result<DatabaseError | NetworkError, User>>
+// No TaggedUnion or explicit types needed!
+```
+
+The inferred union enables exhaustive pattern matching:
+
+```ts
+const [err, user] = await fetchUserData('123')
+if (err) {
+  switch (err._tag) {
+    case 'DatabaseError': /* handle db error */ break
+    case 'NetworkError': /* handle network error */ break
+    default: assertNever(err) // compile-time safety
+  }
+}
+```
+
 ## Types
 
 ```ts
 type Success<T> = readonly [undefined, T]
 type Failure<E> = readonly [E, undefined]
 type Result<E, T> = Success<T> | Failure<E>
+
+// Error type helpers
+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]
 ```
 
 ## License

package/dist/index.cjs

@@ -1,5 +1,15 @@
 '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;
 }
@@ -26,34 +36,65 @@ function goTryOr(value, defaultValue) {
     return [getErrorMessage(err), resolveDefault(defaultValue)];
   }
 }
-async function goTryAll(promises) {
-  const settled = await Promise.allSettled(promises);
+async function runWithConcurrency(items, concurrency) {
+  if (items.length === 0) {
+    return [];
+  }
+  const isFactoryMode = typeof items[0] === "function";
+  if (!isFactoryMode && concurrency <= 0) {
+    return Promise.allSettled(items);
+  }
+  const results = new Array(items.length);
+  let index = 0;
+  async function worker() {
+    while (index < items.length) {
+      const currentIndex = index++;
+      try {
+        const item = items[currentIndex];
+        const value = isFactoryMode ? await item() : await item;
+        results[currentIndex] = { status: "fulfilled", value };
+      } catch (reason) {
+        results[currentIndex] = { status: "rejected", reason };
+      }
+    }
+  }
+  const workerCount = concurrency <= 0 ? items.length : Math.min(concurrency, items.length);
+  const workers = [];
+  for (let i = 0; i < workerCount; i++) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  return results;
+}
+async function goTryAll(items, options) {
+  const settled = await runWithConcurrency(items, options?.concurrency ?? 0);
   const errors = [];
   const results = [];
-  for (const item of settled) {
+  for (let i = 0; i < settled.length; i++) {
+    const item = settled[i];
     if (item.status === "fulfilled") {
-      errors.push(void 0);
-      results.push(item.value);
+      errors[i] = void 0;
+      results[i] = item.value;
     } else {
-      errors.push(getErrorMessage(item.reason));
-      results.push(void 0);
+      errors[i] = getErrorMessage(item.reason);
+      results[i] = void 0;
     }
   }
   return [errors, results];
 }
-async function goTrySettled(promises) {
-  const settled = await Promise.allSettled(promises);
+async function goTryAllRaw(items, options) {
+  const settled = await runWithConcurrency(items, options?.concurrency ?? 0);
   const errors = [];
   const results = [];
-  for (const item of settled) {
+  for (let i = 0; i < settled.length; i++) {
+    const item = settled[i];
     if (item.status === "fulfilled") {
-      errors.push(void 0);
-      results.push(item.value);
+      errors[i] = void 0;
+      results[i] = item.value;
     } else {
-      errors.push(
-        isError(item.reason) ? item.reason : new Error(String(item.reason))
-      );
-      results.push(void 0);
+      const reason = item.reason;
+      errors[i] = isError(reason) ? reason : new Error(String(reason));
+      results[i] = void 0;
     }
   }
   return [errors, results];
@@ -87,33 +128,40 @@ function goTry(value) {
     return failure(getErrorMessage(err));
   }
 }
-function goTryRaw(value) {
+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");
+    }
+    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) => {
-        if (err === void 0) {
-          return failure(new Error("undefined"));
-        }
-        return failure(
-          isError(err) ? err : new Error(String(err))
-        );
-      });
+      return result.then((resolvedValue) => success(resolvedValue)).catch((err) => failure(wrapError(err)));
     }
     return success(result);
   } catch (err) {
-    return failure(
-      isError(err) ? err : new Error(String(err))
-    );
+    return failure(wrapError(err));
   }
 }
 
 exports.failure = failure;
 exports.goTry = goTry;
 exports.goTryAll = goTryAll;
+exports.goTryAllRaw = goTryAllRaw;
 exports.goTryOr = goTryOr;
 exports.goTryRaw = goTryRaw;
-exports.goTrySettled = goTrySettled;
 exports.isFailure = isFailure;
 exports.isSuccess = isSuccess;
 exports.success = success;
+exports.taggedError = taggedError;