VR Models

Common errors

• ERR_REQUIRE_ESM: Must use import to load ES Module

  cause Attempting to `require()` an ES Module file, often when `"type": "module"` is set in `package.json`.
  fix Change `require()` calls to `import` statements or ensure that files intended to be CommonJS are named `.cjs` or reside in a package configured for CommonJS. For `sequelize-cli` migrations, consider adding `"type": "commonjs"` to a `package.json` within your `migrations` directory.

• SequelizeConnectionAcquireTimeoutError: Operation timeout

  cause The database connection pool is unable to acquire a connection within the specified timeout, often due to high load or unreleased connections.
  fix Adjust the `pool.max` and `pool.acquire` options in your Sequelize configuration. Investigate long-running queries or uncommitted transactions in your application logic.

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

  cause A Sequelize model was not properly initialized with the `init` method before being used, or the `sequelize` instance was not passed correctly during model setup.
  fix Ensure `initializeModels(sequelize, DataTypes)` is called correctly and that your Sequelize instance and `DataTypes` are correctly passed and available to all model definitions.

• ERROR: Dialect needs to be explicitly supplied as of v4.0.0

  cause The database dialect (e.g., 'mysql', 'postgres', 'sqlite') was not provided in the Sequelize constructor options.
  fix Pass a `dialect` option to the `Sequelize` constructor, e.g., `new Sequelize({ dialect: 'sqlite', ... })`.

Warnings

• breaking Sequelize v7 introduces significant breaking changes, including renaming the main package to `@sequelize/core` and separating dialects into individual packages. If `vr-models` updates to Sequelize v7, this will require manual updates to your `sequelize` imports and dialect configurations.
  Fix: Review `vr-models` release notes for Sequelize v7 compatibility. Update `sequelize` imports to `@sequelize/core` and install specific dialect packages (e.g., `@sequelize/sqlite3`).
• breaking Sequelize v6.19.2 included a critical SQL injection fix that inadvertently introduced a breaking change related to how replacements were handled within raw SQL strings. While this prevents security vulnerabilities, it might break existing queries that relied on the old behavior of injecting quoted replacements.
  Fix: Audit your `sequelize` queries, especially those using `literal` and `replacements`, to ensure they are not negatively impacted. Avoid using quoted replacements in `literal` expressions.
• deprecated The `sequelize.import` method for loading models was deprecated in Sequelize v5 and completely removed in v6. If `vr-models` or your consuming application uses older model loading patterns, it will break.
  Fix: Ensure `vr-models` uses modern ES module `import` or CommonJS `require` statements for model definitions. Do not use `sequelize.import` in your own code when interacting with older `vr-models` versions if this was a pattern.
• gotcha Mixing ESM `import` syntax with CommonJS `require` in projects configured as ESM (e.g., `"type": "module"` in `package.json`) can lead to `ERR_REQUIRE_ESM` errors, particularly with `sequelize-cli` or older utility scripts that expect CJS.
  Fix: Ensure consistent module syntax across your project. For `sequelize-cli`, consider renaming config files to `.cjs` or creating a local `package.json` with `"type": "commonjs"` in the `migrations` directory.
• gotcha Frequent `ConnectionAcquireTimeoutError` indicates that the Sequelize connection pool is exhausted, often due to too many concurrent requests, long-running queries, or uncommitted/unrolled-back transactions.
  Fix: Increase the `max` option in your Sequelize connection pool configuration, optimize slow queries, ensure transactions are always committed or rolled back, and monitor database server load.
• gotcha Incompatible versions of `sequelize` with `vr-models` (due to peer dependency mismatches) can lead to unexpected behavior, missing methods, or type errors, especially after major `sequelize` updates.
  Fix: Always align your installed `sequelize` version with the peer dependency specified by `vr-models` (e.g., `^6.x`). Check `npm install` warnings carefully.

Install

• npm install vr-models npm
• yarn add vr-models yarn
• pnpm add vr-models pnpm

Imports

• initializeModels
  wrong:

  const { initializeModels } = require('vr-models');

  correct:

  import { initializeModels } from 'vr-models';

  The package ships TypeScript types and is primarily designed for modern ESM usage. Avoid CommonJS `require`.
• VRUser
  wrong:

  import VRUser from 'vr-models/VRUser';

  correct:

  import { VRUser } from 'vr-models';

  Individual models are typically named exports from the main package entry, not default exports from sub-paths.
• IVRUserAttributes
  wrong:

  import { IVRUserAttributes } from 'vr-models';

  correct:

  import type { IVRUserAttributes } from 'vr-models';

  Use `import type` for importing only type definitions to prevent bundling issues and improve tree-shaking.

Quickstart

Demonstrates how to initialize Sequelize, import and synchronize models from `vr-models`, and perform basic CRUD operations with a sample VRUser and VRProduct model.

import { Sequelize, DataTypes, Model } from 'sequelize';
import { initializeModels, VRUser, VRProduct } from 'vr-models';

interface Config { database: string; username?: string; password?: string; host?: string; dialect: string; storage?: string; }

const config: Config = {
  dialect: 'sqlite',
  storage: process.env.DB_STORAGE ?? './vr_database.sqlite',
};

const sequelize = new Sequelize(config);

async function setupAndUseVRModels() {
  try {
    await sequelize.authenticate();
    console.log('Database connection has been established successfully.');

    // Initialize models from vr-models, passing the Sequelize instance
    initializeModels(sequelize, DataTypes); // Assuming initializeModels takes sequelize and DataTypes

    // Synchronize all models (in a real app, use migrations from vr-migrations)
    await sequelize.sync({ alter: true });
    console.log('All models were synchronized successfully.');

    // Create a new VR user
    const newUser = await VRUser.create({ username: 'playerOne', email: 'playerone@example.com' });
    console.log('New VR user created:', newUser.toJSON());

    // Create a new VR product
    const newProduct = await VRProduct.create({ name: 'Virtual Headset', price: 299.99, description: 'High-fidelity VR experience.' });
    console.log('New VR product created:', newProduct.toJSON());

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

  } catch (error) {
    console.error('Unable to connect to the database or operate:', error);
  } finally {
    await sequelize.close();
    console.log('Database connection closed.');
  }
}

setupAndUseVRModels();