@player-tools/dsl 0.11.0 → 0.12.1--canary.213.4811

package/src/string-templates/index.ts

@@ -22,9 +22,11 @@ export interface TemplateInstanceRefStringOptions {
   ) => string;
 }
 
-const OpaqueIdentifier = Symbol("TemplateStringType");
+const OpaqueIdentifier: unique symbol = Symbol("TemplateStringType");
 
-export type TemplateStringType = React.ReactElement & {
+export type TemplateStringType<
+  T extends string | number | boolean | unknown = any,
+> = React.ReactElement & {
   /** An identifier to show that this is a template type */
   [OpaqueIdentifier]: true;
   /** The value of the template string when in another string */
@@ -32,15 +34,21 @@ export type TemplateStringType = React.ReactElement & {
   /** the raw value of the template string */
   toValue: () => string;
   /** the dereferenced value when used in another */
-  toRefString: (options?: TemplateRefStringOptions) => string;
+  toRefString: (options?: TemplateRefStringOptions) => T;
+  /** Underlying type of this binding */
+  type: T;
 };
 
-export type BindingTemplateInstance = TemplateStringType & {
+export type BindingTemplateInstance<
+  DataType extends string | number | boolean | unknown = any,
+> = TemplateStringType<DataType> & {
   /** An identifier for a binding instance */
   __type: "binding";
 };
 
-export type ExpressionTemplateInstance = TemplateStringType & {
+export type ExpressionTemplateInstance<
+  ReturnType extends string | number | boolean | unknown = any,
+> = TemplateStringType<ReturnType> & {
   /** The identifier for an expression instance */
   __type: "expression";
 };
@@ -49,7 +57,9 @@ export type ExpressionTemplateInstance = TemplateStringType & {
 export const TemplateStringComponent = (props: {
   /** The string value of the child template string */
   value: string;
-}) => {
+}): React.ReactElement<{
+  value: string;
+}> => {
   return React.createElement(
     "value",
     {
@@ -179,10 +189,10 @@ const createExpressionTemplateInstance = (
 };
 
 /** A tagged-template constructor for a binding  */
-export const binding = (
+export const binding = <T>(
   strings: TemplateStringsArray,
   ...nested: Array<TemplateStringType | string>
-): BindingTemplateInstance => {
+): BindingTemplateInstance<T> => {
   return createBindingTemplateInstance({
     strings,
     other: nested,
@@ -191,12 +201,12 @@ export const binding = (
 };
 
 /** A tagged-template constructor for an expression */
-export const expression = (
+export const expression = <T>(
   strings: TemplateStringsArray,
   ...nested: Array<
     ExpressionTemplateInstance | BindingTemplateInstance | string
   >
-): ExpressionTemplateInstance => {
+): ExpressionTemplateInstance<T> => {
   return createExpressionTemplateInstance({
     strings,
     other: nested,

package/src/types.ts

@@ -9,6 +9,7 @@ import type {
   BindingTemplateInstance,
   ExpressionTemplateInstance,
 } from "./string-templates";
+import { ExpressionHandler } from "@player-ui/player";
 
 export type WithChildren<T = Record<string, unknown>> = T & {
   /** child nodes */
@@ -56,12 +57,21 @@ export type SwapKeysToType<T, K extends keyof T, NewType> = {
   [P in keyof T]: P extends K ? NewType : T[P];
 };
 
+/**
+ * Note: have to explicitly handle boolean cases, otherwise boolean gets distributed to
+ * the union as true | false breaking the mapping.
+ */
 export type WithTemplateTypes<T> =
   T extends Record<any, any>
     ? {
         [P in keyof T]: WithTemplateTypes<T[P]>;
       }
-    : T | BindingTemplateInstance | ExpressionTemplateInstance;
+    : T extends boolean
+      ?
+          | boolean
+          | BindingTemplateInstance<boolean>
+          | ExpressionTemplateInstance<boolean>
+      : T | BindingTemplateInstance<T> | ExpressionTemplateInstance<T>;
 
 type ValidKeys = "exp" | "onStart" | "onEnd";
 
@@ -115,6 +125,10 @@ export type DataTypeRefs<
   [Property in Extract<keyof DataTypeObjects, string> as `${Property}Ref`]: {
     /** DataType name */
     type: Property;
+
+    default?: DataTypeObjects[Property] extends Schema.DataType<infer BaseType>
+      ? BaseType
+      : unknown;
   };
 };
 
@@ -149,3 +163,15 @@ export interface DSLSchema<DataTypeRef = DataTypeReference> {
     | [DSLSchema<DataTypeRef>]
     | DSLSchema<DataTypeRef>;
 }
+
+type ExpressionHandlerToFunction<T extends ExpressionHandler> =
+  T extends ExpressionHandler<infer A, infer B>
+    ? (...args: WithTemplateTypes<A>) => ExpressionTemplateInstance<B>
+    : undefined;
+
+export type ExpressionArray<T> =
+  T extends Record<any, any>
+    ? {
+        [P in keyof T]: ExpressionHandlerToFunction<T[P]>;
+      }
+    : undefined;

package/src/utils.tsx

@@ -1,9 +1,17 @@
 import * as React from "react";
 import {
+  expression,
+  ExpressionTemplateInstance,
   isTemplateStringInstance,
   TemplateStringComponent,
 } from "./string-templates";
-import type { toJsonOptions } from "./types";
+import type {
+  ExpressionArray,
+  toJsonOptions,
+  WithTemplateTypes,
+} from "./types";
+import { Schema } from "@player-ui/types";
+import { ExpressionHandler } from "@player-ui/player";
 
 /** Get an array version of the value */
 export function toArray<T>(val: T | Array<T>): Array<T> {
@@ -57,7 +65,7 @@ export function toJsonElement(
 export function toJsonProperties(
   value: Record<string, any>,
   options: toJsonOptions = { propertiesToSkip: ["applicability"] },
-) {
+): React.JSX.Element[] {
   return Object.keys(value).map((key) => {
     return (
       <property key={key} name={key}>
@@ -106,7 +114,7 @@ export function normalizeToCollection(options: {
 
   /** A collection asset */
   CollectionComp?: React.ComponentType<any>;
-}) {
+}): React.ReactNode {
   const { node, CollectionComp } = options;
 
   if (
@@ -167,11 +175,17 @@ export function mergeRefs<T = any>(
   };
 }
 
+type TypesToReferences<T> = {
+  [P in keyof T]: T[P] extends Schema.DataType<infer DT> ? DT : unknown;
+};
+
 /** Generates object reference properties from the provided object */
 export function getObjectReferences<
-  OriginalPropertiesObject extends Record<string, unknown>,
-  ReferencesPropertyObject extends Record<string, unknown>,
->(propertiesObject: OriginalPropertiesObject): ReferencesPropertyObject {
+  OriginalPropertiesObject,
+  ReferencesPropertyObject,
+>(
+  propertiesObject: OriginalPropertiesObject,
+): TypesToReferences<ReferencesPropertyObject> {
   const result: any = {};
 
   for (const itemProp in propertiesObject) {
@@ -183,3 +197,63 @@ export function getObjectReferences<
 
   return result;
 }
+
+function parseArg(arg: unknown, deref = false): any {
+  if (isTemplateStringInstance(arg)) {
+    return `'${deref ? arg.toRefString() : arg.toValue()}'`;
+  } else if (Array.isArray(arg)) {
+    return `[${arg.map((a) => parseArg(a, true)).join(", ")}]`;
+  } else if (typeof arg === "string") {
+    return `'${arg}'`;
+  } else {
+    return arg;
+  }
+}
+
+function generateDSLFunction<R>(
+  name: string,
+  args: Array<unknown>,
+): ExpressionTemplateInstance<R> {
+  const expressionArgs: Array<unknown> = [];
+  args.forEach((arg) => {
+    expressionArgs.push(parseArg(arg));
+  });
+
+  return expression`${name}(${expressionArgs.join(", ")})`;
+}
+
+/**
+ * Convert an single ExpressionHandler function to a DSL expression function
+ */
+export function wrapFunctionInType<T extends Array<unknown>, R>(
+  fn: ExpressionHandler<T, R>,
+): (...args: WithTemplateTypes<T>) => ExpressionTemplateInstance<R> {
+  return (...args: WithTemplateTypes<T>): ExpressionTemplateInstance<R> => {
+    return generateDSLFunction(fn.name, args);
+  };
+}
+
+/**
+ * Create a DSL Expression generation function by name and args specified by
+ * generic parameters
+ */
+export function makeFunctionByName<T extends Array<unknown>, R>(
+  name: string,
+): (...args: WithTemplateTypes<T>) => ExpressionTemplateInstance<R> {
+  return (...args: WithTemplateTypes<T>): ExpressionTemplateInstance<R> => {
+    return generateDSLFunction(name, args);
+  };
+}
+
+/**
+ * Takes map of functions and wraps them in a DSL syntax generator
+ */
+export function mapExpressionHandlersToFunctions<
+  T extends Record<string, ExpressionHandler<any, any>>,
+>(functions: T): ExpressionArray<T> {
+  const result: any = {};
+  for (const fn of Object.values(functions)) {
+    result[fn.name] = wrapFunctionInType(fn);
+  }
+  return result;
+}

package/types/compiler/schema.d.ts

@@ -12,7 +12,10 @@ export declare class SchemaGenerator {
     private generatedDataTypes;
     private logger;
     hooks: {
-        createSchemaNode: SyncWaterfallHook<[node: Schema.DataType<unknown>, originalProperty: Record<string | symbol, unknown>], Record<string, any>>;
+        createSchemaNode: SyncWaterfallHook<[
+            node: Schema.DataType<unknown>,
+            originalProperty: Record<string | symbol, unknown>
+        ], Record<string, any>>;
     };
     constructor(logger?: LoggingInterface);
     /**
@@ -41,7 +44,7 @@ export type MakeArrayIntoIndexRef<T extends any[]> = {
 } & BindingTemplateInstance;
 export type MakeBindingRefable<T> = {
     [P in keyof T]: T[P] extends object[] ? MakeArrayIntoIndexRef<T[P]> : T[P] extends unknown[] ? T[P] : MakeBindingRefable<T[P]>;
-} & BindingTemplateInstance;
+} & BindingTemplateInstance<T>;
 /**
  * Adds bindings to an object so that the object can be directly used in JSX
  */

package/types/expressions/native.d.ts

@@ -0,0 +1,50 @@
+import { BindingTemplateInstance, ExpressionTemplateInstance } from "..";
+type Argument<T> = string | boolean | number | undefined | BindingTemplateInstance<T> | ExpressionTemplateInstance<T>;
+/**
+ * Performs an assigment of a value to a binding by returning the expression
+ * {{<binding>}} = <value>
+ * @param binding
+ * @param value
+ */
+export declare const assign: <T>(binding: BindingTemplateInstance<any>, value: Argument<T>) => ExpressionTemplateInstance<void>;
+/**
+ * Returns an equality comparison between the two values
+ */
+export declare const equals: <A, B>(a: Argument<A>, b: Argument<B>) => ExpressionTemplateInstance<boolean>;
+/**
+ * Returns the negated version of the binding/expression
+ * by returning !(<value>)
+ * @param binding Binding/Expression to invert
+ * @returns Negated binding/expression
+ */
+export declare const not: (value: BindingTemplateInstance<boolean> | ExpressionTemplateInstance<boolean>) => ExpressionTemplateInstance<boolean>;
+/**
+ * Creates an expression for the logical or'ing of the provided values
+ * e.g: <exp1> || <exp2> || ...
+ * @param values Array of bindings/expressions to logically or
+ * @returns boolean
+ */
+export declare const or: (...values: Array<BindingTemplateInstance<boolean> | ExpressionTemplateInstance<boolean>>) => ExpressionTemplateInstance<boolean>;
+/**
+ * Creates an expression for the logical nor'ing of the provided values
+ * e.g: !(<exp1> || <exp2> || ...)
+ * @param values Array of bindings/expressions to logically nor
+ * @returns boolean
+ */
+export declare const nor: (...values: Array<BindingTemplateInstance<boolean> | ExpressionTemplateInstance<boolean>>) => ExpressionTemplateInstance<boolean>;
+/**
+ * Creates an expression for the logical and'ing of the provided values
+ * e.g: <exp1> && <exp2> && ...
+ * @param values Array of bindings/expressions to logically and
+ * @returns boolean
+ */
+export declare const and: (...values: Array<BindingTemplateInstance<boolean> | ExpressionTemplateInstance<boolean>>) => ExpressionTemplateInstance<boolean>;
+/**
+ * Creates an expression for the logical nand'ing of the provided values
+ * e.g: !(<exp1> && <exp2> && ...)
+ * @param values Array of bindings/expressions to logically nand
+ * @returns boolean
+ */
+export declare const nand: (...values: Array<BindingTemplateInstance<boolean> | ExpressionTemplateInstance<boolean>>) => ExpressionTemplateInstance<boolean>;
+export {};
+//# sourceMappingURL=native.d.ts.map

package/types/expressions/testing.d.ts

@@ -0,0 +1,13 @@
+import { ExpressionHandler } from "@player-ui/player";
+import { ExpressionTemplateInstance } from "../string-templates";
+/**
+ * Test harness to make testing expressions easier.
+ * Given an expreesion and an initial data model the harness will execute the expression
+ * on and return the new state of the data model.
+ * @param exp expression to execute
+ * @param initialData data model to operate on
+ * @param expressions expression handlers for functions that are called
+ * @returns Final data model state
+ */
+export declare function testExpression(exp: ExpressionTemplateInstance, initialData: object, expressions?: Map<string, ExpressionHandler<any[], any>>): object;
+//# sourceMappingURL=testing.d.ts.map

package/types/index.d.ts

@@ -9,4 +9,5 @@ export * from "react-json-reconciler";
 export * from "./compiler/schema";
 export * from "./compiler";
 export * from "./compiler/types";
+export * from "./expressions/native";
 //# sourceMappingURL=index.d.ts.map

package/types/string-templates/index.d.ts

@@ -15,7 +15,7 @@ export interface TemplateInstanceRefStringOptions {
     toRefString: (options: TemplateRefStringOptions | undefined, value: string) => string;
 }
 declare const OpaqueIdentifier: unique symbol;
-export type TemplateStringType = React.ReactElement & {
+export type TemplateStringType<T extends string | number | boolean | unknown = any> = React.ReactElement & {
     /** An identifier to show that this is a template type */
     [OpaqueIdentifier]: true;
     /** The value of the template string when in another string */
@@ -23,13 +23,15 @@ export type TemplateStringType = React.ReactElement & {
     /** the raw value of the template string */
     toValue: () => string;
     /** the dereferenced value when used in another */
-    toRefString: (options?: TemplateRefStringOptions) => string;
+    toRefString: (options?: TemplateRefStringOptions) => T;
+    /** Underlying type of this binding */
+    type: T;
 };
-export type BindingTemplateInstance = TemplateStringType & {
+export type BindingTemplateInstance<DataType extends string | number | boolean | unknown = any> = TemplateStringType<DataType> & {
     /** An identifier for a binding instance */
     __type: "binding";
 };
-export type ExpressionTemplateInstance = TemplateStringType & {
+export type ExpressionTemplateInstance<ReturnType extends string | number | boolean | unknown = any> = TemplateStringType<ReturnType> & {
     /** The identifier for an expression instance */
     __type: "expression";
 };
@@ -39,11 +41,11 @@ export declare const TemplateStringComponent: (props: {
     value: string;
 }) => React.ReactElement<{
     value: string;
-}, string | React.JSXElementConstructor<any>>;
+}>;
 /** A tagged-template constructor for a binding  */
-export declare const binding: (strings: TemplateStringsArray, ...nested: Array<TemplateStringType | string>) => BindingTemplateInstance;
+export declare const binding: <T>(strings: TemplateStringsArray, ...nested: Array<TemplateStringType | string>) => BindingTemplateInstance<T>;
 /** A tagged-template constructor for an expression */
-export declare const expression: (strings: TemplateStringsArray, ...nested: Array<ExpressionTemplateInstance | BindingTemplateInstance | string>) => ExpressionTemplateInstance;
+export declare const expression: <T>(strings: TemplateStringsArray, ...nested: Array<ExpressionTemplateInstance | BindingTemplateInstance | string>) => ExpressionTemplateInstance<T>;
 /** Check if a value is a template string */
 export declare const isTemplateStringInstance: (val: unknown) => val is ExpressionTemplateInstance | BindingTemplateInstance;
 /** Check if a value is a binding */

package/types/types.d.ts

@@ -1,5 +1,6 @@
 import type { Asset, Expression, Navigation as PlayerNav, Schema, Validation } from "@player-ui/types";
 import type { BindingTemplateInstance, ExpressionTemplateInstance } from "./string-templates";
+import { ExpressionHandler } from "@player-ui/player";
 export type WithChildren<T = Record<string, unknown>> = T & {
     /** child nodes */
     children?: React.ReactNode;
@@ -24,9 +25,13 @@ export type AssetPropsWithChildren<T extends Asset> = WithChildren<WithTemplateT
 export type SwapKeysToType<T, K extends keyof T, NewType> = {
     [P in keyof T]: P extends K ? NewType : T[P];
 };
+/**
+ * Note: have to explicitly handle boolean cases, otherwise boolean gets distributed to
+ * the union as true | false breaking the mapping.
+ */
 export type WithTemplateTypes<T> = T extends Record<any, any> ? {
     [P in keyof T]: WithTemplateTypes<T[P]>;
-} : T | BindingTemplateInstance | ExpressionTemplateInstance;
+} : T extends boolean ? boolean | BindingTemplateInstance<boolean> | ExpressionTemplateInstance<boolean> : T | BindingTemplateInstance<T> | ExpressionTemplateInstance<T>;
 type ValidKeys = "exp" | "onStart" | "onEnd";
 type DeepReplace<T, Old, New> = {
     [P in keyof T]: T[P] extends Old ? P extends ValidKeys ? New : DeepReplace<T[P], Old, New> : T[P] extends (infer R)[] ? DeepReplace<R, Old, New>[] : T[P] extends object ? DeepReplace<T[P], Old, New> : Extract<T[P], Old> extends Old ? DeepReplace<Extract<T[P], object>, Old, New> | Exclude<T[P], Old | object> | New : T[P];
@@ -47,6 +52,7 @@ export type DataTypeRefs<DataTypeObjects extends Record<string, Schema.DataType>
     [Property in Extract<keyof DataTypeObjects, string> as `${Property}Ref`]: {
         /** DataType name */
         type: Property;
+        default?: DataTypeObjects[Property] extends Schema.DataType<infer BaseType> ? BaseType : unknown;
     };
 };
 export type ValidatorFunctionRefs<ValidatorObjects extends {
@@ -70,5 +76,9 @@ export type DataTypeReference<DataTypeProp = {
 export interface DSLSchema<DataTypeRef = DataTypeReference> {
     [key: string]: [DataTypeRef] | DataTypeRef | [DSLSchema<DataTypeRef>] | DSLSchema<DataTypeRef>;
 }
+type ExpressionHandlerToFunction<T extends ExpressionHandler> = T extends ExpressionHandler<infer A, infer B> ? (...args: WithTemplateTypes<A>) => ExpressionTemplateInstance<B> : undefined;
+export type ExpressionArray<T> = T extends Record<any, any> ? {
+    [P in keyof T]: ExpressionHandlerToFunction<T[P]>;
+} : undefined;
 export {};
 //# sourceMappingURL=types.d.ts.map

package/types/utils.d.ts

@@ -1,5 +1,8 @@
 import * as React from "react";
-import type { toJsonOptions } from "./types";
+import { ExpressionTemplateInstance } from "./string-templates";
+import type { ExpressionArray, toJsonOptions, WithTemplateTypes } from "./types";
+import { Schema } from "@player-ui/types";
+import { ExpressionHandler } from "@player-ui/player";
 /** Get an array version of the value */
 export declare function toArray<T>(val: T | Array<T>): Array<T>;
 /** Create a component version  */
@@ -21,7 +24,7 @@ export declare function normalizeToCollection(options: {
     TextComp?: React.ComponentType;
     /** A collection asset */
     CollectionComp?: React.ComponentType<any>;
-}): string | number | boolean | Iterable<React.ReactNode> | React.JSX.Element | null | undefined;
+}): React.ReactNode;
 type ReactChildArray = ReturnType<typeof React.Children.toArray>;
 /**
  *
@@ -35,7 +38,23 @@ export declare function flattenChildren(children: React.ReactNode): ReactChildAr
  * used in an esm environment
  */
 export declare function mergeRefs<T = any>(refs: Array<React.MutableRefObject<T> | React.LegacyRef<T> | undefined | null>): React.RefCallback<T>;
+type TypesToReferences<T> = {
+    [P in keyof T]: T[P] extends Schema.DataType<infer DT> ? DT : unknown;
+};
 /** Generates object reference properties from the provided object */
-export declare function getObjectReferences<OriginalPropertiesObject extends Record<string, unknown>, ReferencesPropertyObject extends Record<string, unknown>>(propertiesObject: OriginalPropertiesObject): ReferencesPropertyObject;
+export declare function getObjectReferences<OriginalPropertiesObject, ReferencesPropertyObject>(propertiesObject: OriginalPropertiesObject): TypesToReferences<ReferencesPropertyObject>;
+/**
+ * Convert an single ExpressionHandler function to a DSL expression function
+ */
+export declare function wrapFunctionInType<T extends Array<unknown>, R>(fn: ExpressionHandler<T, R>): (...args: WithTemplateTypes<T>) => ExpressionTemplateInstance<R>;
+/**
+ * Create a DSL Expression generation function by name and args specified by
+ * generic parameters
+ */
+export declare function makeFunctionByName<T extends Array<unknown>, R>(name: string): (...args: WithTemplateTypes<T>) => ExpressionTemplateInstance<R>;
+/**
+ * Takes map of functions and wraps them in a DSL syntax generator
+ */
+export declare function mapExpressionHandlersToFunctions<T extends Record<string, ExpressionHandler<any, any>>>(functions: T): ExpressionArray<T>;
 export {};
 //# sourceMappingURL=utils.d.ts.map