@gjermundgaraba/effect-actions 0.8.0 → 0.10.0

package/dist/internal/cli.mjs

@@ -1,50 +1,328 @@
-import { Console, Effect, Option, Schema } from "effect";
-import { Command, Flag } from "effect/cli";
+import { InvalidInput } from "./errors.mjs";
+import { assertDistinct, literalValues, members, projectedErrors, unsuspended } from "./actions.mjs";
+import { logToStderr } from "./console.mjs";
+import { Console, Effect, Option, Predicate, Record, Runtime, Schema, SchemaAST } from "effect";
+import { CliError, Command, Flag, Param } from "effect/cli";
 //#region src/internal/cli.ts
-const isParametersOptions = (options) => options?.parameters !== void 0;
+/**
+* `getUser` as a command or flag name: `get-user`; `getHTTPUser`: `get-http-user`; `_id`:
+* `id`, since a flag already starts with its dashes. A name of dashes and underscores alone,
+* which would be left empty, is kept as it is.
+*/
+const kebab = (name) => {
+	const kebabbed = name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/_/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
+	return kebabbed === "" ? name : kebabbed;
+};
 /**
 * A command with a renderer takes `--json` as a flag of its own, so nothing is
 * claimed tree-wide and a host's `--json`, global or not, is never contested.
 * Without a renderer the output is JSON already and there is no flag.
 */
 const jsonFlag = Flag.Boolean("json").pipe(Flag.withDefault(false), Flag.withDescription("Print machine-readable JSON"));
