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

package/dist/args.d.ts

@@ -1,7 +1,9 @@
 import type { ExecutionArgs } from "graphql";
-declare const $$hooked: unique symbol;
-export declare function hookArgs(args: ExecutionArgs & {
-    [$$hooked]?: boolean;
-}, resolvedPreset: GraphileConfig.ResolvedPreset, ctx: Partial<Grafast.RequestContext>): ExecutionArgs | PromiseLike<ExecutionArgs>;
-export {};
+/**
+ * Applies Graphile Config hooks to your GraphQL request, e.g. to
+ * populate context or similar.
+ *
+ * @experimental
+ */
+export declare function hookArgs(rawArgs: ExecutionArgs, resolvedPreset: GraphileConfig.ResolvedPreset, ctx: Partial<Grafast.RequestContext>): Grafast.ExecutionArgs | PromiseLike<Grafast.ExecutionArgs>;
 //# sourceMappingURL=args.d.ts.map

package/dist/assert.d.ts

@@ -1,3 +1,5 @@
+/** Equivalent to `assert.ok(...)` */
 export declare function ok(val: any, message: string): asserts val;
+/** Equivalent to `assert.strictEqual(...)` */
 export declare function strictEqual<T>(actual: any, expected: T, message: string): asserts actual is T;
 //# sourceMappingURL=assert.d.ts.map

package/dist/bucket.d.ts

@@ -1,21 +1,85 @@
 import type { LayerPlan } from "./engine/LayerPlan";
 import type { MetaByMetaKey } from "./engine/OperationPlan";
 import type { ExecutionEventEmitter } from "./interfaces.js";
+/**
+ * @internal
+ */
 export interface RequestTools {
+    /** The `timeSource.now()` at which the request started executing */
     startTime: number;
+    /** The `timeSource.now()` at which the request should stop executing (if a timeout was configured) */
     stopTime: number | null;
     readonly eventEmitter: ExecutionEventEmitter | undefined;
+    /**
+     * If we're running inside GraphQL then we should not serialize scalars,
+     * otherwise we'll face the double-serialization problem.
+     */
     insideGraphQL: false;
 }
