Operations

An operation is a Query or a Command plus optional annotations. Every other annotation attaches to an operation. Without @Query or @Command it has no target and the compiler reports EFFX1103.

Query and CommandCopy Anchor Link

Decorator and builder forms:

// decorator
@Query({ name: "User.Get", input: GetUserInput, success: User.Public })
static get(input: typeof GetUserInput.Type) { /* returns Effect<A, E, R> */ }

// builder
export const getUser = Operation.query({ name: "User.Get", input: GetUserInput, success: User.Public })
  .handler((input: typeof GetUserInput.Type) => /* Effect<A, E, R> */);

@Command(options) and Operation.command(options) take the same options.

OperationOptionsCopy Anchor Link

Source: packages/runtime/src/Annotation.ts (OperationOptions); default name from packages/compiler/src/extensions/core.ts (operationName).

Query is a semantic claimCopy Anchor Link

@Query means "the developer declares observational semantics". It is not a purity proof: two handlers can share A, E, R while one reads and one writes (ADR 0006, docs/decisions/0006-query-is-a-semantic-claim.md). The compiler checks only what it can know.

Query and Command are the only operation kinds. There is no Mutation or Action (ADR 0006).

Errors and RequirementsCopy Anchor Link

E and R are inferred from the handler's Effect<A, E, R> return type. @Errors and @Requirements assert them (ADR 0005, docs/decisions/0005-e-and-r-are-inferred-declarations-assert.md).

ServiceLike:

Source: packages/runtime/src/Annotation.ts (ServiceLike), packages/runtime/src/decorators.ts, packages/runtime/src/builder.ts.

Inferred versus assertedCopy Anchor Link

Source: packages/compiler/src/extensions/core.ts; ADR 0005; docs/specs/0002-source-frontend.md §"E/R inference".

Dropping an assertion never silently changes a contract: the inferred set takes over, and an opaque constituent still diagnoses.

External operationsCopy Anchor Link

On a .declare() operation (see HTTP) there is no handler to infer from. @Errors and @Requirements are then declarations, not assertions: they are recorded with inferred: false, including the Requires edge, and the E/R equality checks do not run. Without them the sets are empty and inferred: false. Source: core.ts (operationInterpreter, errorsAssertion, requirementsAssertion), docs/specs/0010-target-profiles-and-emit-modes.md §"Declaration-only operations".

Rpc and CliCopy Anchor Link

@Rpc("User.Get")
@Cli("users get")

Source: packages/runtime/src/decorators.ts, packages/runtime/src/builder.ts, packages/compiler/src/extensions/transports.ts.

A .declare() operation cannot have RPC or CLI exposure: a raw HTTP binding cannot implement them (EFFX1107).

AuthorizeCopy Anchor Link

Capability values come from Capability.make. See Persistence and authority for the field table.

ExampleCopy Anchor Link

import { Authorize, Cli, Command, Errors, Http, Query, Requirements, Rpc } from "@effx/runtime";
import { Effect } from "effect";
import { ChangeEmail, Read } from "./capabilities.ts";
import { ChangeEmailInput, EmailTaken, GetUserInput, UserNotFound } from "./schemas.ts";
import { Users } from "./services.ts";
import { User } from "./user.ts";

export class UserOperations {
  @Query({ name: "User.Get", input: GetUserInput, success: User.Public })
  @Http.Get("/users/:id")
  @Rpc("User.Get")
  @Cli("users get")
  @Authorize(Read)
  static get(input: typeof GetUserInput.Type) {
    return Effect.gen(function* () {
      const users = yield* Users;
      const user = yield* users.find(input.id);

      return { id: user.id, displayName: user.displayName };
    });
  }

  @Command({ name: "User.ChangeEmail", input: ChangeEmailInput, success: User.Self })
  @Http.Patch("/users/:id/email")
  @Rpc("User.ChangeEmail")
  @Cli("users change-email")
  @Authorize(ChangeEmail)
  @Errors(UserNotFound, EmailTaken)
  @Requirements(Users)
  static changeEmail(input: typeof ChangeEmailInput.Type) {
    return Effect.gen(function* () {
      const users = yield* Users;

      return yield* users.setEmail(input.id, input.email);
    });
  }
}

User.Get declares only the Query, transports and capability: E and R are inferred. User.ChangeEmail also asserts @Errors(UserNotFound, EmailTaken) and @Requirements(Users).