feat: 🎸 promote m from createUnitSystem to UnitSystem.measure

Author: alanhussey

README.md

@@ -59,16 +59,10 @@ const foot = createUnit('foot', {
 
 #### `m(number, unit)`
 
-Shorthand function for creating new `Measurement` instances. If a unit is defined with an alias, that alias can be used instead of passing in the unit.
+Shorthand function for creating new `Measurement` instances. If a unit is defined with an alias, that alias can be used instead of passing in the unit. (see `UnitSystem#measure()` for details)
 
 ```js
-// All of are equivalent to `new Measurement(12, inch)`
 m`12 inches`;
-m`12inches`;
-m`12 ${inch}`;
-m`12`.inches;
-m(12).inches;
-m(12, inch);
 ```
 
 #### `convert(measurement, unit)`
@@ -416,3 +410,24 @@ system.equal(m`12 inches`, m`1 foot`) === true;
 #### `.greaterThanOrEqual(measurement, measurement)`
 
 `greaterThanOrEqual` will return `true` if the first measurement is greater than or equal to the second (after conversion). Otherwise it returns `false`.
+
+#### `.measure(value, unit)`
+
+Shorthand function for creating new `Measurement` instances. If a unit is defined with an alias, that alias can be used instead of passing in the unit.
+
+```js
+// All of these are equivalent to `new Measurement(12, inch)`
+system.measure`12 inches`;
+system.measure`12inches`;
+system.measure`12 ${inch}`;
+system.measure`12`.inches;
+system.measure(12).inches;
+system.measure(12, inch);
+```
+
+`measure` is bound to `system` (its `this` cannot be changed), so it can be "detached" and used as a bare function (but still retain access to your unit system):
+
+```js
+const m = system.measure;
+m`12 inches`;
+```

src/UnitSystem/UnitSystem.js

@@ -18,6 +18,8 @@ class UnitSystem {
     this._converters = new Converters();
 
     this.registerAll(units);
+
+    this.measure = this.measure.bind(this);
   }
 
   merge(...otherSystems) {
@@ -153,6 +155,47 @@ class UnitSystem {
   greaterThanOrEqual(...values) {
     return greaterThanOrEqual(...this._normalizeUnits(values));
   }
+
+  _parse(str, unit = undefined) {
+    const LOOSE_VALUE_AND_OPTIONAL_ALIAS_RE = /^(-?[\d\.\,]+)\s*(.+)?$/;
+    const STRICT_VALUE_RE = /^-?((\d{1,3}(,\d{3})+)|(\d+))?(\.\d+)?$/;
+
+    const result = str.match(LOOSE_VALUE_AND_OPTIONAL_ALIAS_RE);
+
+    let value, alias;
+    [, value, alias] = result || [];
+
+    if (result === null || !STRICT_VALUE_RE.test(value)) {
+      throw Error(
+        `Tried to parse "${str}" but it doesn't appear to be a valid number`
+      );
+    }
+
+    value = value.replace(/,/g, '');
+
+    return [Number(value), unit || this.getUnitForAlias(alias)];
+  }
+
+  measure(value, unit) {
+    if (Array.isArray(value)) {
+      return this.measure(...this._parse(value[0], unit));
+    }
+
+    if (unit instanceof Unit) {
+      return new Measurement(value, unit);
+    }
+
+    const system = this;
+    return new Proxy(Object.create(null), {
+      get(target, property) {
+        const unit = system.getUnitForAlias(property);
+        if (!unit) {
+          throw new Error(`Could not find a unit for the alias "${property}"`);
+        }
+        return system.measure(value, unit);
+      },
+    });
+  }
 }
 
 module.exports = UnitSystem;

src/UnitSystem/UnitSystem.test.js

@@ -529,4 +529,110 @@ describe(UnitSystem, () => {
       }
     );
   });
+
+  describe('#measure', () => {
+    let system;
+    const inch = new Unit('inch');
+
+    beforeEach(() => {
+      system = new UnitSystem();
+    });
+
+    it('creates a Measurement', () => {
+      expect(system.measure(12, inch)).toEqual(new Measurement(12, inch));
+    });
+
+    it('can look up a unit by its alias', () => {
+      system.register(inch, { alias: 'inches' });
+      expect(system.measure(12).inches).toEqual(new Measurement(12, inch));
+    });
+
+    it('can be called as a tagged template', () => {
+      system.register(inch, { alias: 'inches' });
+      expect(system.measure`12 inches`).toEqual(new Measurement(12, inch));
+    });
+
+    it('can be called as a tagged template (negative value)', () => {
+      system.register(inch, { alias: 'inches' });
+      expect(system.measure`-12 inches`).toEqual(new Measurement(-12, inch));
+    });
+
+    it('can be called as a tagged template (no space)', () => {
+      system.register(inch, { alias: 'in' });
+      expect(system.measure`12in`).toEqual(new Measurement(12, inch));
+    });
+
+    it('can be called as a tagged template (commas and decimal)', () => {
+      system.register(inch, { alias: 'inches' });
+      expect(system.measure`1,234.567 inches`).toEqual(
+        new Measurement(1234.567, inch)
+      );
+    });
+
+    it('can be called as a tagged template (everything)', () => {
+      system.register(inch, { alias: 'in' });
+      expect(system.measure`-1,234,567.890in`).toEqual(
+        new Measurement(-1234567.89, inch)
+      );
+    });
+
+    it.each([
+      '1',
+      '12',
+      '123',
+      '-123.4',
+      '123.45',
+      '1,234',
+      '12,345',
+      '123,456',
+      '1,234,567',
+      '1,234.567',
+      '12,345.67',
+      '1,234,567,890',
+      '.1',
+    ])('can parse "%s', str => {
+      system.register(inch, { alias: 'in' });
+      expect(system.measure([`${str}in`])).toEqual(
+        new Measurement(Number(str.replace(/,/g, '')), inch)
+      );
+    });
+
+    it.each([
+      '1,2',
+      ',123',
+      '123.',
+      '12,34',
+      '1234,567',
+      '123,456,7',
+      '1234.567,890',
+      '1,234,567890',
+      undefined,
+      null,
+      {},
+      '',
+    ])('throws an error when attempting to parse "%s"', str => {
+      system.register(inch, { alias: 'in' });
+      expect(() => system.measure([`${str}in`])).toThrowError(
+        new Error(
+          `Tried to parse "${str}in" but it doesn't appear to be a valid number`
+        )
+      );
+    });
+
+    it('can be called as a tagged template with an alias property', () => {
+      system.register(inch, { alias: 'inches' });
+      expect(system.measure`12`.inches).toEqual(new Measurement(12, inch));
+    });
+
+    it('throws an error if called as a tagged template with an alias property but alias does not exist', () => {
+      system.register(inch, { alias: 'inches' });
+      expect(() => system.measure`12`.anchovies).toThrowError(
+        new Error('Could not find a unit for the alias "anchovies"')
+      );
+    });
+
+    it('can be called as a tagged template with an inline unit', () => {
+      expect(system.measure`12 ${inch}`).toEqual(new Measurement(12, inch));
+    });
+  });
 });

src/createMeasurement.js

@@ -1,6 +1,5 @@
 const Unit = require('./Unit');
 const UnitSystem = require('./UnitSystem');
-const createMeasurement = require('./createMeasurement');
 
 function bound(obj, method) {
   return obj[method].bind(obj);
@@ -28,7 +27,7 @@ function createUnitSystem(units) {
   const greaterThan = bound(system, 'greaterThan');
   const greaterThanOrEqual = bound(system, 'greaterThanOrEqual');
 
-  const m = createMeasurement(system);
+  const m = system.measure;
 
   return {
     m,