import { promises as fs } from "fs"; import { Kind } from "graphql"; import { Spinner } from "@topcli/spinner"; import { attachImport, pascalToSlug, slugToCamel, slugToPascal } from "./utils.js"; import { MANAGEMENT_API_DEFINITIONS, QUERY_API_DEFINITIONS } from "./consts.js"; import pages from "../pages.json" assert { type: "json" }; export default async function main() { const spinner = new Spinner().start("Generating Query API snippets"); const snippetsPath = "./snippets/pages"; const queryApiSnippetsPath = `${snippetsPath}/query-apis`; const managementApiSnippetsPath = `${snippetsPath}/management-apis`; await fs.rm(queryApiSnippetsPath, { recursive: true, force: true }); await fs.rm(managementApiSnippetsPath, { recursive: true, force: true }); const PRIMITIVES = ["String", "Boolean", "Int", "Float", "ID"]; const { enums: queryApiEnums, inputs: queryApiInputs, types: queryApiTypes, unions: queryApiUnions, scalars: queryApiScalars, scalarsNames: queryApiScalarsNames, mutations: queryApiMutations, queries: queryApiQueries, } = QUERY_API_DEFINITIONS; const { enums: managementApiEnums, inputs: managementApiInputs, types: managementApiTypes, unions: managementApiUnions, scalars: managementApiScalars, scalarsNames: managementApiScalarsNames, mutations: managementApiMutations, queries: managementApiQueries, } = MANAGEMENT_API_DEFINITIONS; const scalars = [...queryApiScalarsNames, ...managementApiScalarsNames]; const queryApiFiles = { enums: [], inputs: [], types: [], unions: [], scalars: [], mutations: [], queries: [], }; const managementApiFiles = { enums: [], inputs: [], types: [], unions: [], scalars: [], mutations: [], queries: [], }; const pagesFiles = {}; for (const enumDefinition of queryApiEnums) { queryApiFiles.enums.push( await generateEnumOrScalar(enumDefinition, "enums", "query-api"), ); } for (const inputDefinition of queryApiInputs) { queryApiFiles.inputs.push( await generateInputOrType(inputDefinition, "inputs", "query-api"), ); } for (const typeDefinition of queryApiTypes) { queryApiFiles.types.push( await generateInputOrType(typeDefinition, "types", "query-api"), ); } for (const unionDefinition of queryApiUnions) { queryApiFiles.unions.push(await generateUnion(unionDefinition, "query-api")); } for (const mutationDefinition of queryApiMutations) { queryApiFiles.mutations.push( await generateInputOrType(mutationDefinition, "mutations", "query-api"), ); } for (const queryDefinition of queryApiQueries) { queryApiFiles.queries.push( await generateInputOrType(queryDefinition, "queries", "query-api"), ); } for (const scalarDefinition of queryApiScalars) { queryApiFiles.scalars.push( await generateEnumOrScalar(scalarDefinition, "scalars", "query-api"), ); } for (const enumDefinition of managementApiEnums) { managementApiFiles.enums.push( await generateEnumOrScalar(enumDefinition, "enums", "management-api"), ); } for (const inputDefinition of managementApiInputs) { managementApiFiles.inputs.push( await generateInputOrType(inputDefinition, "inputs", "management-api"), ); } for (const typeDefinition of managementApiTypes) { managementApiFiles.types.push( await generateInputOrType(typeDefinition, "types", "management-api"), ); } for (const unionDefinition of managementApiUnions) { managementApiFiles.unions.push( await generateUnion(unionDefinition, "management-api"), ); } for (const mutationDefinition of managementApiMutations) { managementApiFiles.mutations.push( await generateInputOrType(mutationDefinition, "mutations", "management-api"), ); } for (const queryDefinition of managementApiQueries) { managementApiFiles.queries.push( await generateInputOrType(queryDefinition, "queries", "management-api"), ); } for (const scalarDefinition of managementApiScalars) { managementApiFiles.scalars.push( await generateEnumOrScalar(scalarDefinition, "scalars", "management-api"), ); } await generatePages(pages); spinner.succeed("Query API snippets generated successfully"); /** * * @param {typeof pages} pages */ async function generatePages(pages) { for (let [pagePath, files] of Object.entries(pages)) { const includeRaw = files.length === 0; const [api, kind] = pagePath.split("/"); if (files.length === 0) { const filesPerApi = { "query-apis": queryApiFiles, "management-apis": managementApiFiles, }[api]; files = filesPerApi[kind].map((f) => ({ fileName: Object.keys(f)[0].split("/").pop().replaceAll(".mdx", ""), title: Object.keys(f)[0].split("/").pop().replaceAll(".mdx", ""), })); } const patchTopLevelFields = pagePath.includes("queries") || pagePath.includes("mutations"); const includeParamFieldTitles = pagePath.includes("queries") || pagePath.includes("mutations"); const includeTitle = !( pagePath.includes("queries") || pagePath.includes("mutations") ); const includeReturns = pagePath.includes("queries") || pagePath.includes("mutations"); const isApiReference = [ "enums", "inputs", "types", "unions", "queries", "mutations", ].includes(kind); const maxExpandableNesting = isApiReference ? 3 : 1000; const [fileContent] = buildFileContent(files, api, { patchTopLevelFields, includeParamFieldTitles, includeTitle, includeReturns, includeRaw, maxExpandableNesting, }); pagesFiles[pagePath] = fileContent; } } /** * @param {typeof pages[keyof typeof pages]} files * @param {'query-api' | 'management-api'} api * @param {{ patchTopLevelFields: boolean, includeParamFieldTitles: boolean, includeTitle: boolean, includeReturns: boolean, includeRaw: boolean, maxExpandableNesting: number }} options */ function buildFileContent(files, api, options = {}) { const { patchTopLevelFields: shouldPatchTopLevelFields = false, includeParamFieldTitles = false, includeTitle = false, includeReturns = true, includeRaw = false, maxExpandableNesting, } = options; let fileContent = ""; let kind = ""; for (const file of files) { const fileName = file.fileName; const title = file.title; const filesValuesPerApi = { "query-apis": Object.values(queryApiFiles).flat(), "management-apis": Object.values(managementApiFiles).flat(), }[api]; /** @type {Record} */ const contentKey = filesValuesPerApi.find((f) => { const key = Object.keys(f)[0]; return key.includes(`/${fileName}.mdx`); }); kind = Object.keys(contentKey)[0].split("/").slice(-2, -1)[0]; /** @type {string} */ let content = Object.values(contentKey)[0]; if (!includeParamFieldTitles) { const splitContent = content.split("\n"); const indexes = splitContent.reduce((indexes, line, index) => { if (line.includes("## ") && !line.includes("###")) { indexes.push(index); } return indexes; }, []); for (const index of indexes) { splitContent.splice(index, 1, "\n"); content = splitContent.join("\n"); } } if (!includeReturns) { content = content .split("\n") .filter( (line) => !line.includes("### Returns") && !line.includes('

\n\n${fileContent}`; } return [fileContent, kind]; } /** Removes path and type from top-level ParamFields */ function patchTopLevelFields(fileContent) { const splitContent = fileContent.split("\n"); const paramFieldIndexes = splitContent.reduce((indexes, line, index) => { if (line.includes(" !( line.includes("import") && line.includes("from") && (line.includes(".mdx'") || line.includes("'null'")) ), ); const imports = fileContent .split("\n") .filter( (line) => line.includes("import") && line.includes("from") && line.includes(".mdx'"), ) .filter((line) => !line.includes("ui-kit")); const fileNamesFromImports = imports.map((line) => line .split("from")[1] .replaceAll("'", "") .replaceAll('"', "") .trim() .split("/") .pop() .replaceAll(".mdx", ""), ); if (imports.length === 0) { return fileContent; } if (api == null) { api = imports[0].includes("query-apis") ? "query-apis" : "management-apis"; } for (const fileName of fileNamesFromImports) { let [content, kind] = buildFileContent([{ fileName, title: fileName }], api, { includeReturns: false, maxExpandableNesting, }); // Find all indexes where this component is used const componentDeclarationIndexes = fileContentWithoutImports.reduce( (indexes, line, index) => { if ( line.includes(`<${slugToPascal(fileName)} />`) || line.includes(`<${slugToCamel(fileName)} />`) ) { indexes.push(index); } return indexes; }, [], ); // Replace each instance with the content for (const index of componentDeclarationIndexes) { if (maxExpandableNesting <= 0) { const apiPath = { "query-apis": "query-apis/api-reference", "management-apis": "management-api", }[api]; fileContentWithoutImports.splice( index - 1, 3, "\n", "See " + createLink( slugToPascal(fileName), `/docs/${apiPath}/${kind}#${slugToPascal(fileName).toLowerCase()}`, ), "\n", ); } else { fileContentWithoutImports.splice(index, 1, content); } } } return fileContentWithoutImports.join("\n"); } /** * @param {string} title * @param {string} href * @returns {string} */ function createLink(title, href) { return `${title}`; } /** * @param {string} title * @param {boolean} isRequired * @returns {string} */ function createReturnLabel(title, isRequired = false) { const typeBox = `

${title}

`; const requiredLabel = `${isRequired ? "Non-null" : "Nullable"}`; return `

${requiredLabel}${typeBox}

`; } /** * @param {import("graphql").EnumTypeDefinitionNode} definition * @param {'enums' | 'scalars'} kind * @param {'query-api' | 'management-api'} api */ async function generateEnumOrScalar(definition, kind, api) { const definitionName = definition.name?.value ?? definition.name; const fileName = pascalToSlug(definitionName); const filePath = getPathFor(kind, fileName, api); const fileContent = `${definition.description?.value ?? ""}\n\n ${( definition.values?.map( (value) => `\t- \`${value.name.value}\`${ value.description != null ? `: ${value.description.value}` : "" }`, ) ?? [] ).join("\n")} `; // await fs.mkdir(getPathFor(kind, null, api), { recursive: true }); return { [filePath]: fileContent }; } /** * * @param {import("graphql").UnionTypeDefinitionNode} definition * @param {'query-api' | 'management-api'} api */ async function generateUnion(definition, api) { const associatedTypes = definition.types.map((t) => t.name.value); const fileName = pascalToSlug(definition.name.value); const filePath = getPathFor("unions", fileName, api); const paramFieldType = associatedTypes.join(" | "); let fileContent = `${definition.description?.value ?? ""}\n\n\n${associatedTypes.map((t) => `\n<${t} />\n\n`).join("\n")}\n`; associatedTypes.forEach((t) => { fileContent = attachImport(fileContent, t); }); return { [filePath]: fileContent }; } /** * @param {import("graphql").InputObjectTypeDefinitionNode} definition * @param {'inputs' | 'types'} kind * @param {'query-api' | 'management-api'} api */ async function generateInputOrType(definition, kind, api) { const fileName = pascalToSlug(definition.name.value); const filePath = getPathFor(kind, fileName, api); const imports = new Set(); const deprecatedFields = new Set(); let fileContent = `\n${definition.description?.value ?? ""}\n\n ${definition.fields .map((field) => { let type = buildType(field.type); const namedType = normalizeGraphQLType(type); /** @type {import("graphql").InputValueDefinitionNode[]} */ const fieldArguments = field.arguments; const isPrimitiveOrScalar = PRIMITIVES.includes(namedType) || scalars.includes(namedType); const isRecursive = namedType === slugToPascal(fileName); const isCircularDependency = checkCircularDependency(namedType, fileName); const isRequired = field.type.kind === Kind.NON_NULL_TYPE; const formattedType = type.endsWith("!") ? type.slice(0, -1) : type; const isDeprecated = field.directives.some((d) => d.name.value === "deprecated"); const withRequired = isRequired ? " required" : ""; const withDeprecated = isDeprecated ? " deprecated" : ""; const withDeprecatedText = isDeprecated ? `\ndeprecated: ${ field.directives.find((d) => d.name.value === "deprecated").arguments[0].value .value }\n` : ""; let withExpandable = ""; let withArguments = ""; if (!isPrimitiveOrScalar && !isRecursive) { if (isCircularDependency) { const apiPath = { "query-api": "query-apis/api-reference", "management-api": "management-api", }[api]; withExpandable = "See " + createLink( slugToPascal(namedType), `/docs/${apiPath}/${kind}#${slugToPascal(namedType).toLowerCase()}`, ) + "\n"; } else { imports.add(namedType); withExpandable = `\n### Returns\n${createReturnLabel(namedType, isRequired)}\n\n\t\t<${namedType} />\n\t\n`; } } if (fieldArguments != null && fieldArguments.length > 0) { fieldArguments.forEach((argument) => { const argumentType = normalizeGraphQLType(buildType(argument.type)); const isPrimitiveOrScalar = PRIMITIVES.includes(argumentType) || scalars.includes(argumentType); const isRecursive = argumentType === slugToPascal(fileName); const isCircularDependency = checkCircularDependency(argumentType, fileName); if (!isRecursive && !isCircularDependency) { imports.add(argumentType); const builtType = buildType(argument.type); const formattedType = builtType.endsWith("!") ? builtType.slice(0, -1) : builtType; const isRequired = argument.type.kind === Kind.NON_NULL_TYPE; withArguments += `\n\ ${ !isPrimitiveOrScalar ? `\n<${argumentType} />\n\n` : "" } \n`; } }); if (withArguments !== "") { withArguments = "\n### Arguments\n" + withArguments; } } const paramField = `${`## ${field.name.value}\n`}\n${ field?.description?.value ?? "" }\n${withDeprecatedText}${withArguments}${withExpandable}\n`; if (isDeprecated) { deprecatedFields.add(paramField); return ""; } return paramField; }) .join("\n")}`; imports.forEach((definitionName) => { fileContent = attachImport(fileContent, definitionName); }); if (deprecatedFields.size > 0) { fileContent += `\n\n\n${Array.from( deprecatedFields, ).join("\n")}\n\n`; } // await fs.mkdir(getPathFor(kind, null, api), { recursive: true }); return { [filePath]: fileContent }; } /** * @param {'enums' | 'inputs' | 'types' | 'unions'} path * @param {string} fileName * @param {'query-api' | 'management-api'} api */ function getPathFor(path, fileName, api) { const pathByApi = { "query-api": queryApiSnippetsPath, "management-api": managementApiSnippetsPath, }; return `${pathByApi[api]}/${path}/${fileName != null ? `${fileName}.mdx` : ""}`; } /** * @param {import("graphql").TypeNode} type * @returns {string} */ function buildType(type) { if (type.kind === Kind.NAMED_TYPE) { return type.name.value; } if (type.kind === Kind.LIST_TYPE) { return `[${buildType(type.type)}]`; } if (type.kind === Kind.NON_NULL_TYPE) { return `${buildType(type.type)}!`; } } function checkCircularDependency(definitionName, fileName) { const checkLevel = 10; let currentLevel = 0; const initialFileName = fileName; function check(definitionName, fileName) { const queryApiDefinitions = Object.values({ ...QUERY_API_DEFINITIONS, scalarsNames: [], }).flat(); const managementApiDefinitions = Object.values({ ...MANAGEMENT_API_DEFINITIONS, scalarsNames: [], }).flat(); const apiDefinitions = [...queryApiDefinitions, ...managementApiDefinitions]; const definition = apiDefinitions.find((d) => d.name.value === definitionName); const isImported = definition?.fields?.some( (f) => normalizeGraphQLType(buildType(f.type)) === slugToPascal(initialFileName), ) ?? false; if (!isImported) { if (currentLevel >= checkLevel || definition?.fields == null) { return false; } currentLevel++; const result = definition.fields.some((f) => { const definitionType = normalizeGraphQLType(buildType(f.type)); return check(definitionType, fileName); }); return result; } return isImported; } return check(definitionName, fileName); } function normalizeGraphQLType(type) { return type.replaceAll("!", "").replaceAll("[", "").replaceAll("]", ""); } return { queryApiFiles, managementApiFiles, pagesFiles, patchExpandables }; }

Documentation Index