@luvio/graphql-parser 0.98.0 → 0.99.2

package/src/__tests__/metaschema.spec.ts

@@ -0,0 +1,230 @@
+import { gql, referenceMap } from '../gql';
+import { metaschemaMapper } from '../metaschema';
+
+describe('metaschema mapper', () => {
+    it('should produce a equivalent metaschema AST when called with the legacy AST', () => {
+        const ref1 = gql`
+            query {
+                uiapi {
+                    query {
+                        Account(where: { Name: { like: "Account1" } }) @connection {
+                            edges {
+                                node @resource(type: "Record") {
+                                    Name {
+                                        value
+                                        displayValue
+                                    }
+                                }
+                            }
+                            ...conFragment
+                        }
+                    }
+                }
+            }
+
+            fragment conFragment on AccountConnection {
+                edges {
+                    node @resource(type: "Record") {
+                        CreatedBy @resource(type: "Record") {
+                            Id
+                            Name {
+                                value
+                                displayValue
+                            }
+                        }
+                    }
+                }
+            }
+        `;
+
+        const doc1 = referenceMap.get(ref1);
+
+        const ref2 = gql`
+            query {
+                uiapi {
+                    query {
+                        Account(where: { Name: { like: "Account1" } })
+                            @category(name: "recordQuery") {
+                            edges {
+                                node {
+                                    Name {
+                                        value
+                                        displayValue
+                                    }
+                                }
+                            }
+                            ...conFragment
+                        }
+                    }
+                }
+            }
+
+            fragment conFragment on AccountConnection {
+                edges {
+                    node {
+                        CreatedBy @category(name: "parentRelationship") {
+                            Id
+                            Name {
+                                value
+                                displayValue
+                            }
+                        }
+                    }
+                }
+            }
+        `;
+        const doc2 = referenceMap.get(ref2);
+
+        metaschemaMapper(doc1);
+
+        expect(doc1).toStrictEqual(doc2);
+    });
+
+    it('should produce a equivalent metaschema AST when query has multiple entities', () => {
+        const ref1 = gql`
+            query {
+                uiapi {
+                    query {
+                        TimeSheet @connection {
+                            edges {
+                                node @resource(type: "Record") {
+                                    CreatedBy @resource(type: "Record") {
+                                        Email {
+                                            value
+                                            displayValue
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                        User @connection {
+                            edges {
+                                node @resource(type: "Record") {
+                                    CreatedBy @resource(type: "Record") {
+                                        Email {
+                                            value
+                                            displayValue
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        `;
+        const doc1 = referenceMap.get(ref1);
+
+        const ref2 = gql`
+            query {
+                uiapi {
+                    query {
+                        TimeSheet @category(name: "recordQuery") {
+                            edges {
+                                node {
+                                    CreatedBy @category(name: "parentRelationship") {
+                                        Email {
+                                            value
+                                            displayValue
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                        User @category(name: "recordQuery") {
+                            edges {
+                                node {
+                                    CreatedBy @category(name: "parentRelationship") {
+                                        Email {
+                                            value
+                                            displayValue
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        `;
+        const doc2 = referenceMap.get(ref2);
+
+        metaschemaMapper(doc1);
+
+        expect(doc1).toStrictEqual(doc2);
+    });
+
+    it('should leave any non - legacy directives intact', () => {
+        const ref1 = gql`
+            query myQuery($var1: Boolean!, $var2: Boolean!) {
+                uiapi {
+                    query {
+                        TimeSheet @include(if: $var1) @connection {
+                            edges {
+                                node @resource(type: "Record") {
+                                    CreatedBy @resource(type: "Record") {
+                                        Email {
+                                            value
+                                            displayValue
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                        User @connection @skip(if: $var2) {
+                            edges {
+                                node @resource(type: "Record") {
+                                    CreatedBy @resource(type: "Record") {
+                                        Email {
+                                            value
+                                            displayValue
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        `;
+        const doc1 = referenceMap.get(ref1);
+
+        const ref2 = gql`
+            query myQuery($var1: Boolean!, $var2: Boolean!) {
+                uiapi {
+                    query {
+                        TimeSheet @include(if: $var1) @category(name: "recordQuery") {
+                            edges {
+                                node {
+                                    CreatedBy @category(name: "parentRelationship") {
+                                        Email {
+                                            value
+                                            displayValue
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                        User @category(name: "recordQuery") @skip(if: $var2) {
+                            edges {
+                                node {
+                                    CreatedBy @category(name: "parentRelationship") {
+                                        Email {
+                                            value
+                                            displayValue
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        `;
+        const doc2 = referenceMap.get(ref2);
+
+        metaschemaMapper(doc1);
+
+        expect(doc1).toStrictEqual(doc2);
+    });
+});

