Update transform API to operate on top of a stitching scaffolding (#17)

Author: yaacovCR

.changeset/cute-cougars-drop.md

@@ -0,0 +1,7 @@
+---
+'@yaacovcr/transform': patch
+---
+
+Add initial functionality for composition of subschemas, i.e. stitching.
+
+This functionality will supplant object extension.

.changeset/happy-pens-walk.md

@@ -0,0 +1,5 @@
+---
+'@yaacovcr/transform': patch
+---
+
+Change main export to `transform` from `transformResult`.

.mocharc.yml

@@ -5,3 +5,4 @@ extension:
   - ts
 node-option:
   - 'loader=ts-node/esm/transpile-only'
+  - 'enable-source-maps'

README.md

@@ -22,31 +22,60 @@ pnpm add @yaacovCR/transform [email protected]
 
 ## Overview
 
-This library offers:
+This library, primarily through its `transform()` export, provides several helpful functionalities for working with GraphQL results:
 
-- Configurable synchronous leaf value transformers, object field transformers, and path-scoped field transformers for modifying GraphQL results.
-- Mapping from the latest incremental delivery format to the legacy format.
+- **Result Composition:** Combine GraphQL results, including incremental delivery payloads (`@defer`/`@stream`), from multiple downstream GraphQL services into a single unified result. (Note: Composition is currently under development and primarily functional for root fields.)
+- **Result Transformation:** Modify results using configurable transformers based on the leaf type, object field, or specific location within a GraphQL operation.
+- **Legacy Incremental Format Mapping:** Convert results from the modern incremental delivery specification to the legacy format used in earlier `graphql-js` versions.
 
-Note: In the case of multiple transformers, execution is in the above order: first any leaf value transformer is executed, followed by any object field transformer, and then the path-scoped field transformer.
+Notes:
+
+- When multiple transformer types are applied to the same field, they execute in the following order: leaf value transformer -> object field transformer -> path-scoped field transformer.
+
+- A separate `legacyExecuteIncrementally()` export is also available. It leverages the same underlying transformation logic but is specifically designed to provide backwards compatibility for the legacy incremental delivery format when interacting with a single GraphQL service (i.e., without composition).
 
 ## Usage
 
-### Configurable Leaf Transformers
+### Composition of GraphQL Results
 
-Pass `leafTransformers` in a `Transformers` object to `transformResult()`.
+To compose results from multiple GraphQL services, provide a `subschemas` array to `transform()`:
 
 ```ts
-import { transformResult } from '@yaacovCR/transform';
+import { transform } from '@yaacovCR/transform';
 
-const originalResult = await experimentalExecuteIncrementally({
+const transformed = await transform({
   schema,
   document,
-  rootValue,
-  contextValue,
   variableValues,
+  subschemas: [
+    {
+      label: 'Subschema1',
+      subschema: new GraphQLSchema({ ... }),
+      executor: myExecutor1,
+    },
+    {
+      label: 'Subschema2',
+      subschema: new GraphQLSchema({ ... }),
+      executor: myExecutor1,
+    },
+  ],
 });
+```
+
+### Transformation of GraphQL Results
+
+## Configurable Leaf Transformers
 
-const transformed = await transformResult(originalResult, {
+To apply transformations to specific leaf types (scalars or enums), pass `leafTransformers` to `transform()`:
+
+```ts
+import { transform } from '@yaacovCR/transform';
+
+const transformed = await transform({
+  schema,
+  document,
+  variableValues,
+  subschemas,
   leafTransformers: {
     Color: (value) => (value === 'GREEN' ? 'DARK_GREEN' : value),
   },
@@ -65,22 +94,18 @@ type LeafTransformer = (
 ) => unknown;
 ```
 
-### Configurable Object Field Transformers
+## Configurable Object Field Transformers
 
-Pass `objectFieldTransformers` in a `Transformers` object to `transformResult()`, namespaced by type and field.
+To apply transformations to specific fields within object types, pass `objectFieldTransformers` to `transform()`, namespaced by type name and field name:
 
 ```ts
-import { transformResult } from '@yaacovCR/transform';
+import { transform } from '@yaacovCR/transform';
 
-const originalResult = await experimentalExecuteIncrementally({
+const transformed = await transform({
   schema,
   document,
-  rootValue,
-  contextValue,
   variableValues,
-});
-
-const transformed = await transformResult(originalResult, {
+  subschemas,
   objectFieldTransformers: {
     SomeType: {
       someField: (value) => 'transformed',
@@ -101,22 +126,18 @@ type FieldTransformer = (
 ) => unknown;
 ```
 
-### Configurable Path Scoped Field Transformers
+## Configurable Path-Scoped Field Transformers
 
-Pass `pathScopedFieldTransformers` in a `Transformers` object to `transformResult()`, keyed by a period-delimited path to the given field within the operation. (Numeric indices for list fields are simply skipped, reflecting the path within the given operation rather than the result.)
+To apply transformations based on a field's specific location within the operation, pass `pathScopedFieldTransformers` to `transform()`. The keys are period-delimited paths reflecting the field structure in the operation (numeric list indices are omitted).
 
 ```ts
-import { transformResult } from '@yaacovCR/transform';
+import { transform } from '@yaacovCR/transform';
 
-const originalResult = await experimentalExecuteIncrementally({
+const transformed = await transform({
   schema,
   document,
-  rootValue,
-  contextValue,
   variableValues,
-});
-
-const transformed = await transformResult(originalResult, {
+  subschemas,
   objectFieldTransformers: {
     'someType.someFieldNameOrAlias': (value) => 'transformed',
   },
@@ -125,17 +146,39 @@ const transformed = await transformResult(originalResult, {
 
 ### Legacy Incremental Delivery Format
 
-Convert from the the latest incremental delivery format to the legacy format:
+If you need to interact with systems expecting the older incremental delivery format (from `graphql-js` pre-v17), you can enable conversion:
+
+```ts
+import { transform } from '@yaacovCR/transform';
+
+const result = await transform({
+  schema,
+  document,
+  variableValues,
+  subschemas,
+  legacyIncremental: true,
+});
+```
+
+Alternatively, if you are working with a single GraphQL service (no composition) and need the legacy format, the `legacyExecuteIncrementally()` function provides a dedicated interface:
 
 ```ts
 import { legacyExecuteIncrementally } from '@yaacovCR/transform';
 
 const result = await legacyExecuteIncrementally({
   schema,
   document,
+  variableValues,
+  operationName,
   rootValue,
   contextValue,
-  variableValues,
+  fieldResolver,
+  typeResolver,
+  subscribeFieldResolver,
+  perEventExecutor,
+  enableEarlyExecution,
+  hideSuggestions,
+  abortSignal,
 });
 ```
 

src/index.ts

@@ -6,4 +6,4 @@
 
 export { buildTransformationContext } from './transform/buildTransformationContext.js';
 export { legacyExecuteIncrementally } from './transform/legacyExecuteIncrementally.js';
-export { transformResult } from './transform/transformResult.js';
+export { transform } from './transform/transform.js';

src/jsutils/AsyncGeneratorCombinator.ts

@@ -0,0 +1,145 @@
+import { promiseWithResolvers } from './promiseWithResolvers.js';
+import type { SimpleAsyncGenerator } from './SimpleAsyncGenerator.js';
+
+interface WaitingConsumer<T> {
+  resolve: (result: IteratorResult<T>) => void;
+  reject: (error?: unknown) => void;
+}
+
+type GeneratorResult<T> =
+  | {
+      iteratorResult: IteratorResult<T>;
+      error?: never;
+    }
+  | {
+      iteratorResult?: never;
+      error: unknown;
+    };
+
+/**
+ * @internal
+ */
+export class AsyncGeneratorCombinator<T> implements SimpleAsyncGenerator<T> {
+  private _generators: Set<SimpleAsyncGenerator<T>>;
+  private _availableGenerators: Set<SimpleAsyncGenerator<T>>;
+  private _waitingConsumers: Array<WaitingConsumer<T>>;
+  private _availableResults: Array<GeneratorResult<T>>;
+  private _isDone: boolean;
+
+  constructor() {
+    this._generators = new Set();
+    this._availableGenerators = new Set();
+    this._waitingConsumers = [];
+    this._availableResults = [];
+    this._isDone = false;
+  }
+
+  add(generator: SimpleAsyncGenerator<T>): void {
+    this._generators.add(generator);
+    this._availableGenerators.add(generator);
+    if (this._waitingConsumers.length > 0) {
+      this._pollGenerator(generator);
+    }
+  }
+
+  async next(): Promise<IteratorResult<T>> {
+    if (this._isDone) {
+      return { value: undefined, done: true };
+    }
+
+    const queuedResult = this._availableResults.shift();
+    if (queuedResult) {
+      const iteratorResult = queuedResult.iteratorResult;
+      if (iteratorResult) {
+        return iteratorResult;
+      }
+      this._isDone = true;
+      throw queuedResult.error;
+    }
+
+    const { promise, resolve, reject } =
+      promiseWithResolvers<IteratorResult<T>>();
+
+    this._waitingConsumers.push({ resolve, reject });
+
+    this._pollAvailableGenerators();
+
+    return promise;
+  }
+
+  async return(): Promise<IteratorResult<T>> {
+    this._flush();
+    await Promise.all(
+      Array.from(this._generators).map((generator) => generator.return()),
+    );
+    return { value: undefined, done: true };
+  }
+
+  async throw(error?: unknown): Promise<IteratorResult<T>> {
+    this._flush();
+    await Promise.all(
+      Array.from(this._generators).map((generator) => generator.throw(error)),
+    );
+    throw error; /* c8 ignore start */
+  } /* c8 ignore stop */
+
+  [Symbol.asyncIterator](): this {
+    return this;
+  }
+
+  private _pollAvailableGenerators(): void {
+    for (const generator of this._availableGenerators) {
+      this._pollGenerator(generator);
+    }
+  }
+
+  private _pollGenerator(generator: SimpleAsyncGenerator<T>): void {
+    this._availableGenerators.delete(generator);
+    generator.next().then(
+      (iteratorResult) => this._onIteratorResult(generator, iteratorResult),
+      (error: unknown) => this._onError(error),
+    );
+  }
+
+  private _onIteratorResult(
+    generator: SimpleAsyncGenerator<T>,
+    iteratorResult: IteratorResult<T>,
+  ): void {
+    if (iteratorResult.done) {
+      this._generators.delete(generator);
+      if (this._generators.size === 0) {
+        this._flush();
+      }
+    } else if (!this._isDone) {
+      this._availableGenerators.add(generator);
+
+      const waitingConsumer = this._waitingConsumers.shift();
+      if (waitingConsumer) {
+        waitingConsumer.resolve(iteratorResult);
+        if (this._waitingConsumers.length > 0) {
+          this._pollAvailableGenerators();
+        }
+      } else {
+        this._availableResults.push({ iteratorResult });
+      }
+    }
+  }
+
+  private _onError(error: unknown): void {
+    const waitingConsumer = this._waitingConsumers.shift();
+    if (waitingConsumer) {
+      waitingConsumer.reject(error);
+      this._flush();
+    } else {
+      this._availableResults.push({ error });
+    }
+  }
+
+  private _flush(): void {
+    this._isDone = true;
+    this._waitingConsumers.forEach(({ resolve }) =>
+      resolve({ value: undefined, done: true }),
+    );
+    this._waitingConsumers = [];
+  }
+}