@gmbeard/only-data v0.1.3

Only Data

Only Data will strip input down to just its data properties, removing "non-data" types such as functions and symbols. It works on primitive types, objects, arrays of objects, and nested graphs of objects.

Features:

• Circular reference protection is provided by either throwing (the default), or removing them.
• Ability to use a user-provided "reduction" function, allowing fine-grained control over the output.

Signature

onlyData(input[, options])

Parameters:
    input: Primitive | Object | Array<Any>
    options: Object | Array<String> | Function

Returns:
    Primitive | Object | Array<Any>

Usage

const { onlyData } = require("only-data");

const input = {
    name: "object",
    value: 42,
    invoke: function() { ... }
};

const data = onlyData(input);

// data: { name: "object", value: 42 }

Options

If options is a Array<String> then only properties matching these values will be included in the output.

If options is a Function then the function will be used as the reducer. See the Custom Reducer section.

If options is an object, it can contain the following settings...

Circular Reference Behaviour

By default, Only Data will throw an error whenever it encounters a circular reference. This will prevent costly stack overflows. You can control this behaviour using the circularReferences option.

circularReferences: "empty": Circular reference objects will be replaced with an empty object ({ })

const a = { name: "A" };
const b = { name: "B", val: a };
a.val = b; // This closes the loop and causes a circular reference

const data = onlyData(a, { circularReferences: "empty" });

// data: {
//   name: "A",
//   val: {
//     name: "B",
//     val: { }
//   }
// }

circularReferences: "error": An error will be thrown when a circular reference is detected. This is the default behaviour.

circularReferences: "indicate": Indicates circular references in the output by offending objects with { __circular: true }.

const a = { name: "A" };
const b = { name: "B", val: a };
a.val = b; // This closes the loop and causes a circular reference

const data = onlyData(a, { circularReferences: "remove" });

// data: {
//   name: "A",
//   val: {
//     name: "B",
//     val: { __circular: true }
//   }
// }

circularReferences: "remove": Removes circular reference objects from the graph altogether.

const a = { name: "A" };
const b = { name: "B", val: a };
a.val = b; // This closes the loop and causes a circular reference

const data = onlyData(a, { circularReferences: "remove" });

// data: {
//   name: "A",
//   val: {
//     name: "B",
//   }
// }

Custom Reducer

A custom reduction function has the signature (key: String, value: Any) -> Any. It will be called for each property of an object that needs to be reduced. Returning undefined from the custom reducer will cause the property to be ignored in the output.

function customReducer(key, value) {
    if (key === "propertyToIgnore")
        return;

    return value;
}

const data = onlyData(input, customReducer);