graphql-data-generator 0.1.0

package/README.md

@@ -0,0 +1,211 @@
+# graphql-data-generator
+
+A tool to generate objects and operation mocks from a GraphQL schema. Allows
+defining _transforms_ to simplify common variations.
+
+## Example
+
+First generate types and type lists:
+
+```sh
+npx graphql-data-generator --schema src/graphql/schema.graphql --outfile src/util/test/types.ts
+```
+
+Then consume these types and initialize a builder:
+
+```ts
+import { readFileSync } from "node:fs";
+import { init, Patch } from "npm:graphql-data-generator";
+import {
+  Inputs,
+  inputs,
+  Mutation,
+  mutations,
+  queries,
+  Query,
+  Subscription,
+  subscriptions,
+  Types,
+  types,
+} from "./types.ts";
+
+const schema = readFileSync("graphql/schema.graphql", "utf-8");
+
+const scalars = {
+  ID: (typename) => `${typename.toLowerCase()}-0`,
+  String: "",
+};
+
+export const build = init<Query, Mutation, Subscription, Types, Inputs>(
+  schema,
+  queries,
+  mutations,
+  subscriptions,
+  types,
+  inputs,
+  scalars,
+)(() => ({
+  // Can define transforms for objects
+  User: {
+    // `default` automatically applies to all User objects
+    default: { profilePicture: (u) => `https://example.com/${u.id}.png` },
+    // Can invoke with `build.User.withPost()` or `build.User().withPost()`
+    withPost: (_p, post: Patch<Types["Post"]> = {}) => ({
+      posts: { next: post },
+    }),
+  },
+  // Can define transforms for operations
+  CreatePost: {
+    withAuthorId: (_, authorId: string) => ({
+      variables: { input: { authorId } },
+      data: { createPost: { author: { id: authorId } } },
+    }),
+  },
+}));
+```
+
+After which you can build objects and operations in your tests:
+
+```ts
+import { build } from "util/tests/build.ts";
+
+const user1 = build.User().withPost();
+// Can override properties
+const user2 = build.User({ id: "user-2", email: (u) => u.email + "2" });
+// `patch` is a built-in transform while `withPost` was defined above
+const user3 = user1.patch({
+  id: "user-3",
+  // `last` is special property for arrays to modify the last element in the array. If one does not exist it is created
+  // `next` is a special property for arrays to append a new item to the array
+  posts: { last: { author: { id: "user-3" } }, next: {} },
+});
+
+const createPost = build.CreatePost({ data: { createPost: { id: "post-id" } } })
+  .withAuthorId("user-3");
+```
+
+## Patches
+
+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:
+
+```ts
+type Thing = { foo: string };
+type ThingPatch = Patch<Thing>;
+// Can exclude properties
+const patch1: ThingPatch = {};
+// Can specify them
+const patch2: ThingPatch = { foo: "ok" };
+// undefined will be ignored
+const patch3: ThingPatch = { foo: undefined };
+// Can use a function for more dynamic values
+const patch4: ThingPatch = { foo: (prev: Thing) => `${prev.foo}2` };
+```
+
+`Patch` also has added semantics for arrays, including an object notation:
+
+```ts
+type Container = { values: string[] };
+type ContainerPatch = Patch<Container>;
+// Directly set index 1
+const patch1: ContainerPatch = { values: { 1: "ok" } };
+// `last` will modify the last element in the array. If the array is empty,
+// instantiates a new element.
+const patch2: ContainerPatch = { values: { last: "ok" } };
+// `next` instantiates a new element and appends it to the array.
+const patch3: ContainerPatch = { values: { next: "ok" } };
+// `length` can be used to truncate or instantiate new elements
+const patch4: ContainerPatch = { values: { length: 0 } };
+// An array can be directly used. Will truncate extra elements.
+const patch5: ContainerPatch = { values: ["ok"] };
+```
+
+## 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:
+
+Objects:
+
+- `default`: A special transform that is automatically called for all
+  instantations.
+- `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
+
+When defining custom transforms, the `default` transform has special meaning: it
+will be automatically applied as the first aptch to all instances.
+
+## Extra
+
+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
+
+```ts
+const build = init<
+  Query,
+  Mutation,
+  Subscription,
+  Types,
+  Inputs,
+  { optional: boolean }
+>(
+  schema,
+  queries,
+  mutations,
+  subscriptions,
+  types,
+  inputs,
+  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();
+```

package/esm/_dnt.shims.d.ts

@@ -0,0 +1,5 @@
+import { Deno } from "@deno/shim-deno";
+export { Deno } from "@deno/shim-deno";
+export declare const dntGlobalThis: Omit<typeof globalThis, "Deno"> & {
+    Deno: typeof Deno;
+};

package/esm/_dnt.shims.js

