@xyd-js/uniform 0.1.0-xyd.10

package/src/index.ts

@@ -0,0 +1,87 @@
+// Define the new PluginV type with a callback function that returns another function
+import {Reference} from "./types";
+
+// Define the new PluginV type with a callback function that returns another function
+export type UniformPlugin<T> = (cb: (cb: () => T) => void) => (ref: Reference) => void;
+
+// Utility type to infer if a type is an array and avoid wrapping it into an array twice
+type NormalizeArray<T> = T extends Array<infer U> ? U[] : T;
+
+// Infer the return type of the plugin callback properly and normalize array types
+type PluginResult<T extends UniformPlugin<any>> = T extends UniformPlugin<infer R> ? R : never;
+
+// Merge all plugin return types into a single object and normalize arrays
+type MergePluginResults<T extends UniformPlugin<any>[]> = {
+    [K in keyof UnionToIntersection<PluginResult<T[number]>>]: NormalizeArray<UnionToIntersection<PluginResult<T[number]>>[K]>
+};
+
+// Utility type to handle intersection to an object type
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+
+// Implement the uniform function
+export default function uniform<T extends UniformPlugin<any>[]>(
+    references: Reference[],
+    config: { plugins: T }
+) {
+    // Infer the merged result type from all plugins
+    type ResultType = MergePluginResults<T>;
+
+    // Initialize the response with a type-safe out object
+    const response: {
+        references: Reference[]
+        out: { [K in keyof ResultType]: ResultType[K] }
+    } = {
+        references,
+        out: {} as { [K in keyof ResultType]: ResultType[K] }
+    };
+
+
+    const finishCallbacks = new Set();
+
+    config.plugins.forEach((plugin) => {
+        const call = plugin(cb => {
+            finishCallbacks.add(cb);
+        })
+
+        references.forEach((ref) => {
+            call(ref)
+        });
+    })
+
+    finishCallbacks.forEach(cb => {
+        if (typeof cb === "function") {
+            const resp = cb()
+            if (typeof resp !== "object") {
+                throw new Error(`Invalid callback return type: ${typeof resp}`)
+            }
+
+            response.out = {
+                ...response.out,
+                ...resp
+            }
+        } else {
+            throw new Error(`Invalid callback type: ${typeof cb}`)
+        }
+    });
+
+    return response;
+}
+
+// Example usage
+// const examplePlugin: UniformPlugin<{ value: boolean }> = (cb) => {
+//     return (ref: Reference) => {
+//     };
+// };
+// function examplePlugin(cb: (cb: () => { value: boolean }) => void) {
+//     cb(() => ({
+//         value: true,
+//     }));
+//
+//     return (ref: Reference) => {
+//
+//     };
+// }
+// const response = uniform([/* references */], {
+//     plugins: [examplePlugin],
+// });
+// response.out

package/src/markdown/index.ts

@@ -0,0 +1,67 @@
+import {remark} from "remark";
+import remarkStringify from "remark-stringify";
+
+import {Reference} from "../types";
+
+import {definitions, examples, heading, root} from "./utils";
+
+// TODO: any
+export function compile(ast: any) {
+    return remark()
+        // .use(unlimitedHeadings)
+        .use(remarkStringify, {
+            bullet: '-',
+            fences: true,
+            listItemIndent: 'one',
+            incrementListMarker: false,
+            handlers: {
+                heading(node) {
+                    return `${"#".repeat(node.depth)} ${node.children[0].value}`;
+                },
+            },
+        })
+        .stringify(root(ast));
+}
+
+export function referenceAST(ref: Reference) {
+    const md = []
+
+    const mdHeading = heading(
+        ref.title,
+        ref.canonical,
+        ref.description,
+        ref.category,
+        ref.type,
+        ref.context
+    )
+
+    md.push(
+        mdHeading.title,
+    )
+
+    if (mdHeading?.description?.length) {
+        md.push(...mdHeading.description)
+    }
+
+    md.push(
+        mdHeading.canonical,
+    )
+
+    if (mdHeading.category) {
+        md.push(mdHeading.category)
+    }
+
+    if (mdHeading.type) {
+        md.push(mdHeading.type)
+    }
+
+    if (mdHeading?.context?.length) {
+        md.push(...mdHeading.context)
+    }
+
+    const mdExamples = examples(ref.examples)
+    const mdDefinitions = definitions(ref.definitions)
+    md.push(...mdExamples, ...mdDefinitions)
+
+    return md;
+}

