resultar 3.5.2 → 3.7.0

package/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2019 Giorgio Delgado
+Copyright (c) 2026 Inaiat Moraes
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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)
@@ -50,6 +54,7 @@ and optional TypeScript-backed diagnostics.
 - [HTTP Request Packages](#http-request-packages)
 - [API Decision Guide](#api-decision-guide)
 - [More Documentation](#more-documentation)
+- [Limitations](#limitations)
 
 ## Install
 
@@ -400,6 +405,233 @@ 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 required service
+tags and resource scope requirements. Run boundaries supply the root scope automatically and
+require an explicit environment for any remaining service tags.
+
+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, observe, or chain | `map`, `mapError`, `flatMap`, `andThen`, `tap`, `tapError`, `as`, `match` |
+| Recover typed failures | `catchAll` |
+| Write a linear lazy workflow | `gen` with `yield*` |
+| Declare and provide dependencies | `service`, `provideService`, `provideServices`, `provideServiceResolver` |
+| Own resources and await cleanup | `acquireRelease`, `scoped` |
+| Execute at the application boundary | `runExit`, `runResult`, `runPromise` |
+| Bridge to started promises | `fromResultAsync`, `toResultAsync`, `ResultAsync.fromTask` |
+
+```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)` | Preserves `Success`, typed `Fail`, `Die`, `Interrupt`, and `Sequential` causes |
+| `runResult(task)` | Returns a single typed failure as `Err`; rejects defects, interruption, and composite causes |
+| `runPromise(task)` | Returns `T`; rejects every failure for integration with Promise-only APIs |
+
+The error type of `runExit` and `runResult` includes deferred release failures from the root scope.
+Interruption rejects with `AbortError`. A composite cause rejects with `ResultTaskCauseError`, whose
+`cause` preserves the complete tree; use `runExit` to inspect it without rejection.
+
+```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 a single typed failure. Defects and interruption bypass recovery. Composite
+causes bypass recovery as `Die(ResultTaskCauseError)` with the original tree on the error's `cause`;
+this prevents removed error types from escaping as typed failures. The equivalent functional forms
+are `ResultTask.map`, `ResultTask.flatMap`, and `ResultTask.catchAll`.
+
+For promise adapters that do not need an error mapper, pass the lazy callback directly:
+
+```ts
+const response = ResultTask.tryPromise((signal) => fetch(url, { signal }))
+// ResultTask<Response, unknown>: synchronous throws and rejections remain typed failures.
+```
+
+The callback runs only when the task executes. Use `tryPromise({ try, catch })` when you need a
+specific error type; both forms receive the runtime signal and preserve interruption semantics.
+
+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)
+```
+
+Infrastructure such as a dependency-injection adapter can resolve service tags lazily with
+`provideServiceResolver(task, { Logger: () => loggerTask })`. Each required identifier has a
+typed lazy provider. Provider errors and external requirements remain in the resulting task type;
+resource-scope requirements also remain visible. All three providers (`provideService`,
+`provideServices`, `provideServiceResolver`) support data-first and curried (`.pipe`) forms.
+A provider whose value is incompatible with the required service contract is rejected at compile
+time, including through a reused curried provider; partial providers keep the remaining
+requirements until they are satisfied at the boundary.
+
+Adapters can use `ResultTask.makeScope()` to own resources across executions. Run tasks with
+`owner.use(task)` and execute `owner.close()` after consumers finish. Failed uses roll back their
+partial acquisitions. `ResultTask.memoize(task)` shares pending and successful executions and
+allows retry after failure; its first execution supplies the environment and resource scope.
+
+`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'))
+  }
+})
+```
+
+Generator `finally` retains its existing replacement policy if its cleanup fails. Use resource
+scopes below when both the body and cleanup failure must be preserved.
+
+Generators also accept `yield* result` for plain `Result` values: `Ok` unwraps its value and
+`Err` short-circuits into `E`.
+
+### Resource scopes and application lifecycle
+
+```ts
+const connection = ResultTask.acquireRelease({
+  acquire: ResultTask.tryPromise({
+    try: (signal) => connectDatabase(signal),
+    catch: (cause) => new ConnectionError({ cause }),
+  }),
+  release: (database, exit) => ResultTask.tryPromise({
+    try: () => database.close(exit),
+    catch: (cause) => new CloseError({ cause }),
+  }),
+})
+
+const program = ResultTask.scoped(ResultTask.gen(function* () {
+  const database = yield* connection
+  return yield* ResultTask.tryPromise({
+    try: (signal) => database.query('SELECT 1', signal),
+    catch: (cause) => new QueryError({ cause }),
+  })
+}))
+
+const exit = await ResultTask.runExit(program)
+```
+
+Every run owns a root scope. `scoped` closes a child scope before the next task continues. Successful
+acquisitions register finalizers in LIFO order; every finalizer is awaited once, even after a body
+failure, defect, or interruption. Failed acquisition does not register its release. Earlier resources
+are still released if a later acquisition fails. Each finalizer receives the same region exit,
+before release failures are appended. Services provided around acquisition remain available during
+release, including services used only by the release callback.
+
+`acquireRelease` tracks deferred errors with `ResultTaskScope<ReleaseError>` in `R`. `scoped` removes
+that requirement and adds its errors to `E`; run boundaries do the same for the root scope. Service
+provision and `catchAll` before scope closure cannot erase pending release failures. To recover a
+single release failure, put `catchAll` after `scoped`.
+
+If use succeeds but release fails, the failure is returned as `Err`. If both fail, `runExit` retains
+them as `Sequential(useCause, releaseCause)`; subsequent release failures are appended in order.
+Release callbacks that throw produce defects. Resources acquired during a finalizer belong to a
+private cleanup scope, which is closed before the next finalizer starts.
+
+Cancellation is cooperative: tasks check the signal before starting, and promise operations receive
+it. Rejection after abort is classified as interruption. The runtime waits for in-flight operations
+to settle so a resource acquired during cancellation can still be registered and released. Cleanup
+uses a fresh, non-aborted signal. An operation or finalizer that never settles can therefore keep
+the run pending; there is no preemptive cancellation, scheduler, or `Fiber` runtime in this slice.
+
+For application composition, keep ordinary factories and existing `StrictResultAsync` use cases.
+Use service tags only when a program needs requirements supplied at execution. Put the **whole server
+lifetime** inside the resource scope: acquire database, session, then HTTP; wait for shutdown; drain
+HTTP, close session, then close database. Returning a server from a completed scope would return
+already-released resources. TypeScript does not enforce resource reference lifetimes.
+
+See the runnable [application lifecycle example](../../examples/resultar/src/application-lifecycle.ts)
+and its [smoke test](../../examples/resultar/scripts/lifecycle-smoke.ts). Run `pnpm run example:resultar`
+from the workspace root. Its factory and resource contracts return `ResultTask` with database,
+session, and HTTP error types. Drivers expose Promises only inside `ResultTask.tryPromise` adapters,
+which receive the runtime signal without threading it through every application interface.
+Concrete adapters must clean up partial acquisitions before returning a
+failure and implement request draining, SSE termination, and suitable deadlines.
+
+`ResultAsync.withResource` keeps its existing best-effort release behavior. Existing `ResultAsync`
+instances have already started; wrapping one does not make it lazy or automatically cancelable.
+Use `ResultTask.fromResultAsync` to run a `ResultAsync` inside a task boundary: pass a
+`(signal) => ResultAsync` factory to defer creation until execution, or an existing instance to
+capture an already-started execution. Use `ResultTask.toResultAsync(task)` — or the
+`ResultAsync.fromTask(task)` alias — to start a requirement-free task immediately on the default
+runtime and consume it as `ResultAsync`.
+
 ## Production Async Policies
 
 Resultar models common resilience policy in the expected error channel. These helpers use lazy tasks
@@ -507,19 +739,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 +763,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 +871,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 +887,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 +904,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 +939,12 @@ 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`, `provideServiceResolver` |
+| Execute lazy work explicitly | `ResultTask.runExit`, `runResult`, `runPromise` |
+| Bridge to started promises | `ResultTask.fromResultAsync`, `toResultAsync`, `ResultAsync.fromTask` |
 | Handle a final boundary | `match`, `matchTags`, `matchTagsPartial` |
 | Combine independent results | `zip`, `combine`, `combineWithAllErrors` |
 | Try ordered fallback candidates | `firstSuccessOf` |
@@ -729,6 +965,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/docs/rfcs/rfc-0001-result-task-core.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)
@@ -740,6 +977,26 @@ reasons, disposable results, and compatibility APIs.
 
 Resultar is also published on [JSR as `@inaiat/resultar`](https://jsr.io/@inaiat/resultar).
 
+## Limitations
+
+ResultTask implements the RFC 0001 lazy core, generator with services, and resource scopes. The
+following are explicitly out of scope for this slice:
+
+- No `Stream`, STM, caching, clustering, RPC, or platform layer; this is not a full Effect API port.
+- No implicit global runtime: every `run*` call creates its own root scope and signal, and simple
+  tasks need no services or configuration.
+- No fibers or structured concurrency yet: `forkChild`/`join`/`interrupt`, task `race`/`timeout`,
+  and uniform `all`/`forEach` over the task runtime are still Phase 3. The `Cause` model covers
+  `Fail`, `Die`, `Interrupt`, and `Sequential`; `Parallel` is reserved for that future work. Use the
+  `ResultAsync` race, timeout, retry, and concurrency helpers in the meantime — they keep their own
+  eager, per-helper protocols.
+- No `Schedule`, schedule-based retry, or injectable clock yet (Phase 4).
+- No `Layer` system in the core: service graphs with their own lifecycle belong to the optional
+  `resultar-di` package, and the core does not depend on it.
+- `ResultAsync` stays eager and awaitable. `fromResultAsync` on an existing instance captures an
+  already-started execution; only the factory form defers creation.
+- Validated on Node.js 24+ only; other runtimes such as Bun are unvalidated.
+
 ## License
 
 MIT