package/src/gql.ts

@@ -0,0 +1,237 @@
+/**
+ * Exposes a tagged template literal to parse graphql operation string
+ * "gql" is the only publicly exposed method
+ * @module gql
+ */
+import type { DefinitionNode, DocumentNode } from 'graphql/language';
+import { parse } from 'graphql/language';
+import { stripIgnoredCharacters } from 'graphql/utilities';
+import { ObjectCreate, ObjectKeys } from './util/language';
+import { metaschemaMapper } from './metaschema';
+
+export type AstResolver = (astReference: any) => DocumentNode | undefined;
+
+/**
+ * we should look into optimizing this before it turns into a memory hog
+ * weakmaps, or limiting the size of the cache, or something
+ */
+export const docMap = new Map<string, DocumentNode>();
+/**
+ * Opaque reference map to return keys to userland
+ * As a user shouldn't have access to the Document
+ */
+export const referenceMap = new WeakMap<Object, DocumentNode>();
+
+export let addMetaschemaDirectives: boolean = false;
+
+/**
+ * Strips characters that are not significant to the validity or execution
+ * of a GraphQL document:
+ *   - UnicodeBOM
+ *   - WhiteSpace
+ *   - LineTerminator
+ *   - Comment
+ *   - Comma
+ *   - BlockString indentation
+ */
+function operationKeyBuilder(inputString: string): string {
+    return stripIgnoredCharacters(inputString);
+}
+
+/**
+ * Returns document node if cached or else update the cache and return the document node
+ * @param inputString - operation string
+ * @returns DocumentNode
+ */
+function parseDocument(inputString: string): DocumentNode | null {
+    const operationKey = operationKeyBuilder(inputString);
+    const cachedDoc = docMap.get(operationKey);
+    if (cachedDoc !== undefined) {
+        return cachedDoc;
+    }
+    // parse throws an GraphQLError in case of invalid query, should this be in try/catch?
+    const parsedDoc = parse(inputString);
+    if (!parsedDoc || parsedDoc.kind !== 'Document') {
+        if (process.env.NODE_ENV !== 'production') {
+            throw new Error('Invalid graphql doc');
+        }
+        return null;
+    }
+
+    // in-place substitution for removal of legacy and adding metaschema directives
+    if (addMetaschemaDirectives) {
+        metaschemaMapper(parsedDoc);
+    }
+
+    const parsedDocNoLoc = stripLocation(parsedDoc);
+
+    docMap.set(operationKey, parsedDocNoLoc);
+
+    return parsedDocNoLoc;
+}
+
+/**
+ * If the input string has fragment substitution
+ * Insert the fragments AST to the query document node
+ */
+function insertFragments(doc: DocumentNode, fragments: DefinitionNode[]): DocumentNode {
+    fragments.forEach((fragment) => {
+        // @ts-ignore
+        // graphql describes definitions as "readonly"
+        // so we aren't supposed to mutate the document node
+        // but instead of parsing the fragment again, we substitute it's definition in the document node
+        doc.definitions.push(fragment);
+    });
+    return doc;
+}
+
+function createReference(document: DocumentNode): object {
+    const key = ObjectCreate(null);
+    referenceMap.set(key, document);
+
+    return key;
+}
+
+/**
+ * Insert string and fragment substitutions with the actual nodes
+ * @param inputString
+ * @param substitutions - string | fragment DocumentNode
+ * @returns { operation string, fragment docs [] }
+ */
+export function processSubstitutions(
+    inputString: ReadonlyArray<string>,
+    substitutions: (string | object)[]
+): { operationString: string; fragments: DefinitionNode[] } | null {
+    let outputString = '';
+    const fragments: DefinitionNode[] = [];
+    const subLength = substitutions.length;
+
+    for (let i = 0; i < subLength; i++) {
+        const substitution = substitutions[i];
+        outputString += inputString[i];
+
+        if (typeof substitution === 'string' || typeof substitution === 'number') {
+            outputString += substitution;
+        } else if (typeof substitution === 'object') {
+            const doc = referenceMap.get(substitution);
+
+            if (doc === undefined) {
+                if (process.env.NODE_ENV !== 'production') {
+                    throw new Error('Invalid substitution fragment');
+                }
+                return null;
+            }
+
+            for (const def of doc.definitions) {
+                fragments.push(def);
+            }
+        } else {
+            if (process.env.NODE_ENV !== 'production') {
+                throw new Error('Unsupported substitution type');
+            }
+            return null;
+        }
+    }
+
+    return {
+        operationString: outputString + inputString[subLength],
+        fragments,
+    };
+}
+
+/**
+ * strips Document node and nested definitions of location references
+ */
+export function stripLocation(node: any) {
+    if (node.loc) {
+        delete node.loc;
+    }
+    const keys = ObjectKeys(node);
+    const keysLength = keys.length;
+
+    if (keysLength === 0) {
+        return node;
+    }
+
+    for (const key of keys) {
+        const subNode = node[key];
+        if (subNode && typeof subNode === 'object') {
+            stripLocation(subNode);
+        }
+    }
+
+    return node;
+}
+
+/**
+ *
+ * @param astReference - ast reference passed from user land
+ */
+export const astResolver: AstResolver = function (astReference: any) {
+    return referenceMap.get(astReference);
+};
+
+/**
+ *
+ * @param literals - operation query string
+ * @param subs - all other substitutions
+ * @returns an opaque reference to the parsed document
+ */
+export function gql(
+    literals: ReadonlyArray<string> | string,
+    ...subs: (string | object)[]
+): object | null {
+    let inputString: string;
+    let inputSubstitutionFragments: DefinitionNode[];
+
+    if (!literals) {
+        if (process.env.NODE_ENV !== 'production') {
+            throw new Error('Invalid query');
+        }
+        return null;
+    } else if (typeof literals === 'string') {
+        inputString = literals.trim();
+        inputSubstitutionFragments = [];
+    } else {
+        // called as template literal
+        const sub = processSubstitutions(literals, subs);
+        // if invalid fragment references found
+        if (sub === null) {
+            return null;
+        }
+
+        const { operationString, fragments } = sub;
+        inputString = operationString.trim();
+        inputSubstitutionFragments = fragments;
+    }
+
+    if (inputString.length === 0) {
+        if (process.env.NODE_ENV !== 'production') {
+            throw new Error('Invalid query');
+        }
+        return null;
+    }
+
+    const document = parseDocument(inputString);
+
+    if (document === null) {
+        return null;
+    }
+
+    if (inputSubstitutionFragments.length === 0) {
+        return createReference(document);
+    }
+
+    return createReference(insertFragments(document, inputSubstitutionFragments));
+}
+
+/**
+ * Enable the parser to add corresponding metaschema directives for backwards compatibility
+ */
+export function enableAddMetaschemaDirective() {
+    addMetaschemaDirectives = true;
+}
+
+export function disableAddMetaschemaDirective() {
+    addMetaschemaDirectives = false;
+}

