ripplex-config-js

A configuration library that allows for using filesystem based backing stores for local development and GCP Firestore for non-local development.

How does it work?

Depending on the environment name, this library will bootstrap a configuration instance for you wired up to the appropriate backing store.

import getConfig from 'ripplex-config-js'

export const config = getConfig('my-application-name')

async function startMyApp() {
  // call the init method to finish bootstrapping external resources.
  // this method should only be called once during startup.
  await config.init()
  // do other application initialization
}

startMyApp().catch(console.log)

After initialization is complete, you can use the config instance to lookup a string, number or boolean along with a default value if nothing has been defined.

import getConfig from 'ripplex-config-js'
import setUpMyFeature from './feature'

export const config = getConfig('my-application-name')

async function startMyApp() {
  // call the init method to finish bootstrapping external resources.
  // this method should only be called once during startup.
  await config.init()
  const dbName = config.getValue('DB_NAME', 'my-application-db')
  const dbPort = config.getNumValue('DB_PORT', 5432)
  setUpDb(dbName, dbPort)

  const featureEnabled = config.getBoolValue('MY_NEW_FEATURE', false)
  if (featureEnabled) {
    setUpMyFeature()
  }
  // ...
}

To use the configuration throughout your application, you can reference it by either using a global instance similar to what is provided above:

import { config } from './index'

export function setUpMyFeature() {
  const myFeatureValue = config.getValue(
    'MY_FEATURE_VALUE',
    'welcome to feature',
  )
  // ...
}

Or by making the same call in index.ts anywhere in your application once initialization is complete:

export function setUpMyFeature() {
  const myFeatureValue = getConfig('my-application-name').getValue(
    'MY_FEATURE_VALUE',
    'welcome to feature',
  )
  // ...
}

I see there's an init. Is there a shutdown?

Yes, but you don't necessarily have to call it yourself.

The ConfigStore interface returned from getConfig also exposes a shutdown method that can be called if you need to tear down resources as part of your shutdown routine. That said, the API will also listen to process termination events and attempt to clean up resources automatically. If you find that your application is hanging though, you may need to call shutdown() yourself.

How do I know if something changes?

This library has support for subscribing for changes to configuration values via its property system.

In contrast to the examples above, you can make the following call instead to obtain a reference to the property, which provides a hook to subscribe:

import { config } from './index'

export function setUpMyFeature() {
  const myFeatureProperty = config.getProperty(
    'MY_FEATURE_VALUE',
    'welcome to feature',
  )
  const myFeatureValue = myFeatureProperty.get()
  myFeatureProperty.subscribeToChanges((_key) => {
    const myUpdatedValue = myFeatureProperty.get()
    updateMyFeatureConfig(myUpdatedValue)
  })
  // ...
}

You may want to use this if you're allocating long-lived resources that must be recreated in response to a config change, such as an Axios instance or a database connection pool. The subscriber function is also passed a key property in case you need to reuse a subscriber function and perform some kind of switching behavior depending on the key represented in the change. The value however is not returned in this function and should only be fetched by called to config.getValue(key, defaultValue) or property.get() as it's possible that you could receive a stale value depending on order of execution.

How do I set up my local configuration?

By default, all local configuration files are stored in ~/ripplex/config/. Application-level configuration is looked up by the applicationName passed to the getConfig method by finding a file called ${applicationName}.properties. Environment-level configuration is looked up in this directory as well by loading a file called environment.properties.

The properties file format is a simple key/value pairing, delineated by =, similar to what you'd find in the .env file approach used elsewhere. For example:

my_key=my_value
# a comment
my_other_key=2

How do I set up my Firestore configuration?

In GCP Firestore, you'll need to create a document matching the applicationName passed to the getConfig method that exists within the Collection that has the same name as the environment your application is running in (typically dev, test, stage, or prod). Similarly, a document called environment is present in this collection and represents environment-wide configuration values.

The only values supported are string, boolean, and number. Using a type that deviates from these types will have unexpected behavior and will likely result in application failures, potentially during startup.

Your application will also need a GCP service account associated with it in order to access the values in this table. More on this will be added to the document soon as this approach is worked out with operations.