resultar 3.5.2 → 3.6.0

package/README.md

@@ -8,10 +8,12 @@ Resultar makes expected failures visible in function signatures instead of hidin
 ```ts
 Result<T, E>
 ResultAsync<T, E>
+ResultTask<T, E, R>
 ```
 
 - `T` is the success value.
 - `E` is the expected failure.
+- `R` is the typed service environment still required by a `ResultTask`.
 - Callers must handle the result before they can use the value.
 
 Resultar stays focused on explicit values. It does not require a framework, dependency injection
@@ -22,12 +24,13 @@ container, scheduler, or application runtime.
 | You need | Resultar gives you |
 | --- | --- |
 | Expected failures in the type system | `Result<T, E>` and `ResultAsync<T, E>` |
+| Reusable lazy workflows | `ResultTask<T, E, R>` with explicit execution boundaries and typed services |
 | Production errors with useful metadata | Real `Error` subclasses from `createTaggedError` |
 | Composable sync and async workflows | `map`, `mapErr`, `andThen`, `asyncAndThen`, and `orElse` |
 | Linear code without scattered `try/catch` | `safeTry` with `yield*` short-circuiting |
 | Explicit production async policy | Typed timeout, retry, race, concurrency, and cleanup helpers |
 | Exhaustive application boundaries | `matchTags` for tagged error unions |
-| Guardrails for ignored results | The optional `resultar-check` CLI and language-server plugin |
+| Guardrails for ignored results | The optional native `resultar-check` CLI |
 
 Resultar began as a fork of `neverthrow`. The current API keeps the familiar explicit Result model
 and adds Resultar-specific tagged errors, production async helpers, exhaustive tagged boundaries,