+/**
+ * A "bucket" is where the results from plans are stored so that other plans
+ * can retrieve them, it may take on different forms depending on the mode of
+ * execution. A "LayerPlan" is used to both identify the bucket and to specify
+ * why it exists and how it behaves.
+ *
+ * Every `ExecutableStep` belongs to exactly one LayerPlan (and thus bucket),
+ * specified by `plan.layerPlan`.
+ *
+ * @internal
+ */
 export interface Bucket {
+    /**
+     * The LayerPlan definition this bucket adheres to
+     */
     layerPlan: LayerPlan;
+    /**
+     * How many entries are there in the bucket?
+     */
     size: number;
+    /**
+     * The polymorphic path through which each of the entries (respectively) has
+     * travelled. This influences the steps that will be executed using the
+     * related inputs.
+     */
     polymorphicPathList: readonly (string | null)[];
+    /**
+     * These are the iterators the bucket (or its descendents, without crossing a
+     * stream/defer boundary) have created (if any). Each of these must either be
+     * processed via `processRoot`, or must be manually released (via
+     * `releaseUnusedIterators`) otherwise a memory leak could occur.
+     */
     iterators: Array<Set<AsyncIterator<any> | Iterator<any>>>;
+    /**
+     * `metaByMetaKey` belongs to the bucket rather than the request context
+     * because mutations and subscriptions shouldn't re-use caches.
+     *
+     * TODO: `inheritMeta: boolean`?
+     */
     metaByMetaKey: MetaByMetaKey;
+    /**
+     * Every entry in the store is a list with the same length as the bucket has
+     * `size`.
+     *
+     * The entry for '-1' is the request indexes, so we can associate the results
+     * back to the request that triggered them.
+     */
     store: Map<number, any[]>;
+    /**
+     * Set this true when the bucket is fully executed.
+     *
+     * Initialize it to false.
+     */
     isComplete: boolean;
+    /**
+     * If an error occurred at any stage we need to drop down to more careful
+     * (and slower) handling.
+     *
+     * Initialize it to false.
+     */
     hasErrors: boolean;
+    /**
+     * The child buckets of this bucket.
+     */
     children: {
         [layerPlanId: number]: {
             bucket: Bucket;

package/dist/constraints.d.ts

@@ -1,30 +1,61 @@
+/**
+ * Asserts that a value strictly matches.
+ */
 interface ValueConstraint {
     type: "value";
     path: (string | number)[];
     value: unknown;
 }
+/**
+ * Asserts that `(value === expectedValue)` is always equal to `pass`.
+ */
 interface EqualityConstraint {
     type: "equal";
     path: (string | number)[];
     expectedValue: unknown;
     pass: boolean;
 }
+/**
+ * Asserts that the property at the given path exists.
+ *
+ * Let `tail` be the last entry in `path`, and `rest` be the rest of `path`.
+ * The value at path `rest` must be an object, and that object must have an
+ * attribute `tail` which is not `undefined`.
+ */
 interface ExistsConstraint {
     type: "exists";
     path: (string | number)[];
     exists: boolean;
 }
+/**
+ * If `expectedLength` is null: asserts that there is no value at the given
+ * path.
+ *
+ * Otherwise: asserts that the value at the given path is an array containing
+ * `expectedLength` entries.
+ */
 interface LengthConstraint {
     type: "length";
     path: (string | number)[];
+    /**
+     * If this is null it implies that the array did not exist.
+     */
     expectedLength: number | null;
 }
+/**
+ * Checks if the object at the given path matches the `isEmpty` property
+ * (implying no keys). Objects are empty if and only if they exist and have no
+ * keys.
+ */
 interface IsEmptyConstraint {
     type: "isEmpty";
     path: (string | number)[];
     isEmpty: boolean;
 }
 export type Constraint = ValueConstraint | EqualityConstraint | ExistsConstraint | LengthConstraint | IsEmptyConstraint;
+/**
+ * Implements the `MatchesConstraints` algorithm.
+ */
 export declare function matchesConstraints(constraints: Constraint[], object: unknown): boolean;
 export {};
 //# sourceMappingURL=constraints.d.ts.map

package/dist/deferred.d.ts

@@ -1,6 +1,13 @@
+/**
+ * A promise that can be `.resolve()`-ed or `.reject()`-ed at a later time.
+ */
 export interface Deferred<T> extends PromiseLike<T> {
     resolve: (input: T | PromiseLike<T>) => void;
     reject: (error: Error) => void;
 }
+/**
+ * Returns a promise that can be `.resolve()`-ed or `.reject()`-ed at a later
+ * time.
+ */
 export declare function defer<T = void>(): Deferred<T>;
 //# sourceMappingURL=deferred.d.ts.map

package/dist/dev.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @internal
+ */
 export declare const isDev: boolean;
 export declare function noop(): void;
 //# sourceMappingURL=dev.d.ts.map

package/dist/engine/LayerPlan.d.ts

@@ -1,38 +1,64 @@
 import type { Bucket } from "../bucket.js";
 import type { ExecutableStep, ModifierStep, UnbatchedExecutableStep } from "../step";
 import type { OperationPlan } from "./OperationPlan";
+/** Non-branching, non-deferred */
 export interface LayerPlanReasonRoot {
     type: "root";
 }
+/** Non-branching, non-deferred */
 export interface LayerPlanReasonNullableField {
     type: "nullableBoundary";
+    /**
+     * Can be used such that the same LayerPlan can be used for two selection
+     * sets for the same parent plan. In this case an additional output plan
+     * would be added to the LayerPlan.
+     *
+     * Also needed for execution (see `executeBucket`).
+     */
     parentStep: ExecutableStep;
 }
+/** Non-branching, non-deferred */
 export interface LayerPlanReasonListItem {
     type: "listItem";
+    /**
+     * Can be used such that the same LayerPlan can be used for two lists for
+     * the same parent plan. In this case an additional output plan would be
+     * added to the LayerPlan.
+     *
+     * Also needed for execution (see `executeBucket`).
+     */
     parentStep: ExecutableStep;
+    /** If this listItem is to be streamed, the configuration for that streaming */
     stream?: {
         initialCount: number;
         label?: string;
     };
 }
+/** Non-branching, deferred */
 export interface LayerPlanReasonSubscription {
     type: "subscription";
 }
+/** Non-branching, deferred */
 export interface LayerPlanReasonMutationField {
     type: "mutationField";
     mutationIndex: number;
 }
+/** Non-branching, deferred */
 export interface LayerPlanReasonDefer {
     type: "defer";
     label?: string;
 }
+/** Branching, non-deferred */
 export interface LayerPlanReasonPolymorphic {
     type: "polymorphic";
     typeNames: string[];
+    /**
+     * Needed for execution (see `executeBucket`).
+     */
     parentStep: ExecutableStep;
     polymorphicPaths: Set<string>;
 }
+/** Non-branching, non-deferred */
 export interface LayerPlanReasonSubroutine {
     type: "subroutine";
     parentStep: ExecutableStep;
@@ -45,38 +71,143 @@ export type HasParent<A extends LayerPlanReason> = A extends any ? A extends {
     parentStep: ExecutableStep;
 } ? A : never : never;
 export type LayerPlanReasonsWithParentStep = HasParent<LayerPlanReason>;
+/** @internal */
 export interface LayerPlanPhase {
+    /**
+     * If true, we should check before the layer plan executes to see if the
+     * execution has already timed out.
+     *
+     * @see {@link RequestTools.stopTime}
+     */
     checkTimeout: boolean;
+    /**
+     * A list of steps that can be ran in parallel at this point, since all
+     * their previous dependencies have already been satisfied.
+     */
     normalSteps: Array<{
         step: ExecutableStep;
     }> | undefined;
+    /**
+     * A list of 'isSyncAndSafe' steps with unbatchedExecute methods that can be
+     * ran once the `normalSteps` have completed; they must only depend on steps
+     * that have already been executed before them (including previous
+     * unbatchedSyncAndSafeSteps in the same list).
+     */
     unbatchedSyncAndSafeSteps: Array<{
         step: UnbatchedExecutableStep;
+        /**
+         * Store the result of the step here if you want - useful to avoid lookups
+         * and when there's no storage. HIGHLY VOLATILE, will not survive a tick!
+         */
         scratchpad: any;
     }> | undefined;
+    /**
+     * Optimization - a digest of all steps in normalSteps and unbatchedSyncAndSafeSteps
+     *
+     * @internal
+     */
     _allSteps: ExecutableStep[];
 }
+/**
+ * A LayerPlan represents (via "reason") either the root (root), when something
+ * happens at a later time (mutationField, defer), when plurality changes
+ * (list, stream, subscription, polymorphic), or when a subprocess needs to be
+ * computed (subroutine).
+ *
+ * Layer plans belong to an operation plan.
+ *
+ * Every layer plan (except for the root layer plan) has exactly one parent
+ * layer plan.
+ *
+ * Every layer plan is caused by a parent step.
+ *
+ * The LayerPlan of a step influences:
+ *
+ * 1. how steps are deduplicated
+ * 2. the order in which the steps are executed
+ * 3. where the result of executing the step is stored
+ * 4. when the step 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.
+ *
+ */
 export declare class LayerPlan<TReason extends LayerPlanReason = LayerPlanReason> {
     readonly operationPlan: OperationPlan;
     parentLayerPlan: LayerPlan | null;
     readonly reason: TReason;
     id: number;
+    /**
+     * Every layer plan has a "root step" that shapes the value the layer
+     * returns. Note that this step may be dependent on other steps included in
+     * the LayerPlan, or could be provided externally.
+     *
+     * The root step is different for different layer step reasons:
+     *
+     * - root: the `operationPlan.rootValue`
+     * - listItem: the `__ItemStep`
+     * - stream: also the `__ItemStep`
+     * - subscription: also the `__ItemStep`
+     * - mutationField: the result plan of the mutation field
+     * - defer: the parent layer's rootStep (defer always results in an object, unless an error occurs)
+     * - polymorphic: the plan for the particular type
+     * - subroutine: the result (returned) plan of the subroutine
+     *
+     * @internal
+     */
     readonly rootStep: ExecutableStep | null;
+    /**
+     * Which plans the results for which are available in a parent bucket need to
+     * be "copied across" to this bucket because plans in this bucket still
+     * reference them?
+     *
+     * @internal
+     */
     copyStepIds: number[];
+    /** @internal */
     children: LayerPlan[];
+    /** @internal */
     steps: ExecutableStep[];
+    /** @internal */
     pendingSteps: ExecutableStep[];
+    /**
+     * Describes the order in which the steps within this LayerPlan are executed.
+     *
+     * Special attention must be paid to steps that have side effects.
+     *
+     * @internal
+     */
     phases: Array<LayerPlanPhase>;
+    /**
+     * The list of layerPlans that steps added to this LayerPlan may depend upon.
+     * Note this includes self, so it has one more entry than `depth`.
+     *
+     * ```
+     * this.ancestry[this.depth] === this;
+     * ```
+     *
+     * @internal
+     */
     ancestry: LayerPlan[];
+    /** How "deep" this layer plan is (how many ancestors it has). The root layer plan has a depth of 0. */
     depth: number;
+    /** The depth at which a "defer boundary" occurs (OperationPlan.getPeers cannot pass a defer boundary), or 0. */
     deferBoundaryDepth: number;
+    /**
+     * An optimization for OperationPlan.getPeers; this tracks the steps in this
+     * layer plan, grouped by their step class.
+     */
     stepsByConstructor: Map<Function, Set<ExecutableStep>>;
     constructor(operationPlan: OperationPlan, parentLayerPlan: LayerPlan | null, reason: TReason);
     toString(): string;
     print(depth?: number): string;
     setRootStep($root: ExecutableStep): void;
+    /** @internal Use plan.getStep(id) instead. */
     getStep(id: number, requestingStep: ExecutableStep): ExecutableStep;
+    /** @internal */
     _addStep(step: ExecutableStep): number;
+    /** @internal */
     _addModifierStep(step: ModifierStep<any>): string;
     finalize(): void;
     newBucket(parentBucket: Bucket): Bucket | null;

package/dist/engine/OperationPlan.d.ts

@@ -11,6 +11,7 @@ import { OutputPlan } from "./OutputPlan.js";
 import { StepTracker } from "./StepTracker.js";
 export declare const POLYMORPHIC_ROOT_PATH: null;
 export declare const POLYMORPHIC_ROOT_PATHS: ReadonlySet<string> | null;
+/** @internal */
 export type OperationPlanPhase = "init" | "plan" | "validate" | "optimize" | "finalize" | "ready";
 export interface MetaByMetaKey {
     [metaKey: string | number | symbol]: Record<string, any>;
@@ -38,35 +39,76 @@ export declare class OperationPlan {
         [objectTypeName: string]: ReadonlyArray<GraphQLUnionType>;
     };
     private operationType;
+    /**
+     * What state is the OpPlan in?
+     *
+     * 1. init
+     * 2. plan
+     * 3. validate
+     * 5. optimize
+     * 6. finalize
+     * 7. ready
+     *
+     * Once in 'ready' state we can execute the plan.
+     *
+     * @internal
+     */
     phase: OperationPlanPhase;
+    /**
+     * Gets updated as we work our way through the plan, useful for making errors more helpful.
+     */
     loc: string[] | null;
+    /** @internal */
     rootLayerPlan: LayerPlan;
+    /**
+     * Assigned during OperationPlan.planOperation(), guaranteed to exist after
+     * initialization.
+     *
+     * @internal
+     */
     rootOutputPlan: OutputPlan;
     private modifierStepCount;
     private modifierDepthCount;
     private modifierSteps;
+    /** @internal */
     readonly stepTracker: StepTracker;
     private maxDeduplicatedStepId;
     private maxValidatedStepId;
+    /** Constraints based on evaluating variables. @internal */
     readonly variableValuesConstraints: Constraint[];
+    /** Stores the actual variableValues. @internal */
     readonly variableValuesStep: __ValueStep<{
         [key: string]: any;
     }>;
+    /** A step for accessing variableValues in a tracked manner (allowing eval). @internal */
     readonly trackedVariableValuesStep: __TrackedValueStep<{
         [key: string]: any;
     }>;
+    /** Constraints based on evaluating context. @internal */
     readonly contextConstraints: Constraint[];
+    /** Stores the actual value of the context. @internal */
     readonly contextStep: __ValueStep<Grafast.Context>;
+    /** Allows accessing context in a tracked manner (allowing eval). @internal */
     readonly trackedContextStep: __TrackedValueStep<{
         [key: string]: any;
     }>;
+    /** Constraints based on evaluating rootValue. @internal */
     readonly rootValueConstraints: Constraint[];
+    /** Stores the actual value of rootValue. @internal */
     readonly rootValueStep: __ValueStep<any>;
+    /** Allows accessing rootValue in a tracked manner (allowing eval). @internal */
     readonly trackedRootValueStep: __TrackedValueStep<any>;
+    /** @internal */
     makeMetaByMetaKey: () => MetaByMetaKey;
+    /**
+     * @internal
+     */
     readonly itemStepIdByListStepId: {
         [listStepId: number]: number | undefined;
     };
+    /**
+     * If true, then this operation doesn't use (custom) resolvers.
+     */
     pure: boolean;
     private startTime;
     private previousLap;
@@ -82,50 +124,159 @@ export declare class OperationPlan {
     }, rootValue: any, planningTimeout: number | null);
     private lap;
     private checkTimeout;
+    /**
+     * Called by the LayerPlan's constructor when it wants to get a new id to use.
+     *
+     * @internal
+     */
     addLayerPlan(layerPlan: LayerPlan): number;
+    /**
+     * Adds a plan to the known steps and returns the number to use as the plan
+     * id. ONLY to be used from Step, user code should never call this directly.
+     *
+     * @internal
+     */
     _addStep(plan: ExecutableStep): number;
+    /**
+     * Adds a plan to the known steps and returns the number to use as the plan
+     * id. ONLY to be used from Step, user code should never call this directly.
+     *
+     * @internal
+     */
     _addModifierStep(step: ModifierStep<any>): string;
+    /** @internal Use plan.getStep(id) instead. */
     getStep: (id: number, requestingStep: ExecutableStep) => ExecutableStep;
+    /**
+     * Get a plan without specifying who requested it; this disables all the
+     * caller checks. Only intended to be called from internal code.
+     *
+     * @internal
+     */
     dangerouslyGetStep(id: number): ExecutableStep;
     private planOperation;
+    /**
+     * Plans a GraphQL query operation.
+     */
     private planQuery;
+    /**
+     * Implements the `PlanOpPlanMutation` algorithm.
+     */
     private planMutation;
+    /**
+     * Implements the `PlanOpPlanSubscription` algorithm.
+     */
     private planSubscription;
+    /**
+     * Gets the item plan for a given parent list plan - this ensures we only
+     * create one item plan per parent plan.
+     */
     private itemStepForListStep;
     processGroupedFieldSet(outputPlan: OutputPlan, path: readonly string[], polymorphicPath: string | null, polymorphicPaths: ReadonlySet<string> | null, parentStep: ExecutableStep, objectType: GraphQLObjectType, objectTypeFields: GraphQLFieldMap<any, any>, isMutation: boolean, groupedFieldSet: SelectionSetDigest): void;
+    /**
+     *
+     * @param outputPlan - The output plan that this selection set is being added to
+     * @param path - The path within the outputPlan that we're adding stuff (only for root/object OutputPlans)
+     * @param parentStep - The step that represents the selection set root
+     * @param objectType - The object type that this selection set is being evaluated for (note polymorphic selection should already have been handled by this point)
+     * @param selections - The GraphQL selections (fields, fragment spreads, inline fragments) to evaluate
+     * @param isMutation - If true this selection set should be executed serially rather than in parallel (each field gets its own LayerPlan)
+     */
     private planSelectionSet;
     private planIntoOutputPlan;
     private polymorphicLayerPlanByPathByLayerPlan;
     private getPolymorphicLayerPlan;
     private planField;
+    /**
+     * A replacement for GraphQL's
+     * `CoerceArgumentValues` that factors in tracked variables.
+     *
+     * @see https://spec.graphql.org/draft/#CoerceArgumentValues()
+     */
     private getTrackedArguments;
     withModifiers<T>(cb: () => T): T;
+    /**
+     * Sets up tracking for the given value (variableValues, context, rootValue).
+     */
     private track;
+    /**
+     * Checks that no step has a property on it whose value is another step. It
+     * should addDependency instead.
+     */
     private validateSteps;
     private replaceStep;
     private processStep;
+    /**
+     * Process the given steps, either dependencies first (root to leaf) or
+     * dependents first (leaves to root).
+     *
+     * @internal
+     */
     processSteps(actionDescription: string, order: "dependents-first" | "dependencies-first", isReadonly: boolean, callback: (plan: ExecutableStep) => ExecutableStep): void;
+    /**
+     * Peers are steps of the same type (but not the same step!) that are in
+     * compatible layers and have the same dependencies. Peers must not have side
+     * effects. A step is not its own peer.
+     */
     private getPeers;
     private isImmoveable;
+    /**
+     * Attempts to hoist the step into a higher layerPlan to maximize
+     * deduplication.
+     */
     private hoistStep;
+    /**
+     * Attempts to push the step into the lowest layerPlan to minimize the need
+     * for copying between layer plans.
+     */
     private pushDown;
     private _deduplicateInnerLogic;
     private deduplicateStep;
     private deduplicateStepsProcess;
+    /**
+     * Gives us a chance to replace nearly-duplicate plans with other existing
+     * plans (and adding the necessary transforms); this means that by the time
+     * we come to optimize the plan tree should already be simpler. For example
+     * if you have two plans at the same level that both request row data from
+     * the same database table with the same identifiers, `WHERE`, `LIMIT`,
+     * `OFFSET` and `ORDER BY`, but different `SELECT`s we could merge the two
+     * plans together by replacing the latter with the former and having the
+     * former SELECT additional fields, then transform the results back to what
+     * our child plans would be expecting.
+     */
     private deduplicateSteps;
     private hoistAndDeduplicate;
     private hoistSteps;
     private pushDownSteps;
     private getStepOptionsForStep;
+    /**
+     * Calls the 'optimize' method on a plan, which may cause the plan to
+     * communicate with its (deep) dependencies, and even to replace itself with
+     * a different plan.
+     */
     private optimizeStep;
+    /**
+     * Note that we work through dependents first so we can make sure that we
+     * know all our dependent's needs before we optimise ourself.
+     */
     private optimizeSteps;
+    /** Finalizes each step */
     private finalizeSteps;
     private finalizeLayerPlans;
+    /** Optimizes each output plan */
     private optimizeOutputPlans;
+    /** Finalizes each output plan */
     private finalizeOutputPlans;
     private walkOutputPlans;
+    /**
+     * Convert an OpPlan into a plan graph in mermaid-js format.
+     */
     printPlanGraph(options?: PrintPlanGraphOptions): string;
     finishSubroutine(subroutineStep: ExecutableStep, layerPlan: LayerPlan<LayerPlanReasonSubroutine>): void;
+    /**
+     * HIGHLY EXPERIMENTAL!
+     *
+     * @internal
+     */
     deleteLayerPlan(layerPlan: LayerPlan): void;
     getStepsByMetaKey(metaKey: string | number | symbol): ExecutableStep[];
     getStepsByStepClass<TClass extends ExecutableStep>(klass: {