@distilled.cloud/core 1.0.0-rc.11 → 1.0.0-rc.13

package/lib/graphql.d.ts

@@ -1,121 +1,68 @@
+/**
+ * GraphQL Query algebra — the runtime generated GraphQL SDKs target.
+ *
+ * ── Why this exists ────────────────────────────────────────────────────────
+ * A GraphQL document is a *selection*, not an RPC. Distilled used to bake a
+ * max-depth selection into every operation (`Railway.me({})` downloaded the
+ * world). This module instead treats every field as a lazy `Query<Value>`:
+ * reading `user.email` records that field, and nothing is posted until
+ * `Query.fn` evaluates the plan you returned.
+ *
+ * ── The two phases ─────────────────────────────────────────────────────────
+ * 1. Build (your function). `Railway.me()` / `user.email` / `Query.map` do
+ *    not talk to the network. They construct an expression tree:
+ *      Of | Map | Filter | FlatMap | Prop | Root
+ *    The inner function of `Query.fn` is therefore a *builder*, not an
+ *    Effect generator. No `yield*` inside it.
+ *
+ * 2. Evaluate (`Query.fn`). Walk the returned plan, paint every GraphQL
+ *    field that appears onto one selection forest, POST that document
+ *    once through {@link GqlTransport}, then interpret Map/Filter/FlatMap
+ *    against the JSON. Effects reached via FlatMap (e.g.
+ *    `usernameIsAvailable(name)`) run *after* the POST, with real values.
+ *
+ * ── Combinators ────────────────────────────────────────────────────────────
+ * - `Query.of(x)` — a literal; never selected.
+ * - `Query.map` on a list — callback receives `Query<Item>` so `p.name` is
+ *   still a Query (selected). On a scalar, callback receives the value
+ *   after extract (`stars => stars > 5`). Relay connections (`edges { node }`)
+ *   are lists of the node type, so `projects({ first: 20 }).pipe(Query.map)`
+ *   maps projects, not edges.
+ * - `Query.filter` — predicate is `Query<Item> => Query<boolean>`; the
+ *   boolean Query is walked for fields, then run per row after the POST.
+ * - `Query.flatMap` — after extract, run `(value) => Effect | Query`.
+ * - `Query.pages` / `Query.items` — a Stream over every page / node of a
+ *   Relay connection, one POST per page (see "Pagination").
+ *
+ * ── Types ──────────────────────────────────────────────────────────────────
+ * `Query<Value>` is `QueryNode<Value>` plus the GraphQL fields of `Value`,
+ * so `user.name` type-checks. That copy is a circular type alias
+ * (`Query<User>` contains `Query<Project[]>` which contains `Query<User>`
+ * again). TypeScript leaves the cycle lazy; there is no depth cap.
+ *
+ * ── Transport ──────────────────────────────────────────────────────────────
+ * {@link GqlTransport.execute} posts `{ query, variables, operationName }`.
+ * The Effect it returns may require Credentials / HttpClient; those leak
+ * into `Query.fn`'s requirements. It returns the parsed `data` and raw
+ * `errors`; `Query.fn` classifies the errors (see "Errors" below). Compile
+ * failures are {@link GqlError} defects.
+ *
+ * Generated SDKs export *roots* (`Railway.me`, `Railway.project`).
+ * Combinators live in `@distilled.cloud/core/query`.
+ */
+import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as S from "effect/Schema";
 import * as Stream from "effect/Stream";
