@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/examples/kitchen-sink/src/issues/export.ts

@@ -0,0 +1,35 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Effect, Stream } from "effect";
+
+import { authorize } from "../identity/authorize.js";
+import { ExportIssues } from "./Issues.js";
+import { IssueStore } from "./store.js";
+import { exportLimit } from "./write-limit.js";
+
+export const exports = Action.implement(
+  ExportIssues,
+  Effect.gen(function* () {
+    const store = yield* IssueStore;
+    const limited = yield* exportLimit;
+
+    // The handler returns a `Stream`. The limit is spent before the first issue, so a refused
+    // export fails as an action answering one value does, a 429 over HTTP; a failure after an
+    // issue would end the stream instead, the issues before it already sent.
+    return ({ status }, { progress }) =>
+      Stream.unwrap(
+        limited((member) =>
+          Effect.map(store.count(member.workspace, status), (total) =>
+            store.all(member.workspace, status).pipe(
+              Stream.zipWithIndex,
+              // `progress` never waits for the caller, dropping the oldest values a slow one has not taken:
+              // `exported` may skip numbers, so it says how far the export is, not what arrived.
+              Stream.mapEffect(([issue, index]) =>
+                Effect.as(progress({ exported: index + 1, total }), issue)
+              )
+            )
+          )
+        )
+      );
+  }),
+  { authorize }
+);

package/examples/kitchen-sink/src/issues/guide.ts

@@ -1,6 +1,7 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
 import { Effect, Layer, Schema } from "effect";
 import { McpServer } from "effect/ai";
-import * as Action from "@gjermundgaraba/effect-actions/Action";
+
 import { Issues } from "./Issues.js";
 
 const guide = `# Triage
@@ -30,7 +31,7 @@ export const features = Layer.mergeAll(
     parameters: { focus: Schema.String },
     content: ({ focus }) =>
       Effect.succeed(
-        `Call ${tools.listIssues.name} for the open issues and ${tools.getIssue.name} for those about ${focus}. For each, propose ${tools.commentOnIssue.name} or ${tools.closeIssue.name}. Follow tracker://guides/triage.`,
+        `Call ${tools.listIssues.name} for the open issues and ${tools.getIssue.name} for those about ${focus}. For each, propose ${tools.commentOnIssue.name} or ${tools.closeIssue.name}. Follow tracker://guides/triage.`
       ),
-  }),
+  })
 );

package/examples/kitchen-sink/src/issues/handlers.ts

@@ -1,5 +1,6 @@
-import { Effect } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Effect } from "effect";
+
 import { authorize } from "../identity/authorize.js";
 import { CurrentMember } from "../identity/Identity.js";
 import { Issues } from "./Issues.js";
@@ -22,16 +23,28 @@ export const issues = Action.implement(
           const member = yield* CurrentMember;
           const listed = yield* store.list(member.workspace, status, limit);
 
-          return { issues: listed.map(({ id, title, status }) => ({ id, title, status })) };
+          return {
+            issues: listed.map((issue) => ({
+              id: issue.id,
+              title: issue.title,
+              status: issue.status,
+            })),
+          };
         }),
       getIssue: ({ id }) =>
-        Effect.flatMap(CurrentMember, (member) => store.get(member.workspace, id)),
+        Effect.flatMap(CurrentMember, (member) =>
+          store.get(member.workspace, id)
+        ),
       // One function wraps every limited handler, and gives it the member it counted.
-      createIssue: (draft) => limited((member) => store.create(member.workspace, draft)),
+      createIssue: (draft) =>
+        limited((member) => store.create(member.workspace, draft)),
       commentOnIssue: ({ id, text }) =>
-        limited((member) => store.comment(member.workspace, id, { author: member.id, text })),
-      closeIssue: ({ id }) => limited((member) => store.close(member.workspace, id)),
+        limited((member) =>
+          store.comment(member.workspace, id, { author: member.id, text })
+        ),
+      closeIssue: ({ id }) =>
+        limited((member) => store.close(member.workspace, id)),
     };
   }),
-  { authorize },
+  { authorize }
 );

package/examples/kitchen-sink/src/issues/store.ts

@@ -1,9 +1,11 @@
-import { Context, Effect, Layer } from "effect";
-import { type Comment, type Issue, IssueNotFound, type Status } from "./Issues.js";
+import { Context, Effect, Layer, PubSub, Stream } from "effect";
+
+import { IssueNotFound } from "./Issues.js";
+import type { Comment, Issue, IssueChange, Status } from "./Issues.js";
 
 /**
- * Where issues live, each in one workspace. Every method takes the workspace, so tenant
- * isolation is the data access's: no surface and no handler can skip it, and an issue of
+ * Where issues live, each in one workspace. Every method but `changes` takes the workspace, so
+ * tenant isolation is the data access's: no surface and no handler can skip it, and an issue of
  * another workspace is simply not found.
  */
 export class IssueStore extends Context.Service<
