relay-compiler 9.0.0 → 10.1.0

package/language/RelayLanguagePluginInterface.js.flow

@@ -0,0 +1,283 @@
+/**
+ * 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';
+
+const {RelayConcreteNode} = require('relay-runtime');
+
+import type {
+  IsGeneratedFileFn,
+  KeepExtraFileFn,
+} from '../codegen/CodegenRunner';
+import type {IRTransform} from '../core/CompilerContext';
+import type {GeneratedDefinition, Root, Fragment} from '../core/IR';
+import type {GetFileFilter} from '../core/RelaySourceModuleParser';
+import type {Schema} from '../core/Schema';
+import type {ScalarTypeMapping} from './javascript/RelayFlowTypeTransformers';
+import type {GeneratedNode} from 'relay-runtime';
+
+/**
+ * A language plugin allows relay-compiler to both read and write files for any
+ * language.
+ *
+ * When reading, the plugin is expected to parse and return GraphQL tags; and
+ * when writing the plugin is responsible for generating type information about
+ * the GraphQL selections made as well as generating the contents of the
+ * artifact file.
+ *
+ * This interface describes the details relay-compiler requires to be able to
+ * use the plugin and is expected to be returned by a {PluginInitializer}.
+ */
+export type PluginInterface = {
+  inputExtensions: string[],
+  outputExtension: string,
+  findGraphQLTags: GraphQLTagFinder,
+  formatModule: FormatModule,
+  typeGenerator: TypeGenerator,
+  isGeneratedFile?: IsGeneratedFileFn,
+  keepExtraFile?: KeepExtraFileFn,
+  schemaExtensions?: $ReadOnlyArray<string>,
+  getModuleName?: (operationName: string) => string,
+  getFileFilter?: GetFileFilter,
+  ...
+};
+
+/**
+ * The plugin is expected to have as its main default export a function that
+ * returns an object conforming to the plugin interface.
+ *
+ * For now a plugin doesn’t take any arguments, but may do so in the future.
+ */
+export type PluginInitializer = () => PluginInterface;
+
+export type GraphQLTag = {
+  /**
+   * Should hold the string content of the `graphql` tagged template literal,
+   * which is either an operation or fragment.
+   *
+   * @example
+   *
+   *  grapqhl`query MyQuery { … }`
+   *  grapqhl`fragment MyFragment on MyType { … }`
+   */
+  template: string,
+  /**
+   * In the case this tag was part of a fragment container and it used a node
+   * map as fragment spec, rather than a single tagged node, this should hold
+   * the prop key to which the node is assigned.
+   *
+   * @example
+   *
+   *  createFragmentContainer(
+   *    MyComponent,
+   *    {
+   *      keyName: graphql`fragment MyComponent_keyName { … }`
+   *    }
+   *  )
+   *
+   */
+  keyName: ?string,
+  /**
+   * The location in the source file that the tag is placed at.
+   */
+  sourceLocationOffset: {|
+    /**
+     * The line in the source file that the tag is placed on.
+     *
+     * Lines use 1-based indexing.
+     */
+    line: number,
+
+    /**
+     * The column in the source file that the tag starts on.
+     *
+     * Columns use 1-based indexing.
+     */
+    column: number,
+  |},
+  ...
+};
+
+/**
+ * This function is responsible for extracting `GraphQLTag` objects from source
+ * files.
+ *
+ * @param  {string} text       The source file contents.
+ * @param  {string} filePath   The path to the source file on disk.
+ * @return {Array<GraphQLTag>} All extracted `GraphQLTag` objects.
+ *
+ * @see {@link javascript/FindGraphQLTags.js}
+ */
+export type GraphQLTagFinder = (
+  text: string,
+  filePath: string,
+) => $ReadOnlyArray<GraphQLTag>;
+
+/**
+ * The function that is responsible for generating the contents of the artifact
+ * file.
+ *
+ * @see {@link javascript/formatGeneratedModule.js}
+ */
+export type FormatModule = ({|
+  /**
+   * The filename of the module.
+   */
+  moduleName: string,
+
+  /**
+   * The type of artifact that this module represents.
+   *
+   * @todo Document when this can be `empty`.
+   */
+  documentType:
+    | typeof RelayConcreteNode.FRAGMENT
+    | typeof RelayConcreteNode.REQUEST
+    | null,
+
+  /**
+   * The actual document that this module represents.
+   */
+  docText: ?string,
+
+  /**
+   * The IR for the document that this module represents.
+   */
+  concreteText: string,
+
+  /**
+   * The type information generated for the GraphQL selections made.
+   */
+  typeText: string,
+
+  /**
+   * A hash of the concrete node including the query text.
+   *
+   * @todo Document how this is different from `sourceHash`.
+   */
+  hash: ?string,
+
+  /**
+   * The 'kind' of the generated node.
+   */
+  kind: string,
+
+  /**
+   * The IR node from which the generated node is derived.
+   */
+  definition: GeneratedDefinition,
+
+  /**
+   * A hash of the document, which is used by relay-compiler to know if it needs
+   * to write a new version of the artifact.
+   *
+   * @todo Is this correct? And document how this is different from `hash`.
+   */
+  sourceHash: string,
+
+  /**
+   * The generated node being written.
+   */
+  node: GeneratedNode,
+
+  /**
+   * GraphQL Schema Interface
+   */
+  schema: Schema,
+|}) => string;
+
+/**
+ * The options that will be passed to the `generate` function of your plugin’s
+ * type generator.
+ */
+export type TypeGeneratorOptions = {|
+  /**
+   * A map of custom scalars to scalars that the plugin knows about and emits
+   * type information for.
+   *
+   * @example
+   *
+   *  // The URL custom scalar is essentially a string and should be treated as
+   *  // such by the language’s type system.
+   *  { URL: 'String' }
+   */
+  +customScalars: ScalarTypeMapping,
+
+  /**
+   * Whether or not relay-compiler will store artifacts next to the module that
+   * they originate from or all together in a single directory.
+   *
+   * Storing all artifacts in a single directory makes it easy to import and
+   * reference fragments defined in other artifacts without needing to use the
+   * Haste module system.
+   *
+   * This defaults to `false`.
+   */
+  +useSingleArtifactDirectory: boolean,
+
+  /**
+   * This option controls whether or not a catch-all entry is added to enum type
+   * definitions for values that may be added in the future. Enabling this means
+   * you will have to update your application whenever the GraphQL server schema
+   * adds new enum values to prevent it from breaking.
+   *
+   * This defaults to `false`.
+   */
+  +noFutureProofEnums: boolean,
+
+  /**
+   * @todo Document this.
+   */
+  +optionalInputFields: $ReadOnlyArray<string>,
+
+  /**
+   * Whether or not the Haste module system is being used. This will currently
+   * always be `false` for OSS users.
+   */
+  +useHaste: boolean,
+
+  /**
+   * Import flow types from the Haste-style global module name or per-enum
+   * global module name given by the function variant.
+   */
+  +enumsHasteModule?: string | ((enumName: string) => string),
+
+  /**
+   * Optional normalization IR for generating raw response
+   */
+  +normalizationIR?: Root,
+|};
+
+/**
+ * This object should hold the implementation required to generate types for the
+ * GraphQL selections made.
+ *
+ * @see {@link javascript/RelayFlowGenerator.js}
+ */
+export type TypeGenerator = {
+  /**
+   * Transforms that should be applied to the intermediate representation of the
+   * GraphQL document before passing to the `generate` function.
+   */
+  transforms: $ReadOnlyArray<IRTransform>,
+  /**
+   * Given GraphQL document IR, this function should generate type information
+   * for e.g. the selections made. It can, however, also generate any other
+   * content such as importing other files, including other artifacts.
+   */
+  generate: (
+    schema: Schema,
+    node: Root | Fragment,
+    options: TypeGeneratorOptions,
+  ) => string,
+  ...
+};