-import type { GraphQLModel } from "./codegen/graphql-client.ts";
-export type { GraphQLModel } from "./codegen/graphql-client.ts";
-/** A generated field's arguments, GraphQL output reference, and error tags. */
-export interface Field<Args, Ref extends string, E extends string = never> {
-    readonly args: Args;
-    readonly type: Ref;
-    readonly errors: E;
-}
-export interface Schema {
-    types: Record<string, Record<string, Field<any, string, string>>>;
-    scalars: Record<string, unknown>;
-    errors: Record<string, GraphQLIssue>;
-    possibleTypes: Record<string, string>;
-    query: string;
-    mutation: string;
-    subscription: string;
-    globalErrors: string;
+export declare const QuerySymbol: unique symbol;
+declare const inspect: unique symbol;
+/** A plan that cannot be compiled (a programming error, raised as a defect). */
+export declare class GqlError {
+    readonly message: string;
+    readonly _tag: "GqlError";
+    constructor(message: string);
 }
-type Named<T extends string> = T extends `${infer R}!` ? Named<R> : T extends `[${infer R}]` ? Named<R> : T;
-type Fields<C extends Schema, N extends string> = N extends keyof C["types"] ? C["types"][N] : {};
-type TypeOf<F> = F extends Field<any, infer T, any> ? T : never;
-type ArgsOf<F> = F extends Field<infer A, any, any> ? A : never;
-type TagsOf<F> = F extends Field<any, any, infer E> ? E : never;
-type Where<A> = {} extends A ? {
-    readonly where?: A;
-} : {
-    readonly where: A;
-};
-type Directives = {
-    readonly $include?: boolean;
-    readonly $skip?: boolean;
-};
-type FieldSelection<C extends Schema, F> = Named<TypeOf<F>> extends keyof C["scalars"] ? ({} extends ArgsOf<F> ? boolean : never) | (Where<ArgsOf<F>> & Directives & {
-    readonly select?: true;
-}) : (keyof ArgsOf<F> extends never ? Selection<C, Named<TypeOf<F>>> : never) | (Where<ArgsOf<F>> & Directives & {
-    readonly select: Selection<C, Named<TypeOf<F>>>;
-});
-type Alias<C extends Schema, N extends string> = {
-    [K in keyof Fields<C, N>]: {
-        readonly [P in K]: FieldSelection<C, Fields<C, N>[K]>;
-    };
-}[keyof Fields<C, N>];
-/** Mobius-style field selection. Arguments are passed in `where`. */
-export type Selection<C extends Schema, N extends string> = {
-    readonly [K in keyof Fields<C, N>]?: FieldSelection<C, Fields<C, N>[K]>;
-} & {
-    readonly __typename?: boolean;
-    readonly __alias?: Readonly<Record<string, Alias<C, N>>>;
-    readonly __on?: N extends keyof C["possibleTypes"] ? {
-        readonly [K in C["possibleTypes"][N]]?: Selection<C, K>;
-    } : never;
-};
-type Selected<Q> = Q extends {
-    readonly select: infer P;
-} ? P : Q;
-type Keys<Q> = {
-    [K in keyof Q]: Q[K] extends false | undefined ? never : K;
-}[keyof Q];
-type Simplify<A> = {
-    [K in keyof A]: A[K];
-};
-type AliasValue<C extends Schema, N extends string, Q> = {
-    [K in Extract<Keys<Q>, keyof Fields<C, N>>]: Result<C, TypeOf<Fields<C, N>[K]>, Selected<Q[K]>>;
-}[Extract<Keys<Q>, keyof Fields<C, N>>];
-type AliasResult<C extends Schema, N extends string, Q> = Q extends {
-    readonly __alias: infer A;
-} ? Simplify<{
-    [K in keyof A as Conditional<A[K][keyof A[K]]> extends true ? never : K]: AliasValue<C, N, A[K]>;
-} & {
-    [K in keyof A as Conditional<A[K][keyof A[K]]> extends true ? K : never]?: AliasValue<C, N, A[K]>;
-}> : {};
-type Conditional<Q> = boolean extends Q ? true : Q extends {
-    readonly $include: infer I;
-} ? [I] extends [true] ? Q extends {
-    readonly $skip: infer S;
-} ? [S] extends [false] ? false : true : false : true : Q extends {
-    readonly $skip: infer S;
-} ? [S] extends [false] ? false : true : false;
-type ObjectFields<C extends Schema, N extends string, Q> = {
-    [K in Extract<Keys<Q>, keyof Fields<C, N>> as Conditional<Q[K]> extends true ? never : K]: Result<C, TypeOf<Fields<C, N>[K]>, Selected<Q[K]>>;
-} & {
-    [K in Extract<Keys<Q>, keyof Fields<C, N>> as Conditional<Q[K]> extends true ? K : never]?: Result<C, TypeOf<Fields<C, N>[K]>, Selected<Q[K]>>;
-};
-type ObjectResult<C extends Schema, N extends string, Q> = Simplify<ObjectFields<C, N, Q> & (Q extends {
-    readonly __typename: true;
-} ? {
-    __typename: N;
-} : {}) & AliasResult<C, N, Q>>;
-type Branch<C extends Schema, N extends string, Q, T extends string> = T extends unknown ? Simplify<Omit<ObjectResult<C, N, Q>, "__typename"> & (Q extends {
-    readonly __on: infer O;
-} ? T extends keyof O ? ObjectResult<C, T, O[T]> : {} : {}) & {
-    __typename: T;
-}> : never;
-type Value<C extends Schema, T extends string, Q> = T extends `[${infer I}]` ? Array<Result<C, I, Q>> : T extends keyof C["scalars"] ? C["scalars"][T] : T extends keyof C["possibleTypes"] ? Branch<C, T, Q, C["possibleTypes"][T]> : ObjectResult<C, T, Q>;
-/** Selected output, preserving list and nullable wrappers. */
-export type Result<C extends Schema, Ref extends string, Q> = Ref extends `${infer T}!` ? Value<C, T, Q> : Value<C, Ref, Q> | null;
-type SelectionTags<C extends Schema, N extends string, Q> = string extends N ? string : Q extends object ? {
-    [K in Extract<Keys<Q>, keyof Fields<C, N>>]: TagsOf<Fields<C, N>[K]> | SelectionTags<C, Named<TypeOf<Fields<C, N>[K]>>, Selected<Q[K]>>;
-}[Extract<Keys<Q>, keyof Fields<C, N>>] | (Q extends {
-    readonly __on: infer O;
-} ? {
-    [K in keyof O & string]: SelectionTags<C, K, O[K]>;
-}[keyof O & string] : never) | (Q extends {
-    readonly __alias: infer A;
-} ? {
-    [K in keyof A]: SelectionTags<C, N, A[K]>;
-}[keyof A] : never) : never;
-/** Known selected errors plus provider-wide errors and an honest fallback. */
-export type Errors<C extends Schema, N extends string, Q> = (SelectionTags<C, N, Q> extends infer Tags ? C["errors"][Extract<C["globalErrors"] | Tags, keyof C["errors"]>] : never) | UnknownGraphQLError;
-type Root<C extends Schema, K extends OperationKind> = K extends "query" ? C["query"] : C["mutation"];
-type OperationSelection<C extends Schema, N extends string, K extends keyof Fields<C, N>, Q> = {
-    [P in K]: {
-        select: Q;
-    };
-};
+/** Fields every classified GraphQL error carries. */
 export declare const errorFields: {
     message: S.String;
     code: S.optional<S.String>;
@@ -127,8 +74,10 @@ export declare const errorFields: {
     extensions: S.optional<S.Unknown>;
     traceId: S.optional<S.String>;
     status: S.optional<S.Number>;
+    /** Server retry hint in seconds. */
     retryAfter: S.optional<S.Number>;
 };
+/** The shape shared by every classified GraphQL error. */
 export interface GraphQLIssue {
     readonly _tag: string;
     readonly message: string;
@@ -141,9 +90,9 @@ export interface GraphQLIssue {
     readonly extensions?: unknown;
     readonly traceId?: string;
     readonly status?: number;
-    /** Server retry hint in seconds. */
     readonly retryAfter?: number;
 }
+export type GraphQLIssueProps = Omit<GraphQLIssue, "_tag">;
 declare const UnknownGraphQLError_base: S.Class<UnknownGraphQLError, S.TaggedStruct<"UnknownGraphQLError", {
     readonly message: S.String;
     readonly code: S.optional<S.String>;
@@ -156,129 +105,271 @@ declare const UnknownGraphQLError_base: S.Class<UnknownGraphQLError, S.TaggedStr
     readonly traceId: S.optional<S.String>;
     readonly status: S.optional<S.Number>;
     readonly retryAfter: S.optional<S.Number>;
+    /** Root field the error path points at, when the path is known. */
     readonly coordinate: S.optional<S.String>;
 }>, import("effect/Cause").YieldableError>;
+/** A GraphQL error no declared matcher recognizes. */
 export declare class UnknownGraphQLError extends UnknownGraphQLError_base {
 }
 declare const GraphQLFailure_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
     readonly _tag: "GraphQLFailure";
 } & Readonly<A>;
-/** All errors from one GraphQL execution, with the original partial response. */
+/** One response carried errors with different tags; none is hidden. */
 export declare class GraphQLFailure<E extends GraphQLIssue = GraphQLIssue> extends GraphQLFailure_base<{
     readonly errors: readonly [E, ...E[]];
     readonly data: unknown;
-    readonly status: number;
+    readonly status?: number;
 }> {
     get message(): string;
 }
 declare const GraphQLTransportError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
     readonly _tag: "GraphQLTransportError";
 } & Readonly<A>;
+/** The request never produced a GraphQL response (network, HTTP, non-JSON). */
 export declare class GraphQLTransportError extends GraphQLTransportError_base<{
     readonly message: string;
-    readonly cause?: unknown;
     readonly status?: number;
+    /** Server retry hint in seconds. */
     readonly retryAfter?: number;
-}> {
-}
-declare const GraphQLDecodeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "GraphQLDecodeError";
-} & Readonly<A>;
-export declare class GraphQLDecodeError extends GraphQLDecodeError_base<{
-    readonly message: string;
-    readonly path?: ReadonlyArray<string | number>;
     readonly cause?: unknown;
 }> {
 }
