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

package/dist/step.d.ts

@@ -4,51 +4,218 @@ import type { OperationPlan } from "./engine/OperationPlan.js";
 import type { ExecutionExtra, GrafastResultsList, GrafastResultStreamList, GrafastValuesList, PromiseOrDirect, StepOptimizeOptions, StepOptions } from "./interfaces.js";
 import { $$subroutine } from "./interfaces.js";
 import type { __ItemStep } from "./steps/index.js";
+/**
+ * @internal
+ */
 export declare const $$deepDepSkip: unique symbol;
+/**
+ * This indicates that a step never executes (e.g. __ItemStep and __ValueStep)
+ * and thus when executed skips direct to reallyCompletedStep.
+ *
+ * @internal
+ */
 export declare const $$noExec: unique symbol;
 declare function reallyAssertFinalized(plan: BaseStep): void;
 export declare const assertFinalized: typeof reallyAssertFinalized;
+/**
+ * The base abstract plan type; you should not extend this directly - instead
+ * use an ExecutableStep (for use when planning output fields) or a
+ * ModifierStep (for use when planning arguments/input fields).
+ *
+ * @remarks
+ *
+ * Though it might seem that ModifierStep should be used for all inputs
+ * (arguments, input objects), this is not the case. When planning an output
+ * field, all inputs to it (including arguments, parent plan, context, etc)
+ * should be other executable plans. The only time that ModifierStep is used is
+ * when writing specific plans as part of the argument or input field
+ * definitions themself; even in these cases the inputs to these plan resolvers
+ * will be ExecutablePlans.
+ */
 export declare abstract class BaseStep {
+    /**
+     * This identifies the "bucket" into which this plan's results will be stored.
+     * New buckets are introduced when you cross boundaries that may change the
+     * number of results in the bucket, or where control over execution is desired.
+     *
+     * - Lists / list items (generally multiplies up)
+     * - Polymorphism - different entries may go into different buckets
+     * - Mutations - early termination is likely
+     * - Defer boundaries - don't execute this stuff until later
+     * - null boundaries - if a null is met, no need to continue execution
+     *
+     * This bucket influences:
+     *
+     * 1. how plans are deduplicated
+     * 2. the order in which the plans are executed
+     * 3. where the result of executing the plan is stored
+     * 4. when the plan execution cache is allowed to be GC'd
+     *
+     * NOTE: `__ListTransformStep`'s effectively have a temporary bucket inside
+     * them (built on the `__Item`) that's thrown away once the transform is
+     * complete.
+     *
+     * @internal
+     */
     readonly layerPlan: LayerPlan;
     readonly operationPlan: OperationPlan;
     [$$subroutine]: LayerPlan<LayerPlanReasonSubroutine> | null;
     isArgumentsFinalized: boolean;
     isFinalized: boolean;
     debug: boolean;
+    /**
+     * Set this true for plans that implement mutations; this will prevent them
+     * from being tree-shaken.
+     */
     hasSideEffects: boolean;
     constructor();
     toString(): string;
+    /**
+     * This metadata will be merged into toString when referencing this plan.
+     */
     toStringMeta(): string | null;
     finalize(): void;
     destroy(): void;
 }