@@ -12,85 +14,172 @@ export class IssueStore extends Context.Service<
     readonly list: (
       workspace: string,
       status: typeof Status.Type | undefined,
-      limit: number,
-    ) => Effect.Effect<ReadonlyArray<Issue>>;
-    readonly get: (workspace: string, id: string) => Effect.Effect<Issue, IssueNotFound>;
+      limit: number
+    ) => Effect.Effect<readonly Issue[]>;
+    /** Every issue, oldest first. */
+    readonly all: (
+      workspace: string,
+      status: typeof Status.Type | undefined
+    ) => Stream.Stream<Issue>;
+    readonly count: (
+      workspace: string,
+      status: typeof Status.Type | undefined
+    ) => Effect.Effect<number>;
+    readonly get: (
+      workspace: string,
+      id: string
+    ) => Effect.Effect<Issue, IssueNotFound>;
     readonly create: (
       workspace: string,
-      draft: Pick<Issue, "title" | "body" | "assignee">,
+      draft: Pick<Issue, "title" | "body" | "assignee">
     ) => Effect.Effect<Issue>;
     readonly comment: (
       workspace: string,
       id: string,
-      comment: typeof Comment.Type,
+      comment: typeof Comment.Type
     ) => Effect.Effect<Issue, IssueNotFound>;
