Decorators (d)

The Decorator Artifact (d)

Filetype:{filename}.api.d.lua

A decorator is a specialized Lua file that intercepts calls to other TENUM® artifacts before or after they are executed.

By inserting itself into the request pipeline, it can transform the inputs/outputs, enforce additional rules, or halt the request under certain conditions. This allows you to separate cross-cutting concerns—such as logging, authentication, or metrics—from your main application code, keeping everything organized and maintainable.

Usage Sample

Decorators shine when you need to handle tasks that cut across multiple artifacts. For instance, you may need to log all incoming requests to your message handlers or restrict access to certain commands in your entities. Here’s a simple example of a logging decorator:

Sample App: **TENUM®** ToDo App

Sample Decorator: ApiLoggingDecorator.api.d.lua

local export = {}

function export.handle(props)
  -- Print the type of message being called
  print("Decorator Log:", props.metaMessage, props.message)

  -- Continue with the default behavior by calling the 'next' function
  return props.next(props.metaMessage, props.message)
end

return export

props.metaMessage holds the identifier of the targeted artifact or function.
props.message contains the arguments passed to the artifact.
props.next(...) continues the normal execution flow if the decorator does not halt it.

In this example, every time a request or event call hits the decorated artifact, the decorator prints a simple log message, then continues on.

Best Practices

Single Responsibility
- Keep your decorator focused on a single cross-cutting concern, such as logging, authentication, or input transformation. This makes it easier to understand, test, and maintain.
Minimal Business Logic
- Avoid placing complex domain logic in a decorator. Instead, use it to enforce policies or perform ancillary tasks so your main artifacts remain uncluttered.
Non-Destructive Interception
- A good decorator should pass through the original props.message or safely wrap modifications. If you change or filter fields, ensure the next artifact receives valid, expected data.
Graceful Error Handling
- If a decorator detects a problem (e.g., missing auth credentials), it can interrupt the call by throwing an error or returning a suitable response. Provide clear messages to ease debugging.
Chain Decorators
- TENUM® supports multiple decorators on the same artifact. When stacking them, consider their order and ensure they work together without creating conflicts or redundant checks.
Limit Side Effects
- Write decorators to be as pure as possible—do not alter global state, or at least keep side effects minimal. This improves predictability when multiple decorators or artifacts run concurrently.
Use Consistent Naming
- Adopt clear naming conventions (e.g., ApiLoggingDecorator.api.d.lua, AuthDecorator.api.d.lua), so other developers can quickly identify the role of each decorator file.
Document Configuration
- If your decorator requires setup (like environment variables for an external logging service), be sure to document any configuration steps in a README or inline comments.

Last modified: 11 April 2025