+/**
+ * Executable plans are the plans associated with leaves on the GraphQL tree,
+ * they must be able to execute to return values.
+ */
 export declare class ExecutableStep<TData = any> extends BaseStep {
     static $$export: any;
+    /**
+     * Setting this true is a performance optimisation, but it comes with strong
+     * rules; we do not test you comply with these rules (as that would undo the
+     * performance gains) but should you break them the behaviour is undefined
+     * (and, basically, the schema may no longer be GraphQL compliant).
+     *
+     * Do not set this true unless the following hold:
+     *
+     * - The `execute` method must be a regular (not async) function
+     * - The `execute` method must NEVER return a promise
+     * - The values within the list returned from `execute` must NEVER include
+     *   promises or GrafastError objects
+     * - The result of calling `execute` should not differ after a
+     *   `step.hasSideEffects` has executed (i.e. it should be pure, only
+     *   dependent on its deps and use no external state)
+     *
+     * It's acceptable for the `execute` method to throw if it needs to.
+     *
+     * This optimisation applies to the majority of the built in plans and allows
+     * the engine to execute without needing to resolve any promises which saves
+     * precious event-loop ticks.
+     */
     isSyncAndSafe: boolean;
+    /**
+     * The plan this plan will need data from in order to execute.
+     * @internal
+     */
     readonly dependencies: ReadonlyArray<ExecutableStep>;
+    /**
+     * Just for mermaid
+     * @internal
+     */
     readonly dependents: ReadonlyArray<{
         step: ExecutableStep;
         dependencyIndex: number;
     }>;
+    /**
+     * We reserve the right to change our mind as to whether this is a string or
+     * number.
+     *
+     * @internal
+     */
     readonly id: number;
+    /**
+    /**
+     * True when `optimize` has been called at least once.
+     */
     isOptimized: boolean;
+    /**
+     * Set this true if your plan's optimize method can be called a second time;
+     * note that in this situation it's likely that your dependencies will not be
+     * what you expect them to be (e.g. a PgSelectSingleStep might become an
+     * AccessStep).
+     */
     allowMultipleOptimizations: boolean;
+    /** @internal */
     _stepOptions: StepOptions;
+    /** @internal */
     polymorphicPaths: ReadonlySet<string> | null;
+    /**
+     * True if this needs to be permanently stored; for example:
+     *
+     * - Is the dep of another LayerPlan
+     * - Is used in an OutputPlan
+     *
+     * @internal
+     */
     store: boolean;
+    /**
+     * Set the metaKey so `execute` will be passed a meta object to use.
+     * Depending on what you set it to, you can share execution meta between
+     * multiple steps of the same class (or even a family of step classes).
+     *
+     * A sensible value for it is `this.metaKey = this.id;`.
+     */
     metaKey: number | string | symbol | undefined;
+    /**
+     * Like `metaKey` but for the optimize phase
+     */
     optimizeMetaKey: number | string | symbol | undefined;
     constructor();
     protected withMyLayerPlan<T>(callback: () => T): T;
     protected getStep(id: number): ExecutableStep;
     getDep(depId: number): ExecutableStep;
+    /**
+     * Like getDep, except it skips over __ItemStep and similar steps to get to
+     * where the parent really is.
+     *
+     * @experimental
+     */
     protected getDepDeep(depId: number): ExecutableStep;
     toString(): string;
     protected addDependency(step: ExecutableStep, skipDeduplication?: boolean): number;
+    /**
+     * Given a list of "peer" steps, return a list of these `peers` that are
+     * equivalent to this step.
+     *
+     * NOTE: equivalence goes both ways: `a.deduplicate([b]).includes(b)` if and
+     * only if `b.deduplicate([a]).includes(a)`.
+     *
+     * If you need to transform the peer to be equivalent you should do so via
+     * the `deduplicatedWith` callback later.
+     */
     deduplicate?(_peers: readonly ExecutableStep[]): readonly ExecutableStep[];
+    /**
+     * If this plan is replaced via deduplication, this method gives it a chance
+     * to hand over its responsibilities to its replacement.
+     */
     deduplicatedWith?(replacement: ExecutableStep): void;
+    /**
+     * Our chance to optimise the plan (which could go as far as to inline the
+     * plan into the parent plan).
+     */
     optimize?(_options: StepOptimizeOptions): ExecutableStep;
     finalize(): void;
+    /**
+     * This function will be called with a `values` list: an array of entries for
+     * each incoming grafast object, where each entry in the array is a list of
+     * the values retrieved from executing the plans in `this.dependencies` for
+     * that grafast object.
+     *
+     * It must return a list with the same length as `values`, where each value
+     * in the list relates to the result of executing this plan for the
+     * corresponding entry in the `values` list.
+     *
+     * IMPORTANT: it is up to the execute function to cache/memoize results as
+     * appropriate for performance, this can be done via the `meta` object.
+     *
+     * The `meta` object is an empty object stored to `grafastContext.metaByPlan`
+     * that can be used to store anything this plan needs. We recommend that you
+     * add attributes to meta for each purpose (e.g. use `meta.cache` for
+     * memoizing results) so that you can expand your usage of meta in future.
+     */
     execute(count: number, values: ReadonlyArray<GrafastValuesList<any>>, extra: ExecutionExtra): PromiseOrDirect<GrafastResultsList<TData>>;
     destroy(): void;
 }
