grafast 0.1.1-beta.21 → 0.1.1-beta.22

package/dist/mermaid.js

@@ -65,9 +65,6 @@ exports.mermaidEscape = mermaidEscape;
 function isGrafastPlanJSONv1(json) {
     return json.version === "v1";
 }
-function shouldHideStep(step) {
-    return step.extra?.constant?.type === "undefined";
-}
 function planToMermaid(planJSON, { 
 // printPathRelations = false,
 concise = false, skipBuckets = global.grafastExplainMermaidSkipBuckets ?? false, } = {}) {
@@ -79,6 +76,9 @@ concise = false, skipBuckets = global.grafastExplainMermaidSkipBuckets ?? false,
     const dependentsByStepId = Object.create(null);
     const sortedSteps = [];
     const extractSteps = (bucket) => {
+        if (layerPlanById[bucket.id]) {
+            throw new Error(`Two buckets with the same ID ${bucket.id}?`);
+        }
         layerPlanById[bucket.id] = bucket;
         // Shallowest bucket first, then most dependencies
         const sorted = [...bucket.steps].sort((a, z) => z.dependencyIds.length - a.dependencyIds.length);
@@ -97,11 +97,46 @@ concise = false, skipBuckets = global.grafastExplainMermaidSkipBuckets ?? false,
                 }
             }
         }
-        for (const child of bucket.children) {
-            extractSteps(child);
+    };
+    planJSON.buckets.forEach(extractSteps);
+    const shouldHideStep = (step) => {
+        if (step.stepClass === "ConstantStep")
+            return true;
+        if (step.extra?.constant?.type === "undefined") {
+            return true;
+        }
+        if (step.bucketId === 0 &&
+            step.isSyncAndSafe &&
+            (dependentsByStepId[step.id]?.length ?? 0) === 0) {
+            return true;
+        }
+        return false;
+    };
+    const partitionToPoly = (bucketId) => {
+        const lp = layerPlanById[bucketId];
+        if (lp.reason.type === "polymorphicPartition") {
+            return layerPlans.find((lp) => lp.childIds.includes(bucketId));
+        }
+        else {
+            return bucketId;
         }
     };
-    extractSteps(planJSON.rootBucket);
+    const isExcessivelyReferenced = (stepId) => {
+        const step = stepById[stepId];
+        if (!step)
+            return true;
+        if (step.stepClass === "ConstantStep")
+            return true;
+        if (step.bucketId !== 0)
+            return false;
+        const dependents = dependentsByStepId[stepId];
+        if (!dependents || dependents.length === 0)
+            return false;
+        const firstDependent = dependents[0];
+        // If it's referenced by more than one layer plan, it's excessive
+        return dependents.some((d) => partitionToPoly(d.bucketId) !==
+            partitionToPoly(firstDependent.bucketId));
+    };
     const color = (i) => {
         return exports.COLORS[i % exports.COLORS.length];
     };
@@ -126,6 +161,45 @@ concise = false, skipBuckets = global.grafastExplainMermaidSkipBuckets ?? false,
         }
         return str;
     };
