@znight/graphql 0.2.2 → 0.4.0

package/dist/{types-DQ713UgI.d.mts → driver-DgbpFj4-.d.mts}

@@ -1,6 +1,6 @@
-import { Token } from "@znight/core";
-import { GuardEnforcement, HttpContext, RouteMetaCarrier } from "@znight/http";
-import { ConstValueNode, DocumentNode, GraphQLResolveInfo } from "graphql";
+import { Container, CoreLogger, Token } from "@znight/core";
+import { ByteSize, GuardEnforcement, HttpContext, HttpPlugin, PluginRoute, RouteMetaCarrier } from "@znight/http";
+import { ConstValueNode, DocumentNode, ExecutionArgs, ExecutionResult, FormattedExecutionResult, GraphQLError, GraphQLFormattedError, GraphQLResolveInfo, GraphQLSchema, Source, ValidationRule } from "graphql";
 /**
  * GraphQL errors shown to clients (RFC 0005 §5.10, §8.8): `GraphQLException` and the
  * `extensions.code` values the plugin produces (Apollo conventions, which clients already know).
@@ -70,8 +70,11 @@ declare class GraphQLException extends Error {
 type GraphQLArgs = Readonly<Record<string, unknown>>;
 /** Kind of a GraphQL operation. */
 type GraphQLOperationKind = "query" | "mutation" | "subscription";
-/** How an operation reached the server: GraphQL over HTTP, GraphQL over SSE, or `plugin.execute()`. */
-type GraphQLTransport = "http" | "sse" | "direct";
+/**
+ * How an operation reached the server: GraphQL over HTTP, GraphQL over SSE, GraphQL over WebSocket
+ * (`ws`, reserved for `graphql-ws`), or `plugin.execute()` / `plugin.subscribe()` (`direct`).
+ */
+type GraphQLTransport = "http" | "sse" | "ws" | "direct";
 /**
  * Options of a loader (§5.5), read once per loader class: the `options` property of a
  * {@link BatchLoad} provider. They are DataLoader's, except `batchScheduleFn` (Znight batches per
@@ -160,6 +163,13 @@ interface GraphQLContext {
   readonly signal: AbortSignal;
   /** Per-operation storage. */
   readonly state: Map<string | symbol, unknown>;
+  /**
+   * The context of the GraphQL server that received the operation through a driver (RFC 0009): the
+   * `contextValue` it passed to `GraphQLEngine.execute()` (Yoga's initial context, Apollo's context
+   * value). `undefined` for the built-in transport and direct calls. Resolvers do not need it: the
+   * request is `http`, the user a request-scoped provider.
+   */
+  readonly serverContext: unknown;
   /** The DataLoader of the current execution for a loader class (`ctx.loader(AuthorsById)`). */
   loader<L extends BatchLoad<unknown, unknown>>(loader: BatchLoadClass<L>): BatchLoader<LoaderKey<L>, LoaderValue<L>>;
   /**
@@ -168,9 +178,16 @@ interface GraphQLContext {
    */
   loader(token: Token): BatchLoader<unknown, unknown>;
 }
