multitenancy-core

This package allows loading tenant configuration from environment variables.

Installation

npm i @totalsoft/multitenancy-core

or

yarn add @totalsoft/multitenancy-core

Activation

The following environment variable should be set to 'true'

IS_MULTITENANT: 'true'

Environment variables format

Tenant speciffic environment variables should follow the format MultiTenancy__Tenants__Tenant1__TenantProp where:

• MultiTenancy__Tenants__ is a fixed prefix
• Tenant1 is the tenant code
• TenantProp is a tenant speciffic setting
• __ is the separator for the nested structure

An environment variable with the tenant id is mandatory for each tenant (eg: MultiTenancy__Tenants__Tenant1__TenantId)

Nested properties can be used (eg: MultiTenancy__Tenants__Tenant1__ConnectionStrings__MyDatabase__Password)

For settings that are shared by multiple tenants, the folowing format should be used MultiTenancy__Defaults__DefaultProp where:

• MultiTenancy__Defaults__ is a fixed prefix
• DefaultProp is a shared setting for all tenants
• __ is the separator for the nested structure

The default settings are merged with the tenant speciffic settings, and in case of conflicts the tenant speciffic ones have precedence.

Usage

tenantConfiguration

The getValue function reads values or complex objects from environment variables:

const { tenantConfiguration } = require("@totalsoft/multitenancy-core")

// process.env = {
//    IS_MULTITENANT: 'true',
//    MultiTenancy__Tenants__Tenant1__TenantId: '3c841325-eccc-4670-a577-09546df7b1fc',
//    MultiTenancy__Tenants__Tenant1__TenantProp: 'tenantPropValue'
//}
const tenantSpecifficValue = tenantConfiguration.getValue('3c841325-eccc-4670-a577-09546df7b1fc', "tenantProp")

The getAll function retrieves all tenant configurations from environment variables:

const { tenantConfiguration } = require("@totalsoft/multitenancy-core")

// process.env = {
//    IS_MULTITENANT: 'true',
//    MultiTenancy__Tenants__Tenant1__TenantId: '3c841325-eccc-4670-a577-09546df7b1fc',
//    MultiTenancy__Tenants__Tenant1__Name: 'tenant 1 name',
//    MultiTenancy__Tenants__Tenant1__Enabled: 'true',
//    MultiTenancy__Tenants__Tenant2__TenantId: '9c841325-eccc-4670-a577-09546df7b1fc',
//    MultiTenancy__Tenants__Tenant2__Name: 'tenant 2 name',
//    MultiTenancy__Tenants__Tenant2__Enabled: 'false',
//}
const tenants = tenantConfiguration.getAll();

The getConnectionInfo extension reads the configuration to return a connection information object:

const { tenantConfiguration } = require("@totalsoft/multitenancy-core")

// process.env = {
//    IS_MULTITENANT: 'true',
//    MultiTenancy__Tenants__Tenant1__TenantId: tenantId,
//    MultiTenancy__Defaults__ConnectionStrings__MyDatabase__Server: server,
//    MultiTenancy__Tenants__Tenant1__ConnectionStrings__MyDatabase__Database: db,
//    MultiTenancy__Tenants__Tenant1__ConnectionStrings__MyDatabase__UserName: user,
//    MultiTenancy__Tenants__Tenant1__ConnectionStrings__MyDatabase__Password: pass,
//    MultiTenancy__Defaults__ConnectionStrings__MyDatabase__OtherParams: otherParams,
}
const connectionInfo = tenantConfiguration.getConnectionInfo(tenantId, "myDatabase")

The returned ConnectionInfo object has the following structure:

export interface ConnectionInfo {
    server: string, // Can include instance name and port
    database: string, 
    userName: string, 
    password: string, 
    otherParams?: string
}

tenantService

The tenant service relies on the tenant configuration mechanism described above to read obtain tenant attributes.

The getTenantFromId function returns tenant information based on a tenant id.

const { tenantService } = require("@totalsoft/multitenancy-core")

// process.env = {
//     IS_MULTITENANT: 'true',
//     MultiTenancy__Tenants__Tenant1__TenantId: tenantId,
//     MultiTenancy__Tenants__Tenant1__Name: 'Tenant 1 name'
//}

const res = await tenantService.getTenantFromId(tenantId)

tenantService.getAll

The getAll function retrieves all enabled tenants:

const { tenantService } = require("@totalsoft/multitenancy-core")

// process.env = {
//    IS_MULTITENANT: 'true',
//    MultiTenancy__Tenants__Tenant1__TenantId: '3c841325-eccc-4670-a577-09546df7b1fc',
//    MultiTenancy__Tenants__Tenant1__Name: 'tenant 1 name',
//    MultiTenancy__Tenants__Tenant1__Enabled: 'true',
//    MultiTenancy__Tenants__Tenant2__TenantId: '9c841325-eccc-4670-a577-09546df7b1fc',
//    MultiTenancy__Tenants__Tenant2__Name: 'tenant 2 name',
//    MultiTenancy__Tenants__Tenant2__Enabled: 'false',
//}
const tenants = await tenantService.getAll();

The returned Tenant object has the following structure:

export interface Tenant {
    id: string,
    code: string,
    name?: string
    enabled: boolean
}

This function is useful when you need to retrieve all enabled tenants at once, for example, when initializing your application or when performing bulk operations on all tenants.

tenantContextAccessor

Allows propagating a tenant context across async/await calls.

async function inner() {
    // Access tenant context
    const tenantContext = tenantContextAccessor.getTenantContext()
}

const tenant = { id: 'tenant1', code: 'tenant1-code', enabled: true }
//Create context for the current tenant and
tenantContextAccessor.useTenantContext({ tenant }, async () => {
    await inner()
})