relay-compiler 1.3.0 → 1.5.0

package/ARCHITECTURE.md

@@ -1,94 +0,0 @@
-# Relay Compiler
-
-The compiler is a set of modules designed to extract GraphQL documents from across a codebase, transform/optimize them, and generate build artifacts. Examples of common types of artifacts include optimized GraphQL to persist to your server, runtime representations of the queries for use with GraphQL clients such as the Relay runtime, or generated source code for use with GraphQL frameworks for compiled languages (Java/Swift/etc).
-
-## Data Flow
-
-The high-level flow of data through the compiler is represented in the following diagram:
-
-```
-                   ┌─────────────┐┌─────────────┐
-                   │   GraphQL   ││   Schema    │
-                   └─────────────┘└─────────────┘
-                          │              │              parse
-                          └───────┬──────┘
-                                  ▼
-                   ┌────────────────────────────┐
-                   │      CompilerContext       │
-                   │                            │
-                   │   ┌─────┐ ┌─────┐ ┌─────┐  │──┐
-                   │   │ IR  │ │ IR  │ │ ... │  │  │
-                   │   └─────┘ └─────┘ └─────┘  │  │
-                   └────────────────────────────┘  │  transform/
-                          │    │      ▲            │   optimize
-                          │    │      └────────────┘
-                          │    │
-                          │    └──────────┐
-                          │  print        │  codegen
-                          ▼               ▼
-                   ┌─────────────┐ ┌─────────────┐
-                   │   GraphQL   │ │  Artifacts  │
-                   └─────────────┘ └─────────────┘
-```
-
-1. GraphQL text is extracted from source files and "parsed" into an intermediate representation (IR) using information from the schema.
-2. The set of IR documents forms a CompilerContext, which is then transformed and optimized.
-3. Finally, GraphQL is printed (e.g. to files, saved to a database, etc) and any artifacts are generated.
-
-## Data Types & Modules
-
-The compiler module is composed of a set of core building blocks as well as a helper that packages them together in an easy to use API. Some of the main data types and modules in the compiler are as follows:
-
-- `IR` (Intermediate Representation): an (effectively immutable) representation of a GraphQL document (query, fragment, field, etc) as a tree structure, including type information from a schema. Compared to the standard GraphQL AST (produced by e.g. `graphql-js`) the main difference is that it encodes more of the semantics of GraphQL. For example, conditional branches (`@include` and `@skip`) are represented directly, making it easier to target optimizations for these directives (One such optimization is to merge sibling fields with the same condition, potentially reducing the number of conditionals that must be evaluated at runtime).
-- `CompilerContext`: an immutable representation of a corpus of GraphQL documents. It contains the schema and a mapping of document names to document representations (as IR, see above).
-- `Transform`: a "map"-like function that accepts a `CompilerContext` as input and returns a new, modified context as output. Examples below.
-- `Parser`: Converts a GraphQL schema and raw GraphQL text into typed IR objects.
-- `Printer`: a function that accepts IR and converts it to a GraphQL string.
-
-The `RelayCompiler` module is a helper class that demonstrates one way of combining these primitives. It takes IR transforms, and given IR definitions, constructs a CompilerContext from them, transforming them, and generating output artifacts intended for use with Relay runtime.
-
-## Transforms
-
-One of the main goals of the compiler is to provide a consistent platform for writing tools that transform or optimize GraphQL. This includes the ability to experiment with new directives by transforming them away at compile time. Transform functions should typically perform a single type of modification - it's expected that an app will have multiple transforms configured in the compiler instance.
-
-Here are a few examples of some of the included transforms:
-
-- `FlattenTransform`: Reduces extraneous levels of indirection in a query, inlining fields from anonymous fragments wherever they match the parent type. This can be beneficial when generating code to read the results of a query or process query results, as it reduces duplicate field processing. For example:
-
-```
-# before: `id` is processed twice
-foo { # type FooType
-   id
-   ... on FooType { # matches the parent type, so this is extraneous
-     id
-   }
- }
-
- # after: `id` is processed once
- foo {
-   id
- }
- ```
-
- - `SkipRedundantNodeTransform`: A more advanced version of flattening, this eliminates more complex cases of field duplication such as when a field is fetched both unconditionally and conditionally, or is fetched by two different sub-fragments. For example:
-
-```
-# before: `id` processed up to 2x
-foo {
-  bar {
-    id
-  }
-  ... on FooType @include(if: $cond) { # can't be flattened due to conditional
-    id # but this field is guaranteed to be fetched regardless
-  }
-}
-
-# after: `id` processed at most once
-foo {
-  bar {
-    id
-  }
-}
-```
-
-- `GenerateRequisiteFieldTransform`: This optional, Relay-specific transform inserts `id` fields for globally identifiable objects and `__typename` fields wherever the type cannot be statically determined (e.g. for unions).

