@player-tools/xlr-utils 0.4.0-next.0 → 0.4.0-next.2

package/dist/index.cjs.js

@@ -562,10 +562,201 @@ function setupTestEnv(sourceCode, mockFileName = "filename.ts") {
   };
 }
 
+function insertBetweenElements(array, separator) {
+  return array.reduce((acc, item, index) => {
+    if (index === 0) {
+      return [item];
+    }
+    return [...acc, separator, item];
+  }, []);
+}
+function createTSDocString(node) {
+  if (node.type === "ref") {
+    return [
+      {
+        text: node.ref,
+        kind: ts.SymbolDisplayPartKind.keyword
+      }
+    ];
+  }
+  if (node.type === "or" || node.type === "and") {
+    const items = node.type === "and" ? node.and : node.or;
+    return insertBetweenElements(items.map((subnode) => createTSDocString(subnode)), [
+      {
+        kind: ts.SymbolDisplayPartKind.punctuation,
+        text: node.type === "and" ? " & " : " | "
+      }
+    ]).flat();
+  }
+  if (node.type === "function") {
+    return [
+      {
+        kind: ts.SymbolDisplayPartKind.keyword,
+        text: "function"
+      },
+      {
+        kind: ts.SymbolDisplayPartKind.space,
+        text: " "
+      },
+      ...node.name ? [{ text: node.name, kind: ts.SymbolDisplayPartKind.methodName }] : [],
+      {
+        kind: ts.SymbolDisplayPartKind.punctuation,
+        text: "("
+      },
+      ...insertBetweenElements(node.parameters.map((p) => {
+        if (p.name) {
+          return [
+            {
+              kind: ts.SymbolDisplayPartKind.parameterName,
+              text: p.name
+            },
+            {
+              kind: ts.SymbolDisplayPartKind.punctuation,
+              text: p.optional ? "?" : ""
+            },
+            {
+              kind: ts.SymbolDisplayPartKind.punctuation,
+              text: ": "
+            },
+            ...createTSDocString(p.type)
+          ];
+        }
+        return createTSDocString(p.type);
+      }), [
+        {
+          kind: ts.SymbolDisplayPartKind.punctuation,
+          text: ", "
+        }
+      ]).flat(),
+      {
+        kind: ts.SymbolDisplayPartKind.punctuation,
+        text: ")"
+      },
+      ...node.returnType ? [
+        {
+          kind: ts.SymbolDisplayPartKind.punctuation,
+          text: ": "
+        },
+        ...createTSDocString(node.returnType)
+      ] : []
+    ];
+  }
+  if (node.type === "tuple") {
+    return [
+      {
+        kind: ts.SymbolDisplayPartKind.punctuation,
+        text: "["
+      },
+      ...insertBetweenElements(node.elementTypes.map((t) => {
+        if (t.name) {
+          return [
+            {
+              kind: ts.SymbolDisplayPartKind.propertyName,
+              text: t.name
+            },
+            {
+              kind: ts.SymbolDisplayPartKind.punctuation,
+              text: ": "
+            },
+            ...createTSDocString(t.type)
+          ];
+        }
+        return createTSDocString(t.type);
+      }), [
+        {
+          kind: ts.SymbolDisplayPartKind.punctuation,
+          text: ", "
+        }
+      ]).flat(),
+      {
+        kind: ts.SymbolDisplayPartKind.punctuation,
+        text: "]"
+      }
+    ];
+  }
+  if (node.type === "array") {
+    return [
+      {
+        kind: ts.SymbolDisplayPartKind.interfaceName,
+        text: "Array"
+      },
+      {
+        kind: ts.SymbolDisplayPartKind.punctuation,
+        text: "<"
+      },
+      ...createTSDocString(node.elementType),
+      {
+        kind: ts.SymbolDisplayPartKind.punctuation,
+        text: ">"
+      }
+    ];
+  }
+  if (node.type === "record") {
+    return [
+      {
+        kind: ts.SymbolDisplayPartKind.interfaceName,
+        text: "Record"
+      },
+      {
+        kind: ts.SymbolDisplayPartKind.punctuation,
+        text: "<"
+      },
+      ...createTSDocString(node.keyType),
+      {
+        kind: ts.SymbolDisplayPartKind.punctuation,
+        text: ", "
+      },
+      ...createTSDocString(node.valueType),
+      {
+        kind: ts.SymbolDisplayPartKind.punctuation,
+        text: ">"
+      }
+    ];
+  }
+  if ((node.type === "string" || node.type === "boolean" || node.type === "number") && node.const !== void 0) {
+    return [
+      {
+        kind: ts.SymbolDisplayPartKind.keyword,
+        text: typeof node.const === "string" ? `'${node.const}'` : String(node.const)
+      }
+    ];
+  }
+  if (isPrimitiveTypeNode(node) && node.type !== "null") {
+    return [
+      {
+        kind: ts.SymbolDisplayPartKind.keyword,
+        text: node.type
+      }
+    ];
+  }
+  if (node.type === "object" && node.name) {
+    return [
+      {
+        kind: ts.SymbolDisplayPartKind.interfaceName,
+        text: node.name
+      }
+    ];
+  }
+  return [
+    {
+      kind: ts.SymbolDisplayPartKind.localName,
+      text: node.type
+    }
+  ];
+}
+function symbolDisplayToString(displayParts) {
+  return ts.displayPartsToString(displayParts);
+}
+function createDocString(node) {
+  return symbolDisplayToString(createTSDocString(node));
+}
+
 exports.applyPartialOrRequiredToNodeType = applyPartialOrRequiredToNodeType;
 exports.applyPickOrOmitToNodeType = applyPickOrOmitToNodeType;
 exports.buildTemplateRegex = buildTemplateRegex;
 exports.computeEffectiveObject = computeEffectiveObject;