package/language/javascript/FindGraphQLTags.js.flow

@@ -0,0 +1,137 @@
+/**
+ * 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
+ * @format
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+const Profiler = require('../../core/GraphQLCompilerProfiler');
+
+const babylon = require('@babel/parser');
+const util = require('util');
+
+import type {GraphQLTag} from '../RelayLanguagePluginInterface';
+
+// Attempt to be as inclusive as possible of source text.
+const BABYLON_OPTIONS = {
+  allowImportExportEverywhere: true,
+  allowReturnOutsideFunction: true,
+  allowSuperOutsideMethod: true,
+  sourceType: 'module',
+  plugins: [
+    'asyncGenerators',
+    'classProperties',
+    ['decorators', {decoratorsBeforeExport: true}],
+    'doExpressions',
+    'dynamicImport',
+    'exportExtensions',
+    ['flow', {enums: true}],
+    'functionBind',
+    'functionSent',
+    'jsx',
+    'nullishCoalescingOperator',
+    'objectRestSpread',
+    'optionalChaining',
+    'optionalCatchBinding',
+  ],
+  strictMode: false,
+};
+
+function find(text: string): $ReadOnlyArray<GraphQLTag> {
+  const result: Array<GraphQLTag> = [];
+  // $FlowFixMe Discovered when typing babel/parser
+  const ast = babylon.parse(text, BABYLON_OPTIONS);
+
+  const visitors = {
+    TaggedTemplateExpression: node => {
+      if (isGraphQLTag(node.tag)) {
+        result.push({
+          keyName: null,
+          template: node.quasi.quasis[0].value.raw,
+          sourceLocationOffset: getSourceLocationOffset(node.quasi),
+        });
+      }
+    },
+  };
+  visit(ast, visitors);
+  return result;
+}
+
+const IGNORED_KEYS = {
+  comments: true,
+  end: true,
+  leadingComments: true,
+  loc: true,
+  name: true,
+  start: true,
+  trailingComments: true,
+  type: true,
+};
+
+function isGraphQLTag(tag): boolean {
+  return tag.type === 'Identifier' && tag.name === 'graphql';
+}
+
+function getTemplateNode(quasi) {
+  const quasis = quasi.quasis;
+  invariant(
+    quasis && quasis.length === 1,
+    'FindGraphQLTags: Substitutions are not allowed in graphql tags.',
+  );
+  return quasis[0];
+}
+
+function getSourceLocationOffset(quasi) {
+  const loc = getTemplateNode(quasi).loc.start;
+  return {
+    line: loc.line,
+    column: loc.column + 1, // babylon is 0-indexed, graphql expects 1-indexed
+  };
+}
+
+function invariant(condition, msg, ...args) {
+  if (!condition) {
+    throw new Error(util.format(msg, ...args));
+  }
+}
+
+function visit(node, visitors) {
+  // $FlowFixMe Discovered when typing babel
+  const fn = visitors[node.type];
+  if (fn != null) {
+    fn(node);
+    return;
+  }
+  traverse(node, visitors);
+}
+
+function traverse(node, visitors) {
+  for (const key in node) {
+    if (IGNORED_KEYS[key]) {
+      continue;
+    }
+    const prop = node[key];
+    if (prop && typeof prop === 'object' && typeof prop.type === 'string') {
+      visit(prop, visitors);
+    } else if (Array.isArray(prop)) {
+      prop.forEach(item => {
+        if (item && typeof item === 'object' && typeof item.type === 'string') {
+          visit(item, visitors);
+        }
+      });
+    }
+  }
+}
+
+module.exports = {
+  find: (Profiler.instrument(find, 'FindGraphQLTags.find'): (
+    text: string,
+  ) => $ReadOnlyArray<GraphQLTag>),
+};

package/language/javascript/RelayFlowBabelFactories.js.flow

@@ -0,0 +1,176 @@
+/**
+ * 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');
+const t = require('@babel/types');
+
+type BabelAST = BabelNode_DEPRECATED;
+
+/**
+ * type NAME = any;
+ */
+function anyTypeAlias(name: string): BabelAST {
+  return t.typeAlias(t.identifier(name), undefined, t.anyTypeAnnotation());
+}
+
+/**
+ * {|
+ *   PROPS
+ * |}
+ */
+function exactObjectTypeAnnotation(props: Array<BabelAST>): $FlowFixMe {
+  const typeAnnotation = t.objectTypeAnnotation(props);
+  typeAnnotation.exact = true;
+  return typeAnnotation;
+}
+
+/**
+ * {
+ *   PROPS
+ *   ...
+ * }
+ */
+function inexactObjectTypeAnnotation(props: Array<BabelAST>): $FlowFixMe {
+  const typeAnnotation = t.objectTypeAnnotation(props);
+  typeAnnotation.inexact = true;
+  return typeAnnotation;
+}
+
+/**
+ * export type NAME = TYPE
+ */
+function exportType(name: string, type: BabelAST): $FlowFixMe {
+  return t.exportNamedDeclaration(
+    t.typeAlias(t.identifier(name), undefined, type),
+    [],
+    undefined,
+  );
+}
+
+/**
+ * export type {A, B, C}
+ */
+function exportTypes(names: $ReadOnlyArray<string>): $FlowFixMe {
+  const res = t.exportNamedDeclaration(
+    undefined,
+    names.map(name =>
+      t.exportSpecifier(t.identifier(name), t.identifier(name)),
+    ),
+
+    undefined,
+  );
+  res.exportKind = 'type';
+  return res;
+}
+
+/**
+ * declare export type NAME = VALUE
+ */
+function declareExportOpaqueType(name: string, value: string): $FlowFixMe {
+  return t.declareExportDeclaration(
+    t.declareOpaqueType(
+      t.identifier(name),
+      undefined,
+      t.genericTypeAnnotation(t.identifier(value)),
+    ),
+  );
+}
+
+/**
+ * import type {NAMES[0], NAMES[1], ...} from 'MODULE';
+ */
+function importTypes(
+  names: $ReadOnlyArray<string>,
+  module: string,
+): $FlowFixMe {
+  const importDeclaration = t.importDeclaration(
+    names.map(name =>
+      t.importSpecifier(t.identifier(name), t.identifier(name)),
+    ),
+    t.stringLiteral(module),
+  );
+  importDeclaration.importKind = 'type';
+  return importDeclaration;
+}
+
+/**
+ * Create an intersection type if needed.
+ *
+ * TYPES[0] & TYPES[1] & ...
+ */
+function intersectionTypeAnnotation(types: Array<BabelAST>): BabelAST {
+  invariant(
+    types.length > 0,
+    'RelayFlowBabelFactories: cannot create an intersection of 0 types',
+  );
+  return types.length === 1 ? types[0] : t.intersectionTypeAnnotation(types);
+}
+
+function lineComments(
+  ...lines: $ReadOnlyArray<string>
+): $ReadOnlyArray<$FlowFixMe> {
+  return lines.map(line => ({type: 'CommentLine', value: ' ' + line}));
+}
+
+/**
+ * $ReadOnlyArray<TYPE>
+ */
+function readOnlyArrayOfType(thing: BabelAST): $FlowFixMe {
+  return t.genericTypeAnnotation(
+    t.identifier('$ReadOnlyArray'),
+    t.typeParameterInstantiation([thing]),
+  );
+}
+
+/**
+ * +KEY: VALUE
+ */
+function readOnlyObjectTypeProperty(key: string, value: BabelAST): $FlowFixMe {
+  const prop = t.objectTypeProperty(t.identifier(key), value);
+  prop.variance = t.variance('plus');
+  return prop;
+}
+
+function stringLiteralTypeAnnotation(value: string): $FlowFixMe {
+  return t.stringLiteralTypeAnnotation(value);
+}
+
+/**
+ * Create a union type if needed.
+ *
+ * TYPES[0] | TYPES[1] | ...
+ */
+function unionTypeAnnotation(types: Array<BabelAST>): BabelAST {
+  invariant(
+    types.length > 0,
+    'RelayFlowBabelFactories: cannot create a union of 0 types',
+  );
+  return types.length === 1 ? types[0] : t.unionTypeAnnotation(types);
+}
+
+module.exports = {
+  anyTypeAlias,
+  declareExportOpaqueType,
+  exactObjectTypeAnnotation,
+  inexactObjectTypeAnnotation,
+  exportType,
+  exportTypes,
+  importTypes,
+  intersectionTypeAnnotation,
+  lineComments,
+  readOnlyArrayOfType,
+  readOnlyObjectTypeProperty,
+  stringLiteralTypeAnnotation,
+  unionTypeAnnotation,
+};