@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/dist/Action.mjs

@@ -1,20 +1,28 @@
-import { Anyone } from "./contract/caller.mjs";
+import { Anyone, assertCaller } from "./contract/caller.mjs";
 import { BuiltIn, Forbidden, InvalidInput, Refusal, Unauthenticated } from "./contract/errors.mjs";
-import { assertKnown, assertName, assertOnce, heldOnce } from "./contract/names.mjs";
 import { assertDistinctTags, errorList, projectedErrors } from "./contract/declared.mjs";
-import { Implementation, builders, built, memoized, select, toList } from "./contract/implementation.mjs";
-import { inputOf } from "./contract/call.mjs";
+import { InputCheck } from "./contract/input-check.mjs";
+import { assertKnown, assertName, assertOnce, heldOnce } from "./contract/names.mjs";
+import { progressSink } from "./contract/progress.mjs";
+import { codecOf } from "./contract/codec.mjs";
+import { Stream, elementOf } from "./contract/stream.mjs";
+import { Implementation, acquire, builtWith, elementsOf, memoized, provideBuilders, toList, uniqueKey } from "./contract/implementation.mjs";
+import { authorizerOf } from "./contract/authorizer.mjs";
+import { inputOf, jsonRoundTrip, onProgressOf, watchInput } from "./contract/call.mjs";
+import { acquireFeeds, eventsOf, feedBuilders } from "./contract/feed.mjs";
+import { NotServed, SubscriptionError } from "./Event.mjs";
+import { polledOn, queuedPush, readOn } from "./contract/push.mjs";
+import { selectFrom } from "./contract/serving.mjs";
+import { watching } from "./contract/watch.mjs";
 import { Image } from "./contract/media.mjs";
-import { Array as Array$1, Cause, Context, Effect, Predicate, Schema } from "effect";
+import { Idempotency, keyed, layerIdempotency } from "./contract/idempotency.mjs";
+import { Array as Array$1, Cause, Effect, Function, Layer, Predicate, Schema, Stream as Stream$1 } from "effect";
 // src/contract/Action.ts
