ApemanDB

Common errors

• Dialect needs to be explicitly defined. If you are using SQLite, install 'sqlite3' package.

  cause Missing database driver package or incorrect 'DIALECT' in database.json.
  fix Install the correct driver (e.g., `npm install sqlite3` or `npm install mysql2`) for your chosen database, and ensure the `DIALECT` property is correctly set in `env/database.json`.

• Error: connect ECONNREFUSED 127.0.0.1:3306

  cause The database server is not running, or the host/port/credentials in `database.json` are incorrect, preventing a connection.
  fix Verify that your database server (e.g., MySQL, PostgreSQL) is running and accessible. Double-check `HOST`, `PORT`, `USERNAME`, and `PASSWORD` in your `env/database.json`.

• TypeError: Cannot read properties of undefined (reading 'User')

  cause The `modelsDir` path provided to `apemandb.create` is incorrect, or the JSON model file (e.g., `user.json`) is malformed or missing.
  fix Ensure the `modelsDir` path is absolute and correctly points to your model definition directory. Verify that JSON model files are valid and present in that directory.

Warnings

• breaking ApemanDB is a wrapper around Sequelize. Major version updates in Sequelize (e.g., from v6 to v7) can introduce breaking changes that ApemanDB may not fully abstract or document, requiring users to consult Sequelize's migration guides for underlying changes.
  Fix: Always check the release notes for both `apemandb` and the underlying `sequelize` package when upgrading major versions. Be prepared to adapt to Sequelize's API changes.
• gotcha ApemanDB is tightly coupled with `apemanenv` for database configuration. Deviations from the expected `apemanenv` structure for `database.json` or its loading mechanism will result in connection failures or unexpected behavior.
  Fix: Ensure `env/database.json` and `env/index.js` follow the structure prescribed by `apemanenv` and `apemandb` documentation. Verify environment variable loading if applicable.
• gotcha Database drivers (e.g., `mysql2`, `sqlite3`, `pg`) are peer dependencies of Sequelize and must be installed separately based on the chosen dialect in `database.json`. Failing to install the correct driver for your specified dialect will lead to runtime errors.
  Fix: Install the appropriate database driver package (e.g., `npm install mysql2`) corresponding to the `DIALECT` specified in your `database.json`.
• gotcha Model definitions are exclusively handled via JSON files. This approach, while simplifying common use cases, can limit direct programmatic control over Sequelize's full feature set (e.g., custom instance methods, hooks) compared to defining models directly in JavaScript/TypeScript.
  Fix: Understand the JSON schema limitations. For advanced Sequelize features not exposed via the JSON model definition, you might need to extend the database instance post-initialization or consider alternative solutions if full Sequelize flexibility is paramount.

Install

• npm install apemandb npm
• yarn add apemandb yarn
• pnpm add apemandb pnpm

Imports

• create
  wrong:

  import { create } from 'apemandb'; // apemandb primarily uses CommonJS 'require' pattern in examples.

  correct:

  const db = require('apemandb').create(envConfig, { modelsDir: './db/models' });

  The primary interaction with ApemanDB is via its `create` factory function, typically consuming configuration from `apemanenv` and a directory of JSON model definitions.
• apemanenv
  wrong:

  import apemanenv from 'apemanenv'; // Examples explicitly use CommonJS `require`.

  correct:

  const apemanenv = require('apemanenv');

  ApemanDB strongly relies on `apemanenv` for loading environment-specific database configuration, as shown in the provided setup guides.
• DB Instance (methods)
  wrong:

  await db.User.create(); // Access models via `db.models` property, not directly on the instance.

  correct:

  await db.sync(); await db.models.User.create({ username: 'test' });

  After initialization, models are typically accessed via the `models` property of the returned database instance. The `sync` method is used for schema synchronization.

Quickstart

Demonstrates setting up `apemanenv` for database configuration, defining a model using `apemandb`'s JSON schema, and initializing the `apemandb` instance to synchronize schema and perform basic CRUD operations.

const path = require('path');
const apemanenv = require('apemanenv');
const apemandb = require('apemandb');

// 1. Define environment configuration (env/database.json)
// In a real project, this would be loaded by apemanenv automatically.
// For quickstart, we'll simulate the structure.
const envDir = path.join(__dirname, 'env');
require('fs').mkdirSync(envDir, { recursive: true });
require('fs').writeFileSync(path.join(envDir, 'database.json'), JSON.stringify({
  "default": {
    "DIALECT": "sqlite",
    "SCHEMA": "apeman-demo-web",
    "STORAGE": ":memory:"
  },
  "development": {
    "SCHEMA": "apeman-demo-web_dev",
    "STORAGE": "./tmp/dev-database.db"
  },
  "test": {
    "DIALECT": "sqlite",
    "SCHEMA": "apeman-demo-web_test",
    "STORAGE": ":memory:"
  }
}, null, 2));

// 2. Define a model (db/models/user.json)
const modelsDir = path.join(__dirname, 'db', 'models');
require('fs').mkdirSync(modelsDir, { recursive: true });
require('fs').writeFileSync(path.join(modelsDir, 'user.json'), JSON.stringify({
  "$name": "User",
  "$description": "A user model",
  "$attributes": {
    "username": {
      "$type": "STRING",
      "$unique": true
    },
    "introText": {
      "$type": "STRING(1024)",
      "$nullable": true
    }
  }
}, null, 2));

async function main() {
  // Load environment variables
  const envConfig = apemanenv(__dirname); // Simulates env loading from __dirname
  
  // Initialize ApemanDB with configuration and models
  const db = apemandb.create(envConfig, { modelsDir: modelsDir });

  try {
    // Connect to the database and synchronize models (create tables)
    await db.sync({ force: true }); // `force: true` drops tables before recreating
    console.log('Database and tables synchronized!');

    // Create a new user record
    const newUser = await db.models.User.create({ username: 'john_doe', introText: 'Hello world!' });
    console.log('Created user:', newUser.toJSON());

    // Find a user
    const foundUser = await db.models.User.findOne({ where: { username: 'john_doe' } });
    console.log('Found user:', foundUser.toJSON());

  } catch (error) {
    console.error('Database operation failed:', error.message);
  } finally {
    // Close the database connection if it's not an in-memory SQLite
    if (db.sequelize.options.dialect !== 'sqlite' || db.sequelize.options.storage !== ':memory:') {
      await db.sequelize.close();
      console.log('Database connection closed.');
    }
  }
}

main();