package/src/markdown/utils.ts

@@ -0,0 +1,258 @@
+import { fromMarkdown } from "mdast-util-from-markdown";
+import {u} from "unist-builder";
+
+import {
+    ExampleRoot,
+    Definition,
+    ReferenceCategory,
+    ReferenceContext,
+    ReferenceType,
+    DefinitionProperty
+} from "../types";
+
+// START_DEPTH_LEVEL is the start depth level for the markdown AST
+// starts from 2 because 1 is reserved for the title
+const START_DEPTH_LEVEL = 2
+
+// TODO: fix any
+export function root(ast: any) {
+    return u('root', ast);
+}
+
+export function heading(
+    title: string,
+    canonical: string,
+    description: string,
+    refCategory?: ReferenceCategory,
+    refType?: ReferenceType,
+    refContext?: ReferenceContext
+) {
+    const uTitle = u(
+        'heading',
+        {depth: START_DEPTH_LEVEL},
+        [u('text', `!!references ${title}`)]
+    )
+
+    const uCanonical = u(
+        'heading',
+        {depth: uTitle.depth + 1},
+        [u('text', `!canonical ${canonical}`)]
+    )
+
+    let uDesc = [
+        u(
+            'heading',
+            {depth: uTitle.depth + 1},
+            [u('text', `!description`),]
+        ),
+        u('paragraph', [u('text', description)])
+    ]
+
+    let uRefCategory
+    if (refCategory) {
+        uRefCategory = u(
+            'heading',
+            {depth: uTitle.depth + 1},
+            [u('text', `!category ${refCategory}`)]
+        )
+    }
+
+    let uRefType
+    if (refType) {
+        uRefType = u(
+            'heading',
+            {depth: uTitle.depth + 1},
+            [u('text', `!type ${refType}`)]
+        )
+    }
+
+    let uContext = []
+
+    if (refContext && Object.keys(refContext)) {
+        uContext.push(u(
+            'heading',
+            {depth: uTitle.depth + 1},
+            [
+                u('text', `!context`),
+            ]
+        ))
+
+
+        for (const [key, value] of Object.entries(refContext)) {
+            uContext.push(u(
+                    'heading',
+                    {depth: uContext[0].depth + 1},
+                    [u('text', `!${key} ${value}`)]
+                )
+            )
+        }
+    }
+
+    return {
+        title: uTitle,
+        canonical: uCanonical,
+        description: uDesc,
+        category: uRefCategory || null,
+        type: uRefType || null,
+        context: uContext || null
+    }
+}
+
+export function examples(examples: ExampleRoot) {
+    const md = []
+
+    const uExampleRoot = u(
+        'heading',
+        {depth: START_DEPTH_LEVEL + 1},
+        [u('text', `!examples`)]
+    )
+    md.push(uExampleRoot)
+
+    examples.groups.forEach(group => {
+        const uExampleGroups = u(
+            'heading',
+            {depth: uExampleRoot.depth + 1},
+            [u('text', `!!groups`)]
+        )
+        md.push(uExampleGroups)
+
+        const uGroupDescription = u(
+            'heading',
+            {depth: uExampleGroups.depth + 1},
+            [u('text', `!description ${group.description}`)]
+        )
+        md.push(uGroupDescription)
+
+        group.examples.forEach(example => {
+            const uExamples = u(
+                'heading',
+                {depth: uExampleGroups.depth + 1},
+                [u('text', `!!examples`)]
+            )
+            md.push(uExamples)
+
+            const codeBlock = u(
+                'heading',
+                {depth: uExamples.depth + 1},
+                [u('text', `!codeblock`)]
+            )
+            md.push(codeBlock)
+
+            const codeBlockTitle = u(
+                'heading',
+                {depth: codeBlock.depth + 1},
+                [u('text', `!title ${example.codeblock.title}`)]
+            )
+            md.push(codeBlockTitle)
+
+            const tabs = u(
+                'heading',
+                {depth: codeBlock.depth + 1},
+                [u('text', `!!tabs`)]
+            )
+            md.push(tabs)
+
+            example.codeblock.tabs.forEach(tab => {
+                const code = u('code', {
+                    lang: tab.language,
+                    meta: `!code ${tab.title}`
+                }, tab.code);
+
+                md.push(code)
+            })
+
+        })
+    })
+
+    return md
+}
+
+export function definitions(definitions: Definition[]) {
+    const md: any[] = []
+
+    definitions.forEach(definition => {
+        const uDefinition = u(
+            'heading',
+            {depth: START_DEPTH_LEVEL + 1},
+            [u('text', `!!definitions`)]
+        )
+        md.push(uDefinition)
+
+        md.push(u(
+            'heading',
+            {depth: uDefinition.depth + 1},
+            [u('text', `!title ${definition.title}`)]
+        ))
+
+        definition.properties.forEach(prop => {
+            properties(
+                uDefinition.depth + 1,
+                {
+                    name: prop.name,
+                    type: prop.type,
+                    description: prop.description,
+                    context: prop.context,
+                    properties: prop.properties  // TODO: fix ts
+                },
+                md,
+            )
+        })
+    })
+
+    return md
+}
+
+// TODO: any[]
+export function properties(
+    depth: number,
+    props: DefinitionProperty,
+    output: any[] = []
+) {
+    const paramName = props.name;
+
+    const propTitle = `!!properties ${paramName}`; // TODO: check if `!!properties is enough`
+    const uPropTitle = u('heading', {depth}, [u('text', propTitle)]);
+    const uPropName = u('paragraph', {depth}, [u('text', `!name ${paramName}`)]);
+    const uPropType = u('paragraph', {depth}, [u('text', `!type ${props.type}`)]);
+    const markdownAst = fromMarkdown(props.description || '');
+    const uPropDesc = u("paragraph", { depth }, markdownAst.children);
+    const uContext = []
+
+    if (props.context && Object.keys(props.context)) {
+        uContext.push(u(
+            'heading',
+            {depth: depth + 1},
+            [
+                u('text', `!context`),
+            ]
+        ))
+
+        for (const [key, value] of Object.entries(props.context)) {
+            uContext.push(u(
+                    'heading',
+                    {depth: uContext[0].depth + 1},
+                    [u('text', `!${key} ${value}`)]
+                )
+            )
+        }
+    }
+
+    output.push(
+        uPropTitle,
+        uPropName,
+        uPropType,
+        uPropDesc,
+        ...uContext
+    );
+
+    if (props.properties) {
+        const deepDepth = depth + 1
+
+        for (const prop of props.properties) {
+            properties(deepDepth, prop, output)
+        }
+    }
+}
+
+
+

