npm install user@example.com

If you use image processing (image.js), you must have ImageMagick or GraphicsMagick installed at the OS level:

# Debian / Ubuntu
sudo apt-get install imagemagick

# macOS
brew install imagemagick

No native Node addons, no node-gyp build step, no pod install required.

Project setup

1. Create your application directory and install Total.js:

   mkdir myapp && cd myapp
   npm init -y
   npm install user@example.com
   

2. Copy source/helpers/index.js to your project root as index.js (or use it as a reference). This is the canonical entry point.

3. Create the standard Total.js directory layout expected by the framework:

   myapp/
     controllers/
     models/
     views/
     public/
     definitions/
     modules/
     index.js
   

4. Set environment variables before launching. Total.js reads NODE_ENV to distinguish debug / release / test:

   export NODE_ENV=debug
   

5. Launch in debug mode (auto-reload on change):

   node source/debug.js
   # or via your own entry point:
   node index.js
   

6. Launch in release (production) mode:

   node index.js --release
   

7. TypeScript projects: Total.js ships CommonJS modules. In tsconfig.json set "moduleResolution": "node" and "esModuleInterop": true. Import via require or use import F = require('total.js').

Public API

framework (default export from total.js / index.js)

const F: Framework = require('total.js');

F.http(mode: 'debug' | 'release' | 'test', options?: {
  ip?: string;
  port?: number;
  unixsocket?: string;
  config?: Record<string, any>;
  sleep?: number;
  inspector?: number;
  watch?: string[];
  livereload?: boolean;
}): void;

The root framework singleton. Call F.http() once at startup to bind the HTTP server. All routing, middleware, and lifecycle hooks are attached to this object via globals (ROUTE, MIDDLEWARE, MODULE, etc.).

SchemaBuilder (builders.js)

// Accessed via the global NEWSCHEMA helper wired by index.js
const schema: SchemaBuilder = NEWSCHEMA('SchemaName', (schema) => {
  schema.define('name',    'String(50)', true);
  schema.define('age',     'Number',     true);
  schema.define('email',   'Email',      false);

  schema.setInsert(function($) {
    // $.value holds the validated model
    $.success($.value);
  });
});

SchemaBuilder defines typed, validated business objects. Use it for every incoming payload that needs sanitization, type coercion, and error feedback before hitting your database or business logic.

NoSQL database (nosql.js)

// Accessed via global DATABASE() helper after framework boot
const db: TableDB | NoSQLDB = DATABASE('tableName');

// Insert
db.insert(doc: object): Promise<void>;

// Read with filter
db.find()
  .where('field', value)
  .take(limit: number)
  .skip(offset: number)
  .callback((err: Error|null, docs: object[]) => void): void;

// Update
db.update(patch: object)
  .where('field', value)
  .callback(callback): void;

// Remove
db.remove()
  .where('field', value)
  .callback(callback): void;

The embedded NoSQL engine stores documents as newline-delimited JSON on disk. Use it for lightweight persistence without running an external database server.

Working examples

Scenario - Minimal HTTP API server

Start a JSON REST API that responds on port 8000 using only total.js as a dependency.

// index.js
'use strict';

require('total.js').http('debug', { port: 8000 });

// controllers/api.js  (Total.js auto-loads files in controllers/)
exports.install = function() {
  ROUTE('GET /api/ping', ping);
  ROUTE('POST /api/echo', echo, ['*Body']);
};

function ping() {
  // `this` is the controller context
  this.json({ ok: true, ts: new Date() });
}

function echo() {
  this.json(this.body);
}

Scenario - Schema validation with operation

Define a schema, attach a save handler, and call it from a route.

// definitions/user.js
'use strict';

NEWSCHEMA('User', function(schema) {
  schema.define('name',  'String(100)', true);
  schema.define('email', 'Email',       true);
  schema.define('age',   'Number');

  schema.setInsert(function($) {
    // Persist validated model ($.value) however you like
    const doc = $.value;
    doc.id    = UID();
    doc.dtcreated = new Date();
    DATABASE('users').insert(doc);
    $.success(doc.id);
  });
});

// controllers/users.js
exports.install = function() {
  ROUTE('POST /api/users', createUser, ['*User']);
};

function createUser() {
  // this.body has already been validated against the User schema
  this.$save(this.body, (err, id) => {
    if (err)
      return this.json({ error: err.toString() }, 400);
    this.json({ id });
  });
}

Scenario - Embedded NoSQL query

Read and filter records from the embedded database after framework boot.

// definitions/startup.js  (runs after framework is ready)
'use strict';

ON('ready', function() {
  // Insert sample data
  DATABASE('products').insert({ name: 'Widget', price: 9.99, active: true });

  // Query active products under $20
  DATABASE('products')
    .find()
    .where('active', true)
    .callback(function(err, docs) {
      if (err) { console.error(err); return; }
      console.log('Active products:', docs);
    });
});

