dream

Since dream is an independent library that is imported by psychic, we expose configuration for you which enables dream to understand, for example, what your database credentials are, or where you want your database migrations to go. These configuration items are set in the conf/dream.ts file, which we will be covering in depth in this guide.

conf/dream.ts

A configuration file is used to configure dream, and can be found at the conf/dream.ts location. This file is concerned with provisioning your dream application with database credentials, primary key types, etc...

database connection

In order for Dream to connect to your database, you need to provide it with explicit credentials. Dream supports both primary and replica db connections, and configuration for both can be provided. While this example taps into env vars, we recommend that in production, you switch to something more secure, like AWS Secrets Manager.

export default async function (dream: DreamApplication) {
  dream.set('db', {
    primary: {
      user: process.env.DB_USER!,
      password: process.env.DB_PASSWORD!,
      host: process.env.PRIMARY_DB_HOST!,
      name: process.env.PRIMARY_DB_NAME!,
      port: parseInt(process.env.DB_PORT!),
      useSsl: process.env.DB_USE_SSL === '1',
    },
    replica: {
      user: process.env.DB_USER!,
      password: process.env.DB_PASSWORD!,
      host: process.env.REPLICA_DB_HOST!,
      name: process.env.REPLICA_DB_NAME!,
      port: parseInt(process.env.DB_PORT!),
      useSsl: process.env.DB_USE_SSL === '1',
    },
  }),
  ...
}

loading your application files

In order for dream to function properly, it needs you to provide it folders to scan to locate:

• your models
• your serializers
• your services

To do so, every dream application must have the following lines provided in the dream configuration:

export default async function (dream: DreamApplication) {
  app.load('models', srcPath('app', 'models'), await importModels())
  app.load('serializers', srcPath('app', 'serializers'), await importSerializers())
  app.load('services', srcPath('app', 'services'), await importServices())
  ...
}

setting your project root path

Dream requires you to provide it the path from your configuration file to the project's root file. This should be an absolute path, including the __dirname variable provided by node.

export default async function (dream: DreamApplication) {
  dream.set('projectRoot', path.join(__dirname, '..', '..', '..'))
  ...
}

setting your primary key type

The primaryKeyType configuration informs the cli how to generate your migrations for you when building out models using the cli generators provided by dream.

export default async function (dream: DreamApplication) {
  dream.set('primaryKeyType', 'bigserial')
  ...
}

providing inflections

Provide inflections to your dream application to inform the dream cli generators how to generate pluralized version of singulars.

import inflections from './inflections'

export default async function (dream: DreamApplication) {
  dream.set('inflections', inflections)
  ...
}

application logging

Provide inflections to your dream application to inform the dream cli generators how to generate pluralized version of singulars.

// conf/dream.ts
import inflections from './inflections'

export default async function (dream: DreamApplication) {
  dream.set(
    'logger',
    winston.createLogger({
      level: 'info',
      format: winston.format.json(),
      defaultMeta: { service: 'user-service' },
      transports: [
        //
        // - Write all logs with importance level of `error` or less to `error.log`
        // - Write all logs with importance level of `info` or less to `combined.log`
        //
        new winston.transports.File({ filename: 'error.log', level: 'error' }),
        new winston.transports.File({ filename: 'combined.log' }),
      ],
    }),
  )

  ...
}

warning

If no logger is provided, dream will log using console.log, which is not recommended, since console.log is blocking.

paths

Provide information about the paths to the specific directories that dream cares about. These are only used by the cli locally to generate new files into your application, and it is optional to pass them. By default, they will use the typical paths of a psychic application to generate your files.

// conf/dream.ts
export default async function (dream: DreamApplication) {
  // provides a list of path overrides for your app. This is optional, and will default
  // to the paths expected for a typical psychic application.
  dream.set('paths', {
    conf: 'my/custom/path/to/app/conf',
    db: 'my/custom/path/to/db',
    factories: 'my/custom/path/to/factories',
    models: 'my/custom/path/to/app/models',
    serializers: 'my/custom/path/to/app/serializers',
    services: 'my/custom/path/to/app/services',
    modelSpecs: 'my/custom/path/to/spec/unit/models',
  })
  ...
}

parallelTests

Psychic tests can be slower than traditional vitest testing, since each test utilizes a connection to a single database, and that database must be truncated between each test run, preventing multiple test runs from being done at once. This means your tests must run one at a time, which can be quite slow. To speed things up, we provide the ability for you to partition your test runs onto multiple databases, enabling you to run as many tests as you have databases at once.

export default async function (dream: DreamApplication) {
  dream.set('parallelTests', Number(process.env.DREAM_PARALLEL_TESTS))
  ...
}

ApplicationModel

Additionally, a base model (called ApplicationModel) is pre-established for you which contains carefully constructed type bindings to bridge the types generated by kysely throughout our app through each of your models. This happens automatically for you, but it must be the base class for each of your models in order for the type safety of our system to work properly.

import { Dream, Dreamconf } from '@rvoh/dream'
import { AllColumns, DBClass } from '../../types/db'
import { schema } from '../../types/dream'
import dreamconf from '../../conf/dreamconf'

export default class ApplicationModel extends Dream {
  public declare DB: DBClass

  public get allColumns(): typeof AllColumns {
    return AllColumns
  }

  public get dreamconf(): Dreamconf<DBClass, typeof schema> {
    return dreamconf
  }
}