Using XLRs

SDK Initialization

To start using the XLR SDK you’ll need to install the SDK package

npm

npm i @xlr-lib/xlr-sdk

yarn

yarn add @xlr-lib/xlr-sdk

pnpm

pnpm add @xlr-lib/xlr-sdk

Next, import the SDK

import { XLRSDK } from "@xlr-lib/xlr-sdk"

If you want to implement a custom object store, also import the XLRRegistry interface and have your custom registry implement it.

Lastly, just initialize an instance of it.

import { XLRSDK } from "@xlr-lib/xlr-sdk"

const sdk = new XLRSDK();

or if you want to use your custom registry, just pass it in to the initializer.

import { XLRSDK } from "@xlr-lib/xlr-sdk"
import { customRegistry } from "./customRegistry"

const sdk = new XLRSDK(customRegistry);

Loading Types into the SDK

If you want to load XLR types from disk, you can use the loadDefinitionsFromDisk function and pass it the path to parent folder of the xlr directory.

const sdk = new XLRSDK();
sdk.loadDefinitionsFromDisk('./common/static_xlrs/core');

If you want to load XLR types from a module, you can use the loadDefinitionsFromModule function and pass it the module to load from.

const sdk = new XLRSDK();
sdk.loadDefinitionsFromModule(require("@player-ui/reference-assets-plugin").path);

Both functions also accept an optional Filters object (second argument) and a list of TransformFunctions (third argument), covered below.

Filtering

Both loading functions accept a Filters object as their second argument to exclude plugins/capabilities/types you don’t want loaded:

const sdk = new XLRSDK();
sdk.loadDefinitionsFromDisk('./common/static_xlrs/core', {
  typeFilter: /^Internal/,
});

See Filters for the full shape, and importantly, the caution about how matches are treated as exclusions rather than selections.

Registering Persistent Transforms

Beyond passing one-off transforms to a single load call, addTransformFunction(name, fn) registers a transform that runs on every future load until removed with removeTransformFunction(name). See Transform Functions for the mechanism and an example.

Usage

After the types are loaded into the SDK there are a couple ways to interact with them.

Type Recall

To get a type back you can use the getType function and pass the name of the type you want to retrieve. You can also use the hasType function to check to see if the type exists before you try and access it.

const sdk = new XLRSDK();
if(sdk.hasType("InputAsset")){
  return sdk.getType("InputAsset")
} else {
  throw new Error("Oh no!")
}

getType also accepts a second options argument:

interface GetTypeOptions {
  getRawType?: boolean;
  optimize?: boolean;
}

• getRawType: true returns the type exactly as it was registered, with extends left unresolved.
• Otherwise, extends chains are always merged into the type before it’s returned.
• optimize additionally resolves conditional types, computes the effective type of unions/intersections, resolves ref nodes, and fills in remaining generics with their defaults.

Caution

Omitting options entirely is not the same as passing {}. Because of a default parameter internal to the SDK, calling getType(id) with no options behaves the same as getType(id, {optimize: true}), returning the fully resolved type. If you only want extends merged and nothing else, you have to explicitly pass {optimize: false}.

Listing & Inspecting Types

listTypes(filters?) returns every currently-loaded type (optionally narrowed with a Filters object), and getTypeInfo(id) returns where a given type came from:

const sdk = new XLRSDK();
sdk.listTypes({ capabilityFilter: /Internal/ }); // every loaded type except the Internal capability

sdk.getTypeInfo("InputAsset"); // { plugin: "...", capability: "Assets" } | undefined

Type Validation

To validate if some JSON content matches the expected type, you can use the validateByName function. You will need to supply a Node from the jsonc-parser library.

import { parseTree } from 'jsonc-parser';
import { XLRSDK } from '@xlr-lib/xlr-sdk'

const sdk = new XLRSDK();

///... Loading XLRs

const mockAsset = parseTree(`
    {
      "id": 1,
      "type": "input",
      "binding": "some.data",
      "label": {
        "asset": {
          "value": "{{input.label}}"
        }
      }
    }
    `);

return sdk.validateByName('InputAsset', mockAsset)

If you already have a NodeType in hand rather than a registered type name, for example one produced by a transform, use the sibling validateByType(type, rootNode) instead.