Helpers

Arkorm exports a small set of helper functions for application bootstrap, package integration, testing, and advanced schema work. Most applications only need the helpers in this guide.

Import helpers from arkormx:

import { defineConfig, loadModelsFrom, registerModels } from 'arkormx'

Configuration

defineConfig(config)

Use defineConfig() in arkormx.config.ts to keep configuration typed while returning the same object unchanged:

import { createKyselyAdapter, defineConfig } from 'arkormx'

export default defineConfig({
  adapter: createKyselyAdapter(db),
  paths: {
    models: './app/models',
    migrations: './database/migrations',
    seeders: './database/seeders',
    factories: './database/factories',
  },
})

configureArkormRuntime(client?, options)

Use configureArkormRuntime() when a framework creates the database client or adapter outside the config file:

import { configureArkormRuntime, createKyselyAdapter } from 'arkormx'

configureArkormRuntime(() => prisma, {
  adapter: createKyselyAdapter(db),
})

Prefer defineConfig({ adapter }) for normal applications. Runtime configuration is most useful for framework adapters, test harnesses, and code that wires Arkorm after process startup.

Runtime access helpers

These helpers read the effective runtime state:

import { getRuntimeAdapter, getRuntimeClient, getUserConfig } from 'arkormx'

const adapter = getRuntimeAdapter()
const client = getRuntimeClient()
const paths = getUserConfig('paths')
const config = getUserConfig()

getRuntimePrismaClient is still exported as a compatibility alias for getRuntimeClient, but new code should use getRuntimeClient().

disposeArkormRuntime()

Use disposeArkormRuntime() in short-lived processes and tests when you need to release the configured adapter or client before the Node process exits:

import { disposeArkormRuntime } from 'arkormx'

afterAll(async () => {
  await disposeArkormRuntime()
})

Long-running apps usually do not call this until shutdown.

bindAdapterToModels(adapter, models)

Bind one adapter to a set of model classes:

import { bindAdapterToModels, createKyselyAdapter } from 'arkormx'
import { AuditLog } from './models/AuditLog'
import { Event } from './models/Event'

const adapter = createKyselyAdapter(db)

bindAdapterToModels(adapter, [AuditLog, Event])

This is useful for tests, packages, and multi-database applications. Normal apps usually configure a single runtime adapter instead.

Runtime Discovery

Use runtime discovery helpers when models, migrations, seeders, or factories live outside your configured app paths.

import {
  loadFactoriesFrom,
  loadMigrationsFrom,
  loadModelsFrom,
  loadSeedersFrom,
  registerPaths,
} from 'arkormx'

loadModelsFrom('./packages/billing/src/models')
loadMigrationsFrom('./packages/billing/database/migrations')
loadSeedersFrom('./packages/billing/database/seeders')
loadFactoriesFrom('./packages/billing/database/factories')

registerPaths({
  models: './packages/audit/src/models',
  migrations: ['./packages/audit/database/migrations'],
})

These helpers append runtime discovery paths. They do not rewrite defineConfig({ paths }), and generated files still use the configured primary paths.

Use the matching getters when you need to inspect what has been registered:

import { getRegisteredPaths } from 'arkormx'

const allPaths = getRegisteredPaths()
const modelPaths = getRegisteredPaths('models')

Explicit Registration

Runtime discovery loads files from directories. Explicit registration lets you provide constructors directly, which is useful for plugins, tests, bundled packages, and environments where file-system discovery is unavailable.

import { registerFactories, registerMigrations, registerModels, registerSeeders } from 'arkormx'
import { AuditLog } from './models/AuditLog'
import { AuditLogFactory } from './database/factories/AuditLogFactory'
import { CreateAuditTablesMigration } from './database/migrations/CreateAuditTablesMigration'
import { AuditSeeder } from './database/seeders/AuditSeeder'

registerModels(AuditLog)
registerFactories(AuditLogFactory)
registerMigrations(CreateAuditTablesMigration)
registerSeeders(AuditSeeder)

The corresponding getters return the constructors currently registered:

import {
  getModel,
  getRegisteredFactories,
  getRegisteredMigrations,
  getRegisteredModels,
  getRegisteredSeeders,
} from 'arkormx'

models:sync generates .arkormx/models.d.ts from discovered model files. That file augments Arkorm's known model names for string relationship completion and adds exact getModel() overloads. Use a type-only import and an explicit related-model generic when defining a fully typed string relationship:

import type { User } from './User'

return this.belongsTo<User>('User')

Use getModel() when you need to resolve a model constructor by name without importing it directly:

import { getModel } from 'arkormx'

const User = getModel('User')
const users = await User.query().get()

getModel() is synchronous. It returns already registered models first, then loads from the configured model paths and registers the loaded constructor. After running models:sync, literal registered names return their exact model constructor type.

The Arkorm class exposes the same registration and discovery helpers as static and instance methods:

import { Arkorm } from 'arkormx'

Arkorm.loadModelsFrom('./packages/billing/src/models')
Arkorm.registerModels(AuditLog)
const User = Arkorm.getModel('User')

const arkorm = new Arkorm()
arkorm.loadSeedersFrom('./database/seeders')
arkorm.registerSeeders(AuditSeeder)

Prisma Helpers

createPrismaDatabaseAdapter(prisma, mapping?)

Wrap a Prisma client in Arkorm's compatibility adapter:

import { createPrismaDatabaseAdapter, defineConfig } from 'arkormx'

export default defineConfig({
  adapter: createPrismaDatabaseAdapter(prisma),
})

Pass a mapping when Arkorm table names and Prisma delegate names differ:

createPrismaDatabaseAdapter(prisma, {
  users: 'user',
  roleUsers: 'roleUser',
})

inferDelegateName(modelName)

inferDelegateName() applies Arkorm's Prisma delegate naming convention:

import { inferDelegateName } from 'arkormx'

inferDelegateName('User') // users

This is mainly useful for adapter integrations and diagnostics.

Deprecated compatibility helpers

createPrismaAdapter() and createPrismaDelegateMap() are still exported for legacy migration paths. Prefer createPrismaDatabaseAdapter() for new runtime setup.

Generated Column Helpers

Use resolveGeneratedExpression() when building generated-column definitions from Arkorm expressions:

import { resolveGeneratedExpression } from 'arkormx'

const expression = resolveGeneratedExpression((sql) =>
  sql.json('profile', ['age']).asNumber().gte(18),
)

Generated columns cannot use bind parameters, so this helper inlines literal values and rejects unsupported aggregate expressions. Most users will reach it indirectly through the schema builder.

Internal Helpers

Some helper modules are exported because the CLI, migrations, and adapters share them. Treat these as lower-level integration APIs unless you are extending Arkorm itself:

Helper area	Typical use
Migration history helpers	CLI and custom migration runners
Column-mapping metadata helpers	model sync, migrations, and adapter metadata
Runtime module loader helpers	file discovery for models, seeders, factories, and migrations
Migration planning helpers	avoiding duplicate side effects while planning migrations

When possible, prefer the higher-level APIs documented in Configuration, Migrations & CLI, and Database Adapters.