@xlr-lib/xlr-utils 0.1.1-next.4 → 0.1.1-next.6

package/src/annotations.ts

@@ -1,237 +0,0 @@
-import ts from "typescript";
-import type { Annotations } from "@xlr-lib/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 meta: Record<string, 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 if (tag.tagName.text === "meta") {
-      const [key, value] = tag.comment.toString().split(/:(.*)/);
-      meta[key] = value?.trim() ?? "";
-    } 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 }),
-    ...(meta && Object.keys(meta).length === 0 ? {} : { meta }),
-  };
-}
-
-/**
- * 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)),
-  );
-  const meta = nodes.find((n) => n.meta)?.meta;
-  return {
-    ...(name ? { name } : {}),
-    ...(title ? { title } : {}),
-    ...(description ? { description } : {}),
-    ...(examples ? { examples } : {}),
-    ...(_default ? { default: _default } : {}),
-    ...(see ? { see } : {}),
-    ...(comment ? { comment } : {}),
-    ...(meta ? { meta } : {}),
-  };
-}
-
-/**
- * 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/documentation.ts

@@ -1,243 +0,0 @@
-import ts from "typescript";
-import type { SymbolDisplayPart } from "typescript";
-import type { NodeType } from "@xlr-lib/xlr";
-import { isPrimitiveTypeNode } from "./type-checks";
-
-const { SymbolDisplayPartKind, displayPartsToString } = ts;
-
-/** 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/types/annotations.d.ts

@@ -1,7 +0,0 @@
-import ts from "typescript";
-import type { Annotations } from "@xlr-lib/xlr";
-/**
- * Converts JSDoc comments to strings
- */
-export declare function decorateNode(node: ts.Node): Annotations;
-//# sourceMappingURL=annotations.d.ts.map

package/types/documentation.d.ts

@@ -1,14 +0,0 @@
-import type { SymbolDisplayPart } from "typescript";
-import type { NodeType } from "@xlr-lib/xlr";
-/**
- * Generate a documentation string for a given node
- *
- * @param node - The source node to author the docs string for
- * @returns - documentation string
- */
-export declare function createTSDocString(node: NodeType): Array<SymbolDisplayPart>;
-/** Convert the TS SymbolDisplayParts into a single string */
-export declare function symbolDisplayToString(displayParts: Array<SymbolDisplayPart>): string;
-/** Create a documentation string from node */
-export declare function createDocString(node: NodeType): string;
-//# sourceMappingURL=documentation.d.ts.map

package/types/ts-helpers.d.ts

@@ -1,54 +0,0 @@
-import ts from "typescript";
-import type { NodeType, OrType } from "@xlr-lib/xlr";
-/**
- * Returns the required type or the optionally required type
- */
-export declare function tsStripOptionalType(node: ts.TypeNode): ts.TypeNode;
-/**
- * Returns if the top level declaration is exported
- */
-export declare function isExportedDeclaration(node: ts.Statement): boolean;
-/**
- * Returns if the top level declaration is exported
- */
-export declare function isExportedModuleDeclaration(node: ts.Statement): node is ts.ModuleDeclaration;
-/**
- * Returns if the node is exported from the source file
- */
-export declare function isNodeExported(node: ts.Node): boolean;
-/**
- * Returns the actual type and will following import chains if needed
- */
-export declare function getReferencedType(node: ts.TypeReferenceNode, typeChecker: ts.TypeChecker): {
-    declaration: ts.InterfaceDeclaration | ts.TypeAliasDeclaration;
-    exported: boolean;
-} | undefined;
-/**
- * Checks if a type reference points to a TypeScript built-in type
- * by examining whether its declaration comes from TypeScript's lib files.
- *
- * This is more robust than maintaining a hardcoded list of built-in types
- * as it automatically handles all TypeScript lib types (Map, Set, WeakMap,
- * Promise, Array, Date, Error, RegExp, etc.).
- */
-export declare function isTypeScriptLibType(node: ts.TypeReferenceNode, typeChecker: ts.TypeChecker): boolean;
-/**
- * Returns list of string literals from potential union of strings
- */
-export declare function getStringLiteralsFromUnion(node: ts.Node): Set<string>;
-/**
- * Converts a format string into a regex that can be used to validate a given string matches the template
- */
-export declare function buildTemplateRegex(node: ts.TemplateLiteralTypeNode, typeChecker: ts.TypeChecker): string;
-/**
- * Walks generics to fill in values from a combination of the default, constraint, and passed in map values
- * TODO convert this to use simpleTransformGenerator
- */
-export declare function fillInGenerics(xlrNode: NodeType, generics?: Map<string, NodeType>, preferLocalGenerics?: boolean): NodeType;
-/** Applies the TS `Pick` or `Omit` type to an interface/union/intersection */
-export declare function applyPickOrOmitToNodeType(baseObject: NodeType, operation: "Pick" | "Omit", properties: Set<string>): NodeType | undefined;
-/** Applies the TS `Partial` or `Required` type to an interface/union/intersection */
-export declare function applyPartialOrRequiredToNodeType(baseObject: NodeType, modifier: boolean): NodeType;
-/** Applies the TS `Exclude` type to a union */
-export declare function applyExcludeToNodeType(baseObject: OrType, filters: NodeType | OrType): NodeType;
-//# sourceMappingURL=ts-helpers.d.ts.map