transformed

transformed ⚡

A lightweight, low-level, performant, customizable object transformer utility.

• Custom parsers per prop.
• Custom output transformer.
• Built-in value map support.
• Multi-key support.
• Post-instantiation configuration.

Install

npm i transformed

Usage

import transformed from 'transformed'

const myTransformer = transformed()

myTransformer({ foo: 'bar' })

By default transformed won't do anything with your data, you need to define your rules:

• props: definitions of how to process which prop
• outputTransformer: how to process your output

Options

• autoCamelCase (default: false): automatically adds support for camelCase versions of the passed prop names.
• hasOwnPropertyCheck (default: false): for a slight performance improvement we're not doing hasOwnProperty checks by default, but you can enable for cases when not using simple objects as input.

API

(InputObject): Whatever registry: Map<string, Definition> outputTransformer: OutputTransformer options: Partial setOptions(options: Partial): TransformedFn setOutputTransformer(outputTransformer: OutputTransformer): TransformedFn setProps(props: Props): TransformedFn toValue(prop: string, value: unknown)

transformed() (default export)

A constructor method to create your transformer instance.

setOptions()

Set options for your instance.

const myTransformer = transformed()
myTransformer.setOptions({
    autoCamelCase: true,
    foo: 'bar'
})

You may add custom config keys/values. You can access these options inside your property parsers and output transformer.

setOutputTransformer()

Set outputTransformer for your instance.

const myOutputTransformer = ...
const myTransformer = transformed()
myTransformer.setOutputTransformer(myOutputTransformer)

Output transformers always should be set before calling setProps because they have the capability to alter prop names when registering them.

setProps()

Set supported properties for your instance.

Properties defined in "Babel config fashion". Arrays of property descriptors.

// All props
;[
    // Property
    [
        // Property names
        ['p', 'pad', 'padding'],
        // Value map for this property. Use `null` or leave emoty if not needed.
        { large: '30px' },
        // Value parsers
        [input => output]
    ]
]

const props = [
    [['p', 'pad', 'padding'], { large: '30px' }],
    [['bg', 'background'], { cars: 'cars.png' }, [(input, prop) => ({ [prop]: `http://mysite.com/images/${input}` })]]
]

const transform = transformed().setProps(props)

transform({
    padding: 'large',
    background: 'cars'
})

// Output: { padding: '30px', background: 'http://mysite.com/images/cars.png' }

toValue()

Sometimes you just want to get a value for a prop/value pair.

myTransformer.toValue('padding', 'large')

Creating Object Transformers

Object transformer is just a single function with static properties that loops through each property and values using the following API:

• myOutputTransformer(): returns your transformed output, receives the following arguments:
  • output: currently generated output in current iteration (on first iteration it's defaultOutput)
  • value: the generated value in the current iteration
  • prop: the prop name for the current iteration
  • inputObject: the original object passed to transformed
  • transformedFn: current transformed instance used for this iteration
• defaultOutput(): mandatory function returning the default output
• unsupportedHandler(): optional you may specify a handler for unsupported (not registered) properties; receives same arguments as your outputTransformer function
• camelCaseReducer: optional reducer function to alter how generated camelCase keys stored; parameters are the same as for a normal array.reduce callback (accumulator, currentValue, index) transformed will simply push it into the existing key list

See Complete Example for details on usage.

Creating parsers

Parsers are telling how to process values for a certain property. You can apply as many parser functions as you want, during generation the next function will get the previous function's output value (pipe).

The parser function receives the following arguments:

• value: initial value, or the previous parser's output
• prop: property name,
• transformedFn: transformed instance
• inputObject: original input object
• definition: definition object stored in the property registry for this prop

const alwaysBar = (input, prop) => ({ [prop]: 'bar' })
const myTransformer = transformed().setProps([[['foo'], null, [alwaysBar]]])

myTransformer({ foo: 'baz' })

// Output: { foo: 'bar' }

See Complete Example for more advanced details on usage.

Handling unsupported (un-registered) values

Keys that don't have registered handler ignored by default. However, you can tell which key's you want to proceed with.

This can be useful for example when dealing with CSS, and you need to pass some ancient or browser specific style property.

You have tu use the prop key: unsupported which can be:

• true: all props allowed
• string[]: list of props to allow
• string: a single prop to allow

// `-moz-*` will be ignored
{
    padding: '10px',
    '-moz-border-radius': '10px',
    '-moz-foo-bar': 12
}

// only `-moz-foo-bar` will be ignored
{
    padding: '10px',
    '-moz-border-radius': '10px',
    '-moz-foo-bar': 12
    unsupported: '-moz-foo-bar'
}

// allow all
{
    padding: '10px',
    '-moz-border-radius': '10px',
    '-moz-foo-bar': 12
    unsupported: true
}

// specify what's allowed
{
    padding: '10px',
    '-moz-border-radius': '10px',
    '-moz-foo-bar': 12
    unsupported: ['-moz-foo-bar', '-moz-border-radius']
}
   

Complete example

Let's see a simple example to build string based CSS output for a Style Object:

const toCSSParser = (value, prop, transformedFn, inputObject, definition) => {
    // Let's always use the last key as CSS key
    const cssProperty = definition.keys[definition.keys.length - 1]
    return `${cssProperty}: ${value};\n`
}
// It'll just simply concat
const cssTransformer = (output, value) => `${output}${value}`
// Default output is just a string we will concat into
cssTransformer.defaultOutput = () => ''

const props = [
    [['p', 'pad', 'padding'], { large: '30px' }, [toCSSParser]],
    [['bg', 'background'], null, [toCSSParser]]
]

const myTransformer = transformed().setOutputTransformer(cssTransformer).setProps(props)

myTransformer({ p: 'large', bg: './cars.png' })

/**
 * Output:
 *
 * padding: 30px;
 * background: './cars.png'
 */

Show your support

Give a ⭐️ if this project helped you!

---

This README was generated with ❤️ by readme-md-generator