TMPLTR

Documentation

API

Overview

This page documents the public API of the core runtime and ORM used by the demo application. The example server implementation is server.mjs (example only). Primary implementations to integrate with are src/app.mjs and src/orm.mjs.

App (src/app.mjs)

`App` is a lightweight HTTP application class that provides routing, template rendering and request/response helpers.

• Constructor:

          
          new App(host, port, templateDir)
          // defaults: host='localhost', port=3000, templateDir='templates'
          
        

• Properties:

  host

  Server hostname (string).

  port

  Server port (number).

  templateDir

  Directory for templates (string).

  globals

  Global template variables (object).

  session

  Protected session store — use session.setValue / session.getValue.

  staticPath

  URL prefix for static files (default /static/).

  routes

  Registered route handlers (object).

  statusPages

  Custom templates for status codes (object).

• Routing: use route(routePath, callback) to register handlers. Route templates may include parameters using <> (e.g. /posts/<id>/).
• Lifecycle hooks: beforeRequest(callback) and beforeResponse(callback) — callbacks run before request processing and before final response.
• Request/response handler: Handlers receive request, responseContext, and params. The responseContext object exposes helper methods:

  setStatus(code)

  Set HTTP status code for the response.

  addHeader(key, value)

  Add a header to the response.

  setContentType(type)

  Set the Content-Type header for the response.

  send404(context)

  Return the configured 404 template content (if configured) and set status 404.

  sendFileFromDir(path)

  Read a file from disk and set an appropriate content type.

  redirect(url, status=302)

  Set redirect Location header and status code.

• Body parsing: For POST requests the framework parses application/x-www-form-urlencoded into request.form, and basic multipart/form-data into request.form and request.files (files include filename, contentType, and data Buffer).
• Session: `App` manages an internal protected session object. Use session.setValue(key, value, request) and session.getValue(key, request) to store per-client session data. Client identity is tracked with cookie `tmpltr-session`.
• Template rendering: renderTemplate(fileName, context, modifications) — supports a minimal templating workflow used by the demo (extends, blocks, conditionals, context replacement and simple modifications). Template files are resolved relative to `templateDir`.
• Server control: serve() — start listening; requestListener and processRequest(request,response) power the HTTP handling.

Quick example

      
        const app = new App('localhost', 3000, 'demo/templates');

        app.route('/hello/', (req, res) => {
          res.setContentType('text/html');
          return app.renderTemplate('index.html', { name: 'World' });
        });

        app.serve();
      
    

ORM (src/orm.mjs)

`DbObject` is a minimal active-record style base class for SQLite (uses node:sqlite DatabaseSync). Subclasses must declare static tableName and fieldNames (array of field names) to map query results to instances.

• DbObject API:

  ResultError

  Error subclass for ORM-specific errors.

  DbObject.setDb(path)

  Initialize the shared DatabaseSync instance at path.

  DbObject.database

  Getter for the configured database instance.

  constructor(results)

  Map query result columns to instance fields defined in fieldNames.

  props(includeUndefined=true)

  Return an object containing the instance's fields; omits undefined when false.

  static getAll()

  Return all rows as instances.

  static getByFilter(filter, config)

  Flexible query builder; supports operators via double-underscore suffixes (e.g. field__lte, field__in).

  static first(filter, config)

  Return the first matching row.

  static create(item)

  Insert a new record and return the created instance.

  save()

  Update when id exists; otherwise insert and return the persisted instance.

  delete()

  Delete the instance from the database (requires id).

ORM example

      
        DbObject.setDb('./data/db.sqlite');

        class User extends DbObject {
          User.tableName = 'users';
          User.fieldNames = ['id','firstName','lastName','email'];
        }

        const u = User.create({ firstName: 'Sam', lastName: 'Smith', email: 's@e' });
        const found = User.getByFilter({ firstName: 'Sam' });
        u.email = 'sam@example.com';
        u.save();
      
    

For production usage, ensure proper SQL schema creation and consider prepared statements and transactional safety. The ORM is intentionally small and synchronous for simplicity.