package/src/types.ts

@@ -0,0 +1,137 @@
+// TODO: concept only
+export enum ReferenceCategory {
+    // for React
+    COMPONENTS = "components",
+    HOOKS = "hooks",
+    // end for React
+
+    // for API
+    REST = "rest",
+    GRAPHQL = "graphql",
+    // end for API
+
+    // for code
+    FUNCTIONS = "functions",
+    //
+}
+
+// TODO: concept only
+export enum ReferenceType {
+    // for React
+    COMPONENT = "component",
+    HOOK = "hook",
+    // end for React
+
+    // for API
+    REST_HTTP_GET = "rest_get",
+    REST_HTTP_POST = "rest_post",
+    REST_HTTP_PUT = "rest_put",
+    REST_HTTP_PATCH = "rest_patch",
+    REST_HTTP_DELETE = "rest_delete",
+    // ---
+    GRAPHQL_QUERY = "graphql_query",
+    GRAPHQL_MUTATION = "graphql_mutation",
+    // end for API
+
+    // for code
+    FUNCTION_JS = "function_js",
+    // end for code
+}
+
+export interface GraphQLReferenceContext {
+}
+
+// TODO: custom value?
+export interface OpenAPIReferenceContext {
+    method: string;
+
+    path: string;
+}
+
+export type ReferenceContext = GraphQLReferenceContext | OpenAPIReferenceContext;
+
+export interface ExampleRoot {
+    groups: ExampleGroup[];
+}
+
+export interface ExampleGroup {
+    description?: string;
+
+    examples: Example[];
+}
+
+export interface Example {
+    description?: string; // TODO: replace with title ?
+
+    codeblock: CodeBlock;
+}
+
+export interface CodeBlock {
+    title?: string;
+
+    tabs: CodeBlockTab[];
+}
+
+export interface GraphQLExampleContext {
+    schema?: any; // TODO:
+}
+
+export interface OpenAPIExampleContext {
+    status?: number;
+
+    content?: string;
+}
+
+export type ExampleContext = GraphQLExampleContext | OpenAPIExampleContext;
+
+export interface CodeBlockTab {
+    // title of the tab e.g "JavaScript"
+    title: string;
+
+    // code in the tab e.g "console.log('Hello World')"
+    code: string
+    
+    // language of the code e.g "js"
+    language: string;
+
+    // context of the generation method e.g openapi or graphql
+    context?: ExampleContext;
+}
+
+export interface Reference {
+    title: string;
+    description: string;
+    canonical: string;
+
+    definitions: Definition[]
+    examples: ExampleRoot
+
+    category?: ReferenceCategory; // TODO: do we need that?
+    type?: ReferenceType; // TODO: do we need that?
+    context?: ReferenceContext;
+}
+
+export interface Definition {
+    title: string;
+
+    properties: DefinitionProperty[];
+
+
+    type?: string;
+
+    id?: string;
+
+    description?: string;
+}
+
+export interface DefinitionProperty {
+    name: string;
+
+    type: string;
+
+    description: string;
+
+    context?: any // TODO: better type
+
+    properties?: DefinitionProperty[];
+}

