Total.js Node Database Management System (ORM)

Common errors

• ReferenceError: DBMS is not defined

  cause Attempting to call the global `DBMS()` function outside of a properly initialized Total.js application context.
  fix Ensure `dbms.init()` has been executed within a Total.js application's `/definitions/db.js` file, which registers `DBMS()` globally. For standalone use, this pattern is not natively supported and requires manual global exposure or direct module interaction, which may deviate from documented usage.

• Error: Cannot find module 'pg'

  cause The required database driver for PostgreSQL (`pg`) was not installed as a peer dependency.
  fix Install the missing driver: `npm install pg` (for PostgreSQL). Replace `pg` with `mysql2` or `mongodb` as appropriate for your configured database type.

• Database 'default' was not initialized.

  cause The `dbms.init()` method was not called for the specified or default database alias before attempting database operations.
  fix Call `dbms.init([alias], connection_string);` at application startup. For Total.js, this is typically in `/definitions/db.js`.

Warnings

• gotcha The primary interaction method, `DBMS()`, is designed to be a global function within Total.js applications after the module is initialized via `dbms.init()` in a definitions file. Attempting to use `DBMS()` directly in a non-Total.js environment without proper global scope management will result in a `ReferenceError`.
  Fix: Ensure you are running within a Total.js application where `dbms.init()` has been called in `/definitions/db.js`, or manually expose the function to the global scope if adapting for standalone use (though not recommended for production).
• breaking This package is CommonJS-only. It does not natively support ECMAScript Modules (`import` syntax). Attempting to `import dbms from 'dbms'` will result in a module loading error in pure ESM environments.
  Fix: Use `const dbms = require('dbms');` for all imports. If your project is pure ESM, you may need to use a CommonJS wrapper or consider alternative ORMs that offer native ESM support.
• gotcha Database drivers (e.g., `pg` for PostgreSQL, `mysql2` for MySQL, `mongodb` for MongoDB) are peer dependencies and must be installed separately alongside `dbms`. The package will not function with a specific database type unless its corresponding driver is explicitly installed.
  Fix: Install the necessary driver(s) using `npm install <driver-package-name>`, e.g., `npm install pg` for PostgreSQL.
• gotcha The `dbms` package offers only 'partial' support for MongoDB. This implies that not all MongoDB features or query patterns may be fully implemented or optimized compared to dedicated MongoDB ORMs/ODMs.
  Fix: Review the Total.js DBMS documentation for specific limitations with MongoDB. For complex MongoDB operations, consider using a dedicated MongoDB driver or ODM directly.
• gotcha The package's latest version (1.0.9) was published approximately two years ago. While not explicitly deprecated, the infrequent updates suggest a mature but slowly evolving project. This could mean slower adoption of new database features, less frequent security patches, or compatibility issues with very recent Node.js versions or database releases.
  Fix: Evaluate compatibility with your current Node.js and database versions. Monitor the Total.js ecosystem for any announcements regarding future `dbms` development or replacements.

Install

• npm install dbms npm
• yarn add dbms yarn
• pnpm add dbms pnpm

Imports

• dbms
  wrong:

  import dbms from 'dbms';

  correct:

  const dbms = require('dbms');

  The `dbms` package is CommonJS-only; direct ES module `import` statements are not natively supported.
• DBMS()

  var db = DBMS();

  The `DBMS()` function becomes a global accessible method within a Total.js application after `require('dbms').init()` has been successfully called, typically within `/definitions/db.js`. It is not directly exported by the `dbms` module.
• dbms.init
  wrong:

  DBMS.init('...');

  correct:

  const dbms = require('dbms'); dbms.init('postgresql://user:pass@localhost:5432/dbname');

  `init` is a method on the module object obtained via `require('dbms')`, not on the global `DBMS()` function.

Quickstart

Demonstrates initializing database connections with `dbms.init()` and performing basic `find`, `insert`, and `one` operations using the `DBMS()` global function, illustrating common patterns within a Total.js application.

const dbms = require('dbms');

// In a Total.js application, dbms.init() would typically be called once
// within a configuration or definition file (e.g., `/definitions/db.js`).
// This action makes the `DBMS()` function globally available.

// Initialize a PostgreSQL connection named 'default'
dbms.init('postgresql://user:password@localhost:5432/testdb?pooling=false');

// Initialize another PostgreSQL connection named 'mypg'
dbms.init('mypg', 'postgresql://user:password@localhost:5432/anothertestdb');

// --- Simulate Global DBMS() Function (for non-Total.js standalone use) ---
// In a real Total.js app, `DBMS()` would be globally available after init.
// This mock helps illustrate usage but isn't how it works natively outside Total.js.
function DBMS(name) {
  const _dbmsModule = require('dbms');
  return _dbmsModule(name);
}

// Example 1: Find records using the default database
DBMS().find('users').where('age', '>', 25).callback(function(err, response) {
    if (err) {
        console.error('Error finding users:', err);
        return;
    }
    console.log('Found users (default DB):', response);
});

// Example 2: Insert a new record into a named database ('mypg')
DBMS('mypg').insert('products', { name: 'New Widget', price: 99.99, stock: 100 }).callback(function(err, id) {
    if (err) {
        console.error('Error inserting product:', err);
        return;
    }
    console.log('Inserted product with ID (mypg DB):', id);
});

// Example 3: Find a single record
DBMS().one('settings').where('key', 'app_name').callback(function(err, setting) {
    if (err) {
        console.error('Error fetching setting:', err);
        return;
    }
    console.log('App Name setting:', setting);
});

// Note: Ensure the `pg` npm package is installed: `npm install pg`
// And replace `user` and `password` with actual credentials for the database.