TeqFW: Core

Publication date: 2021-06-25

A Teq application is first a Node.js application and then a modular application composed of Teq plugins, which are npm modules. The platform core has three jobs: start the application and its console commands, discover and attach plugins, and establish the foundational architecture.

Bootstrap

The application entry point is bin/tequila.mjs. It finds the application root, loads the DI container, maps core sources, creates the bootstrap configuration, obtains TeqFw_Core_Back_App$, initializes it, and runs it. The script belongs to the application but is intentionally almost identical from one Teq application to another.

import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import teq from '@teqfw/core';

const root = join(dirname(fileURLToPath(import.meta.url)), '..');
teq({ path: root }).catch(console.error);

Different behaviour comes from the installed plugins and the commands they contribute, not from rewriting the launcher.

Core application lifecycle

During initialization, TeqFw_Core_Back_App:

initializes logging;
loads local configuration, such as database connection settings;
scans the application filesystem and creates the plugin registry;
adds namespaces discovered in plugins to the DI container;
collects CLI commands from those plugins.

During execution it runs the requested command — commonly a web server. With no command, it prints the available commands. The application also exposes stop() so a command can close resources such as database connections in an orderly way.

Logger and configuration

The original core design exposed a common logger abstraction that could work on backend or frontend and route records to transports such as console, file, database, or remote server. Local backend configuration is read from a JSON file such as cfg/local.json and injected into the objects that need it. Secrets should remain in an ignored local configuration or a secure deployment environment, never in a package descriptor.

Plugin scanner

A Teq plugin is an npm package with a teqfw.json descriptor in its root. At minimum it declares a namespace and source directory:

{
  "autoload": {
    "ns": "Vendor_Project_Plugin",
    "path": "./src"
  }
}

The plugin scanner walks node_modules, finds descriptors, records plugin packages, and adds namespace-to-filesystem mappings to DI. Other parts of the application access plugin descriptors through this registry instead of rescanning the filesystem.

Commands

The core application is effectively a wrapper around commander. Plugin descriptors list module identifiers that produce command DTOs:

{ "commands": ["TeqFw_Core_Back_Cli_Version"] }

A command DTO provides an action, description, name and optional realm. The realm prefixes commands from one plugin, so app plus clean becomes app-clean.

const command = await container.get(`${factoryName}$`);
const fullName = command.realm ? `${command.realm}-${command.name}` : command.name;
commander.command(fullName).description(command.desc).action(command.action);

Summary

The Core plugin turns a collection of npm modules into a runnable Teq application. It discovers plugins, registers their namespaces, initializes logging and local configuration, collects their commands, and executes the selected command through DI. This keeps the launcher stable while applications grow by composing plugins.

Additional source-code excerpts

“path”: “./src”
}
} Сканер плагинов (TeqFw_Core_Back_Scan_Plugin) пробегает по всем подкаталогам в ./node_modules/ в поисках teq-дескрипторов (./teqfw.json) и фиксирует найденные npm-пакеты в качестве teq-плагинов в реестре TeqFw_Core_Back_Scan_Plugin_Registry. После чего core-приложение добавляет найденные namespace’ы и их маппинг на файловую систему в DI-контейнер.

“TeqFw_Core_Back_Cli_Version”
]
} В узле commands прописываются идентификаторы es6-модулей, экспортирующих по-умолчанию фабрики для создания таких структур (TeqFw_Core_Back_Api_Dto_Command):
class TeqFw_Core_Back_Api_Dto_Command {
/** @type {Function} */
action;
/** @type {string} */
desc;
/** @type {string} */
name;
/** @type {string} */
realm;
}

export default function Factory(spec) {
// EXTRACT DEPS
/** @type {TeqFw_Core_Defaults} */
const DEF = spec[‘TeqFw_Core_Defaults$’];
/** @type {TeqFw_Core_Back_App.Bootstrap} */
const cfg = spec[‘TeqFw_Core_Back_App#Bootstrap$’];
/** @type {Function|TeqFw_Core_Back_Api_Dto_Command.Factory} */
const fCommand = spec[‘TeqFw_Core_Back_Api_Dto_Command#Factory$’]; // DEFINE INNER FUNCTIONS
const action = async function () {
console.log(Application version: ${cfg.version}.);
}; // COMPOSE RESULT
const res = fCommand.create();
res.realm = DEF.BACK_REALM;
res.name = ‘version’;
res.desc = ‘Get version of the application.’;
res.action = action;
return res;
} Core-приложение добавляет команды в commander при помощи DI-контейнера, который запускает соответствующую фабрику для создания действия (action) и мета-информации для commander’а:
const cmd = await container.get(${factoryName}$);
const fullName = (cmd.realm)

cmd.name;

commander.command(fullName)

.action(cmd.action);