package/PATENTS

@@ -1,33 +0,0 @@
-Additional Grant of Patent Rights Version 2
-
-"Software" means the Relay software distributed by Facebook, Inc.
-
-Facebook, Inc. ("Facebook") hereby grants to each recipient of the Software
-("you") a perpetual, worldwide, royalty-free, non-exclusive, irrevocable
-(subject to the termination provision below) license under any Necessary
-Claims, to make, have made, use, sell, offer to sell, import, and otherwise
-transfer the Software. For avoidance of doubt, no license is granted under
-Facebook's rights in any patent claims that are infringed by (i) modifications
-to the Software made by you or any third party or (ii) the Software in
-combination with any software or other technology.
-
-The license granted hereunder will terminate, automatically and without notice,
-if you (or any of your subsidiaries, corporate affiliates or agents) initiate
-directly or indirectly, or take a direct financial interest in, any Patent
-Assertion: (i) against Facebook or any of its subsidiaries or corporate
-affiliates, (ii) against any party if such Patent Assertion arises in whole or
-in part from any software, technology, product or service of Facebook or any of
-its subsidiaries or corporate affiliates, or (iii) against any party relating
-to the Software. Notwithstanding the foregoing, if Facebook or any of its
-subsidiaries or corporate affiliates files a lawsuit alleging patent
-infringement against you in the first instance, and you respond by filing a
-patent infringement counterclaim in that lawsuit against that party that is
-unrelated to the Software, the license granted hereunder will not terminate
-under section (i) of this paragraph due to such counterclaim.
-
-A "Necessary Claim" is a claim of a patent owned by Facebook that is
-necessarily infringed by the Software standing alone.
-
-A "Patent Assertion" is any lawsuit or other action alleging direct, indirect,
-or contributory infringement or inducement to infringe any patent, including a
-cross-claim or counterclaim.

package/lib/AutoAliasTransform.js

@@ -1,80 +0,0 @@
-/**
- * Copyright (c) 2013-present, Facebook, Inc.
- * All rights reserved.
- *
- * This source code is licensed under the BSD-style license found in the
- * LICENSE file in the root directory of this source tree. An additional grant
- * of patent rights can be found in the PATENTS file in the same directory.
- *
- * @providesModule AutoAliasTransform
- * 
- * @format
- */
-
-'use strict';
-
-var _extends3 = _interopRequireDefault(require('babel-runtime/helpers/extends'));
-
-var _toConsumableArray3 = _interopRequireDefault(require('babel-runtime/helpers/toConsumableArray'));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { 'default': obj }; }
-
-/**
- * A transform to generate a unique alias for every combination of field name
- * and static calls. This transform requires that fragment spreads with
- * arguments have been inlined.
- */
-function transform(context) {
-  var documents = context.documents();
-  return documents.reduce(function (ctx, node) {
-    var selections = transformSelections(node.selections);
-    return ctx.add((0, _extends3['default'])({}, node, {
-      selections: selections
-    }));
-  }, new (require('./RelayCompilerContext'))(context.schema));
-}
-
-function transformSelections(nodeSelections) {
-  return nodeSelections.map(function (selection) {
-    if (selection.kind === 'LinkedField') {
-      var alias = generateAlias(selection);
-      var selections = transformSelections(selection.selections);
-      return (0, _extends3['default'])({}, selection, {
-        alias: alias,
-        selections: selections
-      });
-    } else if (selection.kind === 'ScalarField') {
-      var _alias = generateAlias(selection);
-      return (0, _extends3['default'])({}, selection, {
-        alias: _alias
-      });
-    } else if (selection.kind === 'InlineFragment' || selection.kind === 'Condition') {
-      var _selections = transformSelections(selection.selections);
-      return (0, _extends3['default'])({}, selection, {
-        selections: _selections
-      });
-    } else if (selection.kind === 'FragmentSpread') {
-      require('fbjs/lib/invariant')(!selection.args.length, 'AutoAliasTransform: Expected arguments to fragment spread ' + '`%s` to be inlined.', selection.name);
-      return selection;
-    } else {
-      require('fbjs/lib/invariant')(false, 'AutoAliasTransform: Unexpected node kind `%s`.', selection.kind);
-    }
-  });
-}
-
-function generateAlias(field) {
-  if (!field.args.length) {
-    return null;
-  }
-  var args = [].concat((0, _toConsumableArray3['default'])(field.args)).sort(sortByName).map(function (arg) {
-    return require('./getIdentifierForRelayArgumentValue')(arg.value);
-  });
-  var hash = require('./murmurHash')(require('./stableJSONStringifyOSS')(args));
-  return (field.alias || field.name) + '_' + hash;
-}
-
-function sortByName(a, b) {
-  return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
-}
-
-module.exports = { transform: transform };

