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

package/src/validation-helpers.ts

@@ -0,0 +1,252 @@
+import type { Node } from "jsonc-parser";
+import type {
+  ConditionalType,
+  NodeType,
+  ObjectType,
+  RefNode,
+} from "@xlr-lib/xlr";
+import { isGenericNodeType, isPrimitiveTypeNode } from "./type-checks";
+import { fillInGenerics } from "./ts-helpers";
+
+export interface PropertyNode {
+  /** Equivalent Property Name */
+  key: string;
+
+  /** Equivalent Property Value */
+  value: Node;
+}
+
+/**
+ * Takes a property node and returns the underlying Key/Value Pairs
+ */
+export function propertyToTuple(node: Node): PropertyNode {
+  let key = node.children?.[0].value as string;
+  if (key.includes("-")) {
+    // XLR outputs all escaped properties with single quotes
+    key = `'${key}'`;
+  }
+
+  return {
+    key,
+    value: node.children?.[1] as Node,
+  };
+}
+
+/**
+ * Turns a node's children into a map for easy access
+ */
+export function makePropertyMap(node: Node): Map<string, Node> {
+  const m = new Map();
+  node.children?.forEach((child) => {
+    const property = propertyToTuple(child);
+    m.set(property.key, property.value);
+  });
+  return m;
+}
+
+/**
+ * Checks if property is a leaf node or another node
+ */
+export function isNode(obj: Node | string | number | boolean): obj is Node {
+  return (
+    typeof obj !== "string" ||
+    typeof obj !== "number" ||
+    typeof obj !== "boolean"
+  );
+}
+
+/**
+ * Computes if the first arg extends the second arg
+ */
+export function computeExtends(a: NodeType, b: NodeType): boolean {
+  // special case for any/unknown being functionally the same
+  if (
+    (a.type === "any" || a.type === "unknown") &&
+    (b.type === "any" || b.type === "unknown")
+  ) {
+    return true;
+  }
+
+  // special case for null/undefined being functionally the same
+  if (
+    (a.type === "null" || a.type === "undefined") &&
+    (b.type === "null" || b.type === "undefined")
+  ) {
+    return true;
+  }
+
+  // check simple case of equal types
+  if (a.type === b.type) {
+    if (isPrimitiveTypeNode(a) && isPrimitiveTypeNode(b)) {
+      if (a.const && b.const) {
+        if (a.const === b.const) {
+          return true;
+        }
+      } else {
+        return true;
+      }
+    }
+
+    if (a.type === "ref" && b.type === "ref") {
+      return a.ref === b.ref;
+    }
+
+    if (a.type === "object" && b.type === "object") {
+      for (const property in b.properties) {
+        const propertyNode = b.properties[property];
+        if (
+          !a.properties[property] ||
+          !computeExtends(a.properties[property].node, propertyNode.node)
+        ) {
+          return false;
+        }
+      }
+
+      return true;
+    }
+  }
+
+  if (isPrimitiveTypeNode(a) && b.type === "or") {
+    return b.or.every((member) => computeExtends(a, member));
+  }
+
+  if (isPrimitiveTypeNode(b) && a.type === "or") {
+    return a.or.every((member) => computeExtends(b, member));
+  }
+
+  if (a.type === "or" && b.type === "or") {
+    return a.or.every((x) => b.or.some((y) => computeExtends(x, y)));
+  }
+
+  return false;
+}
+
+/**
+ * Attempts to resolve a conditional type
+ */
+export function resolveConditional(conditional: ConditionalType): NodeType {
+  const { left, right } = conditional.check;
+  const conditionalResult = computeExtends(left, right)
+    ? conditional.value.true
+    : conditional.value.false;
+
+  // Compose first level generics here since `conditionalResult` won't have them
+  if (isGenericNodeType(conditional)) {
+    const genericMap: Map<string, NodeType> = new Map();
+    conditional.genericTokens.forEach((token) => {
+      genericMap.set(
+        token.symbol,
+        token.default ?? token.constraints ?? { type: "any" },
+      );
+    });
+
+    return fillInGenerics(conditionalResult, genericMap);
+  }
+
+  return conditionalResult;
+}
+
+/**
+ * Resolve referenced node with potential generic arguments
+ */
+export function resolveReferenceNode(
+  genericReference: RefNode,
+  typeToFill: NodeType,
+): NodeType {
+  const genericArgs = genericReference.genericArguments;
+  const genericMap: Map<string, NodeType> = new Map();
+
+  // Compose first level generics here from `genericReference`
+  if (genericArgs && isGenericNodeType(typeToFill)) {
+    typeToFill.genericTokens.forEach((token, index) => {
+      genericMap.set(
+        token.symbol,
+        genericArgs[index] ?? token.default ?? token.constraints,
+      );
+    });
+  }
+
+  // Fill in generics
+  const filledInNode = fillInGenerics(typeToFill, genericMap);
+
+  // Remove generic tokens that were resolve
+  if (isGenericNodeType(filledInNode) && genericArgs?.length) {
+    if (genericArgs.length < filledInNode.genericTokens.length) {
+      filledInNode.genericTokens = filledInNode.genericTokens.slice(
+        genericArgs?.length,
+      );
+    } else if (genericArgs.length === filledInNode.genericTokens.length) {
+      filledInNode.genericTokens = [];
+    }
+  }
+
+  // Resolve index access
+  if (genericReference.property && filledInNode.type === "object") {
+    return (
+      filledInNode.properties[genericReference.property]?.node ??
+      filledInNode.additionalProperties ?? { type: "undefined" }
+    );
+  }
+
+  return filledInNode;
+}
+
+/**
+ * Combines two ObjectType objects to get a representation of the effective TypeScript interface of `base` extending `operand`
+ - * @param base The base interface
+ - * @param operand The interface that is extended
+ - * @param errorOnOverlap whether or not conflicting properties should throw an error or use the property from operand
+ - * @returns `ObjectType`
+ */
+export function computeEffectiveObject(
+  base: ObjectType,
+  operand: ObjectType,
+  errorOnOverlap = true,
+): ObjectType {
+  const baseObjectName = base.name ?? base.title ?? "object literal";
+  const operandObjectName = operand.name ?? operand.title ?? "object literal";
+  const newObject = {
+    ...JSON.parse(JSON.stringify(base)),
+    name: `${baseObjectName} & ${operandObjectName}`,
+    description: `Effective type combining ${baseObjectName} and ${operandObjectName}`,
+    genericTokens: [
+      ...(isGenericNodeType(base) ? base.genericTokens : []),
+      ...(isGenericNodeType(operand) ? operand.genericTokens : []),
+    ],
+  };
+  // TODO this check needs to account for primitive -> primitive generic overlap
+
+  for (const property in operand.properties) {
+    if (newObject.properties[property] !== undefined && errorOnOverlap) {
+      if (
+        !computeExtends(
+          newObject.properties[property].node,
+          operand.properties[property].node,
+        )
+      ) {
+        throw new Error(
+          `Can't compute effective type for ${baseObjectName} and ${operandObjectName} because of conflicting properties ${property}`,
+        );
+      }
+    }
+
+    newObject.properties[property] = operand.properties[property];
+  }
+
+  if (newObject.additionalProperties && operand.additionalProperties) {
+    if (
+      !isPrimitiveTypeNode(newObject.additionalProperties) ||
+      !isPrimitiveTypeNode(operand.additionalProperties) ||
+      newObject.additionalProperties.type !== operand.additionalProperties.type
+    ) {
+      newObject.additionalProperties = {
+        type: "and",
+        and: [newObject.additionalProperties, operand.additionalProperties],
+      };
+    }
+  } else if (operand.additionalProperties) {
+    newObject.additionalProperties = operand.additionalProperties;
+  }
+
+  return newObject;
+}