-const output = (action, execute, input, render) => Effect.gen(function* () {
-	const value = yield* execute(input);
-	const encoded = yield* Schema.encodeEffect(Schema.toCodecJson(action.success))(value);
-	yield* Console.log(render === void 0 ? JSON.stringify(encoded, null, 2) : render(value));
+/** The kinds of JSON value there are. */
+const jsonKinds = [
+	"null",
+	"boolean",
+	"number",
+	"string",
+	"array",
+	"object"
+];
+/** The kind of a JSON value, or of a literal's, which JSON has no bigint for. */
+const kindOf = (value) => value === null ? "null" : Predicate.isBoolean(value) ? "boolean" : Predicate.isNumber(value) ? "number" : Predicate.isString(value) ? "string" : Array.isArray(value) ? "array" : "object";
+/**
+* The kinds of JSON value an encoded type accepts at its top, each member's of a union and a
+* suspended type's: its checks and what it nests aside, which the action's schema decodes.
+* A type of no fixed kind accepts all.
+*/
+const kindsOf = (ast) => members(ast).flatMap((member) => {
+	if (SchemaAST.isLiteral(member)) return [kindOf(member.literal)];
+	if (SchemaAST.isEnum(member)) return member.enums.map(([, value]) => kindOf(value));
+	if (SchemaAST.isNull(member)) return ["null"];
+	if (SchemaAST.isBoolean(member)) return ["boolean"];
+	if (SchemaAST.isNumber(member)) return ["number"];
+	if (SchemaAST.isString(member) || SchemaAST.isTemplateLiteral(member)) return ["string"];
+	if (SchemaAST.isArrays(member)) return ["array"];
+	if (SchemaAST.isObjects(member)) return ["object"];
+	return jsonKinds;
 });
 /**
-* One native command. The action's own parameters are one nested config, so the
-* flag added for a renderer never meets them in one record.
+* A flag's text as the JSON it holds when the field's `encoded` type accepts that kind of
+* value, or else as itself, for the action's schema to decode: for a number `21` parses,
+* while for `"auto" | string` the text `true` stays text. Only the kind is checked, so JSON
+* breaking a rule of the schema, such as a maximum length, stays JSON, and the action's
+* schema reports the rule and the path to what breaks it.
 */
-const make = (action, execute, options, config, decode) => {
-	const name = options?.name ?? action.name;
-	const render = options?.render;
-	return (render === void 0 ? Command.make(name, { parameters: config }, ({ parameters }) => Effect.flatMap(decode(parameters), (input) => output(action, execute, input, void 0))) : Command.make(name, {
-		parameters: config,
-		json: jsonFlag
-	}, ({ parameters, json }) => Effect.flatMap(decode(parameters), (input) => output(action, execute, input, json ? void 0 : render)))).pipe(Command.withDescription(action.description));
+const jsonOrText = (encoded) => {
+	const accepted = new Set(kindsOf(encoded));
+	return Schema.Union([Schema.fromJsonString(Schema.Json).check(Schema.makeFilter((json) => accepted.has(kindOf(json)))), Schema.String]);
+};
+/** The strings a union of string literals or a string enum accepts, if it is one. */
+const choices = (ast) => {
+	const accepted = members(ast).flatMap(literalValues);
+	return accepted.every(Predicate.isString) ? accepted : void 0;
 };
 /**
-* The whole encoded input, inline or from a file. The native parser decodes both,
-* so an invalid value is rendered with the command's help wherever it came from.
+* The native flag or argument parsing one field's encoded JSON value: a string or boolean
+* for those, a choice for string literals and string enums, and JSON or text for anything
+* else, numbers included. A template literal is a string; the action's schema checks its
+* pattern. A suspended type is read as the type it stands for. JSON or text, a flag's or an
+* argument's, is shown as `value`, not as the string it is parsed from.
 */
-const inputFlags = (codec) => ({
-	input: Flag.String("input").pipe(Flag.withSchema(Schema.fromJsonString(codec)), Flag.optional, Flag.withDescription("Whole canonical action input as JSON")),
-	inputFile: Flag.FileSchema("input-file", codec, { format: "json" }).pipe(Flag.optional, Flag.withDescription("File containing the whole canonical action input as JSON"))
-});
-const defaultCommand = (action, execute, options) => {
+const valueParam = (kind, name, field) => {
+	const encoded = unsuspended(field);
+	const literals = choices(encoded);
+	if (literals !== void 0) return Param.Literals(kind, name, literals);
+	if (SchemaAST.isString(encoded) || SchemaAST.isTemplateLiteral(encoded)) return Param.String(kind, name);
+	if (SchemaAST.isBoolean(encoded)) return Param.Boolean(kind, name);
+	return Param.String(kind, name).pipe(Param.withSchema(jsonOrText(encoded)), Param.withMetavar("value"));
+};
+/**
+* An optional field's value without the absence `Schema.optional` adds to it: `undefined`
+* declared, `null` encoded. Omitting the flag already leaves the field out, so
+* `optional(Schema.String)` takes a plain string.
+*/
+const present = (ast) => {
+	const members = SchemaAST.isUnion(ast) ? ast.types.filter((member) => !SchemaAST.isNull(member) && !SchemaAST.isUndefined(member)) : [];
+	return members.length === 1 && members[0] !== void 0 ? members[0] : ast;
+};
+/**
+* Whether `Schema.optional` added the field's JSON `null`: encoded without the JSON codec,
+* its value admits `undefined` but not `null`. A `null` of the field's own schema, as
+* `NullOr` or `OptionFromNullOr` encode, stays.
+*/
+const addsNull = (plain) => {
+	const types = members(plain);
+	return types.some(SchemaAST.isUndefined) && !types.some(SchemaAST.isNull);
+};
+/**
+* The element of an encoded array a flag repeats, and how many times it must: an array of
+* strings or numbers, choices included, whose fixed first elements, if any, are its rest's,
+* as `Schema.NonEmptyArray` writes one. `undefined` for any other array, which takes JSON.
+*/
+const repeated = (ast) => {
+	const encoded = unsuspended(ast);
+	if (!SchemaAST.isArrays(encoded)) return void 0;
+	const [element, ...after] = encoded.rest;
+	if (element === void 0 || after.length > 0 || !encoded.elements.every((first) => first === element) || !kindsOf(element).every((kind) => kind === "string" || kind === "number")) return;
+	return {
+		element,
+		min: encoded.elements.length
+	};
+};
+/** The occurrence of a repeated flag that adds no element, so `--tag '[]'` alone is `[]`. */
+const empty = "[]";
+/**
+* A field's flag or argument, `None` when omitted, from its JSON encoding and its plain one.
+* A required field's is required, so the parser reports it missing; a required boolean flag
+* is a switch instead: omitted, it is `false`, as a switch reads. A boolean argument takes
+* `true` or `false`. A flag or argument of an array of strings or numbers is repeated, one
+* element per occurrence but `[]`, which adds none, and a choice among the element's: none
+* is `[]`, or leaves an optional field out, which `[]` gives instead.
+*/
+const fieldParam = (kind, name, encoded, plain) => {
+	const optional = SchemaAST.isOptional(encoded);
+	const value = optional && plain !== void 0 && addsNull(plain) ? present(encoded) : encoded;
+	const repeats = repeated(value);
+	if (repeats !== void 0) {
+		const literals = choices(unsuspended(repeats.element));
+		const elements = literals === void 0 ? valueParam(kind, name, repeats.element) : Param.Literals(kind, name, [...literals, empty]);
+		const listed = (values) => Option.some(values.filter((value) => value !== empty));
+		return {
+			param: optional ? Param.variadic(elements).pipe(Param.map((values) => values.length === 0 ? Option.none() : listed(values))) : Param.variadic(elements, { min: repeats.min }).pipe(Param.map(listed)),
+			repeats: true
+		};
+	}
+	if (optional) return {
+		param: Param.optional(valueParam(kind, name, value)),
+		repeats: false
+	};
+	return {
+		param: kind === Param.flagKind && SchemaAST.isBoolean(unsuspended(encoded)) ? Flag.Boolean(name).pipe(Flag.withDefault(false), Flag.map(Option.some)) : valueParam(kind, name, encoded).pipe(Param.map(Option.some)),
+		repeats: false
+	};
+};
+/**
+* The fields of a struct, or of a class, which declares them as its one type parameter, by name.
+*/
+const fieldsOf = (ast) => {
+	const fields = SchemaAST.isDeclaration(ast) ? ast.typeParameters[0] : ast;
+	return new Map(fields !== void 0 && SchemaAST.isObjects(fields) ? fields.propertySignatures.map((property) => [property.name, property.type]) : []);
+};
+/** A struct, or a class's, transformed as a whole, as `Schema.encodeKeys` transforms one. */
+const transformedWhole = (ast) => (SchemaAST.isDeclaration(ast) ? ast.typeParameters[0] : ast)?.encoding !== void 0;
+/** A field's description: its own, or the first a suspension it stands for has. */
+const descriptionOf = (ast) => SchemaAST.resolveDescription(ast) ?? (SchemaAST.isSuspend(ast) ? descriptionOf(ast.thunk()) : void 0);
+/**
+* One flag or argument per top-level field of a struct input, named after the field in
+* kebab case, parsed as its encoded value and described by its declared schema: an
+* argument for a field listed in `positional`, a flag otherwise. A field required once
+* encoded is required; the action's schema still decodes what they parse.
+*/
+const fieldParams = (encoded, input, positional, aliases) => {
+	const plain = fieldsOf(SchemaAST.toEncoded(input));
+	const described = fieldsOf(transformedWhole(input) ? encoded : SchemaAST.toType(input));
+	return encoded.propertySignatures.map((property) => {
+		const field = String(property.name);
+		const declaredField = described.get(property.name);
+		const kind = positional.includes(field) ? Param.argumentKind : Param.flagKind;
+		const { param, repeats } = fieldParam(kind, kebab(field), property.type, plain.get(property.name));
+		const alias = kind === Param.flagKind ? aliases[field] : void 0;
+		const aliased = alias === void 0 ? param : Param.withAlias(param, alias);
+		const documented = declaredField ?? property.type;
+		const description = descriptionOf(documented) ?? descriptionOf(present(documented));
+		return {
+			field,
+			param: description === void 0 ? aliased : Param.withDescription(aliased, description),
+			optional: SchemaAST.isOptional(property.type),
+			repeats
+		};
+	});
+};
+/**
+* The positional fields in order, checked against the fields there are: each one a field,
+* listed once, and every required one before any optional one, as a parser reads them.
+*/
+const positionalOrder = (params, positional) => {
+	assertDistinct("positional argument", positional, (field) => field);
+	const ordered = positional.map((field) => {
+		const found = params.find((param) => param.field === field);
+		if (found === void 0) throw new Error(`Not an input field: ${field}`);
+		return found;
+	});
+	const firstOptional = ordered.findIndex((param) => param.optional);
+	const misplaced = ordered.slice(firstOptional === -1 ? ordered.length : firstOptional).find((param) => !param.optional);
+	if (misplaced !== void 0) throw new Error(`Required positional argument after an optional one: ${misplaced.field}`);
+	const greedy = ordered.slice(0, -1).find((param) => param.repeats);
+	if (greedy !== void 0) throw new Error(`Repeated positional argument before another one: ${greedy.field}`);
+	return ordered;
+};
+/**
+* `--input`, the whole encoded input as JSON, or text, for an input that is not a struct of
+* fields. It is never required: left off, it is `{}`, which the action's schema decodes
+* when the command runs, never when it is built.
+*/
+const inputFlag = (encoded) => Flag.String("input").pipe(Flag.withSchema(jsonOrText(encoded)), Flag.withDescription("Whole action input as JSON; omitted, {}"), Flag.optional);
+/**
+* What a success prints on stdout: its JSON, or `render`'s text. It is validated and encoded
+* first, so human output cannot conceal an invalid success, which is a defect, as on a server.
+* An action that returns nothing prints nothing, rather than its encoding, `null`.
+*/
+const output = (action, value, render) => Effect.map(Effect.orDie(Schema.encodeEffect(Schema.toCodecJson(action.success))(value)), (encoded) => render === void 0 && SchemaAST.isVoid(action.success.ast) ? Option.none() : Option.some(render === void 0 ? JSON.stringify(encoded, null, 2) : render(value)));
+/**
+* What a command fails with when its action fails: Effect CLI's own error for a handler's
+* failure, which `Command.run` prints on stderr and marks reported, so `runMain` does not
+* print it again. Its `cause` is the action's failure. The process exits with the cause's
+* `Runtime.errorExitCode`, 1 by default.
+*/
+var UserError = class extends CliError.UserError {
+	/**
+	* The action's failure, as Effect names an error's nested one, so the native
+	* `Effect.catchReason("UserError", "UserNotFound", f)` and `catchReasons` match it by tag.
+	*/
+	get reason() {
+		return this.cause;
+	}
+	get [Runtime.errorExitCode]() {
+		return Runtime.getErrorExitCode(this.cause);
+	}
+};
+/** `error`'s own `_tag` or `message`, when it is a string. */
+const text = (error, key) => {
+	if (!Predicate.hasProperty(error, key)) return void 0;
+	const value = error[key];
+	return Predicate.isString(value) ? value : void 0;
+};
+/**
+* A failure no projected schema encodes, without a stack: its tag or an error's name, and
+* its message, or the failure itself when it is a string, then each cause's, so a transport
+* error keeps the refused connection beneath it, up to one already described, as a cycle
+* repeats it. Its other fields are left out, a plain object's `name` too: no schema says
+* they are safe to show, and a builder's failure may hold a connection string.
+*/
+const described = (error, seen = /* @__PURE__ */ new Set()) => {
+	const name = text(error, "_tag") ?? (error instanceof Error ? error.name : "Error");
+	const message = Predicate.isString(error) ? error : text(error, "message") ?? "";
+	const named = message === "" ? name : `${name}: ${message}`;
+	seen.add(error);
+	return Predicate.hasProperty(error, "cause") && error.cause !== void 0 && !seen.has(error.cause) ? `${named}: ${described(error.cause, seen)}` : named;
+};
+/**
+* The `UserError` of each failure of `action`, its message the JSON HTTP sends for it: encoded
+* by the first schema that takes it among the built-in errors, the action's and the
+* surface's own `errors`, as an Effect, as HTTP encodes it. A failure none takes, such as a
+* builder's or the transport's, is described instead.
+*/
+const failureOf = (action, errors) => {
+	const encode = Schema.encodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Union(projectedErrors(action, errors)))));
+	return (error) => encode(error).pipe(Effect.orElseSucceed(() => described(error)), Effect.flatMap((userMessage) => Effect.fail(new UserError({
+		cause: error,
+		userMessage
+	}))));
+};
+/**
+* The action's input as native flags: one per field of a struct input, named after it,
+* or `--input` taking the whole input as JSON otherwise. The `positional` fields of a
+* struct are arguments instead, in that order.
+*/
+const inputConfig = (action, positional, aliases) => {
 	const codec = Schema.toCodecJson(action.input);
-	return make(action, execute, options, inputFlags(codec), (parsed) => Option.match(Option.orElse(parsed.inputFile, () => parsed.input), {
-		onNone: () => Schema.decodeUnknownEffect(codec)({}),
-		onSome: Effect.succeed
-	}));
+	const encoded = unsuspended(SchemaAST.toEncoded(codec.ast));
+	const decode = Schema.decodeUnknownEffect(codec, { onExcessProperty: "error" });
+	if (SchemaAST.isObjects(encoded) && encoded.indexSignatures.every((signature) => SchemaAST.isNever(signature.type))) {
+		const params = fieldParams(encoded, unsuspended(action.input.ast), positional, aliases);
+		const flagged = new Set(params.map(({ field }) => field).filter((field) => !positional.includes(field)));
+		const stray = Object.keys(aliases).find((field) => !flagged.has(field));
+		if (stray !== void 0) throw new Error(`Not a flag's input field: ${stray}`);
+		return {
+			flags: Object.fromEntries(params.flatMap(({ field, param }) => positional.includes(field) ? [] : [[field, param]])),
+			positional: positionalOrder(params, positional),
+			decode: (parsed) => decode(Record.getSomes(parsed))
+		};
+	}
+	if (positional.length > 0) throw new Error(`Positional arguments need named input fields: ${positional.join(", ")}`);
+	if (Object.keys(aliases).length > 0) throw new Error(`Aliases need named input fields: ${Object.keys(aliases).join(", ")}`);
+	return {
+		flags: { input: inputFlag(encoded) },
+		positional: [],
+		decode: (parsed) => decode(Option.getOrElse(parsed["input"] ?? Option.none(), () => ({})))
+	};
 };
-const parametersCommand = (action, execute, options) => make(action, execute, options, options.parameters, (parsed) => Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))(options.input(parsed)));
-/** Build one native command around an action-bound operation. */
-const command = (action, execute, options) => {
-	if (isParametersOptions(options)) return parametersCommand(action, execute, options);
-	return defaultCommand(action, execute, options);
+/**
+* One native command around an action-bound operation, its flags and positional
+* arguments derived from the action's input. A field's flag shadows a global flag of the
+* same name; two flags of the command itself with one name are refused when it is built.
+* Input that does not decode is `InvalidInput`, as over HTTP, and the operation writes its
+* logs and console output to stderr, since stdout carries the result. Every failure is a
+* `UserError`, encoded with the surface's `errors` too, such as a binding's.
+*/
+const command = (action, execute, options, errors = []) => {
+	const name = options?.name ?? kebab(action.name);
+	const render = options?.render;
+	const { flags, positional, decode } = inputConfig(action, options?.positional ?? [], options?.aliases ?? {});
+	const failure = failureOf(action, errors);
+	assertDistinct("flag", [
+		...Object.keys(flags).map((field) => [`--${kebab(field)}`, `field ${field}`]),
+		...render === void 0 ? [] : [["--json", "render's --json"]],
+		...Object.entries(options?.aliases ?? {}).flatMap(([field, alias]) => Predicate.isString(alias) ? [[`--${alias.replace(/^-+/, "")}`, `alias of field ${field}`]] : [])
+	], ([flag]) => flag, ([, claimant]) => claimant);
+	const args = positional.map(({ param }) => param);
+	const parsedFields = (input, values) => ({
+		...input,
+		...Object.fromEntries(positional.map(({ field }, index) => [field, values[index] ?? Option.none()]))
+	});
+	const run = (parsed, rendered) => decode(parsed).pipe(Effect.mapError(InvalidInput.fromSchemaError), Effect.flatMap(execute), Effect.catch(failure), Effect.flatMap((value) => output(action, value, rendered)), logToStderr, Effect.flatMap(Option.match({
+		onNone: () => Effect.void,
+		onSome: Console.log
+	})));
+	return (render === void 0 ? Command.make(name, {
+		input: flags,
+		args
+	}, ({ input, args: values }) => run(parsedFields(input, values), void 0)) : Command.make(name, {
+		input: flags,
+		args,
+		json: jsonFlag
+	}, ({ input, args: values, json }) => run(parsedFields(input, values), json ? void 0 : render))).pipe(Command.withDescription(action.description));
 };
 //#endregion
-export { command };
+export { UserError, command, kebab };

package/dist/internal/client.d.mts

@@ -0,0 +1,43 @@
+import { BuiltIns } from "./errors.mjs";
+import "./implementation.mjs";
+import { Call } from "./call.mjs";
+import { Action_d_exports, Any, Errors } from "../Action.mjs";
+import { Any as Any$1, VerifierError } from "./authentication.mjs";
+import { Effect, Schema } from "effect";
+import { HttpClient, HttpClientError } from "effect/http";
+import { HttpApi, HttpApiClient } from "effect/http-api";
+//#region src/internal/client.d.ts
+/**
+ * The native `HttpApiClient.make` options except `transformResponse`: `baseUrl` and
+ * `transformClient`. `transformResponse` may change a call's success, failure or
+ * services, which the method types cannot follow.
+ */
+export type Options = Omit<NonNullable<Parameters<typeof HttpApiClient.make>[1]>, "transformResponse">;
+/** An error schema the binding declares on every endpoint. */
+type BindingError = Errors[number];
+/**
+ * What one call of `A` fails with: a declared error value (the action's own, one `E` of the
+ * binding's, or a built-in `InvalidInput`, `Unauthenticated` or `Forbidden`), a native
+ * `HttpClientError` for a failed request or an undeclared answer, or a `SchemaError` when
+ * the success does not decode. Input that does not encode is `InvalidInput`, and nothing is sent.
+ */
+export type MethodError<A extends Any, E extends BindingError = never> = A["error"][number]["Type"] | E["Type"] | BuiltIns["Type"] | HttpClientError.HttpClientError | Schema.SchemaError;
+/** One action as an Effect of its decoded success, failing with `MethodError`. */
+type Method<A extends Any, E extends BindingError> = Call<A, Effect.Effect<A["success"]["Type"], MethodError<A, E>>>;
+/**
+ * Any HTTP binding. The API is a native constraint here because native groups are
+ * invariant in their endpoints; `actions` carries the types.
+ */
+export interface AnyHttp {
+  readonly authentication?: Any$1 | undefined;
+  readonly actions: ReadonlyArray<Any>;
+  readonly error: ReadonlyArray<BindingError>;
+  readonly prefix: `/${string}`;
+  readonly api: HttpApi.Constraint;
+}
+/**
+ * Every action of the binding `H`, as `client.<action>(input)`: a protected one may also fail
+ * with what its descriptor's verifier declares.
+ */
+export type Client<H extends AnyHttp> = { readonly [A in H["actions"][number] as A["name"]]: Method<A, H["error"][number] | VerifierError<A, H["authentication"]>>; };
+//#endregion

package/dist/internal/client.mjs

@@ -0,0 +1,25 @@
+import { InvalidInput } from "./errors.mjs";
+import { inputOf } from "./call.mjs";
+import { Effect, Schema } from "effect";
+import { HttpApiClient } from "effect/http-api";
+//#region src/internal/client.ts
+/** Refuse an action a binding of `actions` does not hold, matched by identity. */
+const assertInBinding = (actions, action) => {
+	if (!actions.includes(action)) throw new Error(`Action "${action.name}" is not in this HTTP binding`);
+};
+/**
+* Build the native client of a binding once and look up each action's method, taking the
+* action's input directly. Every binding API is a native `HttpApi` of one top-level
+* group built from `http.actions`, so each action has a native method of its name.
+*/
+const methods = (http, options = {}) => Effect.map(HttpApiClient.make(http.api, options), (client) => {
+	const native = client;
+	return (action) => {
+		const method = native[action.name];
+		if (method === void 0) throw new Error(`No client method for ${action.name}`);
+		const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(action.input), { errors: "all" });
+		return (...args) => inputOf(action, args).pipe(Effect.tap(encode), Effect.mapError(InvalidInput.fromSchemaError), Effect.flatMap((payload) => method({ payload })));
+	};
+});
+//#endregion
+export { assertInBinding, methods };

