Add branded dep ID docs

Author: XiNiHa

grafast/grafast/examples/complexInputs.mts

@@ -62,7 +62,7 @@ setTimeout(async () => {
 // Everything below this line will be output in the docs at
 // http://build.graphile.org/graphile-build/next/all-hooks
 /******************************************************************************/
-import type { ExecutionDetails, ExecutionValue, Maybe } from "grafast";
+import type { DepId, ExecutionDetails, Maybe } from "grafast";
 import { makeGrafastSchema, Modifier, Step } from "grafast";
 
 interface Filterable {
@@ -117,8 +117,8 @@ class SearchRequestStep extends Step<{
   sql: string;
   patchJSON: string;
 }> {
-  private readonly patchDepId: number;
-  private readonly applyDepIds: number[] = [];
+  private readonly patchDepId: DepId<Step<BakedUserPatch>>;
+  private readonly applyDepIds: DepId<Step<FilterCallbacks>>[] = [];
 
   constructor($patch: Step<BakedUserPatch>) {
     super();
@@ -130,17 +130,15 @@ class SearchRequestStep extends Step<{
   }
 
   execute(details: ExecutionDetails) {
-    const patchDep = details.values[
-      this.patchDepId
-    ] as ExecutionValue<BakedUserPatch>;
+    const patchDep = details.values.at(this.patchDepId);
 
     const clauses: string[] = [
       // Put any initial clauses here
     ];
 
     // Apply the callbacks
     const applyCallbacks = this.applyDepIds
-      .flatMap((id) => details.values[id].unaryValue() as FilterCallbacks)
+      .flatMap((id) => details.values.at(id).unaryValue())
       .filter((cb) => cb != null);
     const filterable: Filterable = {
       addClause: (clause) => void clauses.push(clause),

grafast/website/grafast/index.mdx

@@ -85,7 +85,7 @@ The GraphQL specification
 [notes](https://spec.graphql.org/draft/#sec-Conforming-Algorithms):
 
 > _Conformance requirements [...] can be fulfilled [...] in any way as long as
-> the perceived result is equivalent._  
+> the perceived result is equivalent._
 > ─ https://spec.graphql.org/draft/#sec-Conforming-Algorithms
 
 Gra*fast* has been written very carefully by a [GraphQL Technical Steering
@@ -336,9 +336,10 @@ once all of its dependencies are ready, continuing until all steps are
 complete.
 
 At planning time a step can add a dependency on another step via `const depId =
-this.addDependency($otherStep);`. This `depId` is the index in the **values
-tuple** that the step can use at execution time to retrieve the associated
-values.
+this.addDependency($otherStep);`. This `depId` is a branded dependency ID: at
+runtime it is the index in the **values tuple**, and in TypeScript it carries
+the dependency step type so the step can use `values.at(depId)` at execution
+time to retrieve the associated values.
 
 When a step executes, its `execute` method is passed the **execution
 details** which includes:
@@ -393,7 +394,7 @@ export class RecordsByColumnStep extends Step {
     super();
     this.tableName = tableName;
     this.columnName = columnName;
-    this.columnValueDepIdx = this.addDependency($columnValue);
+    this.columnValueDepId = this.addDependency($columnValue);
   }
 
   setFirst($first) {
@@ -402,15 +403,15 @@ export class RecordsByColumnStep extends Step {
 
   async execute({ indexMap, values }) {
     // Retrieve the values for the `$columnValue` dependency
-    const columnValueDep = values[this.columnValueDepIdx];
+    const columnValueDep = values.at(this.columnValueDepId);
 
     // We may or may not have added a `$first` limit:
     const firstDep =
-      this.firstDepId !== undefined ? values[this.firstDepId] : undefined;
+      this.firstDepId !== undefined ? values.at(this.firstDepId) : undefined;
 
     // firstDep, if it exists, is definitely a unary dep (!firstDep.isBatch), so
     // we can retrieve its value directly:
-    const first = firstDep ? parseInt(firstDep.value, 10) : null;
+    const first = firstDep ? parseInt(firstDep.unaryValue(), 10) : null;
 
     // Create a `LIMIT` clause in our SQL if the user specified a `$first` limit:
     const limitSQL = Number.isFinite(first) ? `limit ${first}` : ``;

grafast/website/grafast/plan-resolvers/complex-inputs.md

@@ -241,8 +241,10 @@ may apply to the same step, you should expect multiple calls to `.apply()`
 and thus store all dependency IDs in an array:
 
 ```ts
+import { Step, type DepId } from "grafast";
+
 class MyRequestStep extends Step {
-  applyDepIds: number[] = [];
+  applyDepIds: DepId<Step<(parent: any) => void>>[] = [];
 
   apply($cb: Step<(parent: any) => void>) {
     this.applyDepIds.push(this.addUnaryDependency($cb));
@@ -273,7 +275,7 @@ class MyRequestStep extends Step {
 
     // Apply the changes from all the `.apply($cb)` calls
     for (const applyDepId of this.applyDepIds) {
-      const applyCallback = values[applyDepId].unaryValue();
+      const applyCallback = values.at(applyDepId).unaryValue();
       applyCallback(builder);
     }
 

grafast/website/grafast/step-classes.mdx

@@ -131,8 +131,10 @@ but Gra*fast* steps are much more powerful thanks to the additional dependencies
 and lifecycle methods.
 
 When the step class adds a dependency (with `this.addDependency($step)` or
-similar) a dependency index, `depIndex`, is returned. Dependency indexes start
-at 0 and increase monotonically (a dependency can never be removed[^1]).
+similar) a dependency ID, `depId`, is returned. Dependency IDs are numbers at
+runtime and start at 0, increasing monotonically (a dependency can never be
+removed[^1]). In TypeScript they are branded as `DepId<TStep>`, which preserves
+the dependency step type for helpers such as `details.values.at(depId)`.
 
 [^1]:
     To remove a dependency, you must instead replace the step with a copy that
@@ -155,9 +157,10 @@ of the execute method.
 
 `details.values` is also critical: an ordered array of execution values, one for
 each dependency. You can retrieve the execution value for a given dependency via
-its `depIndex` as `const depEv = details.values[depIndex]`. Once you have an
-execution value, you can retrieve the value for a given index in the batch via
-`const value = depEv.at(batchIndex)`.
+its `depId` as `const depEv = details.values.at(depId)`. Tuple destructuring or
+`details.values[depIndex]` is also fine when it is more convenient. Once you
+have an execution value, you can retrieve the value for a given index in the
+batch via `const value = depEv.at(batchIndex)`.
 
 Gra*fast* tracks which steps will always represent exactly one value (e.g. the
 GraphQL context, input values passed as field arguments, constants, etc), and
@@ -180,9 +183,9 @@ top of the execute method:
 class MyStep extends Step {
   constructor($a, $b, $c) {
     super();
-    this.aDepIndex = this.addUnaryDependency($a);
-    this.bDepIndex = this.addDependency($b);
-    this.cDepIndex = this.addDependency($c);
+    this.addUnaryDependency($a);
+    this.addDependency($b);
+    this.addDependency($c);
   }
   execute(details) {
     const { values } = details;
@@ -243,23 +246,25 @@ Here's a hypothetical example, concentrate on the `execute()` method and see how
 the steps outlined above play out:
 
 ```ts
+import { Step, type DepId } from "grafast";
 import { languageService } from "./services/language";
 
-class TranslationStep extends Step {
-  langDepIndex: number;
-  textDepIndex: number;
+class TranslationStep extends Step<string | undefined> {
+  langDepId: DepId<Step<string>>;
+  textDepId: DepId<Step<string>>;
+
   constructor($language: Step<string>, $text: Step<string>) {
     super();
     // Add our dependencies
-    this.langDepIndex = this.addDependency($language);
-    this.textDepIndex = this.addDependency($text);
+    this.langDepId = this.addDependency($language);
+    this.textDepId = this.addDependency($text);
   }
-  execute(details) {
+  async execute(details) {
     // highlight-start
     // 1. Extract and identify the execution value for each dependency:
     // highlight-end
-    const langEv = details.values[this.langDepIndex];
-    const textEv = details.values[this.textDepIndex];
+    const langEv = details.values.at(this.langDepId);
+    const textEv = details.values.at(this.textDepId);
 
     // highlight-start
     // 2. Map over the indices to prepare the input for our translation API:
@@ -278,7 +283,7 @@ class TranslationStep extends Step {
     // highlight-start
     // 4. Finally, return results that correlate with the inputs:
     // highlight-end
-    return indexMap((batchIndex) => {
+    return details.indexMap((batchIndex) => {
       const language = langEv.at(batchIndex);
       const sourceText = textEv.at(batchIndex);
       const match = translations.find(
@@ -736,8 +741,10 @@ as part of `Step`.
 
 When your step requires another step's value in order to execute (which is the
 case for the majority of steps!) it must add a dependency via the
-`this.addDependency($otherStep)` method. This method will return a number,
-which is the index in the `execute` values tuple that represents this step.
+`this.addDependency($otherStep)` method. This method will return a `DepId`
+(a branded number), which is the index in the `execute` values tuple that
+represents the dependency. TypeScript uses the brand to infer the dependency's
+data type when you later call `details.values.at(depId)`.
 
 It's common to do this in the constructor, but it can be done at other stages
 too, for example during the optimize phase a step's descendant might ask it to
@@ -750,8 +757,8 @@ class added two dependencies:
 class AddStep extends Step {
   constructor($a, $b) {
     super();
-    this.addDependency($a); // Returns 0
-    this.addDependency($b); // Returns 1
+    this.addDependency($a); // Returns 0 as a DepId
+    this.addDependency($b); // Returns 1 as a DepId
   }
 }
 ```
@@ -805,9 +812,10 @@ input values are not).
 
 ### getDep
 
-Pass in the number of the dependency (`0` for the first dependency, `1` for the
-second, and so on) and Gra*fast* will return the corresponding step. This should
-only be used before or during the `optimize` phase.
+Pass in the dependency ID returned from `addDependency`, or a literal dependency
+index (`0` for the first dependency, `1` for the second, and so on), and
+Gra*fast* will return the corresponding step. This should only be used before
+or during the `optimize` phase.
 
 For example in the `AddStep` example above we might have: