0.2.0 • Published 1 year ago

gen-unit v0.2.0

Weekly downloads
737
License
MIT
Repository
github
Last release
1 year ago

gen-unit

CircleCI npm codecov dependabot jsDelivr Libraries.io dependency status for latest release install size bundlephobia types Known Vulnerabilities license

A generic unit parser/formatter

Install

# Using npm
npm i gen-unit

# Using yarn
yarn add gen-unit

API

The createParser function

Creates a parse function using the given options.

function createParser(options): Parser;

type Parser = (input: unknown) => number;

createParser options

The unit option

Defines the unit to be used during parsing.

unit: string;

Example

const parse = createParser({
  unit: 'g',
});

parse('1'); // => 1
parse('1 g'); // => 1
parse('1 m'); // => 0.001
parse('1 mg'); // => 0.001
parse('1 k'); // => 1000
parse('1 kg'); // => 1000
parse('1 ms'); // => NaN because "s" is not recognized as unit

Precedence

This option takes precedence over any prefix or prefixed unit.

Examples

const parseMeter = createParser({
  unit: 'm', // Meter
});

parseMeter('1 m'); // returns 1 (1 meter)
parseMeter('1 mm'); // returns 0.001 (1 millimeter)
const parseSecond = createParser({
  unit: 's' // Seconds
});

parseSecond('1 m'); // returns 0.001 (1 millisecond)
parseSecond('1 ms'); // returns 0.001 (1 millisecond)
const parse = createParser({
  unit: 'eg', // assuming "eg" is the unit... for some reason
});

parse('1 meg'); // => 0.001 (not 1000000), it's interpreted as 1 milli-eg
parse('1 megeg'); // => 1000000, it's interpreted as 1 mega-eg
parse('1 Meg'); // => 1000000, it's interpreted as 1 mega-eg because capital "M" parses as mega

The match option

match: RegExp | string | MatchFunction;

type MatchFunction = (input: string) => [value: string, unit: string] | null | undefined;

default /^\s*(-?\d*\.?\d*(?:e[+-]?\d+)?)\s*([a-z\xb5]*)\s*$/i

Defines the first step in the parse process, it takes the input and should turn it into an array with two elements with the value, and the unit to be process further down the road, or null (or undefined) if the input can't be parsed.

match option as a RegExp
match: RegExp;

default /^\s*(-?\d*\.?\d*(?:e[+-]?\d+)?)\s*([a-z\xb5]*)\s*$/i

A RegExp with two capturing groups, the first to be used as value and the second as unit. If the RegExp has less than two capturing groups, parse function will throw.

Example

const parse = createParser({
  match: /^\s*([\d.]+)\s*([a-z]*)\s*$/i,
});

parse('1 m'); // => 0.001
parse('1 k'); // => 1000
match option as a string
match: string;

A string to be used to create a RegExp. It is expected to have two capturing groups, the first to be used as value and the second as unit.

Example

const parse = createParser({
  match: '^\\s*([\\d.]+)\\s*([a-z]*)\\s*$',
});

parse('1 m'); // => 0.001
parse('1 k'); // => 1000
match option as a function
match: (input: string) => [value: string, unit: string] | null | undefined;

A function which will receive the input and should return an array of two elements, the first to be used as value and the second as unit, or null (or undefined) if the input can't be parsed.

Example

const parse = createParser({
  match(input) {
    return [input, 'k']
  },
});

parse('1'); // => 1000
parse('2'); // => 2000

The find option

The find option describes how to find the multiplier which is the number by which the parsed value should be multiplied.

find option as a number
find: number;

A number to be used as base during parsing.

Example

const parse = createParser({
  find: 1024,
});

parse('2'); // => 2
parse('2 k'); // => 2048
parse('2 M'); // => 2097152
parse('2 G'); // => 2147483648
find option as an array
find: Array<{ pre: string; exp: number }>;

An array of objects describing prefixes and exponents to use with the default base (1000) to find the multiplier to be used during parsing. Every item should have a unique pre, if there are duplicates createParser will throw.

notes

Note that empty prefix ({ pre: '', exp: 0 }) is not necessary, as an empty prefix will result in multiplier = 1