package/types/annotations.d.ts

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

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

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

package/types/ts-helpers.d.ts

@@ -0,0 +1,41 @@
+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 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.TypeAliasDeclaration | ts.InterfaceDeclaration;
+    exported: boolean;
+} | undefined;
+/**
+ * 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>): 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

package/types/type-checks.d.ts

@@ -0,0 +1,45 @@
+import ts from "typescript";
+import type { NamedType, NamedTypeWithGenerics, NodeType, NodeTypeWithGenerics, PrimitiveTypes } 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
+ */
+export declare function isGenericNodeType<T extends NodeType = NodeType>(nt: NodeType): nt is NodeTypeWithGenerics<T>;
+/**
+ * Returns if the named type has generic tokens
+ */
+export declare function isGenericNamedType<T extends NamedType = NamedType>(nt: NodeType): nt is NamedTypeWithGenerics<T>;
+/**
+ * Returns if the node is a `PrimitiveTypes`
+ */
+export declare function isPrimitiveTypeNode(node: NodeType): node is PrimitiveTypes;
+/**
+ * Type Guard for non-null values
+ */
+export declare function isNonNullable<T>(a: T | null | undefined): a is NonNullable<T>;
+//# sourceMappingURL=type-checks.d.ts.map

package/types/validation-helpers.d.ts

@@ -0,0 +1,41 @@
+import type { Node } from "jsonc-parser";
+import type { ConditionalType, NodeType, ObjectType, RefNode } from "@xlr-lib/xlr";
+export interface PropertyNode {
+    /** Equivalent Property Name */
+    key: string;
+    /** Equivalent Property Value */
+    value: Node;
+}
+/**
+ * Takes a property node and returns the underlying Key/Value Pairs
+ */
+export declare function propertyToTuple(node: Node): PropertyNode;
+/**
+ * Turns a node's children into a map for easy access
+ */
+export declare function makePropertyMap(node: Node): Map<string, Node>;
+/**
+ * Checks if property is a leaf node or another node
+ */
+export declare function isNode(obj: Node | string | number | boolean): obj is Node;
+/**
+ * Computes if the first arg extends the second arg
+ */
+export declare function computeExtends(a: NodeType, b: NodeType): boolean;
+/**
+ * Attempts to resolve a conditional type
+ */
+export declare function resolveConditional(conditional: ConditionalType): NodeType;
+/**
+ * Resolve referenced node with potential generic arguments
+ */
+export declare function resolveReferenceNode(genericReference: RefNode, typeToFill: NodeType): NodeType;
+/**
+ * Combines two ObjectType objects to get a representation of the effective TypeScript interface of `base` extending `operand`
+ - * @param base The base interface
+ - * @param operand The interface that is extended
+ - * @param errorOnOverlap whether or not conflicting properties should throw an error or use the property from operand
+ - * @returns `ObjectType`
+ */
+export declare function computeEffectiveObject(base: ObjectType, operand: ObjectType, errorOnOverlap?: boolean): ObjectType;
+//# sourceMappingURL=validation-helpers.d.ts.map