@xyd-js/gql 0.1.0-xyd.9 → 0.1.0-xyd.96

package/dist/opendocs.graphql

@@ -0,0 +1,56 @@
+directive @scope(value: String!) on ENUM_VALUE
+
+enum OpenDocsScope {
+    _PLACEHOLDER_
+}
+
+directive @docs(
+    route: String
+    sort: [OpenDocsSortInput!]
+    sortStack: [[String!]!]
+    flattenTypes: Boolean
+    sidebar: [OpenDocsPage]
+    group: [String]
+) repeatable on SCHEMA
+
+input OpenDocsPage {
+    type: OpenDocsSidebarItemType!
+    key: String!
+    group: String
+    path: String
+    pages: [OpenDocsPage]
+}
+
+enum OpenDocsSidebarItemType {
+    OPERATION
+    TYPE
+}
+
+directive @doc(
+    group: [String!],
+    path: String,
+    example: OpenDocsExampleInput,
+    scopes: [OpenDocsScope],
+) on QUERY |
+    FIELD_DEFINITION |
+    MUTATION |
+    SUBSCRIPTION |
+    OBJECT |
+    INPUT_OBJECT |
+    ENUM |
+    SCALAR |
+    UNION
+
+# TODO: finish
+input OpenDocsExampleInput {
+    """
+    The name of the code
+    """
+    code: String!
+}
+
+input OpenDocsSortInput {
+    node: String
+    group: [String!]
+    stack: Int
+}

package/package.json

