@gjermundgaraba/effect-actions 0.16.0 → 0.18.0

package/examples/notes-service/src/notes/store.ts

@@ -1,5 +1,5 @@
 import { Context, Effect, Layer } from "effect";
-import { type Note, NoteChanged, NoteNotFound } from "./Notes.js";
+import { type Note, NoteChanged, NoteNotFound, RequestConflict } from "./Notes.js";
 
 /**
  * Where notes live, each owned by one user. Ownership is checked here, in the data access, so no
@@ -10,7 +10,12 @@ export class NoteStore extends Context.Service<
   {
     readonly list: (owner: string) => Effect.Effect<ReadonlyArray<Note>>;
     readonly get: (owner: string, id: string) => Effect.Effect<Note, NoteNotFound>;
-    readonly create: (owner: string, title: string, body: string) => Effect.Effect<Note>;
+    readonly create: (
+      owner: string,
+      title: string,
+      body: string,
+      requestId?: string,
+    ) => Effect.Effect<Note, RequestConflict>;
     /** Every note or none: a database does this in one transaction. */
     readonly createAll: (
       owner: string,
@@ -26,12 +31,14 @@ export class NoteStore extends Context.Service<
     readonly count: Effect.Effect<number>;
   }
 >()("notes-service/NoteStore") {
-  // DEMO ONLY: memory, lost when the process stops. A real store is another Layer of this
-  // service, chosen by the entrypoint.
+  // DEMO ONLY: notes and replay records live in this process's memory, without eviction.
   static readonly layerMemory = Layer.sync(NoteStore, () => {
     // One map per owner: a note is only ever looked up among its owner's, whatever id is asked.
     const notes = new Map<string, Map<string, Note>>();
 
+    // Keep the original result even after the note is updated or deleted.
+    const creations = new Map<string, Map<string, Note>>();
+
     const ownedBy = (owner: string) => notes.get(owner) ?? new Map<string, Note>();
 
     const save = (owner: string, note: Note) => {
@@ -51,8 +58,31 @@ export class NoteStore extends Context.Service<
     return NoteStore.of({
       list: (owner) => Effect.sync(() => Array.from(ownedBy(owner).values())),
       get,
-      create: (owner, title, body) =>
-        Effect.sync(() => save(owner, { id: crypto.randomUUID(), title, body, revision: 1 })),
+      create: Effect.fn("NoteStore.create")(function* (owner, title, body, requestId) {
+        if (requestId !== undefined) {
+          const recorded = creations.get(owner)?.get(requestId);
+
+          if (recorded !== undefined) {
+            if (recorded.title !== title || recorded.body !== body) {
+              return yield* new RequestConflict({ requestId });
+            }
+
+            return recorded;
+          }
+        }
+
+        // No yield between lookup, mutation and recording: concurrent calls cannot interleave
+        // or interruption leave a note without its result.
+        const note = save(owner, { id: crypto.randomUUID(), title, body, revision: 1 });
+
+        if (requestId !== undefined) {
+          const requests = creations.get(owner) ?? new Map<string, Note>();
+          requests.set(requestId, note);
+          creations.set(owner, requests);
+        }
+
+        return note;
+      }),
       createAll: (owner, all) =>
         Effect.sync(() =>
           all.map(({ title, body }) =>

package/examples/notes-service/test/commands.test.ts

@@ -16,7 +16,7 @@ import { TestConsole } from "effect/testing";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
 import { Http } from "../src/Api.js";
-import { commands, connection } from "../src/commands.js";
+import { commands } from "../src/commands.js";
 import { ImportNotes, Note, NoteNotFound } from "../src/notes/Notes.js";
 import { NoteStore } from "../src/notes/store.js";
 import { routes } from "../src/routes.js";
@@ -26,17 +26,16 @@ import { routes } from "../src/routes.js";
 // service a builder yields is provided here too (routes.test.ts).
 const served = Testing.layer(routes).pipe(Layer.provide(NoteStore.layerMemory));
 
-// Effect's own runner, given arguments instead of the process's. The console of `it.effect`
-// keeps every line printed, so a run returns the lines it added.
-const run = (token: string, args: ReadonlyArray<string>, stdin = "") =>
+// Effect's own runner, given arguments instead of the process's, and what the commands read from
+// the environment as a Layer, so the test decides whether a token is configured, whatever the
+// shell holds. The console of `it.effect` keeps every line printed, so a run returns the lines
+// it added.
+const connected = (environment: Record<string, string>, args: ReadonlyArray<string>, stdin = "") =>
   Effect.gen(function* () {
     const before = (yield* TestConsole.logLines).length;
 
     yield* Command.runWith(commands, { version: "0" })(args).pipe(
-      Effect.updateService(
-        HttpClient.HttpClient,
-        HttpClient.mapRequest(HttpClientRequest.bearerToken(token)),
-      ),
+      Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnvRecord(environment))),
       Effect.provide(Stdio.layerTest({ stdin: Stream.make(new TextEncoder().encode(stdin)) })),
       Effect.provide(NodeServices.layer),
     );
@@ -44,15 +43,9 @@ const run = (token: string, args: ReadonlyArray<string>, stdin = "") =>
     return (yield* TestConsole.logLines).slice(before);
   });
 
-// The commands as cli.ts connects them, with what it reads from the environment given as a
-// Layer, so the test decides whether a token is configured, whatever the shell holds.
-const connected = (environment: Record<string, string>, args: ReadonlyArray<string>) =>
-  Command.runWith(commands.pipe(Command.provideEffect(HttpClient.HttpClient, connection)), {
-    version: "0",
-  })(args).pipe(
-    Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnvRecord(environment))),
-    Effect.provide(NodeServices.layer),
-  );
+// A run as the caller `token` names.
+const run = (token: string, args: ReadonlyArray<string>, stdin = "") =>
+  connected({ NOTES_TOKEN: token }, args, stdin);
 
 const fitsAFile = (text: string) =>
   new TextDecoder().decode(new TextEncoder().encode(text)) === text;
@@ -270,9 +263,10 @@ describe("the commands", () => {
       const refused = yield* Effect.flip(connected({}, ["list-notes"]));
 
       expect(refused).toBeInstanceOf(CliError.UserError);
+      expect(refused).toHaveProperty("cause._tag", "MissingToken");
       expect(refused).toHaveProperty(
         "userMessage",
-        "NOTES_TOKEN is not set. Set it to your token: export NOTES_TOKEN=<your token>",
+        "MissingToken: NOTES_TOKEN is not set. Set it to your token: export NOTES_TOKEN=<your token>",
       );
 
       // What a person sees: that message, once, on stderr, and no report of a `ConfigError`.
@@ -280,7 +274,7 @@ describe("the commands", () => {
         expect.stringContaining("NOTES_TOKEN is not set."),
       ]);
 
-      // The token is read when a command runs, so its help needs none.
+      // The token is read when a command runs, so help needs none.
       yield* connected({}, ["list-notes", "--help"]);
 
       expect(yield* TestConsole.logLines).toHaveLength(2);

package/examples/notes-service/test/notes/idempotency.test.ts

@@ -0,0 +1,132 @@
+import { expect, it } from "@effect/vitest";
+import { Arbitrary, Array, Effect, References, Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { CurrentUser } from "../../src/identity/Identity.js";
+import { users } from "../../src/identity/users.js";
+import { notes } from "../../src/notes/handlers.js";
+import { CreateNote, RequestConflict } from "../../src/notes/Notes.js";
+import { NoteStore } from "../../src/notes/store.js";
+
+const as = (user: keyof typeof users) => Effect.provideService(CurrentUser, users[user]);
+
+it.effect("creates a new note on every call without a request key", () =>
+  Effect.gen(function* () {
+    const client = yield* Action.client(notes);
+    const input = { title: "Plan", body: "Draft" };
+    const first = yield* client.createNote(input);
+    const second = yield* client.createNote(input);
+
+    expect(second.id).not.toBe(first.id);
+    expect(yield* client.listNotes()).toEqual({
+      notes: [
+        { id: first.id, title: input.title },
+        { id: second.id, title: input.title },
+      ],
+    });
+  }).pipe(as("ada"), Effect.provide(NoteStore.layerMemory)),
+);
+
+it.effect.prop(
+  "replays a creation with the same key and content",
+  {
+    input: Arbitrary.schema(
+      Schema.Struct({
+        ...CreateNote.input.fields,
+        requestId: Schema.requiredKey(CreateNote.input.fields.requestId),
+      }),
+    ),
+  },
+  ({ input }) =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(notes);
+      const first = yield* client.createNote(input);
+      const replay = yield* client.createNote(input);
+
+      expect(first).toMatchObject({ title: input.title, body: input.body, revision: 1 });
+      expect(replay).toEqual(first);
+      expect(yield* client.listNotes()).toEqual({
+        notes: [{ id: first.id, title: input.title }],
+      });
+    }).pipe(as("ada"), Effect.provide(NoteStore.layerMemory)),
+);
+
+it.effect.each([
+  { title: "Changed", body: "Draft" },
+  { title: "Plan", body: "Changed" },
+])("refuses reuse of a key with changed content: %j", (changed) =>
+  Effect.gen(function* () {
+    const client = yield* Action.client(notes);
+    const input = { requestId: "plan", title: "Plan", body: "Draft" };
+    const first = yield* client.createNote(input);
+
+    expect(
+      yield* Effect.flip(client.createNote({ requestId: input.requestId, ...changed })),
+    ).toEqual(new RequestConflict({ requestId: input.requestId }));
+    expect(yield* client.createNote(input)).toEqual(first);
+    expect(yield* client.listNotes()).toEqual({ notes: [{ id: first.id, title: "Plan" }] });
+  }).pipe(as("ada"), Effect.provide(NoteStore.layerMemory)),
+);
+
+it.effect("scopes keys to the caller, and treats a new key as a new creation", () =>
+  Effect.gen(function* () {
+    const client = yield* Action.client(notes);
+    const input = { requestId: "plan", title: "Plan", body: "Draft" };
+    const ada = yield* client.createNote(input).pipe(as("ada"));
+    const grace = yield* client.createNote({ ...input, body: "Grace's draft" }).pipe(as("grace"));
+    const another = yield* client.createNote({ ...input, requestId: "another" }).pipe(as("ada"));
+
+    expect(new Set([ada.id, grace.id, another.id]).size).toBe(3);
+    expect(yield* client.createNote(input).pipe(as("ada"))).toEqual(ada);
+    expect(yield* client.listNotes().pipe(as("ada"))).toEqual({
+      notes: [
+        { id: ada.id, title: "Plan" },
+        { id: another.id, title: "Plan" },
+      ],
+    });
+    expect(yield* client.listNotes().pipe(as("grace"))).toEqual({
+      notes: [{ id: grace.id, title: "Plan" }],
+    });
+  }).pipe(Effect.provide(NoteStore.layerMemory)),
+);
+
+it.effect("retains the original result after the note changes or is deleted", () =>
+  Effect.gen(function* () {
+    const client = yield* Action.client(notes);
+    const input = { requestId: "plan", title: "Plan", body: "Draft" };
+    const original = yield* client.createNote(input);
+
+    yield* client.updateNote({ id: original.id, body: "Final", revision: 1 });
+
+    expect(yield* client.createNote(input)).toEqual(original);
+    expect(yield* client.getNote({ id: original.id })).toMatchObject({
+      body: "Final",
+      revision: 2,
+    });
+
+    yield* client.deleteNote({ id: original.id });
+
+    expect(yield* client.createNote(input)).toEqual(original);
+    expect(yield* client.listNotes()).toEqual({ notes: [] });
+  }).pipe(as("ada"), Effect.provide(NoteStore.layerMemory)),
+);
+
+it.effect("creates one note for concurrent duplicates, including under frequent fiber yields", () =>
+  Effect.gen(function* () {
+    const client = yield* Action.client(notes);
+    const steps = Array.range(3, 60);
+
+    yield* Effect.forEach(steps, (limit) =>
+      Effect.gen(function* () {
+        const input = { requestId: `concurrent-${limit}`, title: "Plan", body: "Draft" };
+
+        const created = yield* Effect.all(Array.replicate(client.createNote(input), 3), {
+          concurrency: "unbounded",
+        }).pipe(Effect.provideService(References.MaxOpsBeforeYield, limit));
+
+        expect(created).toEqual(Array.replicate(created[0], 3));
+      }),
+    );
+
+    expect((yield* client.listNotes()).notes).toHaveLength(steps.length);
+  }).pipe(as("ada"), Effect.provide(NoteStore.layerMemory)),
+);

package/examples/notes-service/test/routes.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "@effect/vitest";
 import { Effect, Layer } from "effect";
-import { HttpClient, HttpClientRequest } from "effect/http";
+import { HttpClient, HttpClientError, HttpClientRequest } from "effect/http";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
@@ -84,4 +84,43 @@ describe("the service, over HTTP and MCP", () => {
       expect(yield* response.text).toContain('"name":"createNote"');
     }).pipe(Effect.provide(served)),
   );
+
+  it.effect("retries a committed HTTP write over MCP after its response is lost", () =>
+    Effect.gen(function* () {
+      const http = yield* ActionHttp.client(Http, {
+        transformClient: (client) =>
+          client.pipe(
+            as("ada").transformClient,
+            // The real server finishes the write, but the caller receives no response.
+            HttpClient.transform((response, request) =>
+              response.pipe(
+                Effect.andThen(
+                  Effect.fail(
+                    new HttpClientError.HttpClientError({
+                      reason: new HttpClientError.TransportError({
+                        request,
+                        description: "Response lost after commit",
+                      }),
+                    }),
+                  ),
+                ),
+              ),
+            ),
+          ),
+      });
+
+      const mcp = yield* ActionMcp.client([GetStatus, ...Notes], as("ada"));
+      const input = { requestId: "plan", title: "Plan", body: "Draft" };
+
+      expect(yield* Effect.flip(http.createNote(input))).toBeInstanceOf(
+        HttpClientError.HttpClientError,
+      );
+      expect(yield* mcp.getStatus()).toEqual({ service: "notes-service", notes: 1 });
+
+      const replay = yield* mcp.createNote(input);
+
+      expect(replay).toMatchObject({ title: "Plan", body: "Draft", revision: 1 });
+      expect(yield* mcp.listNotes()).toEqual({ notes: [{ id: replay.id, title: "Plan" }] });
+    }).pipe(Effect.provide(served)),
+  );
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/effect-actions",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Define Effect action contracts once and project them onto HTTP, MCP, Effect RPC, native Toolkits, and CLIs.",
   "keywords": [
     "ai-agents",
@@ -52,13 +52,13 @@
     "@effect/platform-node": "4.0.4",
     "@effect/vitest": "4.0.4",
     "@modelcontextprotocol/client": "2.3.1",
-    "@types/node": "26.6.4",
+    "@types/node": "26.6.5",
     "effect": "4.0.4",
     "tsx": "4.23.15",
     "typescript": "7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
-    "vite-plus": "1.1.0",
-    "vitest": "5.0.3"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.2.0",
+    "vite-plus": "1.2.0",
+    "vitest": "5.0.4"
   },
   "peerDependencies": {
     "effect": "~4.0.4"

package/dist/_virtual/_rolldown/runtime.mjs

@@ -1,13 +0,0 @@
-//#region \0rolldown/runtime.js
-var __defProp = Object.defineProperty;
-var __exportAll = (all, no_symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
-//#endregion
-export { __exportAll };

package/dist/contract/rules.mjs

@@ -1,100 +0,0 @@
-import { builtIns } from "./errors.mjs";
-import { Predicate, Schema, SchemaAST } from "effect";
-//#region src/contract/rules.ts
-const errorList = (error) => error === void 0 ? [] : Schema.isSchema(error) ? [error] : error;
-const projectedErrors = (action, surface = []) => [.../* @__PURE__ */ new Set([
-	...builtIns,
-	...action.error,
-	...surface
-])];
-/**
-* Every error a binding's call of `action` declares: the built-in ones, the action's, the
-* binding's and, where `action` is protected, its authentication's.
-*/
-const bindingErrors = (action, binding) => projectedErrors(action, action.caller === Anyone || binding.authentication === void 0 ? binding.error : [...binding.error, ...binding.authentication.error]);
-const assertAuthentication = (actions, authentication) => {
-	for (const action of actions) if (action.caller !== Anyone && (authentication === void 0 || action.caller.key !== authentication.identity.key)) throw new Error(`Protected action '${action.name}' requires its matching authentication descriptor`);
-};
-/**
-* The caller of a public action, `caller: Action.Anyone`: anyone, signed in or not, and no
-* authorizer runs for it. Registered globally, so two copies of the package agree on it, as they
-* agree on a name.
-*/
-const Anyone = Symbol.for("@gjermundgaraba/effect-actions/Anyone");
-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 assertDistinct = (what, items, nameOf, claimantOf = nameOf) => {
-	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}`);
-		}
-		seen.set(name, claimant);
-	}
-};
-const assertOnce = (what, actions) => assertDistinct(what, actions, (action) => action.name);
-const assertKnown = (what, keys, names) => {
-	const unknown = keys.filter((key) => !names.includes(key));
-	if (unknown.length > 0) throw new Error(`Unknown ${what}: ${unknown.join(", ")}`);
-};
-const unsuspended = (ast) => SchemaAST.isSuspend(ast) ? unsuspended(ast.thunk()) : ast;
-const members = (ast) => {
-	const resolved = unsuspended(ast);
-	return SchemaAST.isUnion(resolved) ? resolved.types.flatMap(members) : [resolved];
-};
-const literalValues = (ast) => SchemaAST.isLiteral(ast) ? [ast.literal] : SchemaAST.isEnum(ast) ? ast.enums.map(([, value]) => value) : [void 0];
-const encodedTags = (ast) => members(SchemaAST.toEncoded(ast)).flatMap((member) => {
-	const tag = SchemaAST.isObjects(member) ? member.propertySignatures.find((property) => property.name === "_tag")?.type : void 0;
-	return tag === void 0 ? [] : members(tag).flatMap(literalValues).filter(Predicate.isString);
-});
-const builtInTags = new Set(builtIns.flatMap((error) => encodedTags(error.ast)));
-const assertOwnTags = (what, errors) => {
-	const tag = errors.flatMap((error) => encodedTags(error.ast)).find((tag) => builtInTags.has(tag));
-	if (tag !== void 0) throw new Error(`${what}: error _tag "${tag}" is built in, and declared on every surface`);
-};
-/**
-* The checks `ActionHttp.make` and `ActionRpc.make` share: each action once, no built-in error in
-* `error`, and the descriptor every protected action names. Returns `error` as a list.
-*/
-const bindingOf = (what, actions, options) => {
-	assertOnce("action", actions);
-	const error = errorList(options.error);
-	assertOwnTags(what, error);
-	assertAuthentication(actions, options.authentication);
-	return {
-		error,
-		authentication: options.authentication
-	};
-};
-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.
-*/
-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 })];
-};
-/**
-* An action's MCP tool hints, MCP's defaults where its `mcp` leaves one out: a write destructive,
-* a read not, no tool idempotent and every tool open-world. A given value passes through, as MCP
-* calls `destructiveHint` and `idempotentHint` meaningless on a read-only tool.
-*/
-const hintsOf = ({ readOnly, mcp }) => ({
-	readOnlyHint: readOnly,
-	destructiveHint: mcp.destructiveHint ?? !readOnly,
-	idempotentHint: mcp.idempotentHint ?? false,
-	openWorldHint: mcp.openWorldHint ?? true
-});
-//#endregion
-export { Anyone, assertAuthentication, assertDistinct, assertKnown, assertName, assertOnce, assertOwnTags, bindingErrors, bindingOf, declared, errorList, hintsOf, httpApiStatusOf, literalValues, members, projectedErrors, unsuspended };