README

split-node-serializer

Fetches split definitions and segments from Split.io and serializes them into a set of strings that the JavaScript SDK can consume.

Installation

Install via npm:

$ npm i @godaddy/split-node-serializer --save

Usage

Use this package in your server-side Node.js environment. The serializer exposes:

a Poller that periodically requests raw experiment configuration data from Split.io. Requests happen in the background and the poller caches the latest data in local memory.
a DataSerializer that reads from the poller's cache, serializes the data, and returns it in a script to be injected into a client's HTML.

Constructor

Create an instance of Poller and DataSerializer:

const { Poller, DataSerializer } = require('@godaddy/split-node-serializer')

const poller = new Poller({
  splitioApiKey: 'YOUR_API_KEY',
  pollingRateSeconds: 600,
  serializeSegments: false
})

const dataSerializer = new DataSerializer({ poller })

The following option properties are available to the Poller:

Property	Description
splitioApiKey	The Split.io SDK key for the environment your app is running in. (required)
pollingRateSeconds	The interval at which to poll Split.io. Defaults to 300 (5 minutes).
serializeSegments	Whether or not to fetch segment configuration data. Defaults to false.

Serializing segments

Segments are pre-defined groups of customers that features can be targeted to. More info here.

Note: Requesting serialized segments will increase the size of your response. Segments can be very large if they include all company employees, for example.

Methods

start

Make an initial request for changes and start polling for raw configuration data every pollingRateSeconds:

poller.start()

stop

To stop the poller:

poller.stop()

The poller emits an error event on errors from the Split.io API.

generateSerializedDataScript

generateSerializedDataScript is an async method that will read the latest data from the cache and return a script that adds serialized data to the window.__splitCachePreload object. The serialized data will be used to determine cohort allocations.

generateSerializedDataScript accepts the following arguments:

Property	Description
splits	Array of strings that, if included, filters the splitsData (Optional)
preloadLocation	The property on the `window` object where the data is stored. Defaults to `__splitCachePreload` (Optional)

const serializedDataScript = await dataSerializer.generateSerializedDataScript()

console.log(serializedDataScript)

//<script>
//  window.__splitCachePreload = {
//    splitsData: {"split-1-name":'{"name":"split-1-name","status":"bar"}',"split-2-name":'{"name":"split-2-name","status":"baz"}'},
//    since: 1,
//    segmentsData: {"test-segment":'{"name":"test-segment","added":["foo","bar"]}'},
//    usingSegmentsCount: 2
//  };
//</script>

Note: Though this is an async method, there will only be a Split.io API call if you have serializeSegments set to true and are passing in a unique splits parameter that this instance's method has not received before.

Testing

Run the linter:

$ npm run lint

Run unit tests:

$ npm test

Generate a coverage report:

$ npm run coverage

License

MIT

Usage no npm install needed!