@xyd-js/gql 0.1.0-xyd.0

package/README.md

@@ -0,0 +1,3 @@
+# @xyd-js/gql
+
+Transform GraphQL into xyd markdown interface.

package/examples/basic/index.ts

@@ -0,0 +1,12 @@
+import path from 'path';
+
+import {gqlSchemaToReferences} from "../../src";
+
+// TODO: support multi graphql files
+// TODO: !!! CIRCULAR_DEPENDENCY !!!
+// TODO: sort by tag??
+(async () => {
+    const schemaLocation = path.join(process.cwd(), "./examples/basic/todo-app.graphqls")
+
+    const references = await gqlSchemaToReferences(schemaLocation)
+})()

package/examples/basic/schema.graphqls

@@ -0,0 +1,89 @@
+# TODO: !!! case with circular dependencies !!!
+
+"""
+A book type
+"""
+type Book {
+    """
+    The title of the book
+    """
+    title: String
+
+    """
+    The author of the book
+    """
+    author_name: String
+    #    author: Author
+}
+
+"""
+An author type
+"""
+type Author {
+    """
+    The name of the author
+    """
+    name: String
+
+    """
+    The books of the author
+    """
+    books: [String]
+    #    books: [Book]
+}
+
+"""
+A nested book type
+"""
+input NestedBook {
+    """
+    The date of the book
+    """
+    date: String
+}
+
+"""
+The input object for the getBook query
+"""
+input BookInput {
+    """
+    The title of the book
+    """
+    title: String
+
+    """
+    The author of the book
+    """
+    nestedBook: NestedBook
+}
+
+type Query {
+    #    books: [Book]
+    #    authors: [Author]
+    """
+    Get a book by title
+    """
+    getBook(
+        """
+        The title of the book
+        """
+        title: String
+
+        """
+        The author of the book
+        """
+        input: BookInput
+    ): Book
+}
+
+type Mutation {
+    """
+    Add a book
+    """
+    addBook(title: String, author: String): Book
+
+    """
+    Add an author
+    """
+    addAuthor(name: String): Author
+}

package/examples/basic/todo-app.graphqls

@@ -0,0 +1,184 @@
+# Define custom scalars for Date and ID
+scalar Date
+scalar ID
+
+# Define the User type
+"""
+A user type representing a user in the system
+"""
+type User {
+    """
+    The unique ID of the user
+    """
+    id: ID!
+
+    """
+    The name of the user
+    """
+    name: String!
+
+    """
+    The email of the user
+    """
+    email: String!
+
+    """
+    The list of todos created by the user
+    """
+    todos: [Todo!]!
+}
+
+# Define the Todo type
+"""
+A todo type representing a task to be done
+"""
+type Todo {
+    """
+    The unique ID of the todo
+    """
+    id: ID!
+
+    """
+    The title of the todo
+    """
+    title: String!
+
+    """
+    The description of the todo
+    """
+    description: String
+
+    """
+    The status of the todo (completed or not)
+    """
+    completed: Boolean!
+
+    """
+    The due date of the todo
+    """
+    dueDate: Date
+}
+
+# Define input types for creating and updating todos
+"""
+Input type for creating a new todo
+"""
+input CreateTodoInput {
+    title: String!
+    description: String
+    dueDate: Date
+    userId: ID!
+}
+
+"""
+Input type for updating an existing todo
+"""
+input UpdateTodoInput {
+    id: ID!
+    title: String
+    description: String
+    completed: Boolean
+    dueDate: Date
+}
+
+# Define the Query type
+"""
+---
+title: Query
+group: [Root Types]
+---
+
+The root query type
+"""
+type Query {
+    """
+    ---
+    title: Users
+    group: [GraphQL, Users]
+    ---
+
+    Get a list of all users
+    """
+    users: [User!]!
+
+    """
+    ---
+    title: User
+    group: [GraphQL, Users]
+    ---
+
+    Get a user by ID
+    """
+    user(id: ID!): User
+
+    """
+    ---
+    title: Todos
+    group: [GraphQL, Todos]
+    ---
+
+    Get a list of all todos
+    """
+    todos: [Todo!]!
+
+    """
+    ---
+    title: Todo
+    group: [GraphQL, Todos]
+    ---
+
+    Get a todo by ID
+    """
+    todo(id: ID!): Todo
+}
+
+# Define the Mutation type
+"""
+---
+title: Mutation
+group: [Root Types]
+---
+
+The root mutation type
+"""
+type Mutation {
+    """
+    ---
+    title: Create User
+    group: [GraphQL, Users]
+    ---
+
+    Create a new user
+    """
+    createUser(name: String!, email: String!): User!
+
+    """
+    ---
+    title: Create Todo
+    group: [GraphQL, Todos]
+    ---
+
+    Create a new todo
+    """
+    createTodo(input: CreateTodoInput!): Todo!
+
+    """
+    ---
+    title: Update Todo
+    group: [GraphQL, Todos]
+    ---
+
+    Update an existing todo
+    """
+    updateTodo(input: UpdateTodoInput!): Todo!
+
+    """
+    ---
+    title: Delete Todo
+    group: [GraphQL, Todos]
+    ---
+
+    Delete a todo by ID
+    """
+    deleteTodo(id: ID!): Boolean!
+}

