A generic unit parser/formatter
# Using npm
npm i gen-unit
# Using yarn
yarn add gen-unit
Creates a parse
function using the given options.
function createParser(options): ParseFunction;
type ParseFunction = (input: string | number | object) => number;
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 mg'); // => 0.001
parse('1 K'); // => 1000
parse('1 Kg'); // => 1000
parse('1 ms'); // => NaN
- Precedence
This option takes precedence over any prefix or prefixed unit.
examples
const parse = createParser({
unit: 'm',
});
parse('1 m'); // => 1 (not 0.001)
parse('1 mm'); // => 0.001
const parse = createParser({
unit: 'eg', // assume "eg" is the unit... for some reason
});
parse('1 meg'); // => 0.001 (not 1000000)
parse('1 megeg'); // => 1000000
parse('1 Meg'); // => 1000000
The "find"
option describes how to find the number
by which the parsed value should be multiplied.
- "find" option as an object
find: {
base?: number;
find?: Array<{ pre: string; exp: number }>;
};
default: {
base: 1000,
find: [
{ pre: 'f', exp: -5 },
{ pre: 'p', exp: -4 },
{ pre: 'n', exp: -3 },
{ pre: 'u', 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 },
],
}
An object describing the base
and unit prefixes
to find the multiplier
.
example
const parse = createParser({
find: {
base: 1024,
find: [
{ 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 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 the different units prefixes
.
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
- "find" option as a function
find: (unit: string) => number;
A function that returns a number
by which the parsed value should be multiplied based on the captured unit
.
example
const parse = createParser({
find: (unit) => {
if (unit === 'K' || unit === 'k') {
return 1024;
} else if (unit === 'M') {
return 1024 ** 2;
}
},
});
parse('2'); // => 2
parse('2 K'); // => 2048
parse('2 M'); // => 2097152
parse('2 G'); // => NaN
Creates a format
function using the given options.
function createFormatter(options): FormatFunction;
type FormatFunction = (input) => string;
The "unit"
option defines the unit
to be used during formatting.
- "unit" option as a string
unit: string;
A string
to be used as main unit
.
example
const format = createFormatter({
unit: 'm',
});
format(100); // => '100 m'
format(0.0012); // => '1.2 mm'
format(1200); // => '1.2 Km'
- "unit" option as a function
unit: (value: number, rounded: string | number, pre: string) => string;
A function
that returns
the unit
based on parameters.
example
const format = createFormatter({
unit: (value, rounded, pre) => {
return '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
based on input value.
- "find" option as an object
find: {
base?: number;
find?: Array<{ exp: number; pre: string }>;
}
default: {
base: 1000,
find: [
{ 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' },
],
}
example
const format = createFormatter({
find: {
base: 1024,
find: [
{ exp: 0, pre: '' },
{ exp: 1, pre: 'K' },
],
},
});
format(100); // => '100'
format(2048); // => '2 K'
format(2097152); // => '2048 K'
- "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<{ exp: number; pre: string }>;
An array
of objects
describing the different unit prefixes
.
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 a function
find: (value: number) => { div: number; pre: string };
A function
that returns
an object
describing the unit prefix
.
example
const format = createFormatter({
find: (value) => {
if (value >= 1000) {
return { pre: 'K', div: 1000 };
} else {
return { pre: '', div: 1 };
}
},
});
format(2); // => '2'
format(2000); // => '2 K'
format(2000000); // => '2000 K'
The "round"
option describes how to round the value.
- "round" option as an object
round: {
dec?: number;
fixed?: boolean;
};
default: {
dec: 2,
fixed: false,
};
An object
describing how to format the value.
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(1230); // => '1.2 K'
format(0.00123); // => '1.2 m'
- "round" option a function
round: (num: number) => (string | number);
A function
that returns
a rounded value.
example
const format = createFormatter({
round: Math.round,
});
format(1.23); // => '1'
format(1230); // => '1 K'
format(0.00123); // => '1 m'
A function
to format the final output.
output: (value: string | number, pre: string, unit: string) => (string | number);
example
const format = createFormatter({
output: (value, pre) => `${value}${pre}s`,
})
format(1.23); // => '1.23s'
format(1230); // => '1.23Ks'
format(0.00123); // => '1.23ms'
A convenient function to parse an input in one step.
function parse(input, options): number;
A convenient function to format a number
in one step.
function format(input, options): string;