graphql-data-generator 0.3.0-alpha.8 → 0.3.0

package/README.md

@@ -1,11 +1,34 @@
 # graphql-data-generator
 
-A tool to generate objects and operation mocks from a GraphQL schema. Allows
-defining _transforms_ to simplify common variations.
+graphql-data-generator is a testing utility for generating GraphQL data objects
+and operation mocks from your schema. It simplifies test setup by combining
+generated types, patching mechanisms, and customizable **transforms** for common
+object variations. It also includes helpers for asserting mock coverage in
+tests.
 
-## Example
+- [Example](#example-setting-up-a-builder-and-building-objects)
+- [CLI options](#cli-options)
+- [Patches](#patches)
+- [Transforms](#transforms)
+- [Testing](#testing)
+- [Extra properties](#extra)
 
-First generate types and type lists:
+### Key Concepts
+
+- **Patch:** Like a `DeepPartial`, but with functions and array helpers.
+- **Transform:** Predefined reusable patches.
+- **MockedProvider:** A helper that wraps `@apollo/client`'s `MockedProvider`
+  with built-in assertions and better stack traces.
+
+## Example: Setting up a builder and building objects
+
+### Step 1: Generating types
+
+To use `graphql-data-generator` with TypeScript, you must pregenerated some a
+types file. This file can optionally include your entire schema types, but at
+minimal includes an index of types, inputs, and operations. You can generated
+the types via the following CLI command or by plugging `@graphql-codegen` (see
+docs).
 
 ```sh
 npx graphql-data-generator --schema src/graphql/schema.graphql --outfile src/util/test/types.ts
@@ -86,31 +109,19 @@ const createPost = build.CreatePost({ data: { createPost: { id: "post-id" } } })
 
 ## CLI options
 
-- `banner=file|copy`: Places copy at the beginning of the generated output. If a
-  file path is detected, will use the contents of the file.
-- `enums=[enums|literals|none|import:*]`: Describes how enums are generated.
-  - `enums`: Use TypeScript enum. E.g., `enum Status { Draft, Submitted }`
-  - `literals`: Use string literals. E.g.,
-    `type Status = "Draft" | "Submitted";`
-  - `none`: Skip generating of enums all together.
-  - `import:file` Import enums from the provided path. E.g.,
-    `import { Status } from "file";`
-- `exports=[operations|types]`: Toggle exporting of operations and/or types.
-- `namingConvention=NamingConvention`: Specify a
-  [`NamingConvention`](https://the-guild.dev/graphql/codegen/docs/config-reference/naming-convention)
-  for generated types. Defaults to `change-case-all#pascalCase` if using the
-  plugin, otherwise defaults to `keep`.
-- `notypenames`: Toggle automatic inclusion of `__typename`.
-- `operations=dir`: Restrict generation of operations to a specific directory.
-  Can be used multiple times for multiple directories.
-- `outfile=file`: Switch output to right to `file` instead of stdout.
-- `scalar=Scalar:Type`: Specify the type of an individual scalar. E.g.,
-  `type Scalar = Type;`
-- `scalars=file.json`: Specify multiple scalars from a json file.
-- `schema=file`: Specify the GraphQL schema file to use.
-- `typesFile=file`: Specify file generated by
-  [`@graphql-codegen`](https://the-guild.dev/graphql/codegen) to import types
-  from.
+| Option             | Value                                               | Description                                                                                                            |
+| ------------------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `banner`           | `<filepath>` or `<string>`                          | Places copy at the beginning of the generated output.                                                                  |
+| `enums`            | `enums`, `literals`, `none`, or `import:<filepath>` | Controls how enums are generated.                                                                                      |
+| `exports`          | `operations` or `types`                             | Toggles exporting operations and/or types.                                                                             |
+| `namingConvention` | `NamingConvention`                                  | Sets the [naming convention](https://the-guild.dev/graphql/codegen/docs/config-reference/naming-convention) for types. |
+| `notypenames`      |                                                     | Disables automatic inclusion of `__typename`.                                                                          |
+| `operations`       | `<dir>`                                             | Limits operation generation to a directory (repeatable).                                                               |
+| `outfile`          | `<file>`                                            | Writes output to `file` instead of stdout.                                                                             |
+| `scalar`           | `<Scalar>:<Type>`                                   | Maps a scalar to a TypeScript type.                                                                                    |
+| `scalars`          | `<json filepath>`                                   | Maps scalars from a JSON file.                                                                                         |
+| `schema`           | `<filepath>`                                        | Specifies the schema file to use.                                                                                      |
+| `typesFile`        | `<filepath>`                                        | Uses types generated by [`@graphql-codegen`](https://the-guild.dev/graphql/codegen) instead of generating them here.   |
 
 ## @graphql-codegen plugin
 
@@ -158,7 +169,7 @@ file can then be consumed by a `build` script similar to the above example.
 
 A `patch` is similar to a `DeepPartial` with a few extensions. First, functions
 can be passed instead of literal properties. These functions will be invoked
-during instantiation and will receieve the previous host value as a property:
+during instantiation and will receive the previous host value as a property:
 
 ```ts
 type Thing = { foo: string };
@@ -173,6 +184,8 @@ const patch3: ThingPatch = { foo: undefined };
 const patch4: ThingPatch = { foo: (prev: Thing) => `${prev.foo}2` };
 ```
 
+### Arrays
+
 `Patch` also has added semantics for arrays, including an object notation:
 
 ```ts
@@ -191,38 +204,93 @@ const patch4: ContainerPatch = { values: { length: 0 } };
 const patch5: ContainerPatch = { values: ["ok"] };
 ```
 
+### `clear`
+
+In rare circumstances, you may want to patch a nullable array input field back
+to `undefined`. Since `undefined` is purposefully ignored as a patch value and
+`null` is semantically different, the `clear` value exported from
+`graphql-data-generator` can be used revert the field back to `undefined`.
+
 ## Transforms
 
-`graphql-data-generator` creates objects and operations by applying **patches**
-in sequence. A **patch** is similar to a `DeepPartial`, but supports functions
-for each property and has . Transforms are a mechanism to define shorthands for
-common patches for particular objects or operations. There are several built in
-transforms:
+Transforms make it easy to define reusable **patches** for objects and
+operations. For example, if you frequently need to build a User with a post, or
+a `CreatePost` mutation with a pre-filled author, you can encode that logic into
+a transform like `withPost` or `withAuthorId`. This keeps your test setup
+concise and consistent. There are several built in transforms:
 
 Objects:
 
 - `default`: A special transform that is automatically called for all
-  instantations.
+  instantiations
 - `patch`: Accepts a list of patches
 
 Operations:
 
 - `patch`: Accepts a list of patches
-- `variables`: Accepts an operation variable patch
-- `data`: Accepts an operation data patch
+- `variables`: Accepts an operation variable patch. Useful as an alternative to
+  `patch` if you don't need to specify `data`
+- `data`: Accepts an operation data patch. Useful as an alternative to `patch`
+  if you don't need to specify `variables`
 
 When defining custom transforms, the `default` transform has special meaning: it
-will be automatically applied as the first aptch to all instances.
+will be automatically applied as the first patch to all instances.
+
+## Testing
+
+`graphql-data-generator` also provides test utilities that work seamlessly with
+`@apollo/client` and `@testing-library/react`. These helpers ensure all GraphQL
+requests are properly mocked and all mocks are fully consumed.
+
+```ts
+import { MockedProvider, waitForMocks } from "graphql-data-generator";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { build } from "util/tests/build.ts";
+
+import Users from ".";
+
+it("my test", async () => {
+  render(<Users />, {
+    wrapper: ({ children }) => (
+      <MockedProvider
+        mocks={[
+          build.users({ data: { users: [{ id: "user-0", name: "User 0" }] } }),
+          build.user({ variables: { id: "user-0" } }),
+        ]}
+        stack={new Error("Render").stack} // Useful if render is wrapped
+      >
+        {children}
+      </MockedProvider>
+    ),
+  });
+  await waitForMocks("users");
+  await userEvent.click(screen.getByText("User 0"));
+});
+```
+
+The `stack` property of `MockedProvider` will be appended to errors in which
+mocks are missing, uncalled, or have mismatched variables.
+
+When transitioning to using `graphql-data-generator`'s `MockedProvider`, it may
+be helpful to disable asserting all requests are mocked. A helper,
+`allowMissingMocks`, exists to disable these assertions and can be called before
+any tests.
+
+If you are using an old version of `@apollo/client`, missing refetch requests
+will emit warnings instead of errors. You can use `failRefetchWarnings` to
+convert these warnings to errors.
 
 ## Extra
 
-The `init` function supports a 6th optional generic parameter, Extra, which
+The `init` function supports a 6th optional generic parameter, `Extra`, which
 allows defining extra properties for operation mocks, passable in operation
 patches. This is helpful to support extra Apollo-related properties or custom
 logic. Extra properties will always be optional in patches and the final object
 and will not be patched in but simply merged, such as by `Object.assign`.
 
-### Example: Adding an extra optional property to bypass an assertion a mock is used
+### Example: Adding an extra property for your own use
 
 ```ts
 const build = init<
@@ -231,7 +299,7 @@ const build = init<
   Subscription,
   Types,
   Inputs,
-  { optional: boolean }
+  { internal: boolean }
 >(
   schema,
   queries,
@@ -242,40 +310,5 @@ const build = init<
   scalars,
 )(() => ({}));
 
-build.CreatePost({ optional: true }).optional; // true
-```
-
-## finalizeOperation
-
-The `init`'s final parmaeter, `options`, supports a `finalizeOperation` key.
-This is used as final step when building an operation and acts as a generic
-transform on the final mock itself, which can be useful to attach spies or when
-building interactivity with other GQL tools.
-
-### Exmaple: Enforcing a mock is used in Apollo & Jest
-
-```ts
-const build = init<Query, Mutation, Subscription, Types, Inputs>(
-  schema,
-  queries,
-  mutations,
-  subscriptions,
-  types,
-  inputs,
-  scalars,
-  {
-    finalizeOperation: (op) => {
-      const fn = Object.assign(
-        jest.fn(() => op.result),
-        op.result,
-      ) as typeof op["result"];
-      op.result = fn;
-      return op;
-    },
-  },
-)(() => ({}));
-
-const createPost = build.CreatePost();
-// ...
-expect(createPost.result).toHaveBeenCalled();
+build.CreatePost({ internal: true }).internal; // true
 ```

package/esm/cli.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import "./_dnt.polyfills.js";
 import * as dntShim from "./_dnt.shims.js";
 import { readFile } from "node:fs";
 import fg from "fast-glob";

package/esm/index.js

@@ -1,5 +1,4 @@
-import "./_dnt.polyfills.js";
 export { init } from "./init.js";
 export { codegen } from "./codegen.js";
-export { proxy } from "./proxy.js";
+export { clear, operation, proxy } from "./proxy.js";
 export { formatCode, toObject } from "./util.js";

package/esm/init.js

@@ -1,13 +1,24 @@
+import * as dntShim from "./_dnt.shims.js";
+import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
 import { Kind, parse } from "graphql";
-import { dirname, join } from "node:path";
 import { gqlPluckFromCodeStringSync } from "@graphql-tools/graphql-tag-pluck";
 import { operation, proxy, withGetDefaultPatch } from "./proxy.js";
 import { toObject } from "./util.js";
+import { dirname, resolve } from "node:path";
+globalThis.require ??= createRequire(dntShim.Deno.cwd());
 const files = {};
-const loadFile = (path) => files[path] || (files[path] = readFileSync(path, "utf-8").replace(/#import "(.*)"/, (_, fragmentPath) => loadFile(fragmentPath.startsWith(".")
-    ? join(dirname(path), fragmentPath)
-    : new URL(fragmentPath, import.meta.url).href)));
+const loadFile = (path) => {
+    if (files[path])
+        return files[path];
+    const raw = files[path] = readFileSync(path, "utf-8");
+    const imports = Array.from(raw.matchAll(/#import "(.*)"/gm), ([, importPath]) => loadFile(require.resolve(importPath.startsWith(".")
+        ? resolve(dntShim.Deno.cwd(), dirname(path), importPath)
+        : importPath, { paths: [dntShim.Deno.cwd()] })));
+    if (!imports.length)
+        return raw;
+    return [raw, ...imports].join("\n\n");
+};
 const getOperationContentMap = {};
 const getOperationContent = (path, operationName) => {
     const existing = getOperationContentMap[path];
@@ -23,7 +34,7 @@ const getOperationContent = (path, operationName) => {
             const document = parse(s);
             const firstOp = document.definitions.find((d) => d.kind === Kind.OPERATION_DEFINITION);
             if (!firstOp)
-                throw new Error(`Cound not find an operation in ${path}`);
+                throw new Error(`Could not find an operation in ${path}`);
             return [firstOp.name?.value, document];
         }));
     }
@@ -32,7 +43,16 @@ const getOperationContent = (path, operationName) => {
     }
     return getOperationContent(path, operationName);
 };
-// - Types will be suffixed with their type: fooQuery or fooMutation
+/**
+ * Initialize the data builder.
+ * @param schema The plain text of your schema.
+ * @param queries List of queries exported from generated types.
+ * @param mutations List of mutations exported from generated types.
+ * @param subscriptions List of subscriptions exported from generated types.
+ * @param types List of types exported from generated types.
+ * @param inputs List of types exported from generated types.
+ * @param scalars A mapping to generate scalar values. Function values will be invoked with their `__typename`.
+ */
 export const init = (schema, queries, mutations, subscriptions, types, inputs, scalars, options) => (fn) => {
     const doc = parse(schema);
     const build = {};
@@ -157,10 +177,13 @@ export const init = (schema, queries, mutations, subscriptions, types, inputs, s
             if (transforms[name] && "default" in transforms[name]) {
                 patches = [transforms[name].default, ...patches];
             }
-            const { request: { query: parsedQuery, ...request }, ...raw } = operation(doc.definitions, scalars, query, ...patches);
-            const mock = toObject({
-                request: { ...request },
-                ...raw,
+            const { mock, parsedQuery } = withGetDefaultPatch((type) => transforms[type]?.default, () => {
+                const { request: { query: parsedQuery, ...request }, ...raw } = operation(doc.definitions, scalars, query, ...patches);
+                const mock = toObject({
+                    request: { ...request },
+                    ...raw,
+                });
+                return { mock, parsedQuery };
             });
             mock.request.query = parsedQuery;
             Error.captureStackTrace(mock, builder);

package/esm/jest.js

@@ -1,30 +1,52 @@
-import "./_dnt.polyfills.js";
 import * as dntShim from "./_dnt.shims.js";
 import React, { useMemo } from "react";
 import { ApolloLink, useApolloClient, } from "@apollo/client";
 import { onError } from "@apollo/client/link/error";
-import { MockedProvider, MockLink, } from "@apollo/client/testing";
+import { MockedProvider as ApolloMockedProvider, MockLink, } from "@apollo/client/testing";
 import { waitFor } from "@testing-library/dom";
 import { Kind, print } from "graphql";
 import { diff as jestDiff } from "jest-diff";
+import "@testing-library/react/dont-cleanup-after-each";
+import { cleanup } from "@testing-library/react";
 let currentSpecResult;
 jasmine.getEnv().addReporter({
     specStarted: (result) => currentSpecResult = result,
 });
+let _skipCleanupAfterEach = false;
+/**
+ * `@testing-library/react` automatically unmounts React trees that were mounted
+ * with render after each test, which `graphql-data-generator` hijacks to ensure
+ * cleanup is done after all mocks are consumed. Invoke this functions to
+ * disable automatic cleanup.
+ * @param value
+ */
+export const skipCleanupAfterEach = (value = false) => {
+    _skipCleanupAfterEach = value;
+};
 const afterTest = [];
 afterEach(async () => {
     const hooks = afterTest.splice(0);
     for (const hook of hooks)
         await hook();
+    if (!_skipCleanupAfterEach)
+        cleanup();
 });
 const diff = (a, b) => jestDiff(a, b, { omitAnnotationLines: true })
     ?.replace(/\w+ \{/g, "{") // Remove class names
     .replace(/\w+ \[/g, "["); // Remove array class names
+const getOperationDefinition = (document) => document.definitions.find((d) => d.kind === Kind.OPERATION_DEFINITION);
+const getOperationType = (operation) => getOperationDefinition(operation.query)?.operation ??
+    "<unknown operation type>";
+const getOperationName = (document) => getOperationDefinition(document)?.name?.value;
+const getOperationInfo = (document) => {
+    const def = getOperationDefinition(document);
+    return {
+        name: def?.name?.value ?? "<unknown operation>",
+        operationType: def?.operation ?? "<unknown operation type>",
+    };
+};
 const getErrorMessage = (operation, mockLink) => {
-    const definition = operation.query.definitions[0];
-    const operationType = definition.kind === "OperationDefinition"
-        ? definition.operation
-        : "<unknown operation type>";
+    const operationType = getOperationType(operation);
     const key = JSON.stringify({
         query: print(operation.query),
     });
@@ -79,51 +101,89 @@ const AutoWatch = ({ mocks }) => {
             client.watchQuery(mock.request);
     return null;
 };
+let lastMocks = [];
+// deno-lint-ignore ban-types
+const getStack = (to) => {
+    const obj = {};
+    Error.captureStackTrace(obj, to);
+    return obj.stack;
+};
+const _waitForMocks = async (mocks, cause) => {
+    for (const mock of mocks) {
+        if (mock.optional || mock.error)
+            continue;
+        await waitFor(() => {
+            if (currentSpecResult.failedExpectations.length)
+                return;
+            if (mock.result.mock.calls.length === 0) {
+                const { name, operationType } = getOperationInfo(mock.request.query);
+                const err = new Error(`Expected to have used ${operationType} ${name}${mock.request.variables
+                    ? ` with variables ${dntShim.Deno.inspect(mock.request.variables, {
+                        depth: Infinity,
+                        colors: true,
+                    })}`
+                    : ""}`);
+                if (mock.stack) {
+                    err.stack = `${mock.stack}${cause ? `\nCaused by: ${cause}` : ""}`;
+                }
+                else if (cause)
+                    err.stack = cause;
+                throw err;
+            }
+        });
+    }
+};
+/**
+ * Wait for mocks to have been used.
+ * @param mock If `undefined`, waits for all mocks. If a number, waits fort he first `mocks` mocks. If a string, waits for all mocks up until and including that mock.
+ * @param offset If `mocks` is a string, grabs the `offset`th mock of that name (e.g., the third `getReport` mock)
+ */
+export const waitForMocks = async (mock = lastMocks.length, offset = 0) => {
+    if (typeof mock === "string") {
+        const matches = lastMocks.map((m, i) => [m, i])
+            .filter(([m]) => getOperationName(m.request.query) === mock);
+        if (matches.length <= offset) {
+            fail({
+                name: "Error",
+                message: `Expected mock ${mock} to have been mocked`,
+                stack: getStack(waitForMocks),
+            });
+        }
+        expect(matches.length).toBeGreaterThan(offset);
+        mock = matches[offset][1] + 1;
+    }
+    await _waitForMocks(lastMocks.slice(0, mock), getStack(waitForMocks));
+};
 /**
  * A wrapper for `@apollo/client/testing`, this component will assert all
  * requests have matching mocks and all defined mocks are used unless marked
  * `optional`.
  */
-export const MockProvider = ({ mocks, stack: renderStack, children, link: passedLink, ...rest }) => {
+export const MockedProvider = ({ mocks, stack: renderStack, children, link: passedLink, ...rest }) => {
     const observableMocks = useMemo(() => {
         const observableMocks = mocks.flatMap((m) => [
-            {
+            typeof m.result === "function" && "mock" in m.result ? m : {
                 ...m,
                 stack: m.stack,
-                result: Object.assign(jest.fn(() => m.result), m.result),
+                result: Object.assign(jest.fn((vars) => typeof m.result === "function" ? m.result(vars) : m.result), m.result),
             },
             ...(m.watch
                 ? [{
                         ...m,
                         stack: m.stack,
-                        result: Object.assign(jest.fn(() => m.result), m.result),
+                        result: typeof m.result === "function" && "mock" in m.result
+                            ? m.result
+                            : Object.assign(jest.fn((vars) => typeof m.result === "function" ? m.result(vars) : m.result), m.result),
                         watch: false,
+                        // TODO: this might be dependent on Apollo version or refetch method,
+                        // ideally should be asserted when we can (maybe when
+                        // _failRefetchWarnings is false?)
+                        optional: true,
                     }]
                 : []),
         ]);
-        afterTest.push(async () => {
-            if (currentSpecResult.failedExpectations.length)
-                return;
-            for (const mock of observableMocks) {
-                if (mock.optional || mock.error)
-                    continue;
-                await waitFor(() => {
-                    if (currentSpecResult.failedExpectations.length)
-                        return;
-                    if (mock.result.mock.calls.length === 0) {
-                        const operation = mock.request.query.definitions.find((d) => d.kind === Kind.OPERATION_DEFINITION);
-                        const err = new Error(`Expected to have used ${operation?.operation} ${operation?.name?.value}${mock.request.variables
-                            ? ` with variables ${dntShim.Deno.inspect(mock.request.variables, {
-                                depth: Infinity,
-                                colors: true,
-                            })}`
-                            : ""}`);
-                        err.stack = mock.stack ?? renderStack ?? err.stack;
-                        throw err;
-                    }
-                }, { onTimeout: (e) => e });
-            }
-        });
+        lastMocks = observableMocks;
+        afterTest.push(() => _waitForMocks(lastMocks, renderStack));
         return observableMocks;
     }, [mocks]);
     const link = useMemo(() => {
@@ -131,14 +191,18 @@ export const MockProvider = ({ mocks, stack: renderStack, children, link: passed
         mockLink.showWarnings = false;
         const errorLoggingLink = onError(({ networkError, operation }) => {
             if (_allowMissingMocks ||
-                !networkError?.message.includes("No more mocked responses"))
+                !networkError?.message?.includes("No more mocked responses"))
                 return;
             const { message, stack: altStack } = getErrorMessage(operation, mockLink);
             try {
                 networkError.message = message;
-                const stack = altStack ?? renderStack;
-                if (stack)
-                    networkError.stack = stack;
+                if (altStack) {
+                    networkError.stack = renderStack
+                        ? `${altStack}\nCaused By: ${renderStack}`
+                        : altStack;
+                }
+                else if (renderStack)
+                    networkError.stack = renderStack;
                 fail({ name: "Error", message, stack: networkError.stack });
             }
             catch {
@@ -154,14 +218,13 @@ export const MockProvider = ({ mocks, stack: renderStack, children, link: passed
     if (_failRefetchWarnings) {
         const oldWarn = console.warn.bind(console.warn);
         console.warn = (message, operation, ...etc) => {
-            if (message !==
-                'Unknown query named "%s" requested in refetchQueries in options.include array') {
+            if (typeof message !== "string" ||
+                !message.match(/Unknown query named.*refetchQueries/))
                 return oldWarn(message, operation, ...etc);
-            }
             try {
                 fail({
                     name: "Error",
-                    message: `Expected query ${operation} requested in refetchQueries options.include array to have bene mocked`,
+                    message: `Expected query ${operation} requested in refetchQueries options.include array to have been mocked`,
                     stack: renderStack,
                 });
             }
@@ -173,7 +236,7 @@ export const MockProvider = ({ mocks, stack: renderStack, children, link: passed
             console.warn = oldWarn;
         });
     }
-    return (React.createElement(MockedProvider, { ...rest, link: link },
+    return (React.createElement(ApolloMockedProvider, { ...rest, link: link },
         React.createElement(React.Fragment, null,
             React.createElement(AutoWatch, { mocks: observableMocks }),
             children)));

package/esm/plugin.cjs

@@ -1,4 +1,4 @@
-import "./_dnt.polyfills.js";
+"use strict";
 module.exports = {
     async plugin(schema, documents, config) {
         const { codegen } = await import("./codegen.js");