package/dist/internal/console.mjs

@@ -0,0 +1,77 @@
+import { Clock, Console, Effect, Function, Predicate } from "effect";
+//#region src/internal/console.ts
+/**
+* The console of code whose program's stdout carries data: a stdio server's protocol, or a
+* CLI command's result. Every method writes through `console.error` alone, so every console
+* logger, `Console.log` and the default logger alike, leaves stdout intact, and so do
+* counters, timers and group labels, which Node's console prints on stdout. A counter or a
+* timer prints its label as given, never as a format, then its count or the milliseconds
+* since it started, read on `clock` and rounded to three decimals; a group prints its label
+* without indenting what follows, and `clear` clears nothing.
+*/
+const stderrConsole = (console, clock) => {
+	const counts = /* @__PURE__ */ new Map();
+	const timers = /* @__PURE__ */ new Map();
+	const write = (...args) => console.error(...args);
+	const elapsed = (label, data) => {
+		const start = timers.get(label);
+		if (start !== void 0) {
+			const millis = Number(clock.monotonicTimeNanosUnsafe() - start) / 1e6;
+			write("%s: %sms", label, Number(millis.toFixed(3)), ...data);
+		}
+	};
+	const labeled = (label, args) => {
+		const [first, ...rest] = args;
+		write(...Predicate.isString(first) ? [`${label}: ${first}`, ...rest] : [label, ...args]);
+	};
+	const group = (...label) => {
+		if (label.some((part) => part !== void 0)) write(...label);
+	};
+	return {
+		assert: (condition, ...args) => {
+			if (!condition) labeled("Assertion failed", args);
+		},
+		clear: Function.constVoid,
+		count: (label = "default") => {
+			const count = (counts.get(label) ?? 0) + 1;
+			counts.set(label, count);
+			write("%s: %d", label, count);
+		},
+		countReset: (label = "default") => {
+			counts.delete(label);
+		},
+		debug: write,
+		dir: (item) => write("%O", item),
+		dirxml: write,
+		error: write,
+		group,
+		groupCollapsed: group,
+		groupEnd: Function.constVoid,
+		info: write,
+		log: write,
+		table: (data) => write(data),
+		time: (label = "default") => {
+			timers.set(label, clock.monotonicTimeNanosUnsafe());
+		},
+		timeEnd: (label = "default") => {
+			elapsed(label, []);
+			timers.delete(label);
+		},
+		timeLog: (label = "default", ...data) => elapsed(label, data),
+		trace: (...args) => {
+			const { stack = "" } = /* @__PURE__ */ new Error();
+			const frames = stack.split("\n").slice(2).join("\n");
+			labeled("Trace", args);
+			if (frames !== "") write(frames);
+		},
+		warn: write
+	};
+};
+/**
+* `effect` writing its console output and Effect logs to stderr alone, through the console
+* it runs with: for what a surface runs where stdout carries data, a stdio server's program
+* or a CLI command's builder, authorizer and handler.
+*/
+const logToStderr = (effect) => Effect.provideServiceEffect(effect, Console.Console, Effect.zipWith(Effect.service(Console.Console), Effect.service(Clock.Clock), stderrConsole));
+//#endregion
+export { logToStderr };

