go-go-try 7.2.0 → 7.3.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

@@ -453,22 +453,6 @@ 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.

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,71 @@ 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 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) => 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 +88,7 @@ function goTryOr(value, defaultValue) {
     return [getErrorMessage(err), resolveDefault(defaultValue)];
   }
 }
+
 async function runWithConcurrency(items, concurrency) {
   if (items.length === 0) {
     return [];
@@ -99,62 +152,32 @@ 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)));
+
+function taggedError(tag) {
+  return class TaggedErrorClass extends Error {
+    constructor(message, options) {
+      super(message);
+      this._tag = tag;
+      this.name = tag;
+      this.cause = options?.cause;
     }
-    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.assert = assert;
+exports.assertNever = assertNever;
 exports.failure = failure;
 exports.goTry = goTry;
 exports.goTryAll = goTryAll;