relay-compiler 9.0.0 → 9.1.0

package/core/CompilerError.js.flow

@@ -0,0 +1,250 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ * @format
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+const {GraphQLError} = require('graphql');
+
+import type {Location} from './IR';
+import type {ASTNode, Source, SourceLocation} from 'graphql';
+
+// Combined results of multiple user errors
+export opaque type CombinedUserError: Error = Error;
+
+// Error describing invalid application code from which the compiler
+// can recover, ie which does not prevent processing of other inputs.
+export opaque type UserError: Error = GraphQLError;
+
+// Error describing invalid application code from which the compiler
+// *cannot* recover, ie where the validity of subsequent inputs cannot
+// be determined. Try to avoid these errors.
+export opaque type NonRecoverableUserError: Error = Error;
+
+// Error describing a bug in the compiler
+export opaque type CompilerError: Error = Error;
+
+/**
+ * Creates an error describing invalid application code (GraphQL/Schema)
+ * that must be fixed by the end developer. This should only be used
+ * for local errors that don't affect processing of other user code.
+ */
+function createUserError(
+  message: string,
+  locations?: ?$ReadOnlyArray<Location>,
+  nodes?: ?$ReadOnlyArray<ASTNode>,
+): UserError {
+  let messageWithLocations = message;
+  if (locations != null) {
+    const printedLocations = printLocations(locations);
+    messageWithLocations =
+      printedLocations.length === 0
+        ? message
+        : [message, ...printedLocations].join('\n\n') + '\n';
+  }
+  return new GraphQLError(messageWithLocations, nodes ?? []);
+}
+
+/**
+ * Similar to createUserError but for errors that are *not* recoverable:
+ * the compiler should not continue to process other inputs because their
+ * validity can't be determined.
+ */
+function createNonRecoverableUserError(
+  message: string,
+  locations?: ?$ReadOnlyArray<Location>,
+  nodes?: ?$ReadOnlyArray<ASTNode>,
+): NonRecoverableUserError {
+  let messageWithLocations = message;
+  if (locations != null) {
+    const printedLocations = printLocations(locations);
+    messageWithLocations =
+      printedLocations.length === 0
+        ? message
+        : [message, ...printedLocations].join('\n\n') + '\n';
+  }
+  const error = new GraphQLError(messageWithLocations, nodes ?? []);
+  return new Error(error.message);
+}
+
+/**
+ * Creates an error describing a problem with the compiler itself - such
+ * as a broken invariant - that must be fixed within the compiler.
+ */
+function createCompilerError(
+  message: string,
+  locations?: ?$ReadOnlyArray<Location>,
+  nodes?: ?$ReadOnlyArray<ASTNode>,
+): CompilerError {
+  let messageWithLocations = message;
+  if (locations != null) {
+    const printedLocations = printLocations(locations);
+    messageWithLocations =
+      printedLocations.length === 0
+        ? message
+        : [message, ...printedLocations].join('\n\n') + '\n';
+  }
+  const error = new GraphQLError(
+    `Internal Error: ${messageWithLocations}`,
+    nodes ?? [],
+  );
+  return new Error(error.message);
+}
+
+/**
+ * Iterates over the elements of some iterable value, calling the
+ * supplied callback for each item with a guard for user errors.
+ *
+ * Non-user errors abort the iteration and are instantly rethrown.
+ * User errors are collected and rethrown at the end, if multiple user errors
+ * occur, a combined error is thrown.
+ */
+function eachWithCombinedError<T>(iterable: Iterable<T>, fn: T => void): void {
+  const errors: Array<UserError> = [];
+  for (const item of iterable) {
+    try {
+      fn(item);
+    } catch (error) {
+      if (error instanceof GraphQLError) {
+        errors.push(error);
+      } else {
+        throw error;
+      }
+    }
+  }
+  if (errors.length > 0) {
+    if (errors.length === 1) {
+      throw errors[0];
+    }
+    throw createUserError(
+      `Encountered ${errors.length} errors:\n` +
+        errors
+          .map(error =>
+            String(error)
+              .split('\n')
+              .map((line, index) => (index === 0 ? `- ${line}` : `  ${line}`))
+              .join('\n'),
+          )
+          .join('\n'),
+    );
+  }
+}
+
+function printLocations(locations: $ReadOnlyArray<Location>): Array<string> {
+  const printedLocations = [];
+  for (const location of locations) {
+    let sourceLocation = location;
+    while (sourceLocation.kind === 'Derived') {
+      sourceLocation = sourceLocation.source;
+    }
+    switch (sourceLocation.kind) {
+      case 'Source': {
+        // source location
+        const prefix =
+          sourceLocation === location ? 'Source: ' : 'Source (derived): ';
+        printedLocations.push(
+          prefix +
+            highlightSourceAtLocation(
+              sourceLocation.source,
+              getLocation(sourceLocation.source, sourceLocation.start),
+            ),
+        );
+        break;
+      }
+      case 'Generated': {
+        printedLocations.push('Source: (generated)');
+        break;
+      }
+      case 'Unknown': {
+        printedLocations.push('Source: (unknown)');
+        break;
+      }
+      default: {
+        (sourceLocation: empty);
+        throw createCompilerError(
+          `CompilerError: cannot print location '${String(sourceLocation)}'.`,
+        );
+      }
+    }
+  }
+  return printedLocations;
+}
+
+/**
+ * Render a helpful description of the location of the error in the GraphQL
+ * Source document.
+ */
+function highlightSourceAtLocation(
+  source: Source,
+  location: SourceLocation,
+): string {
+  const firstLineColumnOffset = source.locationOffset.column - 1;
+  const body = whitespace(firstLineColumnOffset) + source.body;
+
+  const lineIndex = location.line - 1;
+  const lineOffset = source.locationOffset.line - 1;
+  const lineNum = location.line + lineOffset;
+
+  const columnOffset = location.line === 1 ? firstLineColumnOffset : 0;
+  const columnNum = location.column + columnOffset;
+
+  const lines = body.split(/\r\n|[\n\r]/g);
+  return (
+    `${source.name} (${lineNum}:${columnNum})\n` +
+    printPrefixedLines([
+      // Lines specified like this: ["prefix", "string"],
+      [`${lineNum - 1}: `, lines[lineIndex - 1]],
+      [`${lineNum}: `, lines[lineIndex]],
+      ['', whitespace(columnNum - 1) + '^'],
+      [`${lineNum + 1}: `, lines[lineIndex + 1]],
+    ])
+  );
+}
+
+function printPrefixedLines(lines: Array<[string, string]>): string {
+  const existingLines = lines.filter(([_, line]) => line !== undefined);
+
+  let padLen = 0;
+  for (const [prefix] of existingLines) {
+    padLen = Math.max(padLen, prefix.length);
+  }
+
+  return existingLines
+    .map(([prefix, line]) => lpad(padLen, prefix) + line)
+    .join('\n');
+}
+
+function whitespace(len: number): string {
+  return Array(len + 1).join(' ');
+}
+
+function lpad(len: number, str: string): string {
+  return whitespace(len - str.length) + str;
+}
+
+function getLocation(source: Source, position: number): SourceLocation {
+  const lineRegexp = /\r\n|[\n\r]/g;
+  let line = 1;
+  let column = position + 1;
+  let match;
+  while ((match = lineRegexp.exec(source.body)) && match.index < position) {
+    line += 1;
+    column = position + 1 - (match.index + match[0].length);
+  }
+  return {line, column};
+}
+
+module.exports = {
+  createCompilerError,
+  createNonRecoverableUserError,
+  createUserError,
+  eachWithCombinedError,
+};

