@khanacademy/graphql-flow 0.0.1

package/.babelrc

@@ -0,0 +1,6 @@
+{
+	"presets": [
+		"@babel/preset-flow",
+		["@babel/preset-env", { "targets": { "node": "16" } }]
+	]
+}

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@1.7.0/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.eslintignore

@@ -0,0 +1,2 @@
+flow-typed
+dist

package/.eslintrc.js

@@ -0,0 +1,10 @@
+module.exports = {
+    extends: ['@khanacademy'],
+    root: true,
+    parser: '@babel/eslint-parser',
+    plugins: ['flowtype-errors'],
+    rules: {
+        'prettier/prettier': ['error', {singleQuote: true}],
+        'flowtype-errors/uncovered': 2,
+    },
+};

package/.flowconfig

@@ -0,0 +1,13 @@
+[ignore]
+; The 'resolve' package bundles test files that it really shouldn't
+.*/resolve/test/resolver/malformed_package_json/
+[include]
+
+[libs]
+flow-typed/
+
+[lints]
+
+[options]
+
+[strict]

package/.github/actions/filter-files/action.yml

@@ -0,0 +1,37 @@
+name: 'Filter files'
+description: 'Filter the list of changed files'
+inputs:
+  changed-files:
+    description: 'jsonified list of changed files from setup'
+    required: true
+  files:
+    description: 'comma-separated list of files to check for'
+    required: false
+  extensions:
+    description: 'comma-separated list of extensions to check for'
+    required: false
+outputs:
+  filtered:
+    description: 'The jsonified list of files that match'
+    value: ${{ steps.result.outputs.result }}
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/github-script@v6
+      id: result
+      with:
+        script: |
+          const extensionsRaw = "${{ inputs.extensions }}";
+          const exactFilesRaw = "${{ inputs.files }}";
+          const inputFiles = JSON.parse(`${{ inputs.changed-files }}`);
+          const extensions = extensionsRaw.trim() ? extensionsRaw.split(',') : [];
+          const exactFiles = exactFilesRaw.trim() ? exactFilesRaw.split(',') : [];
+
+          const result = inputFiles.filter(name => {
+            return extensions.some(ext => name.endsWith(ext)) || (
+              exactFiles.includes(name)
+            )
+          })
+          console.log(`Filtered Files: ${JSON.stringify(result)}`)
+          return result;
+        result-encoding: json

package/.github/actions/full-or-limited/action.yml

@@ -0,0 +1,27 @@
+name: Full or Limited
+description:  Do a full run if certain files have changed, or a limited run of some others have changed
+inputs:
+  full-trigger:
+    description: A jsonified Array of string files that would trigger a full run
+    required: true
+  limited-trigger:
+    description: A jsonified Array of string files that should be passed to a limited run
+    required: true
+  full:
+    description: The command to run if a full run is triggered
+  limited:
+    description: The command to run, with {} replaced with the list of files to run on.
+runs:
+  using: "composite"
+  steps:
+    - name: Full run
+      if: inputs.full-trigger != '[]'
+      run: ${{ inputs.full }}
+      shell: bash
+
+    - name: Limited run
+      if: inputs.full-trigger == '[]' && inputs.limited-trigger != '[]'
+      uses: ./.github/actions/json-args
+      with:
+        list: ${{ inputs.limited-trigger }}
+        run: ${{ inputs.limited }}

package/.github/actions/json-args/action.yml