package/index.ts

@@ -0,0 +1,3 @@
+export {
+    gqlSchemaToReferences
+} from "./src"

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@xyd-js/gql",
+  "version": "0.1.0-xyd.0",
+  "description": "",
+  "main": "./dist/index.js",
+  "type": "module",
+  "dependencies": {
+    "@graphql-markdown/core": "^1.12.0",
+    "@graphql-markdown/graphql": "^1.1.4",
+    "@graphql-markdown/types": "^1.4.0",
+    "graphql-config": "^5.1.2",
+    "gray-matter": "^4.0.3",
+    "json-to-graphql-query": "^2.3.0",
+    "@xyd-js/core": "0.1.0-xyd.0",
+    "@xyd-js/uniform": "0.1.0-xyd.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0"
+  },
+  "scripts": {
+    "clean": "rimraf build",
+    "prebuild": "pnpm clean",
+    "build": "tsup",
+    "build:examples": "tsup --config tsup.examples-config.ts"
+  }
+}

package/src/arguments.ts

@@ -0,0 +1,52 @@
+import {GraphQLArgument} from "graphql/type/definition";
+import {GraphQLInputObjectType} from "graphql/type";
+import {DefinitionProperty} from "@xyd-js/uniform";
+
+import {fieldIntoDefinitionProperty} from "./fields";
+
+// argumentsIntoDefinitionProperty converts GraphQL arguments into xyd 'uniform' definition properties
+export function argumentsIntoDefinitionProperty(
+    args: readonly GraphQLArgument[]
+): DefinitionProperty[] {
+    const resp: DefinitionProperty[] = []
+
+    args.forEach(arg => {
+        if (arg.type.constructor.name === "GraphQLInputObjectType") {
+            const inputObjectType = arg.type as GraphQLInputObjectType
+
+            const inputFields = inputObjectType.getFields?.()
+
+            const nestedProps: DefinitionProperty[] = []
+            const nestedDefinitionProperty: DefinitionProperty = {
+                name: arg.name,
+                type: arg.type.toJSON(),
+                description: arg.description || "",
+                properties: nestedProps,
+            }
+
+            for (const [name, inputField] of Object.entries(inputFields)) {
+                const prop = fieldIntoDefinitionProperty(
+                    name,
+                    inputField,
+                )
+
+                if (prop) {
+                    nestedProps.push(prop)
+                }
+            }
+
+            resp.push(nestedDefinitionProperty)
+        } else {
+            const prop: DefinitionProperty = {
+                name: arg.name,
+                type: arg.type.toJSON(),
+                description: arg.description || "",
+                properties: [],
+            }
+
+            resp.push(prop)
+        }
+    })
+
+    return resp
+}

package/src/examples.ts

