# Configuration Usage

This document provides an overview of the configuration management for a Rebar server application.

# Features

Parsing environment variables.
Setting a default value if env variable was not defined.
Basic type validation - number, boolean, string (by default).

# Usage

By default, mongodb is initialized automatically. It is required and has default value of local mongodb instance.

Config defined as an interface, all methods covered with type hints, so you will see all variables and correct types on each method call.

# Get config object

You can get the whole config object this way:

import { useRebar } from '@Server/index.js';

const config = useRebar().useConfig().get();
// config === {
//     mongodb: 'mongodb://...',
// }
}

# Get variable from config

You can also get a specific value from config:

import { useRebar } from '@Server/index.js';

const mongodb = useRebar().useConfig().getField('mongodb');
// typeof mongodb === 'string'

# Set new variable

To be able to extend default Rebar config, you can extend Config interface this way:

/plugins/shared/interfaces.ts
import '@Server/config/index.js';

// Extend NodeJS.ProcessEnv, so it will show you that it exists on process.env.SOME_ENV_VARIABLE.
declare global {
    namespace NodeJS {
        export interface ProcessEnv {
            SOME_ENV_VARIABLE: string;
        }
    }
}

// Extend Config interface, don't forget to import module first to make TypeScript magic work.
declare module '@Server/config/index.js' {
    interface Config {
        // Name of key could be different from env variable, it doesn't matter.
        some_variable: number;
    }
}

After you've extended Config interface, you'll be able to use it's keys to initialize config variable against the env.

/plugins/server/index.ts
/* .env file content:
SOME_ENV_VARIABLE=12
*/

import { useRebar } from '@Server/index.js';

const config = useRebar().useConfig();

config.initFromEnv(
    'some_variable', // Config interface key.
    {
        env: 'SOME_ENV_VARIABLE', // Required.
        default: 500, // Optional, default: undefined.
        required: true, // Optional, default: true.
        type: 'number', // Optional, default: undefined (interpreted as string on parse, no type cast).
    },
);

// If default is not set or set as `undefined`, there is no ENV variable declared and required=true
// You will get this exception on server startup:
// Error: `SOME_ENV_VARIABLE should be defined in .env file.`

Important

If you will try to parse not a number as number, you will get an uncaught exception:

/plugins/server/index.ts
/* .env file content:
SOME_ENV_VARIABLE=dummy
*/

import { useRebar } from '@Server/index.js';

const config = useRebar().useConfig();

config.initFromEnv(
    'some_variable', // Config interface key.
    {
        env: 'SOME_ENV_VARIABLE', // Required.
        default: 500, // Optional, default: undefined.
        required: true, // Optional, default: true.
        type: 'number', // Optional, default: undefined (interpreted as string on parse, no type cast).
    },
);

You will get an uncaught exception here, the server won't start and you will see this in logs:

Error: Can't set auth_session_lifetime: Can't parse 'dummy', it is not a valid number

# Override config variable in runtime

You can change variable value in runtime. Be careful with types.

/plugins/server/index.ts
import { useRebar } from '@Server/index.js';

const config = useRebar().useConfig();

// Correct:
config.set('some_variable', 1000);

// Incorrect:
// There you will see an error in IDE, because it checks the type of `some_variable` in Config interface.
// !!! It won't raise an error in runtime, will just write a wrong value to the config.
config.set('some_variable', '1000');