package/lib/GraphQLFileParser.js

@@ -1,27 +0,0 @@
-/**
- * Copyright (c) 2013-present, Facebook, Inc.
- * All rights reserved.
- *
- * This source code is licensed under the BSD-style license found in the
- * LICENSE file in the root directory of this source tree. An additional grant
- * of patent rights can be found in the PATENTS file in the same directory.
- *
- * @providesModule GraphQLFileParser
- * 
- * @format
- */
-
-'use strict';
-
-var _require = require('graphql'),
-    parse = _require.parse,
-    Source = _require.Source;
-
-function parseFile(baseDir, file) {
-  var text = require('fs').readFileSync(require('path').join(baseDir, file.relPath), 'utf8');
-  return parse(new Source(text, file.relPath));
-}
-
-exports.getParser = function getParser(baseDir) {
-  return new (require('./FileParser'))({ baseDir: baseDir, parse: parseFile });
-};

package/lib/GraphQLTextParser.js

@@ -1,46 +0,0 @@
-/**
- * Copyright (c) 2013-present, Facebook, Inc.
- * All rights reserved.
- *
- * This source code is licensed under the BSD-style license found in the
- * LICENSE file in the root directory of this source tree. An additional grant
- * of patent rights can be found in the PATENTS file in the same directory.
- *
- * @providesModule GraphQLTextParser
- * TODO: enable flow
- * @format
- */
-
-'use strict';
-
-var _toConsumableArray3 = _interopRequireDefault(require('babel-runtime/helpers/toConsumableArray'));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { 'default': obj }; }
-
-// Throws an error if parsing the file fails
-function parseFile(baseDir, file, openTag, closeTag) {
-  var text = require('fs').readFileSync(require('path').join(baseDir, file.relPath), 'utf8');
-  var regex = new RegExp(openTag + '([\\s\\S]*?)' + closeTag, 'g');
-  var graphqlText = void 0;
-  var astDefinitions = [];
-  while ((graphqlText = regex.exec(text)) !== null) {
-    var ast = require('graphql').parse(new (require('graphql').Source)(graphqlText[1], file.relPath));
-    require('fbjs/lib/invariant')(ast.definitions.length, 'GraphQLTextParser: Expected GraphQL text to contain at least one ' + 'definition (fragment, mutation, query, subscription), got `%s`.', graphqlText[1]);
-    astDefinitions.push.apply(astDefinitions, (0, _toConsumableArray3['default'])(ast.definitions));
-  }
-  return {
-    kind: 'Document',
-    definitions: astDefinitions
-  };
-}
-
-function getParser(baseDir) {
-  return new (require('./FileParser'))({
-    baseDir: baseDir,
-    parse: parseFile
-  });
-}
-
-module.exports = {
-  getParser: getParser
-};

package/lib/RelayCodegenTypes.js

