@znight/graphql 0.0.0-stage → 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,542 @@
+import { _ as GraphQLErrorCode, a as GraphQLContext, b as GraphQLExceptionOptions, c as GraphQLGuard, d as GraphQLTransport, f as LoaderKey, g as ScalarDefinition, h as ResolverContext, i as GraphQLArgs, l as GraphQLGuardClass, m as LoaderValue, n as BatchLoadClass, o as GraphQLErrorMapper, p as LoaderOptions, r as BatchLoader, s as GraphQLErrorMapperClass, t as BatchLoad, u as GraphQLOperationKind, v as GraphQLErrorCodeValue, y as GraphQLException } from "./types-CgbV9LjD.mjs";
+import { ClassMarker, MethodMarker, ParameterMarker, Plugin, PluginContext, PluginOptions, PluginRootsContext, ProviderKey, Scope, Token, TypedToken, ZnightError } from "@znight/core";
+import { ByteSize, GuardRef, HttpContext, HttpRouteGroupDefinition, InferSchemaOutput, PluginHttpRoutes, PluginHttpRoutesContext, PluginRoute, RouteMetaEntry, StandardSchemaV1, StandardSchemaV1 as StandardSchemaV1$1 } from "@znight/http";
+import { DocumentNode, FormattedExecutionResult, GraphQLError, GraphQLFormattedError, GraphQLResolveInfo, GraphQLScalarType, GraphQLSchema } from "graphql";
+/** GraphQL `ID`: a string on the wire and in TypeScript. Recognised by the compiler through the alias. */
+type ID = string;
+/** GraphQL `Int` (32-bit signed integer). A `number` in TypeScript; plain `number` maps to `Float`. */
+type Int = number;
+/** GraphQL `Float`. Same as `number`, for symmetry with {@link Int}. */
+type Float = number;
+/** Any JSON value: the `JSON` scalar. */
+type JSONValue = string | number | boolean | null | readonly JSONValue[] | {
+  readonly [key: string]: JSONValue;
+};
+/**
+ * The DataLoader of the current execution for the loader provider `L`, injected with `@Loader()`:
+ * created on first use, cached for the operation (or for one subscription event), then dropped.
+ *
+ * ```ts
+ * @ResolveField()
+ * author(@Parent() book: Book, @Loader() authors: Loader<AuthorsById>): Promise<Author> {
+ *   return authors.load(book.authorId)
+ * }
+ * ```
+ */
+export type Loader<L extends BatchLoad<unknown, unknown>> = BatchLoader<LoaderKey<L>, LoaderValue<L>>;
+/** Options of {@link Resolver} (static). */
+interface ResolverOptions {
+  /** Provider scope. Default: `singleton`; `request` creates one resolver per operation. */
+  readonly scope?: Scope;
+}
+/**
+ * Declares a resolver: a provider (singleton by default) whose `@Query`, `@Mutation`,
+ * `@Subscription` and `@ResolveField` methods are fields of the schema. Route decorators of
+ * `@znight/http` (`createRouteDecorator`) on the class are the default decisions of its fields.
+ *
+ * ```ts
+ * @Resolver()
+ * export class BookResolver {
+ *   constructor(private readonly catalog: CatalogService) {}
+ *
+ *   @Query()
+ *   book(@Args('id') id: ID): Promise<Book | null> {
+ *     return this.catalog.find(id)
+ *   }
+ * }
+ * ```
+ *
+ * @param options static: `{ scope? }`.
+ */
+export declare function Resolver(_options?: ResolverOptions): ClassMarker;
+/**
+ * A field of the `Query` root type. The method's declared return type is the field type
+ * (`Promise<T>` unwrapped), its `@Args` the arguments, its JSDoc the description.
+ *
+ * @param name static: field name. Default: the method name.
+ */
+export declare function Query(_name?: string): MethodMarker;
+/**
+ * A field of the `Mutation` root type.
+ *
+ * @param name static: field name. Default: the method name.
+ */
+export declare function Mutation(_name?: string): MethodMarker;
+/**
+ * A field of the `Subscription` root type. The method returns an `AsyncIterable<T>` (an async
+ * generator, or `pubsub.subscribe(...)`), each value being the field value of one event.
+ *
+ * @param name static: field name. Default: the method name.
+ */
+export declare function Subscription(_name?: string): MethodMarker;
+/**
+ * A field resolver: adds a field to the type of the `@Parent()` parameter (mandatory), or replaces
+ * the property field of the same name.
+ *
+ * @param name static: field name. Default: the method name.
+ */
+export declare function ResolveField(_name?: string): MethodMarker;
+/**
+ * Field arguments. Without a name, the properties of the parameter type become arguments
+ * (`@Args() filter: BookFilter`); with a name, one argument (`@Args('id') id: ID`). With a Standard
+ * Schema, the value is validated (and transformed) after GraphQL coerced it; a failure is a
+ * `BAD_USER_INPUT` error listing the issues.
+ *
+ * @param name static: argument name.
+ * @param schema value: a Standard Schema validating the value (its output is injected).
+ */
+export declare function Args(): ParameterMarker;
+export declare function Args(name: string, schema?: StandardSchemaV1$1): ParameterMarker;
+export declare function Args(schema: StandardSchemaV1$1): ParameterMarker;
+/** The parent object of a field resolver (`@ResolveField` only; its type is the parent type). */
+export declare function Parent(): ParameterMarker;
+/** The `GraphQLContext` of the operation. */
+export declare function Ctx(): ParameterMarker;
+/** The graphql-js `GraphQLResolveInfo` of the call (escape hatch). */
+export declare function Info(): ParameterMarker;
+/** The DataLoader of the current execution for the `Loader<L>` parameter type (see {@link Loader}). */
+export declare function Loader(): ParameterMarker;
+/**
+ * Guards of the fields of a resolver class or of one field, run after the global guards (class
+ * guards, then method guards). Guards are providers implementing `GraphQLGuard`.
+ *
+ * @param guards value: guard classes.
+ */
+export declare function UseGuard(..._guards: [GraphQLGuardClass, ...GraphQLGuardClass[]]): ClassMarker & MethodMarker;
+/**
+ * Maps the TypeScript type `T` to the GraphQL scalar `name` wherever it appears. `name` is static;
+ * the returned definition must be exported (`export const`): the generated module imports it.
+ * Returns `definition` unchanged.
+ *
+ * ```ts
+ * export type EmailAddress = string & { readonly __brand: 'EmailAddress' }
+ *
+ * export const EmailAddressScalar = scalar<EmailAddress>('EmailAddress', {
+ *   serialize: value => value,
+ *   parseValue: value => {
+ *     if (typeof value !== 'string' || !value.includes('@')) throw new TypeError('Expected an e-mail address')
+ *     return value.toLowerCase() as EmailAddress
+ *   },
+ * })
+ *
+ * export const UrlScalar = scalar<URL>('URL', GraphQLURL) // a graphql-js GraphQLScalarType
+ * ```
+ *
+ * @param name static: the GraphQL name of the scalar.
+ * @param definition value: a {@link ScalarDefinition} or a graphql-js `GraphQLScalarType` (whose
+ *   name must be `name`, ZNIGHT066 at boot otherwise).
+ */
+export declare function scalar<T>(name: string, definition: ScalarDefinition<T>): ScalarDefinition<T>;
+export declare function scalar<T>(name: string, definition: GraphQLScalarType): GraphQLScalarType<T>;
+/** Options of {@link orderByKeys}. */
+interface OrderByKeysOptions {
+  /**
+   * What a key without value gets: `'error'` (default) a `NOT_FOUND` `GraphQLException` failing that
+   * key only, `'null'` the value `null`.
+   */
+  readonly missing?: "error" | "null";
+}
+/**
+ * Reorders `values` (rows in any order, some keys possibly missing) to match `keys`, what a
+ * `BatchLoad.load()` must return. Keys are compared with `Map` semantics (`===`, `NaN` equal).
+ *
+ * ```ts
+ * async load(ids: readonly ID[]): Promise<readonly (Author | Error)[]> {
+ *   return orderByKeys(ids, await this.authors.findMany(ids), author => author.id)
+ * }
+ * ```
+ */
+export declare function orderByKeys<K, V>(keys: readonly K[], values: Iterable<V>, keyOf: (value: V) => K, options?: OrderByKeysOptions & {
+  readonly missing?: "error";
+}): (V | Error)[];
+export declare function orderByKeys<K, V>(keys: readonly K[], values: Iterable<V>, keyOf: (value: V) => K, options: OrderByKeysOptions & {
+  readonly missing: "null";
+}): (V | null)[];
+/** A GraphQL request: the body of a GraphQL-over-HTTP request, or the argument of `plugin.execute()`. */
+interface GraphQLRequest {
+  readonly query: string;
+  readonly operationName?: string | null | undefined;
+  readonly variables?: Readonly<Record<string, unknown>> | null | undefined;
+  /** Request extensions (ignored by the executor; available to transports). */
+  readonly extensions?: Readonly<Record<string, unknown>> | null | undefined;
+}
+/** The results of a subscription (one per event), or the single result of a query sent as a stream. */
+interface GraphQLResultStream extends AsyncIterableIterator<FormattedExecutionResult> {
+  /** Ends the stream: the source event stream is returned (unsubscribed). */
+  return(): Promise<IteratorResult<FormattedExecutionResult>>;
+}
+/**
+ * The `PubSub` contract (RFC 0005 §5.6, §8.7): topics and payloads of subscriptions. `PubSub` is
+ * an injectable external of `GraphQLPlugin` (`@znight/graphql#PubSub`, singleton), in memory by
+ * default; multi-instance deployments supply their own implementation through the `pubsub` option.
+ */
+/** Options of {@link PubSub.subscribe}. */
+interface SubscribeOptions {
+  /** Ends the subscription when it aborts (client gone, shutdown, `maxDuration`): pass `ctx.signal`. */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Publishes events to the subscribers of a topic. `Events` maps each topic to its payload type.
+ *
+ * ```ts
+ * interface CatalogEvents {
+ *   bookAdded: Book
+ * }
+ *
+ * constructor(private readonly events: PubSub<CatalogEvents>) {}
+ *
+ * await this.events.publish('bookAdded', book)
+ * for await (const book of this.events.subscribe('bookAdded', { signal: ctx.signal })) yield book
+ * ```
+ */
+export declare abstract class PubSub<Events extends object = Record<string, unknown>> {
+  /** Delivers `payload` to the current subscribers of `topic`. */
+  abstract publish<K extends keyof Events & string>(topic: K, payload: Events[K]): Promise<void>;
+  /** The events of `topic` published from now on, until `options.signal` aborts or the iterator returns. */
+  abstract subscribe<K extends keyof Events & string>(topic: K, options?: SubscribeOptions): AsyncIterableIterator<Events[K]>;
+}
+/**
+ * A `PubSub` of any event map, for the `pubsub` option: `PubSub<Events>` types are not assignable
+ * to each other (generic methods over `keyof Events`), so the option accepts the structure.
+ */
+interface AnyPubSub {
+  publish(topic: never, payload: never): Promise<void>;
+  subscribe(topic: never, options?: SubscribeOptions): AsyncIterableIterator<unknown>;
+}
+/** A global GraphQL guard: a provider class or an instance. */
+type GraphQLGuardRef = GraphQLGuardClass | GraphQLGuard;
+/** An error mapper: a provider class or an instance. */
+type GraphQLErrorMapperRef = GraphQLErrorMapperClass | GraphQLErrorMapper;
+/** Options of the GraphQL-over-HTTP endpoint. */
+interface GraphQLHttpOptions {
+  /** Route metadata of the endpoint (`[Public.meta()]`), seen by HTTP guards and the route decision check. */
+  readonly meta?: readonly RouteMetaEntry[];
+  /** Guards of the endpoint (HTTP `CanActivate`), after the global `HttpPlugin` guards. */
+  readonly guards?: readonly GuardRef[];
+  /** Body limit of the endpoint. Default `'100kb'`. */
+  readonly bodyLimit?: ByteSize;
+  /** Queries over `GET`. Default `true`. */
+  readonly get?: boolean;
+}
+/** Request limits; `false` disables one. */
+interface GraphQLLimits {
+  /** Tokens of a document (`parse`). Default 2 000. */
+  readonly maxTokens?: number | false;
+  /** Field nesting of an operation (introspection fields exempt). Default 12. */
+  readonly maxDepth?: number | false;
+  /**
+   * Aliases of a document, as written and as one operation executes them (a fragment spread several
+   * times counts each time). Default 30.
+   */
+  readonly maxAliases?: number | false;
+  /** Directives of a document. Default 50. */
+  readonly maxDirectives?: number | false;
+}
+/** Subscription options. */
+interface GraphQLSubscriptionOptions {
+  /** Active subscriptions cap (every transport); beyond it, 503. Default 10 000. */
+  readonly maxActive?: number;
+  /** Events buffered per subscriber by the default `MemoryPubSub`. Default 100. */
+  readonly bufferSize?: number;
+  /** SSE heartbeat (ms), `false` for none. Default: the `HttpPlugin` `sse` option. */
+  readonly heartbeat?: number | false;
+  /** SSE maximum duration (ms). Default: none. */
+  readonly maxDuration?: number;
+}
+/** Options of `GraphQLPlugin.configure()`. */
+interface GraphQLPluginOptions {
+  /** Path of the endpoint, joined with the `HttpPlugin` prefix. Default `'/graphql'`. */
+  readonly path?: string;
+  /** `false`: no HTTP transport (schema, `execute()` and `subscribe()` only). Default `{}`. */
+  readonly http?: GraphQLHttpOptions | false;
+  /** Global GraphQL guards (classes or instances): root fields, and field resolvers with metadata. */
+  readonly guards?: readonly GraphQLGuardRef[];
+  /** Error mappers (classes or instances), tried in order. */
+  readonly errorMappers?: readonly GraphQLErrorMapperRef[];
+  /** Unmasked messages for unexpected errors (development). Default `false`. */
+  readonly exposeErrors?: boolean;
+  /** Introspection; off, suggestions are hidden too. Default `NODE_ENV !== 'production'`. */
+  readonly introspection?: boolean;
+  /** GraphiQL on `GET path` with `accept: text/html`. Default `NODE_ENV === 'development'`. */
+  readonly graphiql?: boolean;
+  readonly limits?: GraphQLLimits;
+  /** Distinct documents kept parsed and validated (LRU); 0 disables the cache. Default 1 000. */
+  readonly documentCache?: number;
+  /** `false` disables subscriptions over SSE. */
+  readonly subscriptions?: GraphQLSubscriptionOptions | false;
+  /** The `PubSub` provided to the container. Default: a `MemoryPubSub` (closed with the application). */
+  readonly pubsub?: AnyPubSub;
+  /**
+   * How the boot check of route decisions on GraphQL fields (RFC 0001, ZNIGHT023) reports problems:
+   * `'error'` (default) fails the boot, `'warn'` logs.
+   */
+  readonly enforcement?: "error" | "warn";
+}
+/** Options of {@link MemoryPubSub}. */
+interface MemoryPubSubOptions {
+  /**
+   * Events buffered per subscriber. A subscriber that falls further behind gets a final
+   * `SUBSCRIPTION_OVERFLOW` error and its subscription ends. Default 100.
+   */
+  readonly bufferSize?: number;
+}
+/**
+ * In-process fan-out of events to subscribers: what `GraphQLPlugin` provides as `PubSub` by default.
+ * Deployments with several instances supply their own `PubSub` (`pubsub` option).
+ *
+ * ```ts
+ * GraphQLPlugin.configure({ pubsub: new MemoryPubSub({ bufferSize: 500 }) })
+ * ```
+ */
+export declare class MemoryPubSub<Events extends object = Record<string, unknown>> extends PubSub<Events> {
+  #private;
+  constructor(options?: MemoryPubSubOptions);
+  /** Subscribers of every topic. */
+  get subscribers(): number;
+  publish<K extends keyof Events & string>(topic: K, payload: Events[K]): Promise<void>;
+  subscribe<K extends keyof Events & string>(topic: K, options?: SubscribeOptions): AsyncIterableIterator<Events[K]>;
+  /** Ends every subscription; later subscriptions end at once. */
+  close(): void;
+}
+/** Format version of `metadata.extensions.graphql` (another version is ZNIGHT066 at boot). */
+export declare const GRAPHQL_METADATA_VERSION = 1;
+/** The schema of the application. The section is omitted when the application has no resolver. */
+interface GraphQLMetadata {
+  /** {@link GRAPHQL_METADATA_VERSION}. */
+  readonly version: number;
+  /** First 16 hexadecimal characters of the SHA-256 of the SDL (`printSdl`): logs, caches. */
+  readonly schemaHash: string;
+  readonly roots: GraphQLRootTypes;
+  /** Every named type except the graphql-js specified scalars, sorted by name (code-unit order). */
+  readonly types: readonly GraphQLTypeDefinition[];
+  /**
+   * Route decorator groups used on resolvers that must be known at runtime (required, or holding
+   * several keys), by group name: the shape of `extensions.http.groups` (RFC 0001).
+   */
+  readonly groups?: Readonly<Record<string, HttpRouteGroupDefinition>>;
+}
+/** Names of the root operation types (`Query`, `Mutation`, `Subscription`). */
+interface GraphQLRootTypes {
+  readonly query: string;
+  readonly mutation?: string;
+  readonly subscription?: string;
+}
+/** A named type of the schema. */
+type GraphQLTypeDefinition = GraphQLObjectTypeDefinition | GraphQLInputTypeDefinition | GraphQLEnumTypeDefinition | GraphQLUnionTypeDefinition | GraphQLBuiltinScalarDefinition | GraphQLCustomScalarDefinition;
+/** An object type: resolver return types, their fields, the root types. */
+interface GraphQLObjectTypeDefinition {
+  readonly kind: "object";
+  readonly name: string;
+  readonly description?: string;
+  /** Declaration order (base members first), then field resolvers by resolver token and source order. */
+  readonly fields: readonly GraphQLFieldDefinition[];
+}
+/** An input object type. */
+interface GraphQLInputTypeDefinition {
+  readonly kind: "input";
+  readonly name: string;
+  readonly description?: string;
+  readonly fields: readonly GraphQLInputFieldDefinition[];
+}
+/** An enum: a TypeScript `enum`, or a named alias of a union of string literals. */
+interface GraphQLEnumTypeDefinition {
+  readonly kind: "enum";
+  readonly name: string;
+  readonly description?: string;
+  /** Declaration order. */
+  readonly values: readonly GraphQLEnumValueDefinition[];
+}
+/** A union of object types. */
+interface GraphQLUnionTypeDefinition {
+  readonly kind: "union";
+  readonly name: string;
+  readonly description?: string;
+  /** Member type names, sorted. */
+  readonly members: readonly string[];
+  readonly discriminator: GraphQLDiscriminator;
+}
+/** A scalar implemented by `@znight/graphql`: `DateTime`, `BigInt` or `JSON` (`names.ts`). */
+interface GraphQLBuiltinScalarDefinition {
+  readonly kind: "scalar";
+  readonly name: string;
+  readonly description?: string;
+  readonly builtin: true;
+}
+/** A scalar declared with `scalar<T>(name, definition)`: the definition is imported from user code. */
+interface GraphQLCustomScalarDefinition {
+  readonly kind: "scalar";
+  readonly name: string;
+  /** `ScalarDefinition<T>` of any `T` (its methods are bivariant), or a graphql-js scalar named `name`. */
+  readonly scalar: ScalarDefinition<unknown> | GraphQLScalarType;
+}
+/** A field of an object type. */
+interface GraphQLFieldDefinition {
+  readonly name: string;
+  /** Type reference (`'Book!'`, `'[Book!]!'`, `'Int'`), parsed by `type-ref.ts`. */
+  readonly type: string;
+  readonly description?: string;
+  readonly deprecationReason?: string;
+  readonly args?: readonly GraphQLArgumentDefinition[];
+  /** Absent: the graphql-js default resolver (`parent[name]`). */
+  readonly resolver?: GraphQLResolverBinding;
+}
+/** An argument of a field. */
+interface GraphQLArgumentDefinition {
+  readonly name: string;
+  readonly type: string;
+  readonly description?: string;
+  readonly deprecationReason?: string;
+  /**
+   * Default value, as an external value: JSON-compatible, enum values by GraphQL name (passed to
+   * graphql-js as `default: { value }`). Absent: no default.
+   */
+  readonly defaultValue?: unknown;
+  /** The TypeScript type does not accept `null`: a `null` sent by the client becomes `undefined` (§5.4). */
+  readonly nullAsUndefined?: true;
+}
+/** A field of an input object type. */
+interface GraphQLInputFieldDefinition extends GraphQLArgumentDefinition {}
+/** A value of an enum. */
+interface GraphQLEnumValueDefinition {
+  /** GraphQL name (the member name, or the literal). */
+  readonly name: string;
+  /** Internal value (the member value, or the literal), what resolvers receive and return. */
+  readonly value: string | number;
+  readonly description?: string;
+  readonly deprecationReason?: string;
+}
+/** How the runtime tells the members of a union apart (`resolveType`). */
+type GraphQLDiscriminator = {
+  readonly by: "property";
+  readonly property: string;
+  /** Literal value of the property (as a string) → member type name. */
+  readonly values: Readonly<Record<string, string>>;
+} | {
+  readonly by: "class";
+  /** Member classes and their type names, subclasses first (`instanceof` order). */
+  readonly classes: readonly (readonly [cls: abstract new (...args: never[]) => unknown, name: string])[];
+} | {
+  readonly by: "typename";
+};
+/** Kind of field a resolver method provides. */
+type GraphQLResolverOperation = "query" | "mutation" | "subscription" | "field";
+/** The resolver method behind a field. */
+interface GraphQLResolverBinding {
+  /** Provider token of the resolver class. */
+  readonly token: Token;
+  readonly method: string;
+  readonly operation: GraphQLResolverOperation;
+  /** Guard provider tokens: class `@UseGuard` guards, then method ones. */
+  readonly guards: readonly Token[];
+  /**
+   * Effective field metadata (`createRouteDecorator` values, method decisions over class ones, one
+   * decision per group). Empty: no metadata, so global guards skip a field resolver (§5.9).
+   */
+  readonly meta: Readonly<Record<string, unknown>>;
+  /** Informational: loader provider tokens the method injects. */
+  readonly loaders?: readonly Token[];
+  /**
+   * Calls the method: maps the graphql-js arguments to the method parameters (§7.3). Synchronous
+   * unless an argument is validated with a Standard Schema.
+   */
+  readonly invoke: (resolver: any, parent: unknown, args: GraphQLArgs, context: GraphQLContext, info: GraphQLResolveInfo) => unknown;
+}
+declare module "@znight/core" {
+  interface ZnightExtensionsMetadata {
+    readonly graphql?: GraphQLMetadata;
+  }
+}
+/** Options of {@link GraphQLPlugin.execute} and {@link GraphQLPlugin.subscribe}. */
+interface DirectExecuteOptions {
+  /** Cancels the operation (graphql-js `abortSignal`, `GraphQLContext.signal`). */
+  readonly signal?: AbortSignal;
+  /** `GraphQLContext.requestId`. Default: the request id of the enclosing scope, or a UUID. */
+  readonly requestId?: string;
+}
+/** A value of type `T` or a promise of it. */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * The GraphQL plugin: `GraphQLPlugin.configure(options)` (name `graphql`).
+ *
+ * ```ts
+ * await Application.create({
+ *   metadata: __ZNIGHT_METADATA__,
+ *   plugins: [HttpPlugin.configure(), GraphQLPlugin.configure({ guards: [AccessGuard] })],
+ * })
+ * ```
+ */
+export declare class GraphQLPlugin implements Plugin, PluginHttpRoutes {
+  #private;
+  readonly name = "graphql";
+  private constructor();
+  /**
+   * Creates the plugin. `options` may be a function of the container, evaluated once, when first
+   * needed after the container is initialised: `GraphQLPlugin.configure(c => ({ exposeErrors: c.get(Env).dev }))`.
+   */
+  static configure(options?: PluginOptions<GraphQLPluginOptions>): GraphQLPlugin;
+  /**
+   * Providers `TestApp` creates at boot: the classes of the `guards` and `errorMappers` options, and
+   * the resolvers, guards and loaders of the metadata.
+   */
+  initRoots(context?: PluginRootsContext): readonly ProviderKey[];
+  register(ctx: PluginContext): void;
+  /**
+   * The `PluginHttpRoutes` contract of `@znight/http`: the GraphQL endpoint (`GET` and `POST` on
+   * `path`). `[]` with `http: false`.
+   */
+  httpRoutes(context: PluginHttpRoutesContext): readonly PluginRoute[];
+  onBootstrap(ctx: PluginContext): void;
+  onStart(ctx: PluginContext): void;
+  onStop(): Promise<void>;
+  onDispose(): void;
+  /** The schema (after bootstrap). */
+  get schema(): GraphQLSchema;
+  /** The SDL of the schema (graphql-js `printSchema`). */
+  printSchema(): string;
+  /** The `PubSub` of the application: the `pubsub` option, or the plugin's `MemoryPubSub`. */
+  get pubsub(): PubSub;
+  /** Active subscriptions (every transport). */
+  get activeSubscriptions(): number;
+  /**
+   * Executes a query or a mutation outside of HTTP (custom transports, tests, a controller calling
+   * GraphQL), in the current request scope or in a scope of its own. Returns the result directly
+   * when every resolver is synchronous; `await` it. A subscription is an error result: use
+   * {@link subscribe}. Rejects only when `options.signal` aborts the execution.
+   */
+  execute(request: GraphQLRequest, options?: DirectExecuteOptions): MaybePromise<FormattedExecutionResult>;
+  /**
+   * Subscribes outside of HTTP: the results of the subscription, one per event, until the source
+   * ends, `options.signal` aborts, `return()` is called or the application stops. A request error
+   * or a query gives a stream of one result.
+   */
+  subscribe(request: GraphQLRequest, options?: DirectExecuteOptions): Promise<GraphQLResultStream>;
+}
+/**
+ * Tokens of the values `GraphQLPlugin` supplies to the container (declared in the package
+ * manifest). `GraphQLContext` is a request-scoped external: inject it in request-scoped providers
+ * or through `Lazy<GraphQLContext>`.
+ */
+export declare const GraphQLTokens: {
+  /** The {@link GraphQLContext} of the current operation (request scope). */
+  readonly Context: TypedToken<GraphQLContext>;
+  /** The application {@link PubSub} (singleton). */
+  readonly PubSub: TypedToken<PubSub>;
+  /** The {@link GraphQLPlugin} instance (singleton). */
+  readonly Plugin: TypedToken<GraphQLPlugin>;
+};
+/**
+ * Validates an argument value (after GraphQL coercion) with a [Standard Schema](https://standardschema.dev)
+ * (Zod, Valibot, ArkType...) and returns the schema **output** (transforms run, defaults applied).
+ *
+ * Synchronous when the schema validates synchronously (no promise, no microtask), a promise
+ * otherwise: generated code `await`s the result, which is free for a plain value.
+ *
+ * @param label what is validated, for the message: the argument name (`'input'`), or `'arguments'`
+ *   for `@Args(Schema)` without name.
+ * @throws GraphQLException `BAD_USER_INPUT`, `extensions.issues: [{ path, message }]`, when the
+ *   value is invalid.
+ * @throws TypeError when `schema` is not a Standard Schema v1 (a programming error, masked).
+ */
+export declare function validateArgs<S extends StandardSchemaV1$1>(schema: S, value: unknown, label: string): InferSchemaOutput<S> | Promise<InferSchemaOutput<S>>;
+export { type AnyPubSub, type BatchLoad, type BatchLoadClass, type BatchLoader, type DirectExecuteOptions, type Float, type GraphQLArgs, type GraphQLArgumentDefinition, type GraphQLBuiltinScalarDefinition, type GraphQLContext, type GraphQLCustomScalarDefinition, type GraphQLDiscriminator, type GraphQLEnumTypeDefinition, type GraphQLEnumValueDefinition, GraphQLErrorCode, type GraphQLErrorCodeValue, type GraphQLErrorMapper, type GraphQLErrorMapperClass, type GraphQLErrorMapperRef, GraphQLException, type GraphQLExceptionOptions, type GraphQLFieldDefinition, type GraphQLGuard, type GraphQLGuardClass, type GraphQLGuardRef, type GraphQLHttpOptions, type GraphQLInputFieldDefinition, type GraphQLInputTypeDefinition, type GraphQLLimits, type GraphQLMetadata, type GraphQLObjectTypeDefinition, type GraphQLOperationKind, type GraphQLPluginOptions, type GraphQLRequest, type GraphQLResolverBinding, type GraphQLResolverOperation, type GraphQLResultStream, type GraphQLRootTypes, type GraphQLSubscriptionOptions, type GraphQLTransport, type GraphQLTypeDefinition, type GraphQLUnionTypeDefinition, type ID, type Int, type JSONValue, type LoaderKey, type LoaderOptions, type LoaderValue, type MaybePromise, type MemoryPubSubOptions, type OrderByKeysOptions, type ResolverContext, type ResolverOptions, type ScalarDefinition, type StandardSchemaV1, type SubscribeOptions };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,128 @@
+import { a as MemoryPubSub, c as GraphQLErrorCode, i as GraphQLTokens, l as GraphQLException, o as PubSub, s as orderByKeys, t as GraphQLPlugin } from "./plugin-BdBxr5NQ.mjs";
+import { l as GRAPHQL_METADATA_VERSION } from "./names-BlzDM5cF.mjs";
+import { isThenable, toIssueDetail } from "@znight/http";
+// src/decorators.ts
+function marker() {}
+const classMarker = marker;
+const methodMarker = marker;
+const parameterMarker = marker;
+const classOrMethodMarker = marker;
+/**
+* Declares a resolver: a provider (singleton by default) whose `@Query`, `@Mutation`,
+* `@Subscription` and `@ResolveField` methods are fields of the schema. Route decorators of
+* `@znight/http` (`createRouteDecorator`) on the class are the default decisions of its fields.
+*
+* ```ts
+* @Resolver()
+* export class BookResolver {
+*   constructor(private readonly catalog: CatalogService) {}
+*
+*   @Query()
+*   book(@Args('id') id: ID): Promise<Book | null> {
+*     return this.catalog.find(id)
+*   }
+* }
+* ```
+*
+* @param options static: `{ scope? }`.
+*/
+function Resolver(_options) {
+	return classMarker;
+}
+/**
+* A field of the `Query` root type. The method's declared return type is the field type
+* (`Promise<T>` unwrapped), its `@Args` the arguments, its JSDoc the description.
+*
+* @param name static: field name. Default: the method name.
+*/
+function Query(_name) {
+	return methodMarker;
+}
+/**
+* A field of the `Mutation` root type.
+*
+* @param name static: field name. Default: the method name.
+*/
+function Mutation(_name) {
+	return methodMarker;
+}
+/**
+* A field of the `Subscription` root type. The method returns an `AsyncIterable<T>` (an async
+* generator, or `pubsub.subscribe(...)`), each value being the field value of one event.
+*
+* @param name static: field name. Default: the method name.
+*/
+function Subscription(_name) {
+	return methodMarker;
+}
+/**
+* A field resolver: adds a field to the type of the `@Parent()` parameter (mandatory), or replaces
+* the property field of the same name.
+*
+* @param name static: field name. Default: the method name.
+*/
+function ResolveField(_name) {
+	return methodMarker;
+}
+function Args(_nameOrSchema, _schema) {
+	return parameterMarker;
+}
+/** The parent object of a field resolver (`@ResolveField` only; its type is the parent type). */
+function Parent() {
+	return parameterMarker;
+}
+/** The `GraphQLContext` of the operation. */
+function Ctx() {
+	return parameterMarker;
+}
+/** The graphql-js `GraphQLResolveInfo` of the call (escape hatch). */
+function Info() {
+	return parameterMarker;
+}
+/** The DataLoader of the current execution for the `Loader<L>` parameter type (see {@link Loader}). */
+function Loader() {
+	return parameterMarker;
+}
+/**
+* Guards of the fields of a resolver class or of one field, run after the global guards (class
+* guards, then method guards). Guards are providers implementing `GraphQLGuard`.
+*
+* @param guards value: guard classes.
+*/
+function UseGuard(..._guards) {
+	return classOrMethodMarker;
+}
+function scalar(_name, definition) {
+	return definition;
+}
+// src/validate-args.ts
+/**
+* Validates an argument value (after GraphQL coercion) with a [Standard Schema](https://standardschema.dev)
+* (Zod, Valibot, ArkType...) and returns the schema **output** (transforms run, defaults applied).
+*
+* Synchronous when the schema validates synchronously (no promise, no microtask), a promise
+* otherwise: generated code `await`s the result, which is free for a plain value.
+*
+* @param label what is validated, for the message: the argument name (`'input'`), or `'arguments'`
+*   for `@Args(Schema)` without name.
+* @throws GraphQLException `BAD_USER_INPUT`, `extensions.issues: [{ path, message }]`, when the
+*   value is invalid.
+* @throws TypeError when `schema` is not a Standard Schema v1 (a programming error, masked).
+*/
+function validateArgs(schema, value, label) {
+	const props = schema !== null && (typeof schema === "object" || typeof schema === "function") ? schema["~standard"] : void 0;
+	if (props === null || typeof props !== "object" || props.version !== 1 || typeof props.validate !== "function") throw new TypeError(`The schema of ${label} is not a Standard Schema v1 (missing "~standard.validate")`);
+	const result = props.validate(value);
+	if (isThenable(result)) return Promise.resolve(result).then((settled) => unwrap(settled, label));
+	return unwrap(result, label);
+}
+function unwrap(result, label) {
+	if (result.issues === void 0) return result.value;
+	throw new GraphQLException(`Invalid ${label}`, {
+		code: GraphQLErrorCode.BadUserInput,
+		extensions: { issues: result.issues.map(toIssueDetail) }
+	});
+}
+export { Args, Ctx, GRAPHQL_METADATA_VERSION, GraphQLErrorCode, GraphQLException, GraphQLPlugin, GraphQLTokens, Info, Loader, MemoryPubSub, Mutation, Parent, PubSub, Query, ResolveField, Resolver, Subscription, UseGuard, orderByKeys, scalar, validateArgs };
+
+//# sourceMappingURL=index.mjs.map