@player-tools/xlr-sdk 0.0.2-next.0

package/src/sdk.ts

@@ -0,0 +1,229 @@
+import type {
+  Manifest,
+  NamedType,
+  NodeType,
+  TransformFunction,
+  TSManifest,
+} from '@player-tools/xlr';
+import type { TopLevelDeclaration } 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';
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+
+import type { XLRRegistry, Filters } from './registry';
+import { BasicXLRRegistry } from './registry';
+import type { ExportTypes } from './types';
+import { XLRValidator } from './validator';
+
+/**
+ * Abstraction for interfacing with XLRs making it more approachable to use without understanding the inner workings of the types and how they are packaged
+ */
+export class XLRSDK {
+  private registry: XLRRegistry;
+  private validator: XLRValidator;
+  private tsWriter: TSWriter;
+
+  constructor(customRegistry?: XLRRegistry) {
+    this.registry = customRegistry ?? new BasicXLRRegistry();
+    this.validator = new XLRValidator(this.registry);
+    this.tsWriter = new TSWriter();
+  }
+
+  public loadDefinitionsFromDisk(
+    inputPath: string,
+    filters?: Omit<Filters, 'pluginFilter'>,
+    transforms?: Array<TransformFunction>
+  ) {
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(inputPath, 'xlr', 'manifest.json')).toString(),
+      (key: unknown, value: unknown) => {
+        // Custom parser because JSON objects -> JS Objects, not maps
+        if (typeof value === 'object' && value !== null) {
+          if (key === 'capabilities') {
+            return new Map(Object.entries(value));
+          }
+        }
+
+        return value;
+      }
+    ) as Manifest;
+
+    manifest.capabilities?.forEach((capabilityList, capabilityName) => {
+      if (
+        filters?.capabilityFilter &&
+        capabilityName.match(filters?.capabilityFilter)
+      )
+        return;
+      capabilityList.forEach((extensionName) => {
+        if (!filters?.typeFilter || !extensionName.match(filters?.typeFilter)) {
+          const cType: NamedType<NodeType> = JSON.parse(
+            fs
+              .readFileSync(
+                path.join(inputPath, 'xlr', `${extensionName}.json`)
+              )
+              .toString()
+          );
+          transforms?.forEach((transform) => transform(cType, capabilityName));
+          const resolvedType = fillInGenerics(cType) as NamedType<NodeType>;
+          this.registry.add(resolvedType, manifest.pluginName, capabilityName);
+        }
+      });
+    });
+  }
+
+  public async loadDefinitionsFromModule(
+    inputPath: string,
+    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 &&
+        capabilityName.match(filters?.capabilityFilter)
+      )
+        return;
+      const capabilityList = manifest.capabilities[capabilityName];
+      capabilityList.forEach((extension) => {
+        if (
+          !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);
+        }
+      });
+    });
+  }
+
+  public getType(id: string) {
+    return this.registry.get(id);
+  }
+
+  public hasType(id: string) {
+    return this.registry.has(id);
+  }
+
+  public listTypes(filters?: Filters) {
+    return this.registry.list(filters);
+  }
+
+  public validate(typeName: string, rootNode: Node) {
+    const xlr = this.registry.get(typeName);
+    if (!xlr) {
+      throw new Error(
+        `Type ${typeName} does not exist in registry, can't validate`
+      );
+    }
+
+    return this.validator.validateType(rootNode, xlr);
+  }
+
+  /**
+   * Exports the types loaded into the registry to the specified format
+   *
+   * @param exportType - what format to export as
+   * @param importMap - a map of primitive packages to types exported from that package to add import statements
+   * @param filters - filter out plugins/capabilities/types you don't want to export
+   * @param transforms - transforms to apply to types before exporting them
+   * @returns [filename, content][] - Tuples of filenames and content to write
+   */
+  public exportRegistry(
+    exportType: ExportTypes,
+    importMap: Map<string, string[]>,
+    filters?: Filters,
+    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;
+    });
+
+    if (exportType === 'TypeScript') {
+      const outputString = this.exportToTypeScript(typesToExport, importMap);
+      return [['out.d.ts', outputString]];
+    }
+
+    throw new Error(`Unknown export format ${exportType}`);
+  }
+
+  private exportToTypeScript(
+    typesToExport: NamedType[],
+    importMap: Map<string, string[]>
+  ): string {
+    const referencedImports: Set<string> = new Set();
+    const exportedTypes: Map<string, TopLevelDeclaration> = new Map();
+    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+
+    let resultFile = ts.createSourceFile(
+      'output.d.ts',
+      '',
+      ts.ScriptTarget.ES2017,
+      false, // setParentNodes
+      ts.ScriptKind.TS
+    );
+
+    typesToExport.forEach((typeNode) => {
+      const { type, referencedTypes, additionalTypes } =
+        this.tsWriter.convertNamedType(typeNode);
+      exportedTypes.set(typeNode.name, type);
+      additionalTypes?.forEach((additionalType, name) =>
+        exportedTypes.set(name, additionalType)
+      );
+      referencedTypes?.forEach((referencedType) =>
+        referencedImports.add(referencedType)
+      );
+    });
+
+    const typesToPrint: Array<string> = [];
+
+    exportedTypes.forEach((type) =>
+      typesToPrint.push(
+        printer.printNode(ts.EmitHint.Unspecified, type, resultFile)
+      )
+    );
+
+    importMap.forEach((imports, packageName) => {
+      const applicableImports = imports.filter((i) => referencedImports.has(i));
+      resultFile = ts.factory.updateSourceFile(resultFile, [
+        ts.factory.createImportDeclaration(
+          /* decorators */ undefined,
+          /* modifiers */ undefined,
+          ts.factory.createImportClause(
+            false,
+            undefined,
+            ts.factory.createNamedImports(
+              applicableImports.map((i) =>
+                ts.factory.createImportSpecifier(
+                  undefined,
+                  ts.factory.createIdentifier(i)
+                )
+              )
+            )
+          ),
+          ts.factory.createStringLiteral(packageName)
+        ),
+        ...resultFile.statements,
+      ]);
+    });
+
+    const headerText = printer.printFile(resultFile);
+    const nodeText = typesToPrint.join('\n');
+    return `${headerText}\n${nodeText}`;
+  }
+}

