grafast 0.0.1-alpha.13 → 0.0.1-alpha.15

package/dist/input.d.ts

@@ -3,5 +3,12 @@ import type { OperationPlan } from "./engine/OperationPlan.js";
 import type { AnyInputStep } from "./interfaces.js";
 export declare function assertInputStep(itemPlan: unknown): asserts itemPlan is AnyInputStep;
 export declare function graphqlGetTypeForNode(operationPlan: OperationPlan, node: NamedTypeNode | ListTypeNode | NonNullTypeNode): GraphQLType;
+/**
+ * Returns a plan for the given `rawInputValue` AST node which could be a
+ * variable or a literal, and could be nested so that a variable (or more than
+ * one) appears somewhere. More than one plan may be created.
+ *
+ * @internal
+ */
 export declare function inputStep(operationPlan: OperationPlan, inputType: GraphQLInputType, rawInputValue: ValueNode | undefined, defaultValue?: ConstValueNode | undefined): AnyInputStep;
 //# sourceMappingURL=input.d.ts.map

package/dist/interfaces.d.ts

@@ -1,7 +1,7 @@
 import type LRU from "@graphile/lru";
 import type EventEmitter from "eventemitter3";
 import type { PluginHook } from "graphile-config";
-import type { ASTNode, DocumentNode, ExecutionArgs, FragmentDefinitionNode, GraphQLArgument, GraphQLArgumentConfig, GraphQLError, GraphQLField, GraphQLFieldConfig, GraphQLInputField, GraphQLInputFieldConfig, GraphQLInputObjectType, GraphQLInputType, GraphQLList, GraphQLNonNull, GraphQLOutputType, GraphQLScalarType, GraphQLSchema, GraphQLType, OperationDefinitionNode, ValueNode, VariableNode } from "graphql";
+import type { ASTNode, DocumentNode, ExecutionArgs as GraphQLExecutionArgs, FragmentDefinitionNode, GraphQLArgs, GraphQLArgument, GraphQLArgumentConfig, GraphQLError, GraphQLField, GraphQLFieldConfig, GraphQLInputField, GraphQLInputFieldConfig, GraphQLInputObjectType, GraphQLInputType, GraphQLList, GraphQLNonNull, GraphQLOutputType, GraphQLScalarType, GraphQLSchema, GraphQLType, OperationDefinitionNode, ValueNode, VariableNode } from "graphql";
 import type { Bucket, RequestTools } from "./bucket.js";
 import type { OperationPlan } from "./engine/OperationPlan.js";
 import type { SafeError } from "./error.js";
