Entities (e)

The Entity Artifact (e)

Filetype:{filename}.e.lua

Entities manage your application’s business data by combining commands (to mutate state), queries (to retrieve state), and events (to track changes).

They use event sourcing under the hood, meaning changes are recorded as a sequence of events, which TENUM® replays to rebuild the entity’s current state.

Usage Sample

The Entity artifact is a core component of the TENUM® platform, responsible for managing and persisting the application state.

They therefore define how data is created, updated, and retrieved. In TENUM®, an entity artifact typically includes commands (to handle changes), events (to store those changes in an event-sourced way), and queries (to retrieve the current state).

Entities encapsulate domain-specific business logic. They form the foundation for modeling data in TENUM® applications, representing real-world or system objects like users, tasks, or products. They usually form the basis for a common language with the business user side of an app pr project.

One big advantage is that entities run both server-side and client-side, enabling real-time, distributed collaboration out of the box. When you call a command, TENUM® applies the related events locally in the browser (optimistically) and then replays those events in the backend—keeping everything in sync automatically.

Let’s look the TENUM® ToDo App**, which uses an entity artifact for a single to-do item:

Sample App: **TENUM®** ToDo App

Sample Module: todo.e.lua

local types = require("tableshape").types
local todoList = require("todo.api.todoList")
local util = require("todo.api.Util")

return {
  autoHashBase = "unique-hash-for-todo-entity",
  commands = {
    create = {
      validator = types.shape{
        id = types.string:is_optional(),
        title = types.string,
        listId = types.string,
      },
      call = function(args, context)
        todoList.commands.addTodo{
          id = args.listId,
          todoId = context.entityId,
        }
        context.events.todoCreated{
          title = util.sanitizeTitle(args.title),
        }
      end,
    },
    delete = {
      validator = types.shape{
        id = types.string,
        listId = types.string,
      },
      call = function(args, context)
        todoList.commands.removeTodo{
          id = args.listId,
          todoId = context.entityId,
        }
        context.events.todoDeleted()
      end,
    },
    toggleComplete = {
      validator = types.shape{
        id = types.string,
      },
      call = function(_, context)
        context.events.todoToggled()
      end,
    },
  },
  events = {
    todoCreated = {
      validator = types.shape{
        title = types.string,
      },
      call = function(event)
        local entity = {}
        entity.title = event.title
        entity.completed = false
        return entity
      end,
    },
    todoDeleted = {
      call = function()
        return nil
      end,
    },
    todoToggled = {
      call = function(_, context)
        local entity = context.entity
        entity.completed = not entity.completed
        return entity
      end,
    },
  },
  queries = {
    getTodo = {
      validator = types.shape{
        id = types.string,
      },
      call = function(_, context)
        return context.entity
      end,
    },
  },
  eventHandlers = {},
}

Here’s what’s happening:

Commands: Define how data changes—like creating or toggling a to-do item.
Events: Store those changes in an event-sourced log. TENUM® replays these events to recreate the entity’s current state at any time.
Queries: Expose read operations for accessing the latest state.

Because TENUM® handles networking, concurrency, and data persistence automatically, you can focus on business rules (e.g., how to add or update a to-do), while the platform synchronizes these changes across users, sessions, and environments.

Best Practices

Define Clear Commands and Events
- Keep your commands focused on a single task and ensure events represent meaningful state changes in your domain.
Use Validators for Commands
- Always validate input data in your commands to prevent invalid state changes and ensure data integrity.
Keep State Immutable
- Treat entity state as immutable within event handlers by returning a new state object rather than mutating the existing one.
Minimize Business Logic in Events
- Perform only necessary state updates in event handlers; delegate complex logic to commands or shared modules.
Write Comprehensive Tests
- Use spec artifacts to test all possible command and query paths, ensuring your entity behaves correctly under various conditions.

Last modified: 28 April 2025