Total.js Framework v5

Common errors

• ReferenceError: ROUTE is not defined

  cause The Total.js framework was not properly initialized via `require('total5')` at the beginning of the script, or the script is not being run directly by Node.js.
  fix Ensure `require('total5');` is at the top of your main application file (e.g., `index.js`) before any `ROUTE` or other global Total.js functions are called. Then run with `node index.js`.

• TypeError: $.req.body.someProperty is not a function/property

  cause In Total.js v5, direct `request` and `response` objects (`$.req`, `$.res`) have been removed from the controller instance (`$`). You should access data and methods directly on `$` or its helper properties.
  fix Refactor your code to use the new controller API. For example, use `$.body` for POST/PUT body data, `$.query` for query parameters, or specific helper methods provided by the `$` instance.

• Error: Total.js v5 requires Node.js version >= 19

  cause The Node.js runtime version being used is older than the minimum requirement for Total.js v5.
  fix Update your Node.js environment to version 19 or later. You can use tools like NVM (Node Version Manager) to manage multiple Node.js versions.

Warnings

• breaking Total.js v5 introduces significant changes to routing. Direct access to `request` and `response` instances (`$.req`, `$.res`) is removed. All request/response handling is now abstracted through the `controller` instance (alias `$`).
  Fix: Rewrite route handlers to utilize methods and properties available directly on the `$` controller instance. Refer to `$` documentation for updated API.
• breaking The `SESSION()` method for internal session management has been removed in Total.js v5. Developers should now use the `AUTH()` method, which includes predefined session functionality, or implement custom session handling.
  Fix: Migrate session logic to use `AUTH()` for authentication-related sessions or implement a custom session solution as needed.
• breaking The `PREF` global for persistent preferences has been removed. Its functionality is replaced by the `MEMORIZE(name)` method.
  Fix: Replace all instances of `PREF` with `MEMORIZE(name)` to access or store persistent application data.
• breaking For data schemas, `schema.define()` is no longer supported in Total.js v5. Schema actions should be defined directly using `schema.action()`.
  Fix: Update schema definitions to use `schema.action()` for all operations, migrating existing `schema.define()` calls.
• gotcha Total.js v5 has a strong philosophy of pure JavaScript development and explicitly states that users wanting to use TypeScript will be disappointed. The framework is optimized for direct JavaScript without transpilation.
  Fix: Adhere to the pure JavaScript development model, or consider alternative frameworks if TypeScript is a strict requirement for your project.
• gotcha Total.js v5 requires Node.js version 19 or higher. Running on older Node.js versions may lead to unexpected errors or stability issues.
  Fix: Ensure your development and production environments are running Node.js v19 or a newer compatible version.
• gotcha The documentation for Total.js v5 is still incomplete, and developers may need to consult source code, community channels, or older documentation (v3/v4) for certain features or patterns.
  Fix: Be prepared to explore examples, join the Total.js Telegram chat, or refer to previous version documentation when current v5 docs are lacking.

Install

• npm install total5 npm
• yarn add total5 yarn
• pnpm add total5 pnpm

Imports

• total5
  wrong:

  import total5 from 'total5';

  correct:

  require('total5');

  Total.js v5 primarily uses CommonJS `require` for framework initialization and operates with global functions like `ROUTE` and `Total.http`. ESM `import` is not the standard for core framework components.
• ROUTE
  wrong:

  import { ROUTE } from 'total5';

  correct:

  ROUTE('GET /', function($) { /* ... */ });

  Route definitions are made using the global `ROUTE` function, which becomes available after `require('total5')` is called.
• Total.http
  wrong:

  import { http } from 'total5';

  correct:

  Total.http({ load: 'none' });

  The HTTP server is started via the global `Total.http` method, configured with an options object.
• NEWSCHEMA
  wrong:

  import { NEWSCHEMA } from 'total5';

  correct:

  NEWSCHEMA('Users', function(schema) { /* ... */ });

  Data schemas are defined using the global `NEWSCHEMA` function, part of Total.js's built-in data modeling capabilities.

Quickstart

This quickstart demonstrates how to set up a basic Total.js v5 web server with a 'Hello world' GET route and a simple WebSocket chat endpoint.

const framework = require('total5');

// Register a simple GET route
ROUTE('GET /', function($) {
    // $ represents the controller instance
    $.json({ message: 'Hello world from Total.js v5!' });
});

// Register a WebSocket route
ROUTE('SOCKET /chat/', function($) {
    $.on('open', function(client) {
        console.log('Client connected:', client.id);
        client.send({ message: 'Welcome to the chat!' });
    });

    $.on('message', function(client, message) {
        console.log(`Message from ${client.id}:`, message);
        // Broadcast the message to all connected clients
        $.send({ sender: client.id, text: message.text || message });
    });

    $.on('close', function(client) {
        console.log('Client disconnected:', client.id);
    });
});

// Launch the web server on port 8000
Total.http({
    port: process.env.PORT ?? 8000,
    load: 'none' // 'none' for minimal setup, 'release' for production
});

console.log(`Total.js v5 server running at http://127.0.0.1:${process.env.PORT ?? 8000}/`);
console.log(`WebSocket server running at ws://127.0.0.1:${process.env.PORT ?? 8000}/chat/`);