conversions

An Effect library to partially replace the native javascript INTL API.

Non machine-dependent, safe, bidirectional (implements parsing and formatting), tested, documented, with lots of examples, optimized for tree-shaking, 100% Typescript, 100% functional.

Can also come in handy to non-Effect users.

Donate

Any donations would be much appreciated 😄

Installation

Depending on the package manager you use, run one of the following commands in your terminal:

• Using npm:

  npm install effect @parischap/effect-lib @parischap/conversions

• Using pnpm:

  pnpm add effect @parischap/effect-lib @parischap/conversions

• Using yarn:

  yarn add effect @parischap/effect-lib @parischap/conversions

Package size and tree-shaking

This is a modern library optimized for tree-shaking. Don't put too much focus on package size: most of it will go away at bundling. To give you an idea of how this library will impact the size of your project, Bundlephobia announces a size of 15kB once minified and gzipped.

How to import?

This library supports named imports:

import { CVRoundingOption } from "@parischap/conversions";

and default imports:

import * as CVRoundingOption from "@parischap/conversions/CVRoundingOption";

In this documentation, we'll use the first option. But if you value tree-shaking, you should use the second.

API

After reading this introduction, you may take a look at the API documentation.

In this package

This package contains:

• a module to round numbers and BigDecimal's with the same rounding options as those offered by the javascript INTL API: Ceil, Floor, Expand, Trunc, HalfCeil...
• a safe, easy-to-use number/BigDecimal parser/formatter with almost all the options offered by the javascript INTL API: choice of the thousand separator, of the fractional separator, of the minimum and maximum number of fractional digits, of the rounding mode, of the sign display mode, of whether to show or not the integer part when it's zero, of whether to use a scientific or engineering notation, of the character to use as exponent mark... It can also be used as a Schema instead of the Effect.Schema.NumberFromString transformer.
• an equivalent to the PHP sprintf and sscanf functions with real typing of the placeholders. Although Effect.Schema does offer the TemplateLiteralParser API, the latter does not provide a solution to situations such as fixed length fields (potentially padded), numbers formatted otherwise than in the English format... This module can also be used as a Schema.
• a very easy to use DateTime module that implements natively the Iso calendar (Iso year and Iso week). It is also faster than its Effect counterpart as it implements an internal state that's only used to speed up calculation times (but does not alter the result of functions; so CVDateTime functions can be viewed as pure from a user's perspective). It can therefore be useful in applications where time is of essence.
• a DateTime parser/formatter which supports many of the available unicode tokens. It can also be used as a Schema instead of the Effect.Schema.Date transformer.
• a few brands which come in handy in many projects such as email, semantic versioning, integer numbers, positive integer numbers, real numbers and positive real numbers. All these brands are also defined as Schema's. Please read the Effect documentation about Branding if you are not familiar with this concept

Most functions of this package return an Either or an Option to signify the possibility of an error. However, if you are not an Effect user and do not care to learn more about it, you can simply use the OrThrow variant of the function. For instance, use CVDateTime.setWeekdayOrThrow instead of CVDateTime.setWeekday. As its name suggests, it will throw in case failure. Some functions return functions that return an Either or throw. In that case, the variant for non-Effect users contains the word Throwing, e.g. use CVDateTimeFormat.toThrowingFormatter instead of CVDateTimeFormat.toFormatter.