@xlr-lib/xlr-utils 0.2.0--canary.2.120 → 1.0.0

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

@@ -1,180 +0,0 @@
-import { test, expect, describe } from "vitest";
-import * as ts from "typescript";
-import { NodeType } from "@xlr-lib/xlr";
-
-import {
-  tsStripOptionalType,
-  isExportedDeclaration,
-  applyPickOrOmitToNodeType,
-  getStringLiteralsFromUnion,
-  applyPartialOrRequiredToNodeType,
-} from "../ts-helpers";
-
-test("tsStripOptionalType", () => {
-  const input: ts.TypeNode = ts.factory.createKeywordTypeNode(
-    ts.SyntaxKind.StringKeyword,
-  );
-  const expected: ts.TypeNode = ts.factory.createKeywordTypeNode(
-    ts.SyntaxKind.StringKeyword,
-  );
-  const actual = tsStripOptionalType(input);
-  expect(actual).toEqual(expected);
-});
-
-describe("isExportedDeclaration", () => {
-  test("should return false for a non exported Statement", () => {
-    const source = ts.createSourceFile(
-      "test.ts",
-      `
-        interface Test {
-          prop?: string;
-        }
-      `,
-      ts.ScriptTarget.Latest,
-      true,
-    );
-    const node = source.statements[0] as ts.Statement;
-
-    const result = isExportedDeclaration(node);
-    expect(result).toBe(false);
-  });
-
-  test("should return true for an exported Statement", () => {
-    const source = ts.createSourceFile(
-      "test.ts",
-      `
-          export interface Test {
-            prop?: string;
-          }
-        `,
-      ts.ScriptTarget.Latest,
-      true,
-    );
-    const node = source.statements[0] as ts.Statement;
-
-    const result = isExportedDeclaration(node);
-    expect(result).toBe(true);
-  });
-});
-
-test("getStringLiteralsFromUnion", () => {
-  const input: ts.Node = ts.factory.createUnionTypeNode([
-    ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral("foo")),
-    ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral("bar")),
-  ]);
-  const expected: Set<string> = new Set(["foo", "bar"]);
-  const actual = getStringLiteralsFromUnion(input);
-  expect(actual).toEqual(expected);
-});
-
-describe("applyPickOrOmitToNodeType", () => {
-  test("Omit - Doesn't filter property that doesn't exist", () => {
-    const baseObject: NodeType = {
-      type: "object",
-      properties: { foo: { node: { type: "string" }, required: false } },
-      additionalProperties: false,
-    };
-    const operation = "Omit";
-    const properties = new Set(["bar"]);
-
-    const result = applyPickOrOmitToNodeType(baseObject, operation, properties);
-
-    expect(result).toStrictEqual(baseObject);
-  });
-
-  test("Omit - Filters property that do exist", () => {
-    const baseObject: NodeType = {
-      type: "object",
-      properties: {
-        foo: { node: { type: "string" }, required: false },
-        bar: { node: { type: "string" }, required: false },
-      },
-      additionalProperties: false,
-    };
-
-    const filteredObject: NodeType = {
-      type: "object",
-      properties: { foo: { node: { type: "string" }, required: false } },
-      additionalProperties: false,
-    };
-    const operation = "Omit";
-    const properties = new Set(["bar"]);
-
-    const result = applyPickOrOmitToNodeType(baseObject, operation, properties);
-
-    expect(result).toStrictEqual(filteredObject);
-  });
-
-  test("Pick - Selects property that do exist", () => {
-    const baseObject: NodeType = {
-      type: "object",
-      properties: {
-        foo: { node: { type: "string" }, required: false },
-        bar: { node: { type: "string" }, required: false },
-      },
-      additionalProperties: false,
-    };
-
-    const filteredObject: NodeType = {
-      type: "object",
-      properties: { bar: { node: { type: "string" }, required: false } },
-      additionalProperties: false,
-    };
-    const operation = "Pick";
-    const properties = new Set(["bar"]);
-
-    const result = applyPickOrOmitToNodeType(baseObject, operation, properties);
-
-    expect(result).toStrictEqual(filteredObject);
-  });
-});
-
-describe("applyPartialOrRequiredToNodeType", () => {
-  test("Partial - Makes required properties optional", () => {
-    const baseObject: NodeType = {
-      type: "object",
-      properties: {
-        foo: { node: { type: "string" }, required: false },
-        bar: { node: { type: "string" }, required: true },
-      },
-      additionalProperties: false,
-    };
-
-    const modifiedObject: NodeType = {
-      type: "object",
-      properties: {
-        foo: { node: { type: "string" }, required: false },
-        bar: { node: { type: "string" }, required: false },
-      },
-      additionalProperties: false,
-    };
-
-    const result = applyPartialOrRequiredToNodeType(baseObject, false);
-
-    expect(result).toStrictEqual(modifiedObject);
-  });
-
-  test("Required - Makes optional properties required", () => {
-    const baseObject: NodeType = {
-      type: "object",
-      properties: {
-        foo: { node: { type: "string" }, required: false },
-        bar: { node: { type: "string" }, required: true },
-      },
-      additionalProperties: false,
-    };
-
-    const modifiedObject: NodeType = {
-      type: "object",
-      properties: {
-        foo: { node: { type: "string" }, required: true },
-        bar: { node: { type: "string" }, required: true },
-      },
-      additionalProperties: false,
-    };
-
-    const result = applyPartialOrRequiredToNodeType(baseObject, true);
-
-    expect(result).toStrictEqual(modifiedObject);
-  });
-});

package/src/__tests__/type-check.test.ts

@@ -1,39 +0,0 @@
-import * as ts from "typescript";
-import { isOptionalProperty } from "../type-checks";
-import { describe, test, expect } from "vitest";
-
-describe("isOptionalProperty", () => {
-  test("should return true for an optional property", () => {
-    const source = ts.createSourceFile(
-      "test.ts",
-      `
-      interface Test {
-        prop?: string;
-      }
-    `,
-      ts.ScriptTarget.Latest,
-      true,
-    );
-    const node = source.statements[0] as ts.InterfaceDeclaration;
-    const prop = node.members[0] as ts.PropertySignature;
-
-    expect(isOptionalProperty(prop)).toBe(true);
-  });
-
-  test("should return false for a non-optional property", () => {
-    const source = ts.createSourceFile(
-      "test.ts",
-      `
-      interface Test {
-        prop: string;
-      }
-    `,
-      ts.ScriptTarget.Latest,
-      true,
-    );
-    const node = source.statements[0] as ts.InterfaceDeclaration;
-    const prop = node.members[0] as ts.PropertySignature;
-
-    expect(isOptionalProperty(prop)).toBe(false);
-  });
-});

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