+exports.createDocString = createDocString;
+exports.createTSDocString = createTSDocString;
 exports.decorateNode = decorateNode;
 exports.fillInGenerics = fillInGenerics;
 exports.getReferencedType = getReferencedType;
@@ -588,5 +779,6 @@ exports.propertyToTuple = propertyToTuple;
 exports.resolveConditional = resolveConditional;
 exports.resolveReferenceNode = resolveReferenceNode;
 exports.setupTestEnv = setupTestEnv;
+exports.symbolDisplayToString = symbolDisplayToString;
 exports.tsStripOptionalType = tsStripOptionalType;
 //# sourceMappingURL=index.cjs.js.map

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import ts__default from 'typescript';
+import ts__default, { SymbolDisplayPart } from 'typescript';
 import { Annotations, NodeType, NodeTypeWithGenerics, NamedType, NamedTypeWithGenerics, PrimitiveTypes, ConditionalType, RefNode, ObjectType } from '@player-tools/xlr';
 import { Node } from 'jsonc-parser';
 
@@ -141,4 +141,16 @@ declare function setupTestEnv(sourceCode: string, mockFileName?: string): {
     tc: ts.TypeChecker;
 };
 
-export { PropertyNode, SetupReturnType, TopLevelDeclaration, TopLevelNode, applyPartialOrRequiredToNodeType, applyPickOrOmitToNodeType, buildTemplateRegex, computeEffectiveObject, decorateNode, fillInGenerics, getReferencedType, getStringLiteralsFromUnion, isExportedDeclaration, isGenericInterfaceDeclaration, isGenericNamedType, isGenericNodeType, isGenericTypeDeclaration, isNode, isNodeExported, isNonNullable, isOptionalProperty, isPrimitiveTypeNode, isTopLevelDeclaration, isTopLevelNode, isTypeReferenceGeneric, makePropertyMap, propertyToTuple, resolveConditional, resolveReferenceNode, setupTestEnv, tsStripOptionalType };
+/**
+ * Generate a documentation string for a given node
+ *
+ * @param node - The source node to author the docs string for
+ * @returns - documentation string
+ */
+declare function createTSDocString(node: NodeType): Array<SymbolDisplayPart>;
+/** Convert the TS SymbolDisplayParts into a single string */
+declare function symbolDisplayToString(displayParts: Array<SymbolDisplayPart>): string;
+/** Create a documentation string from node */
+declare function createDocString(node: NodeType): string;
+
+export { PropertyNode, SetupReturnType, TopLevelDeclaration, TopLevelNode, applyPartialOrRequiredToNodeType, applyPickOrOmitToNodeType, buildTemplateRegex, computeEffectiveObject, createDocString, createTSDocString, decorateNode, fillInGenerics, getReferencedType, getStringLiteralsFromUnion, isExportedDeclaration, isGenericInterfaceDeclaration, isGenericNamedType, isGenericNodeType, isGenericTypeDeclaration, isNode, isNodeExported, isNonNullable, isOptionalProperty, isPrimitiveTypeNode, isTopLevelDeclaration, isTopLevelNode, isTypeReferenceGeneric, makePropertyMap, propertyToTuple, resolveConditional, resolveReferenceNode, setupTestEnv, symbolDisplayToString, tsStripOptionalType };