@@ -1,14 +0,0 @@
-/**
- * Copyright (c) 2013-present, Facebook, Inc.
- * All rights reserved.
- *
- * This source code is licensed under the BSD-style license found in the
- * LICENSE file in the root directory of this source tree. An additional grant
- * of patent rights can be found in the PATENTS file in the same directory.
- *
- * @providesModule RelayCodegenTypes
- * 
- * @format
- */
-
-'use strict';

package/lib/RelayCompiledTypes.js

@@ -1,13 +0,0 @@
-/**
- * Copyright (c) 2013-present, Facebook, Inc.
- * All rights reserved.
- *
- * This source code is licensed under the BSD-style license found in the
- * LICENSE file in the root directory of this source tree. An additional grant
- * of patent rights can be found in the PATENTS file in the same directory.
- *
- * @providesModule RelayCompiledTypes
- * 
- * @format
- */
-'use strict';

package/lib/RelayCompiler.js

@@ -1,144 +0,0 @@
-/**
- * Copyright (c) 2013-present, Facebook, Inc.
- * All rights reserved.
- *
- * This source code is licensed under the BSD-style license found in the
- * LICENSE file in the root directory of this source tree. An additional grant
- * of patent rights can be found in the PATENTS file in the same directory.
- *
- * 
- * @providesModule RelayCompiler
- * @format
- */
-
-'use strict';
-
-var _classCallCheck3 = _interopRequireDefault(require('babel-runtime/helpers/classCallCheck'));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { 'default': obj }; }
-
-/**
- * A utility class for parsing a corpus of GraphQL documents, transforming them
- * with a standardized set of transforms, and generating runtime representations
- * of each definition.
- */
-
-
-// <CodegenNode> is a generic type here,
-// which represents the node type we get from the CodeGenerator's generation function.
-var RelayCompiler = function () {
-
-  // The context passed in must already have any Relay-specific schema extensions
-  function RelayCompiler(schema, context, transforms, codeGenerator) {
-    (0, _classCallCheck3['default'])(this, RelayCompiler);
-
-    this._context = context;
-    // some transforms depend on this being the original schema,
-    // not the transformed schema/context's schema
-    this._schema = schema;
-    this._transforms = transforms;
-    this._codeGenerator = codeGenerator;
-  }
-
-  RelayCompiler.prototype.clone = function clone() {
-    return new RelayCompiler(this._schema, this._context, this._transforms, this._codeGenerator);
-  };
-
-  RelayCompiler.prototype.context = function context() {
-    return this._context;
-  };
-
-  RelayCompiler.prototype.addDefinitions = function addDefinitions(definitions) {
-    this._context = this._context.addAll(definitions);
-    return this._context.documents();
-  };
-
-  // Can only be called once per compiler. Once run, will use cached context
-  // To re-run, clone the compiler.
-
-
-  RelayCompiler.prototype.transformedQueryContext = function transformedQueryContext() {
-    var _this = this;
-
-    if (this._transformedQueryContext) {
-      return this._transformedQueryContext;
-    }
-    this._transformedQueryContext = this._transforms.queryTransforms.reduce(function (ctx, transform) {
-      return transform(ctx, _this._schema);
-    }, this._context);
-    return this._transformedQueryContext;
-  };
-
-  RelayCompiler.prototype.compile = function compile() {
-    var _this2 = this;
-
-    var transformContext = function transformContext(ctx, transform) {
-      return transform(ctx, _this2._schema);
-    };
-    var fragmentContext = this._transforms.fragmentTransforms.reduce(transformContext, this._context);
-    var queryContext = this.transformedQueryContext();
-    var printContext = this._transforms.printTransforms.reduce(transformContext, queryContext);
-    var codeGenContext = this._transforms.codegenTransforms.reduce(transformContext, queryContext);
-
-    var compiledDocuments = new Map();
-    fragmentContext.documents().forEach(function (node) {
-      if (node.kind !== 'Fragment') {
-        return;
-      }
-      var generatedFragment = _this2._codeGenerator(node);
-      compiledDocuments.set(node.name, generatedFragment);
-    });
-    queryContext.documents().forEach(function (node) {
-      if (node.kind !== 'Root') {
-        return;
-      }
-      var name = node.name;
-      // The unflattened query is used for printing, since flattening creates an
-      // invalid query.
-
-      var text = require('./filterContextForNode')(printContext.getRoot(name), printContext).documents().map(require('./RelayPrinter').print).join('\n');
-      // The original query (with fragment spreads) is converted to a fragment
-      // for reading out the root data.
-      var sourceNode = fragmentContext.getRoot(name);
-      var rootFragment = buildFragmentForRoot(sourceNode);
-      var generatedFragment = _this2._codeGenerator(rootFragment);
-      // The flattened query is used for codegen in order to reduce the number of
-      // duplicate fields that must be processed during response normalization.
-      var codeGenNode = codeGenContext.getRoot(name);
-      var generatedQuery = _this2._codeGenerator(codeGenNode);
-
-      var batchQuery = {
-        fragment: generatedFragment,
-        id: null,
-        kind: 'Batch',
-        metadata: node.metadata || {},
-        name: name,
-        query: generatedQuery,
-        text: text
-      };
-      compiledDocuments.set(name, batchQuery);
-    });
-    return compiledDocuments;
-  };
-
-  return RelayCompiler;
-}();
-
-/**
- * Construct the fragment equivalent of a root node.
- */
-
-
-function buildFragmentForRoot(root) {
-  return {
-    argumentDefinitions: root.argumentDefinitions,
-    directives: root.directives,
-    kind: 'Fragment',
-    metadata: null,
-    name: root.name,
-    selections: root.selections,
-    type: root.type
-  };
-}
-
-module.exports = RelayCompiler;

