Uneventful
    Preparing search index...

    An object representing a desired outcome, such as a task performed, a condition reached, or a value produced.

    As in tools like make and systemd, targets are things run or produced once, lazily, on-demand. Targets track demand for their work, the state of that work, and its ultimate result (success value or failure reason).

    Like services, targets have overridable implementations that can be configured for testing or customization purposes. They can also be forced into a committed state with a specific value or error, either for testing or for loosely-coupled coordination patterns.

    A target's lifecycle looks roughly like this: unused -> requested -> started -> committed (i.e. completed or failed):

    • Unused: freshly-created target()s are unused, and they return to being unused after a newRoot() call. (Making them resettable for testing.)

    • Requested: a target becomes requested as soon as it is called to access its Future result. If the target has a recipe, that recipe is started immediately, and the target proceeds to the Started state.

    • Started: Once started, a target's recipe runs to completion or failure, determining its committed state. A started target's recipe is locked in and can't be overridden using its .start(), .fail(), or .complete() methods: they can only be used in the "unused" or "requested" states.

    • Committed: when a recipe completes or fails, or the target is manually .complete()d or .fail()ed, it becomes committed: the result and any output value are available for querying, as well as being broadcast to any observers that were waiting for the target to complete.

    A rough state diagram:

            const tgt = target(recipe?)
    │
    ▼
    ┌──────────┐
    ┌<────────────│ UNUSED │─────────────>┐
    │ └──────────┘ │
    │ │ │
    │ tgt() │
    │ │ │
    │ ▼ │
    │ ┌───────────┐ │
    ├<────────────│ REQUESTED │────────────>┤
    │ └───────────┘ │
    │ │ │
    │ automatic transition if │
    │ created w/recipe │
    │ │ │
    │ ▼ .complete(output) or
    │ .start() ┌──────────┐ .fail(reason)
    └────────────>│ STARTED │ │
    └──────────┘ │
    │ │
    recipe returns / throws │
    │ │
    │<───────────────────┘
    │
    ▼
    ┌─────────────────────────────────────────┐
    │ COMMITTED │
    │ completed w/value or failed w/error │
    └─────────────────────────────────────────┘
    further .start()/.complete()/.fail() → throw
    newRoot() resets back to unused
    interface Target<T = void> {
        complete(value: T): void;
        fail(reason: string): void;
        start(recipe: Activity<T>): Future<T>;
        used(): boolean;
        (): Future<T>;
    }

    Type Parameters

    • T = void

      The type of output value the target produces, if any: defaults to void if not specified.

    • Experimental

      Request the target's outcome as an async future

      If the target is unused, it will transition to "requested" status, and then "started" if it was created with a recipe.

      Returns Future<T>

      a Future implementing the Promise and Yieldable interfaces for the target's result. You can wait for it using await, yield *, Promise.all(), or the synchronous .do(), .onValue(), etc. methods.

    Index

    Methods

    • Experimental

      Declare the target completed, committing it without using a recipe

      The existing recipe, if any, will not be run.

      This method can only be called on an unstarted target, or an error will be thrown.

      Parameters

      • value: T

        The output value to pass on to observers (can be omitted if the T type is void/undefined)

      Returns void

    • Experimental

      Commit the target as failed, with a reason

      Subsequent attempts to .complete() or fail the target will throw with the given error message.

      As with .complete() and .start(), this can only be run on an unstarted target, and overrides any existing recipe.

      Parameters

      • reason: string

      Returns void

    • Experimental

      Start work on the target using a new or changed recipe

      This works like .complete(), except that it lets you pass a generator, promise, generator function, task, target, Setup function, etc. to complete the target asynchronously. The target's previous recipe, if any, will be ignored.

      This method puts the target into the "started" state, and will throw an error if invoked on a target that's already started or committed.

      Parameters

      Returns Future<T>

      The target's Future

    • Experimental

      Has the target, or any of its methods, been called yet?

      (Note: this is the only Target method that doesn't move the target out of the "unused" state.)

      Returns boolean