Modules (m)

The Module Artifact (m)

Filetype:{filename}.m.lua

A module is a lightweight way to share reusable code across your TENUM® application. You can require a module in other artifacts such as UI elements, entities and message handlers to avoid duplicating logic in multiple places. Modules are not directly accessible via HTTP and never execute in the browser unless a UI artifact explicitly imports them.

Usage Sample

Modules are a way to share common functionality in your frontend code and backend code.

Let's say you want to validate an email. You probably want to validate an email in your frontend so that clients don't send requests to your backend unnecessarily. But you also want to validate your email on the backend, since you can't really trust that the clients will send you valid data.

This is a use case for a module Artefact. You can create a validateEmail function, and then you can import this module script both in you .uie Artefact and .mh Artefact, and use the same code to validate the email in both places.

Sample App: TENUM ToDo App

Sample Module: Util.m.lua

class MyClass {
    public static void main(String[] args) {
        System.out.println("Hello, World");
    }
}

local export = {}
-- Implement a useful module for the todo app:
-- For example, a utility function to sanitize todo titles

-- Basic Email Validation:
-- 1. Trim leading/trailing whitespace.
-- 2. Match against a simplified pattern.

function export.validateEmail(email)
  if not email then
    return false, "Email is missing."
  end

  -- Trim whitespace
  local trimmed = email:gsub("^%s*(.-)%s*$", "%1")
  
  -- Simple pattern: local-part@domain
  -- You can refine this pattern to match your specific requirements.
  local pattern = xyz
  
  if trimmed:match(pattern) then
    return true, "Valid email."
  else
    return false, "Invalid email format."
  end
end

return export

Best Practices

Keep Modules Focused and Reusable
- Design each module to handle a single, well-defined responsibility (e.g., string manipulation, validation) to promote reuse across your application.
Use Clear and Consistent APIs
- Export well-named functions with clear, consistent input and output structures to make your modules easy to use and integrate.
Avoid Side Effects
- Ensure your module functions are pure wherever possible, meaning they do not modify external state and return consistent outputs for the same inputs.
Document Your Functions
- Provide inline documentation for each function to explain its purpose, parameters, and return values, making it easy for other developers to understand.
Share Logic Across Artifacts
- Use modules to share common logic between UI elements, entities, and message handlers, reducing duplication and ensuring consistency.
Version and Maintain
- Regularly review and version your modules as your project evolves, ensuring backward compatibility and clear version management within your package.json.

Last modified: 07 April 2025