grafast 0.1.1-beta.2 → 0.1.1-beta.21

package/dist/interfaces.d.ts

@@ -1,12 +1,17 @@
 import type EventEmitter from "eventemitter3";
-import type { ASTNode, FragmentDefinitionNode, GraphQLArgs, GraphQLArgument, GraphQLArgumentConfig, GraphQLField, GraphQLFieldConfig, GraphQLInputField, GraphQLInputFieldConfig, GraphQLInputObjectType, GraphQLInputType, GraphQLList, GraphQLNonNull, GraphQLOutputType, GraphQLScalarType, GraphQLSchema, GraphQLType, ValueNode, VariableNode } from "graphql";
-import type { Bucket, RequestTools } from "./bucket.js";
+import type { Middleware } from "graphile-config";
+import type { ASTNode, ExecutionArgs, FragmentDefinitionNode, GraphQLArgs, GraphQLArgument, GraphQLArgumentConfig, GraphQLField, GraphQLFieldConfig, GraphQLInputField, GraphQLInputFieldConfig, GraphQLInputObjectType, GraphQLInputType, GraphQLList, GraphQLNonNull, GraphQLOutputType, GraphQLScalarType, GraphQLSchema, GraphQLType, OperationDefinitionNode, Source, ValueNode, VariableNode } from "graphql";
+import type { ObjMap } from "graphql/jsutils/ObjMap.js";
+import type { Constraint } from "./constraints.js";
+import type { LayerPlanReasonListItemStream } from "./engine/LayerPlan.js";
 import type { OperationPlan } from "./engine/OperationPlan.js";