+declare module "@znight/core" {
+  /** Custom parameter decorators (`createParamDecorator`) resolve GraphQL parameters from the {@link ResolverContext}. */
+  interface ParamContexts {
+    graphql: ResolverContext;
+  }
+}
 /**
- * What a {@link GraphQLGuard} receives for one resolver call (§5.9). It satisfies the
- * `RouteMetaCarrier` of `@znight/http`, so route decorators read it: `Roles.get(ctx)`.
+ * What a {@link GraphQLGuard} receives for one resolver call (§5.9), and the context of custom
+ * parameter resolvers (RFC 0010). It satisfies the `RouteMetaCarrier` of `@znight/http`, so route
+ * decorators read it: `Roles.get(ctx)`.
  */
 interface ResolverContext<TParent = unknown, TArgs extends GraphQLArgs = GraphQLArgs> extends RouteMetaCarrier {
   /** Effective metadata of the field (method decisions over class decisions) and its schema coordinate. */
@@ -262,5 +279,172 @@ interface ScalarDefinition<T> {
   /** Literal of the document → internal value. Default: `parseValue` of the literal's JSON value. */
   parseLiteral?(literal: ConstValueNode): T;
 }
-export { GraphQLExceptionOptions as C, GraphQLException as S, LoaderValue as _, GraphQLContext as a, GraphQLErrorCode as b, GraphQLGuard as c, GraphQLResultMapper as d, GraphQLResultMapperClass as f, LoaderOptions as g, LoaderKey as h, GraphQLArgs as i, GraphQLGuardClass as l, GraphQLTransport as m, BatchLoadClass as n, GraphQLErrorMapper as o, GraphQLResultTypes as p, BatchLoader as r, GraphQLErrorMapperClass as s, BatchLoad as t, GraphQLOperationKind as u, ResolverContext as v, GraphQLErrorCodeValue as x, ScalarDefinition as y };
-//# sourceMappingURL=types-DQ713UgI.d.mts.map
+/** 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)
+ * }
+ * ```
+ */
+declare function orderByKeys<K, V>(keys: readonly K[], values: Iterable<V>, keyOf: (value: V) => K, options?: OrderByKeysOptions & {
+  readonly missing?: "error";
+}): (V | Error)[];
+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>>;
+}
+/** A value of type `T` or a promise of it (graphql-js `PromiseOrValue`). */
+type PromiseOrValue<T> = T | Promise<T>;
+/** Options of {@link GraphQLEngine.execute} and {@link GraphQLEngine.subscribe}. */
+interface EngineExecuteOptions {
+  /**
+   * The protocol that carried the operation (`GraphQLOperationEvent.transport`,
+   * `GraphQLContext.transport`): `'http'` (default), `'sse'` for an event stream, `'ws'` for
+   * `graphql-ws`.
+   */
+  readonly transport?: "http" | "sse" | "ws";
+  /**
+   * Cancels the operation (graphql-js `abortSignal`, `GraphQLContext.signal`). Default:
+   * `ExecutionArgs.abortSignal`, else the signal of the HTTP request of the current scope.
+   */
+  readonly signal?: AbortSignal;
+  /** `GraphQLContext.requestId`. Default: the request id of the HTTP request of the scope. */
+  readonly requestId?: string;
+}
+/** The resolved options a GraphQL server needs to configure itself (read-only). */
+interface GraphQLEngineSettings {
+  /** The endpoint path, the `HttpPlugin` prefix included (`/api/graphql`). */
+  readonly path: string;
+  readonly introspection: boolean;
+  /** The `graphiql` option: serve the server's IDE. */
+  readonly ide: boolean;
+  readonly exposeErrors: boolean;
+  /** `limits.maxTokens`, for servers that parse documents themselves. */
+  readonly maxTokens: number | undefined;
+  readonly subscriptions: false | {
+    readonly maxActive: number;
+  };
+  readonly http: false | {
+    readonly get: boolean;
+    readonly bodyLimit: ByteSize;
+  };
+}
+/**
+ * The engine of a bootstrapped `GraphQLPlugin` (`plugin.engine`, and the first argument of
+ * `GraphQLDriver.start()`). Its functions are bound: pass them around as they are.
+ *
+ * ```ts
+ * const handler = createHandler({
+ *   schema: engine.schema,
+ *   parse: engine.parse,
+ *   validate: engine.validate,
+ *   execute: args => engine.execute(args),
+ * })
+ * ```
+ */
+interface GraphQLEngine {
+  /** The executable schema: its resolvers are Znight's pipelines. */
+  readonly schema: GraphQLSchema;
+  readonly settings: GraphQLEngineSettings;
+  /**
+   * graphql-js `parse` through the document cache: `maxTokens`, then the depth, aliases and
+   * directives limits. Throws a `GraphQLError` (`GRAPHQL_PARSE_FAILED`, `QUERY_TOO_COMPLEX`), like
+   * graphql-js. A text the engine validated returns the same `DocumentNode`.
+   */
+  parse(source: string | Source): DocumentNode;
+  /**
+   * graphql-js `validate` with `rules` (default: graphql-js `specifiedRules`), to which the engine
+   * adds its own ({@link rules}), with `hideSuggestions` when introspection is off. With the
+   * default rules on {@link schema}, a document is validated once (then cached).
+   */
+  validate(schema: GraphQLSchema, document: DocumentNode, rules?: readonly ValidationRule[]): readonly GraphQLError[];
+  /** The engine's own rules (limits, introspection), for servers that validate documents themselves. */
+  readonly rules: readonly ValidationRule[];
+  /**
+   * Executes a validated query or mutation in the current request scope (or a scope of its own),
+   * with the operation's `GraphQLContext` as `contextValue` (`args.contextValue` becomes
+   * `GraphQLContext.serverContext`). Errors are mapped and masked, as `GraphQLError` instances.
+   */
+  execute(args: ExecutionArgs, options?: EngineExecuteOptions): PromiseOrValue<ExecutionResult>;
+  /**
+   * Starts a validated subscription: a stream of results, or a single error result (rejected, past
+   * `subscriptions.maxActive`, a source that could not start). The plugin ends the stream when the
+   * application stops.
+   */
+  subscribe(args: ExecutionArgs, options?: EngineExecuteOptions): PromiseOrValue<AsyncGenerator<ExecutionResult, void, void> | ExecutionResult>;
+}
+/** What {@link GraphQLDriver.routes} receives. */
+interface GraphQLDriverRoutesContext {
+  /** The `path` option: the endpoint path, relative to the `HttpPlugin` prefix (`/graphql`). */
+  readonly path: string;
+  /** The absolute endpoint path, the prefix included (`/api/graphql`). */
+  readonly endpoint: string;
+}
+/**
+ * A route of a driver: a plugin route of `HttpPlugin` without `meta`, `guards` and `bodyLimit`,
+ * which `GraphQLPlugin` adds from its `http` option (`bodyLimit` on the routes that are not `GET`).
+ */
+type GraphQLDriverRoute = Pick<PluginRoute, "method" | "path" | "name" | "handler">;
+/** What {@link GraphQLDriver.start} receives besides the engine. */
+interface GraphQLDriverContext {
+  /** The application logger. */
+  readonly logger: CoreLogger;
+  readonly container: Container;
+  /** The `HttpPlugin` of the application, when registered (its adapter, for server-mounted drivers). */
+  readonly http: HttpPlugin | undefined;
+}
+/**
+ * A GraphQL driver, given to `GraphQLPlugin.configure({ driver })`. A route-mounted driver returns
+ * its routes, which run in `HttpPlugin`'s pipeline (request scope, hooks, guards, CORS, drain) and
+ * call the engine from there; a server-mounted one has no routes and attaches itself to the
+ * adapter in `start()`. One driver serves one application at a time.
+ */
+interface GraphQLDriver {
+  /**
+   * The driver's name (`yoga`, `apollo`...): `GraphQLOperationEvent.driver`, logs and errors.
+   * `builtin` is reserved for the built-in transport.
+   */
+  readonly name: string;
+  /**
+   * The routes `HttpPlugin` serves for the driver, with the `http` option's meta, guards and body
+   * limit applied by the plugin. Called once per application, possibly before {@link start}: the
+   * handlers MUST NOT use the engine before the first request. Not called with `http: false`.
+   */
+  routes?(context: GraphQLDriverRoutesContext): readonly GraphQLDriverRoute[];
+  /**
+   * Called in `GraphQLPlugin.onBootstrap`, once the engine is built: create the server. A failure
+   * fails the boot (ZNIGHT066, the original error as `cause`).
+   */
+  start(engine: GraphQLEngine, context: GraphQLDriverContext): void | Promise<void>;
+  /**
+   * Stops the server, after the engine ended its subscriptions: in `GraphQLPlugin.onDispose` for a
+   * route-mounted driver (once `HttpPlugin` drained its requests, which the driver keeps serving),
+   * in `GraphQLPlugin.onStop` for a server-mounted one (drain and stop the server).
+   */
+  stop?(): void | Promise<void>;
+}
+export { ScalarDefinition as A, GraphQLResultMapperClass as C, LoaderOptions as D, LoaderKey as E, GraphQLErrorCodeValue as M, GraphQLException as N, LoaderValue as O, GraphQLExceptionOptions as P, GraphQLResultMapper as S, GraphQLTransport as T, GraphQLErrorMapper as _, EngineExecuteOptions as a, GraphQLGuardClass as b, GraphQLRequest as c, orderByKeys as d, BatchLoad as f, GraphQLContext as g, GraphQLArgs as h, GraphQLDriverRoutesContext as i, GraphQLErrorCode as j, ResolverContext as k, GraphQLResultStream as l, BatchLoader as m, GraphQLDriverContext as n, GraphQLEngine as o, BatchLoadClass as p, GraphQLDriverRoute as r, GraphQLEngineSettings as s, GraphQLDriver as t, OrderByKeysOptions as u, GraphQLErrorMapperClass as v, GraphQLResultTypes as w, GraphQLOperationKind as x, GraphQLGuard as y };
+//# sourceMappingURL=driver-DgbpFj4-.d.mts.map