@@ -0,0 +1,32 @@
+name: 'Pass a jsonified-list of files as shell arguments'
+description: 'Because file names with spaces are the worst'
+inputs:
+  list:
+    description: A jsonified Array of string file names
+    required: true
+  run:
+    description: "a command to run, where the literal '{}' will be replaced with the files as individual arguments. If no '{}' is provided, the files will be appended."
+    required: true
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/github-script@v6
+      with:
+        script: |
+          const listRaw = `${{ inputs.list }}`;
+          const files = JSON.parse(listRaw);
+          const {execSync} = require('child_process');
+          if (files.some(name => name.match(/['"]/))) {
+            throw new Error(`Not going to mess with file names that have quotes in them.`)
+          }
+          const filesList = files.map(name => `"${name}"`).join(' ')
+          let cmd = `${{ inputs.run }}`;
+          if (cmd.includes('{}')) {
+            cmd = cmd.replace('{}', filesList)
+          } else {
+            cmd += ' ' + filesList;
+          }
+          console.log(`Running: ${cmd}`);
+          execSync(cmd, {
+            stdio: 'inherit',
+          })

package/.github/actions/setup/action.yml

@@ -0,0 +1,28 @@
+name: 'Setup'
+description: 'Perform various shared setup tasks'
+inputs:
+  node-version:
+    description: 'Node version to use'
+    required: false
+    default: '16.x'
+outputs:
+  changed_files:
+    description: "List of files changed in this PR, in JSON format"
+    value: ${{ steps.changed.outputs.added_modified }}
+runs:
+  using: "composite"
+  steps:
+    - name: Use Node.js ${{ inputs.node-version }}
+      uses: actions/setup-node@v3
+      id: node
+      with:
+        node-version: ${{ inputs.node-version }}
+        cache: yarn
+    - name: Install dependencies
+      run: yarn install --frozen-lockfile
+      shell: bash
+    - name: Get All Changed Files
+      uses: jaredly/get-changed-files@absolute
+      id: changed
+      with:
+        format: json

package/.github/workflows/changeset-release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+# This workflow will run changesets depending on two different scenarios:
+#
+# 1. If we are landing a specific commit into main (Author PR), then
+#    changesets will check if there are changes verifying the Markdown files
+#    generated automatically:
+#
+#    a) There are new versions and there's NO Release PR, then the changesets
+#    action will create a new Release PR.
+#
+#    b) There's a Release PR, then the changesets action will update the
+#    existing Release PR with the new commit.
+#
+#    NOTE: (in both cases, changesets will modify the new version in
+#    package.json for each package, and will remove the MD files as part of the
+#    Release PR).
+#
+# 2. If we are landing the Release PR into main, then the changesets action
+#    will publish the changes to npm.
+#
+# For more info about this workflow, see:
+# https://github.com/changesets/action#usage
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - uses: ./.github/actions/setup
+        with:
+          node-version: 12.x
+
+      - name: Create Release Pull Request or Publish to npm
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          publish: yarn publish:ci
+        env:
+          # We use a Personal Access Token here rather than the GITHUB_TOKEN
+          # so that it will trigger our other actions. The token has to be on
+          # the account of someone with appropriate access levels and given the
+          # repo scope.
+          GITHUB_TOKEN: ${{ secrets.KHAN_ACTIONS_BOT_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Send a Slack notification for web if a publish happens
+        if: steps.changesets.outputs.published == 'true'
+        uses: rtCamp/action-slack-notify@v2
+        env:
+          SLACK_WEBHOOK: ${{ secrets.SLACK_FEIWEB_WEBHOOK }}
+          SLACK_CHANNEL: frontend-infra-web
+          SLACK_MSG_AUTHOR: ${{ github.event.pull_request.user.login }}
+          SLACK_USERNAME: GithubGoose
+          SLACK_ICON_EMOJI: ":goose:"
+          SLACK_MESSAGE: "A new version of ${{ github.event.repository.name }} was published! 🎉 \nRelease notes → https://github.com/Khan/${{ github.event.repository.name }}/releases/"
+          SLACK_TITLE: "New Graphql-Flow release!"
+          SLACK_FOOTER: Graphql-Flow Slack Notification
+          MSG_MINIMAL: true
+
+      - name: Send a Slack notification for mobile if a publish happens
+        if: steps.changesets.outputs.published == 'true'
+        uses: rtCamp/action-slack-notify@v2
+        env:
+          SLACK_WEBHOOK: ${{ secrets.SLACK_FEIMOBILE_WEBHOOK }}
+          SLACK_CHANNEL: frontend-infra-mobile
+          SLACK_MSG_AUTHOR: ${{ github.event.pull_request.user.login }}
+          SLACK_USERNAME: GithubGoose
+          SLACK_ICON_EMOJI: ":goose:"
+          SLACK_MESSAGE: "A new version of ${{ github.event.repository.name }} was published! 🎉 \nRelease notes → https://github.com/Khan/${{ github.event.repository.name }}/releases/"
+          SLACK_TITLE: "New Graphql-Flow release!"
+          SLACK_FOOTER: Graphql-Flow Slack Notification
+          MSG_MINIMAL: true

package/.github/workflows/pr-checks.yml

@@ -0,0 +1,64 @@
+name: Lint & Test
+
+on:
+  pull_request:
+    # edited is needed because that's the trigger when the base branch is
+    # changed on a PR
+    # The rest are the defaults.
+    types: [edited, opened, synchronize, reopened]
+
+jobs:
+  lint_and_test:
+    name: Lint & Test
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        node-version: [16.x]
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ./.github/actions/setup
+      id: setup
+      with:
+        node-version: ${{ matrix.node-version }}
+
+    - id: js-files
+      name: Find .js changed files
+      uses: ./.github/actions/filter-files
+      with:
+        changed-files: ${{ steps.setup.outputs.changed_files }}
+        extensions: '.js'
+
+    - name: Run Flow
+      if: steps.js-files.outputs.filtered != '[]'
+      run: yarn flow
+
+    - id: eslint-reset
+      uses: ./.github/actions/filter-files
+      name: Files that would trigger a full eslint run
+      with:
+        changed-files: ${{ steps.setup.outputs.changed_files }}
+        files: '.eslintrc.js,package.json,.eslintignore'
+
+    - name: Eslint
+      uses: ./.github/actions/full-or-limited
+      with:
+        full-trigger: ${{ steps.eslint-reset.outputs.filtered }}
+        full: yarn eslint
+        limited-trigger: ${{ steps.js-files.outputs.filtered }}
+        limited: yarn eslint {}
+
+    - id: jest-reset
+      uses: ./.github/actions/filter-files
+      name: Files that would trigger a full jest run
+      with:
+        changed-files: ${{ steps.setup.outputs.changed_files }}
+        files: 'package.json,package-lock.json'
+
+    - name: Jest
+      uses: ./.github/actions/full-or-limited
+      with:
+        full-trigger: ${{ steps.jest-reset.outputs.filtered }}
+        full: yarn jest
+        limited-trigger: ${{ steps.js-files.outputs.filtered }}
+        limited: yarn jest --findRelatedTests {}

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+    "parser": "flow",
+    "tabWidth": 4,
+    "trailingComma": "all",
+    "bracketSpacing": false,
+    "singleQuote": true
+}

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @khanacademy/graphql-flow
+
+## 0.0.1
+
+### Patch Changes
+
+-   a4ae2c8: First release! Hoping this works.
+-   a3e8461: Make a simple change to check out the changeset stuff
+
+## 0.0.1
+
+### Patch Changes
+
+-   a64c3c7: First release! Hoping this works.

package/Readme.md

@@ -0,0 +1,172 @@
+# Graphql Flow Generation
+
+This is a tool for generating flow types from graphql queries in javascript frontends.
+
+The core of this tool is the `documentToFlowTypes` function, which takes a `DocumentNode` (such as is returned by the `graphql-tag` package) as well as your backend's graphql schema (see below for instructions on how to produce this), and produces a list of stringified flow types, one for each query and mutation defined in that graphql block.
+
+It looks something like this:
+
+```js
+import gql from 'graphql-tag';
+import {documentToFlowTypes, schemaFromIntrospectionData} from 'graphql-flow';
+import myIntrospectionData from './server-introspection-response.json';
+
+const schema = schemaFromIntrospectionData(myIntrospectionData);
+
+const MyQuery = gql`
+    query SomeQuery {
+        human(id: "Han Solo") {
+            id
+            name
+            homePlanet
+            friends {
+                name
+            }
+        }
+    }
+`;
+
+console.log(documentToFlowTypes(MyQuery, schema))
+/*
+export type SomeQueryResponseType = {|
+    human: ?{|
+        id: string,
+        name: ?string,
+        homePlanet: ?string,
+        friends: ?$ReadOnlyArray<?{|
+            name: ?string
+        |}>,
+    |}
+|};
+*/
+```
+
+If you already have a setup whereby you collect all of your graphql literals, that may be all you need!
+
+Otherwise, we provide a way to hook into jest to automatically collect your queries and generate the types.
+
+## Options for `documentToFlowTypes`
+
+```js
+{
+    // Use nullable types where the graphql type is nullable. Included for legacy compatability,
+    // will probably remove once the mobile repo no longer needs it.
+    strictNullability: boolean = true,
+    // Output `$ReadOnlyArray<>` instead of `Array<>`, for stricter flow typing. On by default.
+    readOnlyArray: boolean = true,
+    // A mapping of custom scalar names to the underlying json representation.
+    scalars: {[key: string]: 'string' | 'boolean' | 'number'}
+}
+```
+
+## Using jest to do the heavy lifting:
+
+### jest-setup.js
+
+Add the following snippet to your jest-setup.js
+
+```js
+if (process.env.GRAPHQL_FLOW) {
+    jest.mock('graphql-tag', () => {
+        const introspectionData = jest.requireActual(
+            './server-introspection-response.json',
+        );
+
+        return jest.requireActual('../tools/graphql-flow/jest-mock-graphql-tag.js')(
+            introspectionData,
+            {
+                pragma: '# @autogen\n',
+                loosePragma: '# @autogen-loose\n',
+            }
+        );
+    });
+}
+```
+
+That will mock out the `graphql-tag` function, so that everywhere you call 'gql`some-query`', we'll pick it up and
+generate a type for it! As written, the mocking only happens if the `GRAPHQL_FLOW` env variable is set, so that it won't run every time.
+
+By default, all queries are processed. To have them 'opt-in', use the `pragma` and `loosePragma` options. Queries with `loosePragma` in the source will have types generated that ignore nullability.
+
+### Ensure all files with queries get processed by jest
+
+Then you'll want to make a pseudo-'test' that makes sure to 'require' all of the files that define queries, so that
+jest will process them and our mock will see them. 
+```js
+// generate-types.test.js
+import {findFilesWithQueries} from '../tools/graphql-flow/find-files-with-gql';
+
+if (process.env.GRAPHQL_FLOW) {
+    findFilesWithQueries(path.join(__dirname, '..')).forEach(name => {
+        require(name);
+    });
+
+    it('should have found queries', () => {
+        const gql = require('graphql-tag')
+        expect(gql.collectedQueries.length).toBeGreaterThan(0)
+    })
+} else {
+    it(`not generating graphql types because the env flag isn't set`, () => {
+        // not doing anything because the env flag isn't set.
+    })
+}
+```
+
+### Run that test to generate the types!
+
+You can add a script to package.json, like so:
+```json
+    "scripts": {
+        "generate-types": "env GRAPHQL_FLOW=1 jest generate-types.test.js"
+    }
+```
+
+And then `yarn generate-types` or `npm run generate-types` gets your types generated!
+
+🚀
+
+### Options for the `jest-mock-graphql-tag.js` helper:
+
+```js
+{
+    // These are from the `documentToFlowTypes` options object above
+    strictNullability: boolean = true,
+    readOnlyArray: boolean = true,
+    scalars: {[key: string]: 'string' | 'boolean' | 'number'}
+
+    // Specify an opt-in pragma that must be present in a graphql string source
+    // in order for it to be picked up and processed
+    // e.g. set this to `"# @autogen\n"` to only generate types for queries that
+    // have the comment `# @autogen` in them.
+    pragma?: string,
+    // Specify a pragma that will turn off `strictNullability` for that
+    // source file. e.g. `"# @autogen-loose\n"`.
+    loosePragma?: string,
+    // If neither pragma nor loosePragma are specified, all graphql documents
+    // that contain a query or mutation will be processed.
+}
+```
+
+## Introspecting your backend's graphql schema
+Here's how to get your backend's schema in the way that this tool expects, using the builtin 'graphql introspection query':
+
+```js
+import {getIntrospectionQuery} from 'graphql';
+import fs from 'fs';
+import fetch from 'node-fetch';
+
+const query = getIntrospectionQuery({descriptions: true}),
+
+const response = await fetch(`https://my-backend.com`, {
+    method: 'POST',
+    body: query,
+    headers: {
+        // You definitely shouldn't be allowing arbitrary queries without
+        // some strict access control.
+        'X-header-that-allows-arbitrary-queries': 'my-secret-key',
+    },
+    contentType: 'application/json',
+});
+const fullResponse = await response.json();
+fs.writeFileSync('./server-introspection-response.json', JSON.stringify(fullResponse.data, null, 2));
+```

package/build-copy-source.js

@@ -0,0 +1,28 @@
+// A simple script to copy over source files as *.js.flow
+// so that flow will be happy with the distributed package.
+
+const fs = require('fs');
+const path = require('path');
+
+// little recursive walk
+const walk = (dir, fn) => {
+    fs.readdirSync(dir).forEach((name) => {
+        const full = path.join(dir, name);
+        if (fs.statSync(full).isDirectory()) {
+            walk(full, fn);
+        } else {
+            fn(full);
+        }
+    });
+};
+
+const src = path.join(__dirname, 'src');
+const dist = path.join(__dirname, 'dist');
+
+walk(src, (name) => {
+    if (!name.endsWith('.js') || name.includes('__test__')) {
+        return;
+    }
+    const next = path.join(dist, path.relative(src, name)) + '.flow';
+    fs.copyFileSync(name, next);
+});

package/dist/enums.js

@@ -0,0 +1,57 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.scalarTypeToFlow = exports.enumTypeToFlow = exports.builtinScalars = void 0;
+
+var babelTypes = _interopRequireWildcard(require("@babel/types"));
+
+var _utils = require("./utils");
+
+function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function (nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
+
+function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { default: obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj.default = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
+
+/**
+ * Both input & output types can have enums & scalars.
+ */
+const enumTypeToFlow = (config, name) => {
+  const enumConfig = config.schema.enumsByName[name];
+  let combinedDescription = enumConfig.enumValues.map(n => `- ${n.name}` + (n.description ? '\n\n      ' + n.description.replace(/\n/g, '\n      ') : '')).join('\n');
+
+  if (enumConfig.description) {
+    combinedDescription = enumConfig.description + '\n\n' + combinedDescription;
+  }
+
+  return (0, _utils.maybeAddDescriptionComment)(combinedDescription, babelTypes.unionTypeAnnotation(enumConfig.enumValues.map(n => babelTypes.stringLiteralTypeAnnotation(n.name))));
+};
+
+exports.enumTypeToFlow = enumTypeToFlow;
+const builtinScalars = {
+  Boolean: 'boolean',
+  String: 'string',
+  DateTime: 'string',
+  Date: 'string',
+  ID: 'string',
+  Int: 'number',
+  Float: 'number'
+};
+exports.builtinScalars = builtinScalars;
+
+const scalarTypeToFlow = (config, name) => {
+  if (builtinScalars[name]) {
+    return babelTypes.genericTypeAnnotation(babelTypes.identifier(builtinScalars[name]));
+  }
+
+  const underlyingType = config.scalars[name];
+
+  if (underlyingType != null) {
+    return babelTypes.genericTypeAnnotation(babelTypes.identifier(underlyingType));
+  }
+
+  config.errors.push(`Unexpected scalar '${name}'! Please add it to the "scalars" argument at the callsite of 'generateFlowTypes()'.`);
+  return babelTypes.genericTypeAnnotation(babelTypes.identifier(`UNKNOWN_SCALAR["${name}"]`));
+};
+
+exports.scalarTypeToFlow = scalarTypeToFlow;