package/src/types.ts

@@ -0,0 +1,15 @@
+import type { Node } from 'jsonc-parser';
+
+export interface ValidationError {
+  /** Error message text */
+  message: string;
+
+  /** JSONC node that the error originates from */
+  node: Node;
+
+  /** Rough categorization of the error type */
+  type: 'type' | 'missing' | 'unknown' | 'value' | 'unexpected';
+}
+
+/** Support Export Formats */
+export type ExportTypes = 'TypeScript';

package/src/validator.ts

@@ -0,0 +1,398 @@
+import type { Node } from 'jsonc-parser';
+import type {
+  ArrayType,
+  NamedType,
+  NodeType,
+  ObjectType,
+  OrType,
+  PrimitiveTypes,
+  RefType,
+  TemplateLiteralType,
+} from '@player-tools/xlr';
+import {
+  makePropertyMap,
+  resolveConditional,
+  isPrimitiveTypeNode,
+  fillInGenerics,
+  isGenericNodeType,
+} 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 regexCache: Map<string, RegExp>;
+
+  constructor(typeMap: XLRRegistry) {
+    this.typeMap = typeMap;
+    this.regexCache = new Map();
+  }
+
+  /** Main entrypoint for validation */
+  public validateType(
+    rootNode: Node,
+    xlrNode: NodeType
+  ): Array<ValidationError> {
+    const validationIssues = new Array<ValidationError>();
+    if (xlrNode.type === 'object') {
+      if (rootNode.type === 'object') {
+        validationIssues.push(...this.validateObject(xlrNode, rootNode));
+      } else {
+        validationIssues.push({
+          type: 'type',
+          node: rootNode,
+          message: `Expected an object but got an '${rootNode.type}'`,
+        });
+      }
+    } else if (xlrNode.type === 'array') {
+      if (rootNode.type === 'array') {
+        validationIssues.push(...this.validateArray(rootNode, xlrNode));
+      } else {
+        validationIssues.push({
+          type: 'type',
+          node: rootNode,
+          message: `Expected an array but got an '${rootNode.type}'`,
+        });
+      }
+    } else if (xlrNode.type === 'template') {
+      this.validateTemplate(rootNode, xlrNode);
+    } else if (xlrNode.type === 'or') {
+      // eslint-disable-next-line no-restricted-syntax
+      for (const potentialType of xlrNode.or) {
+        const potentialErrors = this.validateType(rootNode, potentialType);
+        if (potentialErrors.length === 0) {
+          return validationIssues;
+        }
+      }
+
+      validationIssues.push({
+        type: 'value',
+        node: rootNode,
+        message: `Does not match any of the expected types for type: '${xlrNode.name}'`,
+      });
+    } else if (xlrNode.type === 'and') {
+      const effectiveType = this.computeIntersectionType(xlrNode.and);
+      validationIssues.push(...this.validateType(rootNode, effectiveType));
+    } else if (xlrNode.type === 'record') {
+      rootNode.children?.forEach((child) => {
+        validationIssues.push(
+          ...this.validateType(child.children?.[0] as Node, xlrNode.keyType)
+        );
+        validationIssues.push(
+          ...this.validateType(child.children?.[1] as Node, xlrNode.valueType)
+        );
+      });
+    } else if (xlrNode.type === 'ref') {
+      const refType = this.getRefType(xlrNode);
+      if (refType === undefined) {
+        validationIssues.push({
+          type: 'unknown',
+          node: rootNode,
+          message: `Type '${xlrNode.ref}' is not defined in provided bundles`,
+        });
+      } else {
+        validationIssues.push(
+          ...this.validateType(rootNode, refType as NamedType)
+        );
+      }
+    } else if (isPrimitiveTypeNode(xlrNode)) {
+      if (!this.validateLiteralType(xlrNode, rootNode)) {
+        if (
+          (xlrNode.type === 'string' ||
+            xlrNode.type === 'number' ||
+            xlrNode.type === 'boolean') &&
+          xlrNode.const
+        ) {
+          validationIssues.push({
+            type: 'type',
+            node: rootNode.parent as Node,
+            message: `Expected '${xlrNode.const}' but got '${rootNode.value}'`,
+          });
+        } else {
+          validationIssues.push({
+            type: 'type',
+            node: rootNode.parent as Node,
+            message: `Expected type '${xlrNode.type}' but got '${rootNode.type}'`,
+          });
+        }
+      }
+    } else if (xlrNode.type === 'conditional') {
+      const resolvedType = resolveConditional(xlrNode);
+      if (resolvedType === xlrNode) {
+        throw Error(
+          `Unable to resolve conditional type at runtime: ${xlrNode.name}`
+        );
+      }
+
+      validationIssues.push(...this.validateType(rootNode, resolvedType));
+    } else {
+      throw Error(`Unknown type ${xlrNode.type}`);
+    }
+
+    return validationIssues;
+  }
+
+  private validateTemplate(
+    node: Node,
+    xlrNode: TemplateLiteralType
+  ): ValidationError | undefined {
+    if (node.type !== 'string') {
+      return {
+        type: 'type',
+        node: node.parent as Node,
+        message: `Expected type '${xlrNode.type}' but got '${typeof node}'`,
+      };
+    }
+
+    const regex = this.getRegex(xlrNode.format);
+    const valid = regex.exec(node.value);
+    if (!valid) {
+      return {
+        type: 'value',
+        node: node.parent as Node,
+        message: `Does not match expected format: ${xlrNode.format}`,
+      };
+    }
+  }
+
+  private validateArray(rootNode: Node, xlrNode: ArrayType) {
+    const issues: Array<ValidationError> = [];
+    rootNode.children?.forEach((child) =>
+      issues.push(...this.validateType(child, xlrNode.elementType))
+    );
+    return issues;
+  }
+
+  private validateObject(xlrNode: ObjectType, node: Node) {
+    const issues: Array<ValidationError> = [];
+    const objectProps = makePropertyMap(node);
+    // eslint-disable-next-line guard-for-in, no-restricted-syntax
+    for (const prop in xlrNode.properties) {
+      const expectedType = xlrNode.properties[prop];
+      const valueNode = objectProps.get(prop);
+      if (expectedType.required && valueNode === undefined) {
+        issues.push({
+          type: 'missing',
+          node,
+          message: `Property '${prop}' missing from type '${xlrNode.name}'`,
+        });
+      }
+
+      if (valueNode) {
+        issues.push(
+          ...this.validateType(valueNode, expectedType.node as NamedType)
+        );
+      }
+    }
+
+    // Check if unknown keys are allowed and if they are - do the violate the constraint
+    const extraKeys = Array.from(objectProps.keys()).filter(
+      (key) => xlrNode.properties[key] === undefined
+    );
+    if (xlrNode.additionalProperties === false && extraKeys.length > 0) {
+      issues.push({
+        type: 'value',
+        node,
+        message: `Unexpected properties on '${xlrNode.name}': ${extraKeys.join(
+          ', '
+        )}`,
+      });
+    } else {
+      issues.push(
+        ...extraKeys.flatMap((key) =>
+          this.validateType(
+            objectProps.get(key) as Node,
+            xlrNode.additionalProperties as NodeType
+          )
+        )
+      );
+    }
+
+    return issues;
+  }
+
+  private validateLiteralType(expectedType: PrimitiveTypes, literalType: Node) {
+    switch (expectedType.type) {
+      case 'boolean':
+        if (expectedType.const) {
+          return expectedType.const === literalType.value;
+        }
+
+        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':
+        return literalType !== undefined;
+      case 'undefined':
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  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
+        );
+      });
+    }
+
+    // Fill in generics
+    return fillInGenerics(actualType, genericMap);
+  }
+
+  private getRegex(expString: string): RegExp {
+    if (this.regexCache.has(expString)) {
+      return this.regexCache.get(expString) as RegExp;
+    }
+
+    const exp = new RegExp(expString);
+    this.regexCache.set(expString, exp);
+    return exp;
+  }
+
+  private computeIntersectionType(types: Array<NodeType>): ObjectType | OrType {
+    let firstElement = types[0];
+    let effectiveType: ObjectType | OrType;
+
+    if (firstElement.type === 'ref') {
+      firstElement = this.getRefType(firstElement);
+    }
+
+    if (firstElement.type === 'and') {
+      effectiveType = this.computeIntersectionType(firstElement.and);
+    } 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})`
+      );
+    } else {
+      effectiveType = firstElement;
+    }
+
+    types.slice(1).forEach((type) => {
+      let typeToApply = type;
+
+      if (type.type === 'ref') {
+        typeToApply = this.getRefType(type);
+      }
+
+      if (typeToApply.type === 'and') {
+        typeToApply = this.computeIntersectionType([type, effectiveType]);
+      }
+
+      if (typeToApply.type === 'object') {
+        if (effectiveType.type === 'object') {
+          effectiveType = this.computeEffectiveObject(
+            effectiveType,
+            typeToApply
+          );
+        } else {
+          effectiveType = {
+            ...effectiveType,
+            or: effectiveType.or.map((y) =>
+              this.computeIntersectionType([y, typeToApply])
+            ),
+          };
+        }
+      } else if (typeToApply.type === 'or') {
+        if (effectiveType.type === 'object') {
+          effectiveType = {
+            ...typeToApply,
+            or: typeToApply.or.map((y) =>
+              this.computeIntersectionType([y, effectiveType])
+            ),
+          };
+        } else {
+          throw new Error('unimplemented operation or x or projection');
+        }
+      } else {
+        throw new Error(
+          `Can't compute a union with a non-object type ${typeToApply.type} (${typeToApply.name})`
+        );
+      }
+    });
+
+    return effectiveType;
+  }
+
+  private computeEffectiveObject(
+    base: ObjectType,
+    operand: ObjectType,
+    errorOnOverlap = true
+  ): ObjectType {
+    const newObject = {
+      ...base,
+      name: `${base.name} & ${operand.name}`,
+      description: `Effective type combining ${base.name} and ${operand.name}`,
+    };
+
+    // 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 ${
+            base.name ?? 'object literal'
+          } and ${
+            operand.name ?? 'object literal'
+          } 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;
+  }
+}