-import type { SafeError } from "./error.js";
-import type { ExecutableStep, ListCapableStep, ModifierStep } from "./step.js";
+import type { FlaggedValue, SafeError } from "./error.js";
+import type { ListCapableStep, Step } from "./step.js";
+import type { __InputDefaultStep } from "./steps/__inputDefault.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";
+import type { ApplyableExecutableStep } from "./steps/applyInput.js";
+import type { __InputListStep, __InputObjectStepWithDollars, __InputStaticLeafStep, __TrackedValueStepWithDollars, ConstantStep, ObjectStep } from "./steps/index.js";
+import type { GrafastObjectType } from "./utils.js";
 export interface GrafastTimeouts {
     /**
      * How many milliseconds should we allow for planning. Remember: planning is
@@ -37,13 +42,26 @@ 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>;
+export interface IEstablishOperationPlanResult {
+    variableValuesConstraints: Constraint[];
+    contextConstraints: Constraint[];
+    rootValueConstraints: Constraint[];
+}
+export interface EstablishOperationPlanResultSuccess extends IEstablishOperationPlanResult {
+    error?: never;
+    operationPlan: OperationPlan;
+}
+export interface EstablishOperationPlanResultError extends IEstablishOperationPlanResult {
+    error: Error | SafeError<{
+        [$$timeout]: number;
+        [$$ts]: number;
+    } | {
+        [$$timeout]?: undefined;
+        [$$ts]?: undefined;
+    } | undefined>;
+    operationPlan?: never;
+}
+export type EstablishOperationPlanResult = EstablishOperationPlanResultSuccess | EstablishOperationPlanResultError;
 /**
  * This represents the list of possible operationPlans for a specific document.
  *
@@ -58,7 +76,7 @@ export interface CacheByOperationEntry {
      * list, and if the list grows beyond a maximum size we can drop the last
      * element.
      */
-    possibleOperationPlans: LinkedList<OperationPlanOrError> | null;
+    possibleOperationPlans: LinkedList<EstablishOperationPlanResult> | null;
     fragments: Fragments;
 }
 export interface LinkedList<T> {
@@ -84,8 +102,6 @@ export declare const $$data: unique symbol;
 export declare const $$extensions: unique symbol;
 /**
  * The "GraphQLObjectType" type name, useful when dealing with polymorphism.
- *
- * @internal
  */
 export declare const $$concreteType: unique symbol;
 /**
@@ -126,10 +142,13 @@ export interface PolymorphicData<TType extends string = string, TData = any> {
 export interface IndexByListItemStepId {
     [listItemStepId: number]: number;
 }
-export type GrafastValuesList<T> = ReadonlyArray<T>;
+export type GrafastValuesList<TData> = ReadonlyArray<TData>;
 export type PromiseOrDirect<T> = PromiseLike<T> | T;
-export type GrafastResultsList<T> = ReadonlyArray<PromiseOrDirect<T>>;
-export type GrafastResultStreamList<T> = ReadonlyArray<PromiseOrDirect<AsyncIterable<PromiseOrDirect<T>> | null> | PromiseLike<never>>;
+export type ExecutionResultValue<T> = T | FlaggedValue<Error> | FlaggedValue<null>;
+export type GrafastResultsList<TData> = ReadonlyArray<PromiseOrDirect<ExecutionResultValue<TData>>>;
+export type GrafastResultStreamList<TStreamItem> = ReadonlyArray<PromiseOrDirect<AsyncIterable<PromiseOrDirect<ExecutionResultValue<TStreamItem>>>> | PromiseLike<never>>;
+export type AwaitedExecutionResults<TData> = ReadonlyArray<PromiseOrDirect<ExecutionResultValue<TData> | AsyncIterable<PromiseOrDirect<ExecutionResultValue<TData extends ReadonlyArray<infer UStreamItem> ? UStreamItem : never>>>>>;
+export type ExecutionResults<TData> = PromiseOrDirect<AwaitedExecutionResults<TData>> | PromiseLike<never>;
 export type BaseGraphQLRootValue = any;
 export interface BaseGraphQLVariables {
     [key: string]: unknown;
@@ -138,17 +157,27 @@ export interface BaseGraphQLArguments {
     [key: string]: any;
 }
 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;
+    /** @deprecated Use bakedInput() step instead. */
+    get?: never;
+    getRaw(path?: string | ReadonlyArray<string | number>): AnyInputStep | ObjectStep<{
+        [argName: string]: AnyInputStep;
+    }>;
+    typeAt(path: string | ReadonlyArray<string | number>): GraphQLInputType;
     /** This also works (without path) to apply each list entry against $target */
-    apply($target: ExecutableStep | ModifierStep | (() => ModifierStep), path?: string | ReadonlyArray<string | number>): void;
+    apply<TArg extends object>($target: ApplyableExecutableStep<TArg>, path?: string | ReadonlyArray<string | number>, getTargetFromParent?: (parent: TArg, inputValue: any) => object | undefined): void;
+    apply<TArg extends object>($target: ApplyableExecutableStep<TArg>, getTargetFromParent: (parent: TArg, inputValue: any) => object | undefined, justTargetFromParent?: never): 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 FieldArg = {
+    /** @deprecated Use bakedInput() step instead. */
+    get?: never;
+    getRaw(path?: string | ReadonlyArray<string | number>): AnyInputStep;
+    typeAt(path: string | ReadonlyArray<string | number>): GraphQLInputType;
+    /** This also works (without path) to apply each list entry against $target */
+    apply<TArg extends object>($target: ApplyableExecutableStep<TArg>, path?: string | ReadonlyArray<string | number>, getTargetFromParent?: (parent: TArg, inputValue: any) => object | undefined): void;
+    apply<TArg extends object>($target: ApplyableExecutableStep<TArg>, getTargetFromParent: (parent: TArg, inputValue: any) => object | undefined, justTargetFromParent?: never): void;
+};
+export type AnyInputStep = __TrackedValueStepWithDollars<any, GraphQLInputType> | __InputListStep | __InputStaticLeafStep | __InputDynamicScalarStep | __InputObjectStepWithDollars<GraphQLInputObjectType> | __InputDefaultStep | ConstantStep<any>;
 export type AnyInputStepWithDollars = AnyInputStep & AnyInputStepDollars;
 /**
  * Lies to make it easier to write TypeScript code like
@@ -159,6 +188,7 @@ export type AnyInputStepDollars = {
     [key in string as `$${key}`]: AnyInputStepWithDollars;
 };
 export interface FieldInfo {
+    fieldName: string;
     field: GraphQLField<any, any, any>;
     schema: GraphQLSchema;
 }
@@ -179,52 +209,36 @@ export interface FieldInfo {
  * 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: {
+export type FieldPlanResolver<_TArgs extends BaseGraphQLArguments, TParentStep extends Step | null, TResultStep extends Step | null> = ($parentPlan: TParentStep, args: FieldArgs, info: FieldInfo) => TResultStep;
+export type InputObjectFieldApplyResolver<TParent> = (target: TParent, input: any, // Don't use unknown here, otherwise users can't easily cast it
+info: {
     schema: GraphQLSchema;
-    entity: GraphQLInputField;
-}) => TResultStep;
-export type InputObjectFieldApplyPlanResolver<TFieldStep extends ExecutableStep | ModifierStep<any> = ExecutableStep | ModifierStep<any>, TResultStep extends ModifierStep<ExecutableStep | ModifierStep<any>> | null | void = ModifierStep<ExecutableStep | ModifierStep<any>> | null | void> = ($fieldPlan: TFieldStep, input: FieldArgs, info: {
-    schema: GraphQLSchema;
-    entity: GraphQLInputField;
-}) => TResultStep;
-export type InputObjectTypeInputPlanResolver = (input: FieldArgs, info: {
+    fieldName: string;
+    field: GraphQLInputField;
+}) => any;
+export type InputObjectTypeBakedInfo = {
     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;
-}) => TResultStep;
-export type ArgumentApplyPlanResolver<TParentStep extends ExecutableStep = ExecutableStep, TFieldStep extends ExecutableStep | ModifierStep<any> = ExecutableStep | ModifierStep<any>, TResultStep extends ExecutableStep | ModifierStep<ExecutableStep | ModifierStep> | null | void = ExecutableStep | ModifierStep<ExecutableStep | ModifierStep> | null | void> = ($parentPlan: TParentStep, $fieldPlan: TFieldStep, input: FieldArgs, info: {
+    applyChildren(val: any): void;
+};
+export type InputObjectTypeBakedResolver = (input: Record<string, any>, info: InputObjectTypeBakedInfo) => any;
+export type ArgumentApplyPlanResolver<TParentStep extends Step = Step, TFieldStep extends Step = Step> = ($parentPlan: TParentStep, $fieldPlan: TFieldStep, input: FieldArg, info: {
     schema: GraphQLSchema;
-    entity: GraphQLArgument;
-}) => TResultStep;
+    arg: GraphQLArgument;
+    argName: string;
+}) => void;
 /**
  * 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: {
+export type ScalarPlanResolver<TParentStep extends Step = Step, TResultStep extends Step = Step> = ($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: {
+export type ScalarInputPlanResolver<TResultStep extends Step = Step> = ($inputValue: AnyInputStep, info: {
     schema: GraphQLSchema;
     type: GraphQLScalarType;
 }) => TResultStep;
@@ -235,50 +249,48 @@ export type ScalarInputPlanResolver<TResultStep extends ExecutableStep = Executa
  * subclasses of ExecutableStep but TypeScript only wants to allow
  * superclasses.
  *
- * @internal
+ * @experimental
  */
-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>;
-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 EnumValueApplyResolver<TParent = any> = (parent: TParent) => void;
+type OutputPlanForNamedType<TType extends GraphQLType> = TType extends GrafastObjectType<infer TStep, any> ? TStep : Step;
+export type OutputPlanForType<TType extends GraphQLOutputType> = TType extends GraphQLNonNull<GraphQLList<GraphQLNonNull<infer U>>> ? ListCapableStep<any, OutputPlanForNamedType<U>> | Step<ReadonlyArray<any>> : TType extends GraphQLNonNull<GraphQLList<infer U>> ? ListCapableStep<any, OutputPlanForNamedType<U>> | Step<ReadonlyArray<any>> : TType extends GraphQLList<GraphQLNonNull<infer U>> ? ListCapableStep<any, OutputPlanForNamedType<U>> | Step<ReadonlyArray<any>> : TType extends GraphQLList<infer U> ? ListCapableStep<any, OutputPlanForNamedType<U>> | Step<ReadonlyArray<any>> : TType extends GraphQLNonNull<infer U> ? OutputPlanForNamedType<U> : OutputPlanForNamedType<TType>;
 /**
  * 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
+export type GrafastFieldConfig<TType extends GraphQLOutputType, TParentStep extends Step | null, TFieldStep extends Step, // 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>;
+    args?: GrafastFieldConfigArgumentMap;
 };
 /**
  * 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>;
+export type GrafastFieldConfigArgumentMap = {
+    [argName: string]: GrafastArgumentConfig;
 };
 /**
  * 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"> & {
+export type GrafastArgumentConfig<TInputType extends GraphQLInputType = GraphQLInputType, _TContext extends Grafast.Context = Grafast.Context, _TParentStep extends Step | null = Step | null> = Omit<GraphQLArgumentConfig, "type"> & {
     type: TInputType;
-    inputPlan?: ArgumentInputPlanResolver<any>;
     applyPlan?: ArgumentApplyPlanResolver<any, any>;
-    autoApplyAfterParentPlan?: boolean;
-    autoApplyAfterParentSubscribePlan?: boolean;
+    applySubscribePlan?: ArgumentApplyPlanResolver<any, any>;
+    inputPlan?: never;
+    autoApplyAfterParentPlan?: never;
+    autoApplyAfterParentSubscribePlan?: never;
 };
 /**
  * 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"> & {
+export type GrafastInputFieldConfig<TParent = any, TInputType extends GraphQLInputType = GraphQLInputType> = Omit<GraphQLInputFieldConfig, "type"> & {
     type: TInputType;
-    inputPlan?: InputObjectFieldInputPlanResolver;
-    applyPlan?: InputObjectFieldApplyPlanResolver<any>;
-    autoApplyAfterParentInputPlan?: boolean;
-    autoApplyAfterParentApplyPlan?: boolean;
+    apply?: InputObjectFieldApplyResolver<TParent>;
+    inputPlan?: never;
+    applyPlan?: never;
+    autoApplyAfterParentInputPlan?: never;
+    autoApplyAfterParentApplyPlan?: never;
 };
 /**
  * The args passed to a field plan resolver, the values are plans.
@@ -289,8 +301,7 @@ export type TrackedArguments<TArgs extends BaseGraphQLArguments = BaseGraphQLArg
 /**
  * `@stream` directive meta.
  */
-export interface StepStreamOptions {
-    initialCount: number;
+export interface StepStreamOptions extends LayerPlanReasonListItemStream {
 }
 /**
  * Additional details about the planning for a field; currently only relates to
@@ -301,12 +312,23 @@ export interface StepOptions {
      * Details for the `@stream` directive.
      */
     stream: StepStreamOptions | null;
+    /**
+     * Should we walk an iterable if presented. This is important because we
+     * don't want to walk things like Map/Set except if we're doing it as part of
+     * a list step.
+     */
+    walkIterable: boolean;
 }
 /**
  * Options passed to the `optimize` method of a plan to give more context.
  */
 export interface StepOptimizeOptions {
-    stream: StepStreamOptions | null;
+    /**
+     * If null, this step will not stream. If non-null, this step _might_ stream,
+     * but it's not guaranteed - it may be dependent on user variables, e.g. the
+     * `if` parameter.
+     */
+    stream: null | {};
     meta: Record<string, unknown> | undefined;
 }
 /**
@@ -335,7 +357,7 @@ export interface NodeIdCodec<T = 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> = {
+export type NodeIdHandler<TIdentifiers extends readonly any[] = readonly any[], TCodec extends NodeIdCodec<any> = NodeIdCodec<any>, TNodeStep extends Step = Step, TSpec = any> = {
     /**
      * The name of the object type this handler is for.
      */
@@ -348,11 +370,16 @@ export type NodeIdHandler<TCodec extends NodeIdCodec<any> = NodeIdCodec<any>, TN
      * Returns true if the given decoded Node ID value represents this type.
      */
     match(specifier: TCodec extends NodeIdCodec<infer U> ? U : any): boolean;
+    /**
+     * Returns the underlying identifiers extracted from the decoded NodeID
+     * value.
+     */
+    getIdentifiers(value: TCodec extends NodeIdCodec<infer U> ? U : any): TIdentifiers;
     /**
      * 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>;
+    plan($thing: TNodeStep): Step<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
@@ -360,7 +387,7 @@ export type NodeIdHandler<TCodec extends NodeIdCodec<any> = NodeIdCodec<any>, TN
      * 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;
+    getSpec(plan: Step<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
@@ -393,16 +420,80 @@ export type ExecutionEventMap = {
     };
 };
 export type ExecutionEventEmitter = TypedEventEmitter<ExecutionEventMap>;
-export interface ExecutionExtra {
+export interface ExecutionExtraBase {
     /** 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 ExecutionExtra extends ExecutionExtraBase {
+}
+export interface UnbatchedExecutionExtra extends ExecutionExtraBase {
+    stream: ExecutionDetailsStream | null;
+}
+/**
+ * A bitwise number representing a number of flags:
+ *
+ * - 0: normal execution value
+ * - 1: errored (trappable)
+ * - 2: null (trappable)
+ * - 4: inhibited (trappable)
+ * - 8: disabled due to polymorphism (untrappable)
+ * - 16: stopped (untrappable) - e.g. due to fatal (unrecoverable) error
+ * - 32: ...
+ */
+export type ExecutionEntryFlags = number & {
+    readonly tsBrand?: unique symbol;
+};
+export declare const NO_FLAGS: ExecutionEntryFlags;
+export declare const FLAG_ERROR: ExecutionEntryFlags;
+export declare const FLAG_NULL: ExecutionEntryFlags;
+export declare const FLAG_INHIBITED: ExecutionEntryFlags;
+export declare const FLAG_POLY_SKIPPED: ExecutionEntryFlags;
+export declare const FLAG_STOPPED: ExecutionEntryFlags;
+export declare const ALL_FLAGS: ExecutionEntryFlags;
+/** By default, accept null values as an input */
+export declare const DEFAULT_ACCEPT_FLAGS: ExecutionEntryFlags;
+export declare const TRAPPABLE_FLAGS: ExecutionEntryFlags;
+export declare const DEFAULT_FORBIDDEN_FLAGS: ExecutionEntryFlags;
+export declare const FORBIDDEN_BY_NULLABLE_BOUNDARY_FLAGS: ExecutionEntryFlags;
+export type ExecutionValue<TData = any> = BatchExecutionValue<TData> | UnaryExecutionValue<TData>;
+interface ExecutionValueBase<TData = any> {
+    at(i: number): TData;
+    isBatch: boolean;
+    /** Returns this.value for a unary execution value; throws if non-unary */
+    unaryValue(): TData;
+}
+export interface BatchExecutionValue<TData = any> extends ExecutionValueBase<TData> {
+    isBatch: true;
+    entries: ReadonlyArray<TData>;
+    /** Always throws, since this should only be called on unary execution values */
+    unaryValue(): never;
+}
+export interface UnaryExecutionValue<TData = any> extends ExecutionValueBase<TData> {
+    isBatch: false;
+    value: TData;
+    /** Same as getting .value */
+    unaryValue(): TData;
+}
+export type IndexMap = <T>(callback: (i: number) => T) => ReadonlyArray<T>;
+export type IndexForEach = (callback: (i: number) => any) => void;
+export interface ExecutionDetailsStream {
+    initialCount: number;
+}
+export interface ExecutionDetails<TDeps extends readonly [...any[]] = readonly [...any[]]> {
+    count: number;
+    indexMap: IndexMap;
+    indexForEach: IndexForEach;
+    values: {
+        [DepIdx in keyof TDeps]: ExecutionValue<TDeps[DepIdx]>;
+    } & {
+        length: TDeps["length"];
+        map: ReadonlyArray<ExecutionValue<TDeps[number]>>["map"];
+    };
+    extra: ExecutionExtra;
+    stream: ExecutionDetailsStream | null;
 }
 export interface LocationDetails {
     node: ASTNode | readonly ASTNode[];
@@ -411,8 +502,8 @@ export interface LocationDetails {
     /** This should only be null for the root selection */
     fieldName: string | null;
 }
-export type UnwrapPlanTuple</* const */ TIn extends readonly ExecutableStep[]> = {
-    [Index in keyof TIn]: TIn[Index] extends ExecutableStep<infer U> ? U : never;
+export type UnwrapPlanTuple</* const */ TIn extends readonly Step[]> = {
+    [Index in keyof TIn]: DataFromStep<TIn[Index]>;
 };
 export type NotVariableValueNode = Exclude<ValueNode, VariableNode>;
 export type StreamMaybeMoreableArray<T = any> = Array<T> & {
@@ -424,7 +515,61 @@ export type StreamMoreableArray<T = any> = Array<T> & {
 export interface GrafastArgs extends GraphQLArgs {
     resolvedPreset?: GraphileConfig.ResolvedPreset;
     requestContext?: Partial<Grafast.RequestContext>;
+    middleware?: Middleware<GraphileConfig.GrafastMiddleware> | null;
 }
 export type Maybe<T> = T | null | undefined;
 export * from "./planJSONInterfaces.js";
+export interface AddDependencyOptions<TStep extends Step = Step> {
+    step: TStep;
+    skipDeduplication?: boolean;
+    /** @defaultValue `FLAG_NULL` */
+    acceptFlags?: ExecutionEntryFlags;
+    onReject?: Maybe<Error>;
+    nonUnaryMessage?: ($dependent: Step, $dependency: Step) => string;
+}
+export interface DependencyOptions<TStep extends Step = Step> {
+    step: TStep;
+    acceptFlags: ExecutionEntryFlags;
+    onReject: Maybe<Error>;
+}
+export type DataFromStep<TStep extends Step> = TStep extends Step<infer TData> ? TData : never;
+export interface GrafastExecutionArgs extends ExecutionArgs {
+    resolvedPreset?: GraphileConfig.ResolvedPreset;
+    middleware?: Middleware<GraphileConfig.GrafastMiddleware> | null;
+    requestContext?: Partial<Grafast.RequestContext>;
+    outputDataAsString?: boolean;
+}
+export interface ValidateSchemaEvent {
+    resolvedPreset: GraphileConfig.ResolvedPreset;
+    schema: GraphQLSchema;
+}
+export interface ParseAndValidateEvent {
+    resolvedPreset: GraphileConfig.ResolvedPreset;
+    schema: GraphQLSchema;
+    source: string | Source;
+}
+export interface PrepareArgsEvent {
+    args: Grafast.ExecutionArgs;
+}
+export interface ExecuteEvent {
+    args: GrafastExecutionArgs;
+}
+export interface SubscribeEvent {
+    args: GrafastExecutionArgs;
+}
+export interface EstablishOperationPlanEvent {
+    schema: GraphQLSchema;
+    operation: OperationDefinitionNode;
+    fragments: ObjMap<FragmentDefinitionNode>;
+    variableValues: Record<string, any>;
+    context: any;
+    rootValue: any;
+    planningTimeout: number | undefined;
+    args: GrafastExecutionArgs;
+}
+export interface ExecuteStepEvent {
+    args: GrafastExecutionArgs;
+    step: Step;
+    executeDetails: ExecutionDetails;
+}
 //# sourceMappingURL=interfaces.d.ts.map

package/dist/interfaces.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.$$ts = exports.$$timeout = exports.$$subroutine = exports.$$safeError = exports.$$proxy = exports.$$streamMore = exports.$$eventEmitter = exports.$$idempotent = exports.$$concreteType = exports.$$extensions = exports.$$data = exports.$$bypassGraphQL = exports.$$verbatim = exports.$$id = exports.$$planResults = exports.$$grafastContext = exports.$$hooked = exports.$$cacheByOperation = exports.$$queryCache = void 0;
+exports.$$deepDepSkip = exports.FORBIDDEN_BY_NULLABLE_BOUNDARY_FLAGS = exports.DEFAULT_FORBIDDEN_FLAGS = exports.TRAPPABLE_FLAGS = exports.DEFAULT_ACCEPT_FLAGS = exports.ALL_FLAGS = exports.FLAG_STOPPED = exports.FLAG_POLY_SKIPPED = exports.FLAG_INHIBITED = exports.FLAG_NULL = exports.FLAG_ERROR = exports.NO_FLAGS = exports.$$ts = exports.$$timeout = exports.$$subroutine = exports.$$safeError = exports.$$proxy = exports.$$streamMore = exports.$$eventEmitter = exports.$$idempotent = exports.$$concreteType = exports.$$extensions = exports.$$data = exports.$$bypassGraphQL = exports.$$verbatim = exports.$$id = exports.$$planResults = exports.$$grafastContext = exports.$$hooked = exports.$$cacheByOperation = exports.$$queryCache = void 0;
 const tslib_1 = require("tslib");
 exports.$$queryCache = Symbol("queryCache");
 /**
@@ -28,8 +28,6 @@ exports.$$data = Symbol("data");
 exports.$$extensions = Symbol("extensions");
 /**
  * The "GraphQLObjectType" type name, useful when dealing with polymorphism.
- *
- * @internal
  */
 exports.$$concreteType = Symbol("concreteType");
 /**
@@ -59,5 +57,24 @@ exports.$$subroutine = Symbol("subroutine");
 exports.$$timeout = Symbol("timeout");
 /** For tracking _when_ the timeout happened (because once the JIT has warmed it might not need so long) */
 exports.$$ts = Symbol("timestamp");
+function flag(f) {
+    return f;
+}
+exports.NO_FLAGS = flag(0);
+exports.FLAG_ERROR = flag(1 << 0);
+exports.FLAG_NULL = flag(1 << 1);
+exports.FLAG_INHIBITED = flag(1 << 2);
+exports.FLAG_POLY_SKIPPED = flag(1 << 3);
+exports.FLAG_STOPPED = flag(1 << 4);
+exports.ALL_FLAGS = flag(exports.FLAG_ERROR | exports.FLAG_NULL | exports.FLAG_INHIBITED | exports.FLAG_POLY_SKIPPED | exports.FLAG_STOPPED);
+/** By default, accept null values as an input */
+exports.DEFAULT_ACCEPT_FLAGS = flag(exports.FLAG_NULL);
+exports.TRAPPABLE_FLAGS = flag(exports.FLAG_ERROR | exports.FLAG_NULL | exports.FLAG_INHIBITED);
+exports.DEFAULT_FORBIDDEN_FLAGS = flag(exports.ALL_FLAGS & ~exports.DEFAULT_ACCEPT_FLAGS);
+exports.FORBIDDEN_BY_NULLABLE_BOUNDARY_FLAGS = flag(exports.FLAG_NULL | exports.FLAG_POLY_SKIPPED);
 tslib_1.__exportStar(require("./planJSONInterfaces.js"), exports);
+/**
+ * @internal
+ */
+exports.$$deepDepSkip = Symbol("deepDepSkip_experimental");
 //# sourceMappingURL=interfaces.js.map

package/dist/makeGrafastSchema.d.ts

@@ -1,6 +1,8 @@
-import type { GraphQLFieldResolver, GraphQLScalarLiteralParser, GraphQLScalarSerializer, GraphQLScalarValueParser, GraphQLSchema } from "graphql";
-import type { EnumValueApplyPlanResolver, FieldPlanResolver, ScalarPlanResolver } from "./interfaces.js";
-import type { ExecutableStep } from "./step.js";
+import type { GraphQLFieldResolver, GraphQLScalarLiteralParser, GraphQLScalarSerializer, GraphQLScalarValueParser } from "graphql";
+import { GraphQLSchema } from "graphql";
+import * as graphql from "graphql";
+import type { ArgumentApplyPlanResolver, EnumValueApplyResolver, FieldPlanResolver, InputObjectFieldApplyResolver, InputObjectTypeBakedResolver, ScalarPlanResolver } from "./interfaces.js";
+import type { Step } 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
@@ -12,15 +14,19 @@ export type FieldPlans = FieldPlanResolver<any, any, any> | {
     resolve?: GraphQLFieldResolver<any, any>;
     subscribe?: GraphQLFieldResolver<any, any>;
     args?: {
-        [argName: string]: Grafast.ArgumentExtensions;
+        [argName: string]: ArgumentApplyPlanResolver | {
+            applyPlan?: ArgumentApplyPlanResolver;
+            applySubscribePlan?: ArgumentApplyPlanResolver;
+            extensions?: graphql.GraphQLArgumentExtensions;
+        };
     };
 };
 /**
  * The plans/config for each field of a GraphQL object type.
  */
 export type ObjectPlans = {
-    __Step?: {
-        new (...args: any[]): ExecutableStep;
+    __assertStep?: ((step: Step) => asserts step is Step) | {
+        new (...args: any[]): Step;
     };
 } & {
     [fieldName: string]: FieldPlans;
@@ -29,7 +35,12 @@ export type ObjectPlans = {
  * The plans for each field of a GraphQL input object type.
  */
 export type InputObjectPlans = {
-    [fieldName: string]: Grafast.InputFieldExtensions;
+    __baked?: InputObjectTypeBakedResolver;
+} & {
+    [fieldName: string]: InputObjectFieldApplyResolver<any> | {
+        apply?: InputObjectFieldApplyResolver<any>;
+        extensions?: graphql.GraphQLInputFieldExtensions;
+    };
 };
 /**
  * The plan config for an interface or union type.
@@ -50,9 +61,10 @@ export type ScalarPlans = {
  * The values/configs for the entries in a GraphQL enum type.
  */
 export type EnumPlans = {
-    [enumValueName: string]: EnumValueApplyPlanResolver | string | number | boolean | {
+    [enumValueName: string]: EnumValueApplyResolver | string | number | boolean | {
         value?: unknown;
-        applyPlan?: EnumValueApplyPlanResolver;
+        extensions?: graphql.GraphQLEnumValueExtensions;
+        apply?: EnumValueApplyResolver;
     };
 };
 /**