-declare const GraphQLRequestError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "GraphQLRequestError";
+declare const GraphQLPaginationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "GraphQLPaginationError";
 } & Readonly<A>;
-export declare class GraphQLRequestError extends GraphQLRequestError_base<{
+/** A paginated connection reported more pages without a new cursor. */
+export declare class GraphQLPaginationError extends GraphQLPaginationError_base<{
     readonly message: string;
+    readonly cursor: string | null;
 }> {
 }
-export type ClientError = GraphQLTransportError | GraphQLDecodeError | GraphQLRequestError;
-/** True only when every issue has an allowed tag; mixed failures are never hidden. */
-export declare const isErrorTag: (error: unknown, tags: string | readonly string[]) => boolean;
-/** Recover only an aggregate whose every issue matches. The original aggregate is also supplied. */
-export declare const catchTags: <const T extends readonly string[] | string, B, E2, R2>(tags: T, handler: (error: GraphQLIssue & {
-    readonly _tag: T extends string ? T : T[number];
-}, failure: GraphQLFailure) => Effect.Effect<B, E2, R2>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A | B, E | E2, R | R2>;
-export type OperationKind = "query" | "mutation";
-export interface GraphQLRequest {
-    readonly query: string;
-    readonly variables: Record<string, unknown>;
-    readonly operationName: string;
-    readonly kind: OperationKind;
+/** Recognizes a raw GraphQL error. Every present property must match. */
+export interface ErrorMatcher {
+    readonly code?: string;
+    readonly message?: string;
+    readonly messageIncludes?: string;
 }
-export interface GraphQLResponse {
-    readonly body: unknown;
-    readonly status: number;
-    readonly headers: Readonly<Record<string, string | undefined>>;
+/** Runtime description of one generated error class. */
+export interface ErrorSpec<E extends GraphQLIssue = GraphQLIssue> {
+    readonly tag: E["_tag"];
+    readonly make: (props: GraphQLIssueProps) => E;
+    readonly matchers: ReadonlyArray<ErrorMatcher>;
+    /** Queries failing only with retryable errors are retried. */
+    readonly retryable: boolean;
+    /** Applies to every root, including errors that carry no path. */
+    readonly global: boolean;
 }
-export type Transport<R> = (request: GraphQLRequest) => Effect.Effect<GraphQLResponse, GraphQLTransportError | GraphQLDecodeError, R>;
-interface Position {
-    readonly field: string;
-    readonly key: string;
-    readonly coordinate: string;
-    readonly type: string;
-    readonly errors: readonly string[];
-    readonly children: readonly Position[];
-    readonly branches: Readonly<Record<string, readonly Position[]>>;
-    readonly typename?: boolean;
-    readonly conditional: boolean;
-}
-export interface CompiledQuery extends GraphQLRequest {
-    readonly rootType: string;
-    readonly positions: readonly Position[];
+export declare const errorSpec: <E extends GraphQLIssue>(make: new (props: GraphQLIssueProps) => E, tag: E["_tag"], matchers: ReadonlyArray<ErrorMatcher>, options?: {
+    readonly retryable?: boolean;
+    readonly global?: boolean;
+}) => ErrorSpec<E>;
+/** An entry of a GraphQL response's `errors` array, as sent on the wire. */
+export interface RawGraphQLError {
+    readonly message: string;
+    readonly path?: ReadonlyArray<string | number>;
+    readonly locations?: ReadonlyArray<{
+        readonly line: number;
+        readonly column: number;
+    }>;
+    readonly extensions?: Record<string, unknown>;
+    readonly [key: string]: unknown;
 }
-/** Compile one selection to a GraphQL AST, variables, and an error/decoder path map. */
-export declare const compile: (model: GraphQLModel, kind: OperationKind, selection: unknown, operationName?: string) => CompiledQuery;
-type ErrorConstructor = new (args: any) => GraphQLIssue;
-export interface Report<A, E extends GraphQLIssue> {
-    readonly data: A | null | undefined;
-    readonly errors: ReadonlyArray<E>;
-    readonly status: number;
-    readonly extensions?: unknown;
+/** What a transport returns once it has a GraphQL response body. */
+export interface GraphQLResponse {
+    readonly data?: unknown;
+    readonly errors?: ReadonlyArray<RawGraphQLError>;
+    readonly status?: number;
+    readonly headers?: Readonly<Record<string, string | undefined>>;
 }
-type Failure<C extends Schema, N extends string, Q> = ClientError | GraphQLFailure<Errors<C, N, Q>>;
-type FieldAt<C extends Schema, N extends string, K extends string> = K extends keyof Fields<C, N> ? Fields<C, N>[K] : never;
-type ConnectionEdge<C extends Schema, Ref extends string> = Named<TypeOf<FieldAt<C, Named<Ref>, "edges">>>;
-type ConnectionNode<C extends Schema, Ref extends string> = TypeOf<FieldAt<C, ConnectionEdge<C, Ref>, "node">>;
-export interface ObjectOperation<C extends Schema, K extends OperationKind, N extends keyof Fields<C, Root<C, K>> & string, R> {
-    <const Q extends Selection<C, Named<TypeOf<Fields<C, Root<C, K>>[N]>>>>(args: ArgsOf<Fields<C, Root<C, K>>[N]>, select: Q): Effect.Effect<Result<C, TypeOf<Fields<C, Root<C, K>>[N]>, Q>, Failure<C, Root<C, K>, OperationSelection<C, Root<C, K>, N, Q>>, R>;
+export type ArgMeta = Record<string, string>;
+export type FieldMeta = {
+    readonly name: string;
+    readonly kind: "scalar" | "object" | "list" | "connection";
+    readonly of?: TypeMeta;
+    readonly argTypes?: ArgMeta;
+};
+export type TypeMeta = {
+    readonly name: string;
+    readonly fields: Record<string, FieldMeta>;
+};
+export declare const scalarField: (name: string) => FieldMeta;
+export declare const objectField: (name: string, objectType: TypeMeta) => FieldMeta;
+export declare const listField: (name: string, itemType: TypeMeta, argTypes?: ArgMeta) => FieldMeta;
+/** Relay connection: GraphQL `edges { node }` presented as `Query<Item[]>`. */
+export declare const connectionField: (name: string, nodeType: TypeMeta, argTypes?: ArgMeta) => FieldMeta;
+export type TypeRef = {
+    readonly tag: "scalar";
+} | {
+    readonly tag: "object";
+    readonly meta: TypeMeta;
+} | {
+    readonly tag: "list";
+    readonly of: TypeRef;
+};
+export interface SelNode {
+    field: string;
+    alias: string | undefined;
+    args: Record<string, string> | undefined;
+    children: Map<string, SelNode>;
+    isScalar: boolean;
+    isList: boolean;
 }
-export interface ScalarOperation<C extends Schema, K extends OperationKind, N extends keyof Fields<C, Root<C, K>> & string, R> {
-    (args: ArgsOf<Fields<C, Root<C, K>>[N]>): Effect.Effect<Result<C, TypeOf<Fields<C, Root<C, K>>[N]>, true>, Failure<C, Root<C, K>, OperationSelection<C, Root<C, K>, N, true>>, R>;
+export interface CompiledOperation {
+    readonly document: string;
+    readonly operationName: string;
+    readonly variables: Record<string, unknown>;
+    readonly kind: "query" | "mutation";
+    readonly tree: SelNode;
 }
-export interface Pagination<C extends Schema, K extends OperationKind, N extends keyof Fields<C, Root<C, K>> & string, R> {
-    pages<const Q extends Selection<C, Named<TypeOf<Fields<C, Root<C, K>>[N]>>>>(args: ArgsOf<Fields<C, Root<C, K>>[N]>, select: Q): Stream.Stream<Result<C, TypeOf<Fields<C, Root<C, K>>[N]>, Q>, ClientError | GraphQLFailure<Errors<C, Root<C, K>, OperationSelection<C, Root<C, K>, N, Q>> | Errors<C, Named<TypeOf<Fields<C, Root<C, K>>[N]>>, {
-        pageInfo: {
-            endCursor: true;
-            hasNextPage: true;
-        };
-    }>>, R>;
-    items<const Q extends Selection<C, Named<ConnectionNode<C, TypeOf<Fields<C, Root<C, K>>[N]>>>>>(args: ArgsOf<Fields<C, Root<C, K>>[N]>, select: Q): Stream.Stream<Result<C, ConnectionNode<C, TypeOf<Fields<C, Root<C, K>>[N]>>, Q>, Failure<C, Root<C, K>, OperationSelection<C, Root<C, K>, N, {
-        edges: {
-            node: Q;
-        };
-        pageInfo: {
-            endCursor: true;
-            hasNextPage: true;
-        };
-    }>>, R>;
+declare const GqlTransport_base: Context.ServiceClass<GqlTransport, "@distilled.cloud/graphql/Transport", {
+    readonly execute: (req: CompiledOperation) => Effect.Effect<GraphQLResponse, GraphQLTransportError, any>;
+}>;
+export declare class GqlTransport extends GqlTransport_base {
 }
-export type Operation<C extends Schema, K extends OperationKind, N extends keyof Fields<C, Root<C, K>> & string, R> = Named<TypeOf<Fields<C, Root<C, K>>[N]>> extends keyof C["scalars"] ? ScalarOperation<C, K, N, R> : ObjectOperation<C, K, N, R> & (K extends "query" ? "after" extends keyof ArgsOf<Fields<C, Root<C, K>>[N]> ? [ConnectionNode<C, TypeOf<Fields<C, Root<C, K>>[N]>>] extends [
-    never
-] ? {} : Pagination<C, K, N, R> : {} : {});
-/** Construct an Effect client; credentials and HTTP are resolved by the transport per call. */
-export declare const makeClient: <C extends Schema, R>(model: GraphQLModel, transport: Transport<R>, classes: Readonly<Record<string, ErrorConstructor>>) => {
-    query: <const Q extends Selection<C, C["query"]>>(selection: Q) => Effect.Effect<Result<C, `${C["query"]}!`, Q>, Failure<C, C["query"], Q>, R>;
-    mutation: <const Q extends Selection<C, C["mutation"]>>(selection: Q) => Effect.Effect<Result<C, `${C["mutation"]}!`, Q>, Failure<C, C["mutation"], Q>, R>;
-    report: {
-        query: <const Q extends Selection<C, C["query"]>>(selection: Q) => Effect.Effect<Report<Result<C, `${C["query"]}!`, Q>, Errors<C, C["query"], Q>>, ClientError, R>;
-        mutation: <const Q extends Selection<C, C["mutation"]>>(selection: Q) => Effect.Effect<Report<Result<C, `${C["mutation"]}!`, Q>, Errors<C, C["mutation"], Q>>, ClientError, R>;
-    };
-    operation: <K extends OperationKind, N extends keyof Fields<C, Root<C, K>> & string>(kind: K, name: N) => Operation<C, K, N, R>;
+/**
+ * GraphQL fields copied onto a Query so `user.name` type-checks.
+ * `Query<User>` contains `projects: Query<Project[]>`, which contains
+ * `owner: Query<User>` again — TypeScript leaves the cycle lazy. Fields
+ * inherit the errors of the root they were read from.
+ */
+type QueryFields<Value, Error> = [NonNullable<Value>] extends [
+    ReadonlyArray<infer Item>
+] ? {
+    readonly [Field in keyof NonNullable<Item>]: Query<NonNullable<Item>[Field] | Nullish<Item>, Error>;
+} & {
+    (args: Record<string, unknown>): Query<Value, Error>;
+} : [NonNullable<Value>] extends [object] ? {
+    readonly [Field in keyof NonNullable<Value>]: Query<NonNullable<Value>[Field] | Nullish<Value>, Error>;
+} : {};
+/** A field read through a `null` parent is `null`. */
+type Nullish<Value> = Extract<Value, null | undefined>;
+/**
+ * A lazy GraphQL selection. `Value` is the plain data after `Query.fn` runs;
+ * `Error` is the union of typed errors the roots it reads can return.
+ */
+export type Query<Value, Error = never> = QueryNode<Value, Error> & QueryFields<Value, Error>;
+/** Strip Query/Effect wrappers from a returned plan down to plain data. */
+export type UnwrapPlan<Plan> = Plan extends QueryNode<infer Value, any> ? Value : Plan extends Effect.Effect<infer Success, any, any> ? Success : Plan extends ReadonlyArray<infer Element> ? ReadonlyArray<UnwrapPlan<Element>> : Plan extends object ? {
+    readonly [Key in keyof Plan]: UnwrapPlan<Plan[Key]>;
+} : Plan;
+/** Typed errors of every Query and Effect in a returned plan. */
+export type PlanError<Plan> = Plan extends QueryNode<any, infer Error> ? Error : Plan extends Effect.Effect<any, infer Error, any> ? Error : Plan extends ReadonlyArray<infer Element> ? PlanError<Element> : Plan extends object ? {
+    readonly [Key in keyof Plan]: PlanError<Plan[Key]>;
+}[keyof Plan] : never;
+/** Failures of evaluating a plan whose roots declare `Error`. */
+export type QueryError<Error> = Error | GraphQLFailure<Extract<Error, GraphQLIssue> | UnknownGraphQLError> | UnknownGraphQLError | GraphQLTransportError;
+type Expr = RootExpr | PropExpr | ItemExpr | MapValueExpr | MapItemsExpr | FilterExpr | FlatMapExpr | LiteralExpr;
+type RootExpr = {
+    readonly _tag: "Root";
+    readonly op: "query" | "mutation";
+    readonly field: string;
+    readonly args: Record<string, unknown> | undefined;
+    readonly argTypes: ArgMeta | undefined;
+    readonly type: TypeRef;
+    /** Relay connection: paint `edges { node }`, extract an array of nodes. */
+    readonly connection?: boolean;
+    /** Errors this root field can return, including global errors. */
+    readonly errors: ReadonlyArray<ErrorSpec>;
+};
+type PropExpr = {
+    readonly _tag: "Prop";
+    readonly parent: Expr;
+    readonly field: FieldMeta;
+    readonly type: TypeRef;
+    readonly args?: Record<string, unknown>;
+};
+type ItemExpr = {
+    readonly _tag: "Item";
+    readonly list: Expr;
+    readonly type: TypeRef;
 };
+type MapValueExpr = {
+    readonly _tag: "MapValue";
+    readonly parent: Expr;
+    readonly mapFn: (value: unknown) => unknown;
+    readonly type: TypeRef;
+};
+type MapItemsExpr = {
+    readonly _tag: "MapItems";
+    readonly parent: Expr;
+    readonly mapped: unknown;
+    /** Map one object (`null` stays `null`) instead of every list item. */
+    readonly single?: boolean;
+    readonly type: TypeRef;
+};
+type FilterExpr = {
+    readonly _tag: "Filter";
+    readonly parent: Expr;
+    readonly predicate: Expr;
+    readonly type: TypeRef;
+};
+type FlatMapExpr = {
+    readonly _tag: "FlatMap";
+    readonly parent: Expr;
+    readonly flatMapFn: (value: unknown) => unknown;
+    readonly type: TypeRef;
+};
+type LiteralExpr = {
+    readonly _tag: "Literal";
+    readonly value: unknown;
+    readonly type: TypeRef;
+};
+export declare class QueryNode<out Value = unknown, out Error = never> {
+    readonly expr: Expr;
+    readonly [QuerySymbol]: symbol;
+    readonly valueType: Value;
+    readonly errorType: Error;
+    constructor(expr: Expr);
+    pipe<Self>(this: Self): Self;
+    pipe<Self, Out1>(this: Self, step1: (_: Self) => Out1): Out1;
+    pipe<Self, Out1, Out2>(this: Self, step1: (_: Self) => Out1, step2: (_: Out1) => Out2): Out2;
+    pipe<Self, Out1, Out2, Out3>(this: Self, step1: (_: Self) => Out1, step2: (_: Out1) => Out2, step3: (_: Out2) => Out3): Out3;
+    pipe<Self, Out1, Out2, Out3, Out4>(this: Self, step1: (_: Self) => Out1, step2: (_: Out1) => Out2, step3: (_: Out2) => Out3, step4: (_: Out3) => Out4): Out4;
+    pipe<Self, Out1, Out2, Out3, Out4, Out5>(this: Self, step1: (_: Self) => Out1, step2: (_: Out1) => Out2, step3: (_: Out2) => Out3, step4: (_: Out3) => Out4, step5: (_: Out4) => Out5): Out5;
+    pipe<Self, Out1, Out2, Out3, Out4, Out5, Out6>(this: Self, step1: (_: Self) => Out1, step2: (_: Out1) => Out2, step3: (_: Out2) => Out3, step4: (_: Out3) => Out4, step5: (_: Out4) => Out5, step6: (_: Out5) => Out6): Out6;
+    pipe<Self, Out1, Out2, Out3, Out4, Out5, Out6, Out7>(this: Self, step1: (_: Self) => Out1, step2: (_: Out1) => Out2, step3: (_: Out2) => Out3, step4: (_: Out3) => Out4, step5: (_: Out4) => Out5, step6: (_: Out5) => Out6, step7: (_: Out6) => Out7): Out7;
+    pipe<Self, Out1, Out2, Out3, Out4, Out5, Out6, Out7, Out8>(this: Self, step1: (_: Self) => Out1, step2: (_: Out1) => Out2, step3: (_: Out2) => Out3, step4: (_: Out3) => Out4, step5: (_: Out4) => Out5, step6: (_: Out5) => Out6, step7: (_: Out6) => Out7, step8: (_: Out7) => Out8): Out8;
+    [inspect](): string;
+    toString(): string;
+}
+export declare const isQuery: (value: unknown) => value is Query<unknown>;
+export declare const root: <Value, Error = never>(op: "query" | "mutation", field: string, meta: TypeMeta, args?: Record<string, unknown>, argTypes?: ArgMeta, errors?: ReadonlyArray<ErrorSpec>) => Query<Value, Error>;
+export declare const rootList: <Item, Error = never>(op: "query" | "mutation", field: string, meta: TypeMeta, args?: Record<string, unknown>, argTypes?: ArgMeta, errors?: ReadonlyArray<ErrorSpec>) => Query<ReadonlyArray<Item>, Error>;
+/** Root Relay connection: typed as `Query<Item[]>`, document uses `edges { node }`. */
+export declare const rootConnection: <Item, Error = never>(op: "query" | "mutation", field: string, meta: TypeMeta, args?: Record<string, unknown>, argTypes?: ArgMeta, errors?: ReadonlyArray<ErrorSpec>) => Query<ReadonlyArray<Item>, Error>;
+/** Root field whose GraphQL type is a scalar, enum, or list of those. */
+export declare const rootLeaf: <Value, Error = never>(op: "query" | "mutation", field: string, list: boolean, args?: Record<string, unknown>, argTypes?: ArgMeta, errors?: ReadonlyArray<ErrorSpec>) => Query<Value, Error>;
+/** `Query.of` / pure. */
+export declare const ofQuery: <Value>(value: Value) => Query<Value>;
+export declare function filterQuery<Item, Error = never>(predicate: (item: Query<Item>) => QueryNode<boolean, any>): (source: QueryNode<readonly Item[] | null, Error>) => Query<readonly Item[], Error>;
+export declare function filterQuery<Item, Error = never>(source: QueryNode<readonly Item[] | null, Error>, predicate: (item: Query<Item>) => QueryNode<boolean, any>): Query<readonly Item[], Error>;
+/**
+ * What `Query.map`'s callback receives: a Query per item for lists, a Query
+ * for an object (so its fields get selected), the plain value for scalars.
+ */
+type MapInput<Value> = [NonNullable<Value>] extends [ReadonlyArray<infer Item>] ? Query<Item> : [NonNullable<Value>] extends [object] ? Query<NonNullable<Value>> : Value;
+/** An object mapped through a `null` value stays `null`. */
+type MapOutput<Value, Mapped> = [NonNullable<Value>] extends [
+    ReadonlyArray<unknown>
+] ? ReadonlyArray<UnwrapPlan<Mapped>> : [NonNullable<Value>] extends [object] ? UnwrapPlan<Mapped> | Nullish<Value> : Mapped;
+export declare function mapQuery<Value, Mapped, Error = never>(mapFn: (value: NoInfer<MapInput<Value>>) => Mapped): (source: QueryNode<Value, Error>) => Query<MapOutput<Value, Mapped>, Error>;
+export declare function mapQuery<Value, Mapped, Error = never>(source: QueryNode<Value, Error>, mapFn: (value: NoInfer<MapInput<Value>>) => Mapped): Query<MapOutput<Value, Mapped>, Error>;
+export declare function flatMapQuery<Value, Result, Error, Requirements, SourceError = never>(flatMapFn: (value: Value) => Effect.Effect<Result, Error, Requirements> | QueryNode<Result, Error>): (source: QueryNode<Value, SourceError>) => Query<Result, SourceError | Error>;
+export declare function flatMapQuery<Value, Result, Error, Requirements, SourceError = never>(source: QueryNode<Value, SourceError>, flatMapFn: (value: Value) => Effect.Effect<Result, Error, Requirements> | QueryNode<Result, Error>): Query<Result, SourceError | Error>;
+/**
+ * Builder → Effect. The inner function is *not* a generator; it returns a
+ * plan of Query/Effect values. Query.fn visits the plan, POSTs one document,
+ * then interprets Map/Filter/FlatMap/Of.
+ */
+export declare const queryFn: <Arguments extends Array<unknown>, Plan>(build: (...args: Arguments) => Plan) => ((...args: Arguments) => Effect.Effect<UnwrapPlan<Plan>, QueryError<PlanError<Plan>>, GqlTransport>);
+/**
+ * Every page of a Relay connection, one request per page. `query` is a
+ * connection lens (root or nested under objects), optionally mapped or
+ * filtered: `Query.pages(Railway.project({ id }).services({ first: 50 }))`.
+ * Starts from the query's own `after` argument, if any.
+ */
+export declare const pagesQuery: <Item, Error>(query: QueryNode<ReadonlyArray<Item> | null, Error>) => Stream.Stream<ReadonlyArray<Item>, QueryError<Error> | GraphQLPaginationError, GqlTransport>;
+/** Every node of a Relay connection, across all pages. */
+export declare const itemsQuery: <Item, Error>(query: QueryNode<ReadonlyArray<Item> | null, Error>) => Stream.Stream<Item, QueryError<Error> | GraphQLPaginationError, GqlTransport>;
+export {};
 //# sourceMappingURL=graphql.d.ts.map