effx
API reference@effx/runtime

builder

API reference for @effx/runtime/builder

builder.ts overview


Exports Grouped by Category


utils

ExternalOperationValue (interface)

A declaration-only operation has no callable handler; the application binds it externally.

Signature

export interface ExternalOperationValue {
  readonly _tag: "Operation"
  readonly annotations: ReadonlyArray<Annotation>
}

HttpGroupReference (type alias)

A builder group or a class decorated with @Http.Group, resolved by the source collector.

Signature

type HttpGroupReference = HttpGroupValue | (abstract new (...args: never[]) => object)

HttpGroupValue (interface)

Signature

export interface HttpGroupValue {
  readonly _tag: "HttpGroup"
  readonly annotations: ReadonlyArray<Annotation>
}

Model

Signature

declare const Model: { persistent: <S extends Schema.Top>(schema: S, options: PersistentModelOptions) => ModelValue<S> }

ModelValue (interface)

Signature

export interface ModelValue<S extends Schema.Top> {
  readonly _tag: "Model"
  readonly annotations: ReadonlyArray<Annotation>
  readonly schema: S
}

Operation

Value-level twin of the @Query and @Command decorators. Each builder step appends the annotation the matching decorator would record; nothing is generated at runtime (ADR 0001).

Example

import { Operation, Reflect } from "@effx/runtime"
import { Schema } from "effect"
import assert from "node:assert"

const GetUser = Operation.query({
  name: "User.Get",
  input: Schema.Struct({ id: Schema.String }),
  success: Schema.Struct({ id: Schema.String })
})
  .http.get("/users/:id")
  .declare()

assert.deepStrictEqual(
  GetUser.annotations.map((a) => a.name),
  ["Query", "Http.Get"]
)
assert.strictEqual(typeof Reflect.annotationsOf, "function")

Signature

declare const Operation: {
  query: (
    args_0: Readonly<{ readonly input: Schema.Top; readonly success: Schema.Top; readonly name?: string | undefined }>
  ) => OperationBuilder
  command: (
    args_0: Readonly<{ readonly input: Schema.Top; readonly success: Schema.Top; readonly name?: string | undefined }>
  ) => OperationBuilder
}

OperationBuilder (class)

Value-level twin of the decorators. Each step appends exactly the annotation the matching decorator would record, so Reflect.annotationsOf(Class.method) equals value.annotations. Every step is its definition from builtins.ts applied through with.

Signature

declare class OperationBuilder { constructor(readonly annotations: ReadonlyArray<Annotation>) }

append (method)

Signature

declare const append: (annotation: Annotation) => OperationBuilder

with (method)

Appends any applied operation annotation, built-in or user-defined (spec 0020 §2.1).

Signature

declare const with: (applied: Applied<string, "operation">) => OperationBuilder

annotate (method)

Generic annotation (spec 0015): records exactly { name, args }, as @Annotate(name, ...args) does.

Signature

declare const annotate: (name: string, ...args: Annotation["args"]) => OperationBuilder

in (method)

Signature

declare const in: (args_0: HttpGroupReference) => OperationBuilder

rpc (method)

Signature

declare const rpc: (args_0: string) => OperationBuilder

cli (method)

Signature

declare const cli: (args_0: string) => OperationBuilder

authorize (method)

Signature

declare const authorize: (args_0: Capability) => OperationBuilder

errors (method)

Signature

declare const errors: (...args: Parameters<typeof Builtins.Errors>) => OperationBuilder

requirements (method)

Signature

declare const requirements: (...args: Parameters<typeof Builtins.Requirements>) => OperationBuilder

handler (method)

Signature

declare const handler: <Handler>(handler: Handler) => OperationValue<Handler>

declare (method)

Signature

declare const declare: () => ExternalOperationValue

http (property)

Signature

readonly http: { access: (args_0: Readonly<{ readonly capabilities: TaggedLive<{ readonly None: {}; readonly One: { readonly capability: Arg<string, string>; }; readonly Any: { readonly capabilities: Arg<readonly [string, ...string[]], readonly [string, ...string[]]>; }; readonly All: { readonly capabilities: Arg<readonly [string, ...string[]], readonly [string, ...string[]]>; }; }>; readonly requirements: ReadonlyArray<Readonly<{ readonly id: string; readonly parameters?: { readonly [key: string]: JsonValue; } | undefined; }>>; readonly canonicalScopeResolver: object; readonly annotator?: ((spec: HttpAccessAnnotationSpec) => Context<never>) | undefined; readonly exposure?: "External" | "Internal" | undefined; readonly acceptedCredentials?: readonly [string, ...string[]] | undefined; readonly principalKinds?: readonly ["Anonymous" | "Person" | "ServicePrincipal" | "CapabilityHolder", ...("Anonymous" | "Person" | "ServicePrincipal" | "CapabilityHolder")[]] | undefined; readonly concealment?: TaggedLive<{ readonly Reveal: {}; readonly NotFound: { readonly stages: Arg<readonly [string, ...string[]], readonly [string, ...string[]]>; }; }> | undefined; readonly decisionTime?: "SnapshotRead" | "Transaction" | undefined; readonly snapshotDecisionForCommand?: boolean | undefined; }>) => OperationBuilder; contract: (args_0: Readonly<{ readonly root?: string | undefined; readonly group?: string | undefined; readonly params?: Schema.Top | undefined; readonly query?: true | Schema.Top | undefined; readonly headers?: Schema.Top | undefined; readonly payload?: Schema.Top | undefined; readonly payloadIsQuery?: boolean | undefined; readonly success?: Schema.Top | undefined; readonly status?: number | undefined; readonly mediaType?: string | undefined; readonly responseHeaders?: Schema.Top | undefined; readonly conditional?: boolean | undefined; readonly middleware?: ReadonlyArray<ServiceLike> | undefined; readonly metadata?: Readonly<{ readonly annotator?: HttpOperationAnnotator | undefined; readonly operationId?: string | undefined; readonly summary?: string | undefined; readonly description?: string | undefined; readonly tags?: ReadonlyArray<string> | undefined; readonly commandIdentity?: ExportedFunctionSymbol | undefined; }> | undefined; }>) => OperationBuilder; problems: <Code extends string>(options: HttpProblemsOptions<Code>) => OperationBuilder; get: (args_0: string) => OperationBuilder; post: (args_0: string) => OperationBuilder; put: (args_0: string) => OperationBuilder; patch: (args_0: string) => OperationBuilder; delete: (args_0: string) => OperationBuilder; }

foldkit (property)

Signature

readonly foldkit: { command: (args_0: Readonly<{ readonly success: Schema.Top; readonly failure: Schema.Top; }>) => OperationBuilder; }

OperationValue (interface)

A local operation keeps the author's untouched handler.

Signature

export interface OperationValue<Handler> {
  readonly _tag: "Operation"
  readonly annotations: ReadonlyArray<Annotation>
  readonly handler: Handler
}

group

Signature

declare const group: (options: HttpGroupOptions) => HttpGroupValue

problems

Http.Problems keeps its Code generic, which the (non-generic) definition cannot carry. ProblemRegistry<Code> is contravariant in Code, so no assignment widens it to ProblemRegistry<string>; an overload (whose implementation signature TypeScript checks with type parameters erased) states the generic public signature without an assertion. The runtime never calls the registry: the compiler reads it by symbol.

Signature

declare const problems: <Code extends string>(
  options: HttpProblemsOptions<Code>
) => Applied<typeof Builtins.HttpProblems.name, "operation">

On this page