effect 4.0.0-beta.79 → 4.0.0-beta.80

package/src/unstable/cli/Prompt.ts

@@ -66,8 +66,8 @@ export const isPrompt = (u: unknown): u is Prompt<unknown> => Predicate.hasPrope
 export type Environment = FileSystem.FileSystem | Path.Path | Terminal.Terminal
 
 /**
- * Represents the action that should be taken by a `Prompt` based upon the
- * user input received during the current frame.
+ * Represents the action that should be taken by a `Prompt` based upon user
+ * input or an external event received during the current frame.
  *
  * @category models
  * @since 4.0.0
@@ -93,6 +93,18 @@ export interface ActionDefinition extends Data.TaggedEnum.WithGenerics<2> {
   readonly taggedEnum: Action<this["A"], this["B"]>
 }
 
+/**
+ * Represents the input that should be processed by a `Prompt` based upon user
+ * input or an external event received during the current frame.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type ProcessInput<A> = Data.TaggedEnum<{
+  readonly Input: { readonly input: Terminal.UserInput }
+  readonly Event: { readonly value: A }
+}>
+
 /**
  * Represents the set of handlers used by a `Prompt`.
  *
@@ -104,7 +116,7 @@ export interface ActionDefinition extends Data.TaggedEnum.WithGenerics<2> {
  * @category models
  * @since 4.0.0
  */
-export interface Handlers<State, Output> {
+export interface Handlers<State, Output, Input = Terminal.UserInput> {
   /**
    * A function that is called to render the current frame of the `Prompt`.
    */
@@ -117,7 +129,7 @@ export interface Handlers<State, Output> {
    * `Prompt.Action` that should be taken.
    */
   readonly process: (
-    input: Terminal.UserInput,
+    input: Input,
     state: State
   ) => Effect.Effect<Action<State, Output>, never, Environment>
   /**
@@ -751,19 +763,85 @@ export const confirm = (options: ConfirmOptions): Prompt<boolean> => {
  * next prompt action, and `clear` returns ANSI output used to clear the previous
  * frame.
  *
+ * Optionally, an external `events` dequeue can be provided as the third
+ * argument. When present, the render loop will race user input against events
+ * from the dequeue, allowing background events to trigger re-renders without
+ * waiting for a keypress. When an event is received from the dequeue, the
+ * `receive` handler is called instead of `process`.
+ *
  * @category constructors
  * @since 4.0.0
  */
-export const custom = <State, Output>(
+export const custom: {
+  /**
+   * Creates a custom `Prompt` from the specified initial state and handlers.
+   *
+   * **Details**
+   *
+   * The initial state can either be a pure value or an `Effect`. This is
+   * particularly useful when the initial state of the `Prompt` must be computed
+   * by performing an effectful computation, such as reading data from the file
+   * system. A `Prompt` runs as a render loop: `render` returns ANSI output for
+   * the current frame, the `Terminal` obtains user input, `process` returns the
+   * next prompt action, and `clear` returns ANSI output used to clear the previous
+   * frame.
+   *
+   * Optionally, an external `events` dequeue can be provided as the third
+   * argument. When present, the render loop will race user input against events
+   * from the dequeue, allowing background events to trigger re-renders without
+   * waiting for a keypress. When an event is received from the dequeue, the
+   * `receive` handler is called instead of `process`.
+   *
+   * @category constructors
+   * @since 4.0.0
+   */
+  <State, Output>(
+    initialState: State | Effect.Effect<State, never, Environment>,
+    handlers: Handlers<State, Output>
+  ): Prompt<Output>
+  /**
+   * Creates a custom `Prompt` from the specified initial state and handlers.
+   *
+   * **Details**
+   *
+   * The initial state can either be a pure value or an `Effect`. This is
+   * particularly useful when the initial state of the `Prompt` must be computed
+   * by performing an effectful computation, such as reading data from the file
+   * system. A `Prompt` runs as a render loop: `render` returns ANSI output for
+   * the current frame, the `Terminal` obtains user input, `process` returns the
+   * next prompt action, and `clear` returns ANSI output used to clear the previous
+   * frame.
+   *
+   * Optionally, an external `events` dequeue can be provided as the third
+   * argument. When present, the render loop will race user input against events
+   * from the dequeue, allowing background events to trigger re-renders without
+   * waiting for a keypress. When an event is received from the dequeue, the
+   * `receive` handler is called instead of `process`.
+   *
+   * @category constructors
+   * @since 4.0.0
+   */
+  <State, Output, A>(
+    initialState: State | Effect.Effect<State, never, Environment>,
+    events: Queue.Dequeue<A, never>,
+    handlers: Handlers<State, Output, ProcessInput<A>>
+  ): Prompt<Output>
+} = <State, Output, A>(
   initialState: State | Effect.Effect<State, never, Environment>,
-  handlers: Handlers<State, Output>
+  ...args:
+    | [handlers: Handlers<State, Output, Terminal.UserInput>]
+    | [events: Queue.Dequeue<A, never>, handlers: Handlers<State, Output, ProcessInput<A>>]
 ): Prompt<Output> => {
+  const [events, handlers] = args.length === 1
+    ? [undefined, args[0]] as const
+    : [args[0], args[1]] as const
   const op = Object.create(proto)
   op._tag = "Loop"
   op.initialState = initialState
   op.render = handlers.render
   op.process = handlers.process
   op.clear = handlers.clear
+  op.events = events
   return op
 }
 
@@ -1266,8 +1344,12 @@ interface Loop extends
   Op<"Loop", {
     readonly initialState: unknown | Effect.Effect<unknown, never, Environment>
     readonly render: Handlers<unknown, unknown>["render"]
-    readonly process: Handlers<unknown, unknown>["process"]
+    readonly process: (
+      input: unknown,
+      state: unknown
+    ) => Effect.Effect<Action<unknown, unknown>, never, Environment>
     readonly clear: Handlers<unknown, unknown>["clear"]
+    readonly events: Queue.Dequeue<unknown, never> | undefined
   }>
 {}
 
@@ -1338,8 +1420,19 @@ const runLoop = Effect.fnUntraced(
     while (true) {
       const msg = yield* loop.render(state, action)
       yield* Effect.orDie(terminal.display(msg))
-      const event = yield* Queue.take(input)
-      action = yield* loop.process(event, state)
+      if (loop.events) {
+        const takeInput = Queue.take(input).pipe(
+          Effect.map((event) => ({ _tag: "Input" as const, event }))
+        )
+        const result = yield* Effect.raceFirst(
+          takeInput,
+          Queue.take(loop.events).pipe(Effect.map((value) => ({ _tag: "Event" as const, value })))
+        )
+        action = yield* loop.process(result, state)
+      } else {
+        const result = yield* Queue.take(input)
+        action = yield* loop.process(result, state)
+      }
       switch (action._tag) {
         case "Beep":
           continue