package/core/DotGraphQLParser.js.flow

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ * @format
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+const ASTCache = require('./ASTCache');
+
+const fs = require('fs');
+const path = require('path');
+
+const {parse, Source} = require('graphql');
+
+import type {File} from '../codegen/CodegenTypes';
+import type {DocumentNode} from 'graphql';
+
+function parseFile(baseDir: string, file: File): ?DocumentNode {
+  const text = fs.readFileSync(path.join(baseDir, file.relPath), 'utf8');
+  return parse(new Source(text, file.relPath), {
+    experimentalFragmentVariables: true,
+  });
+}
+
+function getParser(baseDir: string): ASTCache {
+  return new ASTCache({baseDir, parse: parseFile});
+}
+
+module.exports = {
+  parseFile,
+  getParser,
+};

package/core/GraphQLCompilerProfiler.js.flow

@@ -0,0 +1,341 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ * @format
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+const invariant = require('invariant');
+
+/**
+ * The compiler profiler builds a "call graph" of high level operations as a
+ * means of tracking time spent over the course of running the compiler.
+ */
+
+type Trace =
+  | MetadataTrace
+  | BeginDurationTrace
+  | EndDurationTrace
+  | EventTrace
+  | BeginAsyncTrace
+  | EndAsyncTrace;
+
+type MetadataTrace = {|
+  ph: 'M',
+  pid: number, // Process ID
+  tid: number, // Thread ID
+  name: 'process_name' | 'thread_name',
+  args: {|name: string|},
+|};
+
+type BeginDurationTrace = {|
+  ph: 'B',
+  name: string, // Event name
+  pid: number, // Process ID
+  tid: number, // Thread ID
+  ts: number, // Relative timestamp integer microseconds
+|};
+
+type EndDurationTrace = {|
+  ph: 'E',
+  name: string, // Event name
+  pid: number, // Process ID
+  tid: number, // Thread ID
+  ts: number, // Relative timestamp integer microseconds
+|};
+
+type EventTrace = {|
+  ph: 'X',
+  name: string, // Event name
+  pid: number, // Process ID
+  tid: number, // Thread ID
+  ts: number, // Relative timestamp integer in microseconds
+  dur: number, // Duration timestamp integer in microseconds
+|};
+
+type BeginAsyncTrace = {|
+  ph: 'b',
+  name: string, // Async event name
+  cat: string, // Async category
+  id: number, // Async tree ID
+  pid: number, // Process ID
+  tid: number, // Thread ID
+  ts: number, // Relative timestamp integer microseconds
+|};
+
+type EndAsyncTrace = {|
+  ph: 'e',
+  name: string, // Async event name
+  cat: string, // Async category
+  id: number, // Async tree ID
+  pid: number, // Process ID
+  tid: number, // Thread ID
+  ts: number, // Relative timestamp integer microseconds
+|};
+
+let enabled = false;
+const traces: Array<Trace> = [
+  {
+    ph: 'M',
+    pid: 0,
+    tid: 0,
+    name: 'process_name',
+    args: {name: 'relay-compiler'},
+  },
+  {
+    ph: 'M',
+    pid: 0,
+    tid: 0,
+    name: 'thread_name',
+    args: {name: 'relay-compiler'},
+  },
+];
+const stack: Array<BeginDurationTrace> = [];
+
+function enable(): void {
+  enabled = true;
+}
+
+function getTraces(): Array<Trace> {
+  return traces;
+}
+
+/**
+ * Run the provided function as part of a stack profile.
+ */
+function run<T>(name: string, fn: () => T): T {
+  return instrument(fn, name)();
+}
+
+/**
+ * Run the provided async function as part context in a stack profile.
+ * See instrumentAsyncContext() for limitations and usage notes.
+ */
+function asyncContext<T: Promise<$FlowFixMe>>(name: string, fn: () => T): T {
+  return instrumentAsyncContext(fn, name)();
+}
+
+/**
+ * Wait for the provided async operation as an async profile.
+ */
+function waitFor<T: Promise<$FlowFixMe>>(name: string, fn: () => T): T {
+  return instrumentWait(fn, name)();
+}
+
+/**
+ * Return a new instrumented sync function to be part of a stack profile.
+ *
+ * This instruments synchronous functions to be displayed in a stack
+ * visualization. To instrument async functions, see instrumentAsyncContext()
+ * and instrumentWait().
+ */
+function instrument<F: (...$FlowFixMe) => mixed>(fn: F, name?: string): F {
+  if (!enabled) {
+    return fn;
+  }
+  const profileName =
+    name ??
+    // $FlowFixMe - Flow no longer considers statics of functions as any
+    fn.displayName ??
+    fn.name;
+  const instrumented = function() {
+    const traceId = start(profileName);
+    try {
+      return fn.apply(this, arguments);
+    } finally {
+      end(traceId);
+    }
+  };
+  instrumented.displayName = profileName;
+  return (instrumented: $FlowFixMe);
+}
+
+/**
+ * Return a new instrumented async function which provides context for a stack.
+ *
+ * Because the resulting profiling information will be incorporated into a
+ * stack visualization, the instrumented function must represent a distinct
+ * region of time which does not overlap with any other async context.
+ *
+ * In other words, functions instrumented with instrumentAsyncContext must not
+ * run in parallel via Promise.all().
+ *
+ * To instrument functions which will run in parallel, use instrumentWait().
+ */
+function instrumentAsyncContext<F: (...$FlowFixMe) => Promise<$FlowFixMe>>(
+  fn: F,
+  name?: string,
+): F {
+  if (!enabled) {
+    return fn;
+  }
+
+  const profileName: string =
+    name ??
+    // $FlowFixMe - Flow no longer considers statics of functions as any
+    fn.displayName ??
+    fn.name;
+  const instrumented = async function() {
+    const traceId = start(profileName);
+    try {
+      return await fn.apply(this, arguments);
+    } finally {
+      end(traceId);
+    }
+  };
+  instrumented.displayName = profileName;
+  return (instrumented: $FlowFixMe);
+}
+
+/**
+ * Return a new instrumented function which performs an awaited async operation.
+ *
+ * The instrumented function is not included in the overall run time of the
+ * compiler, instead it captures the time waiting on some asynchronous external
+ * resource such as network or filesystem which are often run in parallel.
+ */
+function instrumentWait<F: (...$FlowFixMe) => Promise<$FlowFixMe>>(
+  fn: F,
+  name?: string,
+): F {
+  if (!enabled) {
+    return fn;
+  }
+  const profileName: string =
+    name ??
+    // $FlowFixMe - Flow no longer considers statics of functions as any
+    fn.displayName ??
+    fn.name;
+  const instrumented = async function() {
+    const traceId = startWait(profileName);
+    try {
+      return await fn.apply(this, arguments);
+    } finally {
+      end(traceId);
+    }
+  };
+  instrumented.displayName = profileName;
+  return (instrumented: $FlowFixMe);
+}
+
+const T_ZERO = process.hrtime();
+
+// Return a Uint32 of microtime duration since program start.
+function microtime(): number {
+  const hrtime = process.hrtime(T_ZERO);
+  // eslint-disable-next-line no-bitwise
+  return 0 | (hrtime[0] * 1e6 + Math.round(hrtime[1] / 1e3));
+}
+
+/**
+ * Start a stack profile with a particular name, returns an ID to pass to end().
+ *
+ * Other profiles may start before this one ends, which will be represented as
+ * nested operations, however all nested operations must end before this ends.
+ *
+ * In particular, be careful to end after errors.
+ */
+function start(name: string): number {
+  const beginTrace = {
+    ph: 'B',
+    name,
+    pid: 0,
+    tid: 0,
+    ts: microtime(),
+  };
+  traces.push(beginTrace);
+  stack.push(beginTrace);
+  return traces.length - 1;
+}
+
+let asyncID = 0;
+
+/**
+ * Start an async wait profile with a particular name, returns an ID to pass
+ * to end().
+ *
+ * Other profiles may start before this one ends, which will be represented as
+ * nested operations, however all nested operations must end before this ends.
+ *
+ * In particular, be careful to end after errors.
+ */
+function startWait(name: string): number {
+  traces.push({
+    ph: 'b',
+    name,
+    cat: 'wait',
+    id: asyncID++,
+    pid: 0,
+    tid: 0,
+    ts: microtime(),
+  });
+  return traces.length - 1;
+}
+
+function end(traceIdx: number): void {
+  const trace = traces[traceIdx];
+
+  if (trace.ph === 'b') {
+    traces.push({
+      ph: 'e',
+      cat: trace.cat,
+      name: trace.name,
+      id: trace.id,
+      pid: trace.pid,
+      tid: trace.tid,
+      ts: microtime(),
+    });
+    return;
+  }
+
+  invariant(trace.ph === 'B', 'Begin trace phase');
+  invariant(
+    stack.pop() === trace,
+    'GraphQLCompilerProfiler: The profile trace %s ended before nested traces. ' +
+      'If it is async, try using Profile.waitFor or Profile.profileWait.',
+    trace.name,
+  );
+
+  const prevTrace = traces[traces.length - 1];
+
+  if (trace === prevTrace) {
+    traces[traceIdx] = {
+      ph: 'X',
+      name: trace.name,
+      pid: trace.pid,
+      tid: trace.tid,
+      ts: trace.ts,
+      dur: microtime() - trace.ts,
+    };
+    return;
+  }
+
+  traces.push({
+    ph: 'E',
+    name: trace.name,
+    pid: trace.pid,
+    tid: trace.tid,
+    ts: microtime(),
+  });
+}
+
+module.exports = {
+  enable,
+  getTraces,
+  run,
+  asyncContext,
+  waitFor,
+  instrument,
+  instrumentAsyncContext,
+  instrumentWait,
+  start,
+  startWait,
+  end,
+};

