@resolute/coerce

Coerce input to types and formats with sanitizers and validators.

Usage no npm install needed!

<script type="module">
  import resoluteCoerce from 'https://cdn.skypack.dev/@resolute/coerce';
</script>

README

Coerce

Coerce input to types and formats with sanitizers and validators.

Features

  • TypeScript friendly
  • Supports tree-shaking from Rollup, esbuild, etc.
  • ES Module and CommonJS support

Installation

npm i @resolute/coerce

Usage

import coerce, { string, safe, spaces, trim, nonEmpty } from '@resolute/coerce';
// sanitize input: removing dangerous characters, normalize double/half/utf
// spaces, trim whitespace, and confirm result is non-empty
const sanitize = coerce(string, safe, spaces, trim, nonEmpty);
  • failures throw a coerce TypeError
    sanitize(' foo '); // 'foo'
    sanitize('     '); // Uncaught TypeError
    
  • failures return default value (never throws)
    sanitize('     ', undefined); // undefined
    
  • failures throw error instance
    sanitize('     ', new Error('Oh no!')); // Uncaught Error: Oh no!
    
  • failures throw error factory
    class CustomError extends Error { }
    const errorFactory = (error: Error) => new CustomError(error.message);
    sanitize('     ', errorFactory); // Uncaught CustomError
    

Examples

Confirm a string value is within a list (enum)

import coerce, { within } from '@resolute/coerce';
const inList = coerce(within(['foo', 'bar'])); // any iterable type ok to use
try {
  inList(input);
  // input is either 'foo' or 'bar'
} catch (error) {
  // input was not 'foo' or 'bar'
}

Convert anything to an array

import coerce, { array } from '@resolute/coerce';
const arrayify = coerce(array);
  • Iterables (except strings) → Array
    arrayify(new Map([[1, 1], [2, 2]]); // [[1, 1], [2, 2]]
    arrayify(new Set([1, 2, 3])); // [1, 2, 3]
    arrayify(Buffer.from('123')); // [49, 50, 51] (char codes)
    // even though Strings are iterable, they are NOT broken apart
    arrayify('123'); // ['123']
    
  • Non-iterables (including strings) → [item] (wrapped in array)
    arrayify(1); // [1]
    arrayify(null); // [null]
    
  • Arrays → Array (no change)
    arrayify([1, 2, 3]); // [1, 2, 3]