resultar 3.6.0 → 3.8.0

package/dist/agent/references/api.md

@@ -0,0 +1,249 @@
+# Resultar v3.7+ API Guide
+
+Use this reference after checking the version installed by the consuming project. The local package
+types and source are authoritative when they differ from this guide.
+
+## Contents
+
+- [Package Baseline](#package-baseline)
+- [Core Types And Constructors](#core-types-and-constructors)
+- [Composition And Recovery](#composition-and-recovery)
+- [Tagged Errors](#tagged-errors)
+- [Boundary Matching](#boundary-matching)
+- [Async Boundaries](#async-boundaries)
+- [Async Policies](#async-policies)
+- [Collections And Control Flow](#collections-and-control-flow)
+- [`safeTry`](#safetry)
+- [ResultTask (Lazy Workflows)](#resulttask-lazy-workflows)
+- [Observation And Cleanup](#observation-and-cleanup)
+
+## Package Baseline
+
+Resultar v3.7 is an ESM package targeting Node.js 24+. The repository currently uses TypeScript 7.
+Do not infer consumer requirements from memory: inspect `package.json`, the lockfile, and exported
+types first.
+
+Prefer named imports and type-only imports:
+
+```ts
+import { ResultAsync, createTaggedError, ok, safeTry, tryResult, tryResultAsync } from "resultar";
+import type { StrictResult, StrictResultAsync } from "resultar";
+```
+
+`tryCatch` and `tryCatchAsync` remain compatibility aliases. Prefer `tryResult` and
+`tryResultAsync` in new v3.7+ code.
+
+## Core Types And Constructors
+
+| Need                                                | API                                      |
+| --------------------------------------------------- | ---------------------------------------- |
+| Synchronous fallible value                          | `Result<T, E>`                           |
+| Asynchronous fallible value                         | `ResultAsync<T, E>`                      |
+| Error-only sync channel                             | `StrictResult<T, E extends Error>`       |
+| Error-only async channel                            | `StrictResultAsync<T, E extends Error>`  |
+| Successful value                                    | `ok(value)` / `okAsync(value)`           |
+| Successful `undefined`                              | `unit()` / `unitAsync()`                 |
+| Expected failure                                    | `err(error)` / `errAsync(error)`         |
+| Catch synchronous throws now                        | `tryResult(fn, toError)`                 |
+| Wrap a synchronous throwing function                | `fromThrowable(fn, toError)`             |
+| Catch promise rejection or a throwing async factory | `tryResultAsync(input, toError)`         |
+| Wrap an async throwing function                     | `fromThrowableAsync(fn, toError)`        |
+| Deliberately leave Resultar at a terminal boundary  | `runSync(result)` / `runPromise(result)` |
+
+Use the named options form when it improves readability:
+
+```ts
+const parsed = tryResult({
+  try: () => JSON.parse(input) as unknown,
+  catch: (cause) => new ParsePayloadError({ cause }),
+});
+```
+
+`runSync` returns the `Ok` value or throws the `Err`; `runPromise` resolves the `Ok` value or
+rejects with the `Err`. Keep both at framework, bootstrap, CLI, or test boundaries.
+
+## Composition And Recovery
+
+- `map` transforms an `Ok` value with an infallible function.
+- `mapErr` transforms an `Err` value.
+- `filterOrElse` validates or narrows an `Ok` value and introduces a typed error on failure.
+- `andThen` chains fallible work. On `ResultAsync`, it accepts sync or async Resultar work.
+- `asyncAndThen` bridges a synchronous `Result` into `ResultAsync`.
+- `orElse` recovers the complete error channel.
+- `catchTag` recovers one tagged error.
+- `catchTags` recovers selected tagged errors; unhandled variants stay in the error union.
+- `pipe` applies named combinators without changing Result semantics.
+
+Let each step expose its narrow error type and let composition infer the union:
+
+```ts
+type CreateUserError = InvalidEmailError | UserExistsError | SaveUserError;
+
+const createUser = (input: CreateUserInput): StrictResultAsync<User, CreateUserError> =>
+  validateEmail(input.email)
+    .asyncAndThen(ensureEmailAvailable)
+    .andThen((email) => saveUser({ ...input, email }));
+```
+
+Do not manually cast the final error union. A surprising inferred union is usually evidence that a
+step has a broad or inaccurate signature.
+
+## Tagged Errors
+
+`createTaggedError` creates nominal `Error` subclasses with stable `_tag`, message-template props,
+`cause`, `fingerprint`, `toJSON()`, and `.err()` support.
+
+```ts
+class UserNotFoundError extends createTaggedError({
+  name: "UserNotFoundError",
+  message: "User $userId was not found in $source",
+}) {}
+
+const missing = UserNotFoundError.err({ userId, source: "database" });
+```
+
+- Let `$variables` in the message template define required constructor props.
+- Preserve the original failure with `cause` when adapting external code.
+- Keep the configured `name` equal to the class name.
+- Do not override the generated constructor.
+- Treat `ErrorClass.is(value)` as a nominal `instanceof`-based guard; a matching `_tag` is not
+  sufficient.
+- Avoid reserved template fields such as `_tag`, `name`, `message`, `messageTemplate`,
+  `fingerprint`, `stack`, and `cause`.
+- Use `TaggedEnum`/`taggedEnum` for lightweight tagged data that should not be an `Error`.
+- Use `redact`, `isRedacted`, and `revealRedacted` when sensitive error metadata must not serialize
+  or log by default.
+- Use `findCause` or an instance's `findCause` to inspect a typed cause chain.
+
+## Boundary Matching
+
+Use branch methods inside an algorithm and matching when converting the completed result:
+
+- `isOk()` / `isErr()` narrow for direct control flow.
+- `match(onOk, onErr)` handles a simple boundary.
+- `matchTags(onOk, handlers)` exhaustively maps tagged errors.
+- `matchTagsPartial(onOk, handlers, fallback)` handles selected tags with a deliberate fallback.
+- `matchError(error, handlers)` handles an error value directly.
+- `matchErrorPartial(error, handlers, fallback)` partially handles an error value.
+
+Include an `Error` handler whenever an error union can contain an untagged `Error`. Do not invent
+`partialCatchTags`; `catchTags` already supports partial recovery.
+
+## Async Boundaries
+
+Choose the wrapper based on ownership of the promise:
+
+- `fromPromise(existingPromise, toError)` wraps a promise that has already been created.
+- `tryResultAsync(() => createPromise(), toError)` also catches synchronous factory throws and is
+  preferred when the agent controls creation.
+- `fromSafePromise(promise)` is only for promises guaranteed not to reject by contract.
+- `fromCallback(options)` adapts callback or subscription APIs and returns
+  `ResultAsync<T, E | AbortError>`. Supply cleanup and forward cancellation where supported.
+- `AbortError` and `isAbortError` identify Resultar cancellation.
+
+Always map `unknown` causes into a specific error near the external boundary:
+
+```ts
+const loadUser = (id: string): StrictResultAsync<User, LoadUserError> =>
+  tryResultAsync(
+    () => client.loadUser(id),
+    (cause) => new LoadUserError({ cause, id }),
+  );
+```
+
+## Async Policies
+
+Use the built-in lazy policies instead of hand-written `Promise.race`, timers, or retry loops:
+
+- `ResultAsync.retry(task, options)` retries typed failures and includes `AbortError` in the error
+  channel. Use `times`, `delayMs`, `jittered`, `while`, and the provided signal deliberately.
+- `ResultAsync.retryOrElse(task, options)` applies a typed fallback after retry exhaustion. The
+  exhausted task error is replaced by the fallback error channel.
+- `ResultAsync.timeout(task, options)` returns the task error or the typed `onTimeout` error.
+- `ResultAsync.race(left, right)` and `raceAll(tasks)` return the first settled result.
+- `ResultAsync.raceFirst(left, right)` returns the first `Ok`; if both fail, it returns the last
+  observed `Err`.
+- `ResultAsync.raceWith(left, right, handlers)` exposes the winner and a handle to the still-running
+  task for custom cooperative policy.
+- `ResultAsync.withResource({ acquire, use, release })` releases after every acquire-success path.
+  Release errors are best-effort and do not enter the result channel; model cleanup in `use` when it
+  must affect control flow.
+
+Race, timeout, retry, callback, and resource helpers rely on cooperative cancellation. Pass their
+`AbortSignal` into fetch, database, SDK, timer, or subscription work; aborting a wrapper cannot stop
+an underlying operation that ignores the signal.
+
+## Collections And Control Flow
+
+Both `Result` and `ResultAsync` provide collection helpers:
+
+- `combine` preserves array/tuple/record shape and returns the first error.
+- `combineWithAllErrors` collects every error.
+- `validateAll` collects all validation errors; async mapped use supports bounded `concurrency`.
+- `zip` combines exactly two values.
+- `firstSuccessOf` tries candidates until one succeeds and otherwise returns the final error.
+- `forEach` stops at the first error; use `{ discard: true }` when successful values are irrelevant.
+- `when`, `unless`, `loop`, and `iterate` model Resultar-native control flow where they improve
+  clarity.
+
+Prefer `ResultAsync.forEach(items, mapper, { concurrency })` for bounded first-error processing and
+`ResultAsync.validateAll(items, mapper, { concurrency })` for independent validation where every
+error matters.
+
+## `safeTry`
+
+Use `safeTry` when a linear generator is clearer than a chain:
+
+```ts
+const workflow = safeTry(async function* () {
+  const input = yield* validateInput(raw);
+  const remote = yield* loadRemote(input);
+  const saved = yield* saveRemote(remote);
+
+  return ok(saved);
+});
+```
+
+Use `yield*` for `Result` and `ResultAsync`. Wrap raw promises before yielding. Avoid raw `await`,
+`try/catch`, and legacy `safeUnwrap()` inside the generator.
+
+## ResultTask (Lazy Workflows)
+
+`ResultTask<A, E, R>` is a lazy, reusable description of work: building one starts nothing, and
+each `run*` call executes it again. Never substitute `ResultAsync` (already-started) where
+laziness matters.
+
+- Build: `succeed`, `fail`, `fromResult`, `sync`, `try`, `tryPromise` (`try`/`tryPromise` map
+  external throws into `E`; `sync` treats them as defects).
+- Compose lazily: `map`, `flatMap`, `catchAll`, `tap`, `gen` with `yield*` (also accepts
+  `yield* result`: `Ok` unwraps, `Err` short-circuits into `E`).
+- Provide services: `yield* Tag`, then `provideService` / `provideServices` /
+  `provideServiceResolver` (data-first and curried); missing or incompatible providers are
+  compile-time errors, never runtime surprises.
+- Resources: `acquireRelease` + `scoped`; LIFO awaited finalizers run on every exit; deferred
+  release errors live in `R` until `scoped` folds them into `E`; `catchAll` recovers a release
+  failure only after `scoped`.
+- Boundaries: `runExit` preserves `Success`/`Fail`/`Die`/`Interrupt`/`Sequential`; `runResult`
+  returns one `Err` and rejects the rest (`AbortError` for interrupts, `ResultTaskCauseError`
+  for composites); `runPromise` unwraps or rejects. Cancellation is cooperative: no fibers,
+  `race`, `timeout`, or scheduler exist on `ResultTask` yet — use the `ResultAsync` helpers.
+
+`Result.gen` is the canonical name for linear Result workflows; `safeTry` remains as its alias.
+For lazy `ResultTask` workflows with typed services and scopes, see `packages/resultar/README.md`
+(Lazy Workflows With ResultTask) and `docs/rfcs/rfc-0001-result-task-core.md`.
+
+## Observation And Cleanup
+
+On `Result` and `ResultAsync`, `tap`, `tapError`, and `log` preserve the original result. Callback throws and rejected callback
+promises are intentionally ignored, so use them only for best-effort logging, metrics, tracing, and
+observation. Use `andThen`, `orElse`, or a Resultar boundary when side-effect failure must alter the
+workflow.
+
+`toDisposable` and `toAsyncDisposable` integrate with Node.js `using` / `await using`; their
+cleanup callbacks are also best-effort. Prefer `withResource` for acquire/use/release workflows.
+
+On `ResultTask`, `tap` and `tapError` are lazy effectful composition. Returned task errors and
+requirements join the workflow type. A thrown callback or rejected Promise becomes `Die`;
+a returned `ResultTask.fail(error)` becomes a typed failure. Use an explicitly recovered task
+when observation must be best-effort. `runExit` preserves these exits; `runResult` can reject.
+Do not substitute `ResultAsync.withResource` for awaited ResultTask resource ownership.

package/dist/agent/references/integrations.md

@@ -0,0 +1,264 @@
+# Resultar Requests And Validation Tooling
+
+Use this reference for HTTP JSON integrations and Resultar-specific diagnostics. Verify package
+versions and local README files before copying an example.
+
+## Contents
+
+- [Choose A Request Package](#choose-a-request-package)
+- [Use The Schema-Agnostic Core](#use-the-schema-agnostic-core)
+- [Use The TypeBox Adapter](#use-the-typebox-adapter)
+- [Use The Zod Adapter](#use-the-zod-adapter)
+- [Map Request Errors](#map-request-errors)
+- [Apply Retry Correctly](#apply-retry-correctly)
+- [Validate In The Preferred Order](#validate-in-the-preferred-order)
+- [Configure The Native Checker](#configure-the-native-checker)
+- [Act On Diagnostics](#act-on-diagnostics)
+- [Discover Repository Commands](#discover-repository-commands)
+
+## Choose A Request Package
+
+| Contract style                   | Package                    | Success type                 |
+| -------------------------------- | -------------------------- | ---------------------------- |
+| Custom type guard or decoder     | `resultar-request`         | Type guard or decoder output |
+| TypeBox schema                   | `resultar-request-typebox` | `Static<typeof schema>`      |
+| Zod schema, including transforms | `resultar-request-zod`     | `z.output<typeof schema>`    |
+
+All three share the same transport implementation. The adapters add schema validation and re-export
+the public `resultar-request` types. Install only the core and schema adapter the service needs.
+
+Keep request payloads concrete. Do not widen a known response contract to `JsonRecord`,
+`Record<string, unknown>`, or `unknown` after validation.
+
+## Use The Schema-Agnostic Core
+
+Use a type guard when validation does not transform the payload:
+
+```ts
+import { requestJson } from "resultar-request";
+
+type User = { readonly email: string; readonly id: string };
+
+const isUser = (value: unknown): value is User =>
+  typeof value === "object" &&
+  value !== null &&
+  "email" in value &&
+  typeof value.email === "string" &&
+  "id" in value &&
+  typeof value.id === "string";
+
+const user = requestJson({
+  request: () => fetch(`https://example.com/users/${userId}`),
+  validator: isUser,
+});
+```
+
+Use `decode` when validation also normalizes or transforms the response. The decoder must make
+success and validation failure explicit; check the installed package types for the exact shape.
+
+## Use The TypeBox Adapter
+
+```ts
+import { createTaggedError } from "resultar";
+import {
+  requestJson as requestJsonTypeBox,
+  type RequestJsonMapError,
+} from "resultar-request-typebox";
+import { Type, type Static } from "typebox";
+
+const userSchema = Type.Object(
+  {
+    email: Type.String(),
+    id: Type.String(),
+    plan: Type.Union([Type.Literal("free"), Type.Literal("team")]),
+  },
+  { additionalProperties: false },
+);
+
+type User = Static<typeof userSchema>;
+
+class UserApiError extends createTaggedError({
+  name: "UserApiError",
+  message: "User API $reason: $detail",
+}) {}
+
+const mapUserError = {
+  404: ({ statusCode }) => new UserApiError({ detail: `HTTP ${statusCode}`, reason: "not-found" }),
+  http: ({ statusCode }) => new UserApiError({ detail: `HTTP ${statusCode}`, reason: "http" }),
+  invalidJson: ({ cause }) =>
+    new UserApiError({ cause, detail: cause.message, reason: "invalid-json" }),
+  request: ({ cause }) => new UserApiError({ cause, detail: cause.message, reason: "request" }),
+  validation: ({ errors }) =>
+    new UserApiError({ detail: `${errors.length} validation issue(s)`, reason: "validation" }),
+} satisfies RequestJsonMapError;
+
+const user = requestJsonTypeBox({
+  request: () => fetch(`https://example.com/users/${userId}`),
+  schema: userSchema,
+  mapError: mapUserError,
+  retry: { times: 2, delayMs: ({ nextAttempt }) => nextAttempt * 100, jittered: 0.2 },
+});
+```
+
+The success channel is `User`, derived from `Static<typeof userSchema>`. Keep the named adapter
+alias when a file uses more than one request helper or when the schema library should be obvious at
+the call site.
+
+## Use The Zod Adapter
+
+```ts
+import { createTaggedError } from "resultar";
+import { requestJson as requestJsonZod, type RequestJsonMapError } from "resultar-request-zod";
+import { z } from "zod";
+
+const userSchema = z
+  .object({ email: z.string().email(), id: z.string(), seats: z.number().int().nonnegative() })
+  .transform((user) => ({
+    ...user,
+    email: user.email.toLowerCase(),
+    seatLabel: `${user.seats} seats`,
+  }));
+
+type User = z.output<typeof userSchema>;
+
+class UserApiError extends createTaggedError({
+  name: "UserApiError",
+  message: "User API $reason: $detail",
+}) {}
+
+const mapUserError = {
+  404: ({ statusCode }) => new UserApiError({ detail: `HTTP ${statusCode}`, reason: "not-found" }),
+  http: ({ statusCode }) => new UserApiError({ detail: `HTTP ${statusCode}`, reason: "http" }),
+  invalidJson: ({ cause }) =>
+    new UserApiError({ cause, detail: cause.message, reason: "invalid-json" }),
+  request: ({ cause }) => new UserApiError({ cause, detail: cause.message, reason: "request" }),
+  validation: ({ errors }) =>
+    new UserApiError({ detail: `${errors.length} validation issue(s)`, reason: "validation" }),
+} satisfies RequestJsonMapError;
+
+const user = requestJsonZod({
+  request: () => fetch(`https://example.com/users/${userId}`),
+  schema: userSchema,
+  mapError: mapUserError,
+  retry: { times: 2, delayMs: ({ nextAttempt }) => nextAttempt * 100, jittered: 0.2 },
+});
+```
+
+Use `z.output`, not `z.input` or an independently maintained interface, because Zod transforms can
+change the success type.
+
+## Map Request Errors
+
+Without `mapError`, request helpers return the package's `RequestError` union. Use that union for
+infrastructure-local code. At an application boundary, use `mapError` to convert these categories
+to concrete tagged errors:
+
+- request creation, network, or fetch failure;
+- status-specific HTTP failure, with numeric handlers taking precedence over `http`;
+- invalid JSON;
+- response validation or decode failure.
+
+Preserve `cause` for request and JSON failures and preserve status, URL, validation details, and
+other safe context needed for diagnosis. Do not map every category to a message-only `Error`.
+
+## Apply Retry Correctly
+
+```ts
+const user = requestJsonZod({
+  request: () => fetch(`https://example.com/users/${userId}`),
+  schema: userSchema,
+  retry: { times: 2, delayMs: ({ nextAttempt }) => nextAttempt * 100, jittered: 0.2 },
+});
+```
+
+The default policy retries request failures and HTTP `5xx`, but not `4xx`, invalid JSON, or
+validation failures. Retry requires a request factory; an already-created promise cannot be
+restarted. Ensure each attempt receives a fresh request. The current request retry configuration
+does not expose ResultAsync's internal retry signal, so do not claim that `requestJson`
+automatically forwards policy cancellation. Supply an external fetch signal through the request
+closure when the caller owns separate cancellation.
+
+## Validate In The Preferred Order
+
+1. Run the native `resultar-check` CLI as the authoritative local and CI gate. It uses TypeScript-Go
+   to run compiler diagnostics and all Resultar rules over the same project.
+2. Run the repository's formatter, build, tests, static analysis, package smoke tests, and runnable
+   examples.
+
+The Go analyzer is the single implementation of Resultar diagnostics.
+
+## Configure The Native Checker
+
+Install Resultar Check. A separate TypeScript installation is not required:
+
+```sh
+pnpm add -D resultar-check
+pnpm exec resultar-check
+```
+
+Add the checker configuration marker to `tsconfig.json` and tune rules only when project policy
+requires it:
+
+```json
+{
+  "$schema": "./node_modules/resultar-check/schema.json",
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "resultar-check",
+        "noDiscard": "error",
+        "noUnsafeAwait": "error",
+        "preferAndThen": "error",
+        "preferMapErr": "error",
+        "unsafeResultTypeAssertion": "error"
+      }
+    ]
+  }
+}
+```
+
+The `plugins` entry is consumed by the native CLI and stdio LSP server; it does not install an editor
+extension. Start `resultar-check lsp` from the editor's language-server configuration. Findings use
+rule IDs such as `resultar/no-discard`; pass `--format json` (or `--json`) when machine-readable JSON
+Lines output is needed.
+
+Read `packages/check/README.md` for all rules, severities, modes, and command-line flags. Use narrow
+`ignoreFilePatterns` only for deliberate tests, scripts, generated files, or terminal process boundaries.
+
+## Act On Diagnostics
+
+When an agent encounters a diagnostic, fix the architecture first:
+
+- handle, compose, return, or intentionally discard a returned Resultar value; a discard does not
+  run a lazy task and must not be applied just to silence diagnostics;
+- replace nested `Result` from `map` with `andThen`;
+- replace `Promise<Result>` / `Promise<StrictResult>` contracts with `ResultAsync` /
+  `StrictResultAsync` and return composed operations directly (`prefer-result-async`);
+- enable `preferResultAsyncMode: "all"` with `preferResultAsync: "error"` to also catch raw
+  `Promise<T>` repository/service contracts and inferred returns; map driver errors in adapters
+  and document local suppressions for required native framework or conversion callbacks;
+- replace error-only recovery with `mapErr`;
+- replace project-wide `try/catch` with `tryResult` or `tryResultAsync` when `noTryCatch` is enabled;
+- wrap raw promise awaits in Resultar contexts;
+- use `yield*` and avoid `try/catch` inside `Result.gen` / `safeTry`;
+- preserve the inferred error channel instead of asserting it away.
+
+## Discover Repository Commands
+
+Inspect `package.json` scripts instead of assuming a package manager or command. In the Resultar
+repository, the relevant root commands currently include:
+
+```sh
+pnpm fmt:check
+pnpm build
+pnpm check
+pnpm test
+pnpm analyze
+pnpm smoke:package
+pnpm test:examples
+pnpm test:agents
+```
+
+Run the narrowest useful command while iterating, then the complete relevant validation set before
+claiming completion. Report pre-existing dependency, lockfile, or environment blockers separately
+from failures introduced by the skill work.