-    readonly close: (workspace: string, id: string) => Effect.Effect<Issue, IssueNotFound>;
+    readonly close: (
+      workspace: string,
+      id: string
+    ) => Effect.Effect<Issue, IssueNotFound>;
+    /**
+     * Every change from now on, in the order the store makes them, of every workspace: whatever
+     * reads it filters by workspace itself, as `issueEvents`' `match` does.
+     */
+    readonly changes: Stream.Stream<typeof IssueChange.Type>;
   }
 >()("tracker/IssueStore") {
   // DEMO ONLY: memory, lost when the process stops. A real store is another Layer of this
   // service, chosen by the entrypoint.
-  static readonly layerMemory = Layer.sync(IssueStore, () => {
-    const issues = new Map<string, Array<Issue>>();
+  static readonly layerMemory = Layer.effect(
+    IssueStore,
+    Effect.gen(function* () {
+      const issues = new Map<string, Issue[]>();
+      const changes = yield* PubSub.unbounded<typeof IssueChange.Type>();
 
-    const of = (workspace: string) => issues.get(workspace) ?? [];
+      // Published in the step of the write, after it, so a subscriber never sees a change the
+      // store did not make, and sees them in the order they were made. A database publishes
+      // from its own change feed, or an outbox written in the same transaction.
+      const publish = (
+        workspace: string,
+        issue: Issue,
+        change: (typeof IssueChange.Type)["change"],
+        comment?: typeof Comment.Type
+      ) =>
+        PubSub.publishUnsafe(changes, {
+          workspace,
+          id: issue.id,
+          title: issue.title,
+          status: issue.status,
+          change,
+          ...(comment === undefined ? {} : { comment }),
+        });
 
-    const get = Effect.fn("IssueStore.get")(function* (workspace: string, id: string) {
-      const issue = of(workspace).find((candidate) => candidate.id === id);
+      const of = (workspace: string) => issues.get(workspace) ?? [];
 
-      if (issue === undefined) return yield* new IssueNotFound({ id });
+      const having = (
+        workspace: string,
+        status: typeof Status.Type | undefined
+      ) =>
+        of(workspace).filter(
+          (issue) => status === undefined || issue.status === status
+        );
 
-      return issue;
-    });
+      const get = Effect.fn("IssueStore.get")(function* (
+        workspace: string,
+        id: string
+      ) {
+        const issue = of(workspace).find((candidate) => candidate.id === id);
 
-    // No `yield*` between the read and the write: a fiber may be set aside at one, and two
-    // changes that each read the issue before either wrote would keep only the second. A
-    // database does this in one statement or a transaction.
-    const change = Effect.fn("IssueStore.change")(function* (
-      workspace: string,
-      id: string,
-      to: (issue: Issue) => Issue,
-    ) {
-      const issue = of(workspace).find((candidate) => candidate.id === id);
-
-      if (issue === undefined) return yield* new IssueNotFound({ id });
-
-      const changed = to(issue);
-
-      issues.set(
-        workspace,
-        of(workspace).map((current) => (current === issue ? changed : current)),
-      );
-
-      return changed;
-    });
-
-    return IssueStore.of({
-      list: (workspace, status, limit) =>
-        Effect.sync(() =>
-          of(workspace)
-            .filter((issue) => status === undefined || issue.status === status)
-            .toReversed()
-            .slice(0, limit),
-        ),
-      get,
-      create: (workspace, draft) =>
-        Effect.sync(() => {
-          const existing = of(workspace);
-
-          const issue: Issue = {
-            ...draft,
-            id: `${workspace.toUpperCase()}-${existing.length + 1}`,
-            status: "open",
-            comments: [],
-          };
-
-          issues.set(workspace, [...existing, issue]);
+        if (issue === undefined) {
+          return yield* new IssueNotFound({ id });
+        }
+
+        return issue;
+      });
 
+      // No `yield*` between the read and the write: a fiber may be set aside at one, and two
+      // changes that each read the issue before either wrote would keep only the second. A
+      // database does this in one statement or a transaction.
+      // A change `to` answers with the same issue for is no change, and is not published.
+      const change = Effect.fn("IssueStore.change")(function* (
+        workspace: string,
+        id: string,
+        to: (issue: Issue) => Issue,
+        kind: (typeof IssueChange.Type)["change"],
+        comment?: typeof Comment.Type
+      ) {
+        const issue = of(workspace).find((candidate) => candidate.id === id);
+
+        if (issue === undefined) {
+          return yield* new IssueNotFound({ id });
+        }
+
+        const changed = to(issue);
+
+        if (changed === issue) {
           return issue;
-        }),
-      comment: (workspace, id, comment) =>
-        change(workspace, id, (issue) => ({ ...issue, comments: [...issue.comments, comment] })),
-      close: (workspace, id) => change(workspace, id, (issue) => ({ ...issue, status: "closed" })),
-    });
-  });
+        }
+
+        issues.set(
+          workspace,
+          of(workspace).map((current) =>
+            current === issue ? changed : current
+          )
+        );
+
+        publish(workspace, changed, kind, comment);
+
+        return changed;
+      });
+
+      return IssueStore.of({
+        list: (workspace, status, limit) =>
+          Effect.sync(() =>
+            having(workspace, status).toReversed().slice(0, limit)
+          ),
+        // A database reads it in pages, by id, so an export never holds the workspace whole.
+        all: (workspace, status) =>
+          Stream.suspend(() => Stream.fromIterable(having(workspace, status))),
+        count: (workspace, status) =>
+          Effect.sync(() => having(workspace, status).length),
+        get,
+        create: (workspace, draft) =>
+          Effect.sync(() => {
+            const existing = of(workspace);
+
+            const issue: Issue = {
+              ...draft,
+              id: `${workspace.toUpperCase()}-${existing.length + 1}`,
+              status: "open",
+              comments: [],
+            };
+
+            issues.set(workspace, [...existing, issue]);
+            publish(workspace, issue, "filed");
+
+            return issue;
+          }),
+        comment: (workspace, id, comment) =>
+          change(
+            workspace,
+            id,
+            (issue) => ({ ...issue, comments: [...issue.comments, comment] }),
+            "commented",
+            comment
+          ),
+        close: (workspace, id) =>
+          change(
+            workspace,
+            id,
+            (issue) =>
+              issue.status === "closed"
+                ? issue
+                : { ...issue, status: "closed" },
+            "closed"
+          ),
+        changes: Stream.fromPubSub(changes),
+      });
+    })
+  );
 }

package/examples/kitchen-sink/src/issues/write-limit.ts

@@ -1,28 +1,25 @@
 import { Duration, Effect } from "effect";
 import { RateLimiter } from "effect/persistence";
-import { CurrentMember, type Member } from "../identity/Identity.js";
+
+import { CurrentMember } from "../identity/Identity.js";
+import type { Member } from "../identity/Identity.js";
 import { RateLimited } from "./Issues.js";
 
