resultar 3.6.0 → 3.8.0

package/dist/agent/references/patterns.md

@@ -0,0 +1,246 @@
+# Resultar Implementation Patterns
+
+Use these patterns as starting points, then align names and types with the consuming domain.
+
+## Contents
+
+- [Model A Domain Failure](#model-a-domain-failure)
+- [Compose Sync And Async Steps](#compose-sync-and-async-steps)
+- [Write A Linear Workflow](#write-a-linear-workflow)
+- [Wrap External Work](#wrap-external-work)
+- [Apply Retry And Timeout Policy](#apply-retry-and-timeout-policy)
+- [Process Batches](#process-batches)
+- [Acquire And Release Resources](#acquire-and-release-resources)
+- [Recover Locally And Match At Boundaries](#recover-locally-and-match-at-boundaries)
+- [Add Observability](#add-observability)
+- [Migrate Incrementally](#migrate-incrementally)
+- [Test Runtime And Type Behavior](#test-runtime-and-type-behavior)
+
+## Model A Domain Failure
+
+```ts
+import { createTaggedError, ok } from "resultar";
+import type { StrictResult } from "resultar";
+
+class InvalidEmailError extends createTaggedError({
+  name: "InvalidEmailError",
+  message: "Invalid email $email",
+}) {}
+
+const validateEmail = (email: string): StrictResult<string, InvalidEmailError> =>
+  email.includes("@") ? ok(email.trim().toLowerCase()) : InvalidEmailError.err({ email });
+```
+
+Use real tagged errors when the failure crosses a service, HTTP, job, queue, CLI, or integration
+boundary. Keep strings, enums, or `TaggedEnum` variants for intentionally local flows.
+
+## Compose Sync And Async Steps
+
+```ts
+type CreateUserError = InvalidEmailError | UserAlreadyExistsError | SaveUserError;
+
+const createUser = (input: CreateUserInput): StrictResultAsync<User, CreateUserError> =>
+  validateEmail(input.email)
+    .asyncAndThen(ensureEmailAvailable)
+    .andThen((email) => saveUser({ ...input, email }));
+```
+
+- Use `map` only for an infallible value transform.
+- Use `filterOrElse` for predicate validation.
+- Use `andThen` when the next operation can fail.
+- Use `asyncAndThen` only for the sync-to-async bridge.
+- Keep each function's error type narrow and allow the final union to be inferred.
+
+## Write A Linear Workflow
+
+```ts
+const createUser = (input: CreateUserInput): StrictResultAsync<User, CreateUserError> =>
+  Result.gen(async function* () {
+    const email = yield* validateEmail(input.email);
+    yield* ensureEmailAvailable(email);
+    const user = yield* saveUser({ ...input, email });
+
+    return ok(user);
+  });
+```
+
+Use `yield*` for every fallible Resultar step. Wrap an uncontrolled promise with
+`tryResultAsync` before yielding it. Do not mix raw `await` or broad `try/catch` into the generator.
+
+## Wrap External Work
+
+```ts
+class ProfileApiError extends createTaggedError({
+  name: "ProfileApiError",
+  message: "Profile API failed for $userId",
+}) {}
+
+type LoadProfileOptions = {
+  readonly attempt?: number;
+  readonly signal?: AbortSignal;
+};
+
+const loadProfile = (
+  userId: string,
+  options: LoadProfileOptions = {},
+): StrictResultAsync<Profile, ProfileApiError> =>
+  tryResultAsync(
+    () => profileClient.load(userId, options),
+    (cause) => new ProfileApiError({ cause, userId }),
+  );
+```
+
+Prefer a promise factory because creating the promise may throw synchronously. Use
+`fromPromise(existingPromise, mapper)` only when the promise already exists, and use
+`fromSafePromise` only when non-rejection is guaranteed by contract.
+
+For callback or subscription APIs, use `fromCallback` and return cleanup from `subscribe`:
+
+```ts
+const message = fromCallback<Message, SubscriptionError>({
+  catch: (cause) => new SubscriptionError({ cause, topic }),
+  signal,
+  subscribe: ({ resolve, reject }) => {
+    const subscription = client.subscribe(topic, resolve, reject);
+
+    return () => subscription.close();
+  },
+});
+```
+
+Check the installed `ResultAsyncFromCallbackOptions` type for exact client integration details.
+
+## Apply Retry And Timeout Policy
+
+```ts
+const profile = ResultAsync.timeout(
+  (signal) =>
+    ResultAsync.retry(
+      (attempt, retrySignal) => loadProfile(userId, { attempt, signal: retrySignal }),
+      {
+        times: 2,
+        delayMs: ({ nextAttempt }) => nextAttempt * 100,
+        jittered: 0.2,
+        while: (error) => error._tag === "ProfileApiError",
+        signal,
+      },
+    ),
+  {
+    timeoutMs: 1_500,
+    onTimeout: () => new ProfileTimeoutError({ timeoutMs: 1_500, userId }),
+  },
+);
+```
+
+Forward the supplied signal into the underlying operation. Confirm whether the desired timeout
+covers each attempt or the complete retry budget, then nest the policies accordingly. Use
+`retryOrElse` only when fallback after exhaustion is domain policy.
+
+Choose races deliberately:
+
+- `race` / `raceAll`: first settled `Ok` or `Err` wins.
+- `raceFirst`: first `Ok` wins; both must fail before an `Err` is returned.
+- `raceWith`: winner-specific logic needs access to the still-running task.
+
+## Process Batches
+
+Stop at the first error with bounded concurrency:
+
+```ts
+const saved = ResultAsync.forEach(rows, saveRow, { concurrency: 8 });
+```
+
+Collect all independent errors instead:
+
+```ts
+const validated = ResultAsync.validateAll(rows, validateRow, { concurrency: 8 });
+```
+
+Use `{ discard: true }` with `forEach` when successful values are intentionally unused. Do not
+silently discard the returned `ResultAsync` itself.
+
+## Acquire And Release Resources
+
+```ts
+const imported = ResultAsync.withResource({
+  acquire: (signal) => openImportSession({ signal }),
+  use: (session, signal) => importRows(session, rows, { signal }),
+  release: (session) => session.close(),
+});
+```
+
+Release runs after every successful acquire path, but release failures are best-effort. If cleanup
+failure must affect the returned result, include that operation in `use` or otherwise model it as a
+typed Resultar step.
+
+## Recover Locally And Match At Boundaries
+
+Recover only where the fallback is part of application policy:
+
+```ts
+const profile = loadProfile(userId).catchTags({
+  ProfileNotFoundError: () => ok(defaultProfile),
+  ProfileDisabledError: () => ok(disabledProfile),
+});
+```
+
+Unhandled tags remain in the error channel. At the HTTP boundary, map the complete union:
+
+```ts
+const response = await createUser(input).matchTags((user) => ({ body: user, statusCode: 201 }), {
+  InvalidEmailError: (error) => ({ body: error.toJSON(), statusCode: 400 }),
+  UserAlreadyExistsError: (error) => ({ body: error.toJSON(), statusCode: 409 }),
+  SaveUserError: (error) => ({ body: error.toJSON(), statusCode: 500 }),
+});
+```
+
+Use `matchTagsPartial` only when a shared fallback is intentional. Keep HTTP status codes out of
+domain functions.
+
+## Add Observability
+
+```ts
+const observed = loadProfile(userId)
+  .tap((profile) => metrics.increment("profile.loaded", { userId: profile.userId }))
+  .tapError((error) => metrics.increment("profile.failed", { tag: error._tag }))
+  .log((profile, error) => logger.info({ error, profile }, "profile result"));
+```
+
+These `ResultAsync` callbacks are best-effort and cannot change the result.
+`ResultTask.tap` and `tapError` instead propagate returned task failures and turn callback
+throws or rejected Promises into defects. Use `andThen` or `orElse` when a
+logging, auditing, publishing, or cleanup failure must affect control flow.
+
+## Migrate Incrementally
+
+1. Identify the outermost throwing or rejecting dependency.
+2. Create concrete tagged errors for expected domain and infrastructure failures.
+3. Wrap throws and rejections at that edge with `tryResult` or `tryResultAsync`.
+4. Change callers to compose with `map`, `andThen`, `asyncAndThen`, and `mapErr`.
+5. Move transport conversion to one boundary matcher.
+6. Replace broad error types and unsafe casts with inferred unions.
+7. Enable `resultar-check` rules and remove narrow temporary exceptions.
+
+Avoid converting the whole codebase in one unsafe cast. A wrapper at an integration seam lets the
+typed error channel spread in reviewable steps.
+
+## Test Runtime And Type Behavior
+
+```ts
+import { equal, ok as assert } from "node:assert";
+import { describe, expectTypeOf, it } from "vite-plus/test";
+
+describe("validateEmail", () => {
+  it("returns a typed tagged error", () => {
+    const result = validateEmail("invalid");
+
+    assert(result.isErr());
+    equal(result.error._tag, "InvalidEmailError");
+    expectTypeOf(result.error).toEqualTypeOf<InvalidEmailError>();
+  });
+});
+```
+
+Test every expected error path, not just `Ok`. Add type tests for inferred unions, required tagged
+error props, narrowing, and exhaustive handlers. Use deterministic fake clocks, signals, and
+clients for retry, timeout, cancellation, race, concurrency, and cleanup tests.

package/dist/agent/references/review-checklist.md

@@ -0,0 +1,122 @@
+# Resultar Review And Migration Checklist
+
+Use this checklist for implementation reviews, migrations, documentation changes, and final
+validation. Report only issues supported by the installed Resultar version and repository evidence.
+
+## Source And Scope
+
+- Confirm the installed `resultar`, request adapter, and `resultar-check` versions.
+- Inspect local exports, types, package README files, and runnable examples before suggesting an API.
+- Separate issues introduced by the change from pre-existing workspace or dependency problems.
+- Preserve unrelated changes in a dirty worktree.
+
+## Failure Model
+
+- Expected failures return `Result`, `ResultAsync`, or `ResultTask`; programmer defects may still throw.
+- Application and integration boundaries prefer `StrictResult` / `StrictResultAsync`.
+- Tagged errors have stable names, useful metadata, inferred template props, and preserved causes.
+- Error unions remain concrete instead of widening early to `Error`, `unknown`, or a string.
+- `TaggedEnum` is limited to lightweight non-Error domain variants.
+- Sensitive metadata is redacted when serialization or logging could expose it.
+
+## Composition
+
+- `map` performs only infallible success transforms.
+- `mapErr` performs error-only transforms.
+- `filterOrElse` represents predicate validation.
+- `andThen` composes fallible steps; `asyncAndThen` is used for the sync-to-async bridge.
+- `orElse` recovers the whole error channel; `catchTag` / `catchTags` recover selected domain cases.
+- `safeTry` uses `yield*` for Resultar values and contains no raw `await` or broad `try/catch`.
+- Returned `Result`, `ResultAsync`, and `ResultTask` values are handled or explicitly discarded by supported policy.
+- Type assertions do not narrow away possible errors.
+
+## Async Boundaries And Policy
+
+- External throws and rejections are wrapped once, close to the uncontrolled dependency.
+- Error mappers accept `unknown` and produce concrete errors with `cause`.
+- Promise factories use `tryResultAsync`; already-created promises use `fromPromise`.
+- `fromSafePromise` is used only when rejection is impossible by contract.
+- Callback integrations provide cleanup and model `AbortError` where applicable.
+- Retry policy defines bounded attempts, delay/jitter, retryable errors, and cancellation.
+- Timeout scope is explicit: per attempt or across the complete retry budget.
+- `race`/`raceAll` are used for first settlement; `raceFirst` for first success.
+- Signals reach the underlying client so cancellation is cooperative rather than cosmetic.
+- Batch concurrency is bounded when workload size or dependency capacity requires it.
+- `validateAll` is used only when collecting all independent failures is desired.
+- `withResource` cleanup is treated as best-effort; important cleanup failures are modeled in the
+  result channel.
+
+## Boundaries And Recovery
+
+- Domain code does not contain transport status codes, framework responses, or CLI exit behavior.
+- `matchTags` handles the complete tagged error union at the boundary.
+- `matchTagsPartial` and `matchErrorPartial` have intentional fallbacks.
+- An `Error` handler exists when untagged errors can reach tagged matching.
+- Recovery is local only when the fallback is genuine domain/application policy.
+- `_unsafeUnwrap*` remains in tests; `runSync`, `runPromise`, and `unwrapOrThrow` appear only at
+  deliberate terminal boundaries.
+
+## HTTP Requests
+
+- `resultar-request` is used for a custom guard/decoder; TypeBox and Zod use their dedicated
+  adapters.
+- TypeBox success types derive from `Static<typeof schema>`.
+- Zod success types derive from `z.output<typeof schema>` so transforms are preserved.
+- Validated values are not widened back to `JsonRecord`, `Record<string, unknown>`, or `unknown`.
+- Error mapping distinguishes request, HTTP, invalid-JSON, and validation failures.
+- Numeric HTTP handlers take precedence over generic HTTP mapping where needed.
+- Retry uses a request factory and does not retry non-retryable `4xx`, JSON, or validation failures
+  without explicit policy.
+
+## Observability And Cleanup
+
+- `Result` / `ResultAsync` observation failures are best-effort; `ResultTask.tap` / `tapError`
+  can introduce typed failures or defects.
+- Resource cleanup and observation use the semantics of the concrete execution model.
+- Audits, publishes, or cleanup that must succeed use `andThen`, `orElse`, or another Resultar
+  boundary.
+- Logs expose stable tags and safe context without leaking redacted values.
+
+## Tests And Documentation
+
+- Runtime tests cover `Ok` and every expected `Err` branch.
+- Type tests cover inferred error unions, required tagged-error props, narrowing, and exhaustive
+  handlers.
+- Retry, timeout, cancellation, races, concurrency, and cleanup use deterministic fakes.
+- Tests use the repository's actual runner; this repository uses `vite-plus/test`.
+- Documentation examples compile or have a matching runnable example.
+- Core request, TypeBox, and Zod docs link to one another as alternatives/adapters.
+- API names, package links, and version claims match current source.
+- `Result.gen` returns a Result; `ResultTask.gen` returns a plain success value.
+- `runResult` rejection paths and deferred release errors are handled at the owning boundary.
+- An intentional-discard fix is not mistaken for executing or handling a lazy task.
+
+## Validation Order
+
+1. Run the `resultar-check` CLI as the authoritative project check.
+2. Confirm the `resultar-check lsp` stdio server emits Resultar diagnostics and quick fixes in the
+   editor.
+3. Use JSONL, SARIF, or JUnit output when a CI/review system needs structured diagnostics; keep the
+   native CLI as the authoritative check.
+4. Run formatting, build, tests, analysis, package smoke tests, and example workflows that apply.
+5. Report exactly which commands passed, failed, or were blocked.
+
+## Review Red Flags
+
+- `T | Error`, sentinel `null`, message strings, or thrown expected failures replace a Resultar
+  channel.
+- A broad `try/catch` surrounds an entire workflow instead of wrapping one external boundary.
+- Project-wide `try/catch` remains after the strict `noTryCatch` migration rule is enabled.
+- `map` returns another `Result` or `ResultAsync`.
+- `orElse` only replaces one error with another and should be `mapErr`.
+- A raw promise is awaited inside a Resultar workflow without a typed mapper.
+- `safeTry` contains raw `await`, plain `yield`, `try/catch`, or legacy `safeUnwrap()`.
+- A Resultar value is created and ignored.
+- `_unsafeUnwrap()` appears in production code.
+- An assertion makes an error union narrower than the implementation can guarantee.
+- Tagged errors override generated constructors, mismatch class names, or omit useful causes.
+- A schema adapter returns a broad JSON type or duplicates the schema with a drifting interface.
+- A promise rather than a request factory is configured for retry.
+- Hand-written retry, timeout, or race logic duplicates a built-in ResultAsync policy.
+- A lint-only pass is described as full Resultar validation.
+- Documentation recommends an API absent from the installed package.

package/dist/agent/references/services.md

@@ -0,0 +1,39 @@
+# Typed services and HTTP scopes
+
+Read the installed `resultar-di/README.md`, `resultar-hono/README.md` and `resultar-fastify/README.md` for the exact companion
+versions. The primary DI exports are `createModule`, `service`, and `resource`; class tokens and
+named factory overloads belong to `resultar-di/advanced`.
+
+- Register a service token with `.singleton(Token)`, `.scoped(Token)`, or `.transient(Token)`.
+  Dependency objects are inferred from tokens. Use `service(name, task)` for asynchronous
+  initialization; an async function passed as an ordinary factory is a defect in the contract.
+- Keep a server's serving-and-waiting task inside its owning `use` / ResultTask scope. Returning a
+  live resource from a completed scope returns a resource whose finalizer has already run.
+- Use `createHonoApp` for Hono routes. Ordinary `await` and `result.match` inside a route are valid;
+  generator-specific restrictions do not apply to a route body.
+- Use `createHonoServices(module).middleware(keys, { locals })` to add services to an existing Hono
+  router. Inline route middleware infers `c.var.services` while preserving `c.env` and native RPC
+  responses. Install one services middleware per request; consume/cancel responses before `close()`.
+- Use `createFastifyPlugin({ services, bindings, appBindings?, locals? })` for native Fastify routes.
+  `app.services` contains the selected startup singletons; `request.services` is available from
+  `preHandler` through response completion. Register authentication providing locals earlier.
+  Infer decorators with `InferAppServices` / `InferRequestServices`; augment Fastify in the application
+  or use its typed `getDecorator`. Annotate module/locals callback parameters with native Fastify
+  types when their inferred return values participate in selection checking.
+- Keep business logic in plain factories with async methods when sufficient. Register them using
+  `service(name, dependencies, factory)`. Map results explicitly through `matchTags` and native
+  response APIs; the framework adapters install no status table or `reply.result` helper.
+- `scope.useSingletons(keys, callback)` restricts selected services and callback tokens to the root
+  lifetime. Keep its callback active while serving; it is not a free-standing resolver. Factory
+  initialization stays lazy until selection; resource release remains explicit.
+- `scope.fetch`, `services.http`, and `createHonoApp` keep the request scope open until the Response
+  body ends, fails, or is canceled. Tests must consume or cancel response bodies before shutdown.
+- Stop and drain the server, finish/cancel persistent streams, then await application close.
+  Handle typed release errors; defects and composite causes may reject `close()`.
+- Supply authenticated request locals through the appropriate per-request integration. A singleton
+  cannot capture scoped services or request-local data. Extracting authentication remains the
+  framework adapter's responsibility.
+
+For a complete runnable pattern, see the workspace `examples/hono/` and `examples/resultar/`
+application lifecycle examples. The distributed guide includes the checked core recipe at
+`examples/workflow.mjs`; use the published declarations to adapt companion integrations.

package/dist/agent/versions.json

@@ -0,0 +1,10 @@
+{
+  "resultar-check": "3.2.0",
+  "resultar-di": "0.2.0",
+  "resultar-fastify": "0.2.0",
+  "resultar-hono": "0.2.0",
+  "resultar-request": "0.1.2",
+  "resultar-request-typebox": "0.1.2",
+  "resultar-request-zod": "0.1.2",
+  "resultar": "3.8.0"
+}