Helpers and common tools for the hpi school-cloud.
Last updated 19 days ago by tofixx .
MIT · Repository · Original npm · Tarball · package.json
$ cnpm install @schul-cloud/commons 
SYNC missed versions from official npm registry.


npm version Test Action Deployment Action Codacy Badge


npm install @schul-cloud/commons --save


npm install
npm test



The Configuration is a singleton that can be reused to hold a configuration that is validated by JSON Schema. A JSON-Schema has to be defined as default.schema.json inside a config folder.

The configuration is build by parsing multiple sources in the following order (Last definition overrides definition from before):

  1. defaults from default.schema.json
  2. defaults from default.json (values have to be defined here, for properties required in the schema too beside the schema default)
  3. NODE_ENV.json from config folder (defaults to development.json, if NODE_ENV is not defined - the file existence is optionally)
  4. .env file from execution/project root directory
  5. existing environment variables finally override everything from before.

The default schema parser options

  1. remove all options from upper sources if the schema contains the property "additionalProperties": false
  2. applying default values
  3. do a type conversion especially for string to type conversion values not defined in the json files (string to X).

Invalid input values will raise an error by default.

To enable multiple inherited objects when parsing environment variables there may be a dot notation be used. When enabled, this gets applied for export, has, and get too. Currently only __ (double underscore) is supported as separator due to the dependency dotenv and bad support of . (single dot) in many terminals.

Specifying Dependencies

Often specific configuration options are required based on the state of other configuration values. These dependencies can be defined using the if/then/else keywords.

In the example below the rule SERVICE_REQUIRES_OTHER rule is activated in the allOf block. The rule itself is defined in the definitions block. If the property SERVICE_PROPERTY is set to VALUE_OF_SERVICE we also require that OTHER_PROPERTY is set. Make sure that a default value is set for SERVICE_PROPERTY to avoid passing undefined to an if keyword.



    "title": "Example Schema with dependency",
    "description": "This schema declares a dependency between two properties.",
    "additionalProperties": false,
    "type": "object",
    "properties": {
            "type": "string",
            "enum": ["none", "VALUE_OF_SERVICE"],
            "default": "none"
        "OTHER_PROPERTY": {
            "type": "string"
    "allOf": [
            "$ref": "#/definitions/SERVICE_REQUIRES_OTHER"
    "definitions": {
            "if": {
                "properties": {
                    "SERVICE_PROPERTY": {
                        "const": "VALUE_OF_SERVICE"
            "then": {
                "required": [


    "$schema": "default.schema.json",


// Access Configuration as Singleton, using default export
// Initialization is done on first access
// uses IConfigOptions optionally defined in a sc-config.json file
import { Configuration as config } from "@schul-cloud/commons";

// Access configuration as class
// IConfigOptions can be set in constructor options
import { TestConfiguration } from "@schul-cloud/commons";
const config = new TestConfiguration(options);

// Then you may run...
const before = config.toObject();
// and when the property key has been defined in the schema...
config.set("key", "value");
// or updating multiple entries

// suggested for testing only
config.remove("key"); // removes a single key
config.remove("key", "key2", ...); // remove multiple keys
// override the complete config (removes prior values)


Option key Value(s) or Type default Description
logger any console a logger instance
throwOnError boolean true enable throwing an error when an undefined configuration value is requested
notFoundValue any null if throwOnError is not set true, an alternate default value may returned
configDir string config directory where schema and configuration files are located
schemaFileName string default.schema.json default schema file name
baseDir string process.cwd() path to folder where configDir is located
ajvOptions object removeAdditional: 'true'
useDefaults: true
coerceTypes: 'array'
Schema Parser Options, see https://github.com/epoberezkin/ajv#options
useDotNotation boolean true enables dot notation for parsing environment variables (not json files!) and exporting the current config using has, get, and toObject.
fileEncoding string 'utf8' set file encoding for imported schema and configuration files

JSON Schema

Enhanced validation

Custom validation keywords may be added to get detailed error messages for specific checks: https://medium.com/@moshfeu/test-json-schema-with-ajv-and-jest-c1d2984234c9


Multiple supported keywords exist in ajv to define dependencies.

Use cases

  • To apply NODE_ENV-specific defaults, use NODE_ENV.json-file in config folder
  • To apply global defaults, set default in schema file itself
  • To apply secrets, set values using .env file (never commit this file!)
  • To apply feature-flag conditions, see dependency keywords above.

Current Tags

  • 1.1.1                                ...           latest (19 days ago)

23 Versions

  • 1.1.1                                ...           19 days ago
  • 1.1.0                                ...           a month ago
  • 1.0.20                                ...           a month ago
  • 1.0.19                                ...           2 months ago
  • 1.0.18                                ...           2 months ago
  • 1.0.17                                ...           2 months ago
  • 1.0.16                                ...           3 months ago
  • 1.0.15                                ...           3 months ago
  • 1.0.14                                ...           3 months ago
  • 1.0.13                                ...           5 months ago
  • 1.0.12                                ...           6 months ago
  • 1.0.11                                ...           6 months ago
  • 1.0.10                                ...           6 months ago
  • 1.0.9                                ...           6 months ago
  • 1.0.8                                ...           6 months ago
  • 1.0.7                                ...           6 months ago
  • 1.0.6                                ...           6 months ago
  • 1.0.5                                ...           6 months ago
  • 1.0.4                                ...           6 months ago
  • 1.0.3                                ...           6 months ago
  • 1.0.2                                ...           6 months ago
  • 1.0.1                                ...           6 months ago
  • 1.0.0                                ...           6 months ago
Today 0
This Week 0
This Month 16
Last Day 0
Last Week 0
Last Month 28
Dependencies (6)
Dependents (0)

Copyright 2014 - 2017 © taobao.org |