@@ -0,0 +1,96 @@
+import {jsonToGraphQLQuery, VariableType} from "json-to-graphql-query";
+import {
+    DefinitionProperty,
+    ReferenceType
+} from "@xyd-js/uniform";
+
+// TODO: support args
+// simpleGraphqlExample is a helper function to create a simple GraphQL example query or mutation.
+export function simpleGraphqlExample(
+    operationType: ReferenceType.GRAPHQL_QUERY | ReferenceType.GRAPHQL_MUTATION,
+    operationName: string,
+    args: DefinitionProperty[],
+    returns: DefinitionProperty[],
+) {
+    let obj: any = {}
+
+
+    switch (operationType) {
+        case ReferenceType.GRAPHQL_QUERY: {
+            const exampleReturnProps = exampleReturns(returns)
+
+            obj = {
+                query: {
+                    __name: operationName,
+                    [operationName]: exampleReturnProps
+                }
+            }
+
+            break
+        }
+        case ReferenceType.GRAPHQL_MUTATION: {
+            const exampleReturnProps = exampleReturns(returns)
+            const vars = exampleVariables(args)
+            const argumen = exampleArguments(args)
+
+            obj = {
+                mutation: {
+                    __name: operationName,
+                    __variables: vars,
+                    [operationName]: {
+                        ...exampleReturnProps,
+                        __args: argumen,
+                    }
+                }
+            }
+
+            break;
+        }
+    }
+
+    return jsonToGraphQLQuery(obj, {pretty: true});
+}
+
+// exampleReturns return an example of return GraphQL object
+function exampleReturns(
+    properties: DefinitionProperty[],
+    obj: any = {}
+) {
+    properties.forEach((property) => {
+        // TODO: only if required?
+        obj[property.name] = true
+
+        if (property?.properties?.length) {
+            obj[property.name] = {}
+            exampleReturns(property.properties, obj[property.name])
+        }
+    })
+
+    return obj
+}
+
+// exampleArguments return an example of GraphQL arguments
+function exampleArguments(
+    properties: DefinitionProperty[],
+    obj: any = {}
+) {
+
+    properties.forEach((property) => {
+        obj[property.name] = new VariableType(property.name)
+    })
+
+    return obj
+}
+
+// exampleVariables return an example of GraphQL variables
+function exampleVariables(
+    properties: DefinitionProperty[],
+    obj: any = {}
+) {
+
+    properties.forEach((property) => {
+        obj[property.name] = property.type
+    })
+
+    return obj
+}

package/src/fields.ts

