@akterjs/client 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@akterjs/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Effect and Promise clients for calling Akter actors from Bun, Node, Workers and browsers.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rika-Labs/akter.git",
+    "directory": "packages/client"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#src/*": "./src/*",
+    "#tests/*": "./tests/*.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/promise-client.adapter.d.mts",
+      "default": "./dist/promise-client.adapter.mjs"
+    },
+    "./effect": {
+      "types": "./dist/akter-client.layer.d.mts",
+      "default": "./dist/akter-client.layer.mjs"
+    },
+    "./operations": {
+      "types": "./dist/actor-operations.pure.d.mts",
+      "default": "./dist/actor-operations.pure.mjs"
+    },
+    "./actor-rpc": {
+      "types": "./dist/actor-rpc.pure.d.mts",
+      "default": "./dist/actor-rpc.pure.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@akterjs/effect": "0.1.1",
+    "@akterjs/workerd-test": "0.0.0",
+    "@effect/platform-node": "4.1.2",
+    "@effect/vitest": "4.1.2",
+    "@vitest/browser-playwright": "5.1.0",
+    "effect": "4.1.2",
+    "esbuild": "0.28.2",
+    "mutant-cafe": "0.1.6",
+    "playwright": "1.65.0",
+    "publint": "0.3.25",
+    "tsdown": "0.23.5",
+    "vitest": "5.1.0"
+  },
+  "peerDependencies": {
+    "@akterjs/effect": "0.1.1",
+    "effect": "4.1.2"
+  },
+  "scripts": {
+    "typecheck": "effect-tsgo tsrs --noEmit -p tsconfig.json",
+    "lint": "effect-tsgo --tsrs-lint oxlint -c ../../oxlint.config.ts --type-aware --tsconfig tsconfig.json src tests",
+    "test": "vitest run",
+    "test:browser": "vitest run --mode browser",
+    "test:workerd": "workerd-test",
+    "build": "tsdown",
+    "mutants": "VITEST_MAX_WORKERS=1 mutant-cafe --advisory && node ../../node_modules/@rikalabs/rules/src/mutants/mutants.cli.mjs --all",
+    "mutants:diff": "VITEST_MAX_WORKERS=1 mutant-cafe --in-diff-range main...HEAD --advisory && node ../../node_modules/@rikalabs/rules/src/mutants/mutants.cli.mjs"
+  }
 }

package/src/actor-fields.pure.ts

@@ -0,0 +1,60 @@
+import { Array as Arr, Record as Rec } from "effect";
+import type { Schema } from "effect";
+
+type JsonObject = Schema.JsonObject;
+
+// The fields an actor operation takes, as its tool's input and the CLI's flags, with each one's JSON Schema.
+const fieldSchemas = {
+  actor: { description: "The actor's name in the app, such as Sale.", type: "string" },
+  after: {
+    description: "Only log lines after this seq, the last one a page before printed, to read on from there.",
+    type: "integer",
+  },
+  commandId: {
+    description: "An id for this call, so a retry with the same id runs it once. A new one is made when it is missing.",
+    type: "string",
+  },
+  computer: { description: "The computer's name, as the actor named it.", type: "string" },
+  computerPath: { description: "Relative path in the computer's files directory.", type: "string" },
+  content: { description: "The file's bytes, as base64.", type: "string" },
+  cursor: { description: "Where the page to read starts, from the cursor of the page before.", type: "string" },
+  direction: {
+    description: "toComputer or fromComputer; copy-back returns an upload receipt.",
+    enum: ["toComputer", "fromComputer"],
+    type: "string",
+  },
+  into: { description: "The new actor's key, as JSON. A bare word is taken as a string key." },
+  key: { description: "The actor's key, as JSON. A bare word is taken as a string key." },
+  length: { description: "How many bytes to read, from offset; give both or neither.", type: "integer" },
+  limit: { description: "The most entries to return.", type: "integer" },
+  member: { description: "The command or query to run.", type: "string" },
+  offset: { description: "The byte to start reading at, with length; give both or neither.", type: "integer" },
+  path: { description: "The file's path in the actor, such as photos/cat.png.", type: "string" },
+  payload: { description: "The command's, query's or create input's payload, as JSON." },
+  prefix: { description: "Only paths that start with this.", type: "string" },
+  step: { description: "The step's id, as steps list prints it.", type: "string" },
+} satisfies Readonly<Record<string, JsonObject>>;
+
+type FieldName = keyof typeof fieldSchemas;
+
+const optional: readonly FieldName[] = [
+  "after",
+  "commandId",
+  "cursor",
+  "length",
+  "limit",
+  "offset",
+  "payload",
+  "prefix",
+];
+
+const inputOf = (fields: readonly FieldName[]): JsonObject => ({
+  additionalProperties: false,
+  properties: Rec.fromEntries(Arr.map(fields, (name) => [name, fieldSchemas[name]] as const)),
+  required: Arr.filter(fields, (name) => !Arr.contains(optional, name)),
+  type: "object",
+});
+
+export { inputOf };
+
+export type { FieldName };