File walkthrough

• index.js - Framework core: defines the Framework class, HTTP/HTTPS server creation, router, static file handler, controller lifecycle, caching, and all globally injected helpers (ROUTE, MODULE, DATABASE, etc.).
• builders.js - SchemaBuilder and SchemaOptions: typed schema definitions, field validators, workflows, operations, and REST builder for external API calls.
• nosql.js - NoSQLDB and TableDB: embedded flat-file document store supporting insert/find/update/remove with streaming reads and backup.
• nosqlstream.js - Low-level stream reader used internally by nosql.js to scan .nosql files line by line.
• nosqlworker.js - Offloads heavy NoSQL operations to a worker thread to avoid blocking the event loop.
• nosqlcrawler.js - Background table crawler for scheduled NoSQL maintenance tasks.
• utils.js - String, Date, Number, Array prototype extensions plus HTTP request helpers, XML parser, and path utilities shared across the framework.
• internal.js - Private utilities (encoding, merging, minification) consumed by index.js and utils.js; not intended for direct use.
• builders.js - (see Public API above).
• mail.js - SMTP client with TLS, authentication, and Tangular-based HTML templating.
• image.js - Chainable ImageMagick/GraphicsMagick wrapper: resize, crop, convert, watermark.
• debug.js - Development launcher: spawns the app child process and restarts it on file changes.
• cluster.js - Multi-core launcher that forks worker processes and handles IPC messaging.
• session.js - In-memory and NoSQL-backed session store integrated with the controller.
• websocketclient.js - WebSocket client for outbound connections from within a Total.js app.
• tangular.js - Template engine with @{variable}, @{if}, @{foreach} and custom helpers.
• flow.js - Integration layer for Total.js Flow visual programming.
• graphdb.js - Lightweight embedded graph database for node/edge data models.
• bundles.js - Packages app slices (controllers, views, public assets) into single .bundle files.
• test.js - Assertion helpers and HTTP test runner for Total.js unit tests.
• helpers/index.js - Minimal startup script that switches debug/release mode based on CLI arguments.
• helpers/debug.js, helpers/release.js, helpers/test.js - Mode-specific launch wrappers.
• merged/merge.js - CLI tool for merging JS/CSS files during build.
• tools/ - Shell scripts used by maintainers for release automation; not needed at runtime.

Common pitfalls and fixes

• Global pollution: Total.js aggressively extends String, Number, Date, and Array prototypes and injects globals on require. Isolate it in its own process or accept the globals project-wide.
• Directory structure is mandatory: The framework silently skips controllers, models, and views if the standard directories (controllers/, views/, public/) do not exist at startup. Create them before calling F.http().
• DATABASE() is only available after ON('ready', ...): Calling DATABASE() at module load time (before the framework finishes booting) returns undefined. Wrap all startup queries in the ready event.
• ESM projects: Total.js v3 is CommonJS only. In ESM projects use import { createRequire } from 'module'; const F = createRequire(import.meta.url)('total.js'); or set "type": "commonjs" in package.json.
• ImageMagick not found: image.js shells out to convert / gm. If the binary is missing, image operations silently fail. Verify with which convert and install the OS package.
• Port conflicts in cluster mode: When using cluster.js, each worker binds the same port via SO_REUSEPORT. On older Linux kernels (< 3.9) this will throw EADDRINUSE. Upgrade the kernel or use a reverse proxy with a single binding.

Vibe-coding prompt template

I have a copy of the Total.js Framework v3 (total.js@3.4.13) source code
located in the `source/` directory of this project, and a USAGE.md file
that documents its real API and directory conventions.

Please help me integrate Total.js into my existing Node.js project by
doing the following, step by step:

1. Read USAGE.md and source/index.js to understand the framework boot
   sequence and available globals (ROUTE, DATABASE, NEWSCHEMA, ON, etc.).

2. Add an `index.js` entry point that calls require('total.js').http()
   in debug mode on port 8000, following the pattern in
   source/helpers/index.js.

3. Create a `controllers/` directory with at least one controller that
   registers GET and POST routes using the ROUTE global.

4. Define one schema in `definitions/` using NEWSCHEMA (from
   source/builders.js) with field validation and a setInsert handler
   that writes to DATABASE().

5. Add a startup definition that listens to ON('ready') and seeds the
   embedded NoSQL database (source/nosql.js) with sample records.

6. Show me how to query those records using DATABASE().find().where()
   .callback() as documented in USAGE.md.

Use only APIs that appear in USAGE.md and the source/ file excerpts.
Do not invent method names. Confirm each step before moving to the next.

License and credit

Total.js Framework v3 is released under the MIT License (see source/LICENSE and source/license.txt). Copyright 2012-2021 Peter Širka.

Upstream repository: https://github.com/totaljs/framework npm package: total.js

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

NestJS Progressive Node.js Backend Framework

Automation, Utilities & Developer Tools

Free