@@ -0,0 +1,156 @@
+// overFields iterates over fields of object or input object types
+import {
+    GraphQLField,
+    GraphQLFieldMap,
+    GraphQLInputField,
+    GraphQLInputFieldMap,
+    GraphQLInputObjectType
+} from "graphql/type";
+import {GraphQLObjectType} from "graphql";
+import {DefinitionProperty} from "@xyd-js/uniform";
+
+// fieldIntoDefinitionProperty converts GraphQL fields (field or input field) into xyd 'uniform' definition property
+export function fieldIntoDefinitionProperty(
+    fieldName: string,
+    field: GraphQLField<any, any> | GraphQLInputField,
+): DefinitionProperty {
+    let properties;
+
+    // if 'ofType' types (non-null values e.g '!<type>')
+    if ("ofType" in field.type) {
+        switch (field.type.constructor.name) {
+            case "GraphQLList": {
+                switch (field.type.ofType.constructor.name) {
+                    case "GraphQLObjectType": {
+                        const objectType = field.type.ofType as GraphQLObjectType
+
+                        properties = nestedProperties(objectType)
+
+                        break
+                    }
+
+                    case "GraphQLInputObjectType": {
+                        const inputObjectType = field.type.ofType as GraphQLInputObjectType
+
+                        properties = nestedProperties(inputObjectType)
+
+                        break
+                    }
+
+                    case "GraphQLScalarType" : {
+                        properties = definitionPropsFromNestedObj(field) || []
+
+                        break
+                    }
+
+                    case "GraphQLNonNull": {
+                        properties = definitionPropsFromNestedObj(field) || []
+
+                        break
+                    }
+
+                    default: {
+                        console.error("unsupported ofType list", field.type.ofType.constructor.name)
+                        break
+                    }
+
+                }
+
+                break
+            }
+
+            case "GraphQLNonNull": {
+                properties = definitionPropsFromNestedObj(field) || []
+
+                break
+            }
+
+            default: {
+                console.error("unsupported ofType", field.type.constructor.name)
+
+                break
+            }
+
+        }
+    }
+
+    // if regular object type
+    else if (field.type.constructor.name === "GraphQLObjectType") {
+        const objectType = field.type as GraphQLObjectType
+
+        // TODO: support nested & circular references - ITS JUST A FAST SOLUTION FOR TESTING PURPOSES
+        // properties = [
+        //     {
+        //         name: fieldName,
+        //         type: "object",
+        //         description: objectType.description || "",
+        //     }
+        // ]
+
+        // TODO: comment if bug with circular references
+        properties = nestedProperties(objectType)
+    }
+
+    // if input object type
+    else if (field.type.constructor.name === "GraphQLInputObjectType") {
+        const objectType = field.type as GraphQLInputObjectType
+
+        properties = nestedProperties(objectType)
+    }
+
+    return {
+        name: fieldName,
+        type: field.type.toJSON(),
+        description: field.description || "",
+        properties,
+    }
+}
+
+// TODO: fix any + another more safety solution?
+// definitionPropsFromNestedObj converts graphql nested obj into xyd 'uniform' definition properties
+function definitionPropsFromNestedObj(obj: any): DefinitionProperty[] | null {
+    if (!obj) {
+        return null
+    }
+    if (obj.getFields) {
+        return nestedProperties(obj)
+    }
+
+    if (obj.ofType) {
+        return definitionPropsFromNestedObj(obj.ofType)
+    }
+
+    if (obj.type) {
+        return definitionPropsFromNestedObj(obj.type)
+    }
+
+    return null
+}
+
+// deepFieldMap iterates over GraphQL field (field or input fields) maps
+function deepFieldMap(
+    fieldsMap: GraphQLFieldMap<any, any> | GraphQLInputFieldMap,
+) {
+    const properties: DefinitionProperty[] = []
+
+    for (const [name, field] of Object.entries(fieldsMap)) {
+        const prop = fieldIntoDefinitionProperty(
+            name,
+            field,
+        )
+
+        if (prop) {
+            properties.push(prop)
+        }
+    }
+
+    return properties
+}
+
+// nestedProperties get fields from object or input object types and iterates over them
+function nestedProperties(objectType: GraphQLObjectType | GraphQLInputObjectType) {
+    const nestedFields = objectType?.getFields?.()
+
+    return deepFieldMap(nestedFields)
+}
+

package/src/index.ts

@@ -0,0 +1,3 @@
+export {
+    gqlSchemaToReferences
+} from "./schema"

package/src/schema.ts

@@ -0,0 +1,47 @@
+import {getDocumentLoaders, loadSchema} from "@graphql-markdown/graphql";
+import {OperationTypeNode} from "graphql/language/ast";
+import {Reference, ReferenceType} from "@xyd-js/uniform"
+
+import {
+    graphqlOperationReferences
+} from "./utils";
+
+// TODO: support multi graphql files
+// TODO: !!! CIRCULAR_DEPENDENCY !!!
+// TODO: sort by tag??
+
+export async function gqlSchemaToReferences(
+    schemaLocation: string
+): Promise<Reference[]> {
+    const loadersList = {
+        ["GraphQLFileLoader"]: "@graphql-tools/graphql-file-loader",
+    }
+    const loaders = await getDocumentLoaders(loadersList);
+
+    // @ts-ignore TODO: but ts works in @graphql-markdown/core
+    const schema = await loadSchema(schemaLocation as string, loaders);
+
+    const references: Reference[] = []
+
+    const queries = schema.getRootType(OperationTypeNode.QUERY)
+    const queryFields = queries?.getFields?.()
+
+    if (queryFields) {
+        references.push(...graphqlOperationReferences(
+            ReferenceType.GRAPHQL_QUERY,
+            queryFields
+        ))
+    }
+
+    const mutations = schema.getRootType(OperationTypeNode.MUTATION)
+    const mutationFields = mutations?.getFields?.()
+
+    if (mutationFields) {
+        references.push(...graphqlOperationReferences(
+            ReferenceType.GRAPHQL_MUTATION,
+            mutationFields
+        ))
+    }
+
+    return references
+}

package/src/utils.ts

