npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@map-colonies/config

v1.3.0

Published

Config package for MapColonies with support for central config management

Downloads

220

Readme

Config

This package provide a solution for handling the configuration for NodeJs applications. The package supports both working as a standalone solution and online using config-server.

The configs are defined in the schemas package. It is used for validation, defining environment variable override, and for generating typescript types.

Installation

In order to use the package you need to install both the package itself, and the schemas package that handles all the config schemas.

npm install @map-colonies/schemas @map-colonies/config

Usage

import { config } from '@map-colonies/config';
import { commonBoilerplateV4 } from '@map-colonies/schemas';

const configInstance = await config({
  configName: 'boiler-config',
  configServerUrl: 'http://localhost:8080',
  schema: commonBoilerplateV4,
  version: 'latest',
  offlineMode: false
});

const port = configInstance.get('server.port');

API Documentation

This section describes the API provided by the package for interacting with the configuration.

ConfigInstance<T>

The ConfigInstance interface represents the your way to interact with the configuration. It provides methods to retrieve configuration values and parts. T is the typescript type associated with the chosen schema. it can be imported from the @map-colonies/schemas package.

Methods

get<TPath extends string>(path: TPath): _.GetFieldType<T, TPath>
  • Description: Retrieves the value at the specified path from the configuration object. Note that the type of returned object is based on the path in the schema.
  • Parameters:
    • path (TPath): The path to the desired value.
  • Returns: The value at the specified path.
getAll(): T
  • Description: Retrieves the entire configuration object.
  • Returns: The entire configuration object.
getConfigParts(): { localConfig: object; config: object; envConfig: object }
  • Description: Retrieves different parts of the configuration object before being merged and validated. Useful for debugging.
  • Returns: An object containing the localConfig, config, and envConfig parts of the configuration.
    • localConfig: The local configuration object.
    • config: The remote configuration object.
    • envConfig: The environment configuration object.
getResolvedOptions(): BaseOptions
  • Description: Retrieves the resolved options from the configuration object. Useful for debugging.
  • Returns: The resolved options, which are an instance of BaseOptions.
initializeMetrics(registry: promClient.Registry): void
  • Description: Initializes the metrics for the configuration.
  • Parameters:
    • registry (promClient.Registry): The prometheus registry to use for the metrics.

Configuration Options

This package allows you to configure various options for loading and managing configurations. Below are the available options and their descriptions.

Options

schema

  • Type: T extends SchemaWithType
  • Optional: false
  • Description: The schema of the configuration object.

configName

  • Type: string
  • Optional: true
  • Description: The name of the remote configuration.
  • Environment Variable: CONFIG_NAME

version

  • Type: 'latest' | number
  • Optional: true
  • Default: latest
  • Description: The version of the remote configuration. It can be either 'latest' or a number.
  • Environment Variable: CONFIG_VERSION

configServerUrl

  • Type: string
  • Optional: true
  • Default: http://localhost:8080
  • Description: The URL of the configuration server.
  • Environment Variable: CONFIG_SERVER_URL

offlineMode

  • Type: boolean
  • Optional: true
  • Default: false
  • Description: Indicates whether the configuration should be loaded in offline mode.
  • Environment Variable: CONFIG_OFFLINE_MODE

ignoreServerIsOlderVersionError

  • Type: boolean
  • Optional: true
  • Description: Indicates whether to ignore the error when the server version is older than the requested version.
  • Environment Variable: CONFIG_IGNORE_SERVER_IS_OLDER_VERSION_ERROR

localConfigPath

  • Type: string
  • Optional: true
  • Default: ./config
  • Description: The path to the local configuration folder.

Environment Variable Configuration

The following environment variables can be used to configure the options:

  • CONFIG_NAME: Sets the configName option.
  • CONFIG_VERSION: Sets the version option.
  • CONFIG_SERVER_URL: Sets the configServerUrl option.
  • CONFIG_OFFLINE_MODE: Sets the offlineMode option.
  • CONFIG_IGNORE_SERVER_IS_OLDER_VERSION_ERROR: Sets the ignoreServerIsOlderVersionError option.

Configuration Merging and Validation

The package supports merging configurations from multiple sources (local, remote, and environment variables) and then validates the merged configuration against the schema.