package/dist/index.esm.js

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import ts__default from 'typescript';
+import ts__default, { SymbolDisplayPartKind, displayPartsToString } from 'typescript';
 import * as tsvfs from '@typescript/vfs';
 
 var __defProp$2 = Object.defineProperty;
@@ -535,5 +535,194 @@ function setupTestEnv(sourceCode, mockFileName = "filename.ts") {
   };
 }
 
-export { applyPartialOrRequiredToNodeType, applyPickOrOmitToNodeType, buildTemplateRegex, computeEffectiveObject, decorateNode, fillInGenerics, getReferencedType, getStringLiteralsFromUnion, isExportedDeclaration, isGenericInterfaceDeclaration, isGenericNamedType, isGenericNodeType, isGenericTypeDeclaration, isNode, isNodeExported, isNonNullable, isOptionalProperty, isPrimitiveTypeNode, isTopLevelDeclaration, isTopLevelNode, isTypeReferenceGeneric, makePropertyMap, propertyToTuple, resolveConditional, resolveReferenceNode, setupTestEnv, tsStripOptionalType };
+function insertBetweenElements(array, separator) {
+  return array.reduce((acc, item, index) => {
+    if (index === 0) {
+      return [item];
+    }
+    return [...acc, separator, item];
+  }, []);
+}
+function createTSDocString(node) {
+  if (node.type === "ref") {
+    return [
+      {
+        text: node.ref,
+        kind: SymbolDisplayPartKind.keyword
+      }
+    ];
+  }
+  if (node.type === "or" || node.type === "and") {
+    const items = node.type === "and" ? node.and : node.or;
+    return insertBetweenElements(items.map((subnode) => createTSDocString(subnode)), [
+      {
+        kind: SymbolDisplayPartKind.punctuation,
+        text: node.type === "and" ? " & " : " | "
+      }
+    ]).flat();
+  }
+  if (node.type === "function") {
+    return [
+      {
+        kind: SymbolDisplayPartKind.keyword,
+        text: "function"
+      },
+      {
+        kind: SymbolDisplayPartKind.space,
+        text: " "
+      },
+      ...node.name ? [{ text: node.name, kind: SymbolDisplayPartKind.methodName }] : [],
+      {
+        kind: SymbolDisplayPartKind.punctuation,
+        text: "("
+      },
+      ...insertBetweenElements(node.parameters.map((p) => {
+        if (p.name) {
+          return [
+            {
+              kind: SymbolDisplayPartKind.parameterName,
+              text: p.name
+            },
+            {
+              kind: SymbolDisplayPartKind.punctuation,
+              text: p.optional ? "?" : ""
+            },
+            {
+              kind: SymbolDisplayPartKind.punctuation,
+              text: ": "
+            },
+            ...createTSDocString(p.type)
+          ];
+        }
+        return createTSDocString(p.type);
+      }), [
+        {
+          kind: SymbolDisplayPartKind.punctuation,
+          text: ", "
+        }
+      ]).flat(),
+      {
+        kind: SymbolDisplayPartKind.punctuation,
+        text: ")"
+      },
+      ...node.returnType ? [
+        {
+          kind: SymbolDisplayPartKind.punctuation,
+          text: ": "
+        },
+        ...createTSDocString(node.returnType)
+      ] : []
+    ];
+  }
+  if (node.type === "tuple") {
+    return [
+      {
+        kind: SymbolDisplayPartKind.punctuation,
+        text: "["
+      },
+      ...insertBetweenElements(node.elementTypes.map((t) => {
+        if (t.name) {
+          return [
+            {
+              kind: SymbolDisplayPartKind.propertyName,
+              text: t.name
+            },
+            {
+              kind: SymbolDisplayPartKind.punctuation,
+              text: ": "
+            },
+            ...createTSDocString(t.type)
+          ];
+        }
+        return createTSDocString(t.type);
+      }), [
+        {
+          kind: SymbolDisplayPartKind.punctuation,
+          text: ", "
+        }
+      ]).flat(),
+      {
+        kind: SymbolDisplayPartKind.punctuation,
+        text: "]"
+      }
+    ];
+  }
+  if (node.type === "array") {
+    return [
+      {
+        kind: SymbolDisplayPartKind.interfaceName,
+        text: "Array"
+      },
+      {
+        kind: SymbolDisplayPartKind.punctuation,
+        text: "<"
+      },
+      ...createTSDocString(node.elementType),
+      {
+        kind: SymbolDisplayPartKind.punctuation,
+        text: ">"
+      }
+    ];
+  }
+  if (node.type === "record") {
+    return [
+      {
+        kind: SymbolDisplayPartKind.interfaceName,
+        text: "Record"
+      },
+      {
+        kind: SymbolDisplayPartKind.punctuation,
+        text: "<"
+      },
+      ...createTSDocString(node.keyType),
+      {
+        kind: SymbolDisplayPartKind.punctuation,
+        text: ", "
+      },
+      ...createTSDocString(node.valueType),
+      {
+        kind: SymbolDisplayPartKind.punctuation,
+        text: ">"
+      }
+    ];
+  }
+  if ((node.type === "string" || node.type === "boolean" || node.type === "number") && node.const !== void 0) {
+    return [
+      {
+        kind: SymbolDisplayPartKind.keyword,
+        text: typeof node.const === "string" ? `'${node.const}'` : String(node.const)
+      }
+    ];
+  }
+  if (isPrimitiveTypeNode(node) && node.type !== "null") {
+    return [
+      {
+        kind: SymbolDisplayPartKind.keyword,
+        text: node.type
+      }
+    ];
+  }
+  if (node.type === "object" && node.name) {
+    return [
+      {
+        kind: SymbolDisplayPartKind.interfaceName,
+        text: node.name
+      }
+    ];
+  }
+  return [
+    {
+      kind: SymbolDisplayPartKind.localName,
+      text: node.type
+    }
+  ];
+}
+function symbolDisplayToString(displayParts) {
+  return displayPartsToString(displayParts);
+}
+function createDocString(node) {
+  return symbolDisplayToString(createTSDocString(node));
+}
+
+export { applyPartialOrRequiredToNodeType, applyPickOrOmitToNodeType, buildTemplateRegex, computeEffectiveObject, createDocString, createTSDocString, decorateNode, fillInGenerics, getReferencedType, getStringLiteralsFromUnion, isExportedDeclaration, isGenericInterfaceDeclaration, isGenericNamedType, isGenericNodeType, isGenericTypeDeclaration, isNode, isNodeExported, isNonNullable, isOptionalProperty, isPrimitiveTypeNode, isTopLevelDeclaration, isTopLevelNode, isTypeReferenceGeneric, makePropertyMap, propertyToTuple, resolveConditional, resolveReferenceNode, setupTestEnv, symbolDisplayToString, tsStripOptionalType };
 //# sourceMappingURL=index.esm.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@player-tools/xlr-utils",
