Nymph

The Nymph core package provides the base level classes and utilities to query the database, save data to it, and define different data types.

npm install --save @nymphjs/nymph

To use Nymph, you need a database driver. Nymph.js provides a MySQL driver, a PostgreSQL driver, and a SQLite3 driver. They all provide the exact same functionality (with the exception of alphanumerical sort order, which is dependent on database collation).

Here's an overview:

// main.ts
import { Nymph } from '@nymphjs/nymph';
import MySQLDriver from '@nymphjs/driver-mysql';
import TodoClass from './Todo';

const mysqlConfig = {
  host: 'your_db_host',
  database: 'your_database',
  user: 'your_user',
  password: 'your_password',
};

// Create a new instance of Nymph.
const nymph = new Nymph({}, new MySQLDriver(mysqlConfig));
// addEntityClass returns the class you should use for this instance of Nymph.
const Todo = nymph.addEntityClass(TodoClass);

// You are set up. Now you can use entity classes like `Todo` to store data,
// and Nymph's query methods like `getEntities` to retrieve them.

async function run() {
  const myEntity = await Todo.factory();
  myEntity.text = 'Get it done!';
  await myEntity.$save();

  const otherPendingTodos = await nymph.getEntities(
    { class: Todo },
    {
      type: '&',
      '!guid': myEntity.guid,
      equal: ['done', false],
    },
  );

  const total = otherPendingTodos.length;
  const single = total === 1;
  console.log(
    `Besides the one I just created, there ${
      single ? 'is' : 'are'
    } ${total} pending todo${single ? '' : 's'} in the database.`,
  );
}

// Todo.ts
import { Entity } from '@nymphjs/nymph';

export interface TodoData {
  text: string;
  done: boolean;
}

export interface Todo extends TodoData {}

export class Todo extends Entity<TodoData> {
  static ETYPE = 'todo'; // This is used for the table name(s) in the DB.
  static class = 'Todo'; // This is used to map references to their class.

  constructor() {
    super();

    this.text = '';
    this.done = false;
  }

  async $getOtherTodos() {
    // this.$nymph (or this.nymph in a static function) is the instance of Nymph
    // this entity was loaded with. Creating transactions will create a new
    // instance of Nymph, so it could be a transactional instance.
    const otherTodos = await this.$nymph.getEntities(
      { class: Todo },
      {
        type: '!&',
        guid: this.guid,
      },
    );
    return otherTodos;
  }
}

See the config declaration file.

Sometimes database changes can be live migrated. In these cases, running needsMigration() will tell you about them, and the docblock for that method will give you more information. You should always run this method after updating to a new version of Nymph to see what needs to be migrated, if anything.

If a migration is needed, you should export the DB in the version you were using before, in case anything goes wrong during the migration.

The next step is to use the liveMigration(migrationType) method with the correct migration type.

If required (explained in the docblock), you might then need to run a specific import on all of your entities. This is very important, and you might not be able to use new features or upgrade further without performing this step.

Note that you can always export the DB in the version you were previously using, completely clear the DB (drop all of the tables), then import the DB in the new version.