package/dist/internal/declared.d.mts

@@ -0,0 +1,13 @@
+import { Action_d_exports, Errors } from "../Action.mjs";
+import { HttpServerResponse } from "effect/http";
+//#region src/internal/declared.d.ts
+/** The list an `error` option of type `G` stands for: one schema is a list of one. */
+type ListOf<G> = G extends Errors ? G : readonly [G];
+/**
+ * The errors options `O` declare, as at run time: those `error` always gives, or, where it may
+ * be absent, those it gives or none, so clients decode each that may arrive.
+ */
+export type ErrorsOf<O> = O extends unknown ? "error" extends keyof O ? O extends {
+  readonly error: infer G extends Errors | Errors[number];
+} ? ListOf<G> : ListOf<Extract<O["error" & keyof O], Errors | Errors[number]>> | [] : [] : never;
+//#endregion

package/dist/internal/declared.mjs

@@ -0,0 +1,34 @@
+import { unsuspended } from "./actions.mjs";
+import { Schema, SchemaAST } from "effect";
+import { HttpServerResponse } from "effect/http";
+import { HttpApiSchema } from "effect/http-api";
+//#region src/internal/declared.ts
+/** The status an error schema states, as `HttpApi` reads it. */
+const statusOf = SchemaAST.resolveAt("httpApiStatus");
+/** The status a schema states, or the first one a suspension it wraps states. */
+const statusThrough = (ast) => statusOf(ast) ?? (SchemaAST.isSuspend(ast) ? statusThrough(ast.thunk()) : void 0);
+/**
+* The schemas an endpoint declares for one error, each with the status it is sent with. `HttpApi`
+* reads a status off each declared schema, never off a union's members nor through a suspension, so
+* a plain union without a status of its own declares each member, and a suspended error, as a
+* recursive one is written, without a status of its own states the status of what it suspends. An
+* error without a status is an outcome the action expects, not a server fault: it is sent as 422,
+* rather than `HttpApi`'s 500, which clients and proxies read as the server failing.
+*/
+const declared = (error) => {
+	const status = statusThrough(error.ast);
+	if (status !== void 0) return [statusOf(error.ast) === void 0 ? HttpApiSchema.status(status)(error) : error];
+	const resolved = unsuspended(error.ast);
+	if (SchemaAST.isUnion(resolved) && resolved.checks === void 0 && resolved.encoding === void 0) return resolved.types.flatMap((member) => declared(Schema.make(member)));
+	return [HttpApiSchema.status(422)(error)];
+};
+/**
+* `error` as an endpoint declaring `errors` sends it: its JSON, encoded by the first declared
+* schema that accepts it, with that schema's status. None for a value no schema accepts.
+*/
+const declaredResponse = (errors, error) => {
+	const schema = errors.flatMap(declared).find((each) => Schema.is(each)(error));
+	return schema === void 0 ? void 0 : HttpServerResponse.jsonUnsafe(Schema.encodeUnknownSync(Schema.toCodecJson(schema))(error), { status: statusOf(schema.ast) ?? 422 });
+};
+//#endregion
+export { declared, declaredResponse };

