@gjermundgaraba/effect-actions 0.18.2 → 0.19.0

package/dist/contract/names.mjs

@@ -1,25 +1,27 @@
 //#region src/contract/names.ts
-const validName = /^[A-Za-z0-9_-]{1,128}$/;
-const assertName = (what, name) => {
-	if (!validName.test(name) || name === "then") throw new Error(`Invalid ${what}: ${name}`);
+const namePattern = "[A-Za-z0-9_-]{1,128}";
+const validName = new RegExp(`^${namePattern}$`);
+const assertName = (name) => {
+	if (!validName.test(name) || name === "then") throw new Error(`Invalid action name: ${name} (use ${namePattern}, other than "then")`);
 };
-const assertDistinct = (what, items, nameOf, claimantOf = nameOf) => {
+const assertDistinct = (what, items, nameOf, { claimantOf = nameOf, labelOf = nameOf, fix }) => {
 	const seen = /* @__PURE__ */ new Map();
 	for (const item of items) {
 		const name = nameOf(item);
-		const claimant = claimantOf(item);
 		const other = seen.get(name);
 		if (other !== void 0) {
-			const by = other === claimant ? "" : `, claimed by ${other} and ${claimant}`;
-			throw new Error(`Duplicate ${what}: ${name}${by}`);
+			const claimants = [claimantOf(other), claimantOf(item)];
+			const by = claimants[0] === claimants[1] ? "" : `, claimed by ${claimants.join(" and ")}`;
+			throw new Error(`Duplicate ${what}: ${labelOf(other)}${by} (${fix})`);
 		}
-		seen.set(name, claimant);
+		seen.set(name, item);
 	}
 };
-const assertOnce = (what, actions) => assertDistinct(what, actions, (action) => action.name);
-const assertKnown = (what, keys, names) => {
+const heldOnce = "pass one implementation of it, or rename one";
+const assertOnce = (what, actions, fix = "list it once, or rename one") => assertDistinct(what, actions, (action) => action.name, { fix });
+const assertKnown = (what, keys, names, fix) => {
 	const unknown = keys.filter((key) => !names.includes(key));
-	if (unknown.length > 0) throw new Error(`Unknown ${what}: ${unknown.join(", ")}`);
+	if (unknown.length > 0) throw new Error(`Unknown ${what}: ${unknown.join(", ")} (${fix})`);
 };
 //#endregion
-export { assertDistinct, assertKnown, assertName, assertOnce };
+export { assertDistinct, assertKnown, assertName, assertOnce, heldOnce };

package/dist/contract/status.mjs

@@ -1,18 +1,11 @@
-import { unsuspended } from "./ast.mjs";
-import { Schema, SchemaAST } from "effect";
+import { SchemaAST } from "effect";
 //#region src/contract/status.ts
 const httpApiStatusOf = SchemaAST.resolveAt("httpApiStatus");
 const statusThroughSuspensions = (ast) => httpApiStatusOf(ast) ?? (SchemaAST.isSuspend(ast) ? statusThroughSuspensions(ast.thunk()) : void 0);
-/**
-* `error` as an endpoint declares it: each member of a union without a status of its own apart,
-* each with its status, 422 without one.
-*/
+/** One error schema, from `errorSchemas`, as an endpoint declares it: with its status, 422 without one. */
 const declared = (error) => {
 	const status = statusThroughSuspensions(error.ast);
-	if (status !== void 0) return [httpApiStatusOf(error.ast) === void 0 ? error.annotate({ httpApiStatus: status }) : 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 [error.annotate({ httpApiStatus: 422 })];
+	return status === void 0 ? error.annotate({ httpApiStatus: 422 }) : httpApiStatusOf(error.ast) === void 0 ? error.annotate({ httpApiStatus: status }) : error;
 };
 //#endregion
 export { declared, httpApiStatusOf };

package/dist/http/client.d.mts

@@ -12,11 +12,22 @@ import { HttpApi, HttpApiClient } from "effect/http-api";
  * which may return a client failing with `E` or requiring `R` of its own, as
  * `HttpApiClient.makeWith` takes one.
  */
-export interface Options<E = HttpClientError.HttpClientError, R = never> extends Pick<NonNullable<Parameters<typeof HttpApiClient.make>[1]>, "baseUrl"> {
+export interface Options<E = HttpClientError.HttpClientError, R = never> {
+  /**
+   * What the routes resolve against: `https://api.example.com`. Omitted: relative routes, which
+   * a page resolves against its own origin.
+   *
+   * **Gotchas**
+   *
+   * - Outside a browser, set it: a relative route has no page to resolve against, and the call fails with an `HttpClientError` whose `reason._tag` is `InvalidUrlError`.
+   */
+  readonly baseUrl?: NonNullable<Parameters<typeof HttpApiClient.make>[1]>["baseUrl"];
   /**
    * Wraps the native `HttpClient` the calls send with: a bearer token is
-   * `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`. A method also fails with what
-   * the returned client fails with beyond an `HttpClientError`, and requires what it requires.
+   * `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`, and a credential read or
+   * refreshed as each request is sent `(client) => HttpClient.mapRequestEffect(client, authorize)`.
+   * A method also fails with what the returned client fails with beyond an `HttpClientError`, as
+   * it is, and requires what it requires.
    */
   readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient.With<E, R>) | undefined;
 }
@@ -25,7 +36,7 @@ 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.
+ * the success does not decode.
  */
 export type MethodError<A extends Any, E extends BindingError = never> = A["error"][number]["Type"] | E["Type"] | BuiltIns["Type"] | HttpClientError.HttpClientError | Schema.SchemaError;
 type Method<A extends Any, E extends BindingError, CE, CR> = Call<A, Effect.Effect<A["success"]["Type"], MethodError<A, E> | CE, CR>>;

package/dist/http/client.mjs

@@ -10,7 +10,7 @@ const methodsWith = (http, httpClient, baseUrl) => Effect.map(HttpApiClient.make
 	const native = client;
 	return Object.fromEntries(http.actions.map((action) => {
 		const method = native[action.name];
-		if (method === void 0) throw new Error(`No client method for ${action.name}`);
+		if (method === void 0) throw new Error(`No client method for ${action.name} (use the binding \`ActionHttp.make\` returned, whose group holds this action)`);
 		return [action.name, checked(action, (payload) => method({ payload }))];
 	}));
 });

package/dist/mcp/client.d.mts

@@ -23,7 +23,8 @@ export interface Params {
 export interface ClientOptions<D extends Any$1 | undefined = Any$1 | undefined, E = HttpClientError.HttpClientError, R = never> {
   /**
    * The endpoint, resolved by the `HttpClient`: relative under `Testing.layer`. Defaults to `/mcp`,
-   * the default `layerHttp` path.
+   * the default `layerHttp` path, so a call to an endpoint on another `path` fails with an
+   * `McpCallError` that `answered 404`.
    */
   readonly url?: string;
   /**
@@ -34,7 +35,8 @@ export interface ClientOptions<D extends Any$1 | undefined = Any$1 | undefined,
   /**
    * The endpoint's descriptor, as `layerHttp` takes it: an error its verifier declares, the
    * endpoint's HTTP answer for a protected tool, is then that error's decoded value, as over
-   * `ActionHttp.client`.
+   * `ActionHttp.client`; without it, the call fails with an `McpCallError` whose `reason` is a
+   * `StatusError`.
    */
   readonly authentication?: D;
 }
@@ -46,6 +48,10 @@ export interface RequestOptions {
    * one.
    */
   readonly url?: string;
+  /**
+   * Headers sent beside the routing ones `request` fills in, such as `Authorization`; a routing
+   * header wins over a given one of its name.
+   */
   readonly headers?: Headers.Input;
 }
 declare const StatusError_base: Schema.Class<StatusError, Schema.TaggedStruct<"StatusError", {
@@ -59,8 +65,7 @@ declare const ProtocolError_base: Schema.Class<ProtocolError, Schema.TaggedStruc
   readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /**
- * The endpoint answered with a JSON-RPC error, such as the native server's for invalid arguments
- * or an unknown tool.
+ * The endpoint answered with a JSON-RPC error, such as the native server's for an unknown tool.
  */
 declare class ProtocolError extends ProtocolError_base {}
 declare const NoReply_base: Schema.Class<NoReply, Schema.TaggedStruct<"NoReply", {
@@ -89,6 +94,10 @@ declare const McpCallError_base: Schema.Class<McpCallError, Schema.TaggedStruct<
  * `Effect.catchReason("McpCallError", "StatusError", ...)`. `message` names the tool and the
  * reason. Structured content that does not decode as the success is a `SchemaError` instead,
  * and a request that fails an `HttpClientError`.
+ *
+ * **Gotchas**
+ *
+ * - `returned an error: Invalid parameters for tool …`, an `UndeclaredError`, from a call its types allowed: the endpoint serves another contract under that name; give `client` the served contract value.
  */
 export declare class McpCallError extends McpCallError_base {}
 type CallError<A extends Any, D> = A["error"][number]["Type"] | VerifierError<A, D>["Type"] | BuiltIn | Schema.SchemaError | HttpClientError.HttpClientError | McpCallError;
@@ -103,10 +112,14 @@ export type Client<Actions extends ReadonlyArray<Any>, D = undefined, E = never,
  * encoded with the action's schema, and the success decoded from its structured content, each
  * media field from the blocks whose `_meta` names it, and a success that is media, or whose
  * every field is, from its blocks alone. A declared error the tool returns, the action's own
- * or a refusal, is its decoded value, and so is a refusal the endpoint's authentication
- * answers with, or an error its verifier declares, given the `authentication`: a test telling a 401 or 403 from a tool result asserts the status of a request
- * `request` builds. The argument may be omitted when `{}` is a valid input. Requires the
- * native `HttpClient`, such as the one `Testing.layer` provides.
+ * or a refusal, is its decoded value, and so is a refusal the endpoint's authentication answers
+ * with: a test telling a 401 or 403 from a tool result asserts the status of a request `request`
+ * builds. The argument may be omitted when `{}` is a valid input. Requires the native
+ * `HttpClient`, such as the one `Testing.layer` provides.
+ *
+ * **Gotchas**
+ *
+ * - It drops undeclared input fields as it encodes, and fails with `InvalidInput`, sending nothing, for an input that does not encode.
  */
 export declare function client<const Actions extends ReadonlyArray<Any>, D extends Any$1 | undefined = undefined>(actions: Actions, options?: ClientOptions<D>): Effect.Effect<Client<Actions, D>, never, HttpClient.HttpClient>;
 export declare function client<const Actions extends ReadonlyArray<Any>, E, R, D extends Any$1 | undefined = undefined>(actions: Actions, options: ClientOptions<D, E, R>): Effect.Effect<Client<Actions, D, E, R>, never, HttpClient.HttpClient>;

package/dist/mcp/client.mjs

@@ -9,12 +9,7 @@ import { McpSchema } from "effect/ai";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import { Sse } from "effect/encoding";
 //#region src/mcp/client.ts
-/**
-* One stateless MCP request of `method` with `params`, as `layerHttp` serves it: the headers
-* routing it, which repeat what its body says, and its JSON-RPC body. The client metadata goes in
-* `_meta`, under any given, such as a `progressToken`; the protocol version is always the
-* request's own.
-*/
+/** The routing headers and JSON-RPC body of the request `request` builds. */
 const statelessRequest = (method, params) => {
 	const { protocolVersion } = httpProtocol;
 	const name = method === "resources/read" ? params.uri : params.name;
@@ -50,8 +45,7 @@ var StatusError = class extends Schema.TaggedError()("StatusError", {
 	body: Schema.String
 }) {};
 /**
-* The endpoint answered with a JSON-RPC error, such as the native server's for invalid arguments
-* or an unknown tool.
+* The endpoint answered with a JSON-RPC error, such as the native server's for an unknown tool.
 */
 var ProtocolError = class extends Schema.TaggedError()("ProtocolError", {
 	code: Schema.Finite,
@@ -83,6 +77,10 @@ const sentenceOf = Match.typeTags()({
 * `Effect.catchReason("McpCallError", "StatusError", ...)`. `message` names the tool and the
 * reason. Structured content that does not decode as the success is a `SchemaError` instead,
 * and a request that fails an `HttpClientError`.
+*
+* **Gotchas**
+*
+* - `returned an error: Invalid parameters for tool …`, an `UndeclaredError`, from a call its types allowed: the endpoint serves another contract under that name; give `client` the served contract value.
 */
 var McpCallError = class extends Schema.TaggedError()("McpCallError", {
 	tool: Schema.String,

package/docs/Action-failures.md

@@ -6,42 +6,33 @@ The tasks are in [Action.md](Action.md).
 ## At `make`
 
 - `Argument of type 'Struct<…>' is not assignable to parameter of type 'Fields'` at `Schema.Struct(X.input)`, or `Objects property names must be strings` or `Invalid value used as weak map key` thrown: an action's `input` is a schema already, a `Schema.Struct` where fields were given. Use it as it is: `Schema.Array(X.input)`.
-- `Invalid action name: <name>` thrown: an action's name matches `[A-Za-z0-9_-]{1,128}` and is not `then`. Rename the action.
 - `'readOnlyHint' does not exist in type 'Mcp'`, or `Type 'true' is not assignable to type 'never'` on `readOnlyHint` beside another hint: a tool's read-only hint is its action's `readOnly`. Set `readOnly` instead.
 - `'<key>' does not exist in type 'Options'`, or `in type 'Mcp'`, or `Type '...' is not assignable to type 'never'` on the key: `make` takes no such option or hint. The key may be misspelled, such as `destructive` for `destructiveHint`.
-- `Type 'H' is not assignable to type 'H & ...'`, or `… is not assignable to type 'ServiceCaller<…>'`, or `… is not assignable to type '[Extract<ErrorMembers<E>, …>] extends …'`, at `make` in a helper whose type parameter stands for `mcp`, `caller` or `error`, as in `<const H extends Action.Mcp>(mcp: H)`: `make` refuses options a type parameter stands for. Type the parameter concretely, `Action.Mcp` or `typeof CurrentUser`, or spread a constant object into the options.
-- A type error on `error`, `... is not assignable to type 'readonly never[]'` or naming the remaining errors, or `Action "<name>": error _tag "Forbidden" is built in, and declared on every surface` thrown: an action's `error` lists a built-in error, or one of your own that encodes with the `_tag` `InvalidInput`, `Unauthenticated` or `Forbidden`. Drop the built-in error, which a handler may fail with anyway; rename your own.
+- `Type 'H' is not assignable to type 'H & ...'` at `make` in a helper whose type parameter stands for `mcp`, as in `<const H extends Action.Mcp>(mcp: H)`: `make` cannot check the hints of a type parameter. Type the parameter `Action.Mcp`, or spread a constant object into the options.
 - `ReferenceError` thrown where a contract is defined: `make` reads every declared error's `_tag` when it is called, so an entry of `error` that is a `Schema.suspend` whose thunk reads a `const` declared further down fails at once. Declare the error before the action.
 
 ## At `implement`
 
-- `... is not assignable to type '"A protected action takes { authorize }: your rule, or Action.allowAll"'`, or `Protected actions require authorize, or Action.allowAll` thrown: an implementation holding a protected action states `authorize`. Pass `{ authorize }`, or `{ authorize: Action.allowAll }`.
-- `Missing authorize: pass an authorization function, or Action.allowAll` thrown, or a layer build dying with it: `authorize` is neither a function nor an Effect building one, or that Effect built something else.
 - `Type 'undefined' is not assignable to type 'Authorizer<...>'`: `authorize` is never `undefined`. Write `enabled ? authorize : Action.allowAll`.
 - `Parameter 'action' implicitly has an 'any' type`, or an `Effect.fn` authorizer whose `action` is `any`: an authorizer defined apart from `implement` annotates its parameter, `(action: Action.Any)`.
 - `Type 'X' is not assignable to type 'Forbidden | Unauthenticated'`, ending `Property '"~declared in the action's error, or built in"' is missing in type 'X'`: an authorizer fails only with `Action.Unauthenticated` or `Action.Forbidden`, and this one fails with `X`. A limit, or another failure callers should see, is the handler's: declare `X` in the action's `error` and fail with it there.
-- `Argument of type ... is not assignable to parameter of type ...`, or `Type 'Effect<...>' is not assignable to type 'Effect<...>'` at a handler of a record written in place, ending `Property '"~declared in the action's error, or built in"' is missing in type 'X'`, under `Type 'X' is not assignable to type 'Forbidden | InvalidInput | Unauthenticated'` or a longer union: a handler fails only with the errors its action declares and the library's built-in ones, and this one fails with `X`, which may be Effect's `HttpApiError.Forbidden` or a `Forbidden` of your own. Add `X` to the action's `error`, or handle it. A builder's error is reported at the builder and names one handler, in `The types returned by '<handler>(...)'`: the next shows once that one is fixed.
+- `Argument of type ... is not assignable to parameter of type ...`, or `Type 'Effect<...>' is not assignable to type 'Effect<...>'` at a handler of a record written in place, ending `Property '"~declared in the action's error, or built in"' is missing in type 'X'`: the handler fails with `X`, which its action does not declare. Add `X` to the action's `error`, or handle it.
+- `Type 'X' is not assignable to type 'Forbidden | InvalidInput | Unauthenticated'`, or a longer union, under a handler's error: a handler fails only with the errors its action declares and the library's built-in ones, and `X` may be Effect's `HttpApiError.Forbidden` or a `Forbidden` of your own. Add `X` to the action's `error`, or handle it.
+- `The types returned by '<handler>(...)'` at a builder: that handler fails with an error its action does not declare, and the error names one handler at a time; add the error to the action's `error` or handle it, and the next handler's shows.
 - `Binding element '<field>' implicitly has an 'any' type` (TS7031), or `Parameter 'input' implicitly has an 'any' type`, at every handler of a builder: the builder is wrapped, as in `Effect.gen(…).pipe(Effect.provide(layer))`, and its record is no longer typed from the contracts. Give `implement` the builder itself, and provide the layer to the surface's layer or to the server.
-- `Missing handlers: <names>` or `Unknown handlers: <keys>` thrown, also when a builder's layer builds: a record of handlers has one own function for each action of its `implement` call, and no other key. Add a missing handler to the record itself, not to a prototype; remove an unknown one, or add its action to the list.
 - `'<name>' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer` (TS7022), or, with the types bypassed, an acquisition that never completes: a builder acquires an `Action.client` of its own implementation, directly or through another builder. Call the services both use instead.
 
 ## Where an implementation is served
 
 - `Type 'CurrentUser' is not assignable to type 'never'`, or `Request<"Requires", CurrentUser>` still owed, for a layer serving only public actions: no surface provides a public action an identity, and a public action's handler reads one. Make the action protected.
-- `Type '{ readonly "A builder yields the caller, which a server has per request: yield it in a handler or an authorizer": { readonly caller: CurrentUser; readonly builderOf: "createNote" | ...; }; }' is not assignable to type 'never'` where a server is launched, or `is missing the following properties from type 'Scope'` at each `it.effect` that runs the routes, one error for each, all of one cause, the builder of the `implement` call whose actions `builderOf` names, or a service shared across requests that should be resolved per request: what a builder, or the Effect building an authorizer, yields is resolved once, at startup, and a server has the caller per request alone. Move the `yield*` into the handler or the authorizer.
+- `Type '{ readonly "A builder yields the caller, which a server has per request: yield it in a handler or an authorizer": { readonly caller: CurrentUser; readonly builderOf: "createNote" | ...; }; }' is not assignable to type 'never'` where a server is launched: the builder of the `implement` call whose actions `builderOf` names, or the Effect building its authorizer, yields the caller, which a builder would resolve once at startup. Move the `yield*` into the handler or the authorizer.
+- `is missing the following properties from type 'Scope'` at each `it.effect` that runs the routes: a builder, or the Effect building an authorizer, yields the caller or another per-request service, which a builder would resolve once at startup. Move the `yield*` into the handler or the authorizer.
 - `HttpRouter.Request<"Requires", X>` still owed, or `Type 'X' is not assignable to type 'never'` at `runMain`, although `X`, a store the authorizer reads, is provided at startup: what a plain authorizer yields is a request-time requirement, and this one yields `X` on every call. Make `authorize` an Effect that yields `X` once and returns the function ([Authorize calls](Action.md#authorize-calls)).
 - `unknown` among a surface's requirements, and a type error where it is served or run, such as `Argument of type 'Layer<never, unknown, unknown>' is not assignable` at `HttpRouter.toWebHandler` or `Type 'unknown' is not assignable to type 'never'`: the implementations are typed `Action.AnyImplementation`, as a helper's parameter or a list's annotation. Make the helper generic over them, `<const Apps extends Action.AnyImplementation | ReadonlyArray<Action.AnyImplementation>>(apps: Apps)`, or drop the annotation.
 - `Request<"Requires", unknown>` where an implementation is served, or `unknown` among the services a call or a run still requires: TypeScript inferred no requirements for one handler of a record, as a data-first call whose type takes a parameter from no argument causes, `Effect.catchTag(effect, tag, f)` for one. Write that handler's Effect `effect.pipe(Effect.catchTag(tag, f))`, or as a generator.
-- A builder runs twice, or a job, an agent or a second server reads other state than the routes, such as an empty in-memory store: inside one `HttpRouter.serve` or one `Testing.layer` a builder runs once, however many surfaces serve it, but each builds its routes in a layer graph of its own, which shares nothing it builds with a layer merged beside it. A job beside the server shares its build only when the job's side builds first, so it can pass in a test and build twice when the job starts later. Put the job or agent inside the layer the server serves, or provide `Action.layer(implementations)` and the services they share above both ([Share one build across servers](Action-in-process.md#share-one-build-across-servers)).
-- Two surfaces in one layer graph, each given startup services of its own, both answer with one surface's: a builder runs once per layer graph, with the services of its first build. Provide the services once; where the surfaces must differ, wrap each in `Layer.fresh`, providing what they share, authentication included, outside it, or give each an implementation of its own.
-- `Not an implementation made by this Action.implement: is effect-actions installed twice?` thrown by a surface, `client` or `layer`: another installed copy of the package made the implementation, or the value is a copy of one, such as a spread. Install one copy of the package, and pass the value `implement` returned.
 
 ## At `client` and its calls
 
-- `Listed in actions, but no implementation holds it: <names>` thrown by `Action.client`: an action listed in `actions` is none the given implementations hold. Pass the implementation holding it, or list the contract value it implemented.
-- `Duplicate action: <name>` thrown: a list given to `implement` or `byName` names one action twice, or two implementations given to `Action.client` implement an action of that name. Two contracts sharing a name are told apart by `actions`, listing one; two implementations of one contract are not: pass one.
 - `Type 'CurrentUser' is not assignable to type 'never'` where a program calling an `Action.client` runs, or `Type 'CurrentUser' is missing the following properties from type 'Scope'` at `it.effect`: a call to a protected action reads the caller from its own context, never from the one the client was acquired in. Provide the caller around the call.
 - `Type 'Scope' is not assignable to type 'never'` where a program runs, or `Service not found: effect/Scope` in plain JavaScript: acquiring an `Action.client` builds, as a layer does. Acquire it in a builder or a layer, or run the program in `Effect.scoped`.
-- A builder runs on every request, or a route owes `HttpRouter.Request<"Requires", X>` for `X`, a service its builder yields: acquiring an `Action.client` runs the builders, and a handler acquires one on every request. Acquire the client in the builder, and call it in the handler.
 - An `Action.client` call dies with a `SchemaError`: the handler's success, or what it fails with, does not pass through its codec. The cause holds the failure beside the `SchemaError`, as `Cause.pretty` shows: before it for a failure the action's errors reject, undeclared or breaking a check, after it for one they accept that does not encode. Return what the success schema accepts, and fail with an error the action declares.
-- `InvalidInput` with `Expected <Class>` from an `Action.client` call given a plain object: an input that is a class encodes only its instances. Pass `new Class({ ... })`.