package/src/actor-operations.pure.ts

@@ -0,0 +1,484 @@
+import { Array as Arr, Effect, Option, Record as Rec, SchemaAST, String as Str } from "effect";
+import type { Schema } from "effect";
+import { SecureRandom } from "effect/crypto";
+import type { Rpc } from "effect/rpc";
+import { RpcSchema } from "effect/rpc";
+
+import { inputOf } from "./actor-fields.pure.js";
+import type { FieldName } from "./actor-fields.pure.js";
+
+type JsonObject = Schema.JsonObject;
+
+// MCP hints matching the Cloud API; this package imports only contracts.
+interface Annotations {
+  readonly confirm: boolean;
+  readonly destructive: boolean;
+  readonly idempotent: boolean;
+  readonly openWorld: boolean;
+  readonly readOnly: boolean;
+}
+
+type ActorKind =
+  | "call"
+  | "computers/cp"
+  | "computers/delete"
+  | "computers/get"
+  | "computers/list"
+  | "computers/logs"
+  | "computers/pause"
+  | "computers/resume"
+  | "computers/stop"
+  | "create"
+  | "ensure"
+  | "files/download"
+  | "files/list"
+  | "files/upload"
+  | "files/usage"
+  | "fork"
+  | "query"
+  | "state"
+  | "steps/get"
+  | "steps/list"
+  | "warm"
+  | "watch";
+
+// An actor RPC operation (ADR 0016), shared by the CLI and MCP.
+interface ActorOperation {
+  readonly annotations: Annotations;
+  // The feature flag the operation is behind, as a Cloud API operation's (akter-cloud ADR 0030): the CLI leaves it out
+  // Of the help and the MCP server lists it to nobody until it reads the caller's flags.
+  readonly flag: Option.Option<string>;
+  readonly command: readonly [string, string];
+  readonly description: string;
+  readonly fields: readonly FieldName[];
+  readonly id: string;
+  readonly input: JsonObject;
+  readonly kind: ActorKind;
+  readonly stream: boolean;
+  readonly tool: string;
+}
+
+interface Declared {
+  readonly description: string;
+  readonly flag?: string;
+  readonly fields: readonly FieldName[];
+  readonly kind: ActorKind;
+  readonly readOnly: boolean;
+  readonly idempotent: boolean;
+}
+
+// Files and computers have command groups; the rest are under actors.
+const group = "actors";
+
+const commandOfKind = (kind: ActorKind): readonly [string, string] => {
+  const [owner, name] = Str.split("/")(kind);
+
+  return Option.match(Option.fromUndefinedOr(name), {
+    onNone: () => [group, kind] as const,
+    onSome: (found) => [owner, found] as const,
+  });
+};
+
+const subscribe = "/subscribe";
+
+const declared: readonly Declared[] = [
+  {
+    description: "Run one of an actor's commands and print its reply.",
+    fields: ["actor", "key", "member", "payload", "commandId"],
+    idempotent: false,
+    kind: "call",
+    readOnly: false,
+  },
+  {
+    description: "Run one of an actor's queries and print its reply.",
+    fields: ["actor", "key", "member", "payload"],
+    idempotent: true,
+    kind: "query",
+    readOnly: true,
+  },
+  {
+    description: "Print an actor's state once.",
+    fields: ["actor", "key"],
+    idempotent: true,
+    kind: "state",
+    readOnly: true,
+  },
+  {
+    description: "Print a query's reply, then each new reply as the actor changes, one JSON line each.",
+    fields: ["actor", "key", "member", "payload"],
+    idempotent: true,
+    kind: "watch",
+    readOnly: true,
+  },
+  {
+    description: "Create an actor from its create input; fails when it already exists.",
+    fields: ["actor", "key", "payload", "commandId"],
+    idempotent: false,
+    kind: "create",
+    readOnly: false,
+  },
+  {
+    description: "Create an actor from its create input unless it already exists.",
+    fields: ["actor", "key", "payload", "commandId"],
+    idempotent: true,
+    kind: "ensure",
+    readOnly: false,
+  },
+  {
+    description: "List an actor's files a page at a time, with each path, size, digest and write time.",
+    fields: ["actor", "key", "prefix", "cursor", "limit"],
+    idempotent: true,
+    kind: "files/list",
+    readOnly: true,
+  },
+  {
+    description: "List an actor's files a page at a time, with the total bytes they hold.",
+    fields: ["actor", "key", "prefix", "cursor", "limit"],
+    idempotent: true,
+    kind: "files/usage",
+    readOnly: true,
+  },
+  {
+    description: "Download one of an actor's files, whole or the byte range offset and length give.",
+    fields: ["actor", "key", "path", "offset", "length"],
+    idempotent: true,
+    kind: "files/download",
+    readOnly: true,
+  },
+  {
+    description: "Upload a file for an actor and print its receipt, which a command attaches at a path.",
+    fields: ["actor", "key", "content"],
+    idempotent: false,
+    kind: "files/upload",
+    readOnly: false,
+  },
+  {
+    description:
+      "Fork an actor into a new actor at another key: a copy of its state and files at one moment, with none of its " +
+      "work in flight (its jobs, timers and undelivered messages stay with the original). A retry with the same " +
+      "commandId makes one copy.",
+    fields: ["actor", "key", "into", "commandId"],
+    idempotent: false,
+    kind: "fork",
+    readOnly: false,
+  },
+  {
+    description: "List an actor's computers, each with its image, size, egress and state.",
+    fields: ["actor", "key"],
+    idempotent: true,
+    kind: "computers/list",
+    readOnly: true,
+  },
+  {
+    description:
+      "Copy one file (at most 1 MiB) between an actor and its computer. fromComputer returns a receipt; attach it with an actor command.",
+    fields: ["actor", "key", "computer", "direction", "path", "computerPath"],
+    flag: "computerFiles",
+    idempotent: false,
+    kind: "computers/cp",
+    readOnly: false,
+  },
+  {
+    description: "Show one of an actor's computers: its image, size, egress and state.",
+    fields: ["actor", "key", "computer"],
+    idempotent: true,
+    kind: "computers/get",
+    readOnly: true,
+  },
+  {
+    description: "Read a page of a computer's log, oldest first; pass the last seq printed as after to read on.",
+    fields: ["actor", "key", "computer", "after", "limit"],
+    idempotent: true,
+    kind: "computers/logs",
+    readOnly: true,
+  },
+  {
+    description: "Pause a computer, keeping its memory and disk, and print it.",
+    fields: ["actor", "key", "computer"],
+    idempotent: true,
+    kind: "computers/pause",
+    readOnly: false,
+  },
+  {
+    description: "Resume a paused computer and print it; fails while a fork holds it.",
+    fields: ["actor", "key", "computer"],
+    idempotent: true,
+    kind: "computers/resume",
+    readOnly: false,
+  },
+  {
+    description: "Stop a computer, keeping its disk, and print it.",
+    fields: ["actor", "key", "computer"],
+    idempotent: true,
+    kind: "computers/stop",
+    readOnly: false,
+  },
+  {
+    description: "Delete a computer and its disk. The actor's own jobs make computers; this only removes one.",
+    fields: ["actor", "key", "computer"],
+    idempotent: true,
+    kind: "computers/delete",
+    readOnly: false,
+  },
+  {
+    description:
+      "List an actor's durable computer steps, newest first: each one's job, name, computer, command and state, and its exit code once it ran.",
+    fields: ["actor", "key", "limit"],
+    flag: "computerSteps",
+    idempotent: true,
+    kind: "steps/list",
+    readOnly: true,
+  },
+  {
+    description:
+      "Show one of an actor's durable computer steps with its output. A step in state unknown may have done its work; reconcile it by its id.",
+    fields: ["actor", "key", "step"],
+    flag: "computerSteps",
+    idempotent: true,
+    kind: "steps/get",
+    readOnly: true,
+  },
+  {
+    description: "Load an actor ahead of its first call, so that call answers sooner.",
+    fields: ["actor", "key"],
+    idempotent: true,
+    kind: "warm",
+    readOnly: true,
+  },
+];
+
+const streams: readonly ActorKind[] = ["files/download", "state", "watch"];
+
+// Kinds that remove something for good, so the CLI asks a person first and an MCP client confirms (ADR 0023).
+const dangerous: readonly ActorKind[] = ["computers/delete"];
+
+const operationOf = ({ description, fields, flag, idempotent, kind, readOnly }: Declared): ActorOperation => {
+  const [owner, name] = commandOfKind(kind);
+  const confirm = Arr.contains(dangerous, kind);
+
+  const operation: ActorOperation = {
+    annotations: { confirm, destructive: confirm, idempotent, openWorld: false, readOnly },
+    command: [owner, name],
+    description,
+    fields,
+    flag: Option.fromUndefinedOr(flag),
+    id: `${owner}.${name}`,
+    input: inputOf(fields),
+    kind,
+    stream: Arr.contains(streams, kind),
+    tool: `${owner}_${name}`,
+  };
+
+  if (kind === "computers/cp") {
+    return { ...operation, tool: "computers_files" };
+  }
+
+  return operation;
+};
+
+// Internal kinds, with no command or tool.
+const unexposedKinds: readonly ActorKind[] = ["warm"];
+
+const actorOperations: readonly ActorOperation[] = Arr.map(
+  Arr.filter(declared, ({ kind }) => !Arr.contains(unexposedKinds, kind)),
+  operationOf,
+);
+
+// The RPC tag a kind sends for an actor and member (akter ADR 0016).
+interface Addressed {
+  readonly actor: string;
+  readonly kind: ActorKind;
+  readonly member: string;
+}
+
+const tagOf = ({ actor, kind, member }: Addressed): string => {
+  const tags: Readonly<Record<ActorKind, string>> = {
+    call: `${actor}/${member}`,
+    "computers/cp": `${actor}/computer/files`,
+    "computers/delete": `${actor}/computer/delete`,
+    "computers/get": `${actor}/computer/get`,
+    "computers/list": `${actor}/computer/list`,
+    "computers/logs": `${actor}/computer/logs`,
+    "computers/pause": `${actor}/computer/pause`,
+    "computers/resume": `${actor}/computer/resume`,
+    "computers/stop": `${actor}/computer/stop`,
+    create: `${actor}/create`,
+    ensure: `${actor}/ensure`,
+    "files/download": `${actor}/files/download`,
+    "files/list": `${actor}/files/list`,
+    "files/upload": `${actor}/files/upload`,
+    "files/usage": `${actor}/files/usage`,
+    fork: `${actor}/fork`,
+    query: `${actor}/${member}`,
+    state: `${actor}/state${subscribe}`,
+    "steps/get": `${actor}/computer/step`,
+    "steps/list": `${actor}/computer/steps`,
+    warm: `${actor}/warm`,
+    watch: `${actor}/${member}${subscribe}`,
+  };
+
+  return tags[kind];
+};
+
+// The payload fields an RPC takes, sorted, such as "commandId,key,payload".
+const payloadFields = (rpc: Rpc.AnyWithProps): string => {
+  const names = Option.match(Option.liftPredicate(rpc.payloadSchema.ast, SchemaAST.isObjects), {
+    onNone: () => [],
+    onSome: (ast) => Arr.map(ast.propertySignatures, ({ name }) => String(name)),
+  });
+
+  return Arr.join(Arr.sort(names, Str.Order), ",");
+};
+
+interface RpcSignature {
+  readonly fields: string;
+  readonly kind: ActorKind;
+  readonly stream: boolean;
+}
+
+// What each kind's RPC takes and whether it streams. Kinds with a fixed member are matched by it first.
+const fixedMembers = {
+  create: { fields: "commandId,key,payload", kind: "create", stream: false },
+  ensure: { fields: "commandId,key,payload", kind: "ensure", stream: false },
+  fork: { fields: "commandId,into,key", kind: "fork", stream: false },
+  state: { fields: "key", kind: "state", stream: true },
+  warm: { fields: "key", kind: "warm", stream: false },
+} satisfies Readonly<Record<string, RpcSignature>>;
+
+const anyMember: readonly RpcSignature[] = [
+  { fields: "commandId,key,payload", kind: "call", stream: false },
+  { fields: "key,payload", kind: "query", stream: false },
+  { fields: "key,payload", kind: "watch", stream: true },
+];
+
+// The file RPCs, by the tag after the actor's name. An upload is a session of three RPCs, so all three are its kind.
+const fileRpcs = {
+  "files/download": { fields: "key,length,offset,path", kind: "files/download", stream: true },
+  "files/list": { fields: "cursor,key,limit,prefix", kind: "files/list", stream: false },
+  "files/upload/append": { fields: "bytes,key,offset,upload", kind: "files/upload", stream: false },
+  "files/upload/close": { fields: "bytes,key,upload", kind: "files/upload", stream: false },
+  "files/upload/open": { fields: "key", kind: "files/upload", stream: false },
+  "files/usage": { fields: "cursor,key,limit,prefix", kind: "files/usage", stream: false },
+} satisfies Readonly<Record<string, RpcSignature>>;
+
+// The computer RPCs, by the tag after the actor's name: none streams, and only the actor makes or runs computers.
+const computerRpcs = {
+  "computer/delete": { fields: "computer,key", kind: "computers/delete", stream: false },
+  "computer/files": { fields: "computer,computerPath,direction,key,path", kind: "computers/cp", stream: false },
+  "computer/get": { fields: "computer,key", kind: "computers/get", stream: false },
+  "computer/list": { fields: "key", kind: "computers/list", stream: false },
+  "computer/logs": { fields: "after,computer,key,limit", kind: "computers/logs", stream: false },
+  "computer/pause": { fields: "computer,key", kind: "computers/pause", stream: false },
+  "computer/resume": { fields: "computer,key", kind: "computers/resume", stream: false },
+  "computer/step": { fields: "key,step", kind: "steps/get", stream: false },
+  "computer/steps": { fields: "key,limit", kind: "steps/list", stream: false },
+  "computer/stop": { fields: "computer,key", kind: "computers/stop", stream: false },
+} satisfies Readonly<Record<string, RpcSignature>>;
+
+const nestedRpcs = { ...fileRpcs, ...computerRpcs } satisfies Readonly<Record<string, RpcSignature>>;
+
+// Members reserved for RPCs of their own (akter ADR 0016): no actor may declare them, so they are never a call or
+// Query. `fork` is one RPC with its own signature above; `files` and `computer` name groups of them.
+const laterMembers = ["computer", "files"];
+
+// `<Actor>/<rest>`: the rest names a file or computer RPC, or a member with or without /subscribe.
+const actorRest = /^[^/]+\/(?<rest>.+)$/u;
+
+// `<Actor>/<member>` or `<Actor>/<member>/subscribe`; anything longer, such as `<Actor>/computer/exec`, is not a kind.
+const actorTag = /^[^/]+\/(?<member>[^/]+)(?:\/subscribe)?$/u;
+
+// The kind an actor's RPC belongs to, or none when the registry has no operation for it. The coverage test runs
+// This over a real actor's RPC group, so a new kind of RPC (files, computer, fork) fails it until the registry
+// Covers it.
+const kindOfRpc = ([tag, rpc]: readonly [string, Rpc.AnyWithProps]): Option.Option<ActorKind> => {
+  const member = Option.fromUndefinedOr(actorTag.exec(tag)?.groups?.member);
+  const fields = payloadFields(rpc);
+  const stream = RpcSchema.isStreamSchema(rpc.successSchema);
+
+  const rest = Option.fromUndefinedOr(actorRest.exec(tag)?.groups?.rest);
+  const nested = Option.flatMap(rest, (name) => Rec.get<string, RpcSignature>(nestedRpcs, name));
+
+  const candidates = Option.match(
+    Option.filter(member, (name) => !Arr.contains(laterMembers, name)),
+    {
+      onNone: (): readonly RpcSignature[] => Option.toArray(nested),
+      onSome: (name) =>
+        Option.match(Rec.get<string, RpcSignature>(fixedMembers, name), { onNone: () => anyMember, onSome: Arr.of }),
+    },
+  );
+
+  return Option.map(
+    Arr.findFirst(candidates, (signature) => signature.fields === fields && signature.stream === stream),
+    (signature) => signature.kind,
+  );
+};
+
+// Every RPC in an actor's group (its requests, by tag) with the kind the registry gives it.
+const kindsOf = (
+  requests: ReadonlyMap<string, Rpc.AnyWithProps>,
+): readonly (readonly [string, Option.Option<ActorKind>])[] =>
+  Arr.map(Arr.fromIterable(requests), ([tag, rpc]) => [tag, kindOfRpc([tag, rpc])] as const);
+
+// The CLI/tool input: key and payload use the actor's JSON schemas. fileFields carries file and computer-copy fields,
+// Never upload bytes; member is used only by call, query and watch.
+interface ActorInput {
+  readonly actor: string;
+  readonly commandId: Option.Option<string>;
+  readonly fileFields: Readonly<Record<string, Schema.Json>>;
+  readonly into: Option.Option<Schema.Json>;
+  readonly key: Schema.Json;
+  readonly member: string;
+  readonly payload: Option.Option<Schema.Json>;
+}
+
+// The RPC request an operation sends: its tag and its payload, { commandId?, key, payload? }.
+interface ActorRequest {
+  readonly payload: Readonly<Record<string, Schema.Json>>;
+  readonly tag: string;
+}
+
+const someField = <Value extends Schema.Json>(
+  name: string,
+  value: Option.Option<Value>,
+): Readonly<Record<string, Schema.Json>> =>
+  Option.match(value, { onNone: () => ({}), onSome: (found) => ({ [name]: found }) });
+
+// Shared CLI/MCP request. Commands receive the given id or a fresh UUIDv7; an absent payload is null (Void's JSON).
+const actorRequestOf =
+  (operation: ActorOperation): ((input: ActorInput) => Effect.Effect<ActorRequest, never, SecureRandom.SecureRandom>) =>
+  (input: ActorInput): Effect.Effect<ActorRequest, never, SecureRandom.SecureRandom> =>
+    Effect.gen(function* buildRequest() {
+      const takes = (name: FieldName): boolean => Arr.contains(operation.fields, name);
+      const minted = SecureRandom.SecureRandom.use((random) => random.uuidV7());
+      const fresh = yield* Effect.when(minted, Effect.succeed(takes("commandId") && Option.isNone(input.commandId)));
+
+      const commandId = Option.filter(
+        Option.orElse(input.commandId, () => fresh),
+        () => takes("commandId"),
+      );
+
+      const payload = Option.liftPredicate(Option.getOrNull(input.payload), () => takes("payload"));
+
+      const fileFields = Rec.filter(input.fileFields, (_value, name) =>
+        Arr.some(operation.fields, (field) => field === name),
+      );
+
+      const fields: ActorRequest["payload"] = {
+        ...fileFields,
+        ...someField("commandId", commandId),
+        ...someField(
+          "into",
+          Option.filter(input.into, () => takes("into")),
+        ),
+        ...someField("payload", payload),
+        key: input.key,
+      };
+
+      return { payload: fields, tag: tagOf({ actor: input.actor, kind: operation.kind, member: input.member }) };
+    });
+
+export { actorOperations, actorRequestOf, kindsOf, tagOf, unexposedKinds };
+
+export type { ActorInput, ActorKind, ActorOperation, ActorRequest, Annotations };
+
+export type { FieldName } from "./actor-fields.pure.js";