Example

const parse = createParser({
  find: [
    { pre: 'k', exp: 1 },
    { pre: 'M', exp: 2 },
  ],
});

parse('1.3'); // => 1.3
parse('1.3 k'); // => 1300
parse('1.3 M'); // => 1300000
parse('1.3 G'); // => NaN because prefix "G" can't be found
find option as an object
find: {
  base?: number;
  items?: Array<{ pre: string; exp: number }>;
};

default: {
  base: 1000,
  items: [
    { pre: 'a', exp: -6 },
    { pre: 'f', exp: -5 },
    { pre: 'p', exp: -4 },
    { pre: 'n', exp: -3 },
    { pre: 'u', exp: -2 },
    { pre: 'µ', exp: -2 },
    { pre: 'm', exp: -1 },
    { pre: 'k', exp: 1 },
    { pre: 'K', exp: 1 },
    { pre: 'meg', exp: 2 },
    { pre: 'M', exp: 2 },
    { pre: 'G', exp: 3 },
    { pre: 'T', exp: 4 },
    { pre: 'P', exp: 5 },
    { pre: 'E', exp: 6 },
  ],
}

An object describing the base and a series of objects describing prefixes and exponents to find the multiplier to be used during parsing. Every item in items array should have a unique pre, if there are duplicates createParser will throw.

Notes

Note that empty prefix ({ pre: '', exp: 0 }) is not necessary, as an empty prefix will result in multiplier = 1

Example

const parse = createParser({
  find: {
    base: 1024,
    items: [
      { pre: 'K', exp: 1 },
      { pre: 'M', exp: 2 },
    ],
  },
});

parse('1'); // => 1
parse('1 K'); // => 1024
parse('1 M'); // => 1048576
parse('1 G'); // => NaN
find option as a function
find: (pre: string) => number | null | undefined;

A function that should return a non-zero number by which the parsed value should be multiplied based on the captured prefix. Return null (or undefined) if multiplier can't be determined. It will cause the parse function to return NaN. If your function returns zero, negative number or any other invalid multiplier, parse function will throw a TypeError.

Example

const parse = createParser({
  find: (unit) => {
    if (unit === 'K' || unit === 'k') {
      return 1024;
    } else if (unit === 'M') {
      return 1024 ** 2;
    }
    // next line can be omitted
    // as it will return undefined anyway
    return null;
  },
});

parse('2'); // => 2
parse('2 k'); // => 2048
parse('2 K'); // => 2048
parse('2 M'); // => 2097152
parse('2 G'); // => NaN

Notes

Previous version of this library allow this function to return an object { mul: number } containing the multiplier. This behavior has been removed, it will throw instead.

The createFormatter function

Creates a format function using the given options.

function createFormatter(options): Formatter;

type Formatter = (input: number) => string;

createFormatter options

The unit option

A string to be used as main unit during formatting.

unit: string;

Example

const format = createFormatter({
  unit: 'm',
});

format(100); // => '100 m'
format(0.0012); // => '1.2 mm'
format(1200); // => '1.2 Km'

The find option

Describes how to find the unit prefix and divider based on input value.

find option as a number
find: number;

A number to be used as base during formatting.

Example

const format = createFormatter({
  find: 1024,
});

format(100); // => '100'
format(2048); // => '2 k'
format(2097152); // => '2 M'
find option as an array
find: Array<{ pre: string; exp: number }>;

An array of objects describing prefixes and exponents to use with the default base (1000) to find the prefix and multiplier to be used during formatting. Every item should have a unique exp, if there are duplicates createFormatter will throw.

Example

const format = createFormatter({
  find: [
    { exp: 0, pre: '' },
    { exp: 1, pre: 'K' },
  ],
});

format(2); // => '2'
format(2000); // => '2 K'
format(2000000); // => '2000 K'
find option as an object
find: {
  base?: number;
  items?: Array<{ exp: number; pre: string }>;
}