@@ -79,6 +246,11 @@ export declare function isObjectLikeStep<TData extends {
     [key: string]: ExecutableStep;
 }>(plan: ExecutableStep): plan is ObjectLikeStep<TData>;
 export type StreamableStep<TData> = ExecutableStep<ReadonlyArray<TData>> & {
+    /**
+     * If this plan supports streaming then it should implement this method. It's
+     * basically the same as `execute` except it returns a list of result streams
+     * rather than a list of results.
+     */
     stream(count: number, values: ReadonlyArray<GrafastValuesList<any>>, extra: ExecutionExtra, streamOptions: {
         initialCount: number;
     }): PromiseOrDirect<GrafastResultStreamList<TData>>;
@@ -88,12 +260,23 @@ export type PolymorphicStep = ExecutableStep & {
     planForType(objectType: GraphQLObjectType): ExecutableStep;
 };
 export declare function isPolymorphicStep(s: ExecutableStep): s is PolymorphicStep;
+/**
+ * Modifier plans modify their parent plan (which may be another ModifierStep
+ * or an ExecutableStep). First they gather all the requirements from their
+ * children (if any) being applied to them, then they apply themselves to their
+ * parent plan. This application is done through the `apply()` method.
+ *
+ * Modifier plans do not use dependencies.
+ */
 export declare abstract class ModifierStep<TParentStep extends BaseStep = BaseStep> extends BaseStep {
     protected readonly $parent: TParentStep;
     static $$export: any;
     readonly id: string;
     constructor($parent: TParentStep);
     toString(): string;
+    /**
+     * In this method, you should apply the changes to your `this.$parent` plan
+     */
     abstract apply(): void;
 }
 export declare function isModifierStep<TParentStep extends ExecutableStep | ModifierStep<any>>(plan: BaseStep): plan is ModifierStep<TParentStep>;

package/dist/steps/__inputDynamicScalar.d.ts

@@ -1,6 +1,9 @@
 import type { GraphQLScalarType, ListValueNode, ObjectValueNode } from "graphql";
 import type { ExecutionExtra } from "../interfaces.js";
 import { UnbatchedExecutableStep } from "../step.js";
+/**
+ * Handles "leaves" (scalars)
+ */
 export declare class __InputDynamicScalarStep<TLeaf = any> extends UnbatchedExecutableStep<TLeaf> {
     private value;
     static $$export: {

package/dist/steps/__inputList.d.ts

@@ -3,6 +3,9 @@ import * as graphql from "graphql";
 import type { InputStep, NotVariableValueNode } from "../interfaces.js";
 import { ExecutableStep } from "../step.js";
 import type { ConstantStep } from "./constant.js";
+/**
+ * Implements `__InputListStep`.
+ */
 export declare class __InputListStep<TInputType extends graphql.GraphQLList<GraphQLInputType> = graphql.GraphQLList<GraphQLInputType>> extends ExecutableStep {
     private readonly inputValues;
     static $$export: {

package/dist/steps/__inputObject.d.ts

@@ -1,6 +1,9 @@
 import type { GraphQLInputObjectType } from "graphql";
 import type { ExecutionExtra, InputStep, NotVariableValueNode } from "../interfaces.js";
 import { UnbatchedExecutableStep } from "../step.js";
+/**
+ * Implements `InputObjectStep`
+ */
 export declare class __InputObjectStep<TInputType extends GraphQLInputObjectType = GraphQLInputObjectType> extends UnbatchedExecutableStep {
     private inputObjectType;
     private inputValues;

package/dist/steps/__inputStaticLeaf.d.ts

@@ -1,5 +1,10 @@
 import type { BooleanValueNode, EnumValueNode, FloatValueNode, GraphQLLeafType, IntValueNode, NullValueNode, StringValueNode } from "graphql";
 import { UnbatchedExecutableStep } from "../step.js";
+/**
+ * Implements `InputStaticLeafStep`
+ *
+ * @see __InputDynamicScalarStep
+ */
 export declare class __InputStaticLeafStep<TLeaf = any> extends UnbatchedExecutableStep<TLeaf> {
     static $$export: {
         moduleName: string;

package/dist/steps/__item.d.ts

@@ -1,5 +1,10 @@
 import type { ExecutableStep } from "../step.js";
 import { $$deepDepSkip, $$noExec, UnbatchedExecutableStep } from "../step.js";
+/**
+ * An __ItemStep is an internal plan (users must never construct it
+ * themselves!) that Grafast uses to refer to an individual item within a list
+ * or stream.
+ */
 export declare class __ItemStep<TData> extends UnbatchedExecutableStep<TData> {
     readonly depth: number;
     static $$export: {
@@ -8,6 +13,9 @@ export declare class __ItemStep<TData> extends UnbatchedExecutableStep<TData> {
     };
     isSyncAndSafe: boolean;
     [$$noExec]: boolean;
+    /**
+     * @internal
+     */
     transformStepId?: number;
     constructor(parentPlan: ExecutableStep<TData> | ExecutableStep<TData[]>, depth?: number);
     toStringMeta(): string;

package/dist/steps/__trackedValue.d.ts

@@ -5,28 +5,102 @@ import type { ExecutionExtra, GrafastResultsList, GrafastValuesList } from "../i
 import { UnbatchedExecutableStep } from "../step.js";
 import type { __ValueStep } from "./__value.js";
 import type { AccessStep } from "./access.js";
+/**
+ * Implements the `__TrackedValueStep(operationPlan, object, constraints, path)`
+ * algorithm used to allow runtime AND plan-time access to the three special
+ * entities: `variableValues`, `rootValue` and `context`.
+ *
+ * ExecutableStep-time access can evaluate the `object` passed to the constructor, and
+ * will add constraints to the relevant operationPlan.variableValuesConstraints,
+ * operationPlan.rootValueConstraints or operationPlan.contextConstraints to
+ * ensure that all future variableValues, rootValues and context will match the
+ * assumptions made.
+ *
+ * Run-time access will see the runtime values of these properties, it will
+ * **NOT** reference the `object` passed to the constructor.
+ *
+ * In core this will be used for evaluating `@skip`, `@include`, `@defer` and
+ * `@stream` directives so that a different OpPlan will be used if these would
+ * change the query plan, but it can also be used within plan resolvers to
+ * branch the logic of a plan based on something in these entities.
+ */
 export declare class __TrackedValueStep<TData = any, TInputType extends GraphQLInputType | ReadonlyArray<VariableDefinitionNode> | undefined = undefined> extends UnbatchedExecutableStep<TData> {
     static $$export: {
         moduleName: string;
         exportName: string;
     };
     isSyncAndSafe: boolean;
+    /**
+     * Could be anything. In the case of context it could even have exotic
+     * entries such as `pgClient`.
+     */
     private readonly value;
+    /**
+     * A reference to the relevant
+     * operationPlan.variableValuesConstraints/contextConstraints/rootValueConstraints.
+     *
+     * @internal
+     */
     private readonly constraints;
+    /**
+     * The path that we are through the original value (the one that
+     * `constraints` relates to).
+     */
     private readonly path;
     static withGraphQLType<TInputType extends GraphQLInputType, TData = any>(value: TData | undefined, valuePlan: __ValueStep<TData> | AccessStep<TData>, constraints: Constraint[], path: (string | number)[] | undefined, graphqlType: TInputType): __TrackedValueStepWithDollars<TData, TInputType>;
     private nullableGraphQLType;
     private variableDefinitions;
+    /**
+     * @internal
+     */
     constructor(value: TData | undefined, valuePlan: __ValueStep<TData> | AccessStep<TData>, constraints: Constraint[], path?: Array<string | number>, graphqlTypeOrVariableDefinitions?: TInputType);
     execute(_count: number, values: [GrafastValuesList<TData>]): GrafastResultsList<TData>;
     unbatchedExecute(_extra: ExecutionExtra, v: TData): TData;
     private getValuePlan;
+    /**
+     * Get the named property of an object.
+     */
     get<TAttribute extends keyof TData & string>(attrName: TAttribute): __TrackedValueStepWithDollars<TData[TAttribute], TInputType extends GraphQLInputObjectType ? ReturnType<TInputType["getFields"]>[TAttribute]["type"] : undefined>;
+    /**
+     * Get the entry at the given index in an array.
+     */
     at<TIndex extends keyof TData & number>(index: TIndex): __TrackedValueStepWithDollars<TData[TIndex], TInputType extends GraphQLList<infer U> ? U & GraphQLInputType : TInputType extends GraphQLNonNull<GraphQLList<infer U>> ? U & GraphQLInputType : undefined>;
+    /**
+     * Evaluates the current value, and adds a constraint to the OpPlan to ensure
+     * that all future evaluations of this property will always return the same
+     * value.
+     *
+     * **WARNING**: avoid using this where possible, it causes OpPlans to split.
+     *
+     * **WARNING**: this is the most expensive eval, if you need to eval, prefer evalIs, evalHas, etc instead.
+     */
     eval(): TData | undefined;
+    /**
+     * Evaluates if the current value is equal to this specific value, and adds a
+     * constraint to the OpPlan to ensure that all future evaluations of this
+     * check will always return the same (boolean) result.
+     *
+     * Should only be used on scalars.
+     *
+     * **WARNING**: avoid using this where possible, it causes OpPlans to split.
+     */
     evalIs(expectedValue: unknown): boolean;
     evalIsEmpty(): boolean;
+    /**
+     * Evaluates if the current value is an object with the given key, and adds a
+     * constraint to the OpPlan to ensure that all future evaluations of this
+     * check will always return the same (boolean) result.
+     *
+     * **WARNING**: avoid using this where possible, it causes OpPlans to split.
+     */
     evalHas(key: string): boolean;
+    /**
+     * Evaluates the length of the current value (assumed to be an array), and
+     * adds a constraint to the OpPlan to ensure that all future values will have
+     * the same length.
+     *
+     * **WARNING**: avoid using this where possible, it causes OpPlans to split.
+     */
     evalLength(): number | null;
     optimize(): import("../step.js").ExecutableStep<any>;
 }

package/dist/steps/__value.d.ts

@@ -1,5 +1,10 @@
 import { $$noExec, ExecutableStep } from "../step.js";
 import type { AccessStep } from "./access.js";
+/**
+ * Implements `__ValueStep(operationPlan)` which is never executed; it's purely
+ * internal - we populate the value as part of the algorithm - see
+ * `GetValueStepId` and `PopulateValueStep`.
+ */
 export declare class __ValueStep<TData> extends ExecutableStep<TData> {
     static $$export: {
         moduleName: string;

package/dist/steps/access.d.ts

@@ -1,7 +1,16 @@
 import type { ExecutionExtra } from "../interfaces.js";
 import type { ExecutableStep } from "../step.js";
 import { UnbatchedExecutableStep } from "../step.js";
+/** @internal */
 export declare const expressionSymbol: unique symbol;
+/**
+ * Accesses a (potentially nested) property from the result of a plan.
+ *
+ * NOTE: this could lead to unexpected results (which could introduce security
+ * issues) if it is not used carefully; only use it on JSON-like data,
+ * preferably where the objects have null prototypes, and be sure to adhere to
+ * the naming conventions detailed in assertSafeToAccessViaBraces.
+ */
 export declare class AccessStep<TData> extends UnbatchedExecutableStep<TData> {
     readonly fallback?: any;
     static $$export: {
@@ -13,12 +22,22 @@ export declare class AccessStep<TData> extends UnbatchedExecutableStep<TData> {
     readonly path: (string | number | symbol)[];
     constructor(parentPlan: ExecutableStep<unknown>, path: (string | number | symbol)[], fallback?: any);
     toStringMeta(): string;
+    /**
+     * Get the named property of an object.
+     */
     get<TAttr extends keyof TData>(attrName: TAttr): AccessStep<TData[TAttr]>;
+    /**
+     * Get the entry at the given index in an array.
+     */
     at<TIndex extends keyof TData>(index: TIndex): AccessStep<TData[TIndex]>;
     optimize(): AccessStep<TData>;
     finalize(): void;
     unbatchedExecute(_extra: ExecutionExtra, ..._values: any[]): any;
     deduplicate(peers: AccessStep<unknown>[]): AccessStep<TData>[];
 }
+/**
+ * Access the property at path `path` in the value returned from `parentPlan`,
+ * falling back to `fallback` if it were null-ish.
+ */
 export declare function access<TData>(parentPlan: ExecutableStep<unknown>, path: (string | number | symbol)[] | string | number | symbol, fallback?: any): AccessStep<TData>;
 //# sourceMappingURL=access.d.ts.map

package/dist/steps/applyTransforms.d.ts

@@ -4,16 +4,29 @@ import type { GrafastError } from "../error.js";
 import type { ExecutionExtra, GrafastResultsList, GrafastValuesList } from "../interfaces.js";
 import type { ListCapableStep } from "../step.js";
 import { ExecutableStep } from "../step.js";
+/**
+ * @internal
+ */
 export declare class ApplyTransformsStep extends ExecutableStep {
     static $$export: {
         moduleName: string;
         exportName: string;
     };
     isSyncAndSafe: boolean;
+    /** Set during query planning.  */
     itemStepId: number;
+    /**
+     * @internal
+     */
     subroutineLayer: LayerPlan<LayerPlanReasonSubroutine>;
     constructor(listPlan: ListCapableStep<any, any>);
     execute(_count: number, values: [GrafastValuesList<any[] | null | undefined | GrafastError>], extra: ExecutionExtra): Promise<GrafastResultsList<any[]>>;
 }
+/**
+ * If you want to use a step that might represent a list and you need all of
+ * the `listItem` transforms to have already taken place (e.g. you're going to
+ * send the result to an external service) rather than processing them through
+ * the GraphQL response, then you may need to call `applyTransforms` on it.
+ */
 export declare function applyTransforms($step: ExecutableStep): ExecutableStep<any>;
 //# sourceMappingURL=applyTransforms.d.ts.map

package/dist/steps/connection.d.ts

@@ -2,6 +2,10 @@ import type { ExecutionExtra, GrafastResultsList, InputStep } from "../interface
 import type { ExecutableStep } from "../step.js";
 import { UnbatchedExecutableStep } from "../step.js";
 type ParametersExceptFirst<F> = F extends (arg0: any, ...rest: infer R) => any ? R : never[];
+/**
+ * Describes what a plan needs to implement in order to be suitable for
+ * supplying what the `PageInfo` type requires.
+ */
 export interface PageInfoCapableStep extends ExecutableStep {
     hasNextPage(): ExecutableStep<boolean>;
     hasPreviousPage(): ExecutableStep<boolean>;
@@ -9,7 +13,16 @@ export interface PageInfoCapableStep extends ExecutableStep {
     endCursor(): ExecutableStep<string | null>;
 }
 export declare function assertPageInfoCapableStep($step: ExecutableStep | PageInfoCapableStep): asserts $step is PageInfoCapableStep;
+/**
+ * Describes what a plan needs to implement in order to be suitable for
+ * supplying what a ConnectionStep requires.
+ */
 export interface ConnectionCapableStep<TItemStep extends ExecutableStep, TCursorStep extends ExecutableStep> extends ExecutableStep<ReadonlyArray<TItemStep extends ExecutableStep<infer U> ? U : any>> {
+    /**
+     * Clone the plan; it's recommended that you add `$connection` as a
+     * dependency so that you can abort execution early in the case of errors
+     * (e.g. if the cursors cannot be parsed).
+     */
     connectionClone($connection: ConnectionStep<TItemStep, TCursorStep, any, any>, ...args: any[]): ConnectionCapableStep<TItemStep, TCursorStep>;
     pageInfo($connection: ConnectionStep<TItemStep, TCursorStep, ConnectionCapableStep<TItemStep, TCursorStep>, any>): PageInfoCapableStep;
     setFirst($plan: InputStep): void;
@@ -19,6 +32,10 @@ export interface ConnectionCapableStep<TItemStep extends ExecutableStep, TCursor
     setBefore($plan: TCursorStep): void;
     setAfter($plan: TCursorStep): void;
 }
+/**
+ * Handles GraphQL cursor pagination in a standard and consistent way
+ * indepdenent of data source.
+ */
 export declare class ConnectionStep<TItemStep extends ExecutableStep, TCursorStep extends ExecutableStep, TStep extends ConnectionCapableStep<TItemStep, TCursorStep>, TNodeStep extends ExecutableStep = ExecutableStep> extends UnbatchedExecutableStep<unknown> {
     readonly itemPlan?: (($item: TItemStep) => TNodeStep) | undefined;
     readonly cursorPlan?: (($item: TItemStep) => ExecutableStep<string | null> | undefined) | undefined;
@@ -45,9 +62,35 @@ export declare class ConnectionStep<TItemStep extends ExecutableStep, TCursorSte
     setBefore($beforePlan: InputStep): void;
     getAfter(): TCursorStep | null;
     setAfter($afterPlan: InputStep): void;
+    /**
+     * This should not be called after the arguments have been finalized.
+     */
     getSubplan(): TStep;
+    /**
+     * This represents the entire collection with conditions and ordering
+     * applied, but without any pagination constraints (before, after, first,
+     * last, offset) applied. It's useful for the following:
+     *
+     * - performing aggregates e.g. totalCount across the entire collection
+     * - determining fields for pageInfo, e.g. is there a next/previous page
+     *
+     * This cannot be called before the arguments have been finalized.
+     */
     cloneSubplanWithoutPagination(...args: ParametersExceptFirst<TStep["connectionClone"]>): TStep;
+    /**
+     * This represents a single page from the collection - not only have
+     * conditions and ordering been applied but we've also applied the pagination
+     * constraints (before, after, first, last, offset). It's useful for
+     * returning the actual edges and nodes of the connection.
+     *
+     * This cannot be called before the arguments have been finalized.
+     */
     cloneSubplanWithPagination(...args: ParametersExceptFirst<TStep["connectionClone"]> | []): TStep;
+    /**
+     * Subplans may call this from their `setBefore`/`setAfter`/etc plans in order
+     * to add a dependency to us, which is typically useful for adding validation
+     * functions so that they are thrown "earlier", avoiding error bubbling.
+     */
     addValidation(callback: () => ExecutableStep): void;
     edges(): ExecutableStep;
     nodes(): TStep | import("./listTransform.js").__ListTransformStep<any, any, any, any>;
@@ -81,6 +124,10 @@ export declare class EdgeStep<TItemStep extends ExecutableStep, TCursorStep exte
     deduplicatedWith(replacement: EdgeStep<any, any, any, any>): void;
     unbatchedExecute(_extra: ExecutionExtra, record: any, cursor: any): any;
 }
+/**
+ * Wraps a collection fetch to provide the utilities for working with GraphQL
+ * cursor connections.
+ */
 export declare function connection<TItemStep extends ExecutableStep, TCursorStep extends ExecutableStep, TStep extends ConnectionCapableStep<TItemStep, TCursorStep>, TNodeStep extends ExecutableStep = ExecutableStep>(step: TStep, itemPlan?: ($item: TItemStep) => TNodeStep, cursorPlan?: ($item: TItemStep) => ExecutableStep<string | null>): ConnectionStep<TItemStep, TCursorStep, TStep, TNodeStep>;
 export {};
 //# sourceMappingURL=connection.d.ts.map

package/dist/steps/constant.d.ts

@@ -1,5 +1,8 @@
 import type { GrafastResultsList } from "../interfaces.js";
 import { UnbatchedExecutableStep } from "../step.js";
+/**
+ * Converts a constant value (e.g. a string/number/etc) into a plan
+ */
 export declare class ConstantStep<TData> extends UnbatchedExecutableStep<TData> {
     readonly data: TData;
     readonly isSensitive: boolean;
@@ -19,6 +22,10 @@ export declare class ConstantStep<TData> extends UnbatchedExecutableStep<TData>
     isNull(): boolean;
     isUndefined(): boolean;
 }
+/**
+ * Call this as a template string or as a function. Only intended for handling
+ * scalar values, not arrays/objects/etc.
+ */
 export declare function constant<const TString extends string>(strings: TemplateStringsArray & [TString]): ConstantStep<TString>;
 export declare function constant<TData>(data: TData, isSecret?: boolean): ConstantStep<TData>;
 //# sourceMappingURL=constant.d.ts.map

package/dist/steps/each.d.ts

@@ -2,5 +2,8 @@ import type { ExecutableStep, ListCapableStep } from "../step.js";
 import { __ItemStep } from "./__item.js";
 import type { ConnectionCapableStep } from "./connection.js";
 import type { __ListTransformStep } from "./listTransform.js";
+/**
+ * Transforms a list by wrapping each element in the list with the given mapper.
+ */
 export declare function each<TListStep extends ExecutableStep<readonly any[]> & Partial<ConnectionCapableStep<any, any>>, TResultItemStep extends ExecutableStep>(listStep: TListStep, mapper: (itemPlan: TListStep extends ListCapableStep<any, any> ? ReturnType<TListStep["listItem"]> : __ItemStep<any>) => TResultItemStep): __ListTransformStep<any, any, any, any>;
 //# sourceMappingURL=each.d.ts.map

package/dist/steps/filter.d.ts

@@ -2,5 +2,9 @@ import type { ExecutableStep, ListCapableStep } from "../step.js";
 import type { __ItemStep } from "./__item.js";
 import type { __ListTransformStep, ListTransformItemPlanCallback } from "./listTransform.js";
 export type FilterPlanMemo = unknown[];
+/**
+ * Filters a list plan to only include entries for which the `filterCallback`
+ * plan results in a truthy value.
+ */
 export declare function filter<TListStep extends ExecutableStep<readonly any[]>, TItemStep extends ExecutableStep<boolean>>(listStep: TListStep, filterCallback: ListTransformItemPlanCallback<TListStep, TItemStep>): __ListTransformStep<TListStep, TItemStep, FilterPlanMemo, TListStep extends ListCapableStep<any, any> ? ReturnType<TListStep["listItem"]> : __ItemStep<any>>;
 //# sourceMappingURL=filter.d.ts.map

package/dist/steps/first.d.ts

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