package/dist/internal/errors.d.mts

@@ -0,0 +1,77 @@
+import { Schema } from "effect";
+//#region src/internal/errors.d.ts
+/**
+ * One thing wrong with an input: where, as the keys and indexes leading to it from the input's
+ * root, none for the input itself, and what the schema expects there.
+ */
+declare const Issue: Schema.Struct<{
+  readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
+  readonly message: Schema.String;
+}>;
+/** One thing wrong with an input, as `InvalidInput.issues` lists it. */
+type Issue = (typeof Issue)["Type"];
+declare const InvalidInput_base: Schema.Class<InvalidInput, Schema.TaggedStruct<"InvalidInput", {
+  readonly message: Schema.withConstructorDefault<Schema.String>;
+  readonly issues: Schema.withConstructorDefault<Schema.$Array<Schema.Struct<{
+    readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
+    readonly message: Schema.String;
+  }>>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The request's input does not decode against the action's input. HTTP answers every such
+ * request with it, its message the schema's own description of what is wrong, and `issues`
+ * the same description an issue at a time, for a caller that points at a field. A handler
+ * failing with it for input that decodes but cannot be served may name its own.
+ */
+export declare class InvalidInput extends InvalidInput_base {
+  private readonly "~builtIn";
+  /**
+   * The `InvalidInput` for input that did not decode, as every surface answers it: the
+   * schema's message, and each of its issues by path, for code that decodes input of its own,
+   * such as a header or a route parameter. Neither carries a value of the input: decoding
+   * runs without `reportInput`, so no issue holds one to format. A symbol key is sent as its
+   * string form, `Symbol(name)`, as JSON has no symbols, which tells it from a string key of
+   * that name.
+   */
+  static readonly fromSchemaError: ({ issue, message }: Schema.SchemaError) => InvalidInput;
+}
+declare const Unauthenticated_base: Schema.Class<Unauthenticated, Schema.TaggedStruct<"Unauthenticated", {
+  readonly message: Schema.withConstructorDefault<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/** The caller is not authenticated: authentication or an implementation's `authorize` refuses. */
+export declare class Unauthenticated extends Unauthenticated_base {
+  private readonly "~builtIn";
+}
+declare const Forbidden_base: Schema.Class<Forbidden, Schema.TaggedStruct<"Forbidden", {
+  readonly message: Schema.withConstructorDefault<Schema.String>;
+  readonly scopes: Schema.optionalKey<Schema.NonEmptyArray<Schema.String>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The caller may not run this action: an implementation's `authorize` refuses. `scopes`,
+ * when given, are every OAuth scope the call needs: a refusal naming them is answered with
+ * the `insufficient_scope` challenge an OAuth client re-authorizes on.
+ */
+export declare class Forbidden extends Forbidden_base {
+  private readonly "~builtIn";
+}
+/**
+ * What authentication or an implementation's `authorize` refuses a caller with, instead of
+ * running a handler. An error an action declares, such as a rate limit, is not a refusal. As a
+ * schema, it tells a refusal apart: `Schema.is(Action.Refusal)(error)`.
+ */
+export declare const Refusal: Schema.Union<readonly [typeof Unauthenticated, typeof Forbidden]>;
+/** A refusal: `Unauthenticated | Forbidden`. */
+export type Refusal = (typeof Refusal)["Type"];
+/**
+ * The failures every endpoint and tool declares beyond its action's own, and any handler may
+ * fail with: bad input, and every refusal. No action or binding declares them itself.
+ */
+export declare const builtIns: readonly [typeof InvalidInput, typeof Unauthenticated, typeof Forbidden];
+/** The built-in failures' schemas. */
+export type BuiltIns = (typeof builtIns)[number];
+/** The built-in failures as one schema: `Schema.is(Action.BuiltIn)(error)`. */
+export declare const BuiltIn: Schema.Union<readonly [typeof InvalidInput, typeof Unauthenticated, typeof Forbidden]>;
+/** A built-in failure: `InvalidInput | Refusal`. */
+export type BuiltIn = (typeof BuiltIn)["Type"];
+//#endregion
+export { Issue };