package/src/utils.ts

@@ -0,0 +1,123 @@
+import path from 'path';
+import matter from 'gray-matter';
+import {Sidebar, FrontMatter, PageFrontMatter} from "@xyd-js/core";
+
+import {Reference} from "./types";
+import uniform from "./index";
+
+// interface UniformFrontMatter extends FrontMatter { // TODO: it's concept only
+//     scopes?: string
+// }
+
+type GroupMap = {
+    [key: string]: {
+        __groups: GroupMap
+        pages: Set<string>
+    }
+}
+
+export interface pluginNavigationOptions {
+    urlPrefix: string
+}
+
+export function pluginNavigation(options: pluginNavigationOptions) {
+    if (!options.urlPrefix) {
+        throw new Error("urlPrefix is required")
+    }
+
+    return function pluginNavigationInner(cb: (cb: () => {
+        pageFrontMatter: PageFrontMatter
+        sidebar: Sidebar[]
+    }) => void) {
+        const pageFrontMatter: PageFrontMatter = {}
+        const groupMaps: GroupMap = {}
+
+        cb(() => {
+            return {
+                pageFrontMatter: pageFrontMatter,
+                sidebar: convertGroupMapsToNavigations(groupMaps) as Sidebar[]
+            }
+        })
+
+        return (ref: Reference) => {
+            const content = matter(ref.description || "") // TODO: pluginMatter before?
+
+            if (content.data) {
+                const data = content.data as FrontMatter
+
+                const pagePath = path.join(options.urlPrefix, ref.canonical)
+
+                if (data.title) {
+                    pageFrontMatter[pagePath] = {
+                        title: data.title,
+                    }
+                }
+
+                if (data.group) {
+                    if (typeof content?.data?.group === "string") {
+                        // TODO: seek nested group (it's not always from 0)
+                        throw new Error("group as string is not supported yet")
+                    }
+
+                    content.data.group.reduce((groups: GroupMap, group: string, i: number) => {
+                        if (!groups[group]) {
+                            groups[group] = {
+                                __groups: {},
+                                pages: new Set()
+                            }
+                        }
+
+                        if (i === content.data.group.length - 1) {
+                            groups[group].pages.add(pagePath)
+                        }
+
+                        return groups[group].__groups
+                    }, groupMaps)
+                }
+
+                // back description to original without frontmatter
+                ref.description = content.content
+            }
+        }
+    }
+}
+
+
+function convertGroupMapsToNavigations(groupMaps: GroupMap): Sidebar[] {
+    const nav: Sidebar[] = []
+
+    Object.keys(groupMaps).map((groupName) => {
+        const current = groupMaps[groupName]
+
+        const pages: string[] | Sidebar[] = []
+
+        current.pages.forEach((page: string) => {
+            pages.push(page)
+        })
+
+        if (Object.keys(current.__groups).length) {
+            const subNav: Sidebar = {
+                group: groupName,
+                pages: convertGroupMapsToNavigations(current.__groups)
+            }
+
+            nav.push(subNav)
+        } else {
+            nav.push({
+                group: groupName,
+                pages,
+            })
+        }
+    })
+
+    return nav
+}
+
+// example usage:
+// const response = uniform([/* references */], {
+//     plugins: [pluginNavigation({
+//         urlPrefix: "/docs"
+//     })],
+// });
+
+

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"]
+}