JugglingDB ORM

Common errors

• TypeError: Schema is not a constructor

  cause Attempting to instantiate `jugglingdb` directly as a constructor (e.g., `new jugglingdb.Schema()`) instead of accessing its `Schema` property.
  fix Correct the import and instantiation to `const Schema = require('jugglingdb').Schema;` and then `const schema = new Schema('memory');`.

• Error: Adapter 'myadapter' is not installed or cannot be found.

  cause The specified database adapter (e.g., `jugglingdb-myadapter`) has not been installed via npm, or the path to a custom adapter is incorrect.
  fix Run `npm install jugglingdb-myadapter` (replace 'myadapter' with your actual adapter name) in your project directory. For custom adapters, ensure the path provided to `new Schema()` is correct and the module exports an adapter conforming to the JugglingDB API.

• jdb.BaseSQL undefined

  cause This specific error often occurred in older `jugglingdb-mysql` adapter versions (e.g., 0.0.1-6) when an incompatible version of the `jugglingdb` core was installed or there was a dependency resolution issue.
  fix This is an indicator of deep-seated dependency incompatibility within an abandoned ecosystem. There is no simple fix other than to avoid this legacy version combination. If encountering this, it's a strong signal to migrate away from JugglingDB entirely.

Warnings

• breaking The `jugglingdb` package is officially abandoned and no longer maintained. Its development activity effectively ceased around 2017-2018. This means it receives no new features, bug fixes, or security updates. Using it in production environments is highly discouraged due to potential vulnerabilities and compatibility issues with modern Node.js versions.
  Fix: Migrate to `loopback-datasource-juggler` or another actively maintained ORM/ODM like Sequelize, TypeORM, or Mongoose. `loopback-datasource-juggler` is the direct successor and maintains a similar API.
• gotcha JugglingDB was built for older Node.js versions (e.g., node >= 0.6) and is primarily CommonJS-based (`require`). It does not natively support ES Modules (`import`/`export`) and may have significant compatibility issues or require complex transpilation to run in modern Node.js or browser environments.
  Fix: Stick to CommonJS `require()` syntax if you must use JugglingDB. For new projects, prefer modern ORMs with full ESM and TypeScript support.
• gotcha JugglingDB does not ship with built-in TypeScript definitions, nor is it designed with TypeScript in mind. Using it in a TypeScript project will require manual type declarations or extensive `@ts-ignore` usage.
  Fix: Consider `loopback-datasource-juggler` which is actively maintained and provides TypeScript definitions. Alternatively, use a modern ORM built for TypeScript.
• breaking The `jugglingdb` core package requires a separate adapter package (e.g., `jugglingdb-mongodb`, `jugglingdb-mysql`) to connect to a specific database. Many of these adapter packages are also abandoned and may not work with current database server versions or their native drivers.
  Fix: Ensure you install the correct adapter (`npm install jugglingdb-ADAPTERNAME`). However, even with the correct adapter, compatibility with modern database versions is not guaranteed.

Install

• npm install jugglingdb npm
• yarn add jugglingdb yarn
• pnpm add jugglingdb pnpm

Imports

• Schema
  wrong:

  import { Schema } from 'jugglingdb';

  correct:

  const Schema = require('jugglingdb').Schema;

  JugglingDB was developed for older Node.js environments and primarily uses CommonJS `require()` syntax. It does not natively support ES Modules (`import`/`export`).
• Post
  wrong:

  const { Post } = require('jugglingdb');

  correct:

  const Post = schema.define('Post', { /* ... */ });

  Models are defined dynamically through a `Schema` instance, not directly imported as named exports from the `jugglingdb` package.

Quickstart

This quickstart demonstrates defining a schema with the in-memory adapter, creating a model, and performing basic CRUD operations (create, find, update, delete) using async/await.

const Schema = require('jugglingdb').Schema;

// Use the in-memory adapter for a quick, no-install example
const schema = new Schema('memory', { debug: true });

const User = schema.define('User', {
  name: { type: String, limit: 50, index: true },
  email: { type: String, unique: true },
  age: { type: Number, default: 18 },
  createdAt: { type: Date, default: Date.now }
});

async function runExample() {
  try {
    // Auto-migrate the schema (create tables/collections if they don't exist)
    await schema.autoupdate(); 
    console.log('Schema autoupdated.');

    // Create a new user
    const newUser = await User.create({ name: 'Alice', email: 'alice@example.com', age: 30 });
    console.log('Created user:', newUser.toJSON());

    // Find a user by ID
    const foundUser = await User.findById(newUser.id);
    console.log('Found user by ID:', foundUser.toJSON());

    // Update a user
    await foundUser.updateAttributes({ age: 31 });
    console.log('Updated user:', foundUser.toJSON());

    // Find all users
    const allUsers = await User.all();
    console.log('All users:', allUsers.map(u => u.toJSON()));

    // Delete a user
    await foundUser.destroy();
    console.log('User deleted.');

    const remainingUsers = await User.count();
    console.log('Remaining users:', remainingUsers);

  } catch (err) {
    console.error('An error occurred:', err);
  } finally {
    // In a real application, you'd disconnect from the database here.
    // For 'memory' adapter, no explicit disconnect is usually needed.
    console.log('Example finished.');
  }
}

runExample();