configcat-common

What is configcat-common?

The configcat-common npm package is a client library for ConfigCat, a feature flag and configuration management service. It allows developers to manage feature flags and remote configurations in their applications, enabling them to toggle features on and off without deploying new code.

What are configcat-common's main functionalities?

Initialize ConfigCat Client

This feature allows you to initialize the ConfigCat client with your SDK key, which is necessary to interact with the ConfigCat service.

const { createClient } = require('configcat-common');
const client = createClient('YOUR-SDK-KEY');

Get Feature Flag Value

This feature allows you to retrieve the value of a feature flag. The method takes the feature flag key, a default value, and a callback function to handle the retrieved value.

client.getValue('isMyFeatureEnabled', false, (value) => {
  console.log('Feature flag value:', value);
});

Get Configuration Value

This feature allows you to retrieve the value of a configuration setting. Similar to feature flags, it takes the configuration key, a default value, and a callback function.

client.getValue('myConfigKey', 'defaultValue', (value) => {
  console.log('Configuration value:', value);
});

Set User Context

This feature allows you to set the user context, which can be used to serve different configurations or feature flags based on the user.

const user = { identifier: 'user123', email: '[e-mail]' };
client.setUser(user);

Other packages similar to configcat-common

launchdarkly-node-client-sdk

LaunchDarkly is a feature management platform that allows you to control the release of features to users. It offers similar functionality to ConfigCat, such as feature flag management and user targeting. However, LaunchDarkly is generally considered to be more enterprise-focused with additional features like experimentation and advanced analytics.

unleash-client

Unleash is an open-source feature management solution. It provides similar capabilities for managing feature flags and configurations. Unleash is a good alternative for those looking for an open-source solution with a self-hosted option.

flagr

Flagr is another open-source feature flagging and A/B testing tool. It allows you to create and manage feature flags and perform A/B testing. Flagr is suitable for teams looking for a customizable and self-hosted feature management solution.

README

ConfigCat SDK for node.js

ConfigCat is a cloud based configuration as a service. It integrates with your apps, backends, websites, and other programs, so you can configure them through this website even after they are deployed. https://configcat.com

Getting Started

1. Install NPM package: configcat-client-node

 npm i configcat-client-node

1. Get your Api Key from configcat.com portal:

2. Create a ConfigCatClient instance:

var configcat = require("configcat-client-node");

var client = configcat.createClient("#YOUR-API-KEY#");

1. Get your config value:

client.getValue("isMyAwesomeFeatureEnabled", false, {identifier : "userIdentifier"}, (value) => {
    if(value) {
        //show your awesome feature to the world!
    }
});

Configuration

Client supports three different caching policies to acquire the configuration from ConfigCat. When the client downloads the latest configuration, puts it into the internal cache and serves any configuration acquisition from cache. With these caching policies you can manage your configurations' lifetimes easily.

Auto polling (default)

Client downloads the latest configuration and puts into a cache repeatedly. Use pollingIntervalSeconds parameter to manage polling interval. You can subscribe to the configChanged event to get notification about configuration changes.

Lazy loading

Client downloads the latest configuration only when it is not present or expired in the cache. Use cacheTimeToLiveSeconds parameter to manage configuration lifetime.

Manual polling

With this mode you always have to invoke .forceRefresh() method to download a latest configuration into the cache. When the cache is empty (for example after client initialization) and you try to acquire any value you'll get the default value!

---

Configuration parameters are different in each mode:

Base configuration

PropertyName	Description	Default
apiKey	Api Key to access your configuration.	REQUIRED
logger	'winston' logger instance	no default tracing method

Auto polling

PropertyName	Description	Default
pollIntervalSeconds	Polling interval in seconds.	60
maxInitWaitTimeSeconds	Maximum waiting time between the client initialization and the first config acquisition in seconds	5
configChanged	event accessor to get notification about configuration changes	-

Lazy loading

PropertyName	Description	Default
cacheTimeToLiveSeconds	Use this value to manage the cache's TTL.	60

Example - increase CacheTimeToLiveSeconds to 600 seconds

var config = {
    "cacheTimeToLiveSeconds": 600
};

var client = configcat.createClientWithLazyLoad("#YOUR-API-KEY#", config);

Example - configChanged

In Auto polling mode you can subscribe an event to get notification about changes. We use "events" package to support event handling in our package.

var events = require("events");

var config = {    
    "configChanged": new events.EventEmitter()
};

config.configChanged.on(configcat.CONFIG_CHANGED_EVENT, () => console.log("config changed, update UI!"));

var client = configcat.createClientWithAutoPoll("#YOUR-API-KEY#", config);

Members

Methods

Name	Description
getValue(key: string, defaultValue: any, user: User, callback: (value: any) => void): void;	Returns the value of the key
forceRefresh(callback: () => void): void	Fetches the latest configuration from the server. You can use this method with WebHooks to ensure up to date configuration values in your application.

User object

If you want to get advantage from our percentage rollout and targeted rollout features, you should pass a user object to the getValue(key: string, defaultValue: any, user: user, callback: (value: any) => void) calls. We strongly recommend you to pass the user object in every call so later you can use these awesome features without rebuilding your application.

User

ParameterName	Description	Default
identifier	Mandatory, unique identifier for the User or Session. e.g. Email address, Primary key, Session Id	REQUIRED
email	Optional parameter for easier targeting rule definitions	None
country	Optional parameter for easier targeting rule definitions	None
custom	Optional dictionary for custom attributes of the User for advanced targeting rule definitions. e.g. User role, Subscription type.	None

Example simple user object:

var myUser = {
    identifier : "435170f4-8a8b-4b67-a723-505ac7cdea92"
};   

Example user object with optional custom attributes:

var myUser = {
    identifier : "435170f4-8a8b-4b67-a723-505ac7cdea92",
    email : "[e-mail]",
    country : "United Kingdom",
    custom : {
        "SubscriptionType": "Pro"
    }
};

Lifecycle of the client

We're recommend to use client as a singleton in your application.

Logging

We use Winston for logging you can setup with 'logger' attribute.

var config = {
    "logger": new winston.Logger({
            level: "info",
            transports: [
                new winston.transports.Console({ timestamp: true })
            ]})
};

License

MIT