Environment

An Asynchronous Environment Manager for JavaScript and TypeScript Applications.

About The Project

This library provides tools to manage environment properties in browser based JavaScript and TypeScript applications.

The common way to manage the application properties in browser based JavaScript frameworks is to define environment values in a constant or env file and load them at build stage. This strategy is not suitable for developments where, for example, the final build is deployed in a repositoy manager such as Nexus or Artifactory and reused in diferent environments, or in a microservices architecture where the properties are loaded from a config manager service. This library addresses this and other gaps by allowing, among others, the following behaviors:

• Get properties from constants
• Get properties from local sources, such as files
• Get properties from remote HTTP sources, such as a REST API
• Get properties from remote streaming sources, such as a WebSocket server
• Get properties from sources with interdependencies
• Get properties from multiple sources in order, unordered or by mixing strategies
• Stop source or application loading after a trigger
• Wait until required sources or properties are setted to load the application
• Define if the properties from a source should overwrite the existing ones or to merge with them
• Manage the loading lifecycle with hooks
• Implement a middleware to intercept the added properties

Getting Started

Installation

Using NPM

npm install --save @kuoki/environment

Using Yarn

yarn add @kuoki/environment

Dependencies

• rxjs >= 7.0.0

Usage

The steps to generate an environment manager are described below. Each of the steps is described in depth, with examples and common hacks, in the documentation of each module.

1. Implement and instantiate an EnvironmentStore to store the environment properties.
2. Implement and instantiate an EnvironmentService to mutate the environment state.
3. Implement and instantiate an EnvironmentQuery to get the environment properties.
4. Implement and instantiate as many EnvironmentSource as needed to get the environment properties.
5. Implement and instantiate an EnvironmentLoader to get the properties from the sources.

There is a faster way to get started if you want to use all the default implementations, which is to use createEnvironmentModule(), a factory that creates an EnvironmentModule and starts the load of properties.

import { createEnvironmentModule, EnvironmentModule, EnvironmentQuery, EnvironmentSource } from '@kuoki/environment';

// env.json = { userName: 'JohnDoe01' }
const fileSource: EnvironmentSource = {
  isRequired: true,
  load: async () => fetch('env.json').then((response) => response.json())
};
const constSource: EnvironmentSource = {
  isRequired: true,
  load: () => [{ name: 'John Doe' }]
};
const environmentModule: EnvironmentModule = await createEnvironmentModule([fileSource, constSource]);
export const env: EnvironmentQuery = environmentModule.query;

env.getAll(); // {name:'John Doe',userName:'JohnDoe01'}

Contributing

In order to better manage all the contributions it is important that, when creating a new issue or discussion, the label environment is added (as well any other required) and to follow the Code of Conduct.

• 🐛 If you want to track or report an issue in the code or documentation use the Environment Issues.
• 💡 If you want to track or discuss new features or share new ideas use the Environment Ideas discussion forum.
• 🙏 If you want to track or get support use the Environment Q&A discussion forum.
• 🙌 If you want to track or show off what you have been able to do use the Environment Show and tell discussion forum.
• 🤝 If you want to contribute fixing issues or with new features you can create a pull request with the new code.