+    const stepToString = (step) => {
+        return `${step.stepClass.replace(/Step$/, "")}${step.bucketId === 0 ? "" : `{${step.bucketId}}`}${step.metaString ? `<${step.metaString}>` : ""}[${step.id}]`;
+    };
+    const layerPlans = Object.values(layerPlanById);
+    if (!skipBuckets) {
+        if (!concise)
+            graph.push("    subgraph Buckets");
+        for (let i = 0, l = layerPlans.length; i < l; i++) {
+            const layerPlan = layerPlans[i];
+            const raisonDEtre = ` (${layerPlan.reason.type})` +
+                (layerPlan.reason.type === "polymorphicPartition"
+                    ? `\n|${layerPlan.reason.typeNames.join("\n|")}`
+                    : layerPlan.reason.type === "polymorphic"
+                        ? `\n__typename: ${shortStep(stepById[layerPlan.reason.parentStepId])}`
+                        : ``);
+            graph.push(`    Bucket${layerPlan.id}(${(0, exports.mermaidEscape)(`Bucket ${layerPlan.id}${raisonDEtre}${layerPlan.parentSideEffectStepId != null
+                ? `\nParent side effect step: ${stepById[layerPlan.parentSideEffectStepId].id}`
+                : ""}${layerPlan.copyStepIds.length > 0
+                ? `\nDeps: ${layerPlan.copyStepIds
+                    .map((pId) => stepById[pId].id)
+                    .join(", ")}`
+                : ""}${layerPlan.reason.type === "polymorphicPartition"
+                ? "\n" + pp(layerPlan.reason.polymorphicPaths)
+                : ""}\n${layerPlan.rootStepId != null && layerPlan.reason.type !== "root"
+                ? `\nROOT ${stepToString(stepById[layerPlan.rootStepId])}`
+                : ""}${startSteps(layerPlan)}`)}):::bucket`);
+        }
+        if (!concise)
+            graph.push("    end");
+    }
+    if (!skipBuckets) {
+        for (let i = 0, l = layerPlans.length; i < l; i++) {
+            const layerPlan = layerPlans[i];
+            const childNodes = layerPlan.childIds.map((cId) => `Bucket${cId}`);
+            if (childNodes.length > 0) {
+                graph.push(`    Bucket${layerPlan.id} --> ${childNodes.join(" & ")}`);
+            }
+        }
+    }
     const planIdMap = Object.create(null);
     const planId = (plan) => {
         if (!planIdMap[plan.id]) {
@@ -140,18 +214,32 @@ concise = false, skipBuckets = global.grafastExplainMermaidSkipBuckets ?? false,
             const meta = concise && strippedMeta ? squish(strippedMeta) : strippedMeta;
             const isUnbatched = plan.supportsUnbatched;
             const polyPaths = pp(plan.polymorphicPaths);
-            const polyPathsIfDifferent = plan.dependencyIds.length === 1 &&
-                pp(stepById[plan.dependencyIds[0]].polymorphicPaths) === polyPaths
-                ? ""
-                : `\n${polyPaths}`;
-            const planString = `${planName}[${plan.id}${`∈${plan.bucketId}`}${plan.stream ? "@s" : ""}]${plan.isUnary ? " ➊" : ""}${meta ? `\n<${meta}>` : ""}${polyPathsIfDifferent}`;
-            const [lBrace, rBrace] = plan.stepClass === "__ItemStep"
+            const depIdsInSameBucket = plan.dependencyIds.filter((id) => stepById[id].bucketId === plan.bucketId);
+            const polyPathsAreSame = depIdsInSameBucket.length >= 1 &&
+                depIdsInSameBucket.every((id) => pp(stepById[id].polymorphicPaths) === polyPaths);
+            const polyPathsIfDifferent = polyPathsAreSame || polyPaths === "" ? "" : `\n${polyPaths}`;
+            const [lBrace, rBrace, shape = "", planNameText = planName] = plan.stepClass === "__ItemStep"
                 ? ["[/", "\\]"]
-                : plan.isSyncAndSafe
-                    ? isUnbatched
-                        ? ["{{", "}}"]
-                        : ["[", "]"]
-                    : ["[[", "]]"];
+                : plan.stepClass === "__ValueStep" && plan.extra?.combined
+                    ? [null, null, "docs", "__Combined"]
+                    : plan.isSyncAndSafe
+                        ? isUnbatched
+                            ? ["{{", "}}"]
+                            : ["[", "]"]
+                        : ["[[", "]]"];
+            const depCount = isExcessivelyReferenced(plan.id)
+                ? `\nDependents: ${dependentsByStepId[plan.id]?.length}`
+                : ``;
+            const extraDeps = plan.dependencyIds.filter(isExcessivelyReferenced);
+            const extraDependencies = extraDeps.length > 0
+                ? `\nMore deps:\n${extraDeps
+                    .map((depId) => {
+                    const step = stepById[depId];
+                    return `- ${shortStep(step)}`;
+                })
+                    .join("\n")}`
+                : ``;
+            const planString = `${planNameText}[${plan.id}${`∈${plan.bucketId}`}${plan.stream ? "@s" : ""}]${plan.isUnary ? " ➊" : ""}${polyPathsAreSame && polyPaths !== "" ? "^" : ""}${meta ? `\n<${meta}>` : ""}${polyPathsIfDifferent}${depCount}${extraDependencies}`;
             const planClass = plan.hasSideEffects
                 ? "sideeffectplan"
                 : plan.stepClass === "__ItemStep"
@@ -159,7 +247,12 @@ concise = false, skipBuckets = global.grafastExplainMermaidSkipBuckets ?? false,
                     : isUnbatched && !plan.isSyncAndSafe
                         ? "unbatchedplan"
                         : "plan";
-            graph.push(`    ${planNode}${lBrace}${(0, exports.mermaidEscape)(planString)}${rBrace}:::${planClass}`);
+            if (lBrace === null) {
+                graph.push(`    ${planNode}:::${planClass}@{shape: ${shape}, label: ${(0, exports.mermaidEscape)(planString)}}`);
+            }
+            else {
+                graph.push(`    ${planNode}${lBrace}${(0, exports.mermaidEscape)(planString)}${rBrace}:::${planClass}`);
+            }
         }
         return planIdMap[plan.id];
     };
