@xlr-lib/xlr-utils 0.1.1--canary.9.190

package/src/type-checks.ts

@@ -0,0 +1,130 @@
+import type {
+  NamedType,
+  NamedTypeWithGenerics,
+  NodeType,
+  NodeTypeWithGenerics,
+  PrimitiveTypes,
+  StringType,
+  NumberType,
+  BooleanType,
+  ObjectType,
+  ArrayType,
+  RefType,
+  OrType,
+  AndType,
+  RecordType,
+} from "@xlr-lib/xlr";
+
+/**
+ * Returns if the NodeType has generic tokens
+ */
+export function isGenericNodeType<T extends NodeType = NodeType>(
+  nt: NodeType,
+): nt is NodeTypeWithGenerics<T> {
+  return (nt as NodeTypeWithGenerics).genericTokens?.length > 0;
+}
+
+/**
+ * Returns if the named type has generic tokens
+ */
+export function isGenericNamedType<T extends NamedType = NamedType>(
+  nt: NodeType,
+): nt is NamedTypeWithGenerics<T> {
+  return (nt as NamedTypeWithGenerics).genericTokens?.length > 0;
+}
+
+/**
+ * Returns if the node is a `PrimitiveTypes`
+ */
+export function isPrimitiveTypeNode(node: NodeType): node is PrimitiveTypes {
+  return (
+    node.type === "string" ||
+    node.type === "number" ||
+    node.type === "boolean" ||
+    node.type === "null" ||
+    node.type === "any" ||
+    node.type === "never" ||
+    node.type === "undefined" ||
+    node.type === "unknown" ||
+    node.type === "void"
+  );
+}
+
+/**
+ * Type Guard for non-null values
+ */
+export function isNonNullable<T>(a: T | null | undefined): a is NonNullable<T> {
+  return a !== null || a !== undefined;
+}
+
+/**
+ * Type guard for string type nodes
+ */
+export function isStringType(node: NodeType): node is StringType {
+  return node.type === "string";
+}
+
+/**
+ * Type guard for number type nodes
+ */
+export function isNumberType(node: NodeType): node is NumberType {
+  return node.type === "number";
+}
+
+/**
+ * Type guard for boolean type nodes
+ */
+export function isBooleanType(node: NodeType): node is BooleanType {
+  return node.type === "boolean";
+}
+
+/**
+ * Type guard for object type nodes
+ */
+export function isObjectType(node: NodeType): node is ObjectType {
+  return node.type === "object";
+}
+
+/**
+ * Type guard for array type nodes
+ */
+export function isArrayType(node: NodeType): node is ArrayType {
+  return node.type === "array";
+}
+
+/**
+ * Type guard for ref type nodes
+ */
+export function isRefType(node: NodeType): node is RefType {
+  return node.type === "ref";
+}
+
+/**
+ * Type guard for or (union) type nodes
+ */
+export function isOrType(node: NodeType): node is OrType {
+  return node.type === "or";
+}
+
+/**
+ * Type guard for and (intersection) type nodes
+ */
+export function isAndType(node: NodeType): node is AndType {
+  return node.type === "and";
+}
+
+/**
+ * Type guard for record type nodes
+ */
+export function isRecordType(node: NodeType): node is RecordType {
+  return node.type === "record";
+}
+
+/**
+ * Type guard for named types (have name and source)
+ */
+export function isNamedType<T extends NodeType = NodeType>(
+  node: NodeType,
+): node is NamedType<T> {
+  return "name" in node && "source" in node && typeof node.name === "string";
+}

package/src/validation-helpers.ts

