Installation

The Data Plugin integrates TypeORM with AxiSpark.js. Follow the steps below to connect your database and register the plugin.

1. Install the Data Plugin

Install the Data package and TypeORM in your project:

npm install @axisparkjs/data typeorm

Install the driver package for the database you plan to use. For example, PostgreSQL and MongoDB:

npm install pg

npm install mongodb

TypeORM documents the driver packages and connection requirements.

2. Import the Data Plugin

Import DataPlugin and DataPluginOptionsFactory, then register the plugin with your AxiSpark.js application:

app.ts

import { AxiSparkFactory } from '@axisparkjs/core';
import { DataPlugin, DataPluginOptionsFactory } from '@axisparkjs/data';

export const app = AxiSparkFactory.create({ name: 'Example API', basePath: __dirname });

app.use(
    DataPlugin,
    DataPluginOptionsFactory.create({
        dataSources: []
    })
);

3. Configure the Data Plugin

DataPluginOptionsFactory.create() accepts a dataSources array. Each entry has a unique name and TypeORM DataSourceOptions in options:

app.ts

import { AxiSparkFactory } from '@axisparkjs/core';
import { DataPlugin, DataPluginOptionsFactory } from '@axisparkjs/data';
import { User } from './entities/user';
import { AuditRecord } from './entities/audit-record';

export const app = AxiSparkFactory.create({ name: 'Example API', basePath: __dirname });

app.use(
    DataPlugin,
    DataPluginOptionsFactory.create({
        dataSources: [
            {
                name: 'PRIMARY',
                options: {
                    type: 'postgres',
                    host: process.env.DB_HOST,
                    port: 5432,
                    username: process.env.DB_USER,
                    password: process.env.DB_PASSWORD,
                    database: process.env.DB_NAME,
                    entities: [User],
                    synchronize: false
                }
            },
            {
                name: 'AUDIT',
                options: {
                    type: 'postgres',
                    host: process.env.AUDIT_DB_HOST,
                    port: 5432,
                    username: process.env.AUDIT_DB_USER,
                    password: process.env.AUDIT_DB_PASSWORD,
                    database: process.env.AUDIT_DB_NAME,
                    entities: [AuditRecord],
                    synchronize: false
                }
            }
        ]
    })
);

Include each entity in the entities array for its data source. The repository generator associates a repository with the first configured data source whose TypeORM metadata contains that entity. If the same entity is registered in multiple sources, the first matching source is used.

All source options are passed to TypeORM's DataSource constructor. This includes TypeORM settings such as logging, migrations, naming strategies, and driver-specific options; see DataSource options.

Use synchronize: true only when appropriate for local development. In production, manage schema changes with TypeORM migrations.

MongoDB connection

Use type: 'mongodb', MongoDB connection options, and Mongo entity classes. Mongo entities should use TypeORM's @ObjectIdColumn() for their document ID. See TypeORM's MongoDB documentation.

{
    name: 'DOCUMENTS',
    options: {
        type: 'mongodb',
        url: process.env.MONGODB_URI,
        database: 'app',
        entities: [MongoUser]
    }
}

Supported derived-query engines

The Data options accept TypeORM DataSourceOptions, while the derived-query dispatcher currently supports these driver types:

Engine	Driver types
SQL	mysql, postgres, cockroachdb, sap, spanner, mariadb, sqljs, oracle, mssql, aurora-mysql, aurora-postgres, better-sqlite3
MongoDB	mongodb

Other TypeORM data source types may still provide TypeORM's own repository methods through BaseRepository, but derived methods fail with an unsupported-driver error until an engine is added. The SQL engine uses TypeORM SelectQueryBuilder; the Mongo engine builds Mongo filters and uses MongoRepository.

Next steps

See Repositories to define and inject repositories, and Derived queries for the method-name format, operators, ordering, and pagination.