nn-type-cast

> Common type casting functions.

Type Casting Functions

* toPrimitive( value: unknown, default?: string | number | boolean ): string | number | boolean | undefined
* Converts a value to a primitive value (i.e. string, number, boolean, null or undefined).

* toBoolean( value: unknown, default?: boolean = false ): boolean
* Converts a value to a boolean.

* toInteger( value: unknown, default?: number = 0 ): number
* Converts a value to a integer.

* toNumber( value: unknown, default?: number = 0 ): number
* Converts a value to a number.

* toString( value: unknown, default?: string = '' ): string
* Converts a value to a string.

* toArray<T>( value: unknown, default?: T[] = [] ): T[]
* Converts a value to a array.
* Note: When using TypeScript the default return type for toArray is unknown[]. It is preferred to specify a type (e.g. toArray<string>).

* toRegExp( value: unknown, default?: RegExp ): RegExp
* Converts a value to a Regular Expression.
* If value and default are undefined then nn-type-cast:reg-exp-undefined will be thrown.

``javascript
import { toPrimitive } from 'nn-type-cast';
import { toBoolean } from 'nn-type-cast';
import { toInteger } from 'nn-type-cast';
import { toNumber } from 'nn-type-cast';
import { toString } from 'nn-type-cast';
import { toArray } from 'nn-type-cast';
import { toRegExp } from 'nn-type-cast';


toPrimitive( undefined, true ); // true
toPrimitive( '123' ); // true


toBoolean( undefined, true ); // true
toBoolean( '123' ); // true


toInteger( undefined, 123 ); // 123
toInteger( 4.56, 123 ); // 4
toInteger( '4.56', 123 ); // 4


toNumber( undefined, 123 ); // 123
toNumber( 4.56, 123 ); // 4.56
toNumber( '4.56', 123 ); // 4.56


toString( undefined ); // ''
toString( 123, 'ABC' ); // '123'
toString( '123', 'ABC' ); // '123'


toArray( undefined ); // []
toArray( 123, [ 123 ] ); // [ 123 ]
toArray( [ 123 ], [ 456 ] ); // [ 123 ]
toArray( [ 123 ] ); // [ 123 ]


toRegExp( undefined ); // Throws an 'nn-type-cast:reg-exp-undefined' exception.
toRegExp( undefined, /XYZ/i ); // /XYZ/i
toRegExp( 'ABC', /XYZ/i ); // /ABC/
toRegExp( '/ABC/i', /XYZ/i ); // /ABC/i
toRegExp( /ABC/i, /XYZ/i ); // /ABC/i
`

Mapping Function

> Re-maps object properties.

mapObjectProperties<Type>( mapping: object, source: object ): object
* mapping: object - Mapping
* source: object - Content

$3

`javascript
const mapping =
{
m: false, // No mapping.
n: true, // Map property 'n'.
x: 'a', // Map to property 'a'.
y: 'b', // Map to property 'b'.
z: 'c', // Map to property 'c'.
a: '#raw text', // Map to 'raw text'.
b: '${ "Abc": 123 }' // Map to JSON or raw text if not parsable.
};

const source =
{
a: 1,
b: 2,
c: 3,
m: 4,
n: 5
};

mapObjectProperties( mapping, source );
// Source maps to:
// {
// n: 5,
// x: 1,
// y: 2,
// z: 3,
// a: "raw text",
// b: { "Abc": 123 }
// }
`

Sanitize Function

> Sanitizes values of key/value pairs. To use sanitize create a template that defines the keys for the key/value pairs. Each key in the template must be a sanitizer function or a TemplateKey. Pass the template and the data to sanitize and, if desired, default data and sanitizer options.

sanitize<Type>( template: Record, source: unknown, defaults: Type, options?: SanitizeOptions ): Type - Returns object with sanitized values.
* template - The template.
* source - The source data to sanitize.
* defaults - The default values.

TemplateKey
* required - {boolean} indicate that the a value is required.
* default - {unknown} the default value.
* sanitizer - {( value: unknown ) => unknown} a function that sanitizes the value.

SanitizeOptions
* merger - {TemplateValueMergerFn} a function to control the value assigned to a key.



TemplateValueMergerFn - ( value1: unknown, value2: unknown) => unknown

> Two TemplateValueMergerFn are provided: overwriteValue will prioritize data values over default values, underwriteValue will prioritize default values over data values.

$3

`javascript
const dataTemplate =
{
'': { sanitizer: toString }, // (Optional): Use '' to apply to all props not defined in the template.
key: toString,
value1: { sanitizer: toString },
value2: { required: true, sanitizer: toString },
value3: { default: 'Abc', sanitizer: toString }
};

const data1 = {};

const data2 =
{
key: 'Abc',
value1: 'Def',
value2: 'Xyz'
};

sanitize( dataTemplate, data1 ); // Returns { key: '', value1: '', value2: '', value3: '' }
sanitize( dataTemplate, data2 ); // Returns { key: 'Abc', value1: 'Xyz', value2: '', value3: '' }
sanitize( dataTemplate, data1, data2 ); // Returns { key: 'Abc', value1: 'Xyz', value2: '', value3: '' }

// TypeScript
interface ContentInterface
{
key: string;
value1: string;
value2: string;
value3: string;
}

sanitize( dataTemplate, data1, data2 ); // Returns { key: 'Abc', value1: 'Xyz', value2: '', value3: '' }
``