Hide @internal APIs from TypeScript consumers

.changeset/stale-geckos-drop.md

@@ -0,0 +1,16 @@
+---
+"graphile-build": patch
+"graphile-utils": patch
+"@dataplan/json": patch
+"@dataplan/pg": patch
+"grafast": patch
+"tamedevil": patch
+"pg-sql2": patch
+---
+
+🚨 TypeScript is now configured to hide interfaces marked as `@internal`. This
+may result in a few errors where you're accessing things you oughtn't be, but
+also may hide some interfaces that should be exposed - please file an issue if
+an API you were dependent on has been removed from the TypeScript typings. If
+that API happens to be `step.dependencies`; you should first read this:
+https://benjie.dev/graphql/ancestors

grafast/dataplan-json/src/steps/jsonParse.ts

@@ -36,7 +36,7 @@ export class JSONParseStep<
   }
 
   toStringMeta(): string {
-    return chalk.bold.yellow(String(this.dependencies[0].id));
+    return chalk.bold.yellow(String(this.getDep(0).id));
   }
 
   get<TKey extends keyof TJSON>(

grafast/dataplan-pg/src/datasource.ts

@@ -269,7 +269,7 @@ export class PgResource<
    * an array of arrays) - and thus is not appropriate to use for GraphQL
    * Cursor Connections.
    *
-   * @internal
+   * @experimental
    */
   public sqlPartitionByIndex: SQL | null = null;
 

grafast/dataplan-pg/src/examples/exampleSchema.ts

@@ -46,7 +46,7 @@ import {
   newInputObjectTypeBuilder,
   newObjectTypeBuilder,
   object,
-  operationPlan,
+  rootValue,
 } from "grafast";
 import type { GraphQLOutputType } from "grafast/graphql";
 import {
@@ -4741,11 +4741,11 @@ export function makeExampleSchema(
       query: {
         type: Query,
         plan: EXPORTABLE(
-          (operationPlan) =>
+          (rootValue) =>
             function plan() {
-              return operationPlan().rootValueStep;
+              return rootValue();
             },
-          [operationPlan],
+          [rootValue],
         ),
       },
     },
@@ -4780,11 +4780,11 @@ export function makeExampleSchema(
       query: {
         type: Query,
         plan: EXPORTABLE(
-          (operationPlan) =>
+          (rootValue) =>
             function plan() {
-              return operationPlan().rootValueStep;
+              return rootValue();
             },
-          [operationPlan],
+          [rootValue],
         ),
       },
     },
@@ -4825,11 +4825,11 @@ export function makeExampleSchema(
       query: {
         type: Query,
         plan: EXPORTABLE(
-          (operationPlan) =>
+          (rootValue) =>
             function plan() {
-              return operationPlan().rootValueStep;
+              return rootValue();
             },
-          [operationPlan],
+          [rootValue],
         ),
       },
     },

grafast/dataplan-pg/src/steps/pgCondition.ts

@@ -8,11 +8,13 @@ import type { PgCodec } from "../interfaces.js";
 
 export type PgWhereConditionSpec<TAttribute extends string> =
   | SQL
-  | {
-      type: "attribute";
-      attribute: TAttribute;
-      callback: (fragment: SQL) => SQL;
-    };
+  | PgWhereConditionAttributeSpec<TAttribute>;
+
+export interface PgWhereConditionAttributeSpec<TAttribute extends string> {
+  type: "attribute";
+  attribute: TAttribute;
+  callback: (fragment: SQL) => SQL;
+}
 
 export type PgHavingConditionSpec<_TAttribute extends string> = SQL;
 // | ...

grafast/dataplan-pg/src/steps/pgSelect.ts

@@ -856,8 +856,6 @@ export class PgSelectStep<
 
   /**
    * @experimental Please use `singleRelation` or `manyRelation` instead.
-   *
-   * @internal
    */
   public join(spec: PgSelectPlanJoin) {
     this.joins.push(spec);
@@ -922,7 +920,6 @@ export class PgSelectStep<
     return new PgSelectStep(this, mode);
   }
 
-  /** @internal */
   connectionClone(
     $connection: ConnectionStep<any, any, any, any>,
     mode?: PgSelectMode,
@@ -1167,7 +1164,6 @@ and ${sql.indent(sql.parens(condition(i + 1)))}`}
     this.where(finalCondition);
   }
 
-  /** @internal */
   parseCursor(
     $cursorPlan: __InputStaticLeafStep<string>,
   ): PgSelectParsedCursorStep | null {
@@ -1190,7 +1186,6 @@ and ${sql.indent(sql.parens(condition(i + 1)))}`}
     this.beforeStepId = this.addDependency($parsedCursorPlan);
   }
 
