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

package/dist/engine/OutputPlan.d.ts

@@ -8,34 +8,80 @@ import type { PayloadRoot } from "./executeOutputPlan.js";
 import type { LayerPlan } from "./LayerPlan.js";
 export type OutputPlanTypeIntrospection = {
     mode: "introspection";
+    /**
+     * The GraphQL introspection field selection (may include arguments/etc). We
+     * can build a GraphQL document from this and issue it to graphql-js rather
+     * than replicating that effort.
+     */
     field: FieldNode;
+    /**
+     * The names of the variables used in this document.
+     */
     variableNames: string[];
+    /**
+     * No need to re-run the introspection each time, may as well cache it,
+     * right?
+     *
+     * Key: canonical JSON stringify of the variables used.
+     * Value: the GraphQL result (`{data, errors}`) for this.
+     */
     introspectionCacheByVariableValues: LRU<string, JSONValue>;
 };
 export type OutputPlanTypeRoot = {
+    /**
+     * Always return `{}`
+     */
     mode: "root";
     typeName: string;
 };
 export type OutputPlanTypeObject = {
+    /**
+     * Return `{}` if non-null
+     */
     mode: "object";
     typeName: string;
     deferLabel: string | undefined;
 };
 export type OutputPlanTypePolymorphicObject = {
+    /**
+     * Return `{}` if non-null
+     */
     mode: "polymorphic";
     typeNames: string[];
     deferLabel: string | undefined;
 };
 export type OutputPlanTypeArray = {
+    /**
+     * Return a list of the same length if an array
+     */
     mode: "array";
 };
 export type OutputPlanTypeLeaf = {
+    /**
+     * Return the value.
+     */
     mode: "leaf";
     graphqlType: GraphQLScalarType | GraphQLEnumType;
 };
 export type OutputPlanTypeNull = {
     mode: "null";
 };
