@gjermundgaraba/effect-actions 0.10.0 → 0.12.0

package/dist/stdio/console.mjs

@@ -0,0 +1,64 @@
+import { Clock, Console, Effect, Function, Predicate } from "effect";
+//#region src/stdio/console.ts
+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 writeLabelKeepingFormat = (label, args) => {
+		const [formatOrFirst, ...rest] = args;
+		write(...Predicate.isString(formatOrFirst) ? [`${label}: ${formatOrFirst}`, ...rest] : [label, ...args]);
+	};
+	const group = (...labelOrUndefined) => {
+		if (labelOrUndefined.some((part) => part !== void 0)) write(...labelOrUndefined);
+	};
+	return {
+		assert: (condition, ...args) => {
+			if (!condition) writeLabelKeepingFormat("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") => {
+			if (!timers.has(label)) 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 [_header, _traceFrame, ...callerFrames] = stack.split("\n");
+			const callerStack = callerFrames.join("\n");
+			writeLabelKeepingFormat("Trace", args);
+			if (callerStack !== "") write(callerStack);
+		},
+		warn: write
+	};
+};
+const withStderrConsole = (effect) => Effect.provideServiceEffect(effect, Console.Console, Effect.zipWith(Effect.service(Console.Console), Effect.service(Clock.Clock), stderrConsole));
+//#endregion
+export { withStderrConsole };

package/dist/{internal → testing}/memory.d.mts

@@ -1,6 +1,6 @@
 import { Layer } from "effect";
 import { HttpClient, HttpRouter, HttpServer } from "effect/http";
-//#region src/internal/memory.d.ts
+//#region src/testing/memory.d.ts
 /** What in-memory routes may leave to the host: the router, the platform, nothing per request. */
 export type Served = HttpRouter.HttpRouter | HttpRouter.Request<"Requires", never> | HttpRouter.Request<"GlobalRequires", never> | HttpRouter.Request<"Error", any> | HttpRouter.Request<"GlobalError", any> | Layer.Success<typeof HttpServer.layerServices>;
 //#endregion

package/dist/{internal → testing}/memory.mjs

@@ -1,14 +1,8 @@
 import { Effect, Layer, Predicate, Stream } from "effect";
 import { FetchHttpClient, HttpBody, HttpClient, HttpClientRequest } from "effect/http";