package/src/main.ts

@@ -64,6 +64,13 @@ export type {
 export { ASTVisitor, parse, Kind, print, visit } from 'graphql/language';
 export { isScalarType } from 'graphql/type';
 export { stripIgnoredCharacters } from 'graphql/utilities';
+export {
+    gql,
+    enableAddMetaschemaDirective,
+    disableAddMetaschemaDirective,
+    astResolver,
+} from './gql';
+export type { AstResolver } from './gql';
 
 /**
  * @deprecated - Schema-backed adapters will use standard graphql types re-exported from @luvio/graphql

package/src/metaschema.ts

@@ -0,0 +1,162 @@
+/**
+ * Add metaschema annotations to their corresponding custom notation counterparts
+ * @module metaschemaMapper
+ */
+import type {
+    DefinitionNode,
+    DirectiveNode,
+    DocumentNode,
+    FragmentSpreadNode,
+    SelectionNode,
+    SelectionSetNode,
+    TypeSystemDefinitionNode,
+    TypeSystemExtensionNode,
+} from 'graphql/language';
+import { CUSTOM_DIRECTIVE_CONNECTION, CUSTOM_DIRECTIVE_RESOURCE } from './constants';
+
+const DIRECTIVE_RECORD_CATEGORY = {
+    kind: 'Directive',
+    name: {
+        kind: 'Name',
+        value: 'category',
+    },
+    arguments: [
+        {
+            kind: 'Argument',
+            name: {
+                kind: 'Name',
+                value: 'name',
+            },
+            value: {
+                kind: 'StringValue',
+                value: 'recordQuery',
+                block: false,
+            },
+        },
+    ],
+};
+
+const DIRECTIVE_PARENT_CATEGORY = {
+    kind: 'Directive',
+    name: {
+        kind: 'Name',
+        value: 'category',
+    },
+    arguments: [
+        {
+            kind: 'Argument',
+            name: {
+                kind: 'Name',
+                value: 'name',
+            },
+            value: {
+                kind: 'StringValue',
+                value: 'parentRelationship',
+                block: false,
+            },
+        },
+    ],
+};
+
+function substituteDirectives(
+    directives: ReadonlyArray<DirectiveNode>,
+    index: number,
+    nodeName: string | undefined
+): void {
+    if (directives[index].name.value === CUSTOM_DIRECTIVE_CONNECTION) {
+        // replace the custom directive node with the metaschema directive node
+        // @ts-ignore - Document is read only
+        directives[index] = DIRECTIVE_RECORD_CATEGORY;
+    } else if (directives[index].name.value === CUSTOM_DIRECTIVE_RESOURCE) {
+        // node gets its type from @category recordQuery
+        if (nodeName === 'node') {
+            // @ts-ignore - Document is read only
+            directives.splice(index, 1);
+        } else {
+            // @ts-ignore - Document is read only
+            directives[index] = DIRECTIVE_PARENT_CATEGORY;
+        }
+    }
+}
+
+/**
+ * Returns true if the directive node is of legacy type
+ * @param node : Directive node
+ * @returns
+ */
+function isCustomDirective(node: DirectiveNode): boolean {
+    return (
+        node.name.value === CUSTOM_DIRECTIVE_CONNECTION ||
+        node.name.value === CUSTOM_DIRECTIVE_RESOURCE
+    );
+}
+
+type TraverseSelectionSetNode = SelectionSetNode | undefined;
+
+/**
+ * Traverses a selection set and it's nested selections,
+ * to find any legacy custom directives and substitute them with metaschema directives
+ * @param node - SelectionSetNode
+ * @returns SelectionSetNode
+ */
+function traverseSelectionSet(node: TraverseSelectionSetNode): TraverseSelectionSetNode {
+    if (node === undefined) {
+        return;
+    }
+
+    for (const selection of node.selections) {
+        // FragmentSpreadNode doesn't have a selection set
+        // which should be handled at this methods entry point
+        const { directives, selectionSet } = selection as Exclude<
+            SelectionNode,
+            FragmentSpreadNode
+        >;
+        let selectionName: string | undefined;
+
+        if (selection.kind !== 'InlineFragment') {
+            selectionName = selection.name.value;
+        }
+
+        if (directives !== undefined && directives.length > 0) {
+            // we follow this pattern instead of map to preserve the order of directives
+            // order of directives may be significant as per graphql spec
+            const index = directives.findIndex(isCustomDirective);
+
+            if (index !== -1) {
+                substituteDirectives(directives, index, selectionName);
+            }
+        }
+
+        traverseSelectionSet(selectionSet);
+    }
+    return node;
+}
+
+/**
+ * Accepts a document node and replaces the legacy custom directives with metaschema directives "in-place"
+ * @param doc
+ */
+export function metaschemaMapper(doc: DocumentNode): void {
+    // this method is only callable for Executable definitions
+    // such as Operations and Fragments
+    // so we have to explicitly cast the definitions for ts
+    const { definitions }: { definitions: unknown } = doc;
+
+    for (const def of definitions as ReadonlyArray<
+        Exclude<DefinitionNode, TypeSystemDefinitionNode | TypeSystemExtensionNode>
+    >) {
+        const { directives, selectionSet } = def;
+
+        if (directives !== undefined && directives.length > 0) {
+            // we are making an assumption here that only one custom directive can be applied to a node
+            // we can revisit if this condition changes
+            const index = directives.findIndex(isCustomDirective);
+
+            if (index !== -1) {
+                substituteDirectives(directives, index, undefined);
+            }
+        }
+
+        traverseSelectionSet(selectionSet);
+    }
+}

package/src/util/language.ts

@@ -0,0 +1,10 @@
+const { isArray } = Array;
+const { create, keys } = Object;
+
+export {
+    // Array
+    isArray as ArrayIsArray,
+    // Object
+    keys as ObjectKeys,
+    create as ObjectCreate,
+};