package/lib/RelayCompilerContext.js

@@ -1,133 +0,0 @@
-/**
- * Copyright (c) 2013-present, Facebook, Inc.
- * All rights reserved.
- *
- * This source code is licensed under the BSD-style license found in the
- * LICENSE file in the root directory of this source tree. An additional grant
- * of patent rights can be found in the PATENTS file in the same directory.
- *
- * 
- * @providesModule RelayCompilerContext
- * @format
- */
-
-'use strict';
-
-var _classCallCheck3 = _interopRequireDefault(require('babel-runtime/helpers/classCallCheck'));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { 'default': obj }; }
-
-var _require = require('./RelayCompilerUserError'),
-    createUserError = _require.createUserError;
-
-var ImmutableList = require('immutable').List,
-    ImmutableOrderedMap = require('immutable').OrderedMap,
-    Record = require('immutable').Record;
-
-var Document = Record({
-  errors: null,
-  name: null,
-  node: null
-});
-
-/**
- * An immutable representation of a corpus of documents being compiled together.
- * For each document, the context stores the IR and any validation errors.
- */
-
-var RelayCompilerContext = function () {
-  function RelayCompilerContext(schema) {
-    (0, _classCallCheck3['default'])(this, RelayCompilerContext);
-
-    this._documents = new ImmutableOrderedMap();
-    this.schema = schema;
-  }
-
-  /**
-   * Returns the documents for the context in the order they were added.
-   */
-
-
-  RelayCompilerContext.prototype.documents = function documents() {
-    return this._documents.valueSeq().map(function (doc) {
-      return doc.get('node');
-    }).toJS();
-  };
-
-  RelayCompilerContext.prototype.updateSchema = function updateSchema(schema) {
-    var context = new RelayCompilerContext(schema);
-    context._documents = this._documents;
-    return context;
-  };
-
-  RelayCompilerContext.prototype.add = function add(node) {
-    require('fbjs/lib/invariant')(!this._documents.has(node.name), 'RelayCompilerContext: Duplicate document named `%s`. GraphQL ' + 'fragments and roots must have unique names.', node.name);
-    return this._update(this._documents.set(node.name, new Document({
-      name: node.name,
-      node: node
-    })));
-  };
-
-  RelayCompilerContext.prototype.addAll = function addAll(nodes) {
-    return nodes.reduce(function (ctx, definition) {
-      return ctx.add(definition);
-    }, this);
-  };
-
-  RelayCompilerContext.prototype.addError = function addError(name, error) {
-    var record = this._get(name);
-    var errors = record.get('errors');
-    if (errors) {
-      errors = errors.push(error);
-    } else {
-      errors = ImmutableList([error]);
-    }
-    return this._update(this._documents.set(name, record.set('errors', errors)));
-  };
-
-  RelayCompilerContext.prototype.get = function get(name) {
-    var record = this._documents.get(name);
-    return record && record.get('node');
-  };
-
-  RelayCompilerContext.prototype.getFragment = function getFragment(name) {
-    var record = this._documents.get(name);
-    var node = record && record.get('node');
-    if (!(node && node.kind === 'Fragment')) {
-      var childModule = name.substring(0, name.lastIndexOf('_'));
-      throw createUserError('Relay cannot find fragment `%s`.' + ' Please make sure the fragment exists in `%s`', name, childModule);
-    }
-    return node;
-  };
-
-  RelayCompilerContext.prototype.getRoot = function getRoot(name) {
-    var record = this._documents.get(name);
-    var node = record && record.get('node');
-    require('fbjs/lib/invariant')(node && node.kind === 'Root', 'RelayCompilerContext: Expected `%s` to be a root, got `%s`.', name, node && node.kind);
-    return node;
-  };
-
-  RelayCompilerContext.prototype.getErrors = function getErrors(name) {
-    return this._get(name).get('errors');
-  };
-
-  RelayCompilerContext.prototype.remove = function remove(name) {
-    return this._update(this._documents['delete'](name));
-  };
-
-  RelayCompilerContext.prototype._get = function _get(name) {
-    var record = this._documents.get(name);
-    require('fbjs/lib/invariant')(record, 'RelayCompilerContext: Unknown document `%s`.', name);
-    return record;
-  };
-
-  RelayCompilerContext.prototype._update = function _update(documents) {
-    var context = new RelayCompilerContext(this.schema);
-    context._documents = documents;
-    return context;
-  };
-
-  return RelayCompilerContext;
-}();
-
-module.exports = RelayCompilerContext;