Local Configuration

  1. The local configuration is loaded from the path specified by the localConfigPath option. The default path is ./config.

Remote Configuration

  1. The remote configuration is fetched from the server specified by the configServerUrl option.
  2. If the version is set to 'latest', the latest version of the configuration is fetched. Otherwise, the specified version is fetched.

Environment Variables

Configuration options can be overridden by setting the corresponding environment variables as described in schema using the x-env-value key.

Merging Configurations

  1. The configurations are merged in the following order of precedence:

    • Environment variables
    • Remote configuration
    • Local configuration
  2. If a configuration option is specified in multiple sources, the value from the source with higher precedence (as listed above) is used.

Validation

  1. After merging, the final configuration is validated against the defined schema using ajv.
  2. The validation ensures that all required properties are present, and the types and values of properties conform to the schema.
  3. Any default value according to the schema is added to the final object.
  4. If the validation fails, an error is thrown, indicating the invalid properties and their issues.

Error handling

This section describes the possible errors that can occur when using the package, along with their codes and payload structures.

Identifying errors

The package exposes a helper function called isConfigError to assert what is the error that was thrown and handle it as needed.

import { config, isConfigError } from '@map-colonies/config';

try {
  const configInstance = await config({
    configName: 'boiler-config',
    configServerUrl: 'http://localhost:8080',
    schema: commonBoilerplateV4,
    version: 'latest',
    offlineMode: false
  });
  
} catch (error) {
  if (isConfigError(error, 'configValidationError')) {
    console.error('Config validation error:', error.payload);
  }
}

Errors

optionValidationError

  • Code: 1
  • Payload: ValidationError[]
  • Description: This error occurs when there is a validation error with one of the configuration options.

configValidationError

  • Code: 2
  • Payload: ValidationError[]
  • Description: This error occurs when the configuration as a whole fails validation.

httpResponseError

  • Code: 3
  • Payload:
    {
      headers: Record<string, string>;
      statusCode: number;
      body: string;
    }
  • Description: This error occurs when an HTTP request results in an error response. The payload includes the response headers, status code and body.

httpGeneralError

  • Code: 4
  • Payload: Error
  • Description: This error occurs when there is a general HTTP error. The payload contains the error object.

schemaNotFoundError

  • Code: 5
  • Payload:
    {
      schemaPath: string;
    }
  • Description: This error occurs when the specified schema cannot be found. The payload includes the path of the missing schema.

schemasPackageVersionMismatchError

  • Code: 6
  • Payload:
    {
      remotePackageVersion: string;
      localPackageVersion: string;
    }
  • Description: This error occurs when there is a version mismatch between the remote and local schema packages. The payload includes the versions of both the remote and local packages.

schemaVersionMismatchError

  • Code: 7
  • Payload:
    {
      remoteSchemaVersion: string;
      localSchemaVersion: string;
    }
  • Description: This error occurs when there is a version mismatch between the remote and local schemas. The payload includes the versions of both the remote and local schemas.

promClientNotInstalledError

  • Code: 8
  • Payload: Error
  • Description: This error occurs when the prom-client package is not installed. The payload contains the error object.

Debugging

If for some reason you want to debug the package you can either use the getConfigParts or the getResolvedOptions functions described in the API or use the more powerful debug logger.

The package debug logger is implemented using the debug npm package and is configured using the DEBUG Environment variable.

The following are the values you can configure to use the debug option.

DEBUG=*

Enables all the logs. Note that setting this option might enable debug logging of other packages.

DEBUG=@map-colonies/config*

Enables all the logs available in this package.

DEBUG=@map-colonies/config:config

Enables only the logs related to the main logic of the package.

DEBUG=@map-colonies/config:env

Enables only the logs related to parsing environment variables from schemas, and retrieving them for use in the configuration.

DEBUG=@map-colonies/config:http

Enables only the logs related to http requests to the config-server.

DEBUG=@map-colonies/config:options

Enables only the logs related to parsing and validation of the package initialization options.

DEBUG=@map-colonies/config:schemas

Enables only the logs related to the retrieving of schemas.

DEBUG=@map-colonies/config:validator

Enables only the logs related to the validation of configurations.