Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
convert-units
Advanced tools
convert-units - npm Package Compare versions
Comparing version 3.0.0-beta.2 to 3.0.0-beta.3
@@ -60,2 +60,3 @@ export interface Unit { | ||
| cutOffNumber?: number; | ||
| system?: TSystems; | ||
| }): BestResult | null; | ||
@@ -62,0 +63,0 @@ /** |
| "use strict"; | ||
| var __spreadArray = (this && this.__spreadArray) || function (to, from) { | ||
| for (var i = 0, il = from.length, j = to.length; i < il; i++, j++) | ||
| to[j] = from[i]; | ||
| return to; | ||
| var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) { | ||
| if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) { | ||
| if (ar || !(i in from)) { | ||
| if (!ar) ar = Array.prototype.slice.call(from, 0, i); | ||
| ar[i] = from[i]; | ||
| } | ||
| } | ||
| return to.concat(ar || Array.prototype.slice.call(from)); | ||
| }; | ||
@@ -112,3 +116,3 @@ Object.defineProperty(exports, "__esModule", { value: true }); | ||
| Converter.prototype.toBest = function (options) { | ||
| var _a, _b; | ||
| var _a, _b, _c; | ||
| if (this.origin == null) | ||
@@ -118,5 +122,7 @@ throw new Error('.toBest must be called after .from'); | ||
| var cutOffNumber = 1; | ||
| var system = this.origin.system; | ||
| if (typeof options === 'object') { | ||
| exclude = (_a = options.exclude) !== null && _a !== void 0 ? _a : []; | ||
| cutOffNumber = (_b = options.cutOffNumber) !== null && _b !== void 0 ? _b : 1; | ||
| system = (_c = options.system) !== null && _c !== void 0 ? _c : this.origin.system; | ||
| } | ||
@@ -129,8 +135,11 @@ var best = null; | ||
| */ | ||
| for (var _i = 0, _c = this.possibilities(); _i < _c.length; _i++) { | ||
| var possibility = _c[_i]; | ||
| for (var _i = 0, _d = this.possibilities(); _i < _d.length; _i++) { | ||
| var possibility = _d[_i]; | ||
| var unit = this.describe(possibility); | ||
| var isIncluded = exclude.indexOf(possibility) === -1; | ||
| if (isIncluded && unit.system === this.origin.system) { | ||
| if (isIncluded && unit.system === system) { | ||
| var result = this.to(possibility); | ||
| if (result < cutOffNumber) { | ||
| continue; | ||
| } | ||
| if (best == null || (result >= cutOffNumber && result < best.val)) { | ||
@@ -273,3 +282,3 @@ best = { | ||
| var system = _b[_a]; | ||
| possibilities = __spreadArray(__spreadArray([], possibilities), Object.keys(system)); | ||
| possibilities = __spreadArray(__spreadArray([], possibilities, true), Object.keys(system), true); | ||
| } | ||
@@ -276,0 +285,0 @@ } |
| import { Measure } from './../index'; | ||
| export declare type AreaUnits = AreaMetricUnits | AreaImperialUnits; | ||
| export declare type AreaSystems = 'metric' | 'imperial'; | ||
| export declare type AreaMetricUnits = 'mm2' | 'cm2' | 'm2' | 'ha' | 'km2'; | ||
| export declare type AreaMetricUnits = 'nm2' | 'μm2' | 'mm2' | 'cm2' | 'm2' | 'ha' | 'km2'; | ||
| export declare type AreaImperialUnits = 'in2' | 'yd2' | 'ft2' | 'ac' | 'mi2'; | ||
| declare const measure: Measure<AreaSystems, AreaUnits>; | ||
| export default measure; |
| "use strict"; | ||
| Object.defineProperty(exports, "__esModule", { value: true }); | ||
| var metric = { | ||
| nm2: { | ||
| name: { | ||
| singular: 'Square Nanometer', | ||
| plural: 'Square Nanometers', | ||
| }, | ||
| to_anchor: 1e-18, | ||
| }, | ||
| μm2: { | ||
| name: { | ||
| singular: 'Square Micrometer', | ||
| plural: 'Square Micrometers', | ||
| }, | ||
| to_anchor: 1e-12, | ||
| }, | ||
| mm2: { | ||
@@ -5,0 +19,0 @@ name: { |
@@ -5,4 +5,4 @@ import { Measure } from './../index'; | ||
| export declare type PressureMetricUnits = 'Pa' | 'kPa' | 'MPa' | 'hPa' | 'bar' | 'torr'; | ||
| export declare type PressureImperialUnits = 'psi' | 'ksi'; | ||
| export declare type PressureImperialUnits = 'psi' | 'ksi' | 'inHg'; | ||
| declare const measure: Measure<PressureSystems, PressureUnits>; | ||
| export default measure; |
@@ -62,2 +62,9 @@ "use strict"; | ||
| }, | ||
| inHg: { | ||
| name: { | ||
| singular: 'Inch of mercury', | ||
| plural: 'Inches of mercury', | ||
| }, | ||
| to_anchor: 0.000491154, | ||
| }, | ||
| }; | ||
@@ -64,0 +71,0 @@ var measure = { |
@@ -5,4 +5,4 @@ import { Measure } from './../index'; | ||
| export declare type SpeedMetricUnits = 'm/s' | 'km/h'; | ||
| export declare type SpeedImperialUnits = 'mph' | 'knot' | 'ft/s'; | ||
| export declare type SpeedImperialUnits = 'mph' | 'knot' | 'ft/s' | 'ft/min'; | ||
| declare const measure: Measure<SpeedSystems, SpeedUnits>; | ||
| export default measure; |
@@ -41,2 +41,9 @@ "use strict"; | ||
| }, | ||
| 'ft/min': { | ||
| name: { | ||
| singular: 'Foot per minute', | ||
| plural: 'Feet per minute', | ||
| }, | ||
| to_anchor: 0.0113636, | ||
| }, | ||
| }; | ||
@@ -43,0 +50,0 @@ var measure = { |
@@ -70,4 +70,4 @@ "use strict"; | ||
| name: { | ||
| singular: 'Matsked', | ||
| plural: 'Matskedar', | ||
| singular: 'Kryddmått', | ||
| plural: 'Kryddmått', | ||
| }, | ||
@@ -74,0 +74,0 @@ to_anchor: 1 / 1000, |
@@ -60,2 +60,3 @@ export interface Unit { | ||
| cutOffNumber?: number; | ||
| system?: TSystems; | ||
| }): BestResult | null; | ||
@@ -62,0 +63,0 @@ /** |
@@ -1,5 +0,9 @@ | ||
| var __spreadArray = (this && this.__spreadArray) || function (to, from) { | ||
| for (var i = 0, il = from.length, j = to.length; i < il; i++, j++) | ||
| to[j] = from[i]; | ||
| return to; | ||
| var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) { | ||
| if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) { | ||
| if (ar || !(i in from)) { | ||
| if (!ar) ar = Array.prototype.slice.call(from, 0, i); | ||
| ar[i] = from[i]; | ||
| } | ||
| } | ||
| return to.concat(ar || Array.prototype.slice.call(from)); | ||
| }; | ||
@@ -109,3 +113,3 @@ /** | ||
| Converter.prototype.toBest = function (options) { | ||
| var _a, _b; | ||
| var _a, _b, _c; | ||
| if (this.origin == null) | ||
@@ -115,5 +119,7 @@ throw new Error('.toBest must be called after .from'); | ||
| var cutOffNumber = 1; | ||
| var system = this.origin.system; | ||
| if (typeof options === 'object') { | ||
| exclude = (_a = options.exclude) !== null && _a !== void 0 ? _a : []; | ||
| cutOffNumber = (_b = options.cutOffNumber) !== null && _b !== void 0 ? _b : 1; | ||
| system = (_c = options.system) !== null && _c !== void 0 ? _c : this.origin.system; | ||
| } | ||
@@ -126,8 +132,11 @@ var best = null; | ||
| */ | ||
| for (var _i = 0, _c = this.possibilities(); _i < _c.length; _i++) { | ||
| var possibility = _c[_i]; | ||
| for (var _i = 0, _d = this.possibilities(); _i < _d.length; _i++) { | ||
| var possibility = _d[_i]; | ||
| var unit = this.describe(possibility); | ||
| var isIncluded = exclude.indexOf(possibility) === -1; | ||
| if (isIncluded && unit.system === this.origin.system) { | ||
| if (isIncluded && unit.system === system) { | ||
| var result = this.to(possibility); | ||
| if (result < cutOffNumber) { | ||
| continue; | ||
| } | ||
| if (best == null || (result >= cutOffNumber && result < best.val)) { | ||
@@ -270,3 +279,3 @@ best = { | ||
| var system = _b[_a]; | ||
| possibilities = __spreadArray(__spreadArray([], possibilities), Object.keys(system)); | ||
| possibilities = __spreadArray(__spreadArray([], possibilities, true), Object.keys(system), true); | ||
| } | ||
@@ -273,0 +282,0 @@ } |
| import { Measure } from './../index'; | ||
| export declare type AreaUnits = AreaMetricUnits | AreaImperialUnits; | ||
| export declare type AreaSystems = 'metric' | 'imperial'; | ||
| export declare type AreaMetricUnits = 'mm2' | 'cm2' | 'm2' | 'ha' | 'km2'; | ||
| export declare type AreaMetricUnits = 'nm2' | 'μm2' | 'mm2' | 'cm2' | 'm2' | 'ha' | 'km2'; | ||
| export declare type AreaImperialUnits = 'in2' | 'yd2' | 'ft2' | 'ac' | 'mi2'; | ||
| declare const measure: Measure<AreaSystems, AreaUnits>; | ||
| export default measure; |
| var metric = { | ||
| nm2: { | ||
| name: { | ||
| singular: 'Square Nanometer', | ||
| plural: 'Square Nanometers', | ||
| }, | ||
| to_anchor: 1e-18, | ||
| }, | ||
| μm2: { | ||
| name: { | ||
| singular: 'Square Micrometer', | ||
| plural: 'Square Micrometers', | ||
| }, | ||
| to_anchor: 1e-12, | ||
| }, | ||
| mm2: { | ||
@@ -3,0 +17,0 @@ name: { |
@@ -5,4 +5,4 @@ import { Measure } from './../index'; | ||
| export declare type PressureMetricUnits = 'Pa' | 'kPa' | 'MPa' | 'hPa' | 'bar' | 'torr'; | ||
| export declare type PressureImperialUnits = 'psi' | 'ksi'; | ||
| export declare type PressureImperialUnits = 'psi' | 'ksi' | 'inHg'; | ||
| declare const measure: Measure<PressureSystems, PressureUnits>; | ||
| export default measure; |
@@ -60,2 +60,9 @@ var metric = { | ||
| }, | ||
| inHg: { | ||
| name: { | ||
| singular: 'Inch of mercury', | ||
| plural: 'Inches of mercury', | ||
| }, | ||
| to_anchor: 0.000491154, | ||
| }, | ||
| }; | ||
@@ -62,0 +69,0 @@ var measure = { |
@@ -5,4 +5,4 @@ import { Measure } from './../index'; | ||
| export declare type SpeedMetricUnits = 'm/s' | 'km/h'; | ||
| export declare type SpeedImperialUnits = 'mph' | 'knot' | 'ft/s'; | ||
| export declare type SpeedImperialUnits = 'mph' | 'knot' | 'ft/s' | 'ft/min'; | ||
| declare const measure: Measure<SpeedSystems, SpeedUnits>; | ||
| export default measure; |
@@ -39,2 +39,9 @@ var metric = { | ||
| }, | ||
| 'ft/min': { | ||
| name: { | ||
| singular: 'Foot per minute', | ||
| plural: 'Feet per minute', | ||
| }, | ||
| to_anchor: 0.0113636, | ||
| }, | ||
| }; | ||
@@ -41,0 +48,0 @@ var measure = { |
@@ -68,4 +68,4 @@ var metric = { | ||
| name: { | ||
| singular: 'Matsked', | ||
| plural: 'Matskedar', | ||
| singular: 'Kryddmått', | ||
| plural: 'Kryddmått', | ||
| }, | ||
@@ -72,0 +72,0 @@ to_anchor: 1 / 1000, |
@@ -60,2 +60,3 @@ export interface Unit { | ||
| cutOffNumber?: number; | ||
| system?: TSystems; | ||
| }): BestResult | null; | ||
@@ -62,0 +63,0 @@ /** |
@@ -1,5 +0,9 @@ | ||
| var __spreadArray = (this && this.__spreadArray) || function (to, from) { | ||
| for (var i = 0, il = from.length, j = to.length; i < il; i++, j++) | ||
| to[j] = from[i]; | ||
| return to; | ||
| var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) { | ||
| if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) { | ||
| if (ar || !(i in from)) { | ||
| if (!ar) ar = Array.prototype.slice.call(from, 0, i); | ||
| ar[i] = from[i]; | ||
| } | ||
| } | ||
| return to.concat(ar || Array.prototype.slice.call(from)); | ||
| }; | ||
@@ -121,3 +125,3 @@ (function (factory) { | ||
| Converter.prototype.toBest = function (options) { | ||
| var _a, _b; | ||
| var _a, _b, _c; | ||
| if (this.origin == null) | ||
@@ -127,5 +131,7 @@ throw new Error('.toBest must be called after .from'); | ||
| var cutOffNumber = 1; | ||
| var system = this.origin.system; | ||
| if (typeof options === 'object') { | ||
| exclude = (_a = options.exclude) !== null && _a !== void 0 ? _a : []; | ||
| cutOffNumber = (_b = options.cutOffNumber) !== null && _b !== void 0 ? _b : 1; | ||
| system = (_c = options.system) !== null && _c !== void 0 ? _c : this.origin.system; | ||
| } | ||
@@ -138,8 +144,11 @@ var best = null; | ||
| */ | ||
| for (var _i = 0, _c = this.possibilities(); _i < _c.length; _i++) { | ||
| var possibility = _c[_i]; | ||
| for (var _i = 0, _d = this.possibilities(); _i < _d.length; _i++) { | ||
| var possibility = _d[_i]; | ||
| var unit = this.describe(possibility); | ||
| var isIncluded = exclude.indexOf(possibility) === -1; | ||
| if (isIncluded && unit.system === this.origin.system) { | ||
| if (isIncluded && unit.system === system) { | ||
| var result = this.to(possibility); | ||
| if (result < cutOffNumber) { | ||
| continue; | ||
| } | ||
| if (best == null || (result >= cutOffNumber && result < best.val)) { | ||
@@ -282,3 +291,3 @@ best = { | ||
| var system = _b[_a]; | ||
| possibilities = __spreadArray(__spreadArray([], possibilities), Object.keys(system)); | ||
| possibilities = __spreadArray(__spreadArray([], possibilities, true), Object.keys(system), true); | ||
| } | ||
@@ -285,0 +294,0 @@ } |
| import { Measure } from './../index'; | ||
| export declare type AreaUnits = AreaMetricUnits | AreaImperialUnits; | ||
| export declare type AreaSystems = 'metric' | 'imperial'; | ||
| export declare type AreaMetricUnits = 'mm2' | 'cm2' | 'm2' | 'ha' | 'km2'; | ||
| export declare type AreaMetricUnits = 'nm2' | 'μm2' | 'mm2' | 'cm2' | 'm2' | 'ha' | 'km2'; | ||
| export declare type AreaImperialUnits = 'in2' | 'yd2' | 'ft2' | 'ac' | 'mi2'; | ||
| declare const measure: Measure<AreaSystems, AreaUnits>; | ||
| export default measure; |
@@ -13,2 +13,16 @@ (function (factory) { | ||
| var metric = { | ||
| nm2: { | ||
| name: { | ||
| singular: 'Square Nanometer', | ||
| plural: 'Square Nanometers', | ||
| }, | ||
| to_anchor: 1e-18, | ||
| }, | ||
| μm2: { | ||
| name: { | ||
| singular: 'Square Micrometer', | ||
| plural: 'Square Micrometers', | ||
| }, | ||
| to_anchor: 1e-12, | ||
| }, | ||
| mm2: { | ||
@@ -15,0 +29,0 @@ name: { |
@@ -5,4 +5,4 @@ import { Measure } from './../index'; | ||
| export declare type PressureMetricUnits = 'Pa' | 'kPa' | 'MPa' | 'hPa' | 'bar' | 'torr'; | ||
| export declare type PressureImperialUnits = 'psi' | 'ksi'; | ||
| export declare type PressureImperialUnits = 'psi' | 'ksi' | 'inHg'; | ||
| declare const measure: Measure<PressureSystems, PressureUnits>; | ||
| export default measure; |
@@ -71,2 +71,9 @@ (function (factory) { | ||
| }, | ||
| inHg: { | ||
| name: { | ||
| singular: 'Inch of mercury', | ||
| plural: 'Inches of mercury', | ||
| }, | ||
| to_anchor: 0.000491154, | ||
| }, | ||
| }; | ||
@@ -73,0 +80,0 @@ var measure = { |
@@ -5,4 +5,4 @@ import { Measure } from './../index'; | ||
| export declare type SpeedMetricUnits = 'm/s' | 'km/h'; | ||
| export declare type SpeedImperialUnits = 'mph' | 'knot' | 'ft/s'; | ||
| export declare type SpeedImperialUnits = 'mph' | 'knot' | 'ft/s' | 'ft/min'; | ||
| declare const measure: Measure<SpeedSystems, SpeedUnits>; | ||
| export default measure; |
@@ -50,2 +50,9 @@ (function (factory) { | ||
| }, | ||
| 'ft/min': { | ||
| name: { | ||
| singular: 'Foot per minute', | ||
| plural: 'Feet per minute', | ||
| }, | ||
| to_anchor: 0.0113636, | ||
| }, | ||
| }; | ||
@@ -52,0 +59,0 @@ var measure = { |
@@ -79,4 +79,4 @@ (function (factory) { | ||
| name: { | ||
| singular: 'Matsked', | ||
| plural: 'Matskedar', | ||
| singular: 'Kryddmått', | ||
| plural: 'Kryddmått', | ||
| }, | ||
@@ -83,0 +83,0 @@ to_anchor: 1 / 1000, |
| { | ||
| "name": "convert-units", | ||
| "version": "3.0.0-beta.2", | ||
| "version": "3.0.0-beta.3", | ||
| "description": "Convert between quantities in different units", | ||
@@ -19,6 +19,6 @@ "main": "lib/cjs/index.js", | ||
| "eslint-plugin-prettier": "^3.4.0", | ||
| "jest": "^26.6.3", | ||
| "jest": "^27.3.1", | ||
| "prettier": "2.2.1", | ||
| "prettier-plugin-organize-imports": "^2.1.0", | ||
| "ts-jest": "^26.5.6", | ||
| "ts-jest": "^27.0.7", | ||
| "typescript": "^4.2.4" | ||
@@ -25,0 +25,0 @@ }, |
756
README.md
@@ -34,3 +34,3 @@ convert-units | ||
| It's also possible to limit the measures configured to only the ones your application needs: | ||
| It's also possible to limit the measures configured. This allows for smaller packages when using a bundler like `webpack` or `rollup`: | ||
@@ -52,3 +52,3 @@ ```js | ||
| Here's how you move between the metric units for volume: | ||
| Converting between units in a measure: | ||
@@ -60,3 +60,3 @@ ```js | ||
| Jump from imperial to metric units the same way: | ||
| Converting between systems is handled automatically (`imperial` to `metric` in this case): | ||
@@ -68,3 +68,3 @@ ```js | ||
| Just be careful not to ask for an impossible conversion: | ||
| Attempting to convert between measures will result in an error: | ||
@@ -76,18 +76,31 @@ ```js | ||
| You can ask `convert-units` to select the best unit for you. You can also optionally explicitly exclude orders of magnitude or specify a cut off number for selecting the best representation. | ||
| To convert a unit to another unit within the same measure with the smallest value above `1`: | ||
| ```js | ||
| convert(12000).from('mm').toBest(); | ||
| // { val: 12, unit: 'm', plural: 'Meters' } (the smallest unit with a value above 1) | ||
| // { val: 12, unit: 'm', ... } | ||
| ``` | ||
| Exclude units to get different results: | ||
| ```js | ||
| convert(12000).from('mm').toBest({ exclude: ['m'] }); | ||
| // { val: 1200, unit: 'cm', plural: 'Centimeters' } (the smallest unit excluding meters) | ||
| // { val: 1200, unit: 'cm', ... } (the smallest unit excluding meters) | ||
| ``` | ||
| The best is always the smallest number above `1`. That number can be changed to get different results: | ||
| ```js | ||
| convert(900).from('mm').toBest({ cutOffNumber: 10 }); | ||
| // { val: 90, unit: 'cm', plural: 'Centimeters' } (the smallest unit with a value equal to or above 10) | ||
| // { val: 90, unit: 'cm', ... } (the smallest unit with a value equal to or above 10) | ||
| convert(1000).from('mm').toBest({ cutOffNumber: 10 }); | ||
| // { val: 100, unit: 'cm', plural: 'Centimeters' } (the smallest unit with a value equal to or above 10) | ||
| // by default the system of the origin is used, the `system` option overwrites this behaviour | ||
| convert(254).from('mm').toBest({ system: 'imperial' }); // ('mm' is metric) | ||
| // { val: 10, unit: 'in', plural: 'Inches' } // ('in' is imperial) | ||
| ``` | ||
| You can get a list of the measures available to the current instance with `.measures` | ||
| List all available measures: | ||
@@ -108,3 +121,3 @@ ```js | ||
| If you ever want to know the possible conversions for a unit, just use `.possibilities` | ||
| List all units that a given unit can be converted to: | ||
@@ -119,3 +132,4 @@ ```js | ||
| You can also get the possible conversions for a measure: | ||
| List all units that belong to a measure: | ||
| ```js | ||
@@ -126,3 +140,4 @@ convert().possibilities('mass'); | ||
| You can also get the all the available units: | ||
| List all configured units: | ||
| ```js | ||
@@ -133,3 +148,3 @@ convert().possibilities(); | ||
| To get a detailed description of a unit, use `describe` | ||
| Get a detailed description of a unit: | ||
@@ -149,3 +164,3 @@ ```js | ||
| To get detailed descriptions of all units, use `list`. | ||
| List detailed descriptions of all units: | ||
@@ -165,3 +180,3 @@ ```js | ||
| You can also get detailed descriptions of all units for a measure: | ||
| List detailed descriptions of all units for a measure: | ||
@@ -184,101 +199,517 @@ ```js | ||
| It's possible to define custom measures if the ones packaged aren't what you need: | ||
| To create a custom measure, it's best to start with an plain object. The key itself will be used as the measure's name. In the example below, the measure's name is "`customMeasure`". | ||
| <details> | ||
| <summary>Code example:</summary> | ||
| ```js | ||
| import configureMeasurements from 'convert-units'; | ||
| const measure = { | ||
| customMeasure: {}, | ||
| }; | ||
| ``` | ||
| </details> | ||
| const customMeasure = { | ||
| systems: { | ||
| A: { | ||
| a: { | ||
| name: { | ||
| singular: 'a', | ||
| plural: 'as', | ||
| }, | ||
| // to_anchor: The factor used to reach the base unit | ||
| // The base unit should have a to_anchor value of 1 | ||
| // Eg. 1 a -> al = 1a * 1e-1 (to_anchor of al) = 10 al | ||
| to_anchor: 1, | ||
| Next step is to create the measure's systems. A system is a collection of related units. Here are some examples of some common systems: metric, imperial, SI, bits, bytes, etc. You don't need to use one of these systems for your measure. In the example below, there are 3 systems defined: `A`, `B`, `C`. | ||
| <details> | ||
| <summary>Code example:</summary> | ||
| ```js | ||
| const measure = { | ||
| customMeasure: { | ||
| systems: { | ||
| A: {}, | ||
| B: {}, | ||
| C: {}, | ||
| } | ||
| }, | ||
| }; | ||
| ``` | ||
| </details> | ||
| Now the measure is ready to define some units. The first unit that needs to be defined for each system is the base unit. The base unit is like all other units except that it's the unit used to convert between systems and every other unit in the system will be configured to convert directly to it. Below is an example of a base unit for the `A` system. | ||
| <details> | ||
| <summary>Code example:</summary> | ||
| ```js | ||
| const measure = { | ||
| customMeasure: { | ||
| systems: { | ||
| A: { | ||
| a: { // the name of the unit (commonly an abbreviation) | ||
| name: { // human friendly names for the unit | ||
| singular: 'a', | ||
| plural: 'as', | ||
| }, | ||
| } | ||
| }, | ||
| al: { | ||
| name: { | ||
| singular: 'al', | ||
| plural: 'als', | ||
| // ignoring C & B for now | ||
| } | ||
| }, | ||
| }; | ||
| ``` | ||
| </details> | ||
| Each unit also needs to an `to_anchor` property. `to_anchor` holds a number which represents the factor needed to go from another unit in the system to the base unit. In the case of the `a` unit, the value will be `1`. The value for all base units in every system should to be `1` because if you convert `5 a` to `a` the result should be `5 a`. This is because the value of `to_anchor` is multiplied with the value of the unit being converted from. So in this case, `5 * 1 = 5`. | ||
| <details> | ||
| <summary>Code example:</summary> | ||
| ```js | ||
| const measure = { | ||
| customMeasure: { | ||
| systems: { | ||
| A: { | ||
| a: { | ||
| name: { | ||
| singular: 'a', | ||
| plural: 'as', | ||
| }, | ||
| to_anchor: 1, | ||
| } | ||
| }, | ||
| // ignoring C & B for now | ||
| } | ||
| }, | ||
| }; | ||
| ``` | ||
| </details> | ||
| Adding a second measure to the `A` measure looks exactly the same as the `a` unit except the `to_anchor` value will be different. If the unit is supposed to be larger than the base then the `to_anchor` value needs to be greater than `1`. For example, the new unit `ah` should be a factor of 10 larger than the base. This would mean that `1 ah` equals `10 a`. To make sure this assumption is correct multiply the `to_anchor` by the unit, `5 ah * 10 = 50 a`. | ||
| <details> | ||
| <summary>Code example:</summary> | ||
| ```js | ||
| const measure = { | ||
| customMeasure: { | ||
| systems: { | ||
| A: { | ||
| ah: { // new unit, ah | ||
| name: { | ||
| singular: 'ah', | ||
| plural: 'ahs', | ||
| }, | ||
| to_anchor: 1e1, // = 10 ^ 1 = 10 | ||
| }, | ||
| to_anchor: 1e-1, | ||
| a: { | ||
| name: { | ||
| singular: 'a', | ||
| plural: 'as', | ||
| }, | ||
| to_anchor: 1, | ||
| } | ||
| }, | ||
| // ignoring C & B for now | ||
| }, | ||
| B: { | ||
| b: { | ||
| name: { | ||
| singular: 'b', | ||
| plural: 'bs', | ||
| }, | ||
| }; | ||
| ``` | ||
| </details> | ||
| If the unit should be smaller than the base unit then the `to_anchor` value should be less than `1` and greater than `0`. With that said, the new unit `al` should have a `to_anchor` value of `0.1`. This would mean that `10 al` would equal `1 a`. | ||
| <details> | ||
| <summary>Code example:</summary> | ||
| ```js | ||
| const measure = { | ||
| customMeasure: { | ||
| systems: { | ||
| A: { | ||
| ah: { // new unit, ah | ||
| name: { | ||
| singular: 'ah', | ||
| plural: 'ahs', | ||
| }, | ||
| to_anchor: 1e1, // = 10 ^ 1 = 10 | ||
| }, | ||
| to_anchor: 1, | ||
| }, | ||
| bl: { | ||
| name: { | ||
| singular: 'bl', | ||
| plural: 'bls', | ||
| a: { | ||
| name: { | ||
| singular: 'a', | ||
| plural: 'as', | ||
| }, | ||
| to_anchor: 1, | ||
| } | ||
| al: { // new unit, al | ||
| name: { | ||
| singular: 'al', | ||
| plural: 'als', | ||
| }, | ||
| to_anchor: 1e-1, // = 10 ^ -1 = 0.1 | ||
| }, | ||
| to_anchor: 1e-1, | ||
| }, | ||
| // ignoring C & B for now | ||
| }, | ||
| C: { | ||
| c: { | ||
| name: { | ||
| singular: 'c', | ||
| plural: 'cs', | ||
| }, | ||
| }; | ||
| ``` | ||
| </details> | ||
| There is one more option, `anchor_shift`, it can be defined on a unit if it requires to be shifted after the conversion. If `al` had a `anchor_shift` of `5` then `10 al` to `a` would look like, `10 * 0.1 - 5 = -4 a`. If the shift needs to go in the opposite direction then it should be a negative number. Typically, measures and units that use the `anchor_shift` only need to be shifted. If that is the desired effect then setting `to_anchor` to `1` for each unit will achieve that. To see a real world example, check out the `temperature` measure in the `definitions` folder. | ||
| <details> | ||
| <summary>Code example:</summary> | ||
| ```js | ||
| const measure = { | ||
| customMeasure: { | ||
| systems: { | ||
| A: { | ||
| ah: { // new unit, ah | ||
| name: { | ||
| singular: 'ah', | ||
| plural: 'ahs', | ||
| }, | ||
| to_anchor: 1e1, // = 10 ^ 1 = 10 | ||
| }, | ||
| to_anchor: 1, | ||
| a: { | ||
| name: { | ||
| singular: 'a', | ||
| plural: 'as', | ||
| }, | ||
| to_anchor: 1, | ||
| } | ||
| al: { // new unit, al | ||
| name: { | ||
| singular: 'al', | ||
| plural: 'als', | ||
| }, | ||
| to_anchor: 1e-1, // = 10 ^ -1 = 0.1 | ||
| anchor_shift: 5, | ||
| }, | ||
| }, | ||
| cl: { | ||
| name: { | ||
| singular: 'cl', | ||
| plural: 'cls', | ||
| // ignoring C & B for now | ||
| } | ||
| }, | ||
| }; | ||
| ``` | ||
| </details> | ||
| At this point if the custom measure only needs one system then it's done! However, if it requires more than one system, an extra step is required. In the example code below, the previously ignored systems `C` and `B` have been defined to look exactly like the `A` system. | ||
| <details> | ||
| <summary>Code example:</summary> | ||
| ```js | ||
| const measure = { | ||
| customMeasure: { | ||
| systems: { | ||
| A: { | ||
| ah: { | ||
| name: { | ||
| singular: 'ah', | ||
| plural: 'ahs', | ||
| }, | ||
| to_anchor: 1e1, | ||
| }, | ||
| to_anchor: 1e-1, | ||
| a: { | ||
| name: { | ||
| singular: 'a', | ||
| plural: 'as', | ||
| }, | ||
| to_anchor: 1, | ||
| }, | ||
| al: { | ||
| name: { | ||
| singular: 'al', | ||
| plural: 'als', | ||
| }, | ||
| to_anchor: 1e-1, | ||
| }, | ||
| }, | ||
| }, | ||
| }, | ||
| anchors: { | ||
| A: { | ||
| // unit a -> unit b | ||
| B: { | ||
| ratio: 2, | ||
| bh: { | ||
| name: { | ||
| singular: 'bh', | ||
| plural: 'bhs', | ||
| }, | ||
| to_anchor: 1e1, | ||
| }, | ||
| b: { | ||
| name: { | ||
| singular: 'b', | ||
| plural: 'bs', | ||
| }, | ||
| to_anchor: 1, | ||
| }, | ||
| bl: { | ||
| name: { | ||
| singular: 'bl', | ||
| plural: 'bls', | ||
| }, | ||
| to_anchor: 1e-1, | ||
| }, | ||
| }, | ||
| // unit a -> unit c | ||
| C: { | ||
| ratio: 3, | ||
| ch: { | ||
| name: { | ||
| singular: 'ch', | ||
| plural: 'chs', | ||
| }, | ||
| to_anchor: 1e1, | ||
| }, | ||
| c: { | ||
| name: { | ||
| singular: 'c', | ||
| plural: 'cs', | ||
| }, | ||
| to_anchor: 1, | ||
| }, | ||
| cl: { | ||
| name: { | ||
| singular: 'cl', | ||
| plural: 'cls', | ||
| }, | ||
| to_anchor: 1e-1, | ||
| }, | ||
| }, | ||
| }, | ||
| B: { | ||
| // unit b -> unit a | ||
| } | ||
| }; | ||
| ``` | ||
| </details> | ||
| The measure now has three systems, `A`, `B`, and `C`. To define how each system can be converted to the other, anchors will needs to be defined for each possible conversion. To start, add the key `anchors` to the `customMeasure` object: | ||
| <details> | ||
| <summary>Code example:</summary> | ||
| ```js | ||
| const measure = { | ||
| customMeasure: { | ||
| systems: { | ||
| // ... | ||
| }, | ||
| anchors: {}, | ||
| } | ||
| }; | ||
| ``` | ||
| </details> | ||
| Then just like for the `systems` object, add a key for each system with it's value being an empty object: | ||
| <details> | ||
| <summary>Code example:</summary> | ||
| ```js | ||
| const measure = { | ||
| customMeasure: { | ||
| systems: { | ||
| // ... | ||
| }, | ||
| anchors: { | ||
| A: {}, | ||
| B: {}, | ||
| C: {}, | ||
| }, | ||
| } | ||
| }; | ||
| ``` | ||
| </details> | ||
| In each of those empty objects, add keys for the other systems which their values being an empty object. The measure should look like the code snippet below: | ||
| <details> | ||
| <summary>Code example:</summary> | ||
| ```js | ||
| const measure = { | ||
| customMeasure: { | ||
| systems: { | ||
| // ... | ||
| }, | ||
| anchors: { | ||
| A: { // A to B or C | ||
| B: {}, | ||
| C: {}, | ||
| }, | ||
| B: { // B to A or C | ||
| A: {}, | ||
| C: {}, | ||
| }, | ||
| C: { // C to A or B | ||
| A: {}, | ||
| B: {}, | ||
| }, | ||
| }, | ||
| } | ||
| }; | ||
| ``` | ||
| </details> | ||
| When converting, for example, `1 a` to `bl`, the code can perform a simple lookup here, `anchors.A.B`. If instead the conversion is from `10 c` to `ah` then the lookup would be, `anchors.C.A`. At this point how to convert from one system to the next hasn't been defined yet; that will be the next and final step in creating a new measure. | ||
| Each system pair needs to either defined a `ratio` or a `transform` function. If a `ratio` is defined then it's multiplied by the base unit to convert it to the target system's base unit. If `transform` is defined, the function is called with the value of the best unit. It's value is used as the base unit of the target system. The `transform` function should return a number. | ||
| > Note: If both `ratio` and `transform` are defined then the `ratio` will be used and the `transform` function will be ignored. If nether are defined, the conversion will throw an error. | ||
| <details> | ||
| <summary>Code example:</summary> | ||
| ```js | ||
| const measure = { | ||
| customMeasure: { | ||
| systems: { | ||
| // ... | ||
| }, | ||
| anchors: { | ||
| A: { // A to B or C | ||
| B: { | ||
| ratio: 2, | ||
| }, | ||
| C: { | ||
| ratio: 3, | ||
| }, | ||
| }, | ||
| B: { // B to A or C | ||
| A: { | ||
| ratio: 1 / 2, | ||
| }, | ||
| C: { | ||
| ratio: 3 / 2, | ||
| }, | ||
| }, | ||
| C: { // C to A or B | ||
| A: { | ||
| // example of using a transform function | ||
| // This would be the same as ratio: 1 / 3 | ||
| transform: value => value * 1 / 3, | ||
| }, | ||
| B: { | ||
| transform: value => value * 2 / 3, | ||
| }, | ||
| }, | ||
| }, | ||
| } | ||
| }; | ||
| ``` | ||
| </details> | ||
| With the above example, converting `10 cl` to `ah` would result in `0.0333` (rounded). | ||
| <details> | ||
| <summary>Here is the complete measure:</summary> | ||
| ```js | ||
| const measure = { | ||
| customMeasure: { | ||
| systems: { | ||
| A: { | ||
| ratio: 1 / 2, | ||
| ah: { | ||
| name: { | ||
| singular: 'ah', | ||
| plural: 'ahs', | ||
| }, | ||
| to_anchor: 1e1, | ||
| }, | ||
| a: { | ||
| name: { | ||
| singular: 'a', | ||
| plural: 'as', | ||
| }, | ||
| // to_anchor: The factor used to reach the base unit | ||
| // The base unit should have a to_anchor value of 1 | ||
| // Eg. 1 a -> al = 1a * 1e-1 (to_anchor of al) = 10 al | ||
| to_anchor: 1, | ||
| }, | ||
| al: { | ||
| name: { | ||
| singular: 'al', | ||
| plural: 'als', | ||
| }, | ||
| to_anchor: 1e-1, | ||
| }, | ||
| }, | ||
| // unit b -> unit c | ||
| B: { | ||
| bh: { | ||
| name: { | ||
| singular: 'bh', | ||
| plural: 'bhs', | ||
| }, | ||
| to_anchor: 1e1, | ||
| }, | ||
| b: { | ||
| name: { | ||
| singular: 'b', | ||
| plural: 'bs', | ||
| }, | ||
| to_anchor: 1, | ||
| }, | ||
| bl: { | ||
| name: { | ||
| singular: 'bl', | ||
| plural: 'bls', | ||
| }, | ||
| to_anchor: 1e-1, | ||
| }, | ||
| }, | ||
| C: { | ||
| ratio: 3 / 2, | ||
| ch: { | ||
| name: { | ||
| singular: 'ch', | ||
| plural: 'chs', | ||
| }, | ||
| to_anchor: 1e1, | ||
| }, | ||
| c: { | ||
| name: { | ||
| singular: 'c', | ||
| plural: 'cs', | ||
| }, | ||
| to_anchor: 1, | ||
| }, | ||
| cl: { | ||
| name: { | ||
| singular: 'cl', | ||
| plural: 'cls', | ||
| }, | ||
| to_anchor: 1e-1, | ||
| }, | ||
| }, | ||
| }, | ||
| C: { | ||
| // unit c -> unit a | ||
| anchors: { | ||
| A: { | ||
| ratio: 1 / 3, | ||
| // unit a -> unit b | ||
| B: { | ||
| ratio: 2, | ||
| }, | ||
| // unit a -> unit c | ||
| C: { | ||
| ratio: 3, | ||
| }, | ||
| }, | ||
| // unit c -> unit b | ||
| B: { | ||
| ratio: 2 / 3, | ||
| // unit b -> unit a | ||
| A: { | ||
| ratio: 1 / 2, | ||
| }, | ||
| // unit b -> unit c | ||
| C: { | ||
| ratio: 3 / 2, | ||
| }, | ||
| }, | ||
| C: { | ||
| // unit c -> unit a | ||
| A: { | ||
| ratio: 1 / 3, | ||
| }, | ||
| // unit c -> unit b | ||
| B: { | ||
| ratio: 2 / 3, | ||
| }, | ||
| }, | ||
| }, | ||
| }, | ||
| } | ||
| }; | ||
| const convert = configureMeasurements({ customMeasure }); | ||
| const convert = configureMeasurements(measure); | ||
| convert(1).from('a').to('bl') | ||
| // 20 | ||
| ``` | ||
| </details> | ||
| The order of opperations goes as follows: | ||
| <details> | ||
| <summary>Pseudo code that shows the maths involved when converting a unit</summary> | ||
@@ -298,5 +729,11 @@ ```js | ||
| ``` | ||
| </details> | ||
| It's also possible to extend existing measures: | ||
| ## Extending Existing Measures | ||
| Since measure definitions are plain JS objects, additional units can be added, removed, and changed. | ||
| <details> | ||
| <summary>Example of extending the `length` measure</summary> | ||
| ```ts | ||
@@ -340,5 +777,6 @@ import configureMeasurements, { | ||
| ``` | ||
| </details> | ||
| Migrating from Old API | ||
| --------------------- | ||
| Migrating from v2 to v3+ | ||
| ----------------------- | ||
@@ -375,10 +813,6 @@ This only applies if moving from `<=2.3.4` to `>=3.x`. | ||
| Defining types can provide the benefit of exposing issues while working on your application. | ||
| The library provides types for all packaged mesasures: | ||
| ```ts | ||
| import configureMeasurements, { | ||
| AllMeasures, | ||
| allMeasures, | ||
| AllMeasuresSystems, | ||
| AllMeasuresUnits, | ||
| area, | ||
@@ -392,3 +826,3 @@ AreaSystems, | ||
| // Meausres: The names of the measures being used | ||
| // Measures: The names of the measures being used | ||
| type Measures = 'length' | 'area'; | ||
@@ -399,2 +833,3 @@ // Systems: The systems being used across all measures | ||
| type Units = LengthUnits | AreaUnits; | ||
| const convert = configureMeasurements<Measures, Systems, Units>({ | ||
@@ -407,4 +842,42 @@ length, | ||
| // 400 | ||
| ``` | ||
| // If you'd like to use all the packages measures that can be done like so | ||
| This also allows for IDE tools to highlight issues before running the application: | ||
| ```ts | ||
| import configureMeasurements, { | ||
| area, | ||
| AreaSystems, | ||
| AreaUnits, | ||
| length, | ||
| LengthSystems, | ||
| LengthUnits, | ||
| } from 'convert-units'; | ||
| // Measures: The names of the measures being used | ||
| type Measures = 'length' | 'area'; | ||
| // Systems: The systems being used across all measures | ||
| type Systems = LengthSystems | AreaSystems; | ||
| // Units: All the units across all measures and their systems | ||
| type Units = LengthUnits | AreaUnits; | ||
| const convert = configureMeasurements<Measures, Systems, Units>({ | ||
| length, | ||
| area, | ||
| }); | ||
| convert(4).from('wat').to('cm'); | ||
| // Typescript will warm that the unit `wat` does not exist because it's not a member of the `Units` type defined above. | ||
| ``` | ||
| Types for the `allMeasures` object are also provided: | ||
| ```js | ||
| import configureMeasurements, { | ||
| AllMeasures, | ||
| allMeasures, | ||
| AllMeasuresSystems, | ||
| AllMeasuresUnits, | ||
| } from 'convert-units'; | ||
| const convertAll = configureMeasurements< | ||
@@ -427,3 +900,4 @@ AllMeasures, | ||
| -------------- | ||
| ### Length | ||
| <details> | ||
| <summary>Length</summary> | ||
| * nm | ||
@@ -442,4 +916,6 @@ * μm | ||
| * nMi | ||
| </details> | ||
| ### Area | ||
| <details> | ||
| <summary>Area</summary> | ||
| * mm2 | ||
@@ -454,4 +930,6 @@ * cm2 | ||
| * mi2 | ||
| </details> | ||
| ### Mass | ||
| <details> | ||
| <summary>Mass</summary> | ||
| * mcg | ||
@@ -465,4 +943,6 @@ * mg | ||
| * t | ||
| </details> | ||
| ### Volume | ||
| <details> | ||
| <summary>Volume</summary> | ||
| * mm3 | ||
@@ -485,4 +965,6 @@ * cm3 | ||
| * yd3 | ||
| </details> | ||
| ### Volume Flow Rate | ||
| <details> | ||
| <summary>Volume Flow Rate</summary> | ||
| * mm3/s | ||
@@ -525,4 +1007,6 @@ * cm3/s | ||
| * yd3/h' | ||
| </details> | ||
| ### Temperature | ||
| <details> | ||
| <summary>Temperature</summary> | ||
| * C | ||
@@ -532,4 +1016,6 @@ * F | ||
| * R | ||
| </details> | ||
| ### Time | ||
| <details> | ||
| <summary>Time</summary> | ||
| * ns | ||
@@ -545,4 +1031,6 @@ * mu | ||
| * year | ||
| </details> | ||
| ### Frequency | ||
| <details> | ||
| <summary>Frequency</summary> | ||
| * Hz | ||
@@ -557,4 +1045,6 @@ * mHz | ||
| * rad/s | ||
| </details> | ||
| ### Speed | ||
| <details> | ||
| <summary>Speed</summary> | ||
| * m/s | ||
@@ -565,4 +1055,6 @@ * km/h | ||
| * ft/s | ||
| </details> | ||
| ### Pace | ||
| <details> | ||
| <summary>Pace</summary> | ||
| * s/m | ||
@@ -572,4 +1064,6 @@ * min/km | ||
| * min/mi | ||
| </details> | ||
| ### Pressure | ||
| <details> | ||
| <summary>Pressure</summary> | ||
| * Pa | ||
@@ -583,4 +1077,6 @@ * hPa | ||
| * ksi | ||
| </details> | ||
| ### Digital | ||
| <details> | ||
| <summary>Digital</summary> | ||
| * b | ||
@@ -596,8 +1092,12 @@ * Kb | ||
| * TB | ||
| </details> | ||
| ### Illuminance | ||
| <details> | ||
| <summary>Illuminance</summary> | ||
| * lx | ||
| * ft-cd | ||
| </details> | ||
| ### Parts-Per | ||
| <details> | ||
| <summary>Parts-Per</summary> | ||
| * ppm | ||
@@ -607,14 +1107,20 @@ * ppb | ||
| * ppq | ||
| </details> | ||
| ### Voltage | ||
| <details> | ||
| <summary>Voltage</summary> | ||
| * V | ||
| * mV | ||
| * kV | ||
| </details> | ||
| ### Current | ||
| <details> | ||
| <summary>Current</summary> | ||
| * A | ||
| * mA | ||
| * kA | ||
| </details> | ||
| ### Power | ||
| <details> | ||
| <summary>Power</summary> | ||
| * W | ||
@@ -629,4 +1135,6 @@ * mW | ||
| * hp | ||
| </details> | ||
| ### Apparent Power | ||
| <details> | ||
| <summary>Apparent Power</summary> | ||
| * VA | ||
@@ -637,4 +1145,6 @@ * mVA | ||
| * GVA | ||
| </details> | ||
| ### Reactive Power | ||
| <details> | ||
| <summary>Reactive Power</summary> | ||
| * VAR | ||
@@ -645,4 +1155,6 @@ * mVAR | ||
| * GVAR | ||
| </details> | ||
| ### Energy | ||
| <details> | ||
| <summary>Energy</summary> | ||
| * Wh | ||
@@ -655,4 +1167,6 @@ * mWh | ||
| * kJ | ||
| </details> | ||
| ### Reactive Energy | ||
| <details> | ||
| <summary>Reactive Energy</summary> | ||
| * VARh | ||
@@ -663,4 +1177,6 @@ * mVARh | ||
| * GVARh | ||
| </details> | ||
| ### Angle | ||
| <details> | ||
| <summary>Angle</summary> | ||
| * deg | ||
@@ -671,4 +1187,6 @@ * rad | ||
| * arcsec | ||
| </details> | ||
| ### Charge | ||
| <details> | ||
| <summary>Charge</summary> | ||
| * c | ||
@@ -679,13 +1197,19 @@ * mC | ||
| * pC | ||
| </details> | ||
| ### Force | ||
| <details> | ||
| <summary>Force</summary> | ||
| * N | ||
| * kN | ||
| * lbf | ||
| </details> | ||
| ### Acceleration | ||
| <details> | ||
| <summary>Acceleration</summary> | ||
| * g (g-force) | ||
| * m/s2 | ||
| </details> | ||
| ### Pieces | ||
| <details> | ||
| <summary>Pieces</summary> | ||
| * pcs | ||
@@ -703,3 +1227,4 @@ * bk-doz | ||
| * sm-gr | ||
| * trio | ||
| * trio | ||
| </details> | ||
@@ -731,2 +1256,1 @@ | ||
| OTHER DEALINGS IN THE SOFTWARE. | ||
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by6.37%
269480
- Lines of code
- increased by1.38%
8401
- Number of lines in readme file
- increased by75.72%
1216
No dependency changes