-  "version": "0.4.0-next.0",
+  "version": "0.4.0-next.2",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
@@ -10,7 +10,7 @@
     "jsonc-parser": "^2.3.1"
   },
   "dependencies": {
-    "@player-tools/xlr": "0.4.0-next.0",
+    "@player-tools/xlr": "0.4.0-next.2",
     "@typescript/vfs": "^1.4.0",
     "@babel/runtime": "7.15.4"
   },

package/src/documentation.ts

@@ -0,0 +1,241 @@
+import { SymbolDisplayPartKind, displayPartsToString } from 'typescript';
+import type { SymbolDisplayPart } from 'typescript';
+import type { NodeType } from '@player-tools/xlr';
+import { isPrimitiveTypeNode } from './type-checks';
+
+/** Like `.join()` but for arrays */
+function insertBetweenElements<T>(array: Array<T>, separator: T): T[] {
+  return array.reduce((acc, item, index) => {
+    if (index === 0) {
+      return [item];
+    }
+
+    return [...acc, separator, item];
+  }, [] as T[]);
+}
+
+/**
+ * Generate a documentation string for a given node
+ *
+ * @param node - The source node to author the docs string for
+ * @returns - documentation string
+ */
+export function createTSDocString(node: NodeType): Array<SymbolDisplayPart> {
+  if (node.type === 'ref') {
+    return [
+      {
+        text: node.ref,
+        kind: SymbolDisplayPartKind.keyword as any,
+      },
+    ];
+  }
+
+  if (node.type === 'or' || node.type === 'and') {
+    const items = node.type === 'and' ? node.and : node.or;
+
+    return insertBetweenElements(
+      items.map((subnode) => createTSDocString(subnode)),
+      [
+        {
+          kind: SymbolDisplayPartKind.punctuation as any,
+          text: node.type === 'and' ? ' & ' : ' | ',
+        },
+      ]
+    ).flat();
+  }
+
+  if (node.type === 'function') {
+    return [
+      {
+        kind: SymbolDisplayPartKind.keyword as any,
+        text: 'function',
+      },
+      {
+        kind: SymbolDisplayPartKind.space as any,
+        text: ' ',
+      },
+      ...(node.name
+        ? [{ text: node.name, kind: SymbolDisplayPartKind.methodName }]
+        : []),
+      {
+        kind: SymbolDisplayPartKind.punctuation as any,
+        text: '(',
+      },
+      ...insertBetweenElements(
+        node.parameters.map((p) => {
+          if (p.name) {
+            return [
+              {
+                kind: SymbolDisplayPartKind.parameterName as any,
+                text: p.name,
+              },
+              {
+                kind: SymbolDisplayPartKind.punctuation as any,
+                text: p.optional ? '?' : '',
+              },
+              {
+                kind: SymbolDisplayPartKind.punctuation as any,
+                text: ': ',
+              },
+              ...createTSDocString(p.type),
+            ];
+          }
+
+          return createTSDocString(p.type);
+        }),
+        [
+          {
+            kind: SymbolDisplayPartKind.punctuation as any,
+            text: ', ',
+          },
+        ]
+      ).flat(),
+      {
+        kind: SymbolDisplayPartKind.punctuation as any,
+        text: ')',
+      },
+      ...(node.returnType
+        ? [
+            {
+              kind: SymbolDisplayPartKind.punctuation as any,
+              text: ': ',
+            },
+            ...createTSDocString(node.returnType),
+          ]
+        : []),
+    ];
+  }
+
+  if (node.type === 'tuple') {
+    return [
+      {
+        kind: SymbolDisplayPartKind.punctuation as any,
+        text: '[',
+      },
+      ...insertBetweenElements(
+        node.elementTypes.map((t) => {
+          if (t.name) {
+            return [
+              {
+                kind: SymbolDisplayPartKind.propertyName as any,
+                text: t.name,
+              },
+              {
+                kind: SymbolDisplayPartKind.punctuation as any,
+                text: ': ',
+              },
+              ...createTSDocString(t.type),
+            ];
+          }
+
+          return createTSDocString(t.type);
+        }),
+        [
+          {
+            kind: SymbolDisplayPartKind.punctuation as any,
+            text: ', ',
+          },
+        ]
+      ).flat(),
+      {
+        kind: SymbolDisplayPartKind.punctuation as any,
+        text: ']',
+      },
+    ];
+  }
+
+  if (node.type === 'array') {
+    return [
+      {
+        kind: SymbolDisplayPartKind.interfaceName as any,
+        text: 'Array',
+      },
+      {
+        kind: SymbolDisplayPartKind.punctuation as any,
+        text: '<',
+      },
+      ...createTSDocString(node.elementType),
+      {
+        kind: SymbolDisplayPartKind.punctuation as any,
+        text: '>',
+      },
+    ];
+  }
+
+  if (node.type === 'record') {
+    return [
+      {
+        kind: SymbolDisplayPartKind.interfaceName as any,
+        text: 'Record',
+      },
+      {
+        kind: SymbolDisplayPartKind.punctuation as any,
+        text: '<',
+      },
+      ...createTSDocString(node.keyType),
+      {
+        kind: SymbolDisplayPartKind.punctuation as any,
+        text: ', ',
+      },
+      ...createTSDocString(node.valueType),
+      {
+        kind: SymbolDisplayPartKind.punctuation as any,
+        text: '>',
+      },
+    ];
+  }
+
+  if (
+    (node.type === 'string' ||
+      node.type === 'boolean' ||
+      node.type === 'number') &&
+    node.const !== undefined
+  ) {
+    return [
+      {
+        kind: SymbolDisplayPartKind.keyword as any,
+        text:
+          typeof node.const === 'string'
+            ? `'${node.const}'`
+            : String(node.const),
+      },
+    ];
+  }
+
+  if (isPrimitiveTypeNode(node) && node.type !== 'null') {
+    return [
+      {
+        kind: SymbolDisplayPartKind.keyword as any,
+        text: node.type,
+      },
+    ];
+  }
+
+  if (node.type === 'object' && node.name) {
+    return [
+      {
+        kind: SymbolDisplayPartKind.interfaceName as any,
+        text: node.name,
+      },
+    ];
+  }
+
+  return [
+    {
+      kind: SymbolDisplayPartKind.localName as any,
+      text: node.type,
+    },
+  ];
+}
+
+/** Convert the TS SymbolDisplayParts into a single string */
+export function symbolDisplayToString(
+  displayParts: Array<SymbolDisplayPart>
+): string {
+  return displayPartsToString(displayParts);
+}
+
+/** Create a documentation string from node */
+export function createDocString(node: NodeType): string {
+  return symbolDisplayToString(createTSDocString(node));
+}

package/src/index.ts

@@ -3,3 +3,4 @@ export * from './ts-helpers';
 export * from './type-checks';
 export * from './validation-helpers';
 export * from './test-helpers';
+export * from './documentation';