@@ -0,0 +1,246 @@
+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 "./xlr-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 {
+  return {
+    key: node.children?.[0].value as string,
+    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/src/xlr-helpers.ts

@@ -0,0 +1,340 @@
+import type {
+  NamedType,
+  NodeType,
+  ObjectProperty,
+  ObjectType,
+  OrType,
+  RefNode,
+} from "@xlr-lib/xlr";
+import { computeExtends, resolveConditional } from "./validation-helpers";
+import { isGenericNamedType, isGenericNodeType } from "./type-checks";
+
+/**
+ * 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 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)) {
+      xlrNode.genericTokens?.forEach((token) => {
+        const genericValue = (token.default ?? token.constraints) as NodeType;
+        localGenerics.set(
+          token.symbol,
+          fillInGenerics(genericValue, localGenerics, preferLocalGenerics),
+        );
+      });
+    }
+  }
+
+  if (xlrNode.type === "ref") {
+    if (localGenerics.has(xlrNode.ref)) {
+      return {
+        ...(localGenerics.get(xlrNode.ref) as NodeType),
+        ...(xlrNode.genericArguments
+          ? {
+              genericArguments: xlrNode.genericArguments.map((ga) =>
+                fillInGenerics(ga, localGenerics, preferLocalGenerics),
+              ),
+            }
+          : {}),
+        ...(xlrNode.title ? { title: xlrNode.title } : {}),
+        ...(xlrNode.name ? { name: xlrNode.name } : {}),
+        ...(xlrNode.description ? { description: xlrNode.description } : {}),
+        ...(xlrNode.comment ? { comment: xlrNode.comment } : {}),
+      };
+    }
+
+    return {
+      ...xlrNode,
+      ...(xlrNode.genericArguments
+        ? {
+            genericArguments: xlrNode.genericArguments.map((ga) =>
+              fillInGenerics(ga, localGenerics, preferLocalGenerics),
+            ),
+          }
+        : {}),
+    };
+  }
+
+  if (xlrNode.type === "object") {
+    const newProperties: { [name: string]: ObjectProperty } = {};
+    Object.getOwnPropertyNames(xlrNode.properties).forEach((propName) => {
+      const prop = xlrNode.properties[propName];
+      newProperties[propName] = {
+        required: prop.required,
+        node: fillInGenerics(prop.node, localGenerics, preferLocalGenerics),
+      };
+    });
+
+    return {
+      ...xlrNode,
+      properties: newProperties,
+      ...(isGenericNamedType(xlrNode)
+        ? {
+            genericTokens: xlrNode.genericTokens.map((token) => {
+              return {
+                ...token,
+                constraints: token.constraints
+                  ? fillInGenerics(
+                      token.constraints,
+                      localGenerics,
+                      preferLocalGenerics,
+                    )
+                  : undefined,
+                default: token.default
+                  ? fillInGenerics(
+                      token.default,
+                      localGenerics,
+                      preferLocalGenerics,
+                    )
+                  : undefined,
+              };
+            }),
+          }
+        : {}),
+      extends: xlrNode.extends
+        ? (fillInGenerics(
+            xlrNode.extends,
+            localGenerics,
+            preferLocalGenerics,
+          ) as RefNode)
+        : undefined,
+      additionalProperties: xlrNode.additionalProperties
+        ? fillInGenerics(
+            xlrNode.additionalProperties,
+            localGenerics,
+            preferLocalGenerics,
+          )
+        : false,
+    };
+  }
+
+  if (xlrNode.type === "array") {
+    return {
+      ...xlrNode,
+      elementType: fillInGenerics(
+        xlrNode.elementType,
+        localGenerics,
+        preferLocalGenerics,
+      ),
+    };
+  } else if (xlrNode.type === "or" || xlrNode.type === "and") {
+    let pointer;
+    if (xlrNode.type === "or") {
+      pointer = xlrNode.or;
+    } else {
+      pointer = xlrNode.and;
+    }
+
+    return {
+      ...xlrNode,
+      [xlrNode.type]: pointer.map((prop) => {
+        return fillInGenerics(prop, localGenerics, preferLocalGenerics);
+      }),
+    };
+  } else if (xlrNode.type === "record") {
+    return {
+      ...xlrNode,
+      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,
+          preferLocalGenerics,
+        ),
+        right: fillInGenerics(
+          xlrNode.check.right,
+          localGenerics,
+          preferLocalGenerics,
+        ),
+      },
+      value: {
+        true: fillInGenerics(
+          xlrNode.value.true,
+          localGenerics,
+          preferLocalGenerics,
+        ),
+        false: fillInGenerics(
+          xlrNode.value.false,
+          localGenerics,
+          preferLocalGenerics,
+        ),
+      },
+    };
+
+    // Check to see if we have enough information to resolve this conditional
+    if (
+      filledInConditional.check.left.type !== "ref" &&
+      filledInConditional.check.right.type !== "ref"
+    ) {
+      return {
+        name: xlrNode.name,
+        title: xlrNode.title,
+        ...resolveConditional(filledInConditional),
+      } as NamedType;
+    }
+
+    return filledInConditional;
+  }
+
+  return xlrNode;
+}
+
+/** Applies the TS `Pick` or `Omit` type to an interface/union/intersection */
+export function applyPickOrOmitToNodeType(
+  baseObject: NodeType,
+  operation: "Pick" | "Omit",
+  properties: Set<string>,
+): NodeType | undefined {
+  if (baseObject.type === "object") {
+    const newObject = { ...baseObject };
+    Object.keys(baseObject.properties).forEach((key) => {
+      if (
+        (operation === "Omit" && properties.has(key)) ||
+        (operation === "Pick" && !properties.has(key))
+      ) {
+        delete newObject.properties[key];
+      }
+    });
+
+    /**
+     * Filter out objects in cases:
+     * - A Pick operation and there are no properties left
+     * - An Omit operation and there are no properties left and no additional properties allowed
+     */
+    if (
+      Object.keys(newObject.properties).length === 0 &&
+      (operation !== "Omit" || newObject.additionalProperties === false)
+    ) {
+      return undefined;
+    }
+
+    return newObject;
+  }
+
+  let pointer;
+  if (baseObject.type === "and") {
+    pointer = baseObject.and;
+  } else if (baseObject.type === "or") {
+    pointer = baseObject.or;
+  } else {
+    throw new Error(
+      `Error: Can not apply ${operation} to type ${baseObject.type}`,
+    );
+  }
+
+  const pickedTypes = pointer
+    .map((type) => {
+      const node = applyPickOrOmitToNodeType(type, operation, properties);
+      if (node === undefined) {
+        return undefined;
+      }
+
+      return { ...node, additionalProperties: false } as ObjectType;
+    })
+    .filter((type) => type !== undefined) as NodeType[];
+
+  if (pickedTypes.length === 0) {
+    return undefined;
+  }
+
+  if (pickedTypes.length === 1) {
+    return pickedTypes[0];
+  }
+
+  if (baseObject.type === "and") {
+    return { ...baseObject, and: pickedTypes };
+  }
+
+  return { ...baseObject, or: pickedTypes };
+}
+
+/** Applies the TS `Partial` or `Required` type to an interface/union/intersection */
+export function applyPartialOrRequiredToNodeType(
+  baseObject: NodeType,
+  modifier: boolean,
+): NodeType {
+  if (baseObject.type === "object") {
+    const newObject = { ...baseObject };
+    Object.keys(baseObject.properties).forEach((key) => {
+      newObject.properties[key].required = modifier;
+    });
+
+    return newObject;
+  }
+
+  if (baseObject.type === "and") {
+    const pickedTypes = baseObject.and.map((type) =>
+      applyPartialOrRequiredToNodeType(type, modifier),
+    );
+    return { ...baseObject, and: pickedTypes };
+  }
+
+  if (baseObject.type === "or") {
+    const pickedTypes = baseObject.or.map((type) =>
+      applyPartialOrRequiredToNodeType(type, modifier),
+    );
+    return { ...baseObject, or: pickedTypes };
+  }
+
+  throw new Error(
+    `Error: Can not apply ${modifier ? "Required" : "Partial"} to type ${
+      baseObject.type
+    }`,
+  );
+}
+
+/** Applies the TS `Exclude` type to a union */
+export function applyExcludeToNodeType(
+  baseObject: OrType,
+  filters: NodeType | OrType,
+): NodeType {
+  const remainingMembers = baseObject.or.filter((type) => {
+    if (filters.type === "or") {
+      return !filters.or.some((filter) => computeExtends(type, filter));
+    }
+
+    return !computeExtends(type, filters);
+  });
+
+  if (remainingMembers.length === 1) {
+    return remainingMembers[0];
+  }
+
+  return {
+    ...baseObject,
+    or: remainingMembers,
+  };
+}

package/types/index.d.ts

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