@naturalcycles/scrubber-lib

Scrub data in JavaScript plain objects by using rules defined in a configuration object

How to use

Install it:

yarn add -D @naturalcycles/scrubber-lib

Define a scrubber configuration object:

import { ScrubberConfig, Scrubber } from '@naturalcycles/scrubber-lib'

const cfg: ScrubberConfig = {
  fields: {
    name: {
      scrubber: 'staticScrubber',
      params: {
        replacement: 'John Doe',
      },
    },
    password: {
      scrubber: 'undefinedScrubber',
    },
  },
  throwOnError: true, // default: false,
  preserveFalsy: false, // default: true
}

Scrub a single object:

const object = { name: 'Real Name', password: 'secret' }

const scrubber = new Scrubber(cfg)
const scrubbedObject = scrubber.scrub(object)

// scrubbedObject =  name: 'John Doe', password: undefined }

Scrub an array of objects:

const objects = [object1, object2, object3]

const scrubbedObjects = scrubber.scrub(objects)

Public API

constructor (private cfg: ScrubberConfig, additionalScrubbersImpl?: ScrubbersImpl)
scrub<T> (data: T): T

Features

Objects are deep traversed
Immutable changes (does not mutate the original object)
TypeScript library, compatible both on browsers and NodeJS
Fields are scrubbed if object keys match the field names on the configuration file
Provides a few built-in scrubber functions
Allows additional scrubber functions
Validates config object on class initialization to ensure all defined scrubber functions exist
Supports field names to be comma-separated on configuration file
Error handling: all errors are logged and allows a cfg.throwOnError optional configuration to re-throw errors
Falsy values: allows a cfg.preserveFalsy optional configuration to control if falsy values should be preserved or passed to scrubber functions. When inspecting scrubbed objects for debugging purposes, it might be useful to set it to true to identify potential interesting fields
[since 2.9] - support matching key only if parent key name(s) also match. Supported using dots . in key name. Config with key a.b will match object key literally AND it will match object key b if parent object key was a. Works at arbitrary depth. LIMITATION: parent matching currently assumes final key (b) is unique. If multiple parent references end with the same key (e.g. a.b & c.b), only last one will work.

Limitations

Objects of types Map, Set and Buffer are currently not traversed or modified

The scrubber-lib supports a ScrubberConfig parameter on initialization which is usually defined by clients on a scrubber configuration file (YAML or JSON) with multiple scrubbing profiles (such as anonymization, pseudonymization, etc).

The library applies scrubber functions to the given objects. It provides some built-in scrubber functions while also allowing custom scrubber functions implementations.

Possible use cases

Allows, for example, removal of sensitive data for:

Logs
Error reporting to third-party services
Data exports (such as staging or other data exports)
Anonymizing production users (GDPR "right to be forgotten")

@naturalcycles/scrubber-lib