@@ -11,15 +11,49 @@ import type { __InputListStep, __InputObjectStepWithDollars, __InputStaticLeafSt
 import type { GrafastInputObjectType, GrafastObjectType } from "./utils.js";
 type PromiseOrValue<T> = T | Promise<T>;
 export interface GrafastTimeouts {
+    /**
+     * How many milliseconds should we allow for planning. Remember: planning is
+     * synchronous, so whilst it is happening the event loop is blocked.
+     */
     planning?: number;
+    /**
+     * How many milliseconds should we allow for execution. We will only check
+     * this immediately before triggering the execution of an asynchronous step,
+     * and if it is exceeded it will only prevent the execution of asynchronous
+     * steps, not synchronous ones.
+     *
+     * IMPORTANT: since we only check this _before_ an asynchronous step
+     * executes, there's nothing to stop an asynchronous step from continuing to
+     * execute long after the timeout has expired - therefore it's the
+     * responsibility of each step to abort itself if it goes over the allocated
+     * time budget (which is detailed in `ExecutionExtra.stopTime`).
+     */
     execution?: number;
 }
 export interface GrafastOptions {
-    context?: Partial<Grafast.Context> | ((ctx: Partial<Grafast.RequestContext>, args: ExecutionArgs) => PromiseOrValue<Partial<Grafast.Context>>);
+    /**
+     * An object to merge into the GraphQL context. Alternatively, pass an
+     * (optionally asynchronous) function that returns an object to merge into
+     * the GraphQL context.
+     */
+    context?: Partial<Grafast.Context> | ((ctx: Partial<Grafast.RequestContext>, args: Grafast.ExecutionArgs) => PromiseOrValue<Partial<Grafast.Context>>);
+    /**
+     * A list of 'explain' types that should be included in `extensions.explain`.
+     *
+     * - `mermaid-js` will cause the mermaid plan to be included
+     * - other values are dependent on the plugins in play
+     *
+     * If set to `true` then all possible explain types will be exposed.
+     */
     explain?: boolean | string[];
     timeouts?: GrafastTimeouts;
 }
 export declare const $$queryCache: unique symbol;
+/**
+ * We store the cache directly onto the GraphQLSchema so that it gets garbage
+ * collected along with the schema when it's not needed any more. To do so, we
+ * attach it using this symbol.
+ */
 export declare const $$cacheByOperation: unique symbol;
 export type Fragments = {
     [key: string]: FragmentDefinitionNode;
@@ -31,7 +65,20 @@ export type OperationPlanOrError = OperationPlan | Error | SafeError<{
     [$$timeout]?: undefined;
     [$$ts]?: undefined;
 } | undefined>;
+/**
+ * This represents the list of possible operationPlans for a specific document.
+ *
+ * @remarks
+ *
+ * It also includes the fragments for validation, but generally we trust that
+ * if the OperationDefinitionNode is the same then the request is equivalent.
+ */
 export interface CacheByOperationEntry {
+    /**
+     * Implemented as a linked list so the hot operationPlans can be kept at the top of the
+     * list, and if the list grows beyond a maximum size we can drop the last
+     * element.
+     */
     possibleOperationPlans: LinkedList<OperationPlanOrError> | null;
     fragments: Fragments;
 }
@@ -39,10 +86,25 @@ export interface LinkedList<T> {
     value: T;
     next: LinkedList<T> | null;
 }
+export declare const $$hooked: unique symbol;
 declare global {
     namespace Grafast {
+        type ExecutionArgs = Pick<GraphQLExecutionArgs, "schema" | "document" | "rootValue" | "variableValues" | "operationName"> & {
+            [$$hooked]?: boolean;
+            contextValue: Grafast.Context;
+        };
+        /**
+         * Details about the incoming GraphQL request - e.g. if it was sent over an
+         * HTTP request, the request itself so headers can be interrogated.
+         *
+         * It's anticipated this will be expanded via declaration merging, e.g. if
+         * your server is Koa then a `koaCtx` might be added.
+         */
         interface RequestContext {
         }
+        /**
+         * The GraphQL context our schemas expect, generally generated from details in Grafast.RequestContext
+         */
         interface Context {
         }
         interface FieldExtensions {
@@ -72,28 +134,55 @@ declare global {
         interface EnumTypeExtensions {
         }
         interface EnumValueExtensions {
+            /**
+             * EXPERIMENTAL!
+             *
+             * @internal
+             */
             applyPlan?: EnumValueApplyPlanResolver<any>;
         }
         interface ScalarTypeExtensions {
             plan?: ScalarPlanResolver;
             inputPlan?: ScalarInputPlanResolver;
+            /**
+             * Set true if `serialize(serialize(foo)) === serialize(foo)` for all foo
+             */
             idempotent?: boolean;
         }
         interface SchemaExtensions {
+            /**
+             * Maximum number of queries to store in this schema's query cache.
+             */
             queryCacheMaxLength?: number;
+            /**
+             * The underlying query cache
+             */
             [$$queryCache]?: LRU<string, DocumentNode | ReadonlyArray<GraphQLError>>;
+            /**
+             * Maximum number of operations to store an operation plan lookup cache for
+             */
             operationsCacheMaxLength?: number;
+            /**
+             * Maximum number of operation plans to store in a single operation's cache
+             */
             operationOperationPlansCacheMaxLength?: number;
+            /**
+             * The starting point for finding/storing the relevant OperationPlan for a request.
+             */
             [$$cacheByOperation]?: LRU<OperationDefinitionNode, CacheByOperationEntry>;
         }
     }
     namespace GraphileConfig {
         interface Preset {
+            /**
+             * Options that control how `grafast` should execute your GraphQL
+             * operations.
+             */
             grafast?: GrafastOptions;
         }
         interface GrafastHooks {
             args: PluginHook<(event: {
-                args: ExecutionArgs;
+                args: Grafast.ExecutionArgs;
                 ctx: Grafast.RequestContext;
                 resolvedPreset: GraphileConfig.ResolvedPreset;
             }) => PromiseOrValue<void>>;
@@ -137,19 +226,56 @@ declare module "graphql" {
 export declare const $$grafastContext: unique symbol;
 export declare const $$planResults: unique symbol;
 export declare const $$id: unique symbol;
+/** Return the value verbatim, don't execute */
 export declare const $$verbatim: unique symbol;
+/**
+ * If we're sure the data is the right shape and valid, we can set this key and
+ * it can be returned directly
+ */
 export declare const $$bypassGraphQL: unique symbol;
 export declare const $$data: unique symbol;
+/**
+ * For attaching additional metadata to the GraphQL execution result, for
+ * example details of the plan or SQL queries or similar that were executed.
+ */
 export declare const $$extensions: unique symbol;
+/**
+ * The "GraphQLObjectType" type name, useful when dealing with polymorphism.
+ *
+ * @internal
+ */
 export declare const $$concreteType: unique symbol;
+/**
+ * Set this key on a type if that type's serialization is idempotent (that is
+ * to say `serialize(serialize(thing)) === serialize(thing)`). This means we
+ * don't have to "roll-back" serialization if we need to fallback to graphql-js
+ * execution.
+ */
 export declare const $$idempotent: unique symbol;
+/**
+ * The event emitter used for outputting execution events.
+ */
 export declare const $$eventEmitter: unique symbol;
+/**
+ * Used to indicate that an array has more results available via a stream.
+ */
 export declare const $$streamMore: unique symbol;
 export declare const $$proxy: unique symbol;
+/**
+ * If an error has this property set then it's safe to send through to the user
+ * without being masked.
+ */
 export declare const $$safeError: unique symbol;
+/** The layerPlan used as a subroutine for this step */
 export declare const $$subroutine: unique symbol;
+/** For tracking the timeout a TimeoutError happened from */
 export declare const $$timeout: unique symbol;
+/** For tracking _when_ the timeout happened (because once the JIT has warmed it might not need so long) */
 export declare const $$ts: unique symbol;
+/**
+ * When dealing with a polymorphic thing we need to be able to determine what
+ * the concrete type of it is, we use the $$concreteType property for that.
+ */
 export interface PolymorphicData<TType extends string = string, TData = any> {
     [$$concreteType]: TType;
     [$$data]?: TData;
@@ -171,13 +297,21 @@ export interface BaseGraphQLArguments {
 export type BaseGraphQLInputObject = BaseGraphQLArguments;
 export type TargetStepOrCallback = ExecutableStep | ModifierStep | ((indexOrFieldName: number | string) => TargetStepOrCallback);
 export type FieldArgs = {
+    /** Gets the value, evaluating the `inputPlan` at each field if appropriate */
     get(path?: string | ReadonlyArray<string | number>): ExecutableStep;
+    /** Gets the value *without* calling any `inputPlan`s */
     getRaw(path?: string | ReadonlyArray<string | number>): AnyInputStep;
+    /** This also works (without path) to apply each list entry against $target */
     apply($target: ExecutableStep | ModifierStep | (() => ModifierStep), path?: string | ReadonlyArray<string | number>): void;
 } & AnyInputStepDollars;
 export type InputStep<TInputType extends GraphQLInputType = GraphQLInputType> = GraphQLInputType extends TInputType ? AnyInputStep : TInputType extends GraphQLNonNull<infer U> ? Exclude<InputStep<U & GraphQLInputType>, ConstantStep<undefined>> : TInputType extends GraphQLList<GraphQLInputType> ? __InputListStep<TInputType> | __TrackedValueStep<any, TInputType> | ConstantStep<undefined> : TInputType extends GraphQLInputObjectType ? __TrackedValueStepWithDollars<any, TInputType> | __InputObjectStepWithDollars<TInputType> | ConstantStep<undefined> : AnyInputStep;
 export type AnyInputStep = __TrackedValueStepWithDollars<any, GraphQLInputType> | __InputListStep | __InputStaticLeafStep | __InputDynamicScalarStep | __InputObjectStepWithDollars<GraphQLInputObjectType> | ConstantStep<undefined>;
 export type AnyInputStepWithDollars = AnyInputStep & AnyInputStepDollars;
+/**
+ * Lies to make it easier to write TypeScript code like
+ * `{ $input: { $user: { $username } } }` without having to pass loads of
+ * generics.
+ */
 export type AnyInputStepDollars = {
     [key in string as `$${key}`]: AnyInputStepWithDollars;
 };
@@ -185,7 +319,30 @@ export interface FieldInfo {
     field: GraphQLField<any, any, any>;
     schema: GraphQLSchema;
 }
+/**
+ * Step resolvers are like regular resolvers except they're called beforehand,
+ * they return plans rather than values, and they only run once for lists
+ * rather than for each item in the list.
+ *
+ * The idea is that the plan resolver returns a plan object which later will
+ * process the data and feed that into the actual resolver functions
+ * (preferably using the default resolver function?).
+ *
+ * They are stored onto `<field>.extensions.grafast.plan`
+ *
+ * @returns a plan for this field.
+ *
+ * @remarks
+ * We're using `TrackedObject<...>` so we can later consider caching these
+ * executions.
+ */
 export type FieldPlanResolver<_TArgs extends BaseGraphQLArguments, TParentStep extends ExecutableStep | null, TResultStep extends ExecutableStep> = ($parentPlan: TParentStep, args: FieldArgs, info: FieldInfo) => TResultStep | null;
+/**
+ * Fields on input objects can have plans; the plan resolver is passed a parent plan
+ * (from an argument, or from a parent input object) or null if none, and an
+ * input plan that represents the value the user will pass to this field. The
+ * resolver must return either a ModifierStep or null.
+ */
 export type InputObjectFieldInputPlanResolver<TResultStep extends ExecutableStep = ExecutableStep> = (input: FieldArgs, info: {
     schema: GraphQLSchema;
     entity: GraphQLInputField;
@@ -198,6 +355,13 @@ export type InputObjectTypeInputPlanResolver = (input: FieldArgs, info: {
     schema: GraphQLSchema;
     type: GraphQLInputObjectType;
 }) => ExecutableStep;
+/**
+ * Arguments can have plans; the plan resolver is passed the parent plan (the
+ * plan that represents the _parent_ field of the field the arg is defined on),
+ * the field plan (the plan that represents the field the arg is defined on)
+ * and an input plan that represents the value the user will pass to this
+ * argument. The resolver must return either a ModifierStep or null.
+ */
 export type ArgumentInputPlanResolver<TParentStep extends ExecutableStep = ExecutableStep, TResultStep extends ExecutableStep = ExecutableStep> = ($parentPlan: TParentStep, input: FieldArgs, info: {
     schema: GraphQLSchema;
     entity: GraphQLArgument;
@@ -206,13 +370,30 @@ export type ArgumentApplyPlanResolver<TParentStep extends ExecutableStep = Execu
     schema: GraphQLSchema;
     entity: GraphQLArgument;
 }) => TResultStep;
+/**
+ * GraphQLScalarTypes can have plans, these are passed the field plan and must
+ * return an executable plan.
+ */
 export type ScalarPlanResolver<TParentStep extends ExecutableStep = ExecutableStep, TResultStep extends ExecutableStep = ExecutableStep> = ($parentPlan: TParentStep, info: {
     schema: GraphQLSchema;
 }) => TResultStep;
+/**
+ * GraphQLScalarTypes can have plans, these are passed the field plan and must
+ * return an executable plan.
+ */
 export type ScalarInputPlanResolver<TResultStep extends ExecutableStep = ExecutableStep> = ($inputValue: InputStep, info: {
     schema: GraphQLSchema;
     type: GraphQLScalarType;
 }) => TResultStep;
+/**
+ * EXPERIMENTAL!
+ *
+ * NOTE: this is an `any` because we want to allow users to specify
+ * subclasses of ExecutableStep but TypeScript only wants to allow
+ * superclasses.
+ *
+ * @internal
+ */
 export type EnumValueApplyPlanResolver<TParentStep extends ExecutableStep | ModifierStep = ExecutableStep | ModifierStep> = ($parent: TParentStep) => ModifierStep | void;
 type OutputPlanForNamedType<TType extends GraphQLType> = TType extends GrafastObjectType<any, infer TStep, any> ? TStep : ExecutableStep;
 export type OutputPlanForType<TType extends GraphQLOutputType> = TType extends GraphQLNonNull<GraphQLList<GraphQLNonNull<infer U>>> ? ListCapableStep<any, OutputPlanForNamedType<U>> | ExecutableStep<ReadonlyArray<any>> : TType extends GraphQLNonNull<GraphQLList<infer U>> ? ListCapableStep<any, OutputPlanForNamedType<U>> | ExecutableStep<ReadonlyArray<any>> : TType extends GraphQLList<GraphQLNonNull<infer U>> ? ListCapableStep<any, OutputPlanForNamedType<U>> | ExecutableStep<ReadonlyArray<any>> : TType extends GraphQLList<infer U> ? ListCapableStep<any, OutputPlanForNamedType<U>> | ExecutableStep<ReadonlyArray<any>> : TType extends GraphQLNonNull<infer U> ? OutputPlanForNamedType<U> : OutputPlanForNamedType<TType>;
@@ -220,15 +401,25 @@ type InputPlanForNamedType<TType extends GraphQLType> = TType extends GrafastInp
 type InputPlanForType<TType extends GraphQLInputType> = TType extends GraphQLNonNull<GraphQLList<GraphQLNonNull<infer U>>> ? InputPlanForNamedType<U> : TType extends GraphQLNonNull<GraphQLList<infer U>> ? InputPlanForNamedType<U> : TType extends GraphQLList<GraphQLNonNull<infer U>> ? InputPlanForNamedType<U> : TType extends GraphQLList<infer U> ? InputPlanForNamedType<U> : TType extends GraphQLNonNull<infer U> ? InputPlanForNamedType<U> : InputPlanForNamedType<TType>;
 type InputTypeForNamedType<TType extends GraphQLType> = TType extends GraphQLScalarType<infer U> ? U : any;
 type InputTypeFor<TType extends GraphQLInputType> = TType extends GraphQLNonNull<GraphQLList<GraphQLNonNull<infer U>>> ? InputTypeForNamedType<U> : TType extends GraphQLNonNull<GraphQLList<infer U>> ? InputTypeForNamedType<U> : TType extends GraphQLList<GraphQLNonNull<infer U>> ? InputTypeForNamedType<U> : TType extends GraphQLList<infer U> ? InputTypeForNamedType<U> : TType extends GraphQLNonNull<infer U> ? InputTypeForNamedType<U> : InputTypeForNamedType<TType>;
-export type GrafastFieldConfig<TType extends GraphQLOutputType, TContext extends Grafast.Context, TParentStep extends ExecutableStep | null, TFieldStep extends ExecutableStep, TArgs extends BaseGraphQLArguments> = Omit<GraphQLFieldConfig<any, any>, "args" | "type"> & {
+/**
+ * Basically GraphQLFieldConfig but with an easy to access `plan` method.
+ */
+export type GrafastFieldConfig<TType extends GraphQLOutputType, TContext extends Grafast.Context, TParentStep extends ExecutableStep | null, TFieldStep extends ExecutableStep, // TODO: should be OutputPlanForType<TType>, but that results in everything thinking it should be a ListStep
+TArgs extends BaseGraphQLArguments> = Omit<GraphQLFieldConfig<any, any>, "args" | "type"> & {
     type: TType;
     plan?: FieldPlanResolver<TArgs, TParentStep, TFieldStep>;
     subscribePlan?: FieldPlanResolver<TArgs, TParentStep, TFieldStep>;
     args?: GrafastFieldConfigArgumentMap<TType, TContext, TParentStep, TFieldStep>;
 };
+/**
+ * Basically GraphQLFieldConfigArgumentMap but allowing for args to have plans.
+ */
 export type GrafastFieldConfigArgumentMap<_TType extends GraphQLOutputType, TContext extends Grafast.Context, TParentStep extends ExecutableStep | null, TFieldStep extends ExecutableStep> = {
     [argName: string]: GrafastArgumentConfig<any, TContext, TParentStep, TFieldStep, any, any>;
 };
+/**
+ * Basically GraphQLArgumentConfig but allowing for a plan.
+ */
 export type GrafastArgumentConfig<TInputType extends GraphQLInputType = GraphQLInputType, _TContext extends Grafast.Context = Grafast.Context, _TParentStep extends ExecutableStep | null = ExecutableStep | null, TFieldStep extends ExecutableStep = ExecutableStep, _TArgumentStep extends TFieldStep extends ExecutableStep ? ModifierStep<TFieldStep> | null : null = TFieldStep extends ExecutableStep ? ModifierStep<TFieldStep> | null : null, _TInput extends InputTypeFor<TInputType> = InputTypeFor<TInputType>> = Omit<GraphQLArgumentConfig, "type"> & {
     type: TInputType;
     inputPlan?: ArgumentInputPlanResolver<any>;
@@ -236,6 +427,9 @@ export type GrafastArgumentConfig<TInputType extends GraphQLInputType = GraphQLI
     autoApplyAfterParentPlan?: boolean;
     autoApplyAfterParentSubscribePlan?: boolean;
 };
+/**
+ * Basically GraphQLInputFieldConfig but allowing for the field to have a plan.
+ */
 export type GrafastInputFieldConfig<TInputType extends GraphQLInputType, _TContext extends Grafast.Context, _TParentStep extends ModifierStep<any>, _TResultStep extends InputPlanForType<TInputType>, _TInput extends InputTypeFor<TInputType>> = Omit<GraphQLInputFieldConfig, "type"> & {
     type: TInputType;
     inputPlan?: InputObjectFieldInputPlanResolver;
@@ -243,19 +437,40 @@ export type GrafastInputFieldConfig<TInputType extends GraphQLInputType, _TConte
     autoApplyAfterParentInputPlan?: boolean;
     autoApplyAfterParentApplyPlan?: boolean;
 };
+/**
+ * The args passed to a field plan resolver, the values are plans.
+ */
 export type TrackedArguments<TArgs extends BaseGraphQLArguments = BaseGraphQLArguments> = {
     get<TKey extends keyof TArgs>(key: TKey): AnyInputStep;
 };
+/**
+ * `@stream` directive meta.
+ */
 export interface StepStreamOptions {
     initialCount: number;
 }
+/**
+ * Additional details about the planning for a field; currently only relates to
+ * the `@stream` directive.
+ */
 export interface StepOptions {
+    /**
+     * Details for the `@stream` directive.
+     */
     stream: StepStreamOptions | null;
 }
+/**
+ * Options passed to the `optimize` method of a plan to give more context.
+ */
 export interface StepOptimizeOptions {
     stream: StepStreamOptions | null;
     meta: Record<string, unknown> | undefined;
 }
+/**
+ * A subscriber provides realtime data, a SubscribeStep can subscribe to a
+ * given topic (string) and will receive an AsyncIterableIterator with messages
+ * published to that topic (standard pub/sub semantics).
+ */
 export type GrafastSubscriber<TTopics extends {
     [key: string]: any;
 } = {
@@ -263,17 +478,50 @@ export type GrafastSubscriber<TTopics extends {
 }> = {
     subscribe<TTopic extends keyof TTopics = keyof TTopics>(topic: TTopic): PromiseOrDirect<AsyncIterableIterator<TTopics[TTopic]>>;
 };
+/**
+ * Specifically relates to the stringification of NodeIDs, e.g. `["User", 1]`
+ * to/from `WyJVc2VyIiwgMV0=`
+ */
 export interface NodeIdCodec<T = any> {
     name: string;
     encode(value: T): string | null;
     decode(value: string): T;
 }
+/**
+ * Determines if a NodeID relates to a given object type, and also relates to
+ * encoding the NodeID for that type.
+ */
 export type NodeIdHandler<TCodec extends NodeIdCodec<any> = NodeIdCodec<any>, TNodeStep extends ExecutableStep = ExecutableStep, TSpec = any> = {
+    /**
+     * The name of the object type this handler is for.
+     */
     typeName: string;
+    /**
+     * Which codec are we using to encode/decode the NodeID string?
+     */
     codec: TCodec;
+    /**
+     * Returns true if the given decoded Node ID value represents this type.
+     */
     match(specifier: TCodec extends NodeIdCodec<infer U> ? U : any): boolean;
+    /**
+     * Returns a plan that returns the value ready to be encoded. When the result
+     * of this plan is fed into `match`, it should return `true`.
+     */
     plan($thing: TNodeStep): ExecutableStep<TCodec extends NodeIdCodec<infer U> ? U : any>;
+    /**
+     * Returns a specification based on the Node ID, this can be in any format
+     * you like. It is intended to then be fed into `get` or handled in your own
+     * code as you see fit. (When used directly, it's primarily useful for
+     * referencing a node without actually fetching it - e.g. allowing you to
+     * delete a node by its ID without first fetching it.)
+     */
     getSpec(plan: ExecutableStep<TCodec extends NodeIdCodec<infer U> ? U : any>): TSpec;
+    /**
+     * Combined with `getSpec`, this forms the recprocal of `plan`; i.e.
+     * `get(getSpec( plan(node) ))` should return a plan that results in the
+     * original node.
+     */
     get(spec: TSpec): TNodeStep;
     deprecationReason?: string;
 };
@@ -289,6 +537,10 @@ export interface TypedEventEmitter<TEventMap extends BaseEventMap> extends Event
     emit<TEventName extends EventMapKey<TEventMap>>(eventName: TEventName, params: TEventMap[TEventName]): boolean;
 }
 export type ExecutionEventMap = {
+    /**
+     * Something that can be added to the
+     * ExecutionResult.extensions.explain.operations list.
+     */
     explainOperation: {
         operation: Record<string, any> & {
             type: string;
@@ -298,15 +550,21 @@ export type ExecutionEventMap = {
 };
 export type ExecutionEventEmitter = TypedEventEmitter<ExecutionEventMap>;
 export interface ExecutionExtra {
+    /** The `performance.now()` at which your step should stop executing */
     stopTime: number | null;
+    /** If you have set a `metaKey` on your step, the relevant meta object which you can write into (e.g. for caching) */
     meta: Record<string, unknown> | undefined;
     eventEmitter: ExecutionEventEmitter | undefined;
+    /** @internal */
     _bucket: Bucket;
+    /** @internal */
     _requestContext: RequestTools;
 }
 export interface LocationDetails {
     node: ASTNode | readonly ASTNode[];
+    /** This should only be null for the root selection */
     parentTypeName: string | null;
+    /** This should only be null for the root selection */
     fieldName: string | null;
 }
 export type JSONValue = boolean | number | string | null | JSONObject | JSONArray;
@@ -315,7 +573,7 @@ export interface JSONObject {
 }
 export interface JSONArray extends Array<JSONValue> {
 }
-export type UnwrapPlanTuple<TIn extends readonly ExecutableStep[]> = {
+export type UnwrapPlanTuple</* const */ TIn extends readonly ExecutableStep[]> = {
     [Index in keyof TIn]: TIn[Index] extends ExecutableStep<infer U> ? U : never;
 } & {
     length: number;
@@ -327,5 +585,9 @@ export type StreamMaybeMoreableArray<T = any> = Array<T> & {
 export type StreamMoreableArray<T = any> = Array<T> & {
     [$$streamMore]: AsyncIterator<any, any, any> | Iterator<any, any, any>;
 };
+export interface GrafastArgs extends GraphQLArgs {
+    resolvedPreset?: GraphileConfig.ResolvedPreset;
+    requestContext?: Partial<Grafast.RequestContext>;
+}
 export {};
 //# sourceMappingURL=interfaces.d.ts.map

package/dist/makeGrafastSchema.d.ts

@@ -1,6 +1,11 @@
 import type { GraphQLFieldResolver, GraphQLScalarLiteralParser, GraphQLScalarSerializer, GraphQLScalarValueParser, GraphQLSchema } from "graphql";
 import type { EnumValueApplyPlanResolver, FieldPlanResolver, ScalarPlanResolver } from "./interfaces.js";
 import type { ExecutableStep } from "./step.js";
+/**
+ * When defining a field with `typeDefs/plans` you can declare the field plan
+ * directly, or you can define a configuration object that accepts the plan and
+ * more.
+ */
 export type FieldPlans = FieldPlanResolver<any, any, any> | {
     plan?: FieldPlanResolver<any, any, any>;
     subscribePlan?: FieldPlanResolver<any, any, any>;
@@ -10,6 +15,9 @@ export type FieldPlans = FieldPlanResolver<any, any, any> | {
         [argName: string]: Grafast.ArgumentExtensions;
     };
 };
+/**
+ * The plans/config for each field of a GraphQL object type.
+ */
 export type ObjectPlans = {
     __Step?: {
         new (...args: any[]): ExecutableStep;
@@ -17,27 +25,46 @@ export type ObjectPlans = {
 } & {
     [fieldName: string]: FieldPlans;
 };
+/**
+ * The plans for each field of a GraphQL input object type.
+ */
 export type InputObjectPlans = {
     [fieldName: string]: Grafast.InputFieldExtensions;
 };
+/**
+ * The plan config for an interface or union type.
+ */
 export type InterfaceOrUnionPlans = {
     __resolveType?: (o: unknown) => string;
 };
+/**
+ * The config for a GraphQL scalar type.
+ */
 export type ScalarPlans = {
     serialize?: GraphQLScalarSerializer<any>;
     parseValue?: GraphQLScalarValueParser<any>;
     parseLiteral?: GraphQLScalarLiteralParser<any>;
     plan?: ScalarPlanResolver<any, any>;
 };
+/**
+ * The values/configs for the entries in a GraphQL enum type.
+ */
 export type EnumPlans = {
     [enumValueName: string]: EnumValueApplyPlanResolver | string | number | boolean | {
         value?: unknown;
         applyPlan?: EnumValueApplyPlanResolver;
     };
 };
+/**
+ * A map from GraphQL named type to the config for that type.
+ */
 export interface GrafastPlans {
     [typeName: string]: ObjectPlans | InputObjectPlans | InterfaceOrUnionPlans | ScalarPlans | EnumPlans;
 }
+/**
+ * Takes a GraphQL schema definition in Interface Definition Language (IDL/SDL)
+ * syntax and configs for the types in it and returns a GraphQL schema.
+ */
 export declare function makeGrafastSchema(details: {
     typeDefs: string;
     plans: GrafastPlans;

package/dist/mermaid.d.ts

@@ -1,6 +1,28 @@
 import type { OperationPlan } from ".";
 import type { ExecutableStep } from "./step.js";
+/**
+ * An array of hex colour codes that we use for colouring the buckets/steps in
+ * the mermaid-js plan diagram.
+ *
+ * Generated by mokole.com/palette.html; re-ordered by Jem
+ */
 export declare const COLORS: string[];
+/**
+ * Given a string, escapes the string so that it can be embedded as the description of a node in a mermaid chart.
+ *
+ * 1. If it's already safe, returns it verbatim
+ * 2. If it contains disallowed characters, escape them by replacing them with similar-looking characters,
+ * 3. Wrap the string in quote marks.
+ *
+ * @remarks
+ *
+ * NOTE: rather than doing literal escapes, we replace with lookalike characters because:
+ *
+ * 1. Mermaid has a bug when calculating the width of the node that doesn't respect escapes,
+ * 2. It's easier to read the raw mermaid markup with substitutes rather than messy escapes.
+ *
+ * @internal
+ */
 export declare const mermaidEscape: (str: string) => string;
 export interface PrintPlanGraphOptions {
     printPathRelations?: boolean;
@@ -8,6 +30,12 @@ export interface PrintPlanGraphOptions {
     concise?: boolean;
     skipBuckets?: boolean;
 }
+/**
+ * Convert an OpPlan into a plan graph; call this via `operationPlan.printPlanGraph()`
+ * rather than calling this function directly.
+ *
+ * @internal
+ */
 export declare function printPlanGraph(operationPlan: OperationPlan, { concise, skipBuckets, }: PrintPlanGraphOptions, { steps, }: {
     steps: {
         [stepId: number]: ExecutableStep | null;

package/dist/polymorphic.d.ts

@@ -1,6 +1,14 @@
 import type { PolymorphicData } from "./interfaces.js";
 export declare function isPolymorphicData(data: unknown): data is PolymorphicData;
 export declare function assertPolymorphicData(data: unknown): asserts data is PolymorphicData;
+/**
+ * Returns an object with the given concrete type (and, optionally, associated
+ * data)
+ */
 export declare function polymorphicWrap<TType extends string, TData>(type: TType, data?: TData): PolymorphicData<TType, TData>;
+/**
+ * All polymorphic objects in Grafast have a $$concreteType property which
+ * contains the GraphQL object's type name; we simply return that.
+ */
 export declare function resolveType(o: unknown): string;
 //# sourceMappingURL=polymorphic.d.ts.map

package/dist/prepare.d.ts

@@ -3,7 +3,20 @@ import type { AsyncExecutionResult, ExecutionResult } from "graphql/execution/ex
 import type { GrafastTimeouts, PromiseOrDirect } from "./interfaces.js";
 declare const $$contextPlanCache: unique symbol;
 export interface GrafastPrepareOptions {
+    /**
+     * A list of 'explain' types that should be included in `extensions.explain`.
+     *
+     * - `mermaid-js` will cause the mermaid plan to be included
+     * - other values are dependent on the plugins in play
+     *
+     * If set to `true` then all possible explain types will be exposed.
+     */
     explain?: boolean | string[];
+    /**
+     * If true, the result will be returned as a string rather than an object -
+     * this is an optimization for returning the data over a network socket or
+     * similar.
+     */
     outputDataAsString?: boolean;
     timeouts?: GrafastTimeouts;
 }
@@ -12,6 +25,9 @@ declare module "./engine/OperationPlan.js" {
         [$$contextPlanCache]?: string;
     }
 }
+/**
+ * @internal
+ */
 export declare function grafastPrepare(args: ExecutionArgs, options?: GrafastPrepareOptions): PromiseOrDirect<ExecutionResult | AsyncGenerator<AsyncExecutionResult, void, void>>;
 export {};
 //# sourceMappingURL=prepare.d.ts.map