@@ -0,0 +1,61 @@
+import { Deno } from "@deno/shim-deno";
+export { Deno } from "@deno/shim-deno";
+const dntGlobals = {
+    Deno,
+};
+export const dntGlobalThis = createMergeProxy(globalThis, dntGlobals);
+function createMergeProxy(baseObj, extObj) {
+    return new Proxy(baseObj, {
+        get(_target, prop, _receiver) {
+            if (prop in extObj) {
+                return extObj[prop];
+            }
+            else {
+                return baseObj[prop];
+            }
+        },
+        set(_target, prop, value) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            baseObj[prop] = value;
+            return true;
+        },
+        deleteProperty(_target, prop) {
+            let success = false;
+            if (prop in extObj) {
+                delete extObj[prop];
+                success = true;
+            }
+            if (prop in baseObj) {
+                delete baseObj[prop];
+                success = true;
+            }
+            return success;
+        },
+        ownKeys(_target) {
+            const baseKeys = Reflect.ownKeys(baseObj);
+            const extKeys = Reflect.ownKeys(extObj);
+            const extKeysSet = new Set(extKeys);
+            return [...baseKeys.filter((k) => !extKeysSet.has(k)), ...extKeys];
+        },
+        defineProperty(_target, prop, desc) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            Reflect.defineProperty(baseObj, prop, desc);
+            return true;
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (prop in extObj) {
+                return Reflect.getOwnPropertyDescriptor(extObj, prop);
+            }
+            else {
+                return Reflect.getOwnPropertyDescriptor(baseObj, prop);
+            }
+        },
+        has(_target, prop) {
+            return prop in extObj || prop in baseObj;
+        },
+    });
+}

package/esm/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/esm/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import * as dntShim from "./_dnt.shims.js";
+import { readFile } from "node:fs";
+import fg from "fast-glob";
+import { parseArgs } from "node:util";
+import { codegen, loadFiles } from "./codegen.js";
+import { formatCode } from "./util.js";
+import process from "node:process";
+const args = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+        schema: { type: "string" },
+        scalars: { type: "string" },
+        operations: { type: "string", multiple: true },
+        scalar: { type: "string", multiple: true },
+        outfile: { type: "string" },
+        useEnums: { type: "boolean", default: false },
+        includeTypenames: { type: "boolean", default: true },
+    },
+}).values;
+const findFirst = async (path) => {
+    for await (const file of fg.stream(path)) {
+        return file.toString();
+    }
+};
+const schemaPath = args.schema
+    ? await findFirst(args.schema)
+    : (await findFirst("**/schema.graphql") ??
+        await findFirst("**/schema.gql") ??
+        await findFirst("**/schema.graphqls"));
+const fail = (reason, code = 1) => {
+    process.stderr.write(reason + "\n");
+    process.exit(code);
+};
+if (!schemaPath) {
+    fail(`Could not locate schema${args.schema ? ` "${args.schema}"` : ", try passing --schema"}`);
+    throw ""; // TS being dumb?
+}
+const operationDirs = args.operations?.map((v) => `${v}`) ?? ["."];
+const [schema, operations] = await loadFiles(schemaPath, operationDirs);
+const defaultScalars = {
+    Int: "number",
+    Float: "number",
+    String: "string",
+    Boolean: "boolean",
+    ID: "string",
+};
+const scalars = { ...defaultScalars };
+if (args.scalars) {
+    readFile;
+    Object.assign(scalars, JSON.parse(await dntShim.Deno.readTextFile(args.scalars)));
+}
+if (args.scalar) {
+    for (const kv of args.scalar) {
+        const [key, value] = `${kv}`.split(":");
+        if (!value) {
+            fail("Invalid --scalar argument. Pass as a key-value pair like --scalar=key:value");
+        }
+        scalars[key] = value;
+    }
+}
+try {
+    const file = await formatCode(codegen(schema, operations, {
+        useEnums: args.useEnums,
+        includeTypenames: args.includeTypenames,
+        scalars,
+    }));
+    if (args.outfile)
+        await dntShim.Deno.writeTextFile(args.outfile, file);
+    else
+        console.log(file);
+}
+catch (err) {
+    const message = err instanceof Error ? err.message : `${err}`;
+    if (message.startsWith("Could not find scalar")) {
+        const scalar = message.match(/'([^']*)'/)?.[1];
+        fail(`${message}. Try passing --scalars=scalars.json or --scalar=${scalar ?? "scalar"}:string, replacing string with the TypeScript type of the scalar.`);
+    }
+    fail(err instanceof Error ? err.message : err);
+}

package/esm/codegen.d.ts

@@ -0,0 +1,12 @@
+export declare const codegen: (schema: string, files: {
+    path: string;
+    content: string;
+}[], { useEnums, scalars, includeTypenames }?: {
+    useEnums?: boolean;
+    scalars?: Record<string, string | undefined>;
+    includeTypenames?: boolean;
+}) => string;
+export declare const loadFiles: (schemaPath: string, operationDirs: string[]) => Promise<[schema: string, operations: {
+    path: string;
+    content: string;
+}[]]>;