+/**
+ * Thanks to `@stream`, output plans must handle their own nullability concerns
+ * and we might need an output plan for any of these:
+ *
+ * - A concrete object
+ * - A polymorphic object
+ * - A leaf (enum/scalar)
+ * - Something we know will always be null
+ * - A list of any of the above
+ * - A list of lists
+ *
+ * In addition to the above, we also need to cover
+ *
+ * - The root object (which is like a concrete object, except it's never null)
+ * - Introspection
+ */
 export type OutputPlanType = OutputPlanTypeRoot | OutputPlanTypeObject | OutputPlanTypePolymorphicObject | OutputPlanTypeLeaf | OutputPlanTypeNull | OutputPlanTypeArray | OutputPlanTypeIntrospection;
 export type OutputPlanKeyValueOutputPlan = {
     type: "outputPlan";
@@ -51,22 +97,69 @@ export type OutputPlanKeyValue = OutputPlanKeyValueOutputPlan | OutputPlanKeyVal
 export type OutputPlanKeyValueOutputPlanWithCachedBits = OutputPlanKeyValueOutputPlan & {
     layerPlanId: number;
 };
+/**
+ * Defines a way of taking a layerPlan and converting it into an output value.
+ *
+ * The result of executing an output plan will be the following:
+ *
+ * - data?: the data for this layer, could be object, array or leaf (see OutputPlanMode)
+ * - errors: a list of errors that occurred (if any), including path details _within the output plan_
+ * - streams: a list of streams that were created
+ */
 export declare class OutputPlan<TType extends OutputPlanType = OutputPlanType> {
     layerPlan: LayerPlan;
     readonly type: TType;
+    /** For errors */
     readonly locationDetails: LocationDetails;
+    /**
+     * The step that represents the root value. How this is used depends on the
+     * OutputPlanMode.
+     */
     readonly rootStep: ExecutableStep;
+    /**
+     * Appended to the root step when accessed to avoid the need for AccessSteps
+     */
     private processRoot;
+    /**
+     * For root/object output plans, the keys to set on the resulting object
+     * grouped by the concrete object type name.
+     *
+     * IMPORTANT: the order of these keys is significant, they MUST match the
+     * order in the request otherwise we break GraphQL spec compliance!
+     */
     keys: {
         [key: string]: OutputPlanKeyValueTypeName | OutputPlanKeyValueOutputPlanWithCachedBits;
     };
+    /**
+     * For list output plans, the output plan that describes the list children.
+     */
     child: OutputPlan | null;
     childIsNonNull: boolean;
+    /**
+     * For polymorphic output plans, the Object output plan for each specific type.
+     */
     childByTypeName: {
         [typeName: string]: OutputPlan<OutputPlanTypeObject>;
     } | undefined;
+    /**
+     * For object output plan types only.
+     */
     deferredOutputPlans: OutputPlan<OutputPlanTypeObject | OutputPlanTypePolymorphicObject>[];
-    constructor(layerPlan: LayerPlan, rootStep: ExecutableStep, type: TType, locationDetails: LocationDetails);
+    constructor(layerPlan: LayerPlan, 
+    /**
+     * For root, this should always be an object.
+     *
+     * For object this could represent an object or null.
+     *
+     * For polymorphic this could represent a polymorphic object or null.
+     *
+     * For array it's the list itself (or null) and dictates the length of the result.
+     *
+     * For leaf, it's the leaf plan itself.
+     *
+     * For `introspection`, `null` it's irrelevant. Use `constant(null)` or whatever.
+     */
+    rootStep: ExecutableStep, type: TType, locationDetails: LocationDetails);
     print(): string;
     toString(): string;
     addChild(type: GraphQLObjectType | null, key: string | null, child: OutputPlanKeyValue): void;
@@ -79,5 +172,16 @@ export declare class OutputPlan<TType extends OutputPlanType = OutputPlanType> {
 }
 export declare function coerceError(error: Error, locationDetails: LocationDetails, path: ReadonlyArray<string | number>): graphql.GraphQLError;
 export declare function nonNullError(locationDetails: LocationDetails, path: readonly (string | number)[]): graphql.GraphQLError;
+/**
+ * We're currently running OutputPlan `outputPlan` in bucket `bucket` at index
+ * `bucketIndex`. If this is an array OutputPlan then we're looping over the
+ * entries in our list and we're currently at index `inArrayIndex` (otherwise
+ * this is null).
+ *
+ * Now we want to run `childOutputPlan`, but to do so we need to find the
+ * related `childBucket` and `childBucketIndex`.
+ *
+ * @internal
+ */
 export declare function getChildBucketAndIndex(childOutputPlan: OutputPlan, outputPlan: OutputPlan | null, bucket: Bucket, bucketIndex: number, arrayIndex?: number | null): [Bucket, number] | null;
 //# sourceMappingURL=OutputPlan.d.ts.map

package/dist/engine/StepTracker.d.ts

@@ -2,39 +2,92 @@ import type { OperationPlan } from "../index.js";
 import type { ExecutableStep } from "../step";
 import type { LayerPlan, LayerPlanReasonsWithParentStep } from "./LayerPlan";
 import type { OutputPlan } from "./OutputPlan";
+/**
+ * This class keeps track of all of our steps, and the dependencies between
+ * steps and other steps, layer plans and steps, and output plans and steps.
+ *
+ * When a step is replaced by another step, all the dependencies are updated
+ * such that the replaced step simply evaporates.
+ *
+ * @internal
+ */
 export declare class StepTracker {
     private readonly operationPlan;
+    /** @internal */
     stepCount: number;
+    /** @internal */
     activeSteps: Set<ExecutableStep<any>>;
+    /** @internal */
     stepById: {
         [stepId: number]: ExecutableStep | null;
     };
+    /** @internal */
     private aliasesById;
+    /** @internal */
     stepsWithNoDependencies: Set<ExecutableStep<any>>;
+    /** @internal */
     outputPlansByRootStep: Map<ExecutableStep<any>, Set<OutputPlan<import("./OutputPlan").OutputPlanType>>>;
+    /** @internal */
     layerPlansByRootStep: Map<ExecutableStep<any>, Set<LayerPlan<import("./LayerPlan").LayerPlanReason>>>;
+    /** @internal */
     layerPlansByParentStep: Map<ExecutableStep<any>, Set<LayerPlan<LayerPlanReasonsWithParentStep>>>;
+    /** @internal */
     layerPlans: Array<LayerPlan | null>;
+    /**
+     * All the OutputPlans that were created to allow a more efficient
+     * walkOutputPlans implementation.
+     *
+     * @internal
+     */
     allOutputPlans: OutputPlan[];
     nextStepIdToDeduplicate: number;
     constructor(operationPlan: OperationPlan);
     newStepsSince(oldStepCount: number): ExecutableStep<any>[];
     private forbid;
+    /** Called when OperationPlan enters finalize phase. */
     finalizeSteps(): void;
+    /** Called when OperationPlan is about to finalize the output plans. */
     finalizeOutputPlans(): void;
     addStep($step: ExecutableStep): number;
+    /**
+     * @internal
+     */
     addLayerPlan(layerPlan: LayerPlan): number;
+    /**
+     * @internal
+     */
     addOutputPlan(outputPlan: OutputPlan): void;
+    /**
+     * HIGHLY EXPERIMENTAL!
+     *
+     * @internal
+     */
     deleteLayerPlan(layerPlan: LayerPlan): void;
     getStepById(id: number): ExecutableStep;
     getStepById(id: number, allowUnset: true): ExecutableStep | null;
     addStepDependency($dependent: ExecutableStep, $dependency: ExecutableStep): number;
     setOutputPlanRootStep(outputPlan: OutputPlan, $dependency: ExecutableStep): void;
     setLayerPlanRootStep(layerPlan: LayerPlan, $dependency: ExecutableStep): void;
+    /** @internal */
     replaceStep($original: ExecutableStep, $replacement: ExecutableStep): void;
     treeShakeSteps(): void;
+    /**
+     * Return true if this step can be tree-shaken.
+     */
     private isNotNeeded;
+    /**
+     * Only for use during planField.
+     */
     purgeBackTo(count: number): void;
+    /**
+     * ONLY CALL THIS IF NOTHING DEPENDS ON $original! It's intended to be called
+     * from `replaceStep` or from itself.
+     *
+     * This method removes $original from the various maps/sets/lists, and also
+     * removes the fact that it was dependent on other steps. If these other
+     * steps no longer have any dependents (steps, layer plans or output plans)
+     * then they can also be eradicated _except_ during the 'plan' phase.
+     */
     private eradicate;
     moveStepToLayerPlan(step: ExecutableStep, targetLayerPlan: LayerPlan): void;
     addStepToItsLayerPlan(step: ExecutableStep): void;

package/dist/engine/executeBucket.d.ts

@@ -1,6 +1,8 @@
 import type { Bucket, RequestTools } from "../bucket.js";
 import type { PromiseOrDirect } from "../interfaces.js";
 import type { MetaByMetaKey } from "./OperationPlan.js";
+/** @internal */
 export declare function executeBucket(bucket: Bucket, requestContext: RequestTools): PromiseOrDirect<void>;
+/** @internal */
 export declare function newBucket(spec: Pick<Bucket, "layerPlan" | "store" | "size" | "hasErrors" | "polymorphicPathList" | "iterators">, parentMetaByMetaKey: MetaByMetaKey | null): Bucket;
 //# sourceMappingURL=executeBucket.d.ts.map

package/dist/engine/executeOutputPlan.d.ts

@@ -6,11 +6,49 @@ export type OutputPath = Array<string | number>;
 export interface OutputStream {
     asyncIterable: AsyncIterableIterator<any>;
 }
+/**
+ * PayloadRoot handles the root-level of a payload, it's ultimately responsible
+ * for sharing the `data`/`errors` with the user. But it also handles the
+ * intermediate payloads for stream/defer.
+ *
+ * A standard GraphQL query/mutation request (one that doesn't use
+ * `@stream`/`@defer`) will have just one payload. A standard GraphQL
+ * subscription request gets one payload per subscription event.
+ *
+ * When we mix `@stream` and `@defer` into this, we will require (often quite a
+ * lot) more payloads.
+ *
+ * @internal
+ */
 export interface PayloadRoot {
+    /**
+     * Serialization works differently if we're running inside GraphQL. (Namely:
+     * we don't serialize - that's GraphQL's job.)
+     */
     insideGraphQL: false;
+    /**
+     * The errors that have occurred; these are proper GraphQLErrors and will be
+     * returned directly to clients so they must be complete.
+     */
     errors: GraphQLError[];
+    /**
+     * Defer queue - we don't start executing these until after the main
+     * payload is completed (to allow for a non-null boundary to abort
+     * execution).
+     */
     queue: Array<SubsequentPayloadSpec>;
+    /**
+     * Stream queue - we don't start executing these until after the main
+     * payload is completed (to allow for a non-null boundary to abort
+     * execution).
+     */
     streams: Array<SubsequentStreamSpec>;
+    /**
+     * VERY DANGEROUS. This is _only_ to pass variables through to introspection
+     * selections, it shouldn't be used for anything else.
+     *
+     * @internal
+     * */
     variables: {
         [key: string]: any;
     };
@@ -38,5 +76,8 @@ export interface SubsequentStreamSpec {
     stream: AsyncIterator<any> | Iterator<any>;
     startIndex: number;
 }
+/**
+ * @internal
+ */
 export declare function executeOutputPlan(ctx: OutputPlanContext, outputPlan: OutputPlan, bucket: Bucket, bucketIndex: number, outputDataAsString: boolean): JSONValue;
 //# sourceMappingURL=executeOutputPlan.d.ts.map

package/dist/envelop.d.ts

@@ -1,7 +1,19 @@
 import type { Plugin as EnvelopPlugin } from "@envelop/core";
 export interface UseGrafastOptions {
+    /**
+     * Set this to 'true' to allow all explains; set it to a list of the allowed
+     * explains to allow only those, set it to false to disable explains.
+     */
     explainAllowed?: boolean | string[];
 }
+/**
+ * An Envelop plugin that uses Grafast to prepare and execute the GraphQL
+ * query.
+ */
 export declare const useGrafast: (options?: UseGrafastOptions) => EnvelopPlugin;
+/**
+ * An Envelop plugin that will make any GraphQL errors easier to read from
+ * inside of GraphiQL.
+ */
 export declare const useMoreDetailedErrors: () => EnvelopPlugin;
 //# sourceMappingURL=envelop.d.ts.map

package/dist/envelop.js

@@ -1,7 +1,7 @@
 const { Buffer } = require('node:buffer');
 const { scryptSync, createDecipheriv } = require('node:crypto');
 const pkgName = "grafast";
-const pkgVersion = "0.0.1-alpha.13";
+const pkgVersion = "0.0.1-alpha.15";
 
 const RESET = '\x1b[0m';
 const BOLD_BLACK_ON_RED = '\x1b[40;31;1;7m';
@@ -28,12 +28,12 @@ if (typeof password !== 'string') {
 }
 
 const algorithm = "aes-192-cbc";
-const salt = "We wouldn't be able to do so much OSS without sponsorship. 16936333328871744";
+const salt = "We wouldn't be able to do so much OSS without sponsorship. 21776549661030886";
 const key = scryptSync(password, salt, 24);
-const ivBuffer = Buffer.from("qtlHrLhZ8uQ/Gne4+muR5g==", "base64");
+const ivBuffer = Buffer.from("fEBkkCJeJGhakF0twHhgpw==", "base64");
 const iv = new Uint8Array(ivBuffer.buffer, ivBuffer.byteOffset, ivBuffer.length);
 const decipher = createDecipheriv(algorithm, key, iv);
-const encrypted = "WR2LyMy/rsPDqXzBVJyNTBtb5s6QiRjnMw+ZxObbpoo89rhMqUXnAT0DqZAp17WCKgwaCumi/4Pa5zlIK5V4Hkgt7KKiwewhNVhxms+/fOFPaI5WYxTSdSLBa4CbpbgpnZBkZYnXXMFcYkh9bltSLC2iMHSuM7x2ml0YSh13jjYqjKiVwEIYx+Ph8CZ+pt4cpEo+0IoEArlv+/8oCaqsfaFhZUtKLf1CwDx/capSnJUIh1IfHQWerMc8URk5P2th2dDYULxhGVXvt7rMcjDoaZ7B3mQRrV4FfiL1tc2Rj4RC0jjoan/8xaIuhl3tIicDxON6PnTjV8iaduOmfZLc6UhE9kXj/iR2xI8UXjvyuPFXgT/LiJTDNYVL9WYSlY72NvF58w/93q1btZ9mI2QOenWgpsn5pZrNNxRyMEmSva1IKn5ZFeiCvFF825I5BEDzwpEj4a0vYO9p2mgSh/hGDLSl5HffZCOuRLngF2Rfc3ip/qf2vXwDZ/XNZwtNoHXZ0pK2+Dr77aoCaCul7m7ky677WXxsaPvGMvOjdr2ZZGjCBeYbn2yx7DNIk4vvDjUYfQx/AUt+UQopach9DxbIo+syjB665Hdh2/AlWpAHJnkaxRoadbLag8E86htAsgOfPISlSypXGs+6JXd/HtQ/e1WIJRcdaeIi09k+XoQcty+8rnu2a2usiGVHmSh2ucgHc9cIUd/esR8Y3bcTwETl8W34YZxVXZwaoUIYQzWap17OLkocq9xcTyyFcl1o2VEBge9uwHt0ZlHtRvrUelztFiXliDNLdPp1jWxA9sVXju7A7LYQTNPYZR3fxwqETmH6Ut/SDQp4PBSZxyX3zY+Tysalm7N6Eb9q45/a7MQAlSpCOjRPh0RLGY5g3bBb3Z6uxRVGNovAdKdnSmT33JkKgAHo3fRRMaEHXfIWjtlDChVMc4HHoQ7X5HdaN/bc9Z2dwEWUJdw1ToVjVBQVKX1S7juPetxHycasg3Blh1Vi3JvwmmxQflws1D3fAmROga7S+2Fgu6PPA68CDL3fKMhkwAgmKFp7JKOpCouaQNGUOnP6SjenMNxEPYI7TtHpXuatzC/mcBjT7j4dH+brjwVO2nYuEK8gTRi+mQI8vYf3D0LWKfDUj/IOx91wKH4WupCMUIzELFmmVRrl+iC2kwGzq9RuFlN0SLJZO+GDNEuBPLccmka0V/IaapXYTfUqAZv+LjFU2fzhyNxFhxv6ArxGvPHkDKJO/MJ2Mo2wSfcY9at6SG0bYV8MlLaWpK+Bqz4EoKzrJ+gpRFLKl/Ae/6L9fzMyLmgBmFstOspcWsui4pgMOG1yS5+tmuh3w68KuiqLtEnlDLAS1HMXoOCcfqTRF7Y1nqXt8tnF4AIBEAkMO9a2+5ucx+oWkFMCTHp96UWDeApu4ljW28/5n9JkNyv6pj4VLiMN4gLTNavjqBo9XG3w2swVfqMaWO+KSxFmhivWJSwIOIXpAbNxjOMCBEz1ig4gW776YYIYjusiXxdiK3uHGhxZ2XFEVW1RGxwjfPjZTUgm8dguWvFnbeoVBWV2q+gXI0pBw7RhBU70fYoqQBandDbKWg4tyK+9OD7O13jtokAxTLKamR6XmUrpgPpwcsJQ3d8uzZxDCWma/1eHSAA0wybvU9ZbFE2+vwkvXZfaQQinFWPPy9ySoxkPSbwYuvMbAV/64yN/VCJHQ+21fxq/gZHlawWWQjI7cUoKYTtD4odtOMrtG5ENdUXpHbkqyydXKE5Mc2x0AJViZSigUki1f1PIdihE2cImb5cSZleWPhhBXc4yAnEtHUDkrU1MaOvu4XysRwu7MwfwT4hbWBg="
+const encrypted = "SVZfreXeCKfixoCo2KglZqBVDEmE+d593oMh1BEoYVR+c3lbcYTjkjdS8zKowzNB59In9rNZKHOo7mBJXRq+aolaaxudzKRUARRVMPlRi6/o3SFYDaGm0tXZ8RUEuzYMqbpOZEVjbQtzbHTlQGy3Ujc4tZuK41S+POR9DjRuXKgkVosWrwf72JhoG+SGy+To7TS7DG2ZoDlrt4XileUgPEQ9pHZHX0Q90WJ7HFxcIDg0LFiAIAVtFn5ajEi9/PmEAZSqJ+7125CUqYstZm/oMSR+fdS9bcIfinump4u0WQRJmEVKqm7MOOpR4NMK15El01e/Jhr0uvWS/S/LRPjiLdAAub4wka1NYCk3cunmWHOoAhTDVuZGH3sQpZSy3Bv15hN4jG4McEbvRToPUGkZduf/fgNIy3rnDaKRF6Wat5S77LDtgFfVAk7DewACpDScLODZxjLdNWHmlx3GlCiPDaFKN6pMCshTWJYiT0aZYiLtR5zRDgTlxsvruzXdGq2Qq9bttSRLcgFL4bRMWy5NlA7EyO2QxuWYDZfcse+9H1oc0TCntEe7UsrTaK73/hfjZpFEkob5HQJTO7yvAMJxncI8QCP9VNcSY+OokfMhpSAok8sgcMVz9Oif6EcDAwmQi190U68iEvRNg7fF7Yrpk9uNgTjreS6ydzo++jRFFF8ZZp698fyJ1azF65sK0hnUbW/Zq5mGNvOQ9x6vSDbBq8teRD0BxD38KTQGcROGaXN4ojXv9uzOphFgoL+2tkdYK2arUtzZPscfYIj5kgyZwQfZVJ8bShEPf9g6HeTHEU8xxA2P9Je6rxGaOcY0cl8Sbcrz9E0D3XEjvSq/eNmJ+ge+JBb5ItMmaA+4cRUy8v/n6HvbIikbIQ5nMr9k+ux2irM/ZWSeKyB4bYNl1CgodEc1jJqjtHOeOdgCB0ckbwOcolim55rlrpWWBF04p3om1TwzWrp85x3m1hloT524G7M5tPWPPYHFORvp6E/5/0cdJlqBm9zktrH1C56sKFtROUJX6RoNdzGaHQ2T/aQYvyNiu3ItV2oSljREZ5VlNzhLvGvQhs35PYLJLGps1W2/GS9NuO7DAoW2bnWnLG/7u7ZNgY9bUJoooowyjlOWElPkps/s349zcYgyqRwL0cgbs+IjO33IW5VDGTA+jnVUuXkjDieMlpNRAd8yjX4pd6Rynv7iFpmGnmOMgdyxIBbOWM51fHXnwjmqFc/mdoyGB3v7A/dBXs5/LXDdgoGLKGbBxDUh2W1Mqkfk2Ubefszxiq13y48q6JhCxQ36KEQXXiE9uNRI/O7ELUCW/3Dgk6EoozNr3/ijbA6vr2oqTHQNSjvAWPLZbyK1wpIo2U7hqz7VzpI0I6L/Xx1wAkF0cAXFc/zRmyd35HZW98YWQfzlNJSZMo9ctXVESOHEp5LrPLjgimmg2lalcO7Got0KnoMW30N5OxcXwnHUNKTBDStZl+EB5o4Wzn6nhlyIIl/zpJCsLuMbj7bJ/R05+0XLVYX5sk5jU0GA7I6Zbd2pACVneCQlhz6qXAdcIbYhiUD0/j11c8hqMIUbP6lxPD5thmNC+cdA0EedZnhd+DuN6HQ7YWDVpy0o81bys0F4yA23EDiraCS2gPh3mj5XTZ/Tm/Uc5yFQnnCmhdrhxAlCahgnCIucDkCJ2aitOH4sujYFNwRIFOwMXltDMdGZD8Cd0hDndCn8bK59J0Oo2Rv1p4KMi4A1R8zVCeQkjGKvWSprP+WpB4SghgiWRoCbr+sVhVvE/eVboW14PBzgp8IiY2ISppFpckZdw9ux43c6ybvxfN75B5XIqmwc4BLz2ORFNA8="
 let decrypted;
 try {
   decrypted = decipher.update(encrypted, 'base64', 'utf8') + decipher.final('utf8');

package/dist/error.d.ts

@@ -1,11 +1,25 @@
 /// <reference types="node" />
 import type { $$extensions } from "./interfaces.js";
 import { $$safeError } from "./interfaces.js";
+/**
+ * Internally we wrap errors that occur in a GrafastError; this allows us to do
+ * simple `instanceof` checks to see if a value is an actual value or an error.
+ * Users should never use this class; it's for internal usage only.
+ *
+ * @internal
+ */
 export interface GrafastError extends Error {
     originalError: Error;
     [$$extensions]?: Record<string, any>;
 }
 export declare const $$error: unique symbol;
+/**
+ * When an error occurs during plan execution we wrap it in a GrafastError so
+ * that we can pass it around as a value.  It gets unwrapped and thrown in the
+ * grafast resolver.
+ *
+ * @internal
+ */
 export declare const _GrafastError: {
     new (originalError: Error, planId: number | null): {
         readonly originalError: Error;
@@ -20,6 +34,11 @@ export declare const _GrafastError: {
     prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
     stackTraceLimit: number;
 };
+/**
+ * DO NOT ALLOW CONSTRUCTION OF ERRORS OUTSIDE OF THIS MODULE!
+ *
+ * @internal
+ */
 export declare function newGrafastError(error: Error, planId: number | null): {
     readonly originalError: Error;
     extensions: Record<string, any>;
@@ -29,6 +48,10 @@ export declare function newGrafastError(error: Error, planId: number | null): {
     stack?: string | undefined;
     cause?: unknown;
 };
+/**
+ * Is the given value a GrafastError? This is the only public API that people
+ * should use for looking at GrafastErrors.
+ */
 export declare function isGrafastError(value: any): value is GrafastError;
 export declare class SafeError<TExtensions extends Record<string, any> | undefined = Record<string, any> | undefined> extends Error {
     extensions: TExtensions;

package/dist/establishOperationPlan.d.ts

@@ -1,5 +1,12 @@
 import type { GraphQLSchema, OperationDefinitionNode } from "graphql";
 import { OperationPlan } from "./index.js";
 import type { BaseGraphQLRootValue, BaseGraphQLVariables, Fragments } from "./interfaces.js";
+/**
+ * Implements the `EstablishOpPlan` algorithm.
+ *
+ * @remarks Though EstablishOpPlan accepts document and operationName, we
+ * instead accept operation and fragments since they're easier to get a hold of
+ * in GraphQL.js.
+ */
 export declare function establishOperationPlan<TVariables extends BaseGraphQLVariables = BaseGraphQLVariables, TContext extends Grafast.Context = Grafast.Context, TRootValue extends BaseGraphQLRootValue = BaseGraphQLRootValue>(schema: GraphQLSchema, operation: OperationDefinitionNode, fragments: Fragments, variableValues: TVariables, context: TContext, rootValue: TRootValue, planningTimeout?: number | null): OperationPlan;
 //# sourceMappingURL=establishOperationPlan.d.ts.map

package/dist/execute.d.ts

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

package/dist/exportAs.d.ts

@@ -1,4 +1,18 @@
+/**
+ * Marks that `thing` is exported from the `grafast` module as
+ * `exportName` so that `graphile-export` can convert references to `thing`
+ * into an `import` statement.
+ *
+ * @internal
+ */
 export declare function exportAs<T extends object>(moduleName: string, thing: T, exportName: string | string[]): T;
+/**
+ * Marks that each value in `all` is exported from the `grafast`
+ * module as the key in the `all` object so that `graphile-export` can
+ * convert references to these values into `import` statements.
+ *
+ * @internal
+ */
 export declare function exportAsMany(moduleName: string, all: {
     [key: string]: any;
 }): void;

package/dist/grafastGraphql.d.ts

@@ -1,5 +1,10 @@
-import type { AsyncExecutionResult, ExecutionResult, GraphQLArgs } from "graphql";
+import type { AsyncExecutionResult, ExecutionResult } from "graphql";
 import type { PromiseOrValue } from "graphql/jsutils/PromiseOrValue";
-export declare function grafast(args: GraphQLArgs, resolvedPreset?: GraphileConfig.ResolvedPreset, ctx?: Partial<Grafast.RequestContext>): PromiseOrValue<ExecutionResult | AsyncGenerator<AsyncExecutionResult, void, undefined>>;
-export declare function grafastSync(args: GraphQLArgs, resolvedPreset?: GraphileConfig.ResolvedPreset, ctx?: Partial<Grafast.RequestContext>): ExecutionResult;
+import type { GrafastArgs } from "./interfaces.js";
+/**
+ * A replacement for GraphQL.js' `graphql` method that calls Grafast's
+ * execute instead
+ */
+export declare function grafast(args: GrafastArgs, legacyResolvedPreset?: GraphileConfig.ResolvedPreset, legacyCtx?: Partial<Grafast.RequestContext>): PromiseOrValue<ExecutionResult | AsyncGenerator<AsyncExecutionResult, void, undefined>>;
+export declare function grafastSync(args: GrafastArgs, legacyResolvedPreset?: GraphileConfig.ResolvedPreset, legacyRequestContext?: Partial<Grafast.RequestContext>): ExecutionResult;
 //# sourceMappingURL=grafastGraphql.d.ts.map

package/dist/grafastPrint.d.ts

@@ -1,5 +1,13 @@
 export declare function _grafastPrint(symbol: string | symbol | symbol[] | Record<symbol, any> | Map<any, any>, seen: Set<any>): string;
 export declare function grafastColor(text: string, n: number): string;
+/**
+ * Prints something grafast-style (i.e. concise, coloured, with helpful detail)
+ */
 export declare function grafastPrint(symbol: symbol | symbol[] | Record<symbol, any> | Map<any, any> | any): string;
+/**
+ * An ANSI-aware pad function; strips ANSI sequences from the string, figures
+ * out how much it needs to pad it by, and then pads the original string by
+ * that amount.
+ */
 export declare function ansiPad(ansiString: string, targetLength: number, fill: string, position: "start" | "end"): string;
 //# sourceMappingURL=grafastPrint.d.ts.map

package/dist/graphqlCollectFields.d.ts

@@ -2,13 +2,35 @@ import type { DirectiveNode, FieldNode, SelectionNode } from "graphql";
 import * as graphql from "graphql";
 import type { OperationPlan } from "./engine/OperationPlan.js";
 import type { __TrackedValueStep } from "./steps/index.js";
+/**
+ * Given a selection, finds the first directive named `directiveName` and, if
+ * found, extracts and returns the value from the argument named
+ * `argumentName`, tracking variable access if necessary.
+ *
+ * @remarks Currently only supports booleans.
+ *
+ * @internal
+ *
+ * PERF: inline.
+ */
 export declare function evalDirectiveArg<T = unknown>(selection: SelectionNode, directiveName: string, argumentName: string, variableValuesStep: __TrackedValueStep, defaultValue: T): T | undefined;
 export declare function evalDirectiveArgDirect<T = unknown>(directive: DirectiveNode, argumentName: string, variableValuesStep: __TrackedValueStep, defaultValue: T): T | undefined;
+/**
+ * @internal
+ */
 export interface SelectionSetDigest {
     label: string | undefined;
     fields: Map<string, FieldNode[]>;
     deferred: SelectionSetDigest[] | undefined;
 }
+/**
+ * Implements the `GraphQLCollectFields` algorithm - like `CollectFields` the
+ * GraphQL spec, but modified such that access to variables is tracked.
+ *
+ * @see https://spec.graphql.org/draft/#CollectFields()
+ *
+ * @internal
+ */
 export declare function graphqlCollectFields(operationPlan: OperationPlan, parentStepId: number, objectType: graphql.GraphQLObjectType, selections: readonly SelectionNode[], isMutation?: boolean, visitedFragments?: {
     [fragmentName: string]: true;
 }, selectionSetDigest?: SelectionSetDigest): SelectionSetDigest;

package/dist/graphqlMergeSelectionSets.d.ts

@@ -1,4 +1,8 @@
 import type { FieldNode, GraphQLObjectType, SelectionNode } from "graphql";
 import type { OperationPlan } from "./index.js";
+/**
+ * Given a list of polymorphic selections, return a list of the nested field
+ * selections that apply to the object type `type`.
+ */
 export declare function fieldSelectionsForType(operationPlan: OperationPlan, type: GraphQLObjectType, selections: ReadonlyArray<SelectionNode>, result?: Array<FieldNode>): ReadonlyArray<FieldNode>;
 //# sourceMappingURL=graphqlMergeSelectionSets.d.ts.map

package/dist/index.d.ts

@@ -21,6 +21,8 @@ export { isAsyncIterable } from "iterall";
 export { __InputListStep, __InputObjectStep, __InputObjectStepWithDollars, __InputStaticLeafStep, __ItemStep, __ListTransformStep, __TrackedValueStep, __TrackedValueStepWithDollars, __ValueStep, $$bypassGraphQL, $$eventEmitter, $$extensions, $$idempotent, $$verbatim, access, AccessStep, ActualKeyByDesiredKey, applyTransforms, ApplyTransformsStep, ArgumentApplyPlanResolver, ArgumentInputPlanResolver, arrayOfLength, arraysMatch, assertEdgeCapableStep, assertExecutableStep, assertListCapableStep, assertModifierStep, assertPageInfoCapableStep, BaseEventMap, BaseGraphQLArguments, BaseGraphQLRootValue, BaseGraphQLVariables, BaseStep, connection, ConnectionCapableStep, ConnectionStep, constant, ConstantStep, context, debugPlans, defer, Deferred, each, EdgeCapableStep, EdgeStep, EnumPlans, EnumValueApplyPlanResolver, error, ErrorStep, EventCallback, EventMapKey, ExecutableStep, execute, ExecutionEventEmitter, ExecutionEventMap, ExecutionExtra, exportAs, exportAsMany, FieldArgs, FieldInfo, FieldPlanResolver, FieldPlans, filter, FilterPlanMemo, first, FirstStep, getEnumValueConfig, grafast, GrafastArgumentConfig, GrafastError, GrafastFieldConfig, GrafastFieldConfigArgumentMap, grafast as grafastGraphql, grafastSync as grafastGraphqlSync, GrafastInputFieldConfig, GrafastInputFieldConfigMap, GrafastInputObjectType, GrafastObjectType, GrafastPlans, grafastPrint, GrafastResultsList, GrafastResultStreamList, GrafastSubscriber, grafastSync, GrafastValuesList, GraphQLItemHandler, graphqlItemHandler, graphqlResolver, GraphQLResolverStep, groupBy, GroupByPlanMemo, InputObjectFieldApplyPlanResolver, InputObjectFieldInputPlanResolver, inputObjectFieldSpec, InputObjectPlans, InputObjectTypeInputPlanResolver, InputObjectTypeSpec, InputStep, InterfaceOrUnionPlans, isDev, isExecutableStep, isGrafastError, isListCapableStep, isModifierStep, isObjectLikeStep, isPromiseLike, isSafeError, isStreamableStep, JSONArray, JSONObject, JSONValue, lambda, LambdaStep, last, LastStep, list, ListCapableStep, listen, ListenStep, ListStep, listTransform, ListTransformItemPlanCallback, ListTransformOptions, ListTransformReduce, LoadedRecordStep, loadMany, LoadManyCallback, loadManyCallback, loadOne, LoadOneCallback, loadOneCallback, LoadOptions, LoadStep, makeGrafastSchema, ModifierStep, newGrafastFieldConfigBuilder, newInputObjectTypeBuilder, newObjectTypeBuilder, node, NodeIdCodec, NodeIdHandler, NodeStep, noop, object, objectFieldSpec, ObjectLikeStep, ObjectPlanMeta, ObjectPlans, objectSpec, ObjectStep, ObjectTypeFields, ObjectTypeSpec, OperationPlan, operationPlan, OutputPlanForType, PageInfoCapableStep, partitionByIndex, PolymorphicData, PolymorphicStep, polymorphicWrap, PrintPlanGraphOptions, PromiseOrDirect, proxy, ProxyStep, remapKeys, RemapKeysStep, reverse, reverseArray, ReverseStep, SafeError, ScalarPlanResolver, ScalarPlans, setter, SetterCapableStep, SetterStep, specFromNodeId, stepADependsOnStepB, stepAMayDependOnStepB, StepOptimizeOptions, stepsAreInSamePhase, StepStreamOptions, StreamableStep, stringifyPayload, stripAnsi, subscribe, TypedEventEmitter, UnbatchedExecutableStep, };
 export { hookArgs } from "./args.js";
 export { version } from "./version.js";
+/** @deprecated Renamed to 'applyTransforms' */
 export declare const deepEval: typeof applyTransforms;
+/** @deprecated Renamed to 'ApplyTransformsStep' */
 export declare const DeepEvalStep: typeof ApplyTransformsStep;
 //# sourceMappingURL=index.d.ts.map