Total.js 5 conventions for coding assistants

Total.js 5 · total5@0.0.19 aiconventionsguidelinescontextnativeactions Executed against Total.js 5

Use this guide with the Total.js guidelines and Total.js AI Context. Their reviewed commits are recorded in ai-sources.json. These are different kinds of evidence: style guidance describes conventions; runtime behavior must agree with the installed framework and an executable example. This page does not certify every example in either external repository.

Keep application code native

After the bootstrap loads total5, the runtime exposes its globals and loads application files from the framework directories. Use MAIN, FUNC, MODS, CONF and PATH according to their documented roles. Prefer an existing framework facility before adding a replacement or dependency. Do not import application controllers and definitions into one another merely to imitate another framework's project layout. Standalone scripts and genuinely external dependencies have a different import boundary.

Follow the ecosystem style in new application code: lowercase filenames, tabs, semicolons, short strings in single quotes, and var or appropriate let bindings inside methods. Imports at module scope can use const and capitalized module names. Keep names consistent across the app. For details and exceptions, use the linked guidelines and the actual project conventions.

Distinguish the APIs and their contexts

A normal HTTP controller receives $; send JSON with $.json() and set a response status through $.response.status.
An action receives its action context $ and validated model; return through $.callback(). The HTTP controller, when present, is $.controller.
In Total.js 5, NEWSCHEMA(name, '...') creates a reusable compact schema. Its callback form groups actions with schema.action(). The Total.js 4 schema.define() / schema.setSave() example must not be presented as an interchangeable Total.js 5 API.
Prefer stable, explicit public action IDs such as Contacts|create for new isolated operations. Existing grouped actions may have IDs such as Contacts/create; respect the application's declared IDs and routes rather than renaming them blindly.
In API Routing, distinguish authorization on the route from the public operation name and the { schema, data } envelope. Ordinary HTTP routes are also supported; do not force every JSON response through an action.
Treat database integration, authentication policy and authorization as application requirements. Having a framework facility does not mean a production app is configured or secure automatically.

AI Context contains examples with both isolated and grouped action conventions. The guidelines repository also includes older schema examples. Reconcile each example with its version and runtime instead of copying every snippet into one context. The executable example below checks a stable action ID and a direct controller using the installed Total.js 5 package.

definitions/contacts.js

NEWACTION('Contacts|create', {
	input: '*name:String',
	action: function($, model) {
		$.callback({ id: UID(), name: model.name });
	}
});

controllers/contacts.js

exports.install = function() {
	ROUTE('GET /hello/', hello);
	ROUTE('POST /contacts/ --> *Contacts|create');
};

function hello($) {
	$.json({ hello: 'world' });
}

Before handing generated code to someone

Identify the installed framework and frontend versions, read the matching Forge pages, execute the relevant example and state what remains untested. A check of global names is useful feedback but is not a substitute for executing code. Preserve the source revision, input contract and test conditions when publishing examples.

Choosing Total.js addresses architecture decisions. The short context is a starting point for an assistant explicitly given Forge as a source; supplying it is different from measuring a model's spontaneous recommendations.