@player-tools/xlr-utils 0.0.2-next.0

package/src/annotations.ts

@@ -0,0 +1,230 @@
+import * as ts from 'typescript';
+import type { Annotations } from '@player-tools/xlr';
+
+interface JSDocContainer {
+  /** */
+  jsDoc: Array<ts.JSDoc>;
+}
+
+/**
+ *
+ */
+function extractDescription(text: string | undefined): Annotations {
+  if (!text) {
+    return {};
+  }
+
+  return { description: text };
+}
+
+/**
+ * Checks if the parent node is a non-object type
+ */
+function parentIsNonObjectPath(node: ts.Node) {
+  return (
+    node.parent &&
+    (ts.isArrayTypeNode(node.parent) ||
+      ts.isTupleTypeNode(node.parent) ||
+      ts.isOptionalTypeNode(node.parent) ||
+      ts.isRestTypeNode(node.parent) ||
+      ts.isUnionTypeNode(node.parent))
+  );
+}
+
+/**
+ * Traverses up the node tree to build the title path down to the initial node
+ */
+function recurseTypeChain(
+  node: ts.Node,
+  child: ts.Node | undefined
+): Array<string> {
+  if (!node) {
+    return [];
+  }
+
+  if (
+    ts.isArrayTypeNode(node) &&
+    node.parent &&
+    ts.isRestTypeNode(node.parent)
+  ) {
+    return recurseTypeChain(node.parent, node);
+  }
+
+  if (ts.isRestTypeNode(node)) {
+    return recurseTypeChain(node.parent, node);
+  }
+
+  if (ts.isOptionalTypeNode(node)) {
+    return recurseTypeChain(node.parent, node);
+  }
+
+  if (ts.isUnionTypeNode(node)) {
+    return recurseTypeChain(node.parent, node);
+  }
+
+  if (ts.isParenthesizedTypeNode(node)) {
+    return recurseTypeChain(node.parent, node);
+  }
+
+  if (ts.isTypeLiteralNode(node)) {
+    return recurseTypeChain(node.parent, node);
+  }
+
+  if (ts.isArrayTypeNode(node)) {
+    return ['[]', ...recurseTypeChain(node.parent, node)];
+  }
+
+  if (ts.isTupleTypeNode(node)) {
+    const pos = node.elements.indexOf(child as any);
+    return [
+      ...(pos === -1 ? [] : [`${pos}`]),
+      ...recurseTypeChain(node.parent, node),
+    ];
+  }
+
+  if (
+    ts.isTypeAliasDeclaration(node) ||
+    ts.isInterfaceDeclaration(node) ||
+    ts.isPropertySignature(node)
+  ) {
+    return [node.name.getText(), ...recurseTypeChain(node.parent, node)];
+  }
+
+  if (parentIsNonObjectPath(node)) {
+    return recurseTypeChain(node.parent, node);
+  }
+
+  return [];
+}
+
+/**
+ * Builds the `Title` property by traversing up and noting the named types in the tree
+ */
+function extractTitle(node: ts.Node): Annotations {
+  const typeNames = recurseTypeChain(node, undefined).reverse().join('.');
+
+  if (!typeNames.length) {
+    return {};
+  }
+
+  return { title: typeNames };
+}
+
+/**
+ *
+ */
+function stringifyDoc(
+  docString: undefined | string | ts.NodeArray<ts.JSDocComment>
+): string | undefined {
+  if (typeof docString === 'undefined' || typeof docString === 'string') {
+    return docString;
+  }
+
+  return docString.map(({ text }) => text).join(' ');
+}
+
+/**
+ * Extracts JSDoc tags to strings
+ */
+function extractTags(tags: ReadonlyArray<ts.JSDocTag>): Annotations {
+  const descriptions: Array<string> = [];
+  const examples: Array<string> = [];
+  const _default: Array<string> = [];
+  const see: Array<string> = [];
+
+  /**
+   *
+   */
+  const extractSee = (tag: ts.JSDocSeeTag) => {
+    return `${tag.tagName ? `${tag.tagName?.getText()} ` : ''}${
+      stringifyDoc(tag.comment)?.trim() ?? ''
+    }`;
+  };
+
+  tags.forEach((tag) => {
+    if (!tag.comment) {
+      return;
+    }
+
+    if (tag.tagName.text === 'example') {
+      examples.push(stringifyDoc(tag.comment)?.trim() ?? '');
+    } else if (tag.tagName.text === 'default') {
+      _default.push(stringifyDoc(tag.comment)?.trim() ?? '');
+    } else if (tag.tagName.text === 'see') {
+      see.push(extractSee(tag as ts.JSDocSeeTag));
+    } else {
+      const text = stringifyDoc(tag.comment)?.trim() ?? '';
+      descriptions.push(`@${tag.tagName.text} ${text}`);
+    }
+  });
+
+  return {
+    ...(descriptions.length === 0
+      ? {}
+      : { description: descriptions.join('\n') }),
+    ...(examples.length === 0 ? {} : { examples }),
+    ...(_default.length === 0 ? {} : { default: _default.join('\n') }),
+    ...(see.length === 0 ? {} : { see }),
+  };
+}
+
+/**
+ * Joins Arrays of maybe strings with a given separator
+ */
+function join(t: Array<string | undefined>, separator = '\n') {
+  const unique = new Set(t).values();
+  return Array.from(unique)
+    .filter((s) => s !== undefined)
+    .join(separator)
+    .trim();
+}
+
+/**
+ * Merges Annotation nodes for various nodes
+ */
+function mergeAnnotations(nodes: Array<Annotations>): Annotations {
+  const name = nodes.find((n) => n.name)?.name;
+  const title = join(
+    nodes.map((n) => n.title),
+    ', '
+  );
+  const description = join(nodes.map((n) => n.description));
+  const _default = join(nodes.map((n) => n.default));
+  const comment = join(nodes.map((n) => n.comment));
+  const examples = join(
+    nodes.map((n) =>
+      Array.isArray(n.examples) ? join(n.examples) : n.examples
+    )
+  );
+  const see = join(
+    nodes.map((n) => (Array.isArray(n.see) ? join(n.see) : n.see))
+  );
+  return {
+    ...(name ? { name } : {}),
+    ...(title ? { title } : {}),
+    ...(description ? { description } : {}),
+    ...(examples ? { examples } : {}),
+    ...(_default ? { default: _default } : {}),
+    ...(see ? { see } : {}),
+    ...(comment ? { comment } : {}),
+  };
+}
+
+/**
+ * Converts JSDoc comments to strings
+ */
+export function decorateNode(node: ts.Node): Annotations {
+  const { jsDoc } = node as unknown as JSDocContainer;
+  const titleAnnotation = extractTitle(node);
+
+  if (jsDoc && jsDoc.length) {
+    const first = jsDoc[0];
+    return mergeAnnotations([
+      extractDescription(stringifyDoc(first.comment)),
+      titleAnnotation,
+      extractTags(first.tags ?? []),
+    ]);
+  }
+
+  return titleAnnotation;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './annotations';
+export * from './ts-helpers';
+export * from './type-checks';
+export * from './validation-helpers';
+export * from './test-helpers';

package/src/test-helpers.ts

@@ -0,0 +1,72 @@
+import * as ts from 'typescript';
+
+export interface SetupReturnType {
+  /**
+   * Virtual source file containing the passed in text
+   */
+  sf: ts.SourceFile;
+  /**
+   * Type checker for the virtual program
+   */
+  tc: ts.TypeChecker;
+}
+
+/**
+ * Setups a virtual TS environment for tests
+ */
+export function setupTestEnv(sourceCode: string, mockFileName = 'filename.ts') {
+  const sourceFile = ts.createSourceFile(
+    mockFileName,
+    sourceCode,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */ true
+  );
+
+  const outputs = [];
+
+  const compilerHost = {
+    getSourceFile(filename: any) {
+      if (filename === mockFileName) {
+        return sourceFile;
+      }
+
+      return undefined;
+    },
+    writeFile(name: any, text: any, writeByteOrderMark: any) {
+      outputs.push({ name, text, writeByteOrderMark });
+    },
+    getDefaultLibFileName() {
+      return 'lib.d.ts';
+    },
+    useCaseSensitiveFileNames() {
+      return false;
+    },
+    getCanonicalFileName(filename: any) {
+      return filename;
+    },
+    getCurrentDirectory() {
+      return '';
+    },
+    getNewLine() {
+      return '\n';
+    },
+    fileExists(fileName: string) {
+      if (fileName === mockFileName) {
+        return true;
+      }
+
+      return false;
+    },
+    readFile(fileName: string) {
+      if (fileName === mockFileName) {
+        return sourceCode;
+      }
+
+      return undefined;
+    },
+  };
+
+  const program = ts.createProgram([mockFileName], {}, compilerHost);
+
+  return { sf: sourceFile, tc: program.getTypeChecker() };
+}

package/src/ts-helpers.ts

@@ -0,0 +1,356 @@
+/* eslint-disable no-bitwise */
+import * as ts from 'typescript';
+import type {
+  NamedType,
+  NodeType,
+  ObjectProperty,
+  ObjectType,
+} from '@player-tools/xlr';
+import { resolveConditional } from './validation-helpers';
+import { isGenericNodeType } from './type-checks';
+
+/**
+ * Returns the required type or the optionally required type
+ */
+export function tsStripOptionalType(node: ts.TypeNode): ts.TypeNode {
+  return ts.isOptionalTypeNode(node) ? node.type : node;
+}
+
+/**
+ * Returns if the top level declaration is exported
+ */
+export function isExportedDeclaration(node: ts.Statement) {
+  return !!node.modifiers?.some(
+    (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword
+  );
+}
+
+/**
+ * Returns if the node is exported from the source file
+ */
+export function isNodeExported(node: ts.Node): boolean {
+  return (
+    (ts.getCombinedModifierFlags(node as ts.Declaration) &
+      ts.ModifierFlags.Export) !==
+      0 ||
+    (!!node.parent && node.parent.kind === ts.SyntaxKind.SourceFile)
+  );
+}
+
+/**
+ * Returns the actual type and will following import chains if needed
+ */
+export function getReferencedType(
+  node: ts.TypeReferenceNode,
+  typeChecker: ts.TypeChecker
+) {
+  let symbol = typeChecker.getSymbolAtLocation(node.typeName);
+
+  if (
+    symbol &&
+    (symbol.flags & ts.SymbolFlags.Alias) === ts.SymbolFlags.Alias
+  ) {
+    // follow alias if it is a symbol
+    symbol = typeChecker.getAliasedSymbol(symbol);
+  }
+
+  const varDecl = symbol?.declarations?.[0];
+  if (
+    varDecl &&
+    (ts.isInterfaceDeclaration(varDecl) || ts.isTypeAliasDeclaration(varDecl))
+  ) {
+    return { declaration: varDecl, exported: isNodeExported(varDecl) };
+  }
+}
+
+/**
+ * Returns list of string literals from potential union of strings
+ */
+export function getStringLiteralsFromUnion(node: ts.Node): Set<string> {
+  if (ts.isUnionTypeNode(node)) {
+    return new Set(
+      node.types.map((type) => {
+        if (ts.isLiteralTypeNode(type) && ts.isStringLiteral(type.literal)) {
+          return type.literal.text;
+        }
+
+        return '';
+      })
+    );
+  }
+
+  if (ts.isLiteralTypeNode(node) && ts.isStringLiteral(node.literal)) {
+    return new Set([node.literal.text]);
+  }
+
+  return new Set();
+}
+
+/**
+ * Converts a format string into a regex that can be used to validate a given string matches the template
+ */
+export function buildTemplateRegex(
+  node: ts.TemplateLiteralTypeNode,
+  typeChecker: ts.TypeChecker
+): string {
+  let regex = node.head.text;
+  node.templateSpans.forEach((span) => {
+    // process template tag
+    let type = span.type.kind;
+    if (ts.isTypeReferenceNode(span.type)) {
+      let symbol = typeChecker.getSymbolAtLocation(
+        span.type.typeName
+      ) as ts.Symbol;
+
+      if (
+        symbol &&
+        (symbol.flags & ts.SymbolFlags.Alias) === ts.SymbolFlags.Alias
+      ) {
+        // follow alias if it is a symbol
+        symbol = typeChecker.getAliasedSymbol(symbol);
+      }
+
+      type = (symbol?.declarations?.[0] as ts.TypeAliasDeclaration).type.kind;
+    }
+
+    if (type === ts.SyntaxKind.StringKeyword) {
+      regex += '.*';
+    } else if (type === ts.SyntaxKind.NumberKeyword) {
+      regex += '[0-9]*';
+    } else if (type === ts.SyntaxKind.BooleanKeyword) {
+      regex += 'true|false';
+    }
+
+    // add non-tag element
+    regex += span.literal.text;
+  });
+  return regex;
+}
+
+/**
+ * Walks generics to fill in values from a combination of the default, constraint, and passed in map values
+ */
+export function fillInGenerics(
+  xlrNode: NodeType,
+  generics?: Map<string, NodeType>
+): NodeType {
+  // Need to make sure not to set generics in passed in map to avoid using generics outside of tree
+  let localGenerics: Map<string, NodeType>;
+
+  if (generics) {
+    localGenerics = new Map(generics);
+  } else {
+    localGenerics = new Map();
+    if (isGenericNodeType(xlrNode)) {
+      xlrNode.genericTokens?.forEach((token) => {
+        localGenerics.set(
+          token.symbol,
+          (token.default ?? token.constraints) as NodeType
+        );
+      });
+    }
+  }
+
+  if (xlrNode.type === 'ref') {
+    if (localGenerics.has(xlrNode.ref)) {
+      return {
+        ...(localGenerics.get(xlrNode.ref) as NodeType),
+        ...(xlrNode.genericArguments
+          ? {
+              genericArguments: xlrNode.genericArguments.map((ga) =>
+                fillInGenerics(ga, localGenerics)
+              ),
+            }
+          : {}),
+        ...(xlrNode.title ? { title: xlrNode.title } : {}),
+        ...(xlrNode.name ? { name: xlrNode.name } : {}),
+        ...(xlrNode.description ? { description: xlrNode.description } : {}),
+        ...(xlrNode.comment ? { comment: xlrNode.comment } : {}),
+      };
+    }
+
+    return {
+      ...xlrNode,
+      ...(xlrNode.genericArguments
+        ? {
+            genericArguments: xlrNode.genericArguments.map((ga) =>
+              fillInGenerics(ga, localGenerics)
+            ),
+          }
+        : {}),
+    };
+  }
+
+  if (xlrNode.type === 'object') {
+    const newProperties: { [name: string]: ObjectProperty } = {};
+    Object.getOwnPropertyNames(xlrNode.properties).forEach((propName) => {
+      const prop = xlrNode.properties[propName];
+      newProperties[propName] = {
+        required: prop.required,
+        node: fillInGenerics(prop.node, localGenerics),
+      };
+    });
+
+    return {
+      ...xlrNode,
+      properties: newProperties,
+    };
+  }
+
+  if (xlrNode.type === 'array') {
+    // eslint-disable-next-line no-param-reassign
+    xlrNode.elementType = fillInGenerics(xlrNode.elementType, localGenerics);
+  } else if (xlrNode.type === 'or' || xlrNode.type === 'and') {
+    let pointer;
+    if (xlrNode.type === 'or') {
+      pointer = xlrNode.or;
+    } else {
+      pointer = xlrNode.and;
+    }
+
+    return {
+      ...xlrNode,
+      [xlrNode.type]: pointer.map((prop) => {
+        return fillInGenerics(prop, localGenerics);
+      }),
+    };
+  } else if (xlrNode.type === 'record') {
+    return {
+      ...xlrNode,
+      keyType: fillInGenerics(xlrNode.keyType, localGenerics),
+      valueType: fillInGenerics(xlrNode.valueType, localGenerics),
+    };
+  } else if (xlrNode.type === 'conditional') {
+    const filledInConditional = {
+      ...xlrNode,
+      check: {
+        left: fillInGenerics(xlrNode.check.left, localGenerics),
+        right: fillInGenerics(xlrNode.check.right, localGenerics),
+      },
+      value: {
+        true: fillInGenerics(xlrNode.value.true, localGenerics),
+        false: fillInGenerics(xlrNode.value.false, localGenerics),
+      },
+    };
+
+    // Check to see if we have enough information to resolve this conditional
+    if (
+      filledInConditional.check.left.type !== 'ref' &&
+      filledInConditional.check.right.type !== 'ref'
+    ) {
+      return {
+        name: xlrNode.name,
+        title: xlrNode.title,
+        ...resolveConditional(filledInConditional),
+      } as NamedType;
+    }
+
+    return filledInConditional;
+  }
+
+  return xlrNode;
+}
+
+/** Applies the TS `Pick` type to an interface/union/intersection */
+export function applyPickOrOmitToNodeType(
+  baseObject: NodeType,
+  operation: 'Pick' | 'Omit',
+  properties: Set<string>
+): NodeType | undefined {
+  if (baseObject.type === 'object') {
+    const newObject = { ...baseObject };
+    Object.keys(baseObject.properties).forEach((key) => {
+      if (
+        (operation === 'Omit' && properties.has(key)) ||
+        (operation === 'Pick' && !properties.has(key))
+      ) {
+        delete newObject.properties[key];
+      }
+    });
+
+    /**
+     * Filter out objects in cases:
+     * - A Pick operation and there are no properties left
+     * - An Omit operation and there are no properties left and no additional properties allowed
+     */
+    if (
+      Object.keys(newObject.properties).length === 0 &&
+      (operation !== 'Omit' || newObject.additionalProperties === false)
+    ) {
+      return undefined;
+    }
+
+    return newObject;
+  }
+
+  let pointer;
+  if (baseObject.type === 'and') {
+    pointer = baseObject.and;
+  } else if (baseObject.type === 'or') {
+    pointer = baseObject.or;
+  } else {
+    throw new Error(
+      `Error: Can not apply ${operation} to type ${baseObject.type}`
+    );
+  }
+
+  const pickedTypes = pointer
+    .map((type) => {
+      const node = applyPickOrOmitToNodeType(type, operation, properties);
+      if (node === undefined) {
+        return undefined;
+      }
+
+      return { ...node, additionalProperties: false } as ObjectType;
+    })
+    .filter((type) => type !== undefined) as NodeType[];
+
+  if (pickedTypes.length === 0) {
+    return undefined;
+  }
+
+  if (pickedTypes.length === 1) {
+    return pickedTypes[0];
+  }
+
+  if (baseObject.type === 'and') {
+    return { ...baseObject, and: pickedTypes };
+  }
+
+  return { ...baseObject, or: pickedTypes };
+}
+
+/** Applies the TS `Omit` type to an interface/union/intersection */
+export function applyPartialOrRequiredToNodeType(
+  baseObject: NodeType,
+  modifier: boolean
+): NodeType {
+  if (baseObject.type === 'object') {
+    const newObject = { ...baseObject };
+    Object.keys(baseObject.properties).forEach((key) => {
+      newObject.properties[key].required = modifier;
+    });
+
+    return newObject;
+  }
+
+  if (baseObject.type === 'and') {
+    const pickedTypes = baseObject.and.map((type) =>
+      applyPartialOrRequiredToNodeType(type, modifier)
+    );
+    return { ...baseObject, and: pickedTypes };
+  }
+
+  if (baseObject.type === 'or') {
+    const pickedTypes = baseObject.or.map((type) =>
+      applyPartialOrRequiredToNodeType(type, modifier)
+    );
+    return { ...baseObject, or: pickedTypes };
+  }
+
+  throw new Error(
+    `Error: Can not apply ${modifier ? 'Required' : 'Partial'} to type ${
+      baseObject.type
+    }`
+  );
+}