-  /** @internal */
   public pageInfo(
     $connectionPlan: ConnectionStep<any, PgSelectParsedCursorStep, this, any>,
   ): PgPageInfoStep<this> {

grafast/grafast/src/engine/OperationPlan.ts

@@ -70,6 +70,7 @@ import {
   findVariableNamesUsed,
   hasItemPlan,
   isTypePlanned,
+  sudo,
 } from "../utils.js";
 import type {
   LayerPlanPhase,
@@ -139,7 +140,7 @@ const isDev =
 /** How many times will we try re-optimizing before giving up */
 const MAX_OPTIMIZATION_LOOPS = 10;
 
-/** @internal */
+/** Beware: the list of phases may change over time... @experimental */
 export type OperationPlanPhase =
   | "init"
   | "plan"
@@ -190,8 +191,6 @@ export class OperationPlan {
    * 7. ready
    *
    * Once in 'ready' state we can execute the plan.
-   *
-   * @internal
    */
   public phase: OperationPlanPhase = "init";
   /**
@@ -235,9 +234,7 @@ export class OperationPlan {
   /** Stores the actual value of the context. @internal */
   public readonly contextStep: __ValueStep<Grafast.Context>;
   /** Allows accessing context in a tracked manner (allowing eval). @internal */
-  public readonly trackedContextStep: __TrackedValueStep<{
-    [key: string]: any;
-  }>;
+  public readonly trackedContextStep: __TrackedValueStep<Grafast.Context>;
 
   /** Constraints based on evaluating rootValue. @internal */
   public readonly rootValueConstraints: Constraint[] = [];
@@ -2097,7 +2094,7 @@ export class OperationPlan {
     } else {
       // used for: hoist
 
-      for (const $processFirst of step.dependencies) {
+      for (const $processFirst of sudo(step).dependencies) {
         if (!processed.has($processFirst)) {
           this.processStep(
             actionDescription,
@@ -2230,7 +2227,7 @@ export class OperationPlan {
       dependencies: deps,
       layerPlan: layerPlan,
       constructor: stepConstructor,
-    } = step;
+    } = sudo(step);
     const dependencyCount = deps.length;
 
     if (dependencyCount === 0) {
@@ -2277,7 +2274,7 @@ export class OperationPlan {
           !possiblyPeer.hasSideEffects &&
           possiblyPeer.constructor === stepConstructor &&
           peerLayerPlan.depth >= minDepth &&
-          possiblyPeer.dependencies.length === dependencyCount &&
+          sudo(possiblyPeer).dependencies.length === dependencyCount &&
           peerLayerPlan === ancestry[peerLayerPlan.depth]
         ) {
           if (allPeers === null) {
@@ -2326,7 +2323,7 @@ export class OperationPlan {
               peerDependencyIndex === dependencyIndex &&
               !possiblyPeer.hasSideEffects &&
               possiblyPeer.constructor === stepConstructor &&
-              possiblyPeer.dependencies.length === dependencyCount &&
+              sudo(possiblyPeer).dependencies.length === dependencyCount &&
               possiblyPeer.layerPlan === ancestry[possiblyPeer.layerPlan.depth]
             ) {
               possiblePeers.push(possiblyPeer);
@@ -2347,7 +2344,7 @@ export class OperationPlan {
         // We know the final dependency matches and the dependency count
         // matches - check the other dependencies match.
         for (let i = 0; i < dependencyCount - 1; i++) {
-          if (deps[i] !== possiblyPeer.dependencies[i]) {
+          if (deps[i] !== sudo(possiblyPeer).dependencies[i]) {
             continue outerloop;
           }
         }
@@ -2440,7 +2437,7 @@ export class OperationPlan {
       case "nullableBoundary": {
         // Safe to hoist _unless_ it depends on the root step of the nullableBoundary.
         const $root = step.layerPlan.reason.parentStep!;
-        if (step.dependencies.includes($root)) {
+        if (sudo(step).dependencies.includes($root)) {
           return;
         } else {
           break;
@@ -2482,7 +2479,7 @@ export class OperationPlan {
     }
 
     // Finally, check that none of its dependencies are in the same bucket.
-    const deps = step.dependencies;
+    const deps = sudo(step).dependencies;
     if (deps.some((dep) => dep.layerPlan === step.layerPlan)) {
       return;
     }
@@ -2850,7 +2847,7 @@ export class OperationPlan {
     step: ExecutableStep,
   ) {
     processed.add(step);
-    for (const dep of step.dependencies) {
+    for (const dep of sudo(step).dependencies) {
       if (dep.id >= start && !processed.has(dep)) {
         this.deduplicateStepsProcess(processed, start, dep);
       }
@@ -3118,7 +3115,7 @@ export class OperationPlan {
 
         const sideEffectDeps: ExecutableStep[] = [];
         const rest: ExecutableStep[] = [];
-        for (const dep of step.dependencies) {
+        for (const dep of sudo(step).dependencies) {
           if (dep.layerPlan !== layerPlan) {
             continue;
           }
@@ -3156,7 +3153,7 @@ export class OperationPlan {
       }
 
       const readyToExecute = (step: ExecutableStep): boolean => {
-        for (const dep of step.dependencies) {
+        for (const dep of sudo(step).dependencies) {
           if (dep.layerPlan === layerPlan && pending.has(dep)) {
             return false;
           }
@@ -3252,7 +3249,7 @@ export class OperationPlan {
         if ($$noExec in step) {
           continue;
         }
-        for (const dep of step.dependencies) {
+        for (const dep of sudo(step).dependencies) {
           ensurePlanAvailableInLayer(dep, layerPlan);
         }
       }
@@ -3332,7 +3329,7 @@ export class OperationPlan {
         stepClass: step.constructor.name,
         metaString: metaString ? stripAnsi(metaString) : metaString,
         bucketId: step.layerPlan.id,
-        dependencyIds: step.dependencies.map((d) => d.id),
+        dependencyIds: sudo(step).dependencies.map((d) => d.id),
         polymorphicPaths: step.polymorphicPaths
           ? [...step.polymorphicPaths]
           : undefined,
@@ -3427,7 +3424,7 @@ export class OperationPlan {
     const process = (lp: LayerPlan, known: LayerPlan[]) => {
       for (const step of this.stepTracker.activeSteps) {
         if (step.layerPlan === lp) {
-          for (const dep of step.dependencies) {
+          for (const dep of sudo(step).dependencies) {
             if (!known.includes(dep.layerPlan)) {
               // Naughty naughty
               (subroutineStep as any).addDependency(dep);

grafast/grafast/src/engine/StepTracker.ts

@@ -2,6 +2,7 @@ import { isDev } from "../dev.js";
 import type { OperationPlan } from "../index.js";
 import { $$subroutine } from "../interfaces.js";
 import type { ExecutableStep } from "../step";
+import { sudo } from "../utils.js";
 import type {
   LayerPlan,
   LayerPlanReasonSubroutine,
@@ -285,7 +286,7 @@ export class StepTracker {
     }
     this.stepsWithNoDependencies.delete($dependent);
     const dependencyIndex =
-      writeableArray($dependent.dependencies).push($dependency) - 1;
+      writeableArray(sudo($dependent).dependencies).push($dependency) - 1;
     writeableArray($dependency.dependents).push({
       step: $dependent,
       dependencyIndex,
@@ -394,7 +395,7 @@ export class StepTracker {
       if (dependents.length > 0) {
         const replacementDependents = writeableArray($replacement.dependents);
         for (const dependent of dependents) {
-          writeableArray(dependent.step.dependencies)[
+          writeableArray(sudo(dependent.step).dependencies)[
             dependent.dependencyIndex
           ] = $replacement;
           replacementDependents.push(dependent);
@@ -561,7 +562,7 @@ export class StepTracker {
     }
 
     // Since this step is being removed, it doesn't need its dependencies any more
-    const oldDependencies = $original.dependencies;
+    const oldDependencies = sudo($original).dependencies;
     for (const $dependency of oldDependencies) {
       // $dependency is no longer a dependent of $original, since we're getting
       // rid of $original

grafast/grafast/src/engine/executeBucket.ts

@@ -24,7 +24,7 @@ import { isStreamableStep } from "../step.js";
 import { __ItemStep } from "../steps/__item.js";
 import { __ValueStep } from "../steps/__value.js";
 import { timeSource } from "../timeSource.js";
-import { arrayOfLength, isPromiseLike } from "../utils.js";
+import { arrayOfLength, isPromiseLike, sudo } from "../utils.js";
 import type { MetaByMetaKey } from "./OperationPlan.js";
 
 const DEBUG_POLYMORPHISM = false;
@@ -516,7 +516,9 @@ export function executeBucket(
           allStepsIndex < allStepsLength;
           allStepsIndex++
         ) {
-          const step = _allSteps[allStepsIndex] as UnbatchedExecutableStep;
+          const step = sudo(
+            _allSteps[allStepsIndex] as UnbatchedExecutableStep,
+          );
           const storeEntry = bucket.store.get(step.id)!;
           try {
             const deps: any = [];
@@ -666,7 +668,10 @@ export function executeBucket(
 
     // Trim the side-effect dependencies back out again
     const dependencies = sideEffectStepsWithErrors
-      ? dependenciesIncludingSideEffects.slice(0, step.dependencies.length)
+      ? dependenciesIncludingSideEffects.slice(
+          0,
+          sudo(step).dependencies.length,
+        )
       : dependenciesIncludingSideEffects;
 
     if (needsNoExecution) {
@@ -714,15 +719,16 @@ export function executeBucket(
         _requestContext: requestContext,
       };
       const dependencies: ReadonlyArray<any>[] = [];
-      const depCount = step.dependencies.length;
+      const sstep = sudo(step);
+      const depCount = sstep.dependencies.length;
       if (depCount > 0 || sideEffectStepsWithErrors !== null) {
         for (let i = 0, l = depCount; i < l; i++) {
-          const $dep = step.dependencies[i];
+          const $dep = sstep.dependencies[i];
           dependencies[i] = store.get($dep.id)!;
         }
         if (sideEffectStepsWithErrors !== null) {
-          if (step.polymorphicPaths) {
-            for (const path of step.polymorphicPaths) {
+          if (sstep.polymorphicPaths) {
+            for (const path of sstep.polymorphicPaths) {
               for (const sideEffectStep of sideEffectStepsWithErrors[path]) {
                 const sideEffectStoreEntry = store.get(sideEffectStep.id)!;
                 if (!dependencies.includes(sideEffectStoreEntry)) {