grafast 0.0.1-alpha.9 → 0.0.1-beta.2

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;
-export declare function inputPlan(operationPlan: OperationPlan, inputType: GraphQLInputType, rawInputValue: ValueNode | undefined, defaultValue?: ConstValueNode | undefined): AnyInputStep;
+/**
+ * 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,35 +1,188 @@
+import type LRU from "@graphile/lru";
 import type EventEmitter from "eventemitter3";
 import type { PluginHook } from "graphile-config";
-import type { ASTNode, ExecutionArgs, GraphQLArgument, GraphQLArgumentConfig, GraphQLField, GraphQLFieldConfig, GraphQLInputField, GraphQLInputFieldConfig, GraphQLInputObjectType, GraphQLInputType, GraphQLList, GraphQLNonNull, GraphQLOutputType, GraphQLScalarType, GraphQLSchema, GraphQLType, 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";
 import type { ExecutableStep, ListCapableStep, ModifierStep } from "./step.js";
 import type { __InputDynamicScalarStep } from "./steps/__inputDynamicScalar.js";
 import type { __InputListStep, __InputObjectStepWithDollars, __InputStaticLeafStep, __TrackedValueStep, __TrackedValueStepWithDollars, ConstantStep } from "./steps/index.js";
 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?: Record<string, any> | (<TContext extends Record<string, any>>(ctx: Partial<Grafast.RequestContext>, currentContext?: Partial<TContext>) => PromiseOrValue<Partial<TContext>>);
+    /**
+     * 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;
+};
+export type OperationPlanOrError = OperationPlan | Error | SafeError<{
+    [$$timeout]: number;
+    [$$ts]: number;
+} | {
+    [$$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;
+}
+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 {
+            plan?: FieldPlanResolver<any, any, any>;
+            subscribePlan?: FieldPlanResolver<any, any, any>;
+        }
+        interface ArgumentExtensions {
+            inputPlan?: ArgumentInputPlanResolver;
+            applyPlan?: ArgumentApplyPlanResolver;
+            autoApplyAfterParentPlan?: boolean;
+            autoApplyAfterParentSubscribePlan?: boolean;
+        }
+        interface InputObjectTypeExtensions {
+            inputPlan?: InputObjectTypeInputPlanResolver;
+        }
+        interface InputFieldExtensions {
+            inputPlan?: InputObjectFieldInputPlanResolver;
+            applyPlan?: InputObjectFieldApplyPlanResolver;
+            autoApplyAfterParentInputPlan?: boolean;
+            autoApplyAfterParentApplyPlan?: boolean;
+        }
+        interface ObjectTypeExtensions {
+            assertStep?: ((step: ExecutableStep) => asserts step is ExecutableStep) | {
+                new (...args: any[]): ExecutableStep;
+            } | null;
+        }
+        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>>;
@@ -41,83 +194,88 @@ declare global {
         }
     }
 }
-export interface GrafastFieldExtensions {
-    plan?: FieldPlanResolver<any, any, any>;
-    subscribePlan?: FieldPlanResolver<any, any, any>;
-}
-export interface GrafastArgumentExtensions {
-    inputPlan?: ArgumentInputPlanResolver;
-    applyPlan?: ArgumentApplyPlanResolver;
-    autoApplyAfterParentPlan?: boolean;
-    autoApplyAfterParentSubscribePlan?: boolean;
-}
-export interface GrafastInputObjectTypeExtensions {
-    inputPlan?: InputObjectTypeInputPlanResolver;
-}
-export interface GrafastInputFieldExtensions {
-    inputPlan?: InputObjectFieldInputPlanResolver;
-    applyPlan?: InputObjectFieldApplyPlanResolver;
-    autoApplyAfterParentInputPlan?: boolean;
-    autoApplyAfterParentApplyPlan?: boolean;
-}
-export interface GrafastObjectTypeExtensions {
-    Step?: ((step: ExecutableStep) => asserts step is ExecutableStep) | {
-        new (...args: any[]): ExecutableStep;
-        displayName?: string;
-    };
-}
-export interface GrafastEnumTypeExtensions {
-}
-export interface GrafastEnumValueExtensions {
-    applyPlan?: EnumValueApplyPlanResolver<any>;
-}
-export interface GrafastScalarTypeExtensions {
-    plan?: ScalarPlanResolver;
-    inputPlan?: ScalarInputPlanResolver;
-    idempotent?: boolean;
-}
 declare module "graphql" {
     interface GraphQLFieldExtensions<_TSource, _TContext, _TArgs = any> {
-        grafast?: GrafastFieldExtensions;
+        grafast?: Grafast.FieldExtensions;
     }
     interface GraphQLArgumentExtensions {
-        grafast?: GrafastArgumentExtensions;
+        grafast?: Grafast.ArgumentExtensions;
     }
     interface GraphQLInputObjectTypeExtensions {
-        grafast?: GrafastInputObjectTypeExtensions;
+        grafast?: Grafast.InputObjectTypeExtensions;
     }
     interface GraphQLInputFieldExtensions {
-        grafast?: GrafastInputFieldExtensions;
+        grafast?: Grafast.InputFieldExtensions;
     }
     interface GraphQLObjectTypeExtensions<_TSource = any, _TContext = any> {
-        grafast?: GrafastObjectTypeExtensions;
+        grafast?: Grafast.ObjectTypeExtensions;
     }
     interface GraphQLEnumTypeExtensions {
-        grafast?: GrafastEnumTypeExtensions;
+        grafast?: Grafast.EnumTypeExtensions;
     }
     interface GraphQLEnumValueExtensions {
-        grafast?: GrafastEnumValueExtensions;
+        grafast?: Grafast.EnumValueExtensions;
     }
     interface GraphQLScalarTypeExtensions {
-        grafast?: GrafastScalarTypeExtensions;
+        grafast?: Grafast.ScalarTypeExtensions;
+    }
+    interface GraphQLSchemaExtensions {
+        grafast?: Grafast.SchemaExtensions;
     }
 }
 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;
@@ -128,7 +286,7 @@ export interface IndexByListItemStepId {
 export type GrafastValuesList<T> = ReadonlyArray<T>;
 export type PromiseOrDirect<T> = PromiseLike<T> | T;
 export type GrafastResultsList<T> = ReadonlyArray<PromiseOrDirect<T>>;
-export type GrafastResultStreamList<T> = ReadonlyArray<PromiseOrDirect<AsyncIterable<PromiseOrDirect<T>>> | PromiseLike<never>>;
+export type GrafastResultStreamList<T> = ReadonlyArray<PromiseOrDirect<AsyncIterable<PromiseOrDirect<T>> | null> | PromiseLike<never>>;
 export type BaseGraphQLRootValue = any;
 export interface BaseGraphQLVariables {
     [key: string]: unknown;
@@ -139,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;
 };
@@ -153,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;
@@ -166,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;
@@ -174,29 +370,56 @@ 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 : TType extends GraphQLNonNull<GraphQLList<infer U>> ? ListCapableStep<any, OutputPlanForNamedType<U>> | ExecutableStep : TType extends GraphQLList<GraphQLNonNull<infer U>> ? ListCapableStep<any, OutputPlanForNamedType<U>> | ExecutableStep : TType extends GraphQLList<infer U> ? ListCapableStep<any, OutputPlanForNamedType<U>> | ExecutableStep : TType extends GraphQLNonNull<infer U> ? OutputPlanForNamedType<U> : OutputPlanForNamedType<TType>;
+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>;
 type InputPlanForNamedType<TType extends GraphQLType> = TType extends GrafastInputObjectType<any, infer U, any> ? U : ModifierStep<any>;
 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>;
@@ -204,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;
@@ -211,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;
 } = {
@@ -231,20 +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;
 }
-export type NodeIdHandler<TCodecs extends {
-    [key: string]: NodeIdCodec<any>;
-} = {
-    [key: string]: NodeIdCodec<any>;
-}, TCodecName extends keyof TCodecs = keyof TCodecs, TNodeStep extends ExecutableStep = ExecutableStep, TSpec = any> = {
+/**
+ * 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;
-    codecName: TCodecName & string;
-    match(specifier: TCodecs[TCodecName] extends NodeIdCodec<infer U> ? U : any): boolean;
-    plan($thing: TNodeStep): ExecutableStep<TCodecs[TCodecName] extends NodeIdCodec<infer U> ? U : any>;
-    getSpec(plan: ExecutableStep<TCodecs[TCodecName] extends NodeIdCodec<infer U> ? U : any>): TSpec;
+    /**
+     * 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;
 };
@@ -260,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;
@@ -269,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;
@@ -286,11 +573,21 @@ 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;
 };
 export type NotVariableValueNode = Exclude<ValueNode, VariableNode>;
+export type StreamMaybeMoreableArray<T = any> = Array<T> & {
+    [$$streamMore]?: AsyncIterator<any, any, any> | Iterator<any, any, any>;
+};
+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