graphql-buddy 0.0.0

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "graphql-buddy",
+  "version": "0.0.0",
+  "type": "module",
+  "license": "MIT",
+  "author": "Hunter John Larco",
+  "description": "CLI tools for manipulating graphql // designed for build system tooling",
+  "bin": {
+    "graphql-buddy": "./dist/cli.js"
+  },
+  "keywords": [
+    "graphql",
+    "parse",
+    "build",
+    "build-tool",
+    "bundler"
+  ],
+  "main": "./dist/api.js",
+  "types": "./dist/api.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hunterlarco/graphql-buddy.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hunterlarco/graphql-buddy/issues"
+  },
+  "funding": "https://github.com/sponsors/hunterlarco",
+  "scripts": {
+    "build": "pnpm run typecheck && pnpm run bundle",
+    "typecheck": "tsc --noEmit",
+    "bundle": "tsup",
+    "start": "pnpm run build && node dist/cli.js",
+    "test": "vitest run",
+    "test:dev": "vitest dev",
+    "format": "pnpm run format:eslint && pnpm run format:prettier",
+    "format:prettier": "prettier . --write",
+    "format:eslint": "eslint . --fix",
+    "lint": "concurrently npm:lint:*",
+    "lint:prettier": "prettier . --check",
+    "lint:eslint": "eslint . --max-warnings=0"
+  },
+  "dependencies": {
+    "@commander-js/extra-typings": "14.0.0",
+    "@graphql-tools/graphql-file-loader": "8.1.2",
+    "@graphql-tools/load": "8.1.2",
+    "@graphql-tools/utils": "10.9.1",
+    "commander": "14.0.1",
+    "glob": "11.0.3",
+    "graphql": "16.11.0",
+    "stringify-object": "6.0.0",
+    "tslib": "2.8.1"
+  },
+  "devDependencies": {
+    "@eslint/compat": "1.4.0",
+    "@eslint/js": "9.36.0",
+    "@types/node": "24.5.2",
+    "@types/stringify-object": "4.0.5",
+    "concurrently": "9.2.1",
+    "eslint": "9.36.0",
+    "eslint-import-resolver-typescript": "4.4.4",
+    "eslint-plugin-import": "2.32.0",
+    "jiti": "2.6.0",
+    "prettier": "3.6.2",
+    "tsup": "8.5.0",
+    "typescript": "5.9.2",
+    "typescript-eslint": "8.44.1",
+    "vitest": "3.2.4"
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+onlyBuiltDependencies:
+  - esbuild
+  - unrs-resolver

package/src/api/commands/bundle.test.ts

@@ -0,0 +1,138 @@
+import * as nodePath from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import * as bundle from './bundle';
+
+describe(`bundle`, () => {
+  it(`handles a single file with no extra deps or aliases.`, async () => {
+    expect(
+      await bundle.bundle({
+        schema: {
+          files: [`*.graphql`],
+          base: nodePath.resolve(
+            __dirname,
+            `../../../test_fixtures/single_file`,
+          ),
+        },
+      }),
+    ).toStrictEqual(
+      `
+type Query {
+  foo: Foo
+  bar: Bar
+}
+
+type Foo {
+  id: ID!
+  displayName: String
+}
+
+type Bar {
+  id: ID!
+  foo: Foo
+}
+`.trim(),
+    );
+  });
+
+  it(`handles multiple files with no extra deps or aliases.`, async () => {
+    expect(
+      await bundle.bundle({
+        schema: {
+          files: [`*.graphql`],
+          base: nodePath.resolve(
+            __dirname,
+            `../../../test_fixtures/multiple_files`,
+          ),
+        },
+      }),
+    ).toStrictEqual(
+      `
+type Bar {
+  baz: Baz
+}
+
+type Baz {
+  dateCreated: DateTime!
+}
+
+scalar DateTime
+
+type Foo {
+  id: ID!
+  name: String
+  bar: Bar
+}
+
+type Mutation {
+  addFoo(foo: FooInput!): Foo!
+}
+
+input FooInput {
+  name: String
+}
+
+type Query {
+  allFoo: [Foo!]!
+}
+`.trim(),
+    );
+  });
+
+  it(`shakes extra deps from a single file.`, async () => {
+    expect(
+      await bundle.bundle({
+        schema: {
+          files: [`*.graphql`],
+          base: nodePath.resolve(
+            __dirname,
+            `../../../test_fixtures/single_file_with_extra_deps`,
+          ),
+        },
+      }),
+    ).toStrictEqual(
+      `
+type Query {
+  foo: Foo
+}
+
+type Mutation {
+  addFooToBar(displayName: String!): Bar
+}
+
+type Subscription {
+  foo: FooEvent
+}
+
+type Foo {
+  id: ID!
+  displayName: String
+}
+
+type Bar {
+  id: ID!
+  foo: Foo
+}
+
+type FooEvent {
+  foo: Foo!
+}
+`.trim(),
+    );
+  });
+
+  it(`throws for invalid schema.`, async () => {
+    await expect(
+      bundle.bundle({
+        schema: {
+          files: [`*.graphql`],
+          base: nodePath.resolve(
+            __dirname,
+            `../../../test_fixtures/missing_scalar`,
+          ),
+        },
+      }),
+    ).rejects.toThrowError(`Unknown type "DateTime"`);
+  });
+});

package/src/api/commands/bundle.ts

@@ -0,0 +1,29 @@
+import * as graphqlToolsUtils from '@graphql-tools/utils';
+import * as graphql from 'graphql';
+
+import * as shared from '../shared';
+
+export type BundleOptions = {
+  schema: shared.LoadSchemaOptions;
+
+  // Defaults to true.
+  shake?: boolean | null;
+};
+
+/**
+ * Bundles multiple schema together into a single file.
+ *
+ * @param options - Bundle options.
+ *
+ * @returns The merged schema as text.
+ */
+export const bundle = async (options: BundleOptions): Promise<string> => {
+  const shake = options.shake ?? true;
+
+  let schema = await shared.loadSchema(options.schema);
+  if (shake) {
+    schema = graphqlToolsUtils.pruneSchema(schema);
+  }
+
+  return graphql.printSchema(schema);
+};

package/src/api/commands/index.ts

@@ -0,0 +1,2 @@
+export * from './bundle';
+export * from './validate';

package/src/api/commands/validate.test.ts

@@ -0,0 +1,35 @@
+import * as nodePath from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import * as validate from './validate';
+
+describe(`validate`, () => {
+  it(`creates a validation stamp when validation passes.`, async () => {
+    await expect(
+      validate.validate({
+        schema: {
+          files: [`*.graphql`],
+          base: nodePath.resolve(
+            __dirname,
+            `../../../test_fixtures/multiple_files`,
+          ),
+        },
+      }),
+    ).resolves.toStrictEqual(expect.any(String));
+  });
+
+  it(`throws for invalid schema.`, async () => {
+    await expect(
+      validate.validate({
+        schema: {
+          files: [`*.graphql`],
+          base: nodePath.resolve(
+            __dirname,
+            `../../../test_fixtures/missing_scalar`,
+          ),
+        },
+      }),
+    ).rejects.toThrowError(`Unknown type "DateTime"`);
+  });
+});

package/src/api/commands/validate.ts

@@ -0,0 +1,49 @@
+import * as stringifyObject from 'stringify-object';
+
+import * as shared from '../shared';
+
+export type ValidateOptions = {
+  schema: shared.LoadSchemaOptions;
+};
+
+/**
+ * Validates that the provided GraphQL schema contain valid syntax and have no
+ * unknown symbols.
+ *
+ * @param options - Validate options.
+ *
+ * @returns If validation is successful, returns a validation stamp: a text blob
+ *   describing the successful outcome and options used during validation. This
+ *   is often useful in build systems where a build step *must* emit a file. If
+ *   validation fails, a runtime error will be thrown.
+ */
+export const validate = async (options: ValidateOptions): Promise<string> => {
+  // We manually normalize the `LoadSchemaOptions` so that we can write the most
+  // accurate data in our validation stamp. For example, normalization expands
+  // globs and resolves absolute paths. These are critical steps to ensure the
+  // validation stamp describes without ambiguity which schema were loaded.
+  const normalizedSchemaOptions = await shared.normalizeLoadSchemaOptions(
+    options.schema,
+  );
+
+  await shared.loadSchema(normalizedSchemaOptions);
+
+  return createValidationStamp({
+    ...options,
+    schema: normalizedSchemaOptions,
+  });
+};
+
+const createValidationStamp = (
+  options: Omit<ValidateOptions, `schema`> & {
+    schema: shared.NormalizedLoadSchemaOptions;
+  },
+): string =>
+  stringifyObject.default(
+    { options, outcome: { valid: true } },
+    {
+      indent: `  `,
+      filter: (container, property) =>
+        !(container === options.schema && property === `normalized`),
+    },
+  );

package/src/api/index.ts

@@ -0,0 +1,2 @@
+export * from './commands';
+export * from './shared';

package/src/api/shared/index.ts

@@ -0,0 +1 @@
+export * from './loadSchema';

package/src/api/shared/loadSchema.ts

@@ -0,0 +1,88 @@
+import * as nodeFs from 'node:fs/promises';
+import * as nodePath from 'node:path';
+
+import * as graphqlFileLoader from '@graphql-tools/graphql-file-loader';
+import * as graphqlLoad from '@graphql-tools/load';
+import * as glob from 'glob';
+
+import type * as graphql from 'graphql';
+
+export type LoadSchemaOptions = {
+  normalized?: false | null;
+
+  // Relative paths will be resolved using `base`.
+  //
+  // Also accepts glob patterns.
+  files: Array<string>;
+
+  // Directory from which `files` are resolved.
+  //
+  // Defaults to `process.cwd()`.
+  base?: string | null;
+
+  // See @graphql-tools/import#PathAliases
+  //
+  // Note that relative paths will be resolved relative to `base` to maintain
+  // parity with `files`.
+  pathAliases?: Map<string, string> | null;
+};
+
+export const loadSchema = async (
+  options: LoadSchemaOptions | NormalizedLoadSchemaOptions,
+): Promise<graphql.GraphQLSchema> => {
+  const { files, pathAliases } = options.normalized
+    ? options
+    : await normalizeLoadSchemaOptions(options);
+
+  // @graphql-tools/graphql-file-loader silently skips input files which are not
+  // found. I suspect this is so that it can delegate missing inputs to other
+  // loaders. For our purposes, this is undesirable because we want to inform
+  // clients if expected inputs are missing. For that reason, we manually
+  // validate that the files exist first.
+  for (const file of files) {
+    try {
+      await nodeFs.access(file, nodeFs.constants.F_OK);
+    } catch {
+      throw new Error(`File does not exist: ${file}`);
+    }
+  }
+
+  return graphqlLoad.loadSchema(files, {
+    loaders: [new graphqlFileLoader.GraphQLFileLoader()],
+    pathAliases: {
+      mappings: Object.fromEntries(pathAliases.entries()),
+    },
+  });
+};
+
+export type NormalizedLoadSchemaOptions = {
+  normalized: true;
+
+  // Absolute paths.
+  files: Array<string>;
+
+  // See @graphql-tools/import#PathAliases
+  pathAliases: Map<string, string>;
+};
+
+export const normalizeLoadSchemaOptions = async (
+  options: LoadSchemaOptions,
+): Promise<NormalizedLoadSchemaOptions> => {
+  const base = options.base ?? process.cwd();
+  const files = await glob.glob(
+    options.files.map((file) => nodePath.resolve(base, file)),
+  );
+
+  const pathAliases = new Map<string, string>();
+  if (options.pathAliases != null) {
+    for (const [alias, source] of options.pathAliases.entries()) {
+      pathAliases.set(alias, nodePath.resolve(base, source));
+    }
+  }
+
+  return {
+    normalized: true,
+    files,
+    pathAliases,
+  };
+};

package/src/cli/commands/bundle.ts

@@ -0,0 +1,62 @@
+import * as nodeFs from 'node:fs/promises';
+import * as nodePath from 'node:path';
+
+import * as commander from '@commander-js/extra-typings';
+
+import * as api from '../../api';
+import * as shared from '../shared';
+
+export const createBundleCommand = () =>
+  new commander.Command()
+    .name(`bundle`)
+    .description(`Bundles multiple GraphQL inputs into a single file.`)
+    .argument(`<schema...>`, `Input GraphQL schema files to bundle.`)
+    .option(
+      `-b, --base <directory>`,
+      `Base directory from which paths are resolved.`,
+    )
+    .option(
+      `-a, --alias <pattern...>`,
+      `Path alias options for @graphql-tools/load.`,
+    )
+    .option(
+      `--out <file>`,
+      `Where to write the bundled schema.`,
+      `bundle.graphql`,
+    )
+    .option(`--no-shake`, `Prevents pruning of unused types.`)
+    .option(`-s, --silent`, `Only log critical information.`, false)
+    .action((schema, options) =>
+      bundle({
+        schema,
+        ...options,
+      }),
+    );
+
+const bundle = async (options: {
+  schema: Array<string>;
+  base?: string;
+  alias?: Array<string>;
+  out: string;
+  shake: boolean;
+  silent: boolean;
+}): Promise<void> => {
+  const { schema, base, alias, shake, silent } = options;
+  const out = nodePath.resolve(base ?? process.cwd(), options.out);
+
+  await nodeFs.writeFile(
+    out,
+    await api.bundle({
+      schema: {
+        files: schema,
+        base,
+        pathAliases: shared.parsePathAliases(alias ?? []),
+      },
+      shake,
+    }),
+  );
+
+  if (!silent) {
+    console.log(`✅ bundler encountered no errors.`);
+  }
+};

package/src/cli/commands/index.ts

@@ -0,0 +1,2 @@
+export * from './bundle';
+export * from './validate';

package/src/cli/commands/validate.ts

@@ -0,0 +1,59 @@
+import * as nodeFs from 'node:fs/promises';
+import * as nodePath from 'node:path';
+
+import * as commander from '@commander-js/extra-typings';
+
+import * as api from '../../api';
+import * as shared from '../shared';
+
+export const createValidateCommand = () =>
+  new commander.Command()
+    .name(`validate`)
+    .description(`Checks that all provided GraphQL files form a valid schema.`)
+    .argument(`<schema...>`, `Input GraphQL schema files to validate.`)
+    .option(
+      `-b, --base <directory>`,
+      `Base directory from which paths are resolved.`,
+    )
+    .option(
+      `-a, --alias <pattern...>`,
+      `Path alias options for @graphql-tools/load.`,
+    )
+    .option(
+      `--stamp <file>`,
+      `Creates a validation stamp to confirm valid GraphQL schema.`,
+    )
+    .option(`-s, --silent`, `Only log critical information.`, false)
+    .action((schema, options) =>
+      validate({
+        schema,
+        ...options,
+      }),
+    );
+
+const validate = async (options: {
+  schema: Array<string>;
+  base?: string;
+  alias?: Array<string>;
+  stamp?: string;
+  silent: boolean;
+}): Promise<void> => {
+  const { schema, base, alias, stamp, silent } = options;
+
+  const validationStamp = await api.validate({
+    schema: {
+      files: schema,
+      base,
+      pathAliases: shared.parsePathAliases(alias ?? []),
+    },
+  });
+
+  if (stamp != null) {
+    const destination = nodePath.resolve(base ?? process.cwd(), stamp);
+    await nodeFs.writeFile(destination, validationStamp);
+  }
+
+  if (!silent) {
+    console.log(`✅ validation encountered no errors.`);
+  }
+};

package/src/cli/index.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+import * as commander from '@commander-js/extra-typings';
+import * as graphql from 'graphql';
+
+import * as commands from './commands';
+
+const main = () => {
+  process.setUncaughtExceptionCaptureCallback((error) => {
+    // When thrown natively, GraphQLError prints like any other error with
+    // minimal context, however, when logged with `.toString()` it prints
+    // helpful debugging information critical for debugging syntax errors (such
+    // as source file, location, symbol, etc...).
+    //
+    // For example:
+    //
+    // ```
+    // Syntax Error: Expected ":", found Name "ID".
+    //
+    // src/services/api/schema/CurrentUser.graphql:2:6
+    // 1 | type CurrentUser {
+    // 2 |   id ID!
+    //   |      ^
+    // 3 |   dateCreated: DateTime!
+    // ```
+    //
+    // Versus the naive output:
+    //
+    // ```
+    // return new _GraphQLError.GraphQLError(`Syntax Error: ${description}`, {
+    // GraphQLError: Syntax Error: Expected ":", found Name "ID".
+    //     at syntaxError (node_modules/graphql/error/syntaxError.js:15:10)
+    // ```
+    if (error instanceof graphql.GraphQLError) {
+      console.error(error.toString());
+      return;
+    }
+
+    console.error(error);
+  });
+
+  commander.program
+    .name(`graphql-buddy`)
+    .description(
+      `CLI tools for manipulating graphql // designed for build system tooling.`,
+    )
+    .addCommand(commands.createBundleCommand())
+    .addCommand(commands.createValidateCommand())
+    .parse();
+};
+
+main();

package/src/cli/shared/index.ts

@@ -0,0 +1 @@
+export * from './parsePathAliases';

package/src/cli/shared/parsePathAliases.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+
+import * as parsePathAliases from './parsePathAliases';
+
+describe(`parsePathAliases`, () => {
+  it(`returns empty when no encoded aliases are passed.`, () => {
+    expect(parsePathAliases.parsePathAliases([])).toStrictEqual(new Map());
+  });
+
+  it(`splits aliases using "=" delimiter.`, () => {
+    expect(
+      parsePathAliases.parsePathAliases([
+        `@/*=src/*`,
+        `custom-foo=path/to/foo`,
+      ]),
+    ).toStrictEqual(
+      new Map([
+        [`@/*`, `src/*`],
+        [`custom-foo`, `path/to/foo`],
+      ]),
+    );
+  });
+
+  it(`throws when aliases conflict.`, () => {
+    expect(() =>
+      parsePathAliases.parsePathAliases([
+        `@/*=src/*`,
+        `custom-foo=path/to/foo`,
+        `@/*=gen/*`,
+      ]),
+    ).toThrowError(`Alias "@/*" is set multiple times.`);
+  });
+
+  it(`throws when aliases are malformed.`, () => {
+    expect(() => parsePathAliases.parsePathAliases([`@/*`])).toThrowError(
+      `Expected an alias in the form "alias=source"`,
+    );
+
+    expect(() =>
+      parsePathAliases.parsePathAliases([`foo=bar=baz`]),
+    ).toThrowError(`Expected an alias in the form "alias=source"`);
+  });
+});

package/src/cli/shared/parsePathAliases.ts

@@ -0,0 +1,25 @@
+export type PathAliases = Map<string, string>;
+
+export const parsePathAliases = (
+  encodedAliases: Array<string>,
+): PathAliases => {
+  const decodedAliases = new Map<string, string>();
+
+  for (const encodedAlias of encodedAliases) {
+    const parts = encodedAlias.split(`=`);
+    if (parts.length !== 2) {
+      throw new Error(
+        `Expected an alias in the form "alias=source" but found "${encodedAlias}"`,
+      );
+    }
+
+    const [alias, source] = parts;
+    if (decodedAliases.has(alias)) {
+      throw new Error(`Alias "${alias}" is set multiple times.`);
+    }
+
+    decodedAliases.set(alias, source);
+  }
+
+  return decodedAliases;
+};

package/test_fixtures/missing_scalar/schema.graphql

@@ -0,0 +1,16 @@
+type Query {
+  foo: Foo
+  bar: Bar
+}
+
+type Foo {
+  id: ID!
+
+  dateCreated: DateTime
+}
+
+type Bar {
+  id: ID!
+
+  foo: Foo
+}