package/core/GraphQLDerivedFromMetadata.js.flow

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+import type {Fragment, Request, Root, SplitOperation} from './IR';
+import type {GeneratedNode} from 'relay-runtime';
+
+/**
+ * Helpers to retieve the name of the document from which the input derives:
+ * this is either the name of the input itself (if it is not a derived node)
+ * or the metadata.derivedFrom property for derived nodes.
+ */
+
+// Version for generated nodes
+function getReaderSourceDefinitionName(node: GeneratedNode): string {
+  const [name, derivedFrom] =
+    node.kind === 'Request'
+      ? [node.params.name, node.params.metadata?.derivedFrom]
+      : node.kind === 'SplitOperation'
+      ? [node.name, node.metadata?.derivedFrom]
+      : [node.name, null];
+  return typeof derivedFrom === 'string' ? derivedFrom : name;
+}
+
+// Version for IR
+function getSourceDefinitionName(
+  node: Fragment | Request | Root | SplitOperation,
+): string {
+  const derivedFrom =
+    node.kind === 'Request' ||
+    node.kind === 'Root' ||
+    node.kind === 'SplitOperation'
+      ? node.metadata?.derivedFrom
+      : null;
+  return typeof derivedFrom === 'string' ? derivedFrom : node.name;
+}
+
+module.exports = {getReaderSourceDefinitionName, getSourceDefinitionName};