-//#region src/internal/memory.ts
-/** Where relative request URLs resolve, so a client needs no `baseUrl`. */
-const origin = "http://localhost/";
-/**
-* `request`, a streamed body turned into a web stream in the current context. The native client
-* turns it in its send, under the in-memory `fetch`, where another client the stream calls
-* would send to the routes too.
-*/
-const pulled = (request) => {
+//#region src/testing/memory.ts
+const relativeUrlOrigin = "http://localhost/";
+const withWebStreamBodyInCurrentContext = (request) => {
 	const body = request.body;
 	if (!Predicate.isTagged(body, "Stream")) return Effect.succeed(request);
 	return Effect.map(Stream.toReadableStreamEffect(body.stream), (readable) => HttpClientRequest.setBody(request, HttpBody.raw(readable, {
@@ -16,12 +10,6 @@ const pulled = (request) => {
 		contentLength: body.contentLength
 	})).pipe(HttpClientRequest.updateHeaders(() => request.headers)));
 };
-/**
-* The native `HttpClient`, sending every request to `handler` instead of the network. A
-* relative URL resolves against `http://localhost/`, as a page there would resolve it, and a
-* request carries the `Host` header of its URL, as one over the network does. The client is
-* its own: the program's other clients keep their `fetch`, and get none of its requests.
-*/
 const clientOf = (handler) => {
 	const fetch = (input, init) => {
 		const request = new Request(input, init);
@@ -29,9 +17,9 @@ const clientOf = (handler) => {
 		return handler(request);
 	};
 	return Layer.effect(HttpClient.HttpClient, Effect.map(HttpClient.HttpClient, (native) => HttpClient.makeWith((request) => Effect.flatMap(request, (mapped) => {
-		const resolved = URL.canParse(mapped.url) ? null : URL.parse(mapped.url, origin);
+		const resolved = URL.canParse(mapped.url) ? null : URL.parse(mapped.url, relativeUrlOrigin);
 		const sent = resolved === null ? mapped : HttpClientRequest.setUrl(mapped, resolved.href);
-		return Effect.flatMap(pulled(sent), (ready) => native.postprocess(Effect.succeed(ready)).pipe(Effect.provideService(FetchHttpClient.Fetch, fetch)));
+		return Effect.flatMap(withWebStreamBodyInCurrentContext(sent), (ready) => native.postprocess(Effect.succeed(ready)).pipe(Effect.provideService(FetchHttpClient.Fetch, fetch)));
 	}), native.preprocess))).pipe(Layer.provide(Layer.fresh(FetchHttpClient.layer)));
 };
 //#endregion

package/dist/toolkit/tools.mjs

@@ -0,0 +1,29 @@
+import { assertOnce, projectedErrors } from "../contract/rules.mjs";
+import { acquire } from "../contract/implementation.mjs";
+import { Effect, Schema } from "effect";
+import { Tool, Toolkit } from "effect/ai";
+//#region src/toolkit/tools.ts
+const annotateIfGiven = (tool, key, value) => value === void 0 ? tool : tool.annotate(key, value);
+const annotateFromContract = (tool, { readOnly, mcp }) => {
+	const destructiveUnlessReadOnly = mcp.destructiveHint ?? (readOnly ? false : void 0);
+	const meta = mcp._meta === void 0 ? void 0 : { ...mcp._meta };
+	const hinted = annotateIfGiven(annotateIfGiven(annotateIfGiven(tool.annotate(Tool.Readonly, readOnly), Tool.Destructive, destructiveUnlessReadOnly), Tool.Idempotent, mcp.idempotentHint), Tool.OpenWorld, mcp.openWorldHint);
+	return annotateIfGiven(annotateIfGiven(hinted, Tool.Title, mcp.title), Tool.Meta, meta);
+};
+const jsonToolOf = (action) => Tool.make(action.name, {
+	description: action.description,
+	parameters: Schema.toCodecJson(action.input),
+	success: Schema.toCodecJson(action.success),
+	failure: Schema.toCodecJson(Schema.Union(projectedErrors(action))),
+	failureMode: "return"
+});
+const bindTools = (apps, projection) => {
+	assertOnce(projection.label, apps.flatMap((app) => app.actions));
+	const toolkit = Toolkit.make(...apps.flatMap((app) => app.actions.map((action) => annotateFromContract(projection.tool(jsonToolOf(action), action, app), action))));
+	return {
+		toolkit,
+		layer: toolkit.toLayer(Effect.map(acquire(apps), (bound) => Object.fromEntries(bound.map(([action, run]) => [action.name, projection.handler?.(run, action) ?? run]))))
+	};
+};
+//#endregion
+export { bindTools };

package/docs/Action-failures.md

@@ -0,0 +1,47 @@
+# Action failure modes
+
+What you see when something is wrong, and the fix. Search for a fragment of the message.
+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.
+- `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.
+- `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.
+- `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. A failure follows the `SchemaError` in the cause, as `Cause.pretty` shows. 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({ ... })`.

package/docs/Action-in-process.md

@@ -0,0 +1,93 @@
+# Action in process
+
+Call actions from your own code, such as a job or a test, and share one build of the
+implementations between servers and jobs.
+
+Read [Action.md](Action.md) first, and this page alone, in one tool call. When something fails,
+search [Action-failures.md](Action-failures.md). Reading order: [README.md](README.md).
+
+## API
+
+Import `@gjermundgaraba/effect-actions/Action`. Its other exports are in [Action.md](Action.md#api).
+
+| Export                                  | Purpose                                                                  |
+| --------------------------------------- | ------------------------------------------------------------------------ |
+| `client(implementations, { actions? })` | An Effect of a client running them in process: `client.<action>(input)`. |
+| `layer(implementations)`                | Their builders as one layer: above several servers, each runs once.      |
+| `Client<Apps>`                          | What `client` gives for the implementations `Apps`, one or a list.       |
+| `ClientOptions`                         | What `client` takes: `actions`, the ones to call.                        |
+
+## Call actions in process
+
+`Action.client(implementations)` gives the methods `ActionHttp.client` gives. A call runs what a
+remote call runs, without a transport: the input and the result pass through their JSON codecs,
+and the authorizer runs before the handler.
+
+```ts
+const as = (user: keyof typeof users) => Effect.provideService(CurrentUser, users[user]);
+
+const program = Effect.gen(function* () {
+  const client = yield* Action.client(notes);
+
+  return yield* client.createNote({ title: "Plan", body: "Draft" }).pipe(as("ada"));
+}).pipe(Effect.scoped, Effect.provide(NoteStore.layerMemory));
+```
+
+Acquiring a client needs a `Scope`: under `it.effect` the test supplies it, as in
+[notes-service/test/notes/notes.test.ts](../examples/notes-service/test/notes/notes.test.ts);
+elsewhere `Effect.scoped` does, as in [kitchen-sink/src/agent.ts](../examples/kitchen-sink/src/agent.ts).
+
+- **Provide the caller around each call, and startup services around the acquisition.** A call
+  reads its own context, never the one the client was acquired in, so one client serves every
+  caller ([assistant/test/identity/identity.test.ts](../examples/assistant/test/identity/identity.test.ts)).
+- **Acquiring a client runs the builders**, and builds a built authorizer: it owes their startup
+  services. Acquire it once, in a builder, a layer, or a scoped program such as a test. Never in
+  a handler, which builds on every request.
+- **Two acquisitions share a build only inside one layer graph**, such as under a layer provided
+  around the program. With none around them, each builds its own.
+- **Every implemented action has a method**, whether or not a surface serves it. `actions` lists
+  the ones to call, and an implementation holding none of them is left unbuilt
+  ([kitchen-sink/test/issues/issues.test.ts](../examples/kitchen-sink/test/issues/issues.test.ts)).
+- **Test what an implementation does here**, and what a surface adds, its authentication,
+  statuses and codecs, in memory ([Testing.md](Testing.md#test-routes-in-memory)). Assert on a
+  failure as [Testing.md](Testing.md#assert-on-errors) says.
+
+## Share one build across servers
+
+Inside one `HttpRouter.serve` or one `Testing.layer`, a builder runs once, however many surfaces
+serve it, a toolkit's `layer` provided to the routes included. Each builds its routes in a layer graph of its own, as `HttpRouter.provideRequest(layer)` builds its layer, which reuses what is provided from
+outside it and shares nothing it builds itself: a builder's run, a built authorizer, or a
+service of yours such as an in-memory store.
+
+- **With one server, put everything the process runs inside the layer it serves**, a job or an
+  agent beside the routes included.
+- **Otherwise, provide `Action.layer(implementations)` and the services they share above the
+  server and its siblings**: a second server, a program beside it, several `Testing.layer`s.
+
+```ts
+// kitchen-sink/src/routes.ts
+export const builders = Action.layer([status, identity, issues, attachments, admin]);
+
+// kitchen-sink/src/server.ts
+Layer.mergeAll(
+  HttpRouter.serve(publicRoutes).pipe(Layer.provide(listen(publicPort))),
+  HttpRouter.serve(adminRoutes).pipe(Layer.provide(listen(adminPort))),
+).pipe(Layer.provide(builders), Layer.provide(memory));
+```
+
+That is [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) and
+[kitchen-sink/src/server.ts](../examples/kitchen-sink/src/server.ts), two ports;
+[kitchen-sink/test/routes.test.ts](../examples/kitchen-sink/test/routes.test.ts) does it with two
+`Testing.layer`s, asserting one run of a builder both ports serve.
+
+- **A job merged beside `HttpRouter.serve`, with no `Action.layer` above both, shares the
+  server's build only when its own side builds first.** Built after the routes, it builds
+  again, with state of its own. Which builds first depends on timing: it can pass in a test and
+  build twice once the job starts later.
+- **`Action.layer` builds every implementation it is given**, those no surface serves included,
+  so it owes their startup services.
+- **Inside one layer graph, a builder runs with the services of whichever surface builds it
+  first**, and services provided around one surface reach the others. Provide startup services
+  once, for every surface.
+- **Do not wrap a server in `Layer.fresh`**: two servers already share no build. It is only for
+  two surfaces in one graph that must each have a build and startup services of their own.