@@ -41,8 +44,9 @@ and optional TypeScript-backed diagnostics.
 - [Compose Results](#compose-results)
 - [Tagged Errors](#tagged-errors)
 - [Async Work](#async-work)
+- [Lazy Workflows With ResultTask](#lazy-workflows-with-resulttask)
 - [Production Async Policies](#production-async-policies)
-- [Linear Workflows With safeTry](#linear-workflows-with-safetry)
+- [Linear Workflows With Result.gen](#linear-workflows-with-resultgen)
 - [Recover Inside A Workflow](#recover-inside-a-workflow)
 - [Handle Results At Boundaries](#handle-results-at-boundaries)
 - [Strict Results At Production Boundaries](#strict-results-at-production-boundaries)
@@ -400,6 +404,129 @@ Choose the wrapper that matches the external boundary:
 
 Prefer a factory with `tryResultAsync` when creating the promise can also throw synchronously.
 
+## Lazy Workflows With ResultTask
+
+`ResultTask<T, E, R>` is the lazy workflow primitive in Resultar. Creating one does not start the
+work; `runResult`, `runExit`, or `runPromise` executes it explicitly. `R` records the service tags
+still required by the workflow, so the execution boundary can require an explicit environment.
+
+Unlike `ResultAsync`, a `ResultTask` is a reusable description of work rather than an already-started
+operation. Mapping, chaining, recovery, service provision, and generator composition all remain lazy.
+
+| Need | API |
+| --- | --- |
+| Create an immediate success or failure | `succeed`, `fail`, `fromResult` |
+| Defer synchronous work | `sync`, `try` |
+| Defer promise-producing work | `tryPromise` |
+| Transform or chain | `map`, `flatMap`, `andThen` |
+| Recover typed failures | `catchAll` |
+| Write a linear lazy workflow | `gen` with `yield*` |
+| Declare and provide dependencies | `service`, `provideService`, `provideServices` |
+| Execute at the application boundary | `runExit`, `runResult`, `runPromise` |
+
+```ts
+import { ResultTask } from 'resultar'
+
+const loadUser = (id: string) =>
+  ResultTask.tryPromise({
+    try: (signal) => fetch(`/users/${id}`, { signal }).then((response) => response.json()),
+    catch: (cause) => new Error(`Could not load user: ${String(cause)}`),
+  })
+
+const task = loadUser('user_123')
+const result = await ResultTask.runResult(task)
+```
+
+`sync` treats a thrown value as an unexpected defect. Use `try` or `tryPromise` when the boundary is
+expected to throw or reject and should map that cause into `E`. `tryPromise` receives the execution
+`AbortSignal`, so callers can cancel cooperative work without starting it early.
+
+Choose the execution boundary based on how much information the application needs:
+
+| Boundary | Result |
+| --- | --- |
+| `runExit(task)` | `Exit<T, E>` preserving `Success`, typed `Fail`, and unexpected `Die` causes |
+| `runResult(task)` | `Result<T, E>`; a `Die` rejects instead of entering the typed error channel |
+| `runPromise(task)` | `T`; typed failures and defects reject for integration with Promise-only APIs |
+
+```ts
+const controller = new AbortController()
+const exit = await ResultTask.runExit(loadUser('user_123'), {
+  signal: controller.signal,
+})
+
+if (exit._tag === 'Failure' && exit.cause._tag === 'Die') {
+  console.error('Unexpected defect', exit.cause.defect)
+}
+```
+
+Instance methods and their static functional forms preserve laziness and infer combined error and
+environment types:
+
+```ts
+const userName = loadUser('user_123')
+  .map((user) => String(user.name))
+  .andThen((name) => ResultTask.succeed(name.trim()))
+  .catchAll((error) => ResultTask.succeed(`unavailable: ${error.message}`))
+```
+
+`catchAll` recovers only typed failures. Runtime defects remain defects and are visible through
+`runExit`. The equivalent functional forms are `ResultTask.map`, `ResultTask.flatMap`, and
+`ResultTask.catchAll`.
+
+Workflows can request typed services with `yield*` and receive them at the boundary. Pass the service
+type and its literal identifier so the named environment remains checked:
+
+```ts
+const Database = ResultTask.service<
+  { findUser: (id: string) => Promise<string> },
+  'Database'
+>('Database')
+
+const taskWithDatabase = ResultTask.gen(function* () {
+  const database = yield* Database
+  return yield* ResultTask.tryPromise({
+    try: () => database.findUser('user_123'),
+    catch: () => 'database-error' as const,
+  })
+})
+
+const resultWithDatabase = await ResultTask.runResult(taskWithDatabase, {
+  services: { Database: { findUser: async () => 'Ada' } },
+})
+```
+
+The environment requirement is part of the task type. A missing or misspelled `Database` property is
+a compile-time error at `runResult`, `runExit`, or `runPromise`. Dependencies can also be bound before
+the final boundary:
+
+```ts
+const database = { findUser: async () => 'Ada' }
+
+const readyWithOne = ResultTask.provideService(taskWithDatabase, Database, database)
+const readyWithAll = ResultTask.provideServices(taskWithDatabase, { Database: database })
+
+await ResultTask.runResult(readyWithOne)
+await ResultTask.runResult(readyWithAll)
+```
+
+`ResultTask.gen` composes tasks and services linearly. On short-circuit, generator `finally` blocks
+are closed and any yielded cleanup tasks or services are interpreted before execution completes:
+
+```ts
+const program = ResultTask.gen(function* () {
+  try {
+    return yield* loadUser('user_123')
+  } finally {
+    yield* ResultTask.sync(() => logger.info('load-user finished'))
+  }
+})
+```
+
+If cleanup itself fails or defects, that cleanup exit becomes the final exit. ResultTask 3.6 keeps
+execution deliberately small: it provides laziness, typed services, cooperative cancellation, and
+explicit exits, but does not yet include a scheduler, scopes, or `Fiber` runtime.
+
 ## Production Async Policies
 
 Resultar models common resilience policy in the expected error channel. These helpers use lazy tasks
@@ -507,19 +634,19 @@ See the full guides for
 [concurrency](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#async-concurrency-mapping),
 and [resource cleanup](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#resourceful-async-iterables).
 
-## Linear Workflows With `safeTry`
+## Linear Workflows With `Result.gen`
 
-Use `safeTry` when a longer chain reads better as linear code. `yield*` extracts the `Ok` value and
-short-circuits on the first `Err`.
+Use `Result.gen` when a longer chain reads better as linear code. `yield*` extracts the `Ok` value and
+short-circuits on the first `Err`. `safeTry` remains an exact compatibility alias.
 
 ```ts
-import { safeTry } from 'resultar'
+import { Result } from 'resultar'
 import type { ResultAsync } from 'resultar'
 
 const createAccountLinear = (
   input: string,
 ): ResultAsync<Account, CreateAccountAsyncError> =>
-  safeTry(async function* () {
+  Result.gen(async function* () {
     const email = yield* normalizeEmail(input)
     yield* ensureAccountIsAvailable(email)
 
@@ -531,7 +658,7 @@ The object form can map unexpected throws from inside the generator while leavin
 values unchanged:
 
 ```ts
-const account = safeTry({
+const account = Result.gen({
   async *try() {
     const email = yield* normalizeEmail(input)
     return persistAccount(email)
@@ -639,11 +766,10 @@ messages, causes, stack traces, and structured metadata.
 
 ## Prevent Ignored Results
 
-Result values are useful only when callers handle them. Install `resultar-check` with a project-local
-TypeScript 7+:
+Result values are useful only when callers handle them. Install the native `resultar-check` CLI:
 
 ```sh
-pnpm add -D resultar-check "typescript@>=7"
+pnpm add -D resultar-check
 ```
 
 Use the CLI as the authoritative local and CI check:
@@ -656,8 +782,8 @@ Use the CLI as the authoritative local and CI check:
 }
 ```
 
-The CLI runs TypeScript first and then Resultar diagnostics over the same `tsconfig.json`. Configure
-the TypeScript language-server plugin for equivalent feedback while editing:
+The CLI uses TypeScript-Go to run compiler and Resultar diagnostics over the same `tsconfig.json`.
+Configure its rules in the project file:
 
 ```json
 {
@@ -673,13 +799,13 @@ the TypeScript language-server plugin for equivalent feedback while editing:
 }
 ```
 
-After the CLI and language server are working, add the Oxlint, ESLint, or Deno Lint adapter only if
-you want optional low-latency syntax feedback. The adapters intentionally expose fewer rules because
-they do not have TypeScript type information.
+The `plugins` entry is configuration consumed by the native CLI and stdio LSP server; it does not
+install an editor extension. Run `resultar-check lsp` from an editor language-server configuration.
+A separate TypeScript installation is not required.
 
 See the
 [`resultar-check` guide](https://github.com/inaiat/resultar/blob/main/packages/check/README.md)
-for all rules, editor setup, ignore patterns, and lint adapter configuration.
+for all diagnostics, severities, modes, and ignore patterns.
 
 ## HTTP Request Packages
 
@@ -708,7 +834,11 @@ service needs.
 | Continue fallible work | `andThen`, `asyncAndThen` |
 | Recover from failure | `orElse`, `catchTag`, `catchTags` |
 | Wrap throwing or rejecting code | `tryResult`, `tryResultAsync`, `fromPromise` |
-| Write linear Result code | `safeTry` |
+| Write linear Result code | `Result.gen` (`safeTry` compatibility alias) |
+| Describe reusable lazy work | `ResultTask.succeed`, `sync`, `try`, `tryPromise` |
+| Compose or recover lazy work | `ResultTask.map`, `flatMap`, `andThen`, `catchAll`, `gen` |
+| Require or bind typed services | `ResultTask.service`, `provideService`, `provideServices` |
+| Execute lazy work explicitly | `ResultTask.runExit`, `runResult`, `runPromise` |
 | Handle a final boundary | `match`, `matchTags`, `matchTagsPartial` |
 | Combine independent results | `zip`, `combine`, `combineWithAllErrors` |
 | Try ordered fallback candidates | `firstSuccessOf` |
@@ -729,6 +859,7 @@ reasons, disposable results, and compatibility APIs.
 ## More Documentation
 
 - [Full Resultar guide](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md)
+- [ResultTask core RFC](https://github.com/inaiat/resultar/blob/main/packages/resultar/RESULT-TASK-CORE-RFC.md)
 - [Runnable core cookbook](https://github.com/inaiat/resultar/tree/main/examples/resultar)
 - [Catching and recovering errors](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#catching-and-recovering-errors)
 - [Safe Try](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#safe-try)

package/dist/index.d.ts

@@ -412,6 +412,10 @@ interface ResultStatic {
    * Runtime `instanceof Result` support for Ok and Err values.
    */
   [Symbol.hasInstance]: (value: unknown) => boolean;
+  /**
+   * Alias for `safeTry`, providing the same generator vocabulary as `ResultTask.gen`.
+   */
+  gen: typeof safeTry;
   /**
    * Runs synchronous work and captures thrown values into a Result.
    *
@@ -1527,6 +1531,128 @@ declare const isRedacted: (value: unknown) => value is Redacted<unknown>;
  */
 declare const revealRedacted: <T>(value: Redacted<T>) => T;
 //#endregion
+//#region src/result-task.d.ts
+/** A failure cause produced by a `ResultTask` execution. */
+type Cause<E> = {
+  readonly _tag: "Fail";
+  readonly error: E;
+} | {
+  readonly _tag: "Die";
+  readonly defect: unknown;
+};
+/** The complete outcome of a `ResultTask` execution. */
+type Exit<A, E> = {
+  readonly _tag: "Success";
+  readonly value: A;
+} | {
+  readonly _tag: "Failure";
+  readonly cause: Cause<E>;
+};
+/** A service that can be requested from a `ResultTask.gen` workflow. */
+interface ServiceTag<Identifier extends string, Service> {
+  readonly _tag: "ServiceTag";
+  readonly identifier: Identifier;
+  readonly key: symbol;
+  readonly [Symbol.iterator]: () => Generator<ResultTaskServiceYield<ServiceTag<Identifier, Service>>, Service, Service>;
+}
+/** Options for running a `ResultTask` with an optional signal and its required services. */
+type ResultTaskRunOptions<R = never> = {
+  readonly signal?: AbortSignal;
+} & ([R] extends [never] ? {
+  readonly services?: never;
+} : {
+  readonly services: ResultTaskServices<R>;
+});
+/** The object-shaped service environment required by a task. */
+type ResultTaskServices<R> = { readonly [Tag in Extract<R, AnyServiceTag> as Tag["identifier"]]: ServiceForTag<Tag>; };
+/** Options for creating a synchronous task with an explicit error boundary. */
+interface ResultTaskTryOptions<A, E> {
+  readonly try: () => A;
+  readonly catch: (cause: unknown) => E;
+}
+/** Options for creating a lazy promise-producing task with an explicit error boundary. */
+interface ResultTaskTryPromiseOptions<A, E> {
+  readonly try: (signal: AbortSignal) => PromiseLike<A>;
+  readonly catch: (cause: unknown) => E;
+}
+type AnyServiceTag = Pick<ServiceTag<string, unknown>, "_tag" | "identifier" | "key">;
+type ServiceForTag<Tag> = Tag extends ServiceTag<string, infer Service> ? Service : never;
+interface ResultTaskYield<A, E, R> {
+  readonly _tag: "ResultTask";
+  readonly task: ResultTask<A, E, R>;
+}
+interface ResultTaskServiceYield<Tag extends AnyServiceTag> {
+  readonly _tag: "Service";
+  readonly tag: Tag;
+}
+type GeneratorError<Yield> = Yield extends {
+  readonly _tag: "ResultTask";
+  readonly task: infer Task;
+} ? Task extends ResultTask<infer _A, infer E, infer _R> ? E : never : never;
+type GeneratorRequirements<Yield> = Yield extends {
+  readonly _tag: "ResultTask";
+  readonly task: infer Task;
+} ? Task extends ResultTask<infer _A, infer _E, infer R> ? R : never : Yield extends {
+  readonly _tag: "Service";
+  readonly tag: infer Tag;
+} ? Tag : never;
+type ResultTaskRunArguments<R> = [R] extends [never] ? [options?: ResultTaskRunOptions<R>] : [options: ResultTaskRunOptions<R>];
+/**
+ * A lazy, composable workflow that can succeed with `A` or fail with `E`.
+ *
+ * Constructing a `ResultTask` never runs its work. Use `runResult`, `runExit`, or `runPromise` at an
+ * explicit application boundary to execute it.
+ */
+declare class ResultTask<A, E = never, R = never> extends Pipeable {
+  private readonly execute;
+  private constructor();
+  private readonly typeWitness;
+  /** Creates a task that succeeds with `value` when it is executed. */
+  static succeed<A, E = never>(value: A): ResultTask<A, E>;
+  /** Creates a task that fails with `error` when it is executed. */
+  static fail<const E>(error: E): ResultTask<never, E>;
+  /** Lifts an already computed Result into a lazy task. */
+  static fromResult<A, E>(result: Result<A, E>): ResultTask<A, E>;
+  /** Creates a task for synchronous work. Thrown values are defects, not typed failures. */
+  static sync<A>(evaluate: () => A): ResultTask<A>;
+  /** Creates a task that maps synchronous throws into the typed error channel. */
+  static try<A, E>(options: ResultTaskTryOptions<A, E>): ResultTask<A, E>;
+  /** Creates a lazy task that maps synchronous throws and promise rejections into `E`. */
+  static tryPromise<A, E>(options: ResultTaskTryPromiseOptions<A, E>): ResultTask<A, E>;
+  /** Creates a service tag that can be requested with `yield*` inside `ResultTask.gen`. */
+  static service<Service, const Identifier extends string>(identifier: Identifier): ServiceTag<Identifier, Service>;
+  /** Builds a task from a generator and short-circuits on the first failed task. */
+  static gen<Yield, Return, Next>(body: () => Generator<Yield, Return, Next>): ResultTask<Return, GeneratorError<Yield>, GeneratorRequirements<Yield>>;
+  /** Maps the success value without executing the task. */
+  map<B>(f: (value: A) => B): ResultTask<B, E, R>;
+  /** Chains another task from the success value without executing either task immediately. */
+  flatMap<B, E2, R2>(f: (value: A) => ResultTask<B, E2, R2>): ResultTask<B, E | E2, R | R2>;
+  /** Alias for `flatMap`, matching the existing Resultar vocabulary. */
+  andThen<B, E2, R2>(f: (value: A) => ResultTask<B, E2, R2>): ResultTask<B, E | E2, R | R2>;
+  /** Recovers from a typed failure without recovering from a runtime defect. */
+  catchAll<B, E2, R2>(f: (error: E) => ResultTask<B, E2, R2>): ResultTask<A | B, E2, R | R2>;
+  /** Enables `yield* task` inside `ResultTask.gen` workflows. */
+  [Symbol.iterator](): Generator<ResultTaskYield<A, E, R>, A, Exit<A, E>>;
+  /** Provides one required service and removes it from the task's requirements. */
+  static provideService<A, E, R, Tag extends Extract<R, AnyServiceTag>>(task: ResultTask<A, E, R>, tag: Tag, service: ServiceForTag<Tag>): ResultTask<A, E, Exclude<R, Tag>>;
+  /** Provides all requirements using an object keyed by service identifier. */
+  static provideServices<A, E, R>(task: ResultTask<A, E, R>, services: ResultTaskServices<R>): ResultTask<A, E>;
+  /** Maps the success value using the canonical functional form. */
+  static map<A, E, R, B>(task: ResultTask<A, E, R>, f: (value: A) => B): ResultTask<B, E, R>;
+  /** Chains a task using the canonical functional form. */
+  static flatMap<A, E, R, B, E2, R2>(task: ResultTask<A, E, R>, f: (value: A) => ResultTask<B, E2, R2>): ResultTask<B, E | E2, R | R2>;
+  /** Recovers from a typed failure using the canonical functional form. */
+  static catchAll<A, E, R, B, E2, R2>(task: ResultTask<A, E, R>, f: (error: E) => ResultTask<B, E2, R2>): ResultTask<A | B, E2, R | R2>;
+  private static runExitInternal;
+  private static runResultInternal;
+  /** Runs a task and preserves success, typed failure, and runtime defects in an `Exit`. */
+  static runExit<A, E, R>(task: ResultTask<A, E, R>, ...args: ResultTaskRunArguments<R>): Promise<Exit<A, E>>;
+  /** Runs a task and returns a Result, rejecting only when a runtime defect occurs. */
+  static runResult<A, E, R>(task: ResultTask<A, E, R>, ...args: ResultTaskRunArguments<R>): Promise<Result<A, E>>;
+  /** Runs a task and returns the success value, rejecting on typed failures or defects. */
+  static runPromise<A, E, R>(task: ResultTask<A, E, R>, ...args: ResultTaskRunArguments<R>): Promise<A>;
+}
+//#endregion
 //#region src/tagged-error.d.ts
 type Alpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "_";
 type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
@@ -1691,4 +1817,4 @@ declare const matchError: <ErrorType extends Error, ReturnType>(error: ErrorType
  */
 declare const matchErrorPartial: <ErrorType extends Error, ReturnType>(error: ErrorType, handlers: PartialMatchHandlers<ErrorType, ReturnType>, fallback: (error: ErrorType) => ReturnType) => ReturnType;
 //#endregion
-export { AbortError, DisposableResult, DisposableResultAsync, type ErrResult, type OkResult, type Redacted, Result, ResultAsync, type ResultAsyncAbortSignal, type ResultAsyncCallbackCleanup, type ResultAsyncCallbackContext, type ResultAsyncConcurrency, type ResultAsyncFromCallbackOptions, type ResultAsyncRaceHandle, type ResultAsyncRaceTask, type ResultAsyncResourceAcquire, type ResultAsyncResourceEffect, type ResultAsyncResourceRelease, type ResultAsyncResourceReleaseContext, type ResultAsyncResourceUse, type ResultAsyncRetryContext, type ResultAsyncRetryOptions, type ResultAsyncRetryOrElseOptions, type ResultAsyncRetryTask, type ResultAsyncTimeoutOptions, type ResultAsyncWithResourceOptions, type ResultOperations, type SafeTryAsyncOptions, type SafeTryOptions, type StrictResult, type StrictResultAsync, type TaggedEnum, type TaggedEnumFactory, type TaggedErrorClass, type TaggedErrorInstance, type TaggedErrorOptions, type TryResultAsyncOptions, type TryResultOptions, createTaggedError, tryResult as default, tryResult as try, tryResult, err, errAsync, findCause, fromCallback, fromPromise, fromSafePromise, fromThrowable, fromThrowableAsync, isAbortError, isError, isRedacted, matchError, matchErrorPartial, ok, okAsync, redact, revealRedacted, runPromise, runSync, safeTry, taggedEnum, tryResultAsync as tryAsync, tryResultAsync, tryCatch, tryCatchAsync, unit, unitAsync };
+export { AbortError, type Cause, DisposableResult, DisposableResultAsync, type ErrResult, type Exit, type OkResult, type Redacted, Result, ResultAsync, type ResultAsyncAbortSignal, type ResultAsyncCallbackCleanup, type ResultAsyncCallbackContext, type ResultAsyncConcurrency, type ResultAsyncFromCallbackOptions, type ResultAsyncRaceHandle, type ResultAsyncRaceTask, type ResultAsyncResourceAcquire, type ResultAsyncResourceEffect, type ResultAsyncResourceRelease, type ResultAsyncResourceReleaseContext, type ResultAsyncResourceUse, type ResultAsyncRetryContext, type ResultAsyncRetryOptions, type ResultAsyncRetryOrElseOptions, type ResultAsyncRetryTask, type ResultAsyncTimeoutOptions, type ResultAsyncWithResourceOptions, type ResultOperations, ResultTask, type ResultTaskRunOptions, type ResultTaskServices, type ResultTaskTryOptions, type ResultTaskTryPromiseOptions, type SafeTryAsyncOptions, type SafeTryOptions, type ServiceTag, type StrictResult, type StrictResultAsync, type TaggedEnum, type TaggedEnumFactory, type TaggedErrorClass, type TaggedErrorInstance, type TaggedErrorOptions, type TryResultAsyncOptions, type TryResultOptions, createTaggedError, tryResult as default, tryResult as try, tryResult, err, errAsync, findCause, fromCallback, fromPromise, fromSafePromise, fromThrowable, fromThrowableAsync, isAbortError, isError, isRedacted, matchError, matchErrorPartial, ok, okAsync, redact, revealRedacted, runPromise, runSync, safeTry, taggedEnum, tryResultAsync as tryAsync, tryResultAsync, tryCatch, tryCatchAsync, unit, unitAsync };

package/dist/index.js

@@ -192,6 +192,10 @@ var ResultNamespace = class {
 		return value instanceof Ok || value instanceof Err;
 	}
 	/**
+	* Alias for the top-level `safeTry` generator workflow.
+	*/
+	static gen = safeTry;
+	/**
 	* Creates a `Result` by running a function that might throw.
 	* If the function throws, the error will be caught and returned as an `Err`.
 	* If the function succeeds, the value will be wrapped in an `Ok`.
@@ -2023,4 +2027,282 @@ const runPromise = (result) => result.unwrapOrThrow();
 /** Compatibility alias. Prefer `tryResultAsync` in new code. */
 const tryCatchAsync = tryResultAsync;
 //#endregion
-export { AbortError, DisposableResult, DisposableResultAsync, Result, ResultAsync, createTaggedError, tryResult as default, tryResult as try, tryResult, err, errAsync, findCause, fromCallback, fromPromise, fromSafePromise, fromThrowable, fromThrowableAsync, isAbortError, isError, isRedacted, matchError, matchErrorPartial, ok, okAsync, redact, revealRedacted, runPromise, runSync, safeTry, taggedEnum, tryResultAsync as tryAsync, tryResultAsync, tryCatch, tryCatchAsync, unit, unitAsync };
+//#region src/result-task.ts
+const success = (value) => ({
+	_tag: "Success",
+	value
+});
+const failure = (cause) => ({
+	_tag: "Failure",
+	cause
+});
+const failed = (error) => failure({
+	_tag: "Fail",
+	error
+});
+const died = (defect) => failure({
+	_tag: "Die",
+	defect
+});
+const throwDefect = (defect) => {
+	throw defect;
+};
+const isRecord = (value) => typeof value === "object" && value !== null;
+const createMissingServiceError = (identifier) => {
+	const error = /* @__PURE__ */ new Error(`Missing ResultTask service: ${identifier}`);
+	error.name = "MissingServiceError";
+	return error;
+};
+const isResultTaskYield = (value) => isRecord(value) && value["_tag"] === "ResultTask" && value["task"] instanceof ResultTask;
+const isServiceYield = (value) => isRecord(value) && value["_tag"] === "Service" && value["tag"] instanceof ServiceTagValue;
+const lookupService = (tag, context) => {
+	if (context.services.has(tag.key)) return context.services.get(tag.key);
+	return context.namedServices.get(tag.identifier);
+};
+const executeTaskSafely = async (task, executeTask) => {
+	try {
+		return await executeTask(task);
+	} catch (error) {
+		return { error };
+	}
+};
+const closeGenerator = async (iterator, exit, runtime) => {
+	try {
+		let step = iterator.return(void 0);
+		let finalExit = exit;
+		while (step.done === false) if (isResultTaskYield(step.value)) {
+			const outcome = await executeTaskSafely(step.value.task, runtime.executeTask);
+			if ("error" in outcome) {
+				finalExit = died(outcome.error);
+				step = iterator.return(void 0);
+			} else if (outcome._tag === "Failure") {
+				finalExit = outcome;
+				step = iterator.return(void 0);
+			} else step = iterator.next(outcome);
+		} else if (isServiceYield(step.value)) {
+			const service = lookupService(step.value.tag, runtime.context);
+			if (service === void 0) {
+				finalExit = died(createMissingServiceError(step.value.tag.identifier));
+				step = iterator.return(void 0);
+			} else step = iterator.next(service);
+		} else {
+			finalExit = died(/* @__PURE__ */ new TypeError("ResultTask.gen yielded an unsupported value"));
+			step = iterator.return(void 0);
+		}
+		return finalExit;
+	} catch (error) {
+		return died(error);
+	}
+};
+const withServices = (context, services) => ({
+	namedServices: context.namedServices,
+	services,
+	signal: context.signal
+});
+const withNamedServices = (context, namedServices) => ({
+	namedServices,
+	services: context.services,
+	signal: context.signal
+});
+var ServiceTagValue = class {
+	_tag = "ServiceTag";
+	identifier;
+	key;
+	constructor(identifier) {
+		this.identifier = identifier;
+		this.key = Symbol(identifier);
+	}
+	*[Symbol.iterator]() {
+		return yield {
+			_tag: "Service",
+			tag: this
+		};
+	}
+};
+/**
+* A lazy, composable workflow that can succeed with `A` or fail with `E`.
+*
+* Constructing a `ResultTask` never runs its work. Use `runResult`, `runExit`, or `runPromise` at an
+* explicit application boundary to execute it.
+*/
+var ResultTask = class ResultTask extends Pipeable {
+	execute;
+	constructor(execute) {
+		super();
+		this.execute = execute;
+	}
+	/** Creates a task that succeeds with `value` when it is executed. */
+	static succeed(value) {
+		return new ResultTask(() => Promise.resolve(success(value)));
+	}
+	/** Creates a task that fails with `error` when it is executed. */
+	static fail(error) {
+		return new ResultTask(() => Promise.resolve(failed(error)));
+	}
+	/** Lifts an already computed Result into a lazy task. */
+	static fromResult(result) {
+		return new ResultTask(() => Promise.resolve(result.isOk() ? success(result.value) : failed(result.error)));
+	}
+	/** Creates a task for synchronous work. Thrown values are defects, not typed failures. */
+	static sync(evaluate) {
+		return new ResultTask(() => Promise.resolve(success(evaluate())));
+	}
+	/** Creates a task that maps synchronous throws into the typed error channel. */
+	static try(options) {
+		return new ResultTask(() => {
+			try {
+				return Promise.resolve(success(options.try()));
+			} catch (error) {
+				return Promise.resolve(failed(options.catch(error)));
+			}
+		});
+	}
+	/** Creates a lazy task that maps synchronous throws and promise rejections into `E`. */
+	static tryPromise(options) {
+		return new ResultTask(async (context) => {
+			try {
+				return success(await options.try(context.signal));
+			} catch (error) {
+				return failed(options.catch(error));
+			}
+		});
+	}
+	/** Creates a service tag that can be requested with `yield*` inside `ResultTask.gen`. */
+	static service(identifier) {
+		return new ServiceTagValue(identifier);
+	}
+	/** Builds a task from a generator and short-circuits on the first failed task. */
+	static gen(body) {
+		return new ResultTask(async (context) => {
+			try {
+				const iterator = body();
+				const executeTask = (task) => task.execute(context);
+				let step = iterator.next();
+				while (step.done === false) if (isResultTaskYield(step.value)) {
+					const outcome = await executeTaskSafely(step.value.task, executeTask);
+					if ("error" in outcome) return await closeGenerator(iterator, died(outcome.error), {
+						context,
+						executeTask
+					});
+					if (outcome._tag === "Failure") return await closeGenerator(iterator, outcome, {
+						context,
+						executeTask
+					});
+					step = iterator.next(outcome);
+				} else if (isServiceYield(step.value)) {
+					const service = lookupService(step.value.tag, context);
+					if (service === void 0) return await closeGenerator(iterator, died(createMissingServiceError(step.value.tag.identifier)), {
+						context,
+						executeTask
+					});
+					step = iterator.next(service);
+				} else return await closeGenerator(iterator, died(/* @__PURE__ */ new TypeError("ResultTask.gen yielded an unsupported value")), {
+					context,
+					executeTask
+				});
+				return success(step.value);
+			} catch (error) {
+				return died(error);
+			}
+		});
+	}
+	/** Maps the success value without executing the task. */
+	map(f) {
+		return new ResultTask(async (context) => {
+			const exit = await this.execute(context);
+			if (exit._tag === "Failure") return exit;
+			return success(f(exit.value));
+		});
+	}
+	/** Chains another task from the success value without executing either task immediately. */
+	flatMap(f) {
+		return new ResultTask(async (context) => {
+			const exit = await this.execute(context);
+			if (exit._tag === "Failure") return exit;
+			return f(exit.value).execute(context);
+		});
+	}
+	/** Alias for `flatMap`, matching the existing Resultar vocabulary. */
+	andThen(f) {
+		return this.flatMap(f);
+	}
+	/** Recovers from a typed failure without recovering from a runtime defect. */
+	catchAll(f) {
+		return new ResultTask(async (context) => {
+			const exit = await this.execute(context);
+			if (exit._tag === "Success") return exit;
+			if (exit.cause._tag === "Die") return exit;
+			return f(exit.cause.error).execute(context);
+		});
+	}
+	/** Enables `yield* task` inside `ResultTask.gen` workflows. */
+	*[Symbol.iterator]() {
+		const exit = yield {
+			_tag: "ResultTask",
+			task: this
+		};
+		if (exit._tag === "Success") return exit.value;
+		return throwDefect(/* @__PURE__ */ new Error("ResultTask generator received a failed task result"));
+	}
+	/** Provides one required service and removes it from the task's requirements. */
+	static provideService(task, tag, service) {
+		return new ResultTask(async (context) => {
+			const services = new Map([...context.services, [tag.key, service]]);
+			return task.execute(withServices(context, services));
+		});
+	}
+	/** Provides all requirements using an object keyed by service identifier. */
+	static provideServices(task, services) {
+		return new ResultTask(async (context) => {
+			const namedServices = new Map(context.namedServices);
+			for (const [identifier, service] of Object.entries(services)) namedServices.set(identifier, service);
+			return task.execute(withNamedServices(context, namedServices));
+		});
+	}
+	/** Maps the success value using the canonical functional form. */
+	static map(task, f) {
+		return task.map(f);
+	}
+	/** Chains a task using the canonical functional form. */
+	static flatMap(task, f) {
+		return task.flatMap(f);
+	}
+	/** Recovers from a typed failure using the canonical functional form. */
+	static catchAll(task, f) {
+		return task.catchAll(f);
+	}
+	static async runExitInternal(task, options) {
+		const signal = options?.signal ?? new AbortController().signal;
+		const suppliedServices = options !== void 0 && "services" in options ? options.services : void 0;
+		const context = {
+			namedServices: new Map(Object.entries(suppliedServices ?? {})),
+			services: /* @__PURE__ */ new Map(),
+			signal
+		};
+		try {
+			return await task.execute(context);
+		} catch (error) {
+			return died(error);
+		}
+	}
+	static async runResultInternal(task, options) {
+		const exit = await ResultTask.runExitInternal(task, options);
+		if (exit._tag === "Success") return ok(exit.value);
+		if (exit.cause._tag === "Fail") return err(exit.cause.error);
+		return throwDefect(exit.cause.defect);
+	}
+	/** Runs a task and preserves success, typed failure, and runtime defects in an `Exit`. */
+	static runExit(task, ...args) {
+		return ResultTask.runExitInternal(task, args[0]);
+	}
+	/** Runs a task and returns a Result, rejecting only when a runtime defect occurs. */
+	static runResult(task, ...args) {
+		return ResultTask.runResultInternal(task, args[0]);
+	}
+	/** Runs a task and returns the success value, rejecting on typed failures or defects. */
+	static async runPromise(task, ...args) {
+		return (await ResultTask.runResultInternal(task, args[0])).unwrapOrThrow();
+	}
+};
+//#endregion
+export { AbortError, DisposableResult, DisposableResultAsync, Result, ResultAsync, ResultTask, createTaggedError, tryResult as default, tryResult as try, tryResult, err, errAsync, findCause, fromCallback, fromPromise, fromSafePromise, fromThrowable, fromThrowableAsync, isAbortError, isError, isRedacted, matchError, matchErrorPartial, ok, okAsync, redact, revealRedacted, runPromise, runSync, safeTry, taggedEnum, tryResultAsync as tryAsync, tryResultAsync, tryCatch, tryCatchAsync, unit, unitAsync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resultar",
-  "version": "3.5.2",
+  "version": "3.6.0",
   "description": "Result pattern for TypeScript",
   "keywords": [
     "error-handling",
@@ -43,14 +43,14 @@
   "devDependencies": {
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
-    "@types/node": "26.2.0",
-    "@vitest/coverage-v8": "4.1.10",
-    "@vitest/ui": "4.1.10",
-    "fallow": "3.17.0",
-    "tsx": "4.23.12",
+    "@types/node": "26.4.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/ui": "4.1.11",
+    "fallow": "3.20.0",
+    "tsx": "4.23.13",
     "typescript": "7.0.2",
-    "vite-plus": "0.2.9",
-    "vitest": "4.1.10"
+    "vite-plus": "0.3.0",
+    "vitest": "4.1.11"
   },
   "peerDependencies": {
     "typescript": ">=7.0.0"