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

package/dist/makeGrafastSchema.d.ts

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

package/dist/mermaid.d.ts

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

package/dist/polymorphic.d.ts

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

package/dist/prepare.d.ts

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

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,11 +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