use dev/prod condition to trigger instanceOf check

Author: yaacovCR

package.json

@@ -12,7 +12,9 @@
       ]
     }
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./dev/index.js"
+  ],
   "homepage": "https://github.com/graphql/graphql-js",
   "bugs": {
     "url": "https://github.com/graphql/graphql-js/issues"

resources/build-npm.ts

@@ -19,11 +19,14 @@ await buildPackage('./npmDist');
 showDirStats('./npmDist');
 
 async function buildPackage(outDir: string): Promise<void> {
+  const devDir = path.join(outDir, '__dev__');
+
   fs.rmSync(outDir, { recursive: true, force: true });
   fs.mkdirSync(outDir);
+  fs.mkdirSync(devDir);
 
-  fs.copyFileSync('./LICENSE', `./${outDir}/LICENSE`);
-  fs.copyFileSync('./README.md', `./${outDir}/README.md`);
+  fs.copyFileSync('./LICENSE', `${outDir}/LICENSE`);
+  fs.copyFileSync('./README.md', `${outDir}/README.md`);
 
   const packageJSON = readPackageJSON();
 
@@ -85,17 +88,61 @@ async function buildPackage(outDir: string): Promise<void> {
     extension: '.js',
   });
 
-  for (const filepath of emittedTSFiles) {
-    if (path.basename(filepath) === 'index.js') {
-      const relativePath =
-        './' + crossPlatformRelativePath('./npmDist', filepath);
-      packageJSON.exports[path.dirname(relativePath)] = relativePath;
+  for (const prodFile of emittedTSFiles) {
+    const { dir, base } = path.parse(prodFile);
+
+    const match = base.match(/^([^.]*)\.?(.*)$/);
+    assert(match);
+    const [, name, ext] = match;
+
+    if (ext === 'js.map') {
+      continue;
+    } else if (path.basename(dir) === 'dev') {
+      packageJSON.exports['./dev'] = './dev/index.js';
+      continue;
+    }
+
+    const relativePathToProd = crossPlatformRelativePath(prodFile, outDir);
+    const relativePathAndName = crossPlatformRelativePath(
+      outDir,
+      `${dir}/${name}`,
+    );
+
+    const lines =
+      ext === 'd.ts' ? [] : [`import '${relativePathToProd}/dev/index.js';`];
+    lines.push(
+      `export * from '${relativePathToProd}/${relativePathAndName}.js';`,
+    );
+    const body = lines.join('\n');
+
+    writeGeneratedFile(
+      path.join(devDir, path.relative(outDir, prodFile)),
+      body,
+    );
+
+    if (base === 'index.js') {
+      const dirname = path.dirname(relativePathAndName);
+      packageJSON.exports[dirname === '.' ? dirname : `./${dirname}`] = {
+        development: `./__dev__/${relativePathAndName}.js`,
+        default: `./${relativePathAndName}.js`,
+      };
     }
   }
 
   // Temporary workaround to allow "internal" imports, no grantees provided
-  packageJSON.exports['./*.js'] = './*.js';
-  packageJSON.exports['./*'] = './*.js';
+  packageJSON.exports['./*.js'] = {
+    development: './__dev__/*.js',
+    default: './*.js',
+  };
+  packageJSON.exports['./*'] = {
+    development: './__dev__/*.js',
+    default: './*.js',
+  };
+
+  packageJSON.sideEffects = [
+    ...(packageJSON.sideEffects as Array<string>),
+    '__dev__/*',
+  ];
 
   const packageJsonPath = `./${outDir}/package.json`;
   const prettified = await prettify(
@@ -127,7 +174,11 @@ function emitTSFiles(options: {
   const tsHost = ts.createCompilerHost(tsOptions);
   tsHost.writeFile = (filepath, body) => writeGeneratedFile(filepath, body);
 
-  const tsProgram = ts.createProgram(['src/index.ts'], tsOptions, tsHost);
+  const tsProgram = ts.createProgram(
+    ['src/index.ts', 'src/dev/index.ts'],
+    tsOptions,
+    tsHost,
+  );
   const tsResult = tsProgram.emit(undefined, undefined, undefined, undefined, {
     after: [changeExtensionInImportPaths({ extension }), inlineInvariant],
   });

resources/utils.ts

@@ -234,7 +234,15 @@ interface PackageJSON {
   repository?: { url?: string };
   scripts?: { [name: string]: string };
   type?: string;
-  exports: { [path: string]: string };
+  sideEffects?: boolean | Array<string>;
+  exports: {
+    [path: string]:
+      | string
+      | {
+          development: string;
+          default: string;
+        };
+  };
   types?: string;
   typesVersions: { [ranges: string]: { [path: string]: Array<string> } };
   devDependencies?: { [name: string]: string };

src/dev/README.md

@@ -0,0 +1,10 @@
+## GraphQL Dev
+
+The `graphql/dev` module is responsible for enabling development mode.
+
+In development mode, GraphQL.js provides additional checks to help avoid developer errors.
+
+```js
+import 'graphql/dev'; // ES6
+require('graphql/dev'); // CommonJS
+```

src/dev/index.ts

@@ -0,0 +1,46 @@
+import { inspect } from '../jsutils/inspect.js';
+import type { Constructor } from '../jsutils/instanceOf.js';
+
+/**
+ * An additional check to be included within instanceOf warning when
+ * multi-realm constructors are detected.
+ *
+ * This additional check will be included:
+ * 1. if 'graphql/development.js' is imported explicitly prior to all
+ *    other imports from this library, or
+ * 2. if the "development" condition is set.
+ */
+export function developmentInstanceOfCheck(
+  value: unknown,
+  constructor: Constructor,
+): void {
+  if (typeof value === 'object' && value !== null) {
+    // Prefer Symbol.toStringTag since it is immune to minification.
+    const className = constructor.prototype[Symbol.toStringTag];
+    const valueClassName =
+      // We still need to support constructor's name to detect conflicts with older versions of this library.
+      Symbol.toStringTag in value
+        ? value[Symbol.toStringTag]
+        : value.constructor?.name;
+    if (className === valueClassName) {
+      const stringifiedValue = inspect(value);
+      throw new Error(
+        `Cannot use ${className} "${stringifiedValue}" from another module or realm.
+
+Ensure that there is only one instance of "graphql" in the node_modules
+directory. If different versions of "graphql" are the dependencies of other
+relied on modules, use "resolutions" to ensure only one version is installed.
+
+https://yarnpkg.com/en/docs/selective-version-resolutions
+
+Duplicate "graphql" modules cannot be used at the same time since different
+versions may have different capabilities and behavior. The data from one
+version used in the function from another could produce confusing and
+spurious results.`,
+      );
+    }
+  }
+}
+
+(globalThis as any)[Symbol.for('graphql.instanceOfCheck')] =
+  developmentInstanceOfCheck;

src/jsutils/__tests__/instanceOf-test.ts

@@ -1,7 +1,12 @@
 import { expect } from 'chai';
 import { describe, it } from 'mocha';
 
-import { instanceOf } from '../instanceOf.js';
+import { developmentInstanceOfCheck } from '../../dev/index.js';
+
+(globalThis as any)[Symbol.for('graphql.instanceOfCheck')] =
+  developmentInstanceOfCheck;
+
+const { instanceOf } = await import(`../instanceOf.js?ts${Date.now()}`);
 
 describe('instanceOf', () => {
   it('do not throw on values without prototype', () => {

src/jsutils/instanceOf.ts

@@ -1,58 +1,27 @@
-import { inspect } from './inspect.js';
-
-/* c8 ignore next 3 */
-const isProduction =
-  globalThis.process != null &&
-  // eslint-disable-next-line no-undef
-  process.env.NODE_ENV === 'production';
-
 /**
- * A replacement for instanceof which includes an error warning when multi-realm
- * constructors are detected.
- * See: https://expressjs.com/en/advanced/best-practice-performance.html#set-node_env-to-production
- * See: https://webpack.js.org/guides/production/
+ * "src/development.ts" includes an additional check for development mode
+ * which throws on multiple versions of graphql-js.
+ *
+ * This additional check will be included:
+ * 1. if 'graphql/dev' is imported explicitly prior to all
+ *    other imports from this library, or
+ * 2. if the "development" condition is set.
  */
-export const instanceOf: (value: unknown, constructor: Constructor) => boolean =
-  /* c8 ignore next 6 */
-  // FIXME: https://github.com/graphql/graphql-js/issues/2317
-  isProduction
-    ? function instanceOf(value: unknown, constructor: Constructor): boolean {
-        return value instanceof constructor;
-      }
-    : function instanceOf(value: unknown, constructor: Constructor): boolean {
-        if (value instanceof constructor) {
-          return true;
-        }
-        if (typeof value === 'object' && value !== null) {
-          // Prefer Symbol.toStringTag since it is immune to minification.
-          const className = constructor.prototype[Symbol.toStringTag];
-          const valueClassName =
-            // We still need to support constructor's name to detect conflicts with older versions of this library.
-            Symbol.toStringTag in value
-              ? value[Symbol.toStringTag]
-              : value.constructor?.name;
-          if (className === valueClassName) {
-            const stringifiedValue = inspect(value);
-            throw new Error(
-              `Cannot use ${className} "${stringifiedValue}" from another module or realm.
-
-Ensure that there is only one instance of "graphql" in the node_modules
-directory. If different versions of "graphql" are the dependencies of other
-relied on modules, use "resolutions" to ensure only one version is installed.
+const check: (_value: unknown, _constructor: Constructor) => void =
+  (globalThis as any)[Symbol.for('graphql.instanceOfCheck')] ??
+  ((_value: unknown, _constructor: Constructor) => {
+    /* no-op */
+  });
 
-https://yarnpkg.com/en/docs/selective-version-resolutions
-
-Duplicate "graphql" modules cannot be used at the same time since different
-versions may have different capabilities and behavior. The data from one
-version used in the function from another could produce confusing and
-spurious results.`,
-            );
-          }
-        }
-        return false;
-      };
+export function instanceOf(value: unknown, constructor: Constructor): boolean {
+  if (value instanceof constructor) {
+    return true;
+  }
+  check(value, constructor);
+  return false;
+}
 
-interface Constructor {
+export interface Constructor {
   prototype: {
     [Symbol.toStringTag]: string;
   };