@@ -1,18 +1,16 @@
 {
   "name": "@xyd-js/gql",
-  "version": "0.1.0-xyd.9",
+  "version": "0.1.0-xyd.96",
   "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.9",
-    "@xyd-js/uniform": "0.1.0-xyd.11"
+    "@graphql-tools/merge": "^8.4.0",
+    "@graphql-tools/schema": "^10.0.0",
+    "github-slugger": "^2.0.0",
+    "graphql": "^16.8.1",
+    "@xyd-js/core": "0.1.0-xyd.96",
+    "@xyd-js/uniform": "0.1.0-xyd.98"
   },
   "devDependencies": {
     "rimraf": "^3.0.2",

package/src/context.ts

@@ -0,0 +1,17 @@
+import { GraphQLSchema } from "graphql";
+import {GQLSchemaToReferencesOptions, NestedGraphqlType} from "./types";
+
+export class Context {
+    constructor(
+        public processedTypes: Set<NestedGraphqlType> = new Set(),
+        public globalOptions?: GQLSchemaToReferencesOptions,
+        public config?: {
+            flatReturn?: boolean,
+            flat?: boolean,
+            flatArg?: boolean,
+        },
+        public schema?: GraphQLSchema
+    ) {
+    }
+}
+

package/src/converters/gql-arg.ts

@@ -0,0 +1,51 @@
+import {GraphQLArgument, GraphQLInputObjectType} from "graphql";
+
+import {DefinitionProperty} from "@xyd-js/uniform";
+
+import {gqlInputToUniformDefinitionProperty} from "./gql-input";
+import {Context} from "../context";
+import {gqlFieldToUniformMeta, gqlFieldTypeInfo, propsUniformify} from "../gql-core";
+
+// gqlArgToUniformDefinitionProperty converts GraphQL arguments into xyd 'uniform' definition properties
+export function gqlArgToUniformDefinitionProperty(
+    ctx: Context,
+    args: readonly GraphQLArgument[],
+): DefinitionProperty[] {
+    const resp: DefinitionProperty[] = []
+
+    args.forEach(arg => {
+        const fieldInfo = gqlFieldTypeInfo(arg);
+        if (!fieldInfo.typeFlat) {
+            console.error("gqlArgToUniformDefinitionProperty: no typeFlat for", arg.name);
+            return;
+        }
+
+        const flatType = fieldInfo.typeFlat
+
+        if (flatType instanceof GraphQLInputObjectType) {
+            const inputObj = flatType
+            const meta = gqlFieldToUniformMeta(arg)
+            const defProperty = gqlInputToUniformDefinitionProperty(
+                ctx,
+                inputObj,
+            )
+
+            resp.push({
+                ...defProperty,
+                type: arg.type.toJSON(),
+                name: arg.name,
+                description: arg.description || "",
+                meta: [
+                    ...defProperty.meta || [],
+                    ...meta || []
+                ],
+            });
+        } else {
+            const defProperty = propsUniformify(ctx, arg)
+            resp.push(defProperty)
+        }
+    });
+
+    return resp;
+}
+

package/src/converters/gql-enum.ts

@@ -0,0 +1,27 @@
+import {GraphQLEnumType} from "graphql";
+
+import type {DefinitionProperty, Reference} from "@xyd-js/uniform";
+import {uniformify} from "../gql-core";
+import {NestedGraphqlType} from "../types";
+import {Context} from "../context";
+
+// gqlEnumToUniformRef is a helper function to convert a GraphQL enum type into a 'uniform' reference.
+export function gqlEnumToUniformRef(ctx: Context, gqlType: GraphQLEnumType): Reference {
+    const props: DefinitionProperty[] = gqlType.getValues().map(value => ({
+        name: value.name,
+        type: "string", // TODO: other types?
+        description: value.description || "",
+    }))
+
+    return uniformify(
+        ctx,
+        gqlType,
+        [
+            {
+                title: "Valid values",
+                properties: props
+            }
+        ],
+        [],
+    )
+}

package/src/converters/gql-field.ts

@@ -0,0 +1,164 @@
+import {
+    GraphQLField,
+    GraphQLFieldMap,
+    GraphQLInputField,
+    GraphQLInputFieldMap,
+    GraphQLInputObjectType,
+    GraphQLUnionType,
+    GraphQLObjectType,
+    GraphQLInterfaceType,
+    GraphQLScalarType,
+    GraphQLNonNull,
+} from "graphql";
+
+import type {DefinitionProperty, DefinitionPropertyMeta} from "@xyd-js/uniform";
+
+import {NestedGraphqlType} from "../types";
+import {gqlFieldTypeInfo, propsUniformify} from "../gql-core";
+import {gqlUnionToUniformDefinitionProperties} from "./gql-union";
+import {Context} from "../context";
+
+// gqlFieldToUniformDefinitionProperty converts GraphQL fields (field or input field) into xyd 'uniform' definition property
+export function gqlFieldToUniformDefinitionProperty(
+    ctx: Context,
+    field: GraphQLField<any, any> | GraphQLInputField,
+): DefinitionProperty {
+    return GQLFieldConverter.convert(ctx, field);
+}
+
+export class GQLFieldConverter {
+    private constructor(private ctx: Context) {
+    }
+
+    public static convert(
+        ctx: Context,
+        field: GraphQLField<any, any> | GraphQLInputField,
+    ): DefinitionProperty {
+        return new GQLFieldConverter(ctx).convert(field);
+    }
+
+    private convert(
+        field: GraphQLField<any, any> | GraphQLInputField,
+        parent?: NestedGraphqlType,
+    ): DefinitionProperty {
+        if (this.ctx.globalOptions?.flat && (this.ctx.config?.flatReturn || this.ctx.config?.flat)) {
+            const info = gqlFieldTypeInfo(field)
+            const meta: DefinitionPropertyMeta[] = []
+
+            const props = propsUniformify(this.ctx, field, [], meta)
+            if (this.ctx.config?.flatReturn) {
+                return {
+                    ...props,
+                    name: ""
+                }
+            }
+
+            if (this.ctx.config?.flat) {
+                return props
+            }
+        }
+
+        const fieldInfo = gqlFieldTypeInfo(field)
+        const graphqlTypeFlat = fieldInfo?.typeFlat
+
+        let properties
+
+        switch (graphqlTypeFlat?.constructor) {
+            case GraphQLObjectType:
+            case GraphQLInputObjectType:
+            case GraphQLInterfaceType: {
+                properties = this.nestedProperties(graphqlTypeFlat as NestedGraphqlType)
+                break;
+            }
+            case GraphQLScalarType:
+            case GraphQLNonNull: {
+                properties = this.definitionPropsFromNestedObj(field) || []
+                break;
+            }
+            case GraphQLUnionType: {
+                properties = gqlUnionToUniformDefinitionProperties(this.ctx, graphqlTypeFlat as GraphQLUnionType)
+                break;
+            }
+        }
+
+        const resp = propsUniformify(
+            this.ctx,
+            field,
+            properties,
+        )
+
+        if (graphqlTypeFlat) {
+            const nestedType = graphqlTypeFlat as NestedGraphqlType
+            nestedType.__definitionProperties = resp.properties
+        }
+
+        if (parent) {
+            parent.__definitionProperties = resp.properties
+        }
+
+        return resp
+    }
+
+    // TODO: fix any + another more safety solution?
+    // definitionPropsFromNestedObj converts graphql nested obj into xyd 'uniform' definition properties
+    private definitionPropsFromNestedObj(obj: any): DefinitionProperty[] | null {
+        if (!obj) {
+            return null
+        }
+        if (obj.getFields) {
+            return this.nestedProperties(obj)
+        }
+
+        if (obj.ofType) {
+            return this.definitionPropsFromNestedObj(obj.ofType)
+        }
+
+        if (obj.type) {
+            return this.definitionPropsFromNestedObj(obj.type)
+        }
+
+        return null
+    }
+
+    // deepFieldMap iterates over GraphQL field (field or input fields) maps
+    private deepFieldMap(
+        fieldsMap: GraphQLFieldMap<any, any> | GraphQLInputFieldMap,
+        parent: NestedGraphqlType
+    ): DefinitionProperty[] {
+        const properties: DefinitionProperty[] = []
+
+        for (const [name, field] of Object.entries(fieldsMap)) {
+            const prop = this.convert(
+                field,
+                parent
+            )
+
+            if (prop) {
+                properties.push(prop)
+            }
+        }
+
+        return properties
+    }
+
+    // nestedProperties get fields from object or input object types and iterates over them
+    private nestedProperties(objectType: NestedGraphqlType) {
+        // Check if we've already processed this type to prevent circular dependencies
+        if (this.ctx.processedTypes.has(objectType)) {
+            if (objectType?.__definitionProperties) {
+                return objectType.__definitionProperties || []
+            }
+
+            return [] // Return empt array for already processed types to break the cycle
+        }
+
+        // Mark this type as being processed
+        this.ctx.processedTypes.add(objectType)
+
+        const nestedFields = objectType?.getFields?.()
+        const result = this.deepFieldMap(nestedFields, objectType)
+
+        return result
+    }
+}
+

package/src/converters/gql-input.ts

@@ -0,0 +1,34 @@
+import {GraphQLInputObjectType} from "graphql";
+
+import {Reference} from "@xyd-js/uniform";
+
+import {gqlObjectPropsUniformify, uniformify} from "../gql-core";
+import {Context} from "../context";
+
+// gqlInputToUniformRef is a helper function to convert a GraphQL input object type into a 'uniform' reference.
+export function gqlInputToUniformRef(ctx: Context, gqlType: GraphQLInputObjectType): Reference {
+    const prop = gqlInputToUniformDefinitionProperty(
+        ctx,
+        gqlType,
+    )
+
+    return uniformify(
+        ctx,
+        gqlType,
+        [
+            {
+                title: "Fields",
+                properties: prop.properties || []
+            }
+        ],
+        []
+    )
+}
+
+// gqlInputToUniformDefinitionProperty is a helper function to convert a GraphQL input object into a xyd definition property.
+export function gqlInputToUniformDefinitionProperty(
+    ctx: Context,
+    obj: GraphQLInputObjectType,
+) {
+    return gqlObjectPropsUniformify(ctx, obj)
+}

package/src/converters/gql-interface.ts

@@ -0,0 +1,35 @@
+import {GraphQLInterfaceType, GraphQLField} from "graphql";
+
+import {Definition, DefinitionProperty, Reference} from "@xyd-js/uniform";
+
+import {gqlFieldToUniformDefinitionProperty} from "./gql-field";
+import {uniformify} from "../gql-core";
+import {NestedGraphqlType} from "../types";
+import {Context} from "../context";
+
+export function gqlInterfaceToUniformRef(ctx: Context, interfaceType: GraphQLInterfaceType): Reference {
+    const properties = gqlInterfaceToUniformDefinitionProperties(ctx, interfaceType)
+
+    const definitions: Definition[] = [
+        {
+            title: "Fields",
+            properties,
+        }
+    ]
+
+    return uniformify(
+        ctx,
+        interfaceType,
+        definitions,
+        []
+    )
+}
+
+export function gqlInterfaceToUniformDefinitionProperties(ctx: Context, interfaceType: GraphQLInterfaceType): DefinitionProperty[] {
+    return Object.values(interfaceType.getFields()).map((field: GraphQLField<any, any>) => {
+        return gqlFieldToUniformDefinitionProperty(
+            ctx,
+            field,
+        )
+    })
+} 

package/src/converters/gql-mutation.ts

@@ -0,0 +1,36 @@
+import type {GraphQLSchema} from "graphql";
+import {OperationTypeNode} from "graphql";
+
+import {Reference, ReferenceType} from "@xyd-js/uniform";
+
+import type {GQLSchemaToReferencesOptions} from "../types";
+import {filterFieldsByRegions} from "../utils";
+import {gqlOperationToUniformRef} from "./gql-operation";
+
+export function graphqlMutationsToUniformReferences(
+    schema: GraphQLSchema,
+    options?: GQLSchemaToReferencesOptions,
+) {
+    const references: Reference[] = []
+
+    const mutations = schema.getRootType(OperationTypeNode.MUTATION)
+    const mutationFields = mutations?.getFields?.()
+
+    if (mutationFields) {
+        // Filter mutation fields based on regions if provided
+        const filteredMutationFields = filterFieldsByRegions(
+            mutationFields,
+            "mutation",
+            options?.regions
+        );
+
+        references.push(...gqlOperationToUniformRef(
+            ReferenceType.GRAPHQL_MUTATION,
+            filteredMutationFields,
+            schema,
+            options,
+        ))
+    }
+
+    return references;
+}

package/src/converters/gql-object.ts

@@ -0,0 +1,83 @@
+import {GraphQLObjectType} from "graphql";
+
+import {Definition, DefinitionProperty, DefinitionVariant} from "@xyd-js/uniform";
+
+import {gqlFieldToUniformDefinitionProperty} from "./gql-field";
+import {gqlObjectPropsUniformify, uniformify} from "../gql-core";
+import {Context} from "../context";
+import {gqlArgToUniformDefinitionProperty} from "./gql-arg";
+
+// gqlObjectToUniformRef is a helper function to convert a GraphQL object type into a 'uniform' reference.
+export function gqlObjectToUniformRef(
+    ctx: Context,
+    gqlType: GraphQLObjectType
+) {
+    const definitions: Definition[] = []
+    const graphqlFields: DefinitionProperty[] = []
+
+    const variants: DefinitionVariant[] = []
+
+    const argumentDefinition: Definition = {
+        title: "Arguments",
+        properties: [],
+        variants,
+        meta: [
+            {
+                name: "type",
+                value: "arguments",
+            },
+        ]
+    }
+
+    for (const [name, field] of Object.entries(gqlType.getFields())) {
+        if (!field?.args?.length) {
+         continue;
+        }
+
+        const args = gqlArgToUniformDefinitionProperty(ctx, field.args)
+
+        variants.push({
+            title: "",
+            properties: args,
+            meta: [
+                {
+                    name: "symbolName",
+                    value: name,
+                }
+            ]
+        })
+    }
+    definitions.push(argumentDefinition)
+
+    for (const [name, field] of Object.entries(gqlType.getFields())) {
+        const prop = gqlFieldToUniformDefinitionProperty(ctx, field)
+
+        graphqlFields.push(prop)
+    }
+
+    definitions.push({
+        title: "Fields",
+        properties: graphqlFields,
+        meta: [
+            {
+                name: "type",
+                value: "fields",
+            }
+        ]
+    })
+
+    return uniformify(
+        ctx,
+        gqlType,
+        definitions,
+        []
+    )
+}
+
+// gqlObjectToUniformDefinitionProperty is a helper function to convert a GraphQL object type into a xyd definition property.
+export function gqlObjectToUniformDefinitionProperty(
+    ctx: Context,
+    obj: GraphQLObjectType,
+) {
+    return gqlObjectPropsUniformify(ctx, obj)
+}

package/src/converters/gql-operation.ts

@@ -0,0 +1,128 @@
+import { GraphQLFieldMap, GraphQLSchema, OperationTypeNode } from "graphql";
+import { Definition, Example, Reference, ReferenceType, } from "@xyd-js/uniform";
+
+import { type GQLSchemaToReferencesOptions, GQLOperation } from "../types";
+import { gqlArgToUniformDefinitionProperty } from "./gql-arg";
+import { gqlFieldToUniformDefinitionProperty } from "./gql-field";
+import { simpleGraphqlExample } from "./gql-sample";
+import { uniformify } from "../gql-core";
+import { Context } from "../context";
+
+// gqlOperationToUniformRef is a helper function to create a list of xyd reference for a GraphQL operation (query or mutation).
+export function gqlOperationToUniformRef(
+    operationType: ReferenceType.GRAPHQL_MUTATION | ReferenceType.GRAPHQL_QUERY | ReferenceType.GRAPHQL_SUBSCRIPTION,
+    fieldsMap: GraphQLFieldMap<any, any>,
+    schema: GraphQLSchema,
+    options?: GQLSchemaToReferencesOptions,
+) {
+    const references: Reference[] = []
+
+    for (const [operationName, operationField] of Object.entries(fieldsMap)) {
+        const definitions: Definition[] = []
+        let flatReturn = false
+        let flat = false
+        let argFlat = false
+
+        if (options?.flat) {
+            flatReturn = true
+            flat = true
+            argFlat = true
+        }
+
+        const args = gqlArgToUniformDefinitionProperty(new Context(
+            new Set(),
+            options,
+            {
+                flat,
+                flatArg: argFlat,
+            },
+            schema
+        ), operationField.args)
+
+
+        const returns = gqlFieldToUniformDefinitionProperty(new Context(
+            new Set(),
+            options,
+            {
+                flatReturn
+            },
+            schema
+        ), operationField)
+        let returnProperties = returns.properties || []
+        if (options?.flat) {
+            returnProperties = [returns]
+        }
+
+        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: "",
+                            language: "graphql",
+                            code: exampleQuery,
+                        }
+                    ]
+                }
+            }
+        ]
+
+        const exampleGroup = {
+            description: "",
+            examples,
+        }
+
+        const operation = new GQLOperation(operationField)
+        switch (operationType) {
+            case ReferenceType.GRAPHQL_QUERY: {
+                operation.__operationType = OperationTypeNode.QUERY;
+                break;
+            }
+            case ReferenceType.GRAPHQL_MUTATION: {
+                operation.__operationType = OperationTypeNode.MUTATION;
+                break;
+            }
+            case ReferenceType.GRAPHQL_SUBSCRIPTION: {
+                operation.__operationType = OperationTypeNode.SUBSCRIPTION;
+                break;
+            }
+            default: {
+                console.error(`Invalid operation type: ${operationType}`);
+            }
+        }
+
+        const ref = uniformify(
+            new Context(
+                new Set(),
+                options,
+                {},
+                schema
+            ),
+            operation,
+            definitions,
+            [exampleGroup]
+        )
+        
+        if (ref) {
+            references.push(ref)
+        }
+    }
+
+    return references
+}