-// The write limit: ten writes a minute per member. It is the handlers', not a surface's, so it
-// holds wherever they run: HTTP, MCP, RPC, stdio and the assistant's tools all count against
-// the one limiter. A builder yields this once and wraps each limited handler in the function
-// it gets, which fails with an error those actions' contracts declare; every surface sends it
-// as any declared error. The limiter is a service, so its counts are shared wherever it is
-// provided: memory.ts provides Effect's own, `RateLimiter.layer` over a store. `consume` counts
-// in a fixed window unless given `algorithm: "token-bucket"`: ten writes in each minute, so
-// twenty may pass across the boundary between two. A strict limit, ten in any sixty seconds,
-// is a service of your own of the same shape, yielded here, never part of the issue store.
-export const writeLimit = Effect.gen(function* () {
+const limitedBy = Effect.gen(function* () {
   const limiter = yield* RateLimiter.RateLimiter;
 
-  return <A, E, R>(write: (member: Member) => Effect.Effect<A, E, R>) =>
+  return <A, E, R>(
+    name: string,
+    limit: number,
+    run: (member: Member) => Effect.Effect<A, E, R>
+  ) =>
     Effect.gen(function* () {
       const member = yield* CurrentMember;
 
       yield* limiter
         .consume({
-          key: JSON.stringify(["writes", member.workspace, member.id]),
-          limit: 10,
+          key: JSON.stringify([name, member.workspace, member.id]),
+          limit,
           window: "1 minute",
           onExceeded: "fail",
         })
@@ -31,12 +28,41 @@ export const writeLimit = Effect.gen(function* () {
             "RateLimiterError",
             "RateLimitExceeded",
             ({ retryAfter }) =>
-              Effect.fail(new RateLimited({ retryAfterSeconds: Duration.toSeconds(retryAfter) })),
+              Effect.fail(
+                new RateLimited({
+                  retryAfterSeconds: Duration.toSeconds(retryAfter),
+                })
+              ),
             // Any other reason is the limiter's store failing: a defect, not the caller's.
-            Effect.die,
-          ),
+            Effect.die
+          )
         );
 
-      return yield* write(member);
+      return yield* run(member);
     });
 });
+
+// The write limit: ten writes a minute per member. It is the handlers', not a surface's, so it
+// holds wherever they run: HTTP, MCP, RPC, stdio and the assistant's tools all count against
+// the one limiter. A builder yields this once and wraps each limited handler in the function
+// it gets, which fails with an error those actions' contracts declare; every surface sends it
+// as any declared error. The limiter is a service, so its counts are shared wherever it is
+// provided: memory.ts provides Effect's own, `RateLimiter.layer` over a store. `consume` counts
+// in a fixed window unless given `algorithm: "token-bucket"`: ten writes in each minute, so
+// twenty may pass across the boundary between two. A strict limit, ten in any sixty seconds,
+// is a service of your own of the same shape, yielded here, never part of the issue store.
+export const writeLimit = Effect.gen(function* () {
+  const limited = yield* limitedBy;
+
+  return <A, E, R>(write: (member: Member) => Effect.Effect<A, E, R>) =>
+    limited("writes", 10, write);
+});
+
+// The export limit: two exports a minute per member, on the same limiter under a key of its
+// own, so exporting spends no write.
+export const exportLimit = Effect.gen(function* () {
+  const limited = yield* limitedBy;
+
+  return <A, E, R>(read: (member: Member) => Effect.Effect<A, E, R>) =>
+    limited("exports", 2, read);
+});

package/examples/kitchen-sink/src/memory.ts

@@ -1,5 +1,7 @@
+import * as Event from "@gjermundgaraba/effect-actions/Event";
 import { Layer } from "effect";
 import { RateLimiter } from "effect/persistence";
+
 import { Grants } from "./admin/grants.js";
 import { Conversations } from "./assistant/conversations.js";
 import { demoModel } from "./assistant/demo-model.js";
@@ -13,10 +15,14 @@ import { WorkspaceRegistry } from "./workspaces/registry.js";
 // test replaces the one it is about.
 
 /** Both stores. The attachment store is built on the issue store: `provideMerge` keeps it. */
-export const stores = AttachmentStore.layerMemory.pipe(Layer.provideMerge(IssueStore.layerMemory));
+export const stores = AttachmentStore.layerMemory.pipe(
+  Layer.provideMerge(IssueStore.layerMemory)
+);
 
 /** Effect's own limiter, counting in memory. `RateLimiter.layerStoreRedis` counts across processes. */
-export const limiter = RateLimiter.layer.pipe(Layer.provide(RateLimiter.layerStoreMemory));
+export const limiter = RateLimiter.layer.pipe(
+  Layer.provide(RateLimiter.layerStoreMemory)
+);
 
 /** Everything the server needs, for both ports. A local entrypoint provides only what it serves. */
 export const memory = Layer.mergeAll(
@@ -27,4 +33,7 @@ export const memory = Layer.mergeAll(
   Grants.layerDemo,
   Conversations.layerMemory,
   demoModel,
+  // The issue changes' log, kept in this process for the subscribers its sockets and streams
+  // hold.
+  Event.layerMemory
 );

package/examples/kitchen-sink/src/ops.ts

@@ -1,8 +1,10 @@
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import { Effect, Layer } from "effect";
 import { Command } from "effect/cli";
-import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
-import { Operator, type TrustedOperator } from "./admin/Admin.js";
+
+import { Operator } from "./admin/Admin.js";
+import type { TrustedOperator } from "./admin/Admin.js";
 import { Grants } from "./admin/grants.js";
 import { admin } from "./admin/handlers.js";
 import { WorkspaceRegistry } from "./workspaces/registry.js";
@@ -19,7 +21,10 @@ const ops = ActionCli.make(admin, {
     listWorkspaces: {
       render: ({ workspaces }) =>
         workspaces
-          .map(({ slug, name, suspended }) => `${slug}  ${name}${suspended ? "  (suspended)" : ""}`)
+          .map(
+            ({ slug, name, suspended }) =>
+              `${slug}  ${name}${suspended ? "  (suspended)" : ""}`
+          )
           .join("\n"),
     },
     suspendWorkspace: { positional: ["workspace"] },
@@ -29,11 +34,11 @@ const ops = ActionCli.make(admin, {
   // Only what these actions are built from. DEMO ONLY: memory, so this console sees its own
   // process, not the server's data. A real one provides the database Layers the server does.
   Command.provide(Layer.merge(WorkspaceRegistry.layerMemory, Grants.layerDemo)),
-  Command.provideSync(Operator, operator),
+  Command.provideSync(Operator, operator)
 );
 
 Command.run(ops, { version: "1.0.0" }).pipe(
   Effect.provide(NodeServices.layer),
   ActionCli.logToStderr,
-  NodeRuntime.runMain,
+  NodeRuntime.runMain()
 );

package/examples/kitchen-sink/src/request-policy.ts

@@ -1,5 +1,6 @@
 import { Effect, Layer, Option } from "effect";
 import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
+
 import { allowedOrigins, publicUrl } from "./config.js";
 
 const loopback = ["localhost", "127.0.0.1"];
@@ -13,32 +14,39 @@ const loopback = ["localhost", "127.0.0.1"];
 // authentication, too late.
 export const requestPolicy = HttpRouter.middleware(
   Effect.gen(function* () {
-    const hosts = [...loopback, new URL(yield* publicUrl).hostname];
+    const hosts = new Set([...loopback, new URL(yield* publicUrl).hostname]);
     const origins = yield* allowedOrigins;
 
     return (httpEffect) =>
       Effect.gen(function* () {
         const request = yield* HttpServerRequest.HttpServerRequest;
-        const url = HttpServerRequest.toURL(request.modify({ url: request.originalUrl }));
 
-        if (Option.isNone(url) || !hosts.includes(url.value.hostname)) {
+        const url = HttpServerRequest.toURL(
+          request.modify({ url: request.originalUrl })
+        );
+
+        if (Option.isNone(url) || !hosts.has(url.value.hostname)) {
           return HttpServerResponse.text("Host not allowed", { status: 403 });
         }
 
-        const origin = request.headers["origin"];
+        const { origin } = request.headers;
 
         // The request's own origin is that of a page served from this port directly. Behind a
         // proxy ending TLS it is an `http:` one from Effect 4.0.6, whose `originalUrl` takes the
         // scheme of the connection, whatever `X-Forwarded-Proto` says, so the public URL's
         // origin is among `origins`.
-        if (origin !== undefined && origin !== url.value.origin && !origins.includes(origin)) {
+        if (
+          origin !== undefined &&
+          origin !== url.value.origin &&
+          !origins.includes(origin)
+        ) {
           return HttpServerResponse.text("Origin not allowed", { status: 403 });
         }
 
         return yield* httpEffect;
       });
   }),
-  { global: true },
+  { global: true }
 );
 
 // CORS for the one cross-origin caller, a browser MCP client. `HttpRouter.cors` is global to
@@ -61,7 +69,11 @@ export const cors = Layer.unwrap(
         "MCP-Name",
         "Mcp-Session-Id",
       ],
-      exposedHeaders: ["WWW-Authenticate", "MCP-Protocol-Version", "Mcp-Session-Id"],
-    }),
-  ),
+      exposedHeaders: [
+        "WWW-Authenticate",
+        "MCP-Protocol-Version",
+        "Mcp-Session-Id",
+      ],
+    })
+  )
 );