@@ -0,0 +1,101 @@
+import {GraphQLFieldMap} from "graphql/type";
+import {
+    Reference,
+    ReferenceCategory,
+    ReferenceType,
+    ExampleGroup,
+    Definition,
+    Example,
+} from "@xyd-js/uniform";
+
+import {argumentsIntoDefinitionProperty} from "./arguments";
+import {fieldIntoDefinitionProperty} from "./fields";
+import {simpleGraphqlExample} from "./examples";
+
+// TODO: examples
+// graphqlOperationReferences is a helper function to create a list of xyd reference for a GraphQL query or mutation.
+export function graphqlOperationReferences(
+    operationType: ReferenceType.GRAPHQL_MUTATION | ReferenceType.GRAPHQL_QUERY,
+    fieldsMap: GraphQLFieldMap<any, any>
+) {
+    const references: Reference[] = []
+
+    for (const [operationName, operationField] of Object.entries(fieldsMap)) {
+        const definitions: Definition[] = []
+
+        const args = argumentsIntoDefinitionProperty(operationField.args)
+        const returns = fieldIntoDefinitionProperty(operationName, operationField)
+        const returnProperties = returns.properties || []
+
+        definitions.push({
+            title: "Arguments",
+            properties: args,
+        })
+        definitions.push({
+            title: "Returns",
+            properties: returnProperties
+        })
+
+        const exampleQuery = simpleGraphqlExample(
+            operationType,
+            operationName,
+            args,
+            returnProperties
+        )
+        const examples: Example[] = [
+            {
+                codeblock: {
+                    tabs: [
+                        {
+                            title: "graphql",
+                            language: "graphql",
+                            code: exampleQuery,
+                        }
+                    ]
+                }
+            }
+        ]
+
+        const exampleGroup = {
+            description: "Example request",
+            examples,
+        }
+
+        let description = operationField.description || ""
+
+        references.push(graphqlReference(
+            operationType,
+            operationName,
+            operationName,
+            description,
+            [exampleGroup],
+            definitions,
+        ))
+    }
+
+    return references
+}
+
+// graphqlReference is a helper function to create a Reference object for a GraphQL query or mutation.
+function graphqlReference(
+    operationType: ReferenceType.GRAPHQL_QUERY | ReferenceType.GRAPHQL_MUTATION,
+    title: string,
+    canonical: string,
+    description: string,
+    examples: ExampleGroup[],
+    definitions: Definition[],
+): Reference {
+    return {
+        title,
+        canonical,
+        description,
+
+        category: ReferenceCategory.GRAPHQL,
+        type: operationType,
+
+        examples: {
+            groups: examples,
+        },
+        definitions,
+    }
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo"
+  },
+  "include": ["examples/basic-example/**/*.ts", "src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,19 @@
+import {defineConfig} from 'tsup';
+
+export default defineConfig({
+    entry: ['index.ts'],
+    format: ['esm'], // Output both ESM and CJS formats
+    target: 'node16', // Ensure compatibility with Node.js 16
+    dts: {
+        entry: 'index.ts', // Specify the entry for DTS
+        resolve: true, // Resolve external types
+    },
+    splitting: false, // Disable code splitting
+    sourcemap: true, // Generate source maps
+    clean: true, // Clean the output directory before each build
+    esbuildOptions: (options) => {
+        options.platform = 'node'; // Ensure the platform is set to Node.js
+        options.external = ['node:fs/promises']; // Mark 'node:fs/promises' as external
+        options.loader = {'.js': 'jsx'}; // Ensure proper handling of .js files
+    },
+});

package/tsup.examples-config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from 'tsup';
+
+// TODO: multiple entry points + outputs
+
+const isDebugMode = !!process.env.DEBUG
+
+export default defineConfig({
+    entry: [
+        "./examples/basic/index.ts"
+    ],
+    format: ['esm', 'cjs'], // Output both ESM and CJS formats
+    target: 'node16', // Ensure compatibility with Node.js 16
+    dts: {
+        entry: "./examples/basic/index.ts",
+        resolve: true, // Resolve external types
+    },
+    splitting: false, // Disable code splitting
+    sourcemap: true, // Generate source maps
+    clean: true, // Clean the output directory before each build
+    outDir: './examples/dist', // Output directory
+    esbuildOptions(options) {
+        options.minify = true;
+        if (isDebugMode) {
+            options.drop = [];
+        } else {
+            options.drop = [];
+            options.pure = ['console.debug'];
+        }
+    },
+});