@xlr-lib/xlr-utils 0.1.1-next.0

package/src/__tests__/validation-helpers.test.ts

@@ -0,0 +1,141 @@
+import { test, expect, describe } from "vitest";
+import type { ObjectType } from "@xlr-lib/xlr";
+import { computeEffectiveObject, makePropertyMap } from "../validation-helpers";
+import { parseTree } from "jsonc-parser";
+
+describe("computeEffectiveObject tests", () => {
+  test("mixed test", () => {
+    const type1: ObjectType = {
+      type: "object",
+      properties: {
+        foo: {
+          required: true,
+          node: {
+            type: "string",
+          },
+        },
+      },
+      additionalProperties: false,
+    };
+
+    const type2: ObjectType = {
+      type: "object",
+      properties: {
+        bar: {
+          required: true,
+          node: {
+            type: "number",
+          },
+        },
+      },
+      additionalProperties: {
+        type: "unknown",
+      },
+    };
+
+    expect(computeEffectiveObject(type1, type2)).toMatchSnapshot();
+  });
+
+  test("Error on property overlap", () => {
+    const type1: ObjectType = {
+      type: "object",
+      properties: {
+        foo: {
+          required: true,
+          node: {
+            type: "string",
+          },
+        },
+      },
+      additionalProperties: false,
+    };
+
+    const type2: ObjectType = {
+      type: "object",
+      properties: {
+        foo: {
+          required: true,
+          node: {
+            type: "number",
+          },
+        },
+      },
+      additionalProperties: {
+        type: "unknown",
+      },
+    };
+
+    expect(() =>
+      computeEffectiveObject(type1, type2, true),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Error: Can't compute effective type for object literal and object literal because of conflicting properties foo]`,
+    );
+  });
+
+  test("Merges equal additionalProperties", () => {
+    const type1: ObjectType = {
+      type: "object",
+      properties: {
+        foo: {
+          required: true,
+          node: {
+            type: "string",
+          },
+        },
+      },
+      additionalProperties: {
+        type: "unknown",
+      },
+    };
+
+    const type2: ObjectType = {
+      type: "object",
+      properties: {
+        bar: {
+          required: true,
+          node: {
+            type: "number",
+          },
+        },
+      },
+      additionalProperties: {
+        type: "unknown",
+      },
+    };
+
+    expect(computeEffectiveObject(type1, type2)).toMatchSnapshot();
+  });
+});
+
+describe("makePropertyMap tests", () => {
+  test("basic test", () => {
+    const jsonObject = {
+      key1: "value",
+      key2: true,
+      key3: 1,
+    };
+
+    const treeObject = parseTree(JSON.stringify(jsonObject));
+
+    const propertyMap = makePropertyMap(treeObject);
+
+    expect(propertyMap.get("key1")?.value).toStrictEqual("value");
+    expect(propertyMap.get("key2")?.value).toStrictEqual(true);
+    expect(propertyMap.get("key3")?.value).toStrictEqual(1);
+  });
+
+  test("escaped key", () => {
+    const jsonObject = {
+      "some-key": "value",
+      // eslint-disable-next-line prettier/prettier
+      'some-otherkey': "value",
+    };
+
+    const treeObject = parseTree(JSON.stringify(jsonObject));
+
+    const propertyMap = makePropertyMap(treeObject);
+
+    expect(propertyMap.get("'some-key'")?.value).toStrictEqual("value");
+    expect(propertyMap.get("'some-otherkey'")?.value).toStrictEqual("value");
+  });
+});

package/src/annotations.ts

@@ -0,0 +1,237 @@
+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

@@ -0,0 +1,243 @@
+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/src/index.ts

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