effect 4.0.0-beta.99 → 4.0.0-rc.109

package/src/unstable/workers/WorkerError.ts

@@ -31,10 +31,10 @@ export const isWorkerError = (u: unknown): u is WorkerError => hasProperty(u, Ty
 /**
  * Worker error reason for failures while spawning or setting up a worker.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
-export class WorkerSpawnError extends Schema.ErrorClass<WorkerSpawnError>(
+export class WorkerSpawnError extends Schema.Error<WorkerSpawnError>(
   "effect/workers/WorkerError/WorkerSpawnError"
 )({
   _tag: Schema.tag("WorkerSpawnError"),
@@ -45,10 +45,10 @@ export class WorkerSpawnError extends Schema.ErrorClass<WorkerSpawnError>(
 /**
  * Worker error reason for failures while sending a message to a worker.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
-export class WorkerSendError extends Schema.ErrorClass<WorkerSendError>(
+export class WorkerSendError extends Schema.Error<WorkerSendError>(
   "effect/workers/WorkerError/WorkerSendError"
 )({
   _tag: Schema.tag("WorkerSendError"),
@@ -60,10 +60,10 @@ export class WorkerSendError extends Schema.ErrorClass<WorkerSendError>(
  * Worker error reason for failures while receiving or handling a message from a
  * worker.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
-export class WorkerReceiveError extends Schema.ErrorClass<WorkerReceiveError>(
+export class WorkerReceiveError extends Schema.Error<WorkerReceiveError>(
   "effect/workers/WorkerError/WorkerReceiveError"
 )({
   _tag: Schema.tag("WorkerReceiveError"),
@@ -74,10 +74,10 @@ export class WorkerReceiveError extends Schema.ErrorClass<WorkerReceiveError>(
 /**
  * Worker error reason for an unclassified worker failure.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
-export class WorkerUnknownError extends Schema.ErrorClass<WorkerUnknownError>(
+export class WorkerUnknownError extends Schema.Error<WorkerUnknownError>(
   "effect/workers/WorkerError/WorkerUnknownError"
 )({
   _tag: Schema.tag("WorkerUnknownError"),
@@ -88,7 +88,7 @@ export class WorkerUnknownError extends Schema.ErrorClass<WorkerUnknownError>(
 /**
  * Union of the specific failure reasons that can be wrapped by a `WorkerError`.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export type WorkerErrorReason =
@@ -100,7 +100,7 @@ export type WorkerErrorReason =
 /**
  * Schema for decoding and encoding all supported worker error reason variants.
  *
- * @category models
+ * @category schemas
  * @since 4.0.0
  */
 export const WorkerErrorReason: Schema.Union<[
@@ -119,10 +119,10 @@ export const WorkerErrorReason: Schema.Union<[
  * Error raised by worker APIs, wrapping a specific `WorkerErrorReason` and
  * exposing its message and cause.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
-export class WorkerError extends Schema.ErrorClass<WorkerError>(TypeId)({
+export class WorkerError extends Schema.Error<WorkerError>(TypeId)({
   _tag: Schema.tag("WorkerError"),
   reason: WorkerErrorReason
 }) {

package/src/unstable/workers/WorkerRunner.ts

@@ -49,7 +49,7 @@ export type PlatformMessage<I> = readonly [request: 0, I] | readonly [close: 1]
 /**
  * Context service that starts a platform-specific `WorkerRunner`.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export class WorkerRunnerPlatform extends Context.Service<WorkerRunnerPlatform, {

package/src/unstable/workflow/Activity.ts

@@ -237,7 +237,7 @@ export const retry: {
  * Context reference containing the current activity retry attempt, defaulting
  * to `1`.
  *
- * @category Attempts
+ * @category services
  * @since 4.0.0
  */
 export const CurrentAttempt = Context.Reference<number>(
@@ -249,7 +249,7 @@ export const CurrentAttempt = Context.Reference<number>(
  * Computes a deterministic activity idempotency key from the current workflow
  * execution ID, the supplied name, and optionally the current attempt.
  *
- * @category Idempotency
+ * @category idempotency
  * @since 4.0.0
  */
 export const idempotencyKey: (

package/src/unstable/workflow/DurableClock.ts

@@ -64,7 +64,7 @@ const InstanceTag = Context.Service<
  * Waits inside a workflow, using an in-memory activity for durations at or
  * below the threshold and scheduling a durable clock for longer durations.
  *
- * @category sleeping
+ * @category delays & timeouts
  * @since 4.0.0
  */
 export const sleep: (

package/src/unstable/workflow/DurableDeferred.ts

@@ -144,6 +144,8 @@ const await_: <Success extends Schema.Constraint, Error extends Schema.Constrain
 >(self: DurableDeferred<Success, Error>) {
   const engine = yield* EngineTag
   const instance = yield* InstanceTag
+  // Register before the read so any later completion can preempt the run.
+  instance.awaitedDeferreds.add(self.name)
   const exit = yield* Workflow.wrapActivityResult(
     engine.deferredResult(self),
     Option.isNone
@@ -237,9 +239,12 @@ export const into: {
                 exit.cause.reasons,
                 Filter.fromPredicate(Cause.isInterruptReason)
               )
-              const hasInterruptsOnly = interrupts.length === exit.cause.reasons.length
-              if (hasInterruptsOnly && instance.suspended) {
-                parentInstance.suspended = true
+              if (interrupts.length === exit.cause.reasons.length) {
+                // An interrupt-only exit is never a result: the effect was
+                // suspended, preempted or interrupted, so record nothing.
+                if (instance.suspended) {
+                  parentInstance.suspended = true
+                }
                 return
               } else if (interrupts.length > 0) {
                 exit = Exit.failCause(Cause.fromReasons(reasons))
@@ -321,7 +326,7 @@ export type TokenTypeId = typeof TokenTypeId
  * Branded string token identifying a durable deferred for a workflow
  * execution.
  *
- * @category token
+ * @category models
  * @since 4.0.0
  */
 export type Token = Brand.Branded<string, TokenTypeId>
@@ -329,7 +334,7 @@ export type Token = Brand.Branded<string, TokenTypeId>
 /**
  * Schema for branded durable deferred tokens.
  *
- * @category token
+ * @category schemas
  * @since 4.0.0
  */
 export const Token: Schema.brand<Schema.String, TokenTypeId> = Schema.String.pipe(Schema.brand(TokenTypeId))
@@ -338,7 +343,7 @@ export const Token: Schema.brand<Schema.String, TokenTypeId> = Schema.String.pip
  * Schema for a decoded durable deferred token containing the workflow
  * name, execution ID, and deferred name.
  *
- * @category token
+ * @category schemas
  * @since 4.0.0
  */
 export class TokenParsed extends Schema.Class<TokenParsed>(
@@ -413,7 +418,7 @@ export class TokenParsed extends Schema.Class<TokenParsed>(
  * Creates a token for a durable deferred using the current workflow instance's
  * workflow name and execution ID.
  *
- * @category token
+ * @category constructors
  * @since 4.0.0
  */
 export const token: <Success extends Schema.Constraint, Error extends Schema.Constraint>(
@@ -431,7 +436,7 @@ export const token: <Success extends Schema.Constraint, Error extends Schema.Con
  * Creates a durable deferred token from an explicit workflow, execution ID,
  * and deferred name.
  *
- * @category token
+ * @category constructors
  * @since 4.0.0
  */
 export const tokenFromExecutionId: {
@@ -439,7 +444,7 @@ export const tokenFromExecutionId: {
    * Creates a durable deferred token from an explicit workflow, execution ID,
    * and deferred name.
    *
-   * @category token
+   * @category constructors
    * @since 4.0.0
    */
   (
@@ -454,7 +459,7 @@ export const tokenFromExecutionId: {
    * Creates a durable deferred token from an explicit workflow, execution ID,
    * and deferred name.
    *
-   * @category token
+   * @category constructors
    * @since 4.0.0
    */
   <Success extends Schema.Constraint, Error extends Schema.Constraint>(
@@ -481,7 +486,7 @@ export const tokenFromExecutionId: {
  * Creates a durable deferred token by deriving the workflow execution ID from
  * the supplied workflow payload.
  *
- * @category token
+ * @category constructors
  * @since 4.0.0
  */
 export const tokenFromPayload: {
@@ -489,7 +494,7 @@ export const tokenFromPayload: {
    * Creates a durable deferred token by deriving the workflow execution ID from
    * the supplied workflow payload.
    *
-   * @category token
+   * @category constructors
    * @since 4.0.0
    */
   <W extends Workflow.Any>(
@@ -504,7 +509,7 @@ export const tokenFromPayload: {
    * Creates a durable deferred token by deriving the workflow execution ID from
    * the supplied workflow payload.
    *
-   * @category token
+   * @category constructors
    * @since 4.0.0
    */
   <

package/src/unstable/workflow/DurableQueue.ts

@@ -61,8 +61,8 @@ export interface DurableQueue<
  *
  * **Example** (Defining a durable queue with workers)
  *
- * ```ts
- * import { Effect, Schema } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Layer, Schema } from "effect"
  * import { DurableQueue, Workflow } from "effect/unstable/workflow"
  *
  * // Define a DurableQueue that can be used to derive workers and offer items for
@@ -88,25 +88,27 @@ export interface DurableQueue<
  *
  * const MyWorkflowLayer = MyWorkflow.toLayer(
  *   Effect.fnUntraced(function*() {
- *     // Add an item to the DurableQueue defined above.
- *     //
- *     // When the worker has finished processing the item, the workflow will
- *     // resume.
- *     //
+ *     // The workflow suspends until a worker completes this queue item.
  *     yield* DurableQueue.process(ApiQueue, { id: "api-call-1" })
- *
- *     yield* Effect.log("Workflow succeeded!")
+ *     return "Workflow succeeded!"
  *   })
  * )
  *
- * // Define a worker layer that can process items from the DurableQueue.
- * const ApiWorker = DurableQueue.worker(
- *   ApiQueue,
- *   Effect.fnUntraced(function*({ id }) {
- *     yield* Effect.log(`Worker processing API call with id: ${id}`)
- *   }),
- *   { concurrency: 5 } // Process up to 5 items concurrently
- * )
+ * const processed: Array<string> = []
+ * const processApiCall = ({ id }: { readonly id: string }) => Effect.sync(() => processed.push(id))
+ *
+ * // Construct the worker layer without starting background workers in this example.
+ * const ApiWorker = DurableQueue.worker(ApiQueue, processApiCall, {
+ *   concurrency: 5
+ * })
+ *
+ * const program = Effect.gen(function*() {
+ *   // Exercise the finite handler directly instead of running a queue worker.
+ *   yield* processApiCall({ id: "api-call-1" })
+ *   return [Layer.isLayer(MyWorkflowLayer), Layer.isLayer(ApiWorker), processed] as const
+ * })
+ *
+ * await Effect.runPromise(program) // => [true, true, ["api-call-1"]]
  * ```
  *
  * @category constructors
@@ -170,7 +172,7 @@ const getQueueSchema = <Payload extends Schema.Top>(
 /**
  * Adds an item to the queue and wait for a worker to process it.
  *
- * @category Processing
+ * @category running
  * @since 4.0.0
  */
 export const process: <
@@ -247,7 +249,7 @@ const defaultRetrySchedule = Schedule.min([
 /**
  * Create a worker effect that processes items from the durable queue.
  *
- * @category Worker
+ * @category workers
  * @since 4.0.0
  */
 export const makeWorker: <
@@ -334,7 +336,7 @@ export const makeWorker: <
 /**
  * Create a layer that runs workers for the durable queue.
  *
- * @category Worker
+ * @category workers
  * @since 4.0.0
  */
 export const worker: <

package/src/unstable/workflow/Workflow.ts

@@ -20,7 +20,7 @@ import * as Fiber from "../../Fiber.ts"
 import * as Filter from "../../Filter.ts"
 import { constFalse, constTrue, dual, identity } from "../../Function.ts"
 import * as Layer from "../../Layer.ts"
-import * as Option from "../../Option.ts"
+import type * as Option from "../../Option.ts"
 import * as Predicate from "../../Predicate.ts"
 import type * as Schedule from "../../Schedule.ts"
 import * as Schema from "../../Schema.ts"
@@ -200,7 +200,7 @@ export interface AnyStructSchema extends Schema.Top {
  * Type-level marker for services associated with a specific workflow
  * execution tag.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export interface Execution<Tag extends string> {
@@ -252,7 +252,7 @@ export interface AnyWithProps extends Any {
 /**
  * Extracts the payload schema from a `Workflow`.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type PayloadSchema<W> = W extends Workflow<
@@ -267,7 +267,7 @@ export type PayloadSchema<W> = W extends Workflow<
  * Computes the schema services required by clients that execute or poll
  * workflows.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type RequirementsClient<Workflows extends Any> = Workflows extends Workflow<
@@ -285,7 +285,7 @@ export type RequirementsClient<Workflows extends Any> = Workflows extends Workfl
  * Computes the schema services required by handlers that decode workflow
  * payloads and encode workflow results.
  *
- * @category models
+ * @category utility types
  * @since 4.0.0
  */
 export type RequirementsHandler<Workflows extends Any> = Workflows extends Workflow<
@@ -465,7 +465,7 @@ const ResultTypeId = "~effect/workflow/Workflow/Result"
 /**
  * Returns `true` when a value is a workflow `Result`.
  *
- * @category results
+ * @category guards
  * @since 4.0.0
  */
 export const isResult = <A = unknown, E = unknown>(
@@ -476,7 +476,7 @@ export const isResult = <A = unknown, E = unknown>(
  * Result of a workflow execution, either a completed exit or a suspended
  * workflow state.
  *
- * @category results
+ * @category models
  * @since 4.0.0
  */
 export type Result<A, E> = Complete<A, E> | Suspended
@@ -484,7 +484,7 @@ export type Result<A, E> = Complete<A, E> | Suspended
 /**
  * Encoded representation of a workflow `Result`.
  *
- * @category results
+ * @category models
  * @since 4.0.0
  */
 export type ResultEncoded<A, E> =
@@ -495,7 +495,7 @@ export type ResultEncoded<A, E> =
  * Encoded representation of a completed workflow result containing an encoded
  * `Exit`.
  *
- * @category results
+ * @category models
  * @since 4.0.0
  */
 export interface CompleteEncoded<A, E> {
@@ -527,7 +527,7 @@ export interface CompleteSchema<
 /**
  * Represents a completed workflow execution with its success or failure `Exit`.
  *
- * @category results
+ * @category models
  * @since 4.0.0
  */
 export class Complete<A, E> extends Data.TaggedClass("Complete")<{
@@ -557,16 +557,13 @@ export class Complete<A, E> extends Data.TaggedClass("Complete")<{
       [Schema.Exit(options.success, options.error, Schema.Defect())],
       ([exit]) => (input, ast, options) => {
         if (!(isResult(input) && input._tag === "Complete")) {
-          return Effect.fail(new SchemaIssue.InvalidType(ast, Option.some(input)))
+          return Effect.fail(new SchemaIssue.InvalidType(ast, input, options))
         }
         return Effect.mapBothEager(
           SchemaParser.decodeEffect(exit)(input.exit, options),
           {
             onSuccess: (exit) => new Complete({ exit }),
-            onFailure: (issue) =>
-              new SchemaIssue.Composite(ast, Option.some(input), [
-                new SchemaIssue.Pointer(["exit"], issue)
-              ])
+            onFailure: (issue) => SchemaIssue.makeCompositeAtKey(ast, "exit", issue, input, options)
           }
         )
       },
@@ -599,7 +596,7 @@ export class Complete<A, E> extends Data.TaggedClass("Complete")<{
  * Represents a suspended workflow execution, optionally carrying the cause that
  * triggered suspension.
  *
- * @category results
+ * @category schemas
  * @since 4.0.0
  */
 export class Suspended extends Schema.Class<Suspended>(
@@ -620,7 +617,7 @@ export class Suspended extends Schema.Class<Suspended>(
  * Creates a schema for workflow results using the supplied success and error
  * schemas.
  *
- * @category results
+ * @category schemas
  * @since 4.0.0
  */
 export const Result = <
@@ -636,7 +633,7 @@ const AnyOrVoid = Schema.Union([Schema.Any, Schema.Void])
 /**
  * Schema for encoded workflow results with generic success and error payloads.
  *
- * @category results
+ * @category schemas
  * @since 4.0.0
  */
 export const ResultEncoded: Schema.Codec<ResultEncoded<any, any>> = Schema.toEncoded(
@@ -653,7 +650,7 @@ export const ResultEncoded: Schema.Codec<ResultEncoded<any, any>> = Schema.toEnc
  * `Result`, handling suspension, defect capture, interruption, and workflow
  * scope finalization.
  *
- * @category results
+ * @category converting
  * @since 4.0.0
  */
 export const intoResult = <A, E, R>(
@@ -716,7 +713,7 @@ export const intoResult = <A, E, R>(
  * Wraps an activity-like effect so workflow suspension waits for currently
  * running activities to finish or suspend.
  *
- * @category results
+ * @category resource management
  * @since 4.0.0
  */
 export const wrapActivityResult = <A, E, R>(
@@ -825,7 +822,7 @@ export const addFinalizer: <R>(
  *
  * Compensation finalizers are only registered for top-level effects in the workflow and do not work for nested activities.
  *
- * @category Compensation
+ * @category compensation
  * @since 4.0.0
  */
 export const withCompensation: {
@@ -845,7 +842,7 @@ export const withCompensation: {
    *
    * Compensation finalizers are only registered for top-level effects in the workflow and do not work for nested activities.
    *
-   * @category Compensation
+   * @category compensation
    * @since 4.0.0
    */
   <A, R2>(
@@ -869,7 +866,7 @@ export const withCompensation: {
    *
    * Compensation finalizers are only registered for top-level effects in the workflow and do not work for nested activities.
    *
-   * @category Compensation
+   * @category compensation
    * @since 4.0.0
    */
   <A, E, R, R2>(
@@ -891,7 +888,7 @@ export const withCompensation: {
  * Marks a workflow instance as suspended and interrupts the current fiber to
  * stop execution until it is resumed.
  *
- * @category results
+ * @category interruption
  * @since 4.0.0
  */
 export const suspend = (instance: WorkflowInstance["Service"]): Effect.Effect<never> =>
@@ -908,7 +905,7 @@ export const suspend = (instance: WorkflowInstance["Service"]): Effect.Effect<ne
  *
  * By default, this annotation is set to `true`, meaning defects are captured.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const CaptureDefects = Context.Reference<boolean>(
@@ -925,7 +922,7 @@ export const CaptureDefects = Context.Reference<boolean>(
  *
  * The suspended execution can later be resumed with the workflow's `resume` method, for example `MyWorkflow.resume(executionId)`.
  *
- * @category annotations
+ * @category services
  * @since 4.0.0
  */
 export const SuspendOnFailure = Context.Reference<boolean>(