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

package/dist/steps/graphqlResolver.d.ts

@@ -4,6 +4,12 @@ import type { ExecutionExtra, GrafastResultsList, GrafastResultStreamList, Grafa
 import type { PolymorphicStep } from "../step.js";
 import { ExecutableStep, UnbatchedExecutableStep } from "../step.js";
 type ResolveInfoBase = Omit<GraphQLResolveInfo, "path" | "rootValue" | "variableValues">;
+/**
+ * Calls the given GraphQL resolver for each input - emulates GraphQL
+ * resolution.
+ *
+ * @internal
+ */
 export declare class GraphQLResolverStep extends UnbatchedExecutableStep {
     private resolver;
     private subscriber;
@@ -20,6 +26,7 @@ export declare class GraphQLResolverStep extends UnbatchedExecutableStep {
     private contextDep;
     private variableValuesDep;
     private rootValueDep;
+    /** root fields can have null parent */
     private isNotRoot;
     constructor(resolver: (GraphQLFieldResolver<any, any> & {
         displayName?: string;
@@ -32,6 +39,7 @@ export declare class GraphQLResolverStep extends UnbatchedExecutableStep {
     unbatchedStream(_extra: ExecutionExtra, source: any, args: any, context: any, variableValues: any, rootValue: any): any;
     stream(count: number, values: ReadonlyArray<GrafastValuesList<any>>, extra: ExecutionExtra): Promise<GrafastResultStreamList<any>>;
 }
+/** @internal */
 export declare class GraphQLItemHandler extends ExecutableStep implements PolymorphicStep {
     static $$export: {
         moduleName: string;
@@ -43,6 +51,10 @@ export declare class GraphQLItemHandler extends ExecutableStep implements Polymo
     constructor($parent: ExecutableStep, nullableType: GraphQLNullableType & GraphQLOutputType);
     planForType(): this;
     listItem($item: __ItemStep<any>): GraphQLItemHandler;
+    /**
+     * Akin to graphql-js' completeAbstractValue... but just the typeName
+     * resolution part.
+     */
     private figureOutTheTypeOf;
     private actuallyWrapData;
     private polymorphicWrapData;
@@ -54,6 +66,12 @@ export declare class GraphQLItemHandler extends ExecutableStep implements Polymo
     execute(_count: number, values: [GrafastValuesList<any>]): GrafastResultsList<any>;
 }
 export declare function graphqlItemHandler($item: ExecutableStep, nullableType: GraphQLNullableType & GraphQLOutputType): GraphQLItemHandler;
+/**
+ * Emulates what GraphQL does when calling a resolver, including handling of
+ * polymorphism.
+ *
+ * @internal
+ */
 export declare function graphqlResolver(resolver: GraphQLFieldResolver<any, any> | null | undefined, subscriber: GraphQLFieldResolver<any, any> | null | undefined, $step: ExecutableStep, $args: ObjectStep, resolveInfoBase: ResolveInfoBase): ExecutableStep;
 export {};
 //# sourceMappingURL=graphqlResolver.d.ts.map

package/dist/steps/groupBy.d.ts

@@ -1,5 +1,11 @@
 import type { ExecutableStep } from "../step.js";
 import type { __ListTransformStep, ListTransformItemPlanCallback } from "./listTransform.js";
 export type GroupByPlanMemo = Map<unknown, unknown[]>;
+/**
+ * Takes a single dimensional list plan and a mapper that returns a grouping
+ * key. Returns a plan that results in a Map where the keys are the grouping
+ * keys and the values are lists of the original entries that match these
+ * grouping keys.
+ */
 export declare function groupBy<TListStep extends ExecutableStep<readonly any[]>, TItemStep extends ExecutableStep<number>>(listStep: TListStep, mapper: ListTransformItemPlanCallback<TListStep, TItemStep>): __ListTransformStep<TListStep, TItemStep, GroupByPlanMemo, any>;
 //# sourceMappingURL=groupBy.d.ts.map

package/dist/steps/index.d.ts

@@ -2,6 +2,10 @@ import type { OperationPlan } from "../index.js";
 import type { __ValueStep } from "./__value.js";
 export declare function operationPlan(): OperationPlan;
 export declare function context<TContext extends Grafast.Context = Grafast.Context>(): __ValueStep<TContext>;
+/**
+ * Turns on debug mode, calls the callback, and then turns debug mode back off
+ * again.
+ */
 export declare function debugPlans<T>(callback: () => T): T;
 export { access, AccessStep } from "./access.js";
 export { assertEdgeCapableStep, assertPageInfoCapableStep, connection, ConnectionCapableStep, ConnectionStep, EdgeCapableStep, EdgeStep, PageInfoCapableStep, } from "./connection.js";

package/dist/steps/lambda.d.ts

@@ -1,6 +1,9 @@
 import type { ExecutionExtra, PromiseOrDirect, UnwrapPlanTuple } from "../interfaces.js";
 import type { ExecutableStep } from "../step.js";
 import { UnbatchedExecutableStep } from "../step.js";
+/**
+ * Calls the given lambda function for each tuple
+ */
 export declare class LambdaStep<TIn, TOut> extends UnbatchedExecutableStep<TOut> {
     private fn;
     static $$export: {
@@ -15,6 +18,11 @@ export declare class LambdaStep<TIn, TOut> extends UnbatchedExecutableStep<TOut>
     deduplicate(peers: LambdaStep<any, any>[]): LambdaStep<TIn, TOut>[];
     unbatchedExecute(_extra: ExecutionExtra, value: TIn): PromiseOrDirect<TOut>;
 }
+/**
+ * A plan that takes the input `$plan` and feeds each value through the `fn`
+ * callback. Note: if you need to pass more than one value, pass a `ListStep`
+ * as the `$plan` argument.
+ */
 declare function lambda<const TIn extends readonly ExecutableStep[], TOut>(plans: TIn, fn: (value: UnwrapPlanTuple<TIn>) => PromiseOrDirect<TOut>, isSyncAndSafe?: boolean): LambdaStep<UnwrapPlanTuple<TIn>, TOut>;
 declare function lambda<const TIn, TOut>($plan: ExecutableStep<TIn> | null | undefined, fn: (value: TIn) => PromiseOrDirect<TOut>, isSyncAndSafe?: boolean): LambdaStep<TIn, TOut>;
 export { lambda };

package/dist/steps/last.d.ts

@@ -13,5 +13,9 @@ export declare class LastStep<TData> extends UnbatchedExecutableStep<TData> {
     deduplicate(peers: LastStep<TData>[]): LastStep<TData>[];
     optimize(): ExecutableStep<any> | this;
 }
+/**
+ * A plan that resolves to the last entry in the list returned by the given
+ * plan.
+ */
 export declare function last<TData>(plan: ExecutableStep<ReadonlyArray<TData>>): LastStep<TData>;
 //# sourceMappingURL=last.d.ts.map

package/dist/steps/list.d.ts

@@ -16,7 +16,14 @@ export declare class ListStep<const TPlanTuple extends readonly ExecutableStep[]
     unbatchedExecute(_extra: ExecutionExtra, ...values: any[]): UnwrapPlanTuple<TPlanTuple>;
     deduplicate(peers: ListStep<TPlanTuple>[]): ListStep<TPlanTuple>[];
     optimize(opts: StepOptimizeOptions): this | ConstantStep<any[]>;
+    /**
+     * Get the original plan at the given index back again.
+     */
     at<TIndex extends keyof TPlanTuple>(index: TIndex): TPlanTuple[TIndex];
 }
+/**
+ * Takes a list of plans and turns it into a single plan that represents the
+ * list of their values.
+ */
 export declare function list<const TPlanTuple extends readonly ExecutableStep[]>(list: TPlanTuple): ListStep<TPlanTuple>;
 //# sourceMappingURL=list.d.ts.map

package/dist/steps/listTransform.d.ts

@@ -19,6 +19,15 @@ export interface ListTransformOptions<TListStep extends ExecutableStep<readonly
     optimize?: (this: __ListTransformStep<TListStep, TDepsStep, TMemo, TItemStep>) => ExecutableStep;
     connectionClone?: ConnectionCapableStep<TListStep, any>["connectionClone"];
 }
+/**
+ * **Experimental.**
+ *
+ * A "special" plan that has custom handling in Grafast. Used for turning lists
+ * into other things (or maybe more lists!).
+ *
+ * It's recommended that you don't use this directly, please use one of the
+ * functions that uses this under the hood such as `filter()`.
+ */
 export declare class __ListTransformStep<TListStep extends ExecutableStep<readonly any[]> = ExecutableStep<readonly any[]>, TDepsStep extends ExecutableStep = ExecutableStep, TMemo = any, TItemStep extends ExecutableStep | undefined = ExecutableStep | undefined> extends ExecutableStep<TMemo> {
     static $$export: {
         moduleName: string;
@@ -33,7 +42,11 @@ export declare class __ListTransformStep<TListStep extends ExecutableStep<readon
     listItem?: (itemPlan: __ItemStep<this>) => TItemStep;
     private meta;
     connectionClone?: ConnectionCapableStep<TListStep, any>["connectionClone"];
+    /** Set during query planning.  */
     itemStepId: number;
+    /**
+     * @internal
+     */
     subroutineLayer: LayerPlan<LayerPlanReasonSubroutine>;
     constructor(options: ListTransformOptions<TListStep, TDepsStep, TMemo, TItemStep>);
     toStringMeta(): string | null;
@@ -44,5 +57,13 @@ export declare class __ListTransformStep<TListStep extends ExecutableStep<readon
     optimize(): ExecutableStep;
     execute(_count: number, values: [GrafastValuesList<any[] | null | undefined | GrafastError>], extra: ExecutionExtra): Promise<GrafastResultsList<TMemo>>;
 }
+/**
+ * **Experimental.**
+ *
+ * A "special" plan that has custom handling in Grafast. Used for turning lists
+ * into other things (or maybe more lists!).
+ *
+ * {@page ~grafast/steps/listTransform.md}
+ */
 export declare function listTransform<TListStep extends ExecutableStep<readonly any[]>, TDepsStep extends ExecutableStep, TMemo, TItemStep extends ExecutableStep | undefined = undefined>(options: ListTransformOptions<TListStep, TDepsStep, TMemo, TItemStep>): __ListTransformStep<TListStep, TDepsStep, TMemo, TItemStep>;
 //# sourceMappingURL=listTransform.d.ts.map

package/dist/steps/listen.d.ts

@@ -2,6 +2,11 @@ import type { GrafastResultStreamList, GrafastSubscriber, GrafastValuesList } fr
 import type { StreamableStep } from "../step.js";
 import { ExecutableStep } from "../step.js";
 import type { __ItemStep } from "./__item.js";
+/**
+ * Subscribes to the given `pubsubOrPlan` to get realtime updates on a given
+ * topic (`topicOrPlan`), mapping the resulting event via the `itemPlan`
+ * callback.
+ */
 export declare class ListenStep<TTopics extends {
     [topic: string]: any;
 }, TTopic extends keyof TTopics, TPayloadStep extends ExecutableStep> extends ExecutableStep<TTopics[TTopic]> implements StreamableStep<TTopics[TTopic]> {
@@ -11,7 +16,13 @@ export declare class ListenStep<TTopics extends {
         exportName: string;
     };
     isSyncAndSafe: boolean;
+    /**
+     * The id for the PostgreSQL context plan.
+     */
     private pubsubDep;
+    /**
+     * The plan that will tell us which topic we're subscribing to.
+     */
     private topicDep;
     constructor(pubsubOrPlan: ExecutableStep<GrafastSubscriber<TTopics> | null> | GrafastSubscriber<TTopics> | null, topicOrPlan: ExecutableStep<TTopic> | string, itemPlan?: (itemPlan: __ItemStep<TTopics[TTopic]>) => TPayloadStep);
     execute(): never;
@@ -20,6 +31,11 @@ export declare class ListenStep<TTopics extends {
         GrafastValuesList<TTopic>
     ]): GrafastResultStreamList<TTopics[TTopic]>;
 }
+/**
+ * Subscribes to the given `pubsubOrPlan` to get realtime updates on a given
+ * topic (`topicOrPlan`), mapping the resulting event via the `itemPlan`
+ * callback.
+ */
 export declare function listen<TTopics extends {
     [topic: string]: any;
 }, TTopic extends keyof TTopics, TPayloadStep extends ExecutableStep>(pubsubOrPlan: ExecutableStep<GrafastSubscriber<TTopics> | null> | GrafastSubscriber<TTopics> | null, topicOrPlan: ExecutableStep<TTopic> | string, itemPlan?: (itemPlan: __ItemStep<TTopics[TTopic]>) => TPayloadStep): ListenStep<TTopics, TTopic, TPayloadStep>;

package/dist/steps/load.d.ts

@@ -11,8 +11,21 @@ type LoadCallback<TSpec, TItem, TData extends TItem | ReadonlyArray<TItem>, TPar
 };
 export type LoadOneCallback<TSpec, TItem, TParams extends Record<string, any>> = LoadCallback<TSpec, TItem, TItem, TParams>;
 export type LoadManyCallback<TSpec, TItem, TParams extends Record<string, any>> = LoadCallback<TSpec, TItem, ReadonlyArray<TItem>, TParams>;
+/**
+ * A TypeScript Identity Function to help you strongly type your
+ * LoadOneCallback.
+ */
 export declare function loadOneCallback<TSpec, TItem, TParams extends Record<string, any>>(callback: LoadOneCallback<TSpec, TItem, TParams>): LoadOneCallback<TSpec, TItem, TParams>;
+/**
+ * A TypeScript Identity Function to help you strongly type your
+ * LoadManyCallback.
+ */
 export declare function loadManyCallback<TSpec, TItem, TParams extends Record<string, any>>(callback: LoadManyCallback<TSpec, TItem, TParams>): LoadManyCallback<TSpec, TItem, TParams>;
+/**
+ * You shouldn't create instances of this yourself - use `loadOne` or `loadMany` instead.
+ *
+ * @internal
+ */
 export declare class LoadedRecordStep<TItem, TParams extends Record<string, any>> extends ExecutableStep<TItem> {
     private isSingle;
     private sourceDescription;

package/dist/steps/node.d.ts

@@ -2,6 +2,12 @@ import type { GraphQLObjectType } from "graphql";
 import type { ExecutionExtra, NodeIdHandler, PolymorphicData } from "../interfaces.js";
 import type { ExecutableStep, PolymorphicStep } from "../step.js";
 import { UnbatchedExecutableStep } from "../step.js";
+/**
+ * A plan to get a Node by it's global object identifier (string). Accepts an
+ * object specifying the supported codecs, an object map detailing the
+ * typeNames supported and their details (codec to use, how to find the record,
+ * etc), and finally the Node id string plan.
+ */
 export declare class NodeStep extends UnbatchedExecutableStep implements PolymorphicStep {
     private possibleTypes;
     static $$export: {
@@ -18,6 +24,12 @@ export declare class NodeStep extends UnbatchedExecutableStep implements Polymor
     private getTypeNameFromSpecifier;
     unbatchedExecute: (_extra: ExecutionExtra, specifier: any) => PolymorphicData<string, ReadonlyArray<any>> | null;
 }
+/**
+ * A plan to get a Node by it's global object identifier (string). Accepts an
+ * object specifying the supported codecs, an object map detailing the
+ * typeNames supported and their details (codec to use, how to find the record,
+ * etc), and finally the Node id string plan.
+ */
 export declare function node(possibleTypes: {
     [typeName: string]: NodeIdHandler;
 }, $id: ExecutableStep<string>): NodeStep;

package/dist/steps/object.d.ts

@@ -20,6 +20,10 @@ export interface ObjectPlanMeta<TPlans extends {
 }> {
     results: Results<TPlans>;
 }
+/**
+ * A plan that represents an object using the keys given and the values being
+ * the results of the associated plans.
+ */
 export declare class ObjectStep<TPlans extends {
     [key: string]: ExecutableStep;
 } = {
@@ -34,6 +38,10 @@ export declare class ObjectStep<TPlans extends {
     private keys;
     optimizeMetaKey: string;
     constructor(obj: TPlans);
+    /**
+     * This key doesn't get typed, but it can be added later which can be quite
+     * handy.
+     */
     set<TKey extends keyof TPlans>(key: TKey, plan: TPlans[TKey]): void;
     getStepForKey<TKey extends keyof TPlans>(key: TKey, allowMissing?: boolean): TKey extends keyof TPlans ? TPlans[TKey] : null;
     toStringMeta(): string;
@@ -43,8 +51,15 @@ export declare class ObjectStep<TPlans extends {
     unbatchedExecute(_extra: ExecutionExtra, ..._values: any[]): any;
     deduplicate(peers: ObjectStep<any>[]): ObjectStep<TPlans>[];
     optimize(opts: StepOptimizeOptions): this | ConstantStep<any>;
+    /**
+     * Get the original plan with the given key back again.
+     */
     get<TKey extends keyof TPlans>(key: TKey): TPlans[TKey];
 }
+/**
+ * A plan that represents an object using the keys given and the values being
+ * the results of the associated plans.
+ */
 export declare function object<TPlans extends {
     [key: string]: ExecutableStep;
 }>(obj: TPlans): ObjectStep<TPlans>;

package/dist/steps/partitionByIndex.d.ts

@@ -1,4 +1,39 @@
 import type { ExecutableStep } from "../step.js";
 import type { __ListTransformStep, ListTransformItemPlanCallback } from "./listTransform.js";
+/**
+ * Takes a single dimensional list plan and a mapper that calculates a
+ * (potentially duplicate) target index for each entry in the list. Returns a
+ * plan that results in a two dimensional list of the items in the original
+ * list partitioned (grouped) by their target index.
+ *
+ * If your datasource returns indexes that are 1-indexed then you may pass `1`
+ * as the third argument and we'll account for this.
+ *
+ * @example For this data:
+ *
+ * ```jsonc
+ * [
+ *   {"array_idx": 1, "id": "b0b00000-0000-0000-0000-000000000b0b", "username": "Bob"},
+ *   {"array_idx": 2, "id": "a11ce000-0000-0000-0000-0000000a11ce", "username": "Alice"}],
+ *   {"array_idx": 2, "id": "cec111a0-0000-0000-0000-00000cec111a", "username": "Cecilia"}],
+ * ]
+ * ```
+ *
+ * partitioning by the array_idx (which is 1-indexed), would result in:
+ *
+ * ```jsonc
+ * [
+ *   [
+ *     {"array_idx": 1, "id": "b0b00000-0000-0000-0000-000000000b0b", "username": "Bob"},
+ *   ],
+ *   [
+ *     {"array_idx": 2, "id": "a11ce000-0000-0000-0000-0000000a11ce", "username": "Alice"}],
+ *     {"array_idx": 2, "id": "cec111a0-0000-0000-0000-00000cec111a", "username": "Cecilia"}],
+ *   ],
+ * ]
+ * ```
+ *
+ * Beware: the target indexes should not contain gaps.
+ */
 export declare function partitionByIndex<TListStep extends ExecutableStep<readonly any[]>, TItemStep extends ExecutableStep<number>>(listStep: TListStep, mapper: ListTransformItemPlanCallback<TListStep, TItemStep>, startIndex?: 0 | 1): __ListTransformStep<TListStep, TItemStep, unknown[][], any>;
 //# sourceMappingURL=partitionByIndex.d.ts.map

package/dist/steps/proxy.d.ts

@@ -3,6 +3,11 @@ import type { ExecutionExtra } from "../interfaces.js";
 import { $$proxy } from "../interfaces.js";
 import type { ExecutableStep } from "../step.js";
 import { UnbatchedExecutableStep } from "../step.js";
+/**
+ * @experimental
+ *
+ * Never build this class directly.
+ */
 export declare class ProxyStep<T> extends UnbatchedExecutableStep<T> {
     static $$export: {
         moduleName: string;
@@ -22,6 +27,12 @@ declare module "../step.js" {
         [$$proxy]?: any;
     }
 }
+/**
+ * @experimental
+ *
+ * This could change at any time, may impact performance, and just, generally,
+ * needs more work. You shouldn't need this in the vast majority of cases.
+ */
 export declare function proxy<TData, TStep extends ExecutableStep<TData>>($step: TStep, $actualDep?: ExecutableStep): TStep & {
     addDependency(step: ExecutableStep): number;
 };

package/dist/steps/remapKeys.d.ts

@@ -4,6 +4,10 @@ import { UnbatchedExecutableStep } from "../step.js";
 export type ActualKeyByDesiredKey = {
     [desiredKey: string]: string;
 };
+/**
+ * A plan that returns an object resulting from extracting the given
+ * `actualKey` from the input and storing it as the `desiredKey` in the output.
+ */
 export declare class RemapKeysStep extends UnbatchedExecutableStep {
     private actualKeyByDesiredKey;
     static $$export: {
@@ -21,6 +25,10 @@ export declare class RemapKeysStep extends UnbatchedExecutableStep {
     unbatchedExecute(_extra: ExecutionExtra, value: any): any;
     deduplicate(peers: RemapKeysStep[]): RemapKeysStep[];
 }
+/**
+ * A plan that returns an object resulting from extracting the given
+ * `actualKey` from the input and storing it as the `desiredKey` in the output.
+ */
 export declare function remapKeys($step: ExecutableStep, actualKeyByDesiredKey: {
     [desiredKey: string]: string;
 }): RemapKeysStep;

package/dist/steps/reverse.d.ts

@@ -1,7 +1,13 @@
 import type { ExecutionExtra, GrafastResultsList, GrafastValuesList } from "../interfaces.js";
 import type { ExecutableStep } from "../step.js";
 import { UnbatchedExecutableStep } from "../step.js";
+/**
+ * Returns a reversed copy of the list.
+ */
 export declare function reverseArray<TData = any>(list: readonly TData[]): TData[];
+/**
+ * Reverses a list.
+ */
 export declare class ReverseStep<TData> extends UnbatchedExecutableStep<readonly TData[]> {
     static $$export: {
         moduleName: string;
@@ -14,5 +20,8 @@ export declare class ReverseStep<TData> extends UnbatchedExecutableStep<readonly
     unbatchedExecute(_extra: ExecutionExtra, arr: TData[]): TData[];
     deduplicate(peers: ReverseStep<TData>[]): ReverseStep<TData>[];
 }
+/**
+ * Reverses a list.
+ */
 export declare function reverse<TData>(plan: ExecutableStep<readonly TData[]>): ReverseStep<TData>;
 //# sourceMappingURL=reverse.d.ts.map

package/dist/subscribe.d.ts

@@ -1,4 +1,8 @@
 import type { AsyncExecutionResult, ExecutionArgs, ExecutionResult } from "graphql";
 import type { PromiseOrValue } from "graphql/jsutils/PromiseOrValue";
+/**
+ * Use this instead of GraphQL.js' subscribe method and we'll automatically
+ * run grafastPrepare for you and handle the result.
+ */
 export declare function subscribe(args: ExecutionArgs, resolvedPreset?: GraphileConfig.ResolvedPreset, outputDataAsString?: boolean): PromiseOrValue<AsyncGenerator<ExecutionResult | AsyncExecutionResult, void, void> | ExecutionResult>;
 //# sourceMappingURL=subscribe.d.ts.map

package/dist/utils.d.ts

@@ -4,12 +4,32 @@ import type { Deferred } from "./deferred.js";
 import type { OperationPlan } from "./engine/OperationPlan.js";
 import type { BaseGraphQLArguments, GrafastFieldConfig, GrafastInputFieldConfig, InputStep, OutputPlanForType } from "./interfaces.js";
 import type { ExecutableStep, ModifierStep } from "./step.js";
+/**
+ * The parent object is used as the key in `GetValueStepId()`; for root level
+ * fields it's possible that the parent will be null/undefined (in all other
+ * cases it will be an object), so we need a value that can be the key in a
+ * WeakMap to represent the root.
+ */
 export declare const ROOT_VALUE_OBJECT: any;
 export declare function assertNullPrototype(object: Record<string, unknown>, description: string): void;
+/**
+ * Specifically allows for the `defaultValue` to be undefined, but otherwise
+ * defers to {@link rawValueToValueNode}
+ */
 export declare function defaultValueToValueNode(type: GraphQLInputType, defaultValue: unknown): ConstValueNode | undefined;
 export declare function isPromise<T>(t: T | Promise<T>): t is Promise<T>;
+/**
+ * Is "thenable".
+ */
 export declare function isPromiseLike<T>(t: T | Promise<T> | PromiseLike<T>): t is PromiseLike<T>;
+/**
+ * Is a promise that can be externally resolved.
+ */
 export declare function isDeferred<T>(t: T | Promise<T> | Deferred<T>): t is Deferred<T>;
+/**
+ * Returns true if array1 and array2 have the same length, and every pair of
+ * values within them pass the `comparator` check (which defaults to `===`).
+ */
 export declare function arraysMatch<T>(array1: ReadonlyArray<T>, array2: ReadonlyArray<T>, comparator?: (val1: T, val2: T) => boolean): boolean;
 export type ObjectTypeFields<TContext extends Grafast.Context, TParentStep extends ExecutableStep> = {
     [key: string]: GrafastFieldConfig<GraphQLOutputType, TContext, TParentStep, any, any>;
@@ -20,15 +40,29 @@ export type ObjectTypeSpec<TContext extends Grafast.Context, TParentStep extends
         new (...args: any[]): TParentStep;
     } : null;
 };
+/**
+ * Saves us having to write `extensions: {grafast: {...}}` everywhere.
+ */
 export declare function objectSpec<TContext extends Grafast.Context, TParentStep extends ExecutableStep, TFields extends ObjectTypeFields<TContext, TParentStep>>(spec: ObjectTypeSpec<TContext, TParentStep, TFields>): GraphQLObjectTypeConfig<any, TContext>;
 export type GrafastObjectType<TContext extends Grafast.Context, TParentStep extends ExecutableStep, TFields extends ObjectTypeFields<TContext, TParentStep>> = graphql.GraphQLObjectType<TParentStep extends ExecutableStep<infer U> ? U : never, TContext> & {
     TParentStep: TParentStep;
     TFields: TFields;
 };
+/**
+ * @remarks This is a mess because the first two generics need to be specified manually, but the latter one we want inferred.
+ */
 export declare function newObjectTypeBuilder<TContext extends Grafast.Context, TParentStep extends ExecutableStep>(assertStep: TParentStep extends ExecutableStep ? ((step: ExecutableStep) => asserts step is TParentStep) | {
     new (...args: any[]): TParentStep;
 } : never): <TFields extends ObjectTypeFields<TContext, TParentStep>>(spec: ObjectTypeSpec<TContext, TParentStep, TFields>) => GrafastObjectType<TContext, TParentStep, TFields>;
+/**
+ * Saves us having to write `extensions: {grafast: {...}}` everywhere.
+ */
 export declare function objectFieldSpec<TContext extends Grafast.Context, TSource extends ExecutableStep, TResult extends ExecutableStep = ExecutableStep, TArgs extends BaseGraphQLArguments = BaseGraphQLArguments>(grafastSpec: GrafastFieldConfig<GraphQLOutputType, TContext, TSource, TResult, TArgs>, path: string): GraphQLFieldConfig<any, TContext, TArgs>;
+/**
+ * "Constrainted identity function" for field configs.
+ *
+ * @see {@link https://kentcdodds.com/blog/how-to-write-a-constrained-identity-function-in-typescript}
+ */
 export declare function newGrafastFieldConfigBuilder<TContext extends Grafast.Context, TParentStep extends ExecutableStep>(): <TType extends GraphQLOutputType, TFieldStep extends OutputPlanForType<TType>, TArgs extends BaseGraphQLArguments>(config: GrafastFieldConfig<TType, TContext, TParentStep, TFieldStep, TArgs>) => typeof config;
 export type GrafastInputFieldConfigMap<TContext extends Grafast.Context, TParentStep extends ModifierStep<any>> = {
     [key: string]: GrafastInputFieldConfig<GraphQLInputType, TContext, TParentStep, any, any>;
@@ -42,6 +76,9 @@ export type GrafastInputObjectType<TContext extends Grafast.Context, TParentStep
     TFields: TFields;
 };
 export declare function newInputObjectTypeBuilder<TContext extends Grafast.Context, TParentStep extends ModifierStep<any>>(): <TFields extends GrafastInputFieldConfigMap<TContext, TParentStep>>(spec: InputObjectTypeSpec<TContext, TParentStep, TFields>) => GrafastInputObjectType<TContext, TParentStep, TFields>;
+/**
+ * Saves us having to write `extensions: {grafast: {...}}` everywhere.
+ */
 export declare function inputObjectFieldSpec<TContext extends Grafast.Context, TParent extends ModifierStep<any>, TResult extends ModifierStep<TParent> = ModifierStep<TParent>, TInput extends InputStep = InputStep>(grafastSpec: GrafastInputFieldConfig<GraphQLInputType, TContext, TParent, TResult, TInput>, path: string): GraphQLInputFieldConfig;
 declare module "graphql" {
     interface GraphQLEnumType {
@@ -49,15 +86,80 @@ declare module "graphql" {
     }
 }
 declare const $$valueConfigByValue: unique symbol;
+/**
+ * This would be equivalent to `enumType._valueLookup.get(outputValue)` except
+ * that's not a public API so we have to do a bit of heavy lifting here. Since
+ * it is heavy lifting, we cache the result, but we don't know when enumType
+ * will go away so we use a weakmap.
+ */
 export declare function getEnumValueConfig(enumType: graphql.GraphQLEnumType, outputValue: string): GraphQLEnumValueConfig | undefined;
+/**
+ * It's a peculiarity of V8 that `{}` is twice as fast as
+ * `Object.create(null)`, but `Object.create(sharedNull)` is the same speed as
+ * `{}`. Hat tip to `@purge` for bringing this to my attention.
+ *
+ * @internal
+ */
 export declare const sharedNull: any;
+/**
+ * Prints out the stack trace to the current position with a message; useful
+ * for debugging which code path has hit this line.
+ *
+ * @internal
+ */
 export declare function stack(message: string, length?: number): void;
+/**
+ * Ridiculously, this is faster than `new Array(length).fill(fill)`
+ *
+ * @internal
+ */
 export declare function arrayOfLength(length: number, fill?: any): any[];
+/**
+ * Builds an array of length `length` calling `fill` for each entry in the
+ * list and storing the result.
+ *
+ * @internal
+ */
 export declare function arrayOfLengthCb(length: number, fill: () => any): any[];
+/**
+ * Given a FieldNode, recursively walks and finds all the variable references,
+ * returning a list of the (unique) variable names used.
+ */
 export declare function findVariableNamesUsed(operationPlan: OperationPlan, field: FieldNode): string[];
 export declare function isTypePlanned(schema: GraphQLSchema, namedType: GraphQLNamedType): boolean;
 export declare function stepADependsOnStepB(stepA: ExecutableStep, stepB: ExecutableStep): boolean;
+/**
+ * Returns true if stepA is allowed to depend on stepB, false otherwise. (This
+ * mostly relates to heirarchy.)
+ */
 export declare function stepAMayDependOnStepB($a: ExecutableStep, $b: ExecutableStep): boolean;
+/**
+ * For a regular GraphQL query with no `@stream`/`@defer`, the entire result is
+ * calculated and then the output is generated and sent to the client at once.
+ * Thus you can think of this as every plan is in the same "phase".
+ *
+ * However, if you introduce a `@stream`/`@defer` selection, then the steps
+ * inside that selection should run _later_ than the steps in the parent
+ * selection - they should run in two different phases. Similar is true for
+ * subscriptions.
+ *
+ * When optimizing your plans, if you are not careful you may end up pushing
+ * what should be later work into the earlier phase, resulting in the initial
+ * payload being delayed whilst things that should have been deferred are being
+ * calculated. Thus, you should generally check that two plans are in the same phase
+ * before you try and merge them.
+ *
+ * This is not a strict rule, though, because sometimes it makes more sense to
+ * push work into the parent phase because it would be faster overall to do
+ * that work there, and would not significantly delay the initial payload's
+ * execution time - for example it's unlikely that it would make sense to defer
+ * selecting an additional boolean column from a database table even if the
+ * operation indicates that's what you should do.
+ *
+ * As a step class author, it's your responsiblity to figure out the right
+ * approach. Once you have, you can use this function to help you, should you
+ * need it.
+ */
 export declare function stepsAreInSamePhase(ancestor: ExecutableStep, descendent: ExecutableStep): boolean;
 export declare const canonicalJSONStringify: (o: object) => string;
 export declare function assertNotAsync(fn: any, name: string): void;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "0.0.1-alpha.13";
+export declare const version = "0.0.1-alpha.15";
 //# sourceMappingURL=version.d.ts.map

package/fwd/graphql/index.d.ts

@@ -0,0 +1 @@
+export * from "graphql";

package/fwd/graphql/index.js

@@ -0,0 +1 @@
+module.exports = require("graphql");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grafast",
-  "version": "0.0.1-alpha.13",
+  "version": "0.0.1-alpha.15",
   "description": "Cutting edge GraphQL planning and execution engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -57,7 +57,7 @@
   },
   "peerDependencies": {
     "@envelop/core": "^3.0.4",
-    "graphile-config": "^0.0.1-alpha.6",
+    "graphile-config": "^0.0.1-alpha.7",
     "graphql": "^16.1.0-experimental-stream-defer.6",
     "tamedevil": "^0.0.0-alpha.4"
   },