package/lib/RelayCompilerUserError.js

@@ -1,30 +0,0 @@
-/**
- * Copyright (c) 2013-present, Facebook, Inc.
- * All rights reserved.
- *
- * This source code is licensed under the BSD-style license found in the
- * LICENSE file in the root directory of this source tree. An additional grant
- * of patent rights can be found in the PATENTS file in the same directory.
- *
- * @providesModule RelayCompilerUserError
- * 
- * @format
- */
-
-'use strict';
-
-var createUserError = function createUserError(format) {
-  for (var _len = arguments.length, args = Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
-    args[_key - 1] = arguments[_key];
-  }
-
-  var index = 0;
-  var formatted = format.replace(/%s/g, function (match) {
-    return args[index++];
-  });
-  var err = new Error(formatted);
-  err.isRelayUserError = true;
-  return err;
-};
-
-module.exports = { createUserError: createUserError };

package/lib/RelayConsoleReporter.js

@@ -1,40 +0,0 @@
-/**
- * Copyright (c) 2013-present, Facebook, Inc.
- * All rights reserved.
- *
- * This source code is licensed under the BSD-style license found in the
- * LICENSE file in the root directory of this source tree. An additional grant
- * of patent rights can be found in the PATENTS file in the same directory.
- *
- * @providesModule RelayConsoleReporter
- * 
- * @format
- */
-
-'use strict';
-
-var _classCallCheck3 = _interopRequireDefault(require('babel-runtime/helpers/classCallCheck'));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { 'default': obj }; }
-
-var RelayConsoleReporter = function () {
-  function RelayConsoleReporter(options) {
-    (0, _classCallCheck3['default'])(this, RelayConsoleReporter);
-
-    this._verbose = options.verbose;
-  }
-
-  RelayConsoleReporter.prototype.reportError = function reportError(caughtLocation, error) {
-    process.stdout.write(require('chalk').red('ERROR:\n' + error.message + '\n'));
-    if (this._verbose) {
-      var frames = error.stack.match(/^ {4}at .*$/gm);
-      if (frames) {
-        process.stdout.write(require('chalk').gray('From: ' + caughtLocation + '\n' + frames.join('\n') + '\n'));
-      }
-    }
-  };
-
-  return RelayConsoleReporter;
-}();
-
-module.exports = RelayConsoleReporter;