default: {
  base: 1000,
  items: [
    { exp: -6, pre: 'a' },
    { exp: -5, pre: 'f' },
    { exp: -4, pre: 'p' },
    { exp: -3, pre: 'n' },
    { exp: -2, pre: 'µ' },
    { exp: -1, pre: 'm' },
    { exp: 0, pre: '' },
    { exp: 1, pre: 'k' },
    { exp: 2, pre: 'M' },
    { exp: 3, pre: 'G' },
    { exp: 4, pre: 'T' },
    { exp: 5, pre: 'P' },
    { exp: 6, pre: 'E' },
  ],
}

An object describing the base and a series of objects describing prefixes and exponents to find the prefix and multiplier to be used during formatting. Every item in items array should have a unique exp, if there are duplicates createFormatter will throw.

Example

const format = createFormatter({
  find: {
    base: 1024,
    items: [
      { exp: 0, pre: '' },
      { exp: 1, pre: 'K' },
    ],
  },
});

format(100); // => '100'
format(2048); // => '2 K'
format(2097152); // => '2048 K'
find option as a function
find: (value: number) => { pre: string; mul: number };

A function that returns an object describing the unit prefix (pre) and multiplier (mul).

Example

const format = createFormatter({
  find: (value) => {
    if (value >= 1000) {
      return { pre: 'K', mul: 1000 };
    } else {
      return { pre: '', mul: 1 };
    }
  },
});

format(0.2); // => '0.2'
format(2); // => '2'
format(2000); // => '2 K'
format(2000000); // => '2000 K'

The round option

Describes how to round the output value before final format.

round option as an object
round: {
  dec?: number;
  fixed?: boolean;
};

default: {
  dec: 2,
  fixed: false,
};

An object describing how to round the value before final format. Describes the number of decimal (dec) and whether or not the output should have a fixed number of decimal (fixed).

Example

const format = createFormatter({
  round: {
    dec: 3,
    fixed: true,
  },
});

format(1.23); // => '1.230'
format(1230); // => '1.230 k'
format(0.00123); // => '1.230 m'
round option as a number
round: number;

A number defining the number of decimal places to round to.

Example

const format = createFormatter({
  round: 1,
});

format(1.23); // => '1.2'
format(1.28); // => '1.3'
format(1230); // => '1.2 k'
format(0.00123); // => '1.2 m'
round option as a function
round: (num: number) => (string | number);

A function which returns the rounded value.

Example

const format = createFormatter({
  round: Math.round,
});

format(1.23); // => '1'
format(1.75); // => '2'
format(1230); // => '1 k'
format(0.00123); // => '1 m'

The output option

Describes the final output format.

output: FormatOutputFunction | FormatOutputAdvancedOption;

type FormatOutputFunction = (value: string | number, prefix: string, unit: string) => string;

interface FormatOutputAdvancedOption {
  space: string;
}
output option as an object
output: {
  space?: string;
}

default {
  space: ' ';
}

Example

const format = createFormatter({
  output: {
    space: '-', // unrealistic, for demonstration only
  },
})

format(1.23); // => '1.23'
format(1230); // => '1.23-k'
format(0.00123); // => '1.23-m'
output option as a function

A function to format the final output.

output: (value: string | number, prefix: string, unit: string) => string;

Example

const format = createFormatter({
  unit: 'x',
  output: (value, pre) => {
    // ignore original unit and hardcode one
    return `${value}${pre}s`;
  },
});

format(1.23); // => '1.23s'
format(1230); // => '1.23ks'
format(0.00123); // => '1.23ms'

The parse function

A convenient function to parse an input in one step. I will internally call createParser then will call the newly created parser. See createParser options.

function parse(input, options): number;

The format function

A convenient function to format a number in one step. It wil internally call createFormatter then will call the newly created formatter. See createFormatter options.

function format(input, options): string;

The MICRO constant

A constant containing the micro symbol ("µ"). Used internally, exported for convenience.

License

MIT © 2019-2024 Manuel Fernández

genericunitunitsparseparserformatformatter
@everything-registry/sub-chunk-1730@zalastax/nolb-gen-bundlib
0.1.0

1 year ago

0.2.0

1 year ago

0.0.6

5 years ago

0.0.5

6 years ago

0.0.4

6 years ago

0.0.3

6 years ago

0.0.2

6 years ago

0.0.1

6 years ago