@nice-code/action 0.2.8 → 0.2.10

package/README.md

@@ -1 +1,273 @@
-# @nice-code/action-test
+# @nice-code/action
+
+Typed, transport-agnostic action system for calling functions across client/server boundaries with full TypeScript inference.
+
+## Install
+
+```bash
+bun add @nice-code/action
+```
+
+Peer deps: `valibot` (or any [Standard Schema](https://github.com/standard-schema/standard-schema) library), `@tanstack/react-query` (for `@nice-code/action/react-query`).
+
+## Core concepts
+
+- **ActionDomain** — a named group of typed actions (like an API surface)
+- **ActionSchema** — input/output schema + declared error types for one action
+- **ActionRuntime** — processes incoming requests and dispatches them to handlers
+- **ActionLocalHandler** — executes actions in the current process
+- **ActionExternalClientHandler** — forwards/receives actions over HTTP or WebSocket
+- **RuntimeCoordinate** — identifies an environment (frontend, backend, worker…)
+
+---
+
+## Defining actions
+
+### 1. Create a root domain (shared between client and server)
+
+```ts
+import { createActionRootDomain, actionSchema } from "@nice-code/action";
+import * as v from "valibot";
+
+// Root domain — no actions, just a namespace anchor
+export const appRoot = createActionRootDomain({ domain: "app_root" });
+
+// Child domain with actions
+export const userDomain = appRoot.createChildDomain({
+  domain: "user",
+  actions: {
+    getUser: actionSchema()
+      .input({ schema: v.object({ userId: v.string() }) })
+      .output({ schema: v.object({ id: v.string(), name: v.string() }) })
+      .throws(err_user, ["not_found"]),  // from @nice-code/error
+
+    updateName: actionSchema()
+      .input({ schema: v.object({ userId: v.string(), name: v.string() }) })
+      .output({ schema: v.object({ success: v.boolean() }) }),
+  },
+});
+```
+
+### 2. Serialization for non-JSON-native types
+
+```ts
+createAt: actionSchema()
+  .output(
+    { schema: v.object({ createdAt: v.date() }) },
+    ({ createdAt }) => ({ createdAt: createdAt.toISOString() }),  // serialize
+    ({ createdAt }) => ({ createdAt: new Date(createdAt) }),       // deserialize
+  ),
+```
+
+### 3. Declare thrown errors
+
+```ts
+import { defineNiceError, err } from "@nice-code/error";
+
+const err_user = defineNiceError({
+  domain: "err_user",
+  schema: {
+    not_found: err<{ userId: string }>({
+      message: ({ userId }) => `User not found: ${userId}`,
+      httpStatusCode: 404,
+      context: { required: true },
+    }),
+  },
+} as const);
+
+// Attach to an action schema
+actionSchema()
+  .throws(err_user)                        // any id from err_user
+  .throws(err_user, ["not_found"])          // only specific ids
+```
+
+---
+
+## Setting up runtimes
+
+### Server (local handler)
+
+```ts
+import { ActionRuntime, createLocalHandler, RuntimeCoordinate } from "@nice-code/action";
+
+// Identify this environment
+export const serverCoord = RuntimeCoordinate.env("backend");
+
+// Implement the actions
+const userHandler = createLocalHandler()
+  .forDomain(userDomain, async (request) => {
+    if (request.id === "getUser") {
+      const user = await db.users.find(request.input.userId);
+      if (!user) throw err_user.fromId("not_found", { userId: request.input.userId });
+      return user;
+    }
+  });
+
+// Or use the map syntax (preferred)
+const userHandler = createLocalHandler().forDomainActionCases(userDomain, {
+  getUser: async (req) => {
+    const user = await db.users.find(req.input.userId);
+    if (!user) throw err_user.fromId("not_found", { userId: req.input.userId });
+    return user;
+  },
+  updateName: async (req) => {
+    await db.users.update(req.input.userId, { name: req.input.name });
+    return { success: true };
+  },
+});
+
+// Or wrap an object directly
+const userHandler = userDomain.wrapAsLocalHandler({
+  getUser: async ({ userId }) => { /* ... */ },
+  updateName: async ({ userId, name }) => { /* ... */ },
+});
+
+// Wire up the runtime
+export const serverRuntime = new ActionRuntime(serverCoord)
+  .addHandlers([userHandler])
+  .apply();
+```
+
+### Handling incoming requests (HTTP endpoint)
+
+```ts
+// Hono example
+app.post("/resolve_action", async (c) => {
+  const wire = await c.req.json();
+  const runningAction = await serverRuntime.handleActionPayloadWire(wire);
+  const result = await runningAction.waitForResultPayload();
+  return c.json(result.toJsonObject());
+});
+```
+
+### Client (external handler)
+
+```ts
+import {
+  ActionRuntime,
+  ActionExternalClientHandler,
+  RuntimeCoordinate,
+  ETransportType,
+  ETransportStatus,
+} from "@nice-code/action";
+
+export const clientCoord = RuntimeCoordinate.env("frontend");
+export const serverCoord = RuntimeCoordinate.env("backend");
+
+const serverHandler = new ActionExternalClientHandler({
+  externalClientSpecifier: serverCoord,
+  transports: [
+    {
+      type: ETransportType.http,
+      initialize: () => ({
+        getTransport: () => ({
+          status: ETransportStatus.ready,
+          readyData: {
+            createRequest: () => ({ url: "https://api.example.com/resolve_action" }),
+          },
+        }),
+      }),
+    },
+  ],
+}).forDomain(userDomain);
+
+export const clientRuntime = new ActionRuntime(clientCoord)
+  .addHandlers([serverHandler])
+  .apply();
+```
+
+---
+
+## Calling actions
+
+```ts
+// Create a request payload
+const request = userDomain.action.getUser.request({ userId: "u_123" });
+
+// Run it — returns a RunningAction
+const runningAction = await userDomain.runAction(request);
+
+// Wait for the result
+const result = await runningAction.waitForResultPayload();
+console.log(result.output); // { id: "u_123", name: "Alice" }
+
+// Or run and get the output directly (throws on error)
+const output = await userDomain.action.getUser
+  .request({ userId: "u_123" })
+  .runToOutput();
+```
+
+---
+
+## React Query integration
+
+```ts
+import { useActionQuery, useActionMutation } from "@nice-code/action/react-query";
+
+// Query
+function UserProfile({ userId }: { userId: string }) {
+  const { data } = useActionQuery(
+    userDomain.action.getUser,
+    { userId },
+    { queryKey: ["user", userId] },
+  );
+  return <div>{data?.name}</div>;
+}
+
+// Mutation
+function RenameUser() {
+  const { mutate } = useActionMutation(userDomain.action.updateName);
+  return <button onClick={() => mutate({ userId: "u_1", name: "Bob" })}>Rename</button>;
+}
+```
+
+---
+
+## WebSocket transport
+
+```ts
+{
+  type: ETransportType.ws,
+  initialize: () => ({
+    getTransport: () => ({
+      status: ETransportStatus.ready,
+      readyData: {
+        ws: new WebSocket("wss://api.example.com/resolve_action/ws"),
+      },
+    }),
+  }),
+}
+```
+
+Multiple transports can be registered; the runtime picks the best available one (WebSocket preferred for lower latency, HTTP as fallback).
+
+---
+
+## RuntimeCoordinate
+
+Identifies a runtime environment and is used to route actions to the right handler.
+
+```ts
+RuntimeCoordinate.env("backend")                   // named env
+RuntimeCoordinate.env("backend").specify({ perId: "worker-1" }) // env + instance
+RuntimeCoordinate.unknown                           // unspecified
+```
+
+---
+
+## Error handling in actions
+
+Actions declared with `.throws(domain, ids?)` surface typed errors at the call site:
+
+```ts
+import { castNiceError } from "@nice-code/error";
+
+try {
+  const output = await userDomain.action.getUser.request({ userId }).runToOutput();
+} catch (e) {
+  const error = castNiceError(e);
+  if (err_user.isExact(error) && error.hasId("not_found")) {
+    console.log("User not found:", error.getContext("not_found").userId);
+  }
+}
+```