Interpreter store

An interpreter store is responsible for filling entities values based on a schema and builder definition.

Creating an interpreter store

The createInterpreterStore method is utilized to create an interpreter store based on one of your custom builders and a schema.

In most cases, you won't need to use the createInterpreterStore method directly. Instead, you will mostly utilize useInterpreterStore from @coltorapps/builder-react, which essentially creates the interpreter store for you.

This store is equipped to handle tasks such as setting entities values and performing validation of entities values.

import { createInterpreterStore } from "@coltorapps/builder";

import { formBuilder } from "./form-builder";

const formSchema = {
  entities: {
    "51324b32-adc3-4d17-a90e-66b5453935bd": {
      type: "textField",
      attributes: {
        label: "First name",
      },
    },
  },
  root: ["51324b32-adc3-4d17-a90e-66b5453935bd"],
};

const formInterpreterStore = createInterpreterStore(formBuilder, formSchema);

In the example above, we've hardcoded the schema, but typically, you would retrieve it from a database, for instance.

Now, we can start interacting with the store.

formInterpreterStore.setEntityValue(
  "51324b32-adc3-4d17-a90e-66b5453935bd",
  "Alex",
);

void formInterpreterStore.validateEntities();

We have the ability to access the values of the entities:

formInterpreterStore.getEntitiesValues();

This will be equivalent to:

{
  "51324b32-adc3-4d17-a90e-66b5453935bd": "Alex"
}

Subscribing to changes

An interpreter store offers a subscribe method that facilitates subscribing to data changes. With each change, you'll receive both the updated data and an array of events that specify what modifications have occurred.

const unsubscribe = formInterpreterStore.subscribe((data, events) => {
  events.forEach((event) => {
    if (event.name === "EntityValueUpdated") {
      console.log(
        "An entity value was updated.",
        event.payload.entityId,
        event.payload.value,
      );
    }
  });
});

Data breakdown

You can access an interpreter store's data using the getData method. Example:

formInterpreterStore.getData();

This will produce an output similar to:

{
  "entitiesValues": {
    "51324b32-adc3-4d17-a90e-66b5453935bd": "Alex"
  },
  "entitiesErrors": {
    "51324b32-adc3-4d17-a90e-66b5453935bd": "Username taken"
  }
}

• entitiesValues: Represents the values of entities. It can be mutated by interpreter store methods such as setEntityValue, resetEntityValue, resetEntitiesValues, clearEntityValue, and clearEntitiesValues.

• entitiesErrors: Represents validation errors for various entities. It can be mutated by interpreter store methods such as validateEntityValue, validateEntitiesValues, setEntityError, resetEntityError, resetEntitiesErrors, and setEntitiesErrors.

Initial data

You can create an interpreter store with initial entities values and entities errors.

import { createBuilderStore } from "@coltorapps/builder";

import { formBuilder } from "./form-builder";

const formInterpreterStore = createInterpreterStore(
  formBuilder,
  {
    entities: {
      "51324b32-adc3-4d17-a90e-66b5453935bd": {
        type: "textField",
        attributes: {
          label: "First name",
        },
      },
    },
    root: ["51324b32-adc3-4d17-a90e-66b5453935bd"],
  },
  {
    initialData: {
      entitiesValues: {
        "51324b32-adc3-4d17-a90e-66b5453935bd": "Alex",
      },
      entitiesErrors: {
        "51324b32-adc3-4d17-a90e-66b5453935bd": "Must be Alexandru",
      },
    },
  },
);

Default entities values

Entities values will be automatically populated with their default values during interpreter store initialization if their entity definitions have the defaultValue method set.

To opt out of this behavior and prevent automatic default value assignment, you can set the initialEntitiesValuesWithDefaults flag to false.

import { createInterpreterStore } from "@coltorapps/builder";

import { formBuilder } from "./form-builder";

const formInterpreterStore = createInterpreterStore(
  formBuilder,
  {
    entities: {
      "51324b32-adc3-4d17-a90e-66b5453935bd": {
        type: "textField",
        attributes: {
          label: "First name",
        },
      },
    },
    root: ["51324b32-adc3-4d17-a90e-66b5453935bd"],
  },
  {
    initialEntitiesValuesWithDefaults: false,
  },
);