-const NoInput = Schema.Record(Schema.String, Schema.Never);
-const codecOf = (schema) => Schema.isSchema(schema) ? schema : Reflect.ownKeys(schema).length === 0 ? NoInput : Schema.Struct(schema);
 function make(name, options) {
 	assertName(name);
 	const { caller, readOnly } = options;
-	if (caller !== Anyone && !Context.isKey(caller)) throw new Error("Missing caller: declare Action.Anyone or an identity service key");
-	if (caller !== Anyone && Context.isReference(caller)) throw new Error("Invalid caller: an identity is a Context.Service, not a Context.Reference");
-	if (readOnly !== true && readOnly !== false) throw new Error(`Invalid readOnly: ${String(readOnly)} (set true or false)`);
+	assertCaller(caller);
+	if (!Predicate.isBoolean(readOnly)) throw new Error(`Invalid readOnly: ${String(readOnly)} (set true or false)`);
 	const action = {
 		caller,
 		name,
@@ -22,72 +30,109 @@ function make(name, options) {
 		input: codecOf(options.input ?? {}),
 		success: options.success === void 0 ? Schema.Void : codecOf(options.success),
 		error: errorList(options.error),
+		progress: options.progress === void 0 ? void 0 : codecOf(options.progress),
 		readOnly,
-		mcp: { ...options.mcp }
+		mcp: { ...options.mcp },
+		idempotencyKey: options.idempotencyKey
 	};
+	if (action.idempotencyKey !== void 0 && elementOf(action.success) !== void 0) throw new Error(`Action "${name}" answers a stream, so it takes no idempotencyKey (a kept answer is whole: answer a value, or remove the key)`);
 	assertDistinctTags(`Action "${action.name}"`, projectedErrors(action));
 	return action;
 }
+const appendErrors = (action, more) => {
+	const error = [...action.error, ...more];
+	const appended = {
+		...action,
+		error
+	};
+	assertDistinctTags(`Action "${action.name}"`, projectedErrors(appended));
+	return appended;
+};
+/**
+* `action` with the errors `more` declared after its own, as if `make` had been given them in
+* `error`: its handler may fail with them, and every surface answers and every client decodes
+* them. For errors a module adds to the actions it serves, such as a proxy's or a store's,
+* whose contracts are written elsewhere: `pipe(action, Action.withErrors([Unavailable]))`, or
+* `Action.withErrors(action, [Unavailable])`.
+*
+* **Gotchas**
+*
+* - It returns a new contract with the same name: implement, bind and list the value it returns, since surfaces match a contract by identity; the original and the copy in one surface are one name held twice.
+* - A `_tag` that `more` shares with the action's own errors or a built-in one throws as `make` throws for one `error` list: reuse the one schema value, which is declared once.
+*/
+const withErrors = Function.dual(2, appendErrors);
 function byName(actions) {
 	assertOnce("action", actions);
 	return Object.fromEntries(actions.map((action) => [action.name, action]));
 }
 /** Every authenticated caller may call a protected action. */
 const allowAll = () => Effect.void;
-const assertAuthorizer = (before) => {
-	if (!Predicate.isFunction(before)) throw new Error("Missing authorize: not a function (pass your rule, Action.allowAll, or an Effect returning one)");
-	return before;
-};
-const assertAuthorization = (authorize) => {
-	if (authorize === void 0) throw new Error("Protected actions require authorize, or Action.allowAll");
-	return authorize;
-};
-const assertNoAuthorization = (authorize) => {
-	if (authorize !== void 0) throw new Error("A public-only target takes no authorize (remove it, or list a protected action)");
-	return allowAll;
-};
-const authorizerOf = (before) => memoized(Effect.isEffect(before) ? Effect.map(before, assertAuthorizer) : Effect.succeed(assertAuthorizer(before)));
 function implement(actions, handlers, options) {
 	const listed = Array$1.ensure(actions);
 	const names = listed.map((action) => action.name);
 	assertOnce("action", listed);
-	const authorizer = authorizerOf(listed.some((action) => action.caller !== Anyone) ? assertAuthorization(options?.authorize) : assertNoAuthorization(options?.authorize));
+	const authorizer = authorizerOf({
+		singular: "action",
+		module: "Action"
+	}, listed.some((action) => action.caller !== Anyone), options?.authorize);
 	const pairWithActions = (built) => {
-		const keyed = Predicate.isFunction(built) ? Object.fromEntries(Array.isArray(actions) ? [] : listed.map(({ name }) => [name, built])) : built;
-		assertKnown("handlers", Object.keys(keyed), names, "remove it, or list its action");
+		const handlersByName = Predicate.isFunction(built) ? Object.fromEntries(Array.isArray(actions) ? [] : listed.map(({ name }) => [name, built])) : built;
+		assertKnown("handlers", Object.keys(handlersByName), names, "remove it, or list its action");
 		const bound = listed.flatMap((action) => {
-			const handle = Object.hasOwn(keyed, action.name) ? keyed[action.name] : void 0;
+			const handle = Object.hasOwn(handlersByName, action.name) ? handlersByName[action.name] : void 0;
 			return Predicate.isFunction(handle) ? [[action, handle]] : [];
 		});
 		const missing = names.filter((name) => !bound.some(([action]) => action.name === name));
 		if (missing.length > 0) throw new Error(`Missing handlers: ${missing.join(", ")} (return the handler for one action, or a record with an own function per listed action)`);
 		return bound;
 	};
-	const recorded = Effect.isEffect(handlers) ? Effect.map(handlers, pairWithActions) : Effect.succeed(pairWithActions(handlers));
+	const paired = Effect.isEffect(handlers) ? Effect.map(handlers, pairWithActions) : Effect.succeed(pairWithActions(handlers));
+	const recorded = listed.some((action) => action.idempotencyKey !== void 0) ? Effect.flatMap(paired, (written) => Effect.map(Effect.service(Idempotency), (store) => written.map(([action, handle]) => [action, keyed(action, store, handle)]))) : paired;
 	return new Implementation(listed, memoized(recorded), authorizer);
 }
 function layer(implementations) {
-	return builders(toList(implementations));
+	return Layer.empty.pipe(provideBuilders([...toList(implementations).map((app) => Implementation.layerOf(app)), ...feedBuilders(eventsOf(implementations))]));
 }
-const jsonRoundTrip = (schema) => {
-	const codec = Schema.fromJsonString(Schema.toCodecJson(schema));
-	const encode = Schema.encodeUnknownEffect(codec, { errors: "all" });
-	const decode = Schema.decodeUnknownEffect(codec, { errors: "all" });
-	return (value) => Effect.flatMap(encode(value), (encoded) => decode(encoded));
+const received = (schema) => {
+	const sent = jsonRoundTrip(schema);
+	return (value) => Effect.map(sent(value), (roundTripped) => roundTripped.value);
 };
 const mapFailuresInPlace = (cause, failure) => Effect.map(Effect.forEach(cause.reasons, (reason) => Cause.isFailReason(reason) ? Effect.match(failure(reason.error), {
 	onFailure: (refused) => Cause.combine(Cause.die(refused), Cause.die(reason.error)),
 	onSuccess: (decoded) => Cause.fail(Predicate.isError(reason.error) && Predicate.isError(decoded) ? Object.assign(decoded, { stack: reason.error.stack }) : decoded)
 }).pipe(Effect.map((mapped) => Cause.annotate(mapped, Cause.reasonAnnotations(reason)))) : Effect.succeed(Cause.fromReasons([reason]))), (causes) => Cause.fromReasons(causes.flatMap(({ reasons }) => reasons)));
 const methodOf = (action, run) => {
-	const input = jsonRoundTrip(action.input);
-	const success = jsonRoundTrip(action.success);
-	const failure = jsonRoundTrip(Schema.Union(projectedErrors(action)));
-	return (...args) => inputOf(action, args).pipe(Effect.flatMap(input), Effect.mapError(InvalidInput.fromSchemaError), Effect.flatMap((value) => Effect.catchCause(run(value), (cause) => Effect.flatMap(mapFailuresInPlace(cause, failure), Effect.failCause))), Effect.flatMap((value) => Effect.orDie(success(value))));
+	const input = received(action.input);
+	const element = elementOf(action.success);
+	const success = received(element ?? action.success);
+	const failure = received(Schema.Union(projectedErrors(action)));
+	const declared = (cause) => Effect.flatMap(mapFailuresInPlace(cause, failure), Effect.failCause);
+	const called = (args) => inputOf(action, args).pipe(Effect.flatMap(input), Effect.mapError(InvalidInput.fromSchemaError), Effect.map((value) => run(value, progressSink(onProgressOf(args)))));
+	if (element !== void 0) return (...args) => Stream$1.unwrap(Effect.map(called(args), elementsOf)).pipe(Stream$1.catchCause((cause) => Stream$1.fromEffect(declared(cause))), Stream$1.mapEffect((value) => Effect.orDie(success(value))));
+	return (...args) => called(args).pipe(Effect.flatMap((answer) => Effect.catchCause(answer, declared)), Effect.flatMap((value) => Effect.orDie(success(value))));
+};
+const watcherOf = (feeds) => (event, input, options) => {
+	const feed = feeds.find((held) => held.event === event);
+	if (feed === void 0) return Stream$1.fail(SubscriptionError.of(event.name, new NotServed()));
+	return Stream$1.unwrap(Effect.map(watchInput(event, input), ({ value }) => {
+		const subscriber = uniqueKey();
+		return watching({
+			name: event.name,
+			poll: polledOn("In process", event.name)((cursor) => feed.poll(value, cursor, { subscriber })),
+			stream: (cursor) => Stream$1.unwrap(Effect.flatMap(feed.stream(value), (open) => Effect.map(queuedPush(open, cursor, Effect.succeed, {
+				inOrder: true,
+				capacity: 1
+			}), (queue) => Stream$1.fromQueue(queue)))).pipe(readOn("In process", event.name))
+		}, options).pipe(Stream$1.ensuring(feed.release?.(value, subscriber) ?? Effect.void));
+	}));
 };
 function client(served, options) {
-	const apps = select(toList(served), options?.actions);
+	const { apps, events } = selectFrom(served, options?.actions);
 	assertOnce("action", apps.flatMap((app) => app.actions), heldOnce);
-	return Effect.map(built(apps), (bound) => Object.fromEntries(bound.map(([action, run]) => [action.name, methodOf(action, run)])));
+	assertOnce("event", events.flatMap((app) => app.events), heldOnce);
+	return Effect.map(builtWith([...apps.map((app) => Implementation.layerOf(app)), ...feedBuilders(events)], Effect.all([acquire(apps, void 0), acquireFeeds(events)])), ([bound, feeds]) => ({
+		...Object.fromEntries(bound.map(([action, run]) => [action.name, methodOf(action, run)])),
+		...feeds.length === 0 ? {} : { watch: watcherOf(feeds) }
+	}));
 }
-export { Anyone, BuiltIn, Forbidden, Image, InvalidInput, Refusal, Unauthenticated, allowAll, byName, client, implement, layer, make };
+export { Anyone, BuiltIn, Forbidden, Idempotency, Image, InputCheck, InvalidInput, Refusal, Stream, Unauthenticated, allowAll, byName, client, implement, layer, layerIdempotency, make, withErrors };

package/dist/ActionCli.d.mts

@@ -1,15 +1,19 @@
 import { BuiltIn } from "./contract/errors.mjs";
-import { ActionOf, BuildError, BuildServices, Holding, Known, Member, RequestOf, Selected, SelectedOf, Selection, Served } from "./contract/implementation.mjs";
-import { Any } from "./Action.mjs";
+import { EventBuildError, EventBuildServices, EventOf, EventRequestOf, ServingEvents } from "./contract/feed.mjs";
+import { Any, SubscriptionError } from "./Event.mjs";
+import { ActionOf, BuildError, BuildServices, Holding, Known, Member, RequestOf, Selected, SelectedEvents, SelectedEventsOf, SelectedOf, Selection, Served, ServedActions } from "./contract/implementation.mjs";
+import { Receiving } from "./contract/receiving.mjs";
+import { WatchArgs } from "./contract/watch.mjs";
+import { Any as Any$1 } from "./Action.mjs";
 import { Declaring } from "./contract/declared.mjs";
-import { Options, UserError } from "./cli/commands.mjs";
-import { AnyHttp, Client } from "./http/client.mjs";
+import { AnyHttp, Client, WatchError } from "./http/client.mjs";
 import "./ActionHttp.mjs";
-import { Effect } from "effect";
+import { Options, UserError } from "./cli/commands.mjs";
+import { Effect, Stream } from "effect";
 import { HttpClient } from "effect/http";
 import { CliError, Command } from "effect/cli";
 interface AnyBinding extends Declaring {
-  readonly actions: ReadonlyArray<Any>;
+  readonly actions: readonly Any$1[];
 }
 /**
  * Make a command of your own fail as a derived command does. Give it what the command calls, the
@@ -25,24 +29,29 @@ interface AnyBinding extends Declaring {
  * - A failure left unmapped, one call's included, is reported as a crash, `ERROR (#n)` with a stack trace: pipe the whole Effect through it, once.
  * - To add context, such as how far a batch got, print it before this in the pipe, `Effect.tapError(() => Console.error(…))`: a `UserError` wrapped around the result puts its JSON mid-sentence and hides the action's failure from `catchReason`.
  */
-export declare const toUserError: (calls: AnyBinding | ReadonlyArray<Any>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, UserError<Exclude<E, CliError.CliError>> | Exclude<E, Exclude<E, CliError.CliError>>, R>;
+export declare const toUserError: (calls: AnyBinding | readonly Any$1[]) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, UserError<Exclude<E, CliError.CliError>> | Exclude<E, Exclude<E, CliError.CliError>>, R>;
 /**
  * An aggregate command of the actions `A`: its name, the actions that are its subcommands,
  * and their options.
  */
-interface Options$1<A extends Any = Any> {
+interface Options$1<A extends Any$1 | Any = Any$1 | Any> {
   /** The aggregate command's name. */
   readonly name: string;
   /**
-   * The actions that are subcommands, among the binding's or the implementations' actions:
-   * `[GetUser, RenameUser]`. Defaults to every action of them.
+   * The actions that are subcommands and the event types that have a `watch`, among the
+   * binding's or the implementations': `[GetUser, RenameUser, UserRenamed]`, exactly those.
+   * Defaults to every one of them.
+   *
+   * **Gotchas**
+   *
+   * - A list naming actions alone adds no `watch`: list the event types beside them.
    */
-  readonly actions?: ReadonlyArray<A> | undefined;
+  readonly actions?: readonly A[] | undefined;
   /**
    * The options of each subcommand, keyed by its action's name, as `command` takes them:
    * `{ readFile: { positional: ["path"], render } }`.
    */
-  readonly commands?: { readonly [K in A as K["name"]]?: Options<K>; };
+  readonly commands?: { readonly [K in Extract<A, Any$1> as K["name"]]?: Options<K>; };
   /**
    * Commands of your own beside the derived ones, as `Command.withSubcommands` takes them:
    * `[importLinks]`, each made with Effect CLI's `Command.make` and printing its output itself,
@@ -58,16 +67,29 @@ interface Options$1<A extends Any = Any> {
    */
   readonly subcommands?: Subcommands | undefined;
 }
-type Subcommands = ReadonlyArray<Command.Command.SubcommandEntry>;
+type Subcommands = readonly Command.Command.SubcommandEntry[];
 type OwnCommand<Own extends Subcommands> = Subcommands extends Own ? never : Own[number] extends (infer Entry) ? Entry extends Command.Command<infer _N, infer _I, infer _C, infer _E, infer _R> ? Entry : Entry extends Command.Command.SubcommandGroup<infer Commands> ? Commands[number] : never : never;
 type CommandsOf<O> = O extends unknown ? "commands" extends keyof O ? NonNullable<O["commands" & keyof O]> : never : never;
 type KeysOf<C> = C extends unknown ? keyof C : never;
-type CommandOf<C, K> = C extends unknown ? (K extends keyof C ? C[K] : never) : never;
-type KnownOptions<O, Keys, A extends Any> = Known<O, Keys> & ([CommandsOf<O>] extends [never] ? unknown : {
-  readonly commands?: Known<CommandsOf<O>, { readonly [K in A["name"]]: Options<A>; }> & { readonly [K in KeysOf<CommandsOf<O>>]?: Known<CommandOf<CommandsOf<O>, K>, Options<Any>>; };
+type CommandOf<C, K> = C extends unknown ? K extends keyof C ? C[K] : never : never;
+type KnownOptions<O, Keys, A extends Any$1> = Known<O, Keys> & ([CommandsOf<O>] extends [never] ? unknown : {
+  readonly commands?: Known<CommandsOf<O>, { readonly [K in A["name"]]: Options<A>; }> & { readonly [K in KeysOf<CommandsOf<O>>]?: Known<CommandOf<CommandsOf<O>, K>, Options<Any$1>>; };
 });
-type Owning<App, A extends Any> = App extends unknown ? A extends ActionOf<App> ? App : never : never;
-type Local<App, A extends Any> = Effect.Effect<A["success"]["Type"], A["error"][number]["Type"] | BuildError<App, A> | BuiltIn, RequestOf<App, A> | BuildServices<App, A>>;
+type Owning<App, A extends Any$1> = App extends unknown ? A extends ActionOf<App> ? App : never : never;
+type Local<App, A extends Any$1> = Effect.Effect<A["success"]["Type"], A["error"][number]["Type"] | BuildError<App, A> | BuiltIn, RequestOf<App, A> | BuildServices<App, A>>;
+type LocalCall<Apps extends Served, O> = [SelectedOf<O, Apps>] extends [never] ? never : Local<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>;
+type LocalWatch<App, Listed extends Any> = [ServingEvents<App, Listed>] extends [never] ? never : Effect.Effect<void, SubscriptionError | BuiltIn | EventBuildError<App, Listed>, EventRequestOf<App, ServingEvents<App, Listed>> | EventBuildServices<App, Listed>>;
+type Watched<M, E extends Any> = M extends {
+  readonly watch: (event: E, ...args: WatchArgs<E, never>) => Stream.Stream<unknown, infer WE, infer WR>;
+} ? {
+  readonly error: WE;
+  readonly services: Exclude<WR, Receiving>;
+} : {
+  readonly error: never;
+  readonly services: never;
+};
+type WatchFailure<H extends AnyHttp, C, E extends Any> = [E] extends [never] ? never : C extends Effect.Effect<infer M, infer CE, unknown> ? CE | Watched<M, E>["error"] : WatchError<E, H>;
+type WatchServices<C, E extends Any> = [E] extends [never] ? never : C extends Effect.Effect<infer M, unknown, infer CR> ? CR | Watched<M, E>["services"] : HttpClient.HttpClient;
 /**
  * Project one implemented action into a native Effect CLI command that runs its handler in
  * process, behind its implementation's authorization. It is named after the action in kebab
@@ -79,6 +101,8 @@ type Local<App, A extends Any> = Effect.Effect<A["success"]["Type"], A["error"][
  * **Gotchas**
  *
  * - A success is its JSON on stdout, indented by two spaces, or `render`'s text; nothing for an action without `success`. Its Effect logs and `Console` output go to stderr; other writes as `logToStderr` says.
+ * - Each value an action declaring `progress` reports is one line of compact JSON on stderr, as it arrives, so stdout holds the answer alone; `remoteCommand` asks the server for them too.
+ * - An action answering a stream prints each element on stdout as it arrives, one line of compact JSON, or `render`'s text of it; a declared failure ends the command after the elements before it.
  * - A declared error is its JSON on stderr, under Effect CLI's `ERROR` heading, the command failing with a `UserError` whose `cause` is the error, exit 1 or its `Runtime.errorExitCode`; a refusal as `Action.Unauthenticated` and `Action.Forbidden` say; input that does not decode, in `--input` or a flag's JSON value, is `InvalidInput`'s JSON there, while a missing flag or a rejected choice is Effect CLI's own parse error.
  * - Effect CLI styles what it prints, a failure's JSON included, on a terminal and, from Effect 4.0.6, wherever `FORCE_COLOR` forces colour: for plain text there, set `NO_COLOR` or provide `TerminalCapabilities.TerminalCapabilities` with `canColor: false`.
  * - A failure no schema encodes, a builder's or an accepted error that does not encode, is a `UserError` printed as its tag or name and its message, then its causes, never its other fields; a defect, an undeclared failure, or a success that does not encode is the command's defect, which `runMain` reports as `logToStderr` says.
@@ -86,14 +110,15 @@ type Local<App, A extends Any> = Effect.Effect<A["success"]["Type"], A["error"][
  * - Each run builds the action's implementation, its builder and an authorizer an Effect builds, and releases them after the call, even where the host already built them; implementations passed beside it are not built.
  * - A field named like a global flag (`help`, `version`, `log-level`) is no clash: its flag shadows the global one on this command.
  */
-export declare function command<const Apps extends Served, A extends ActionOf<Member<Apps>>, const O = {}>(implementations: Apps, action: A, options?: O & NoInfer<Options<A>> & NoInfer<Known<O, Options<Any>>>): Command.Command<string, never, {}, Failing<Effect.Error<Local<Owning<Member<Apps>, A>, A>>>, Effect.Services<Local<Owning<Member<Apps>, A>, A>>>;
+export declare const command: <const Apps extends ServedActions, A extends ActionOf<Member<Apps>>, const O = {}>(implementations: Apps, action: A, options?: O & NoInfer<Options<A>> & NoInfer<Known<O, Options<Any$1>>>) => Command.Command<string, never, {}, Failing<Effect.Error<Local<Owning<Member<Apps>, A>, A>>>, Effect.Services<Local<Owning<Member<Apps>, A>, A>>>;
 /**
  * Project one action of an HTTP binding into a native Effect CLI command, derived as `command`
  * derives it, that calls the action through `client`'s method and fails as the method does, or
  * as the Effect building the client does. It runs nothing locally and names no caller: the
  * server verifies the credentials its client sends.
  */
-export declare function remoteCommand<const H extends AnyHttp, A extends H["actions"][number], const O = {}, C extends ClientOf<H, A> | undefined = undefined>(binding: H, action: A, options?: O & NoInfer<Options<A>> & NoInfer<Known<O, RemoteKeys<Options<Any>>>> & Calling<C>): Command.Command<string, never, {}, Failing<CallFailure<H, C, A>>, CallServices<C, A>>;
+export declare function remoteCommand<const H extends AnyHttp, A extends H["actions"][number], const O = {}, C extends ClientOf<H, A> | undefined = undefined>(binding: H, action: A, options?: O & NoInfer<Options<A>> & NoInfer<Known<O, RemoteKeys<Options<Any$1>>>> & Calling<C>): Command.Command<string, never, {}, Failing<CallFailure<H, C, A>>, CallServices<C, A>>;
+/** The `client` option of `remote` and `remoteCommand`, declared once for both. */
 export interface Calling<C> {
   /**
    * The connection: an Effect of the binding's client, such as
@@ -112,41 +137,52 @@ export interface Calling<C> {
    */
   readonly client?: C;
 }
-type ClientOf<H extends AnyHttp, A extends Any> = Effect.Effect<Pick<Client<H, unknown, unknown>, A["name"]>, unknown, unknown>;
-type Needed<O, L extends ReadonlyArray<Any>, All extends Any> = "actions" extends (O extends unknown ? keyof O : never) ? Selected<O, All> : L[number];
+type ClientOf<H extends AnyHttp, A extends Any$1, E extends Any = never> = Effect.Effect<Pick<Client<H, unknown, unknown>, A["name"] | ([E] extends [never] ? never : "watch")>, unknown, unknown>;
+type Needed<O, L extends readonly unknown[], All extends Any$1> = "actions" extends (O extends unknown ? keyof O : never) ? Selected<O, All> : Extract<L[number], All>;
+type NeededEvents<O, L extends readonly unknown[], All extends Any> = "actions" extends (O extends unknown ? keyof O : never) ? SelectedEvents<O, All> : Extract<L[number], All>;
 type RemoteKeys<Keys> = Keys & {
   readonly client?: unknown;
 };
-type Failing<F> = UserError<Exclude<F, CliError.CliError>> | Extract<F, CliError.CliError>;
-type Called<M, A extends Any> = A extends unknown ? A["name"] extends keyof M ? M[A["name"]] extends ((...input: never) => infer Call) ? Call : never : never : never;
-type CallFailure<H extends AnyHttp, C, A extends Any> = C extends Effect.Effect<infer M, infer CE, unknown> ? CE | Effect.Error<Called<M, A>> : Effect.Error<Called<Client<H>, A>>;
-type CallServices<C, A extends Any> = C extends Effect.Effect<infer M, unknown, infer CR> ? CR | Effect.Services<Called<M, A>> : HttpClient.HttpClient;
+type Failing<F> = [F] extends [never] ? never : UserError<Exclude<F, CliError.CliError>> | Extract<F, CliError.CliError>;
+type Called<M, A extends Any$1> = A extends unknown ? A["name"] extends keyof M ? M[A["name"]] extends ((...input: never) => infer Call) ? Call : never : never : never;
+type CallError<Call> = Effect.Error<Call> | Stream.Error<Call>;
+type CallRequirements<Call> = Effect.Services<Call> | Stream.Services<Call>;
+type CallFailure<H extends AnyHttp, C, A extends Any$1> = C extends Effect.Effect<infer M, infer CE, unknown> ? CE | CallError<Called<M, A>> : CallError<Called<Client<H>, A>>;
+type CallServices<C, A extends Any$1> = C extends Effect.Effect<infer M, unknown, infer CR> ? CR | CallRequirements<Called<M, A>> : HttpClient.HttpClient;
 /**
  * Project the implemented actions, every one or those `actions` selects, as subcommands of one
  * aggregate command, each derived as `command` derives it and run in process. `commands` gives a
  * subcommand the options `command` takes, by action name; `subcommands` adds commands of your
- * own. `remote` calls a server instead. A test runs it in memory, with no process: `Command.runWith(command, { version })(args)`.
+ * own. `remote` calls a server instead. Each event type among the implementations, or each
+ * `actions` lists, adds `watch <event>`, a flag per input field and `--cursor`, printing each
+ * occurrence, or a `Gap`, as one line of JSON, its `cursor` included, until it is stopped. A test
+ * runs it in memory, with no process: `Command.runWith(command, { version })(args)`.
  * Guide: `docs/ActionCli.md` in this package; in an application: `examples/assistant/src/commands.ts`.
  *
  * **Gotchas**
  *
  * - Services provided on it with `Command.provide` are also built when it runs with no subcommand, before it shows its help.
+ * - An event input field named `cursor` throws when `make` or `remote` is called, `--cursor` claiming its flag: rename the field.
+ * - A watch's refusal, when it starts or later, or `Event.SubscriptionError`, ends the command as its `UserError`, exit 1, after the lines it printed.
  */
-export declare function make<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>>> = {}, const Own extends Subcommands = []>(implementations: Apps, options: O & NoInfer<Options$1<ActionOf<Member<Apps>>>> & NoInfer<KnownOptions<O, Options$1, ActionOf<Member<Apps>>>> & {
+export declare const make: <const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>> | EventOf<Member<Apps>>> = {}, const Own extends Subcommands = []>(implementations: Apps, options: O & NoInfer<Options$1<ActionOf<Member<Apps>> | EventOf<Member<Apps>>>> & NoInfer<KnownOptions<O, Options$1, ActionOf<Member<Apps>>>> & {
   readonly subcommands?: Own | undefined;
-}): Command.Command<string, {}, {}, Failing<Effect.Error<Local<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>>> | Command.Error<OwnCommand<Own>>, Effect.Services<Local<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>> | Command.Services<OwnCommand<Own>>>;
+}) => Command.Command<string, {}, {}, Failing<Effect.Error<LocalCall<Apps, O> | LocalWatch<Member<Apps>, SelectedEventsOf<O, Apps>>>> | Command.Error<OwnCommand<Own>>, Effect.Services<LocalCall<Apps, O> | LocalWatch<Member<Apps>, SelectedEventsOf<O, Apps>>> | Command.Services<OwnCommand<Own>>>;
 /**
  * Project the actions of an HTTP binding, every one or those `actions` selects, as subcommands of
  * one aggregate command, derived as `make` derives them, each calling its action through
  * `client`'s method, as `remoteCommand` does. `commands` gives one the options `command` takes;
  * `subcommands` adds commands of your own, which call through the same client by yielding the
- * Effect given as `client`.
- * In an application: `examples/notes-service/src/commands.ts`.
+ * Effect given as `client`. Each event type of the binding, or each `actions` lists, adds
+ * `watch <event>`, as `make` adds it, watching through `client`'s `watch`, which reconnects as
+ * `ActionHttp.client`'s does.
+ * In an application: `examples/notes-service/src/commands.ts`, and for events,
+ * `examples/build-events/src/commands.ts`.
  */
-export declare function remote<const H extends AnyHttp, const O extends Selection<H["actions"][number]> = {}, const Own extends Subcommands = [], const L extends ReadonlyArray<H["actions"][number]> = H["actions"], C extends ClientOf<H, Needed<O, L, H["actions"][number]>> | undefined = undefined>(binding: H, options: O & NoInfer<Options$1<H["actions"][number]>> & NoInfer<KnownOptions<O, RemoteKeys<Options$1<Any>>, H["actions"][number]>> & Calling<C> & {
+export declare function remote<const H extends AnyHttp, const O extends Selection<H["actions"][number] | H["events"][number]> = {}, const Own extends Subcommands = [], const L extends ReadonlyArray<H["actions"][number] | H["events"][number]> = [...H["actions"], ...H["events"]], C extends ClientOf<H, Needed<O, L, H["actions"][number]>, NeededEvents<O, L, H["events"][number]>> | undefined = undefined>(binding: H, options: O & NoInfer<Options$1<H["actions"][number] | H["events"][number]>> & NoInfer<KnownOptions<O, RemoteKeys<Options$1>, H["actions"][number]>> & Calling<C> & {
   readonly actions?: L | undefined;
   readonly subcommands?: Own | undefined;
-}): Command.Command<string, {}, {}, Failing<CallFailure<H, C, Selected<O, H["actions"][number]>>> | Command.Error<OwnCommand<Own>>, CallServices<C, Selected<O, H["actions"][number]>> | Command.Services<OwnCommand<Own>>>;
+}): Command.Command<string, {}, {}, Failing<CallFailure<H, C, Selected<O, H["actions"][number]>> | WatchFailure<H, C, SelectedEvents<O, H["events"][number]>>> | Command.Error<OwnCommand<Own>>, CallServices<C, Selected<O, H["actions"][number]>> | WatchServices<C, SelectedEvents<O, H["events"][number]>> | Command.Services<OwnCommand<Own>>>;
 /**
  * A program whose stdout carries only its results, such as a CLI feeding scripts or an MCP
  * subprocess, applied last, before `NodeRuntime.runMain`: the default logger of every layer

package/dist/ActionCli.mjs

@@ -1,9 +1,14 @@
+import { bindingErrors, eventErrors, projectedErrors } from "./contract/declared.mjs";
 import { assertDistinct, assertKnown } from "./contract/names.mjs";
-import { bindingErrors, projectedErrors } from "./contract/declared.mjs";
-import { Implementation, acquire, assertHeld, notHeld, select, toList } from "./contract/implementation.mjs";
-import { client } from "./ActionHttp.mjs";
-import { command as command$1, failingAsDerived } from "./cli/commands.mjs";
-import { Cause, Effect, Logger, Runtime } from "effect";
+import { progressSink } from "./contract/progress.mjs";
+import { elementOf } from "./contract/stream.mjs";
+import { Implementation, acquire, assertHeld, elementsOf, notHeld, toList } from "./contract/implementation.mjs";
+import { selection } from "./contract/listed.mjs";
+import { selectFrom } from "./contract/serving.mjs";
+import { client } from "./Action.mjs";
+import { client as client$1 } from "./ActionHttp.mjs";
+import { command as command$1, failingAsDerived, watchCommand } from "./cli/commands.mjs";
+import { Cause, Effect, Logger, Runtime, Stream } from "effect";
 import { Command } from "effect/cli";
 // src/cli/ActionCli.ts
 /**
@@ -21,12 +26,14 @@ import { Command } from "effect/cli";
 * - To add context, such as how far a batch got, print it before this in the pipe, `Effect.tapError(() => Console.error(…))`: a `UserError` wrapped around the result puts its JSON mid-sentence and hides the action's failure from `catchReason`.
 */
 const toUserError = (calls) => "actions" in calls ? failingAsDerived(calls.actions.flatMap((action) => bindingErrors(action, calls))) : failingAsDerived(calls.flatMap((action) => projectedErrors(action)));
-const runWithBuildOfItsOwn = (app, action, input) => {
+const runWithBuildOfItsOwn = (app, action, input, onProgress) => {
 	const thisActionOnly = Implementation.share([action], app);
-	return Effect.flatMap(acquire([thisActionOnly]), (bound) => {
+	const call = Effect.flatMap(acquire([thisActionOnly], void 0), (bound) => {
 		const [, run] = bound.find(([candidate]) => candidate === action) ?? [];
-		return run === void 0 ? Effect.die(/* @__PURE__ */ new Error(`No handler for ${action.name}`)) : run(input);
-	}).pipe(Effect.provide(Implementation.layerOf(thisActionOnly), { local: true }));
+		return run === void 0 ? Effect.die(/* @__PURE__ */ new Error(`No handler for ${action.name}`)) : run(input, progressSink(onProgress));
+	});
+	const builder = Implementation.layerOf(thisActionOnly);
+	return elementOf(action.success) === void 0 ? call.pipe(Effect.provide(builder, { local: true })) : Effect.succeed(elementsOf(call).pipe(Stream.provide(builder, { local: true })));
 };
 const theImplementationOf = (apps, action) => {
 	const [app, ...others] = apps.filter((candidate) => candidate.actions.includes(action));
@@ -36,32 +43,38 @@ const theImplementationOf = (apps, action) => {
 };
 const inProcess = (apps, action, options) => {
 	const app = theImplementationOf(apps, action);
-	return command$1(action, (input) => runWithBuildOfItsOwn(app, action, input), options, projectedErrors(action));
+	return command$1(action, (input, onProgress) => runWithBuildOfItsOwn(app, action, input, onProgress), options, projectedErrors(action));
 };
-const overHttp = (binding, action, options, client$1) => {
+const overHttp = (binding, action, options, client) => {
 	if (!binding.actions.includes(action)) throw new Error(`Action "${action.name}" is not in this HTTP binding (pass it to the binding's ActionHttp.make, and select with the contract value it received)`);
-	return command$1(action, (input) => Effect.flatMap(client$1 ?? client(binding), (methods) => {
+	return command$1(action, (input, onProgress) => Effect.flatMap(client ?? client$1(binding), (methods) => {
 		const method = methods[action.name];
 		if (method === void 0) throw new Error(`No client method for ${action.name} (give \`client\` a method for this action)`);
-		return method(input);
+		const answer = method(input, { onProgress });
+		return Stream.isStream(answer) ? Effect.succeed(answer) : answer;
 	}), options, bindingErrors(action, binding));
 };
-const aggregateCommand = (name, actions, commands, own, project) => {
-	const derived = actions.map((action) => ({
+/** The command watching `event` through the `watch` of each client `client` makes as it runs. */
+const watched = (event, client, errors) => watchCommand(event, (input, cursor) => Stream.unwrap(Effect.map(client, (methods) => methods.watch(event, input, { cursor }))), errors);
+const aggregateCommand = (name, actions, commands, own, project, watches) => {
+	const derived = [...actions.map((action) => ({
 		claimant: `action ${action.name}`,
 		command: project(action, Object.hasOwn(commands, action.name) ? commands[action.name] : void 0)
-	}));
-	assertDistinct("command", [...derived.map(({ claimant, command }) => ({
+	})), ...watches.length === 0 ? [] : [{
+		claimant: "the event types",
+		command: Command.make("watch").pipe(Command.withDescription("Watch an event type, each occurrence a line of JSON"), Command.withSubcommands(watches))
+	}]];
+	assertDistinct("command", [...derived.map(({ claimant, command: derivedCommand }) => ({
 		claimant,
-		name: command.name
-	})), ...own.flatMap((entry) => Command.isCommand(entry) ? [entry] : entry.commands).map((command) => ({
+		name: derivedCommand.name
+	})), ...own.flatMap((entry) => Command.isCommand(entry) ? [entry] : entry.commands).map((subcommand) => ({
 		claimant: "subcommands",
-		name: command.name
+		name: subcommand.name
 	}))], ({ name: claimed }) => claimed, {
 		claimantOf: ({ claimant }) => claimant,
 		fix: "rename one of your subcommands, or give an action's command another name in commands"
 	});
-	return Command.make(name).pipe(Command.withSubcommands([...derived.map(({ command }) => command), ...own]));
+	return Command.make(name).pipe(Command.withSubcommands([...derived.map(({ command: derivedCommand }) => derivedCommand), ...own]));
 };
 const checkedCommandsOf = (commands, actions) => {
 	const given = commands ?? {};
@@ -79,6 +92,8 @@ const checkedCommandsOf = (commands, actions) => {
 * **Gotchas**
 *
 * - A success is its JSON on stdout, indented by two spaces, or `render`'s text; nothing for an action without `success`. Its Effect logs and `Console` output go to stderr; other writes as `logToStderr` says.
+* - Each value an action declaring `progress` reports is one line of compact JSON on stderr, as it arrives, so stdout holds the answer alone; `remoteCommand` asks the server for them too.
+* - An action answering a stream prints each element on stdout as it arrives, one line of compact JSON, or `render`'s text of it; a declared failure ends the command after the elements before it.
 * - A declared error is its JSON on stderr, under Effect CLI's `ERROR` heading, the command failing with a `UserError` whose `cause` is the error, exit 1 or its `Runtime.errorExitCode`; a refusal as `Action.Unauthenticated` and `Action.Forbidden` say; input that does not decode, in `--input` or a flag's JSON value, is `InvalidInput`'s JSON there, while a missing flag or a rejected choice is Effect CLI's own parse error.
 * - Effect CLI styles what it prints, a failure's JSON included, on a terminal and, from Effect 4.0.6, wherever `FORCE_COLOR` forces colour: for plain text there, set `NO_COLOR` or provide `TerminalCapabilities.TerminalCapabilities` with `canColor: false`.
 * - A failure no schema encodes, a builder's or an accepted error that does not encode, is a `UserError` printed as its tag or name and its message, then its causes, never its other fields; a defect, an undeclared failure, or a success that does not encode is the command's defect, which `runMain` reports as `logToStderr` says.
@@ -86,9 +101,7 @@ const checkedCommandsOf = (commands, actions) => {
 * - Each run builds the action's implementation, its builder and an authorizer an Effect builds, and releases them after the call, even where the host already built them; implementations passed beside it are not built.
 * - A field named like a global flag (`help`, `version`, `log-level`) is no clash: its flag shadows the global one on this command.
 */
-function command(implementations, action, options) {
-	return inProcess(toList(implementations), action, options);
-}
+const command = (implementations, action, options) => inProcess(toList(implementations), action, options);
 function remoteCommand(binding, action, options) {
 	const { client, ...syntax } = options ?? {};
 	return overHttp(binding, action, options === void 0 ? void 0 : syntax, client);
@@ -97,24 +110,30 @@ function remoteCommand(binding, action, options) {
 * Project the implemented actions, every one or those `actions` selects, as subcommands of one
 * aggregate command, each derived as `command` derives it and run in process. `commands` gives a
 * subcommand the options `command` takes, by action name; `subcommands` adds commands of your
-* own. `remote` calls a server instead. A test runs it in memory, with no process: `Command.runWith(command, { version })(args)`.
+* own. `remote` calls a server instead. Each event type among the implementations, or each
+* `actions` lists, adds `watch <event>`, a flag per input field and `--cursor`, printing each
+* occurrence, or a `Gap`, as one line of JSON, its `cursor` included, until it is stopped. A test
+* runs it in memory, with no process: `Command.runWith(command, { version })(args)`.
 * Guide: `docs/ActionCli.md` in this package; in an application: `examples/assistant/src/commands.ts`.
 *
 * **Gotchas**
 *
 * - Services provided on it with `Command.provide` are also built when it runs with no subcommand, before it shows its help.
+* - An event input field named `cursor` throws when `make` or `remote` is called, `--cursor` claiming its flag: rename the field.
+* - A watch's refusal, when it starts or later, or `Event.SubscriptionError`, ends the command as its `UserError`, exit 1, after the lines it printed.
 */
-function make(implementations, options) {
+const make = (implementations, options) => {
 	const apps = toList(implementations);
+	const { apps: served, events } = selectFrom(implementations, options.actions);
 	const commands = checkedCommandsOf(options.commands, apps.flatMap((app) => app.actions));
-	const served = select(apps, options.actions);
-	return aggregateCommand(options.name, served.flatMap((app) => app.actions), commands, options.subcommands ?? [], (action, syntax) => inProcess(served, action, syntax));
-}
+	return aggregateCommand(options.name, served.flatMap((app) => app.actions), commands, options.subcommands ?? [], (action, syntax) => inProcess(served, action, syntax), events.flatMap((app) => app.events.map((event) => watched(event, client(app), eventErrors(event, { error: [] })))));
+};
 function remote(binding, options) {
-	const listed = options.actions;
-	if (listed !== void 0) assertHeld(notHeld.byBinding, listed, binding.actions);
+	const listed = selection(options.actions);
+	if (listed.actions !== void 0) assertHeld(notHeld.byBinding, listed.actions, binding.actions);
+	if (listed.events !== void 0) assertHeld(notHeld.byBinding, listed.events, binding.events);
 	const commands = checkedCommandsOf(options.commands, binding.actions);
-	return aggregateCommand(options.name, binding.actions.filter((action) => listed?.includes(action) ?? true), commands, options.subcommands ?? [], (action, syntax) => overHttp(binding, action, syntax, options.client));
+	return aggregateCommand(options.name, binding.actions.filter((action) => listed.actions?.includes(action) ?? true), commands, options.subcommands ?? [], (action, syntax) => overHttp(binding, action, syntax, options.client), binding.events.filter((event) => listed.events?.includes(event) ?? true).map((event) => watched(event, options.client ?? client$1(binding), eventErrors(event, binding))));
 }
 /**
 * A program whose stdout carries only its results, such as a CLI feeding scripts or an MCP