nn-type-cast v1.3.0

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.

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

Usage

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<symbol | string | number, TemplateKey>, 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.

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

Usage

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<ContentInterface>( dataTemplate, data1, data2 ); // Returns { key: 'Abc', value1: 'Xyz', value2: '', value3: '' }