@@ -169,6 +262,9 @@ concise = false, skipBuckets = global.grafastExplainMermaidSkipBuckets ?? false,
     const depDeets = (step, idx) => {
         const forbiddenFlags = step.dependencyForbiddenFlags[idx];
         const onReject = step.dependencyOnReject[idx];
+        // TODO: factor 'data only' into the diagrams
+        //
+        // const dataOnly = step.dependencyDataOnly[idx];
         const info = [];
         if (forbiddenFlags) {
             if ((forbiddenFlags & 2) === 2) {
@@ -198,17 +294,15 @@ concise = false, skipBuckets = global.grafastExplainMermaidSkipBuckets ?? false,
         if (shouldHideStep(plan))
             return;
         const planNode = planId(plan);
-        const depNodes = plan.dependencyIds
-            .map((depId) => {
+        const depNodes = plan.dependencyIds.map((depId) => {
             const step = stepById[depId];
-            if (shouldHideStep(step)) {
+            if (shouldHideStep(step) || isExcessivelyReferenced(depId)) {
                 return null;
             }
             else {
                 return planId(step);
             }
-        })
-            .filter((n) => n !== null);
+        });
         const transformItemPlanNode = null;
         /*
         plan.stepClass === '__ListTransformStep'
@@ -217,23 +311,25 @@ concise = false, skipBuckets = global.grafastExplainMermaidSkipBuckets ?? false,
             )
           : null;
           */
-        if (depNodes.length > 0) {
+        const firstDep = depNodes.find((n) => n != null);
+        if (depNodes.length > 0 && firstDep) {
             if (plan.stepClass === "__ItemStep") {
-                const [firstDep, ...rest] = depNodes;
                 const arrow = plan.extra?.transformStepId == null ? "==>" : "-.->";
                 graph.push(`    ${firstDep} ${arrow}${depDeets(plan, 0)} ${planNode}`);
-                if (rest.length > 0) {
-                    const normal = [];
-                    for (let i = 0; i < rest.length; i++) {
-                        const r = rest[i];
-                        const deets = depDeets(plan, i + 1);
-                        if (deets) {
-                            graph.push(`    ${r} -->${deets} ${planNode}`);
-                        }
-                        else {
-                            normal.push(r);
-                        }
+                const normal = [];
+                for (let i = 0; i < depNodes.length; i++) {
+                    const r = depNodes[i];
+                    if (r == null || r === firstDep)
+                        continue;
+                    const deets = depDeets(plan, i);
+                    if (deets) {
+                        graph.push(`    ${r} -->${deets} ${planNode}`);
+                    }
+                    else {
+                        normal.push(r);
                     }
+                }
+                if (normal.length > 0) {
                     outputGroupedNormalLinks(graph, planNode, normal);
                 }
             }
@@ -242,20 +338,21 @@ concise = false, skipBuckets = global.grafastExplainMermaidSkipBuckets ?? false,
                     !dependentsByStepId[plan.id] &&
                     depNodes.length === 1) {
                     // Try alternating the nodes so they render closer together
-                    const depNode = depNodes[0];
-                    if (chainByDep[depNode] === undefined) {
-                        graph.push(`    ${depNode} -->${depDeets(plan, 0)} ${planNode}`);
+                    if (chainByDep[firstDep] === undefined) {
+                        graph.push(`    ${firstDep} -->${depDeets(plan, 0)} ${planNode}`);
                     }
                     else {
-                        graph.push(`    ${chainByDep[depNode]} o--o${depDeets(plan, 0)} ${planNode}`);
+                        graph.push(`    ${chainByDep[firstDep]} o--o${depDeets(plan, 0)} ${planNode}`);
                     }
-                    chainByDep[depNode] = planNode;
+                    chainByDep[firstDep] = planNode;
                 }
                 else {
                     const normal = [];
                     for (let i = 0; i < depNodes.length; i++) {
                         const r = depNodes[i];
-                        const deets = depDeets(plan, i + 1);
+                        if (r == null)
+                            continue;
+                        const deets = depDeets(plan, i);
                         if (deets) {
                             graph.push(`    ${r} -->${deets} ${planNode}`);
                         }
@@ -279,9 +376,15 @@ concise = false, skipBuckets = global.grafastExplainMermaidSkipBuckets ?? false,
             planId(step);
         }
     });
-    const stepToString = (step) => {
-        return `${step.stepClass.replace(/Step$/, "")}${step.bucketId === 0 ? "" : `{${step.bucketId}}`}${step.metaString ? `<${step.metaString}>` : ""}[${step.id}]`;
-    };
+    for (let i = 0, l = layerPlans.length; i < l; i++) {
+        const layerPlan = layerPlans[i];
+        const steps = layerPlan.steps;
+        graph.push(`    classDef bucket${layerPlan.id} stroke:${color(typeof layerPlan.id === "number" ? layerPlan.id : Object.values(layerPlanById).indexOf(layerPlan))}`);
+        graph.push(`    class ${[
+            `Bucket${layerPlan.id}`,
+            ...steps.filter((s) => !shouldHideStep(s)).map(planId),
+        ].join(",")} bucket${layerPlan.id}`);
+    }
     let firstSideEffect = true;
     sortedSteps.forEach((step) => {
         if (step.implicitSideEffectStepId) {
@@ -295,64 +398,22 @@ concise = false, skipBuckets = global.grafastExplainMermaidSkipBuckets ?? false,
         }
     });
     graph.push("");
-    if (!concise && !skipBuckets)
-        graph.push("    subgraph Buckets");
-    const layerPlans = Object.values(layerPlanById);
+    // Handle concat for any "combination" layer plans
     for (let i = 0, l = layerPlans.length; i < l; i++) {
         const layerPlan = layerPlans[i];
-        const steps = layerPlan.steps;
-        const raisonDEtre = ` (${layerPlan.reason.type})` +
-            (layerPlan.reason.type === "polymorphic"
-                ? `\n${layerPlan.reason.typeNames}`
-                : ``);
-        if (!skipBuckets) {
-            graph.push(`    Bucket${layerPlan.id}(${(0, exports.mermaidEscape)(`Bucket ${layerPlan.id}${raisonDEtre}${layerPlan.parentSideEffectStepId != null
-                ? `\nParent side effect step: ${stepById[layerPlan.parentSideEffectStepId].id}`
-                : ""}${layerPlan.copyStepIds.length > 0
-                ? `\nDeps: ${layerPlan.copyStepIds
-                    .map((pId) => stepById[pId].id)
-                    .join(", ")}`
-                : ""}${layerPlan.reason.type === "polymorphic"
-                ? "\n" + pp(layerPlan.reason.polymorphicPaths)
-                : ""}\n${layerPlan.rootStepId != null && layerPlan.reason.type !== "root"
-                ? `\nROOT ${stepToString(stepById[layerPlan.rootStepId])}`
-                : ""}${startSteps(layerPlan)}`)}):::bucket`);
-        }
-        graph.push(`    classDef bucket${layerPlan.id} stroke:${color(layerPlan.id)}`);
-        graph.push(`    class ${[
-            `Bucket${layerPlan.id}`,
-            ...steps.filter((s) => !shouldHideStep(s)).map(planId),
-        ].join(",")} bucket${layerPlan.id}`);
-    }
-    if (!skipBuckets) {
-        for (let i = 0, l = layerPlans.length; i < l; i++) {
-            const layerPlan = layerPlans[i];
-            const childNodes = layerPlan.children.map((c) => `Bucket${c.id}`);
-            if (childNodes.length > 0) {
-                graph.push(`    Bucket${layerPlan.id} --> ${childNodes.join(" & ")}`);
+        if (layerPlan.reason.type === "combined") {
+            for (const { targetStepId, sources } of layerPlan.reason.combinations) {
+                const targetStep = stepById[targetStepId];
+                for (const { stepId } of sources) {
+                    const step = stepById[stepId];
+                    graph.push(`    ${planId(step)} -.-x ${planId(targetStep)}`);
+                }
             }
         }
     }
-    if (!concise && !skipBuckets)
-        graph.push("    end");
     const graphString = graph.join("\n");
     return graphString;
     function startSteps(layerPlan) {
-        function shortStep(step) {
-            return `${step.stepClass.replace(/Step$/, "") ?? ""}[${step.id}]`;
-        }
-        function shortSteps(steps) {
-            if (!steps) {
-                return "";
-            }
-            const str = steps.map(shortStep).join(", ");
-            if (str.length < 40) {
-                return str;
-            }
-            else {
-                return steps.map((s) => s.id).join(", ");
-            }
-        }
         return layerPlan.phases.length === 1
             ? ``
             : `\n${layerPlan.phases
@@ -362,11 +423,51 @@ concise = false, skipBuckets = global.grafastExplainMermaidSkipBuckets ?? false,
                 .join("\n")}`;
     }
 }
+function shortStep(step) {
+    if (step.stepClass === "ConstantStep") {
+        return `Constant${step.metaString ? `<${step.metaString}>` : ""}[${step.id}]`;
+    }
+    return `${step.stepClass.replace(/Step$/, "") ?? ""}[${step.id}]`;
+}
+function shortSteps(steps) {
+    if (!steps) {
+        return "";
+    }
+    const str = steps.map(shortStep).join(", ");
+    if (str.length < 40) {
+        return str;
+    }
+    else {
+        return steps.map((s) => s.id).join(", ");
+    }
+}
 function pp(polymorphicPaths) {
-    if (!polymorphicPaths) {
+    if (polymorphicPaths == null) {
         return "";
     }
-    return polymorphicPaths.map((p) => `${p}`).join("\n");
+    const counts = Object.create(null);
+    const out = [];
+    const last = Object.create(null);
+    for (const p of polymorphicPaths) {
+        const i = p.lastIndexOf(">");
+        if (i <= 0) {
+            out.push(p);
+        }
+        else {
+            const end = p.slice(i);
+            last[end] = p;
+            if (counts[end]) {
+                counts[end]++;
+            }
+            else {
+                counts[end] = 1;
+            }
+        }
+    }
+    for (const [end, count] of Object.entries(counts)) {
+        out.push(count === 1 ? last[end] : `(${count}) ...${end}`);
+    }
+    return out.join("\n");
 }
 tslib_1.__exportStar(require("./planJSONInterfaces.js"), exports);
 function trim(string, length = 15) {

package/dist/operationPlan-input.d.ts

@@ -3,6 +3,6 @@ import type { OperationPlan } from "./engine/OperationPlan.js";
 import type { FieldArgs, TrackedArguments } from "./interfaces.js";
 import type { Step } from "./step.js";
 export type ApplyAfterModeArg = "plan" | "subscribePlan";
-export declare function withFieldArgsForArguments<T extends Step>(operationPlan: OperationPlan, $all: TrackedArguments, field: GraphQLField<any, any, any>, $parent: Step, applyAfterMode: ApplyAfterModeArg, coordinate: string, callback: (fieldArgs: FieldArgs) => T | null | undefined): Exclude<T, undefined | null> | null;
+export declare function withFieldArgsForArguments<T extends Step>(operationPlan: OperationPlan, trackedArguments: TrackedArguments, field: GraphQLField<any, any, any>, $parent: Step, applyAfterMode: ApplyAfterModeArg, coordinate: string, callback: (fieldArgs: FieldArgs) => T | null | undefined): T | null;
 export declare function getNullableInputTypeAtPath(startType: GraphQLInputType, path: ReadonlyArray<string | number>): GraphQLInputType & GraphQLNullableType;
 //# sourceMappingURL=operationPlan-input.d.ts.map

package/dist/operationPlan-input.js

@@ -13,7 +13,7 @@ function assertNotRuntime(operationPlan, description) {
         throw new Error(`${description} may only be called at planning time; however you have code that has attempted to call it during execution time. Please revisit your plan resolvers to locate the issue.`);
     }
 }
-function withFieldArgsForArguments(operationPlan, $all, field, $parent, applyAfterMode, coordinate, callback) {
+function withFieldArgsForArguments(operationPlan, trackedArguments, field, $parent, applyAfterMode, coordinate, callback) {
     if (operationPlan.loc !== null)
         operationPlan.loc.push(`withFieldArgsForArguments(${field.name})`);
     const args = Object.create(null);
@@ -62,17 +62,17 @@ function withFieldArgsForArguments(operationPlan, $all, field, $parent, applyAft
         getRaw(path) {
             assertNotRuntime(operationPlan, `fieldArgs.getRaw()`);
             if (path === undefined) {
-                return (0, index_js_1.object)(Object.fromEntries(Object.keys(args).map((argName) => [argName, $all.get(argName)])));
+                return (0, index_js_1.object)(trackedArguments);
             }
             else if (typeof path === "string") {
-                return $all.get(path);
+                return trackedArguments[path];
             }
             else if (Array.isArray(path)) {
                 const [first, ...rest] = path;
                 if (!first) {
                     throw new Error(`getRaw() must be called with a non-empty path`);
                 }
-                let $entry = $all.get(first);
+                let $entry = trackedArguments[first];
                 for (const pathSegment of rest) {
                     if (typeof pathSegment === "number" && "at" in $entry) {
                         $entry = $entry.at(pathSegment);
@@ -141,13 +141,16 @@ function withFieldArgsForArguments(operationPlan, $all, field, $parent, applyAft
         });
     }
     const result = callback(fieldArgs);
+    if (result === undefined) {
+        throw new Error(`Field ${coordinate} returned 'undefined'; perhaps you forgot the 'return' statement?`);
+    }
     (0, utils_js_1.assertNotPromise)(result, callback, operationPlan.loc?.join(">") ?? "???");
     if (!explicitlyApplied && result != null) {
         processAfter($parent, fieldArgs, result, args, applyAfterMode, coordinate);
     }
     if (operationPlan.loc !== null)
         operationPlan.loc.pop();
-    return (result ?? null);
+    return result;
 }
 function processAfter($parent, rootFieldArgs, $result, args, applyAfterMode, coordinate) {
     const schema = $parent.operationPlan.schema;
@@ -158,6 +161,13 @@ function processAfter($parent, rootFieldArgs, $result, args, applyAfterMode, coo
                 ? arg.extensions.grafast?.applySubscribePlan
                 : null;
         if (autoApply) {
+            if (arg.defaultValue === undefined) {
+                const $argVal = rootFieldArgs.getRaw(argName);
+                if ($argVal instanceof index_js_1.ConstantStep && $argVal.data === undefined) {
+                    // no action necessary
+                    continue;
+                }
+            }
             // TODO: should this have dollars on it for accessing subkeys?
             const input = {
                 typeAt(path) {

package/dist/planJSONInterfaces.d.ts

@@ -12,6 +12,7 @@ export interface GrafastPlanStepJSONv1 {
     dependencyIds: ReadonlyArray<string | number>;
     dependencyForbiddenFlags: ReadonlyArray<ExecutionEntryFlags>;
     dependencyOnReject: ReadonlyArray<string | null | undefined>;
+    dependencyDataOnly: ReadonlyArray<boolean>;
     polymorphicPaths: readonly string[] | undefined;
     isSyncAndSafe: boolean | undefined;
     supportsUnbatched: boolean | undefined;
@@ -25,7 +26,7 @@ export interface GrafastPlanBucketPhaseJSONv1 {
     normalStepIds?: ReadonlyArray<string | number>;
     unbatchedStepIds?: ReadonlyArray<string | number>;
 }
-export type GrafastPlanBucketReasonJSONv1 = GrafastPlanBucketReasonRootJSONv1 | GrafastPlanBucketReasonNullableFieldJSONv1 | GrafastPlanBucketReasonListItemJSONv1 | GrafastPlanBucketReasonSubscriptionJSONv1 | GrafastPlanBucketReasonMutationFieldJSONv1 | GrafastPlanBucketReasonDeferJSONv1 | GrafastPlanBucketReasonPolymorphicJSONv1 | GrafastPlanBucketReasonSubroutineJSONv1;
+export type GrafastPlanBucketReasonJSONv1 = GrafastPlanBucketReasonRootJSONv1 | GrafastPlanBucketReasonNullableFieldJSONv1 | GrafastPlanBucketReasonListItemJSONv1 | GrafastPlanBucketReasonSubscriptionJSONv1 | GrafastPlanBucketReasonMutationFieldJSONv1 | GrafastPlanBucketReasonDeferJSONv1 | GrafastPlanBucketReasonPolymorphicJSONv1 | GrafastPlanBucketReasonPolymorphicPartitionJSONv1 | GrafastPlanBucketReasonCombinedJSONv1 | GrafastPlanBucketReasonSubroutineJSONv1;
 export interface GrafastPlanBucketReasonRootJSONv1 {
     type: "root";
 }
@@ -59,31 +60,49 @@ export interface GrafastPlanBucketReasonDeferJSONv1 {
     type: "defer";
     label?: string;
 }
-/** Branching, non-deferred */
+/** Non-branching, non-deferred */
 export interface GrafastPlanBucketReasonPolymorphicJSONv1 {
     type: "polymorphic";
     typeNames: readonly string[];
     parentStepId: string | number;
     polymorphicPaths: ReadonlyArray<string>;
 }
+/** Branching, non-deferred */
+export interface GrafastPlanBucketReasonPolymorphicPartitionJSONv1 {
+    type: "polymorphicPartition";
+    typeNames: readonly string[];
+    polymorphicPaths: ReadonlyArray<string>;
+}
 /** Non-branching, non-deferred */
 export interface GrafastPlanBucketReasonSubroutineJSONv1 {
     type: "subroutine";
     parentStepId: string | number;
 }
+/** Anti-branching, non-deferred */
+export interface GrafastPlanBucketReasonCombinedJSONv1 {
+    type: "combined";
+    parentLayerPlanIds: ReadonlyArray<string | number>;
+    combinations: ReadonlyArray<{
+        sources: readonly {
+            layerPlanId: string | number;
+            stepId: string | number;
+        }[];
+        targetStepId: number;
+    }>;
+}
 export interface GrafastPlanBucketJSONv1 {
-    id: number;
+    id: number | string;
     reason: GrafastPlanBucketReasonJSONv1;
     parentSideEffectStepId: string | number | null;
     copyStepIds: ReadonlyArray<string | number>;
     steps: ReadonlyArray<GrafastPlanStepJSONv1>;
     rootStepId: string | number | null;
     phases: ReadonlyArray<GrafastPlanBucketPhaseJSONv1>;
-    children: ReadonlyArray<GrafastPlanBucketJSONv1>;
+    childIds: ReadonlyArray<number | string>;
 }
 export interface GrafastPlanJSONv1 extends GrafastPlanJSON {
     version: "v1";
-    rootBucket: GrafastPlanBucketJSONv1;
+    buckets: ReadonlyArray<GrafastPlanBucketJSONv1>;
 }
 export type JSONValue = boolean | number | string | null | JSONObject | JSONArray;
 export interface JSONObject {

package/dist/prepare.d.ts

@@ -1,7 +1,5 @@
-import type { GrafastPlanJSON } from "./index.js";
 import type { GrafastTimeouts } from "./interfaces.js";
-declare const $$contextPlanCache: unique symbol;
-export interface GrafastPrepareOptions {
+export interface GrafastOperationOptions {
     /**
      * A list of 'explain' types that should be included in `extensions.explain`.
      *
@@ -18,11 +16,20 @@ export interface GrafastPrepareOptions {
      */
     outputDataAsString?: boolean;
     timeouts?: GrafastTimeouts;
+    /**
+     * How many planning layers deep do we allow? Should be handled by validation.
+     *
+     * A planning layer can happen due to:
+     *
+     * - A nested selection set
+     * - Planning a field return type
+     * - A list position
+     * - A polymorphic type
+     * - A deferred/streamed response
+     *
+     * These reasons may each cause 1, 2 or 3 planning layers to be added, so this
+     * limit should be set quite high - e.g. 6x the selection set depth.
+     */
+    maxPlanningDepth?: number;
 }
-declare module "./engine/OperationPlan.js" {
-    interface OperationPlan {
-        [$$contextPlanCache]?: GrafastPlanJSON;
-    }
-}
-export {};
 //# sourceMappingURL=prepare.d.ts.map