Getting started

Tutorial

Follow this tutorial to grasp the core concepts of Expry and how it has to be used.

Create expry function

The main function of this package is the createExpry function. It receives an object that defines the operations used to map JSON to JavaScript and returns a function.

import { createExpry, Executions } from "@expry/system";

type Operations = {
  concat: {
    params: unknown[];
    return: string;
  };
  gte: {
    params: [unknown, unknown];
    return: boolean;
  };
};

const operations: Executions<Operations> = {
  concat: (args, vars, expry) => {
    const array = args.map((str) => expry(str, vars)) as string[];
    return array.join("");
  },
  gte: (args, vars, expry) => {
    const a = expry(args[0], vars) as number;
    const b = expry(args[1], vars) as number;
    return a >= b;
  },
};

const expry = createExpry<[Operations]>(operations);

The Operations type is used to define the structure of the operations. It defines the type of the parameters and the return type of each operation.

The operations object contains a key for every operation. Every operation is defined as a function with the following parameters:

  • args: The arguments that the operator receives.
  • vars: The variables.
  • expry: The expry function.

Expry function

The expry function accepts a JSON expression and variables, executes the code that is defined with JSON, and returns the result.

const expression: unknown = {
  name: { $concat: ["$name", " ", "$surname"] },
  adult: { $gte: ["$age", 18] },
};

const variables: Record<string, unknown> = {
  name: "John",
  surname: "Doe",
  age: 20,
};

const result = expry(expression, variables);

console.log(result); // { name: "John Doe", adult: true }

The objects that have a single key starting with $ are the operators used to map JSON to JavaScript code. The strings that start with $ are variables.

Variables

The variables parameter of the expry function is optional, but when provided it must be an object containing key-value pairs.

const expression: unknown = {
  $gte: ["$a", "$b"],
};

const variables: Record<string, unknown> = {
  a: 1,
  b: 2,
};

const result = expry(expression, variables);

console.log(result); // false

When a variable is an object, we can access the properties using the dot notation.

const expression: unknown = {
  $gte: ["$numbers.a", "$numbers.b"],
};

const variables: Record<string, unknown> = {
  numbers: { a: 1, b: 2 },
};

const result = expry(expression, variables);

console.log(result); // false

When a variable is an array, we can access the items using the dot notation.

const expression: unknown = {
  $gte: ["$numbers.0", "$numbers.1"],
};

const variables: Record<string, unknown> = {
  numbers: [1, 2],
};

const result = expry(expression, variables);

console.log(result); // false

Escape character

When we want to treat the $ as a normal character in strings and object properties, we have to use the _ character.

const expression: unknown = {
  _$gte: ["_$a", "_$b"],
};

const variables: Record<string, unknown> = {
  a: 1,
  b: 2,
};

const result = expry(expression, variables);

console.log(result); // { $gte: ["$a", "$b"] }

Namespaces

We can organize our operations into groups, each handling a specific set of functions.

import { createExpry, Executions } from "@expry/system";

type StringOperations = {
  concat: {
    params: unknown[];
    return: string;
  };
};

type NumberOperations = {
  add: {
    params: unknown[];
    return: number;
  };
};

const stringOperations: Executions<StringOperations> = {
  concat: (args, vars, expry) => {
    const array = args.map((str) => expry(str, vars)) as string[];
    return array.join("");
  },
};

const numberOperations: Executions<NumberOperations> = {
  add: (args, vars, expry) => {
    const array = args.map((num) => expry(num, vars)) as number[];
    return array.reduce((acc, val) => acc + val, 0);
  },
};

type Operations = [StringOperations, NumberOperations];

const expry = createExpry<Operations>(stringOperations, numberOperations);

Additionally, to avoid naming conflicts among operations across different groups, we can prefix each operator with a group-specific identifier ending with $.

import { createExpry, Executions } from "@expry/system";

type StringOperations = {
  str$concat: {
    params: unknown[];
    return: string;
  };
};

type NumberOperations = {
  num$add: {
    params: unknown[];
    return: number;
  };
};

const stringOperations: Executions<StringOperations> = {
  str$concat: (args, vars, expry) => {
    const array = args.map((str) => expry(str, vars)) as string[];
    return array.join("");
  },
};

const numberOperations: Executions<NumberOperations> = {
  num$add: (args, vars, expry) => {
    const array = args.map((num) => expry(num, vars)) as number[];
    return array.reduce((acc, val) => acc + val, 0);
  },
};

type Operations = [StringOperations, NumberOperations];

const expry = createExpry<Operations>(stringOperations, numberOperations);

Context-scoped variables

The operations that we use can create context-scoped variables. These are variables that only exist within the scope defined by the operation.

To create these type of variables we can do it as you can see here.

import { createExpry, Executions } from "@expry/system";

type Operations = {
  map: {
    params: { input: unknown; as: unknown; in: unknown };
    return: unknown[];
  };
  add: {
    params: unknown[];
    return: unknown;
  };
};

const operations: Executions<Operations> = {
  map(args, vars, expry) {
    const array = expry(args.input, vars) as unknown[];
    const as = expry(args.as, vars) as string;
    return array.map((value) => {
      return expry(args.in, { ...vars, [`$${as}`]: value });
    });
  },
  add: (args, vars, expry) => {
    const array = args.map((num) => expry(num, vars)) as number[];
    return array.reduce((acc, val) => acc + val, 0);
  },
};

const expry = createExpry<[Operations]>(operations);

const expression: unknown = {
  $map: {
    input: [1, 2, 3],
    as: "num",
    in: { $add: ["$$num", 1] },
  },
};

const result = expry(expression);

console.log(result); // [2, 3, 4]

As a convention, these variables should start with $. By doing it this way, these variables will be referenced using two $, and that will help us avoid conflicts with the names of the variables provided externally.

Introduction
Usage