@player-tools/xlr-sdk 0.2.1-next.4 → 0.2.1

package/src/sdk.ts

@@ -2,10 +2,15 @@ import type {
   Manifest,
   NamedType,
   NodeType,
+  ObjectType,
   TransformFunction,
   TSManifest,
 } from '@player-tools/xlr';
 import type { TopLevelDeclaration } from '@player-tools/xlr-utils';
+import {
+  computeEffectiveObject,
+  resolveReferenceNode,
+} from '@player-tools/xlr-utils';
 import { fillInGenerics } from '@player-tools/xlr-utils';
 import type { Node } from 'jsonc-parser';
 import { TSWriter } from '@player-tools/xlr-converters';
@@ -17,6 +22,12 @@ import type { XLRRegistry, Filters } from './registry';
 import { BasicXLRRegistry } from './registry';
 import type { ExportTypes } from './types';
 import { XLRValidator } from './validator';
+import { simpleTransformGenerator } from './utils';
+
+export interface GetTypeOptions {
+  /** Resolves `extends` fields in objects */
+  getRawType?: boolean;
+}
 
 /**
  * Abstraction for interfacing with XLRs making it more approachable to use without understanding the inner workings of the types and how they are packaged
@@ -28,10 +39,17 @@ export class XLRSDK {
 
   constructor(customRegistry?: XLRRegistry) {
     this.registry = customRegistry ?? new BasicXLRRegistry();
-    this.validator = new XLRValidator(this.registry);
+    this.validator = new XLRValidator(this.getType.bind(this));
     this.tsWriter = new TSWriter();
   }
 
+  /**
+   * Loads definitions from a path on the filesystem
+   *
+   * @param inputPath - path to the directory to load (above the xlr folder)
+   * @param filters - Any filters to apply when loading the types (a positive match will omit)
+   * @param transforms - any transforms to apply to the types being loaded
+   */
   public loadDefinitionsFromDisk(
     inputPath: string,
     filters?: Omit<Filters, 'pluginFilter'>,
@@ -66,24 +84,34 @@ export class XLRSDK {
               )
               .toString()
           );
-          transforms?.forEach((transform) => transform(cType, capabilityName));
-          const resolvedType = fillInGenerics(cType) as NamedType<NodeType>;
-          this.registry.add(resolvedType, manifest.pluginName, capabilityName);
+          const effectiveType =
+            transforms?.reduce(
+              (typeAccumulator: NamedType<NodeType>, transformFn) =>
+                transformFn(
+                  typeAccumulator,
+                  capabilityName
+                ) as NamedType<NodeType>,
+              cType
+            ) ?? cType;
+
+          this.registry.add(effectiveType, manifest.pluginName, capabilityName);
         }
       });
     });
   }
 
+  /**
+   * Load definitions from a js/ts file in memory
+   *
+   * @param manifest - The imported XLR manifest module
+   * @param filters - Any filters to apply when loading the types (a positive match will omit)
+   * @param transforms - any transforms to apply to the types being loaded
+   */
   public async loadDefinitionsFromModule(
-    inputPath: string,
+    manifest: TSManifest,
     filters?: Omit<Filters, 'pluginFilter'>,
     transforms?: Array<TransformFunction>
   ) {
-    const importManifest = await import(
-      path.join(inputPath, 'xlr', 'manifest.js')
-    );
-    const manifest = importManifest.default as TSManifest;
-
     Object.keys(manifest.capabilities)?.forEach((capabilityName) => {
       if (
         filters?.capabilityFilter &&
@@ -96,30 +124,82 @@ export class XLRSDK {
           !filters?.typeFilter ||
           !extension.name.match(filters?.typeFilter)
         ) {
-          transforms?.forEach((transform) =>
-            transform(extension, extension.name)
-          );
-          const resolvedType = fillInGenerics(extension) as NamedType<NodeType>;
-          this.registry.add(resolvedType, manifest.pluginName, extension.name);
+          const effectiveType =
+            transforms?.reduce(
+              (typeAccumulator: NamedType<NodeType>, transformFn) =>
+                transformFn(
+                  typeAccumulator,
+                  capabilityName
+                ) as NamedType<NodeType>,
+              extension
+            ) ?? extension;
+
+          this.registry.add(effectiveType, manifest.pluginName, capabilityName);
         }
       });
     });
   }
 
-  public getType(id: string) {
-    return this.registry.get(id);
+  /**
+   * Returns a Type that has been previously loaded
+   *
+   * @param id - Type to retrieve
+   * @param options - `GetTypeOptions`
+   * @returns `NamedType<NodeType>` | `undefined`
+   */
+  public getType(
+    id: string,
+    options?: GetTypeOptions
+  ): NamedType<NodeType> | undefined {
+    let type = this.registry.get(id);
+    if (options?.getRawType === true || !type) {
+      return type;
+    }
+
+    type = this.resolveType(type);
+
+    return fillInGenerics(type) as NamedType;
   }
 
+  /**
+   * Returns if a Type with `id` has been loaded into the DSK
+   *
+   * @param id - Type to retrieve
+   * @returns `boolean`
+   */
   public hasType(id: string) {
     return this.registry.has(id);
   }
 
+  /**
+   * Lists types that have been loaded into the SDK
+   *
+   * @param filters - Any filters to apply to the types returned (a positive match will omit)
+   * @returns `Array<NamedTypes>`
+   */
   public listTypes(filters?: Filters) {
     return this.registry.list(filters);
   }
 
-  public validate(typeName: string, rootNode: Node) {
-    const xlr = this.registry.get(typeName);
+  /**
+   * Returns meta information around a registered type
+   *
+   * @param id - Name of Type to retrieve
+   * @returns `TypeMetaData` | `undefined`
+   */
+  public getTypeInfo(id: string) {
+    return this.registry.info(id);
+  }
+
+  /**
+   * Validates if a JSONC Node follows the XLR Type registered under the `typeName` specified
+   *
+   * @param typeName - Registered XLR Type to use for validation
+   * @param rootNode - Node to validate
+   * @returns `Array<ValidationErrors>`
+   */
+  public validateByName(typeName: string, rootNode: Node) {
+    const xlr = this.getType(typeName, { getRawType: true });
     if (!xlr) {
       throw new Error(
         `Type ${typeName} does not exist in registry, can't validate`
@@ -129,6 +209,17 @@ export class XLRSDK {
     return this.validator.validateType(rootNode, xlr);
   }
 
+  /**
+   * Validates if a JSONC Node follows the supplied XLR Type
+   *
+   * @param type - Type to validate against
+   * @param rootNode - Node to validate
+   * @returns `Array<ValidationErrors>`
+   */
+  public validateByType(type: NodeType, rootNode: Node) {
+    return this.validator.validateType(rootNode, type);
+  }
+
   /**
    * Exports the types loaded into the registry to the specified format
    *
@@ -145,13 +236,18 @@ export class XLRSDK {
     transforms?: Array<TransformFunction>
   ): [string, string][] {
     const typesToExport = this.registry.list(filters).map((type) => {
-      transforms?.forEach((transformFunction) =>
-        transformFunction(
-          type,
-          this.registry.info(type.name)?.capability as string
-        )
-      );
-      return type;
+      const resolvedType = this.resolveType(type);
+      const effectiveType =
+        transforms?.reduce(
+          (typeAccumulator: NamedType<NodeType>, transformFn) =>
+            transformFn(
+              typeAccumulator,
+              this.registry.info(type.name)?.capability as string
+            ) as NamedType<NodeType>,
+          resolvedType
+        ) ?? resolvedType;
+
+      return effectiveType;
     });
 
     if (exportType === 'TypeScript') {
@@ -162,6 +258,36 @@ export class XLRSDK {
     throw new Error(`Unknown export format ${exportType}`);
   }
 
+  private resolveType(type: NodeType) {
+    return simpleTransformGenerator('object', 'any', (objectNode) => {
+      if (objectNode.extends) {
+        const refName = objectNode.extends.ref.split('<')[0];
+        let extendedType = this.getType(refName, { getRawType: true });
+        if (!extendedType) {
+          throw new Error(
+            `Error resolving ${objectNode.name}: can't find extended type ${refName}`
+          );
+        }
+
+        extendedType = resolveReferenceNode(
+          objectNode.extends,
+          extendedType as NamedType<ObjectType>
+        ) as NamedType;
+        return {
+          ...computeEffectiveObject(
+            extendedType as ObjectType,
+            objectNode as ObjectType,
+            false
+          ),
+          name: objectNode.name,
+          description: objectNode.description,
+        };
+      }
+
+      return objectNode;
+    })(type, 'any') as NamedType;
+  }
+
   private exportToTypeScript(
     typesToExport: NamedType[],
     importMap: Map<string, string[]>
@@ -202,7 +328,6 @@ export class XLRSDK {
       const applicableImports = imports.filter((i) => referencedImports.has(i));
       resultFile = ts.factory.updateSourceFile(resultFile, [
         ts.factory.createImportDeclaration(
-          /* decorators */ undefined,
           /* modifiers */ undefined,
           ts.factory.createImportClause(
             false,

package/src/utils.ts

@@ -6,6 +6,8 @@ import type {
   NodeTypeMap,
   TransformFunction,
   NodeType,
+  ObjectProperty,
+  RefNode,
 } from '@player-tools/xlr';
 
 /**
@@ -17,68 +19,127 @@ export function simpleTransformGenerator<
 >(
   typeToTransform: T,
   capabilityToTransform: string,
-  functionToRun: (input: NodeTypeMap[T]) => void
+  functionToRun: (input: NodeTypeMap[T]) => NodeTypeMap[T]
 ): TransformFunction {
   /** walker for an XLR tree to touch every node */
   const walker: TransformFunction = (
-    node: NamedType | NodeType,
+    n: NamedType | NodeType,
     capability: string
   ) => {
     // Run transform on base node before running on children
     if (capability === capabilityToTransform) {
+      let node = { ...n };
       if (node.type === typeToTransform) {
-        functionToRun(node as unknown as NodeTypeMap[T]);
+        node = functionToRun(node as unknown as NodeTypeMap[T]);
       }
 
       if (node.type === 'object') {
-        if (node.extends) {
-          walker(node, capability);
-        }
+        const newObjectProperties: Record<string, ObjectProperty> = {};
 
         for (const key in node.properties) {
           const value = node.properties[key];
-          walker(value.node, capability);
+          newObjectProperties[key] = {
+            required: value.required,
+            node: walker(value.node, capability),
+          };
         }
 
-        if (node.additionalProperties) {
-          walker(node.additionalProperties, capability);
-        }
-      } else if (node.type === 'array') {
-        walker(node.elementType, capability);
-      } else if (node.type === 'and') {
-        node.and.forEach((element) => walker(element, capability));
-      } else if (node.type === 'or') {
-        node.or.forEach((element) => walker(element, capability));
-      } else if (node.type === 'ref') {
-        node.genericArguments?.forEach((element) =>
-          walker(element, capability)
-        );
-      } else if (node.type === 'tuple') {
-        if (node.additionalItems) {
-          walker(node.additionalItems, capability);
-        }
+        return {
+          ...node,
+          properties: { ...newObjectProperties },
+          extends: node.extends
+            ? (walker(node.extends, capability) as RefNode)
+            : undefined,
+          additionalProperties: node.additionalProperties
+            ? walker(node.additionalProperties, capability)
+            : false,
+        };
+      }
 
-        node.elementTypes.forEach((element) => walker(element, capability));
-      } else if (node.type === 'function') {
-        node.parameters.forEach((param) => {
-          walker(param.type, capability);
-          if (param.default) {
-            walker(param.default, capability);
-          }
-        });
-        if (node.returnType) {
-          walker(node.returnType, capability);
-        }
-      } else if (node.type === 'record') {
-        walker(node.keyType, capability);
-        walker(node.valueType, capability);
-      } else if (node.type === 'conditional') {
-        walker(node.check.left, capability);
-        walker(node.check.right, capability);
-        walker(node.value.true, capability);
-        walker(node.value.false, capability);
+      if (node.type === 'array') {
+        return {
+          ...node,
+          elementType: walker(node.elementType, capability),
+        };
+      }
+
+      if (node.type === 'and') {
+        return {
+          ...node,
+          and: node.and.map((element) => walker(element, capability)),
+        };
+      }
+
+      if (node.type === 'or') {
+        return {
+          ...node,
+          or: node.or.map((element) => walker(element, capability)),
+        };
+      }
+
+      if (node.type === 'ref') {
+        return {
+          ...node,
+          genericArguments: node.genericArguments?.map((arg) =>
+            walker(arg, capability)
+          ),
+        };
+      }
+
+      if (node.type === 'tuple') {
+        return {
+          ...node,
+          elementTypes: node.elementTypes.map((type) =>
+            walker(type, capability)
+          ),
+          additionalItems: node.additionalItems
+            ? walker(node.additionalItems, capability)
+            : false,
+        };
+      }
+
+      if (node.type === 'function') {
+        return {
+          ...node,
+          parameters: node.parameters.map((param) => {
+            return {
+              ...param,
+              type: walker(param.type, capability),
+              default: param.default
+                ? walker(param.default, capability)
+                : undefined,
+            };
+          }),
+          returnType: node.returnType
+            ? walker(node.returnType, capability)
+            : undefined,
+        };
+      }
+
+      if (node.type === 'record') {
+        return {
+          ...node,
+          keyType: walker(node.keyType, capability),
+          valueType: walker(node.valueType, capability),
+        };
+      }
+
+      if (node.type === 'conditional') {
+        return {
+          ...node,
+          check: {
+            left: walker(node.check.left, capability),
+            right: walker(node.check.left, capability),
+          },
+          value: {
+            true: walker(node.value.true, capability),
+            false: walker(node.value.false, capability),
+          },
+        };
       }
     }
+
+    return n;
   };
 
   return walker;

package/src/validator.ts

@@ -13,21 +13,20 @@ import {
   makePropertyMap,
   resolveConditional,
   isPrimitiveTypeNode,
-  fillInGenerics,
-  isGenericNodeType,
+  resolveReferenceNode,
+  computeEffectiveObject,
 } from '@player-tools/xlr-utils';
 import type { ValidationError } from './types';
-import type { XLRRegistry } from './registry';
 
 /**
  * Validator for XLRs on JSON Nodes
  */
 export class XLRValidator {
-  private typeMap: XLRRegistry;
+  private resolveType: (id: string) => NamedType<NodeType> | undefined;
   private regexCache: Map<string, RegExp>;
 
-  constructor(typeMap: XLRRegistry) {
-    this.typeMap = typeMap;
+  constructor(resolveType: (id: string) => NamedType<NodeType> | undefined) {
+    this.resolveType = resolveType;
     this.regexCache = new Map();
   }
 
@@ -74,7 +73,10 @@ export class XLRValidator {
         message: `Does not match any of the expected types for type: '${xlrNode.name}'`,
       });
     } else if (xlrNode.type === 'and') {
-      const effectiveType = this.computeIntersectionType(xlrNode.and);
+      const effectiveType = {
+        ...this.computeIntersectionType(xlrNode.and),
+        ...(xlrNode.name ? { name: xlrNode.name } : {}),
+      };
       validationIssues.push(...this.validateType(rootNode, effectiveType));
     } else if (xlrNode.type === 'record') {
       rootNode.children?.forEach((child) => {
@@ -120,14 +122,35 @@ export class XLRValidator {
         }
       }
     } else if (xlrNode.type === 'conditional') {
-      const resolvedType = resolveConditional(xlrNode);
-      if (resolvedType === xlrNode) {
+      // Resolve RefNodes in check conditions if needed
+      let { right, left } = xlrNode.check;
+
+      if (right.type === 'ref') {
+        right = this.getRefType(right);
+      }
+
+      if (left.type === 'ref') {
+        left = this.getRefType(left);
+      }
+
+      const resolvedXLRNode = {
+        ...xlrNode,
+        check: {
+          left,
+          right,
+        },
+      };
+
+      const resolvedConditional = resolveConditional(resolvedXLRNode);
+      if (resolvedConditional === resolvedXLRNode) {
         throw Error(
           `Unable to resolve conditional type at runtime: ${xlrNode.name}`
         );
       }
 
-      validationIssues.push(...this.validateType(rootNode, resolvedType));
+      validationIssues.push(
+        ...this.validateType(rootNode, resolvedConditional)
+      );
     } else {
       throw Error(`Unknown type ${xlrNode.type}`);
     }
@@ -174,7 +197,7 @@ export class XLRValidator {
 
     if (xlrNode.extends) {
       const extendedNode = this.getRefType(xlrNode.extends) as ObjectType;
-      effectiveXLRNode = this.computeEffectiveObject(extendedNode, xlrNode);
+      effectiveXLRNode = computeEffectiveObject(extendedNode, xlrNode);
     }
 
     // eslint-disable-next-line guard-for-in, no-restricted-syntax
@@ -233,27 +256,22 @@ export class XLRValidator {
         }
 
         return typeof literalType.value === 'boolean';
-        break;
       case 'number':
         if (expectedType.const) {
           return expectedType.const === literalType.value;
         }
 
         return typeof literalType.value === 'number';
-        break;
       case 'string':
         if (expectedType.const) {
           return expectedType.const === literalType.value;
         }
 
         return typeof literalType.value === 'string';
-        break;
       case 'null':
         return literalType.value === 'null';
-        break;
       case 'never':
         return literalType === undefined;
-        break;
       case 'any':
         return literalType !== undefined;
       case 'unknown':
@@ -267,27 +285,16 @@ export class XLRValidator {
 
   private getRefType(ref: RefType): NodeType {
     let refName = ref.ref;
-    const { genericArguments } = ref;
-
     if (refName.indexOf('<') > 0) {
       [refName] = refName.split('<');
     }
 
-    const actualType = this.typeMap.get(refName) as NodeType;
-    const genericMap: Map<string, NodeType> = new Map();
-
-    // Compose first level generics here since `fillInGenerics` won't process them if a map is passed in
-    if (genericArguments && isGenericNodeType(actualType)) {
-      actualType.genericTokens.forEach((token, index) => {
-        genericMap.set(
-          token.symbol,
-          genericArguments[index] ?? token.default ?? token.constraints
-        );
-      });
+    const actualType = this.resolveType(refName);
+    if (!actualType) {
+      throw new Error(`Error: can't resolve type reference ${refName}`);
     }
 
-    // Fill in generics
-    return fillInGenerics(actualType, genericMap);
+    return resolveReferenceNode(ref, actualType);
   }
 
   private getRegex(expString: string): RegExp {
@@ -310,6 +317,12 @@ export class XLRValidator {
 
     if (firstElement.type === 'and') {
       effectiveType = this.computeIntersectionType(firstElement.and);
+    } else if (firstElement.type === 'record') {
+      effectiveType = {
+        type: 'object',
+        properties: {},
+        additionalProperties: firstElement.valueType,
+      };
     } else if (firstElement.type !== 'or' && firstElement.type !== 'object') {
       throw new Error(
         `Can't compute a union with a non-object type ${firstElement.type} (${firstElement.name})`
@@ -321,6 +334,14 @@ export class XLRValidator {
     types.slice(1).forEach((type) => {
       let typeToApply = type;
 
+      if (typeToApply.type === 'record') {
+        typeToApply = {
+          type: 'object',
+          properties: {},
+          additionalProperties: typeToApply.valueType,
+        };
+      }
+
       if (type.type === 'ref') {
         typeToApply = this.getRefType(type);
       }
@@ -331,10 +352,7 @@ export class XLRValidator {
 
       if (typeToApply.type === 'object') {
         if (effectiveType.type === 'object') {
-          effectiveType = this.computeEffectiveObject(
-            effectiveType,
-            typeToApply
-          );
+          effectiveType = computeEffectiveObject(effectiveType, typeToApply);
         } else {
           effectiveType = {
             ...effectiveType,
@@ -363,45 +381,4 @@ export class XLRValidator {
 
     return effectiveType;
   }
-
-  private computeEffectiveObject(
-    base: ObjectType,
-    operand: ObjectType,
-    errorOnOverlap = true
-  ): ObjectType {
-    const baseObjectName = base.name ?? 'object literal';
-    const operandObjectName = operand.name ?? 'object literal';
-    const newObject = {
-      ...base,
-      name: `${baseObjectName} & ${operandObjectName}`,
-      description: `Effective type combining ${baseObjectName} and ${operandObjectName}`,
-    };
-
-    // eslint-disable-next-line no-restricted-syntax, guard-for-in
-    for (const property in operand.properties) {
-      if (
-        newObject.properties[property] !== undefined &&
-        newObject.properties[property].node.type !==
-          operand.properties[property].node.type &&
-        errorOnOverlap
-      ) {
-        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) {
-      newObject.additionalProperties = {
-        type: 'and',
-        and: [newObject.additionalProperties, operand.additionalProperties],
-      };
-    } else if (operand.additionalProperties) {
-      newObject.additionalProperties = operand.additionalProperties;
-    }
-
-    return newObject;
-  }
 }