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

package/src/{ts-helpers.ts → xlr-helpers.ts}

@@ -1,4 +1,3 @@
-import ts from "typescript";
 import type {
   NamedType,
   NodeType,
@@ -10,167 +9,6 @@ import type {
 import { computeExtends, resolveConditional } from "./validation-helpers";
 import { isGenericNamedType, 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): boolean {
-  const modifiers = ts.canHaveModifiers(node)
-    ? ts.getModifiers(node)
-    : undefined;
-
-  if (modifiers) {
-    return modifiers.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
-  }
-  return false;
-}
-
-/**
- * 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) };
-  }
-}
-
-/**
- * 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 function isTypeScriptLibType(
-  node: ts.TypeReferenceNode,
-  typeChecker: ts.TypeChecker,
-): boolean {
-  let symbol = typeChecker.getSymbolAtLocation(node.typeName);
-
-  if (!symbol) return false;
-
-  // Follow alias if it is a symbol
-  if ((symbol.flags & ts.SymbolFlags.Alias) === ts.SymbolFlags.Alias) {
-    symbol = typeChecker.getAliasedSymbol(symbol);
-  }
-
-  const declarations = symbol.getDeclarations();
-  if (!declarations || declarations.length === 0) return false;
-
-  // Check if any declaration comes from TypeScript lib files
-  return declarations.some((decl) => {
-    const sourceFile = decl.getSourceFile();
-    if (!sourceFile) return false;
-
-    const filePath = sourceFile.fileName;
-    return (
-      filePath.includes("/typescript/lib/") ||
-      filePath.includes("\\typescript\\lib\\") ||
-      (filePath.endsWith(".d.ts") && filePath.includes("lib."))
-    );
-  });
-}
-
-/**
- * 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
  * TODO convert this to use simpleTransformGenerator
@@ -178,12 +16,22 @@ export function buildTemplateRegex(
 export function fillInGenerics(
   xlrNode: NodeType,
   generics?: Map<string, NodeType>,
+  preferLocalGenerics = false,
 ): 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);
+    if (preferLocalGenerics && isGenericNodeType(xlrNode)) {
+      xlrNode.genericTokens?.forEach((token) => {
+        const genericValue = (token.default ?? token.constraints) as NodeType;
+        localGenerics.set(
+          token.symbol,
+          fillInGenerics(genericValue, localGenerics, preferLocalGenerics),
+        );
+      });
+    }
   } else {
     localGenerics = new Map();
     if (isGenericNodeType(xlrNode)) {
@@ -191,7 +39,7 @@ export function fillInGenerics(
         const genericValue = (token.default ?? token.constraints) as NodeType;
         localGenerics.set(
           token.symbol,
-          fillInGenerics(genericValue, localGenerics),
+          fillInGenerics(genericValue, localGenerics, preferLocalGenerics),
         );
       });
     }
@@ -204,7 +52,7 @@ export function fillInGenerics(
         ...(xlrNode.genericArguments
           ? {
               genericArguments: xlrNode.genericArguments.map((ga) =>
-                fillInGenerics(ga, localGenerics),
+                fillInGenerics(ga, localGenerics, preferLocalGenerics),
               ),
             }
           : {}),
@@ -220,7 +68,7 @@ export function fillInGenerics(
       ...(xlrNode.genericArguments
         ? {
             genericArguments: xlrNode.genericArguments.map((ga) =>
-              fillInGenerics(ga, localGenerics),
+              fillInGenerics(ga, localGenerics, preferLocalGenerics),
             ),
           }
         : {}),
@@ -233,7 +81,7 @@ export function fillInGenerics(
       const prop = xlrNode.properties[propName];
       newProperties[propName] = {
         required: prop.required,
-        node: fillInGenerics(prop.node, localGenerics),
+        node: fillInGenerics(prop.node, localGenerics, preferLocalGenerics),
       };
     });
 
@@ -246,20 +94,36 @@ export function fillInGenerics(
               return {
                 ...token,
                 constraints: token.constraints
-                  ? fillInGenerics(token.constraints, localGenerics)
+                  ? fillInGenerics(
+                      token.constraints,
+                      localGenerics,
+                      preferLocalGenerics,
+                    )
                   : undefined,
                 default: token.default
-                  ? fillInGenerics(token.default, localGenerics)
+                  ? fillInGenerics(
+                      token.default,
+                      localGenerics,
+                      preferLocalGenerics,
+                    )
                   : undefined,
               };
             }),
           }
         : {}),
       extends: xlrNode.extends
-        ? (fillInGenerics(xlrNode.extends, localGenerics) as RefNode)
+        ? (fillInGenerics(
+            xlrNode.extends,
+            localGenerics,
+            preferLocalGenerics,
+          ) as RefNode)
         : undefined,
       additionalProperties: xlrNode.additionalProperties
-        ? fillInGenerics(xlrNode.additionalProperties, localGenerics)
+        ? fillInGenerics(
+            xlrNode.additionalProperties,
+            localGenerics,
+            preferLocalGenerics,
+          )
         : false,
     };
   }
@@ -267,7 +131,11 @@ export function fillInGenerics(
   if (xlrNode.type === "array") {
     return {
       ...xlrNode,
-      elementType: fillInGenerics(xlrNode.elementType, localGenerics),
+      elementType: fillInGenerics(
+        xlrNode.elementType,
+        localGenerics,
+        preferLocalGenerics,
+      ),
     };
   } else if (xlrNode.type === "or" || xlrNode.type === "and") {
     let pointer;
@@ -280,25 +148,49 @@ export function fillInGenerics(
     return {
       ...xlrNode,
       [xlrNode.type]: pointer.map((prop) => {
-        return fillInGenerics(prop, localGenerics);
+        return fillInGenerics(prop, localGenerics, preferLocalGenerics);
       }),
     };
   } else if (xlrNode.type === "record") {
     return {
       ...xlrNode,
-      keyType: fillInGenerics(xlrNode.keyType, localGenerics),
-      valueType: fillInGenerics(xlrNode.valueType, localGenerics),
+      keyType: fillInGenerics(
+        xlrNode.keyType,
+        localGenerics,
+        preferLocalGenerics,
+      ),
+      valueType: fillInGenerics(
+        xlrNode.valueType,
+        localGenerics,
+        preferLocalGenerics,
+      ),
     };
   } else if (xlrNode.type === "conditional") {
     const filledInConditional = {
       ...xlrNode,
       check: {
-        left: fillInGenerics(xlrNode.check.left, localGenerics),
-        right: fillInGenerics(xlrNode.check.right, localGenerics),
+        left: fillInGenerics(
+          xlrNode.check.left,
+          localGenerics,
+          preferLocalGenerics,
+        ),
+        right: fillInGenerics(
+          xlrNode.check.right,
+          localGenerics,
+          preferLocalGenerics,
+        ),
       },
       value: {
-        true: fillInGenerics(xlrNode.value.true, localGenerics),
-        false: fillInGenerics(xlrNode.value.false, localGenerics),
+        true: fillInGenerics(
+          xlrNode.value.true,
+          localGenerics,
+          preferLocalGenerics,
+        ),
+        false: fillInGenerics(
+          xlrNode.value.false,
+          localGenerics,
+          preferLocalGenerics,
+        ),
       },
     };
 

package/types/index.d.ts

@@ -1,6 +1,4 @@
-export * from "./annotations";
-export * from "./ts-helpers";
+export * from "./xlr-helpers";
 export * from "./type-checks";
 export * from "./validation-helpers";
-export * from "./documentation";
 //# sourceMappingURL=index.d.ts.map

package/types/type-checks.d.ts

@@ -1,31 +1,4 @@
-import ts from "typescript";
 import type { NamedType, NamedTypeWithGenerics, NodeType, NodeTypeWithGenerics, PrimitiveTypes, StringType, NumberType, BooleanType, ObjectType, ArrayType, RefType, OrType, AndType, RecordType } from "@xlr-lib/xlr";
-/**
- * Returns if the Object Property is optional
- */
-export declare function isOptionalProperty(node: ts.PropertySignature): boolean;
-/**
- * Returns if the node is an Interface or Type with Generics
- */
-export declare function isGenericInterfaceDeclaration(node: ts.InterfaceDeclaration): boolean;
-/**
- * Returns if the node is an Type Declaration with Generics
- */
-export declare function isGenericTypeDeclaration(node: ts.TypeAliasDeclaration): boolean;
-/**
- * Returns if the referenced type is a generic
- */
-export declare function isTypeReferenceGeneric(node: ts.TypeReferenceNode, typeChecker: ts.TypeChecker): boolean;
-export type TopLevelDeclaration = ts.InterfaceDeclaration | ts.TypeAliasDeclaration;
-/**
- * Returns if the node is an interface or a type declaration
- */
-export declare function isTopLevelDeclaration(node: ts.Node): node is TopLevelDeclaration;
-export type TopLevelNode = TopLevelDeclaration | ts.VariableStatement;
-/**
- * Returns if the node is an interface or a type declaration
- */
-export declare function isTopLevelNode(node: ts.Node): node is TopLevelNode;
 /**
  * Returns if the NodeType has generic tokens
  */

package/types/xlr-helpers.d.ts

@@ -0,0 +1,13 @@
+import type { NodeType, OrType } from "@xlr-lib/xlr";
+/**
+ * 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=xlr-helpers.d.ts.map

package/src/__tests__/annotations.test.ts

@@ -1,40 +0,0 @@
-import { test, expect, describe } from "vitest";
-import { setupTestEnv } from "@xlr-lib/test-utils";
-import { decorateNode } from "../annotations";
-
-describe("Annotations", () => {
-  test("JSDoc comments to strings", () => {
-    const sc = `
-    /**
-   * An asset is the smallest unit of user interaction in a player view
-   * @example Example usage of interface Asset
-   * @see Asset for implementation details
-   * @default default value
-   */
-  export interface Asset<T extends string = string> {
-    id: string;
-    [key: string]: unknown;
-  }
-  `;
-
-    const { sf } = setupTestEnv(sc);
-    expect(decorateNode(sf.statements[0])).toMatchSnapshot();
-  });
-
-  test("JSDoc @meta", () => {
-    const sc = `
-    /**
-   * An asset is the smallest unit of user interaction in a player view
-   * @meta category:views
-   * @meta screenshot:/path/image.png
-   */
-  export interface Asset<T extends string = string> {
-    id: string;
-    [key: string]: unknown;
-  }
-  `;
-
-    const { sf } = setupTestEnv(sc);
-    expect(decorateNode(sf.statements[0])).toMatchSnapshot();
-  });
-});

package/src/__tests__/documentation.test.ts

@@ -1,116 +0,0 @@
-import { test, expect, describe } from "vitest";
-import type { FunctionType, OrType, TupleType } from "@xlr-lib/xlr";
-import { createDocString } from "../documentation";
-
-describe("docs", () => {
-  test("or", () => {
-    const type1: OrType = {
-      type: "or",
-      or: [
-        {
-          type: "string",
-        },
-        {
-          type: "array",
-          elementType: {
-            type: "string",
-          },
-        },
-      ],
-    };
-
-    expect(createDocString(type1)).toMatchInlineSnapshot(
-      `"string | Array<string>"`,
-    );
-  });
-
-  test("function", () => {
-    const type1: FunctionType = {
-      type: "function",
-      name: "testABC",
-      parameters: [
-        {
-          name: "a",
-          type: {
-            type: "string",
-          },
-        },
-        {
-          name: "b",
-          type: {
-            type: "array",
-            elementType: {
-              type: "string",
-            },
-          },
-        },
-      ],
-      returnType: {
-        type: "string",
-      },
-    };
-
-    expect(createDocString(type1)).toMatchInlineSnapshot(
-      `"function testABC(a: string, b: Array<string>): string"`,
-    );
-  });
-
-  test("tuple", () => {
-    const type1: TupleType = {
-      type: "tuple",
-      name: "testABC",
-      elementTypes: [
-        {
-          name: "a",
-          type: {
-            type: "string",
-          },
-        },
-        {
-          type: {
-            type: "array",
-            elementType: {
-              type: "string",
-            },
-          },
-        },
-      ],
-      minItems: 2,
-      additionalItems: false,
-    };
-
-    expect(createDocString(type1)).toMatchInlineSnapshot(
-      `"[a: string, Array<string>]"`,
-    );
-  });
-
-  test("const", () => {
-    const type1: OrType = {
-      type: "or",
-      or: [
-        {
-          type: "string",
-          const: "abc",
-        },
-        {
-          type: "number",
-          const: 123,
-        },
-        {
-          type: "boolean",
-          const: true,
-        },
-        {
-          type: "array",
-          elementType: {
-            type: "string",
-          },
-        },
-      ],
-    };
-
-    expect(createDocString(type1)).toMatchInlineSnapshot(
-      `""abc" | 123 | true | Array<string>"`,
-    );
-  });
-});