feat: Transform method

manferlo81 · May 10, 2020 · bb3f2b3 · bb3f2b3
1 parent 98ec6fd
commit bb3f2b3
Show file tree

Hide file tree

Showing 20 changed files with 333 additions and 303 deletions.
diff --git a/README.md b/README.md
@@ -49,7 +49,14 @@ npm i map-number
 ### Node.js
 
 ```javascript
-const { map } = require("map-number");
+const { map } = require('map-number');
+const result = map(Math.sin(angle), -1, 1, 100, 0);
+```
+
+***using javascript modules...***
+
+```javascript
+import { map } from 'map-number';
 const result = map(Math.sin(angle), -1, 1, 100, 0);
 ```
 
@@ -65,9 +72,9 @@ const result = mapNum.map(Math.sin(angle), -1, 1, 100, 0);
 
 ### map
 
-*Maps a number in a range to a different range, returning a floting point number. The result **WILL NOT** be limited (clamped) to the the given output range.*
+*Maps a number within a given range to a different range, returning a floting point number. The result **WILL NOT** be limited (clamped) to the the given output range.*
 
-> *This is the core function and all other map function variants depend on it.*
+*This is the core function and all other map function variants depend on it.*
 
 ***syntax***
 
@@ -77,7 +84,7 @@ function map(num: number, inMin: number, inMax: number, outMin: number, outMax:
 
 ### floor
 
-*Maps a number in a range to a different range, returning a number rounded **down** to the **previous** integer number. The result **WILL NOT** be limited (clamped) to the the given output range.*
+*Maps a number within a given range to a different range, returning a number rounded **down** to the **previous** integer number. The result **WILL NOT** be limited (clamped) to the the given output range.*
 
 ***syntax***
 
@@ -87,7 +94,7 @@ function floor(num: number, inMin: number, inMax: number, outMin: number, outMax
 
 ### ceil
 
-*Maps a number in a range to a different range, returning a number rounded **up** to the **next** integer number. The result **WILL NOT** be limited (clamped) to the the given output range.*
+*Maps a number within a given range to a different range, returning a number rounded **up** to the **next** integer number. The result **WILL NOT** be limited (clamped) to the the given output range.*
 
 ***syntax***
 
@@ -97,19 +104,21 @@ function ceil(num: number, inMin: number, inMax: number, outMin: number, outMax:
 
 ### round
 
-*Maps a number in a range to a different range, returning a number **rounded** to the **closest** integer number. The result **WILL NOT** be limited (clamped) to the the given output range.*
+*Maps a number within a given range to a different range, returning a number **rounded** to the **closest** integer number. The result **WILL NOT** be limited (clamped) to the the given output range.*
 
 ***syntax***
 
 ```typescript
 function round(num: number, inMin: number, inMax: number, outMin: number, outMax: number): number;
 ```
 
+> *If you need to round to a specific number of decimal places, you can use the `transform` method and write your own round function.*
+
 ### limit
 
-#### alias: `clamp`
+***alias: `clamp`***
 
-*Maps a number in a range to a different range, returning a floting point number. The result will be limited (clamped) to the given output range.*
+*Maps a number within a given range to a different range, returning a floting point number. The result will be limited (clamped) to the given output range.*
 
 ***syntax***
 
@@ -119,14 +128,16 @@ function limit(num: number, inMin: number, inMax: number, outMin: number, outMax
 
 ### compile
 
-#### alias: `wrap`, `create`
+***alias: `wrap`, `create`***
 
-*Creates a single argument function implementing the given [`map`](#map), [`floor`](#floor), [`ceil`](#ceil), [`round`](#round), [`limit`](#limit) or [`clamp`](#limit) function. Useful when you need to map values multiple times within the same range, see example below.*
+*Creates a single argument function implementing the given [`map`](#map), [`floor`](#floor), [`ceil`](#ceil), [`round`](#round), [`limit`](#limit), [`clamp`](#limit) or user created function. Useful when you need to map values multiple times within the same range, see example below.*
 
 ***syntax***
 
 ```typescript
-function compile(func: MapNumberFunction, inMin: number, inMax: number, outMin: number, outMax: number): (num: number) => number;
+function compile<T>(func: MapFunction<T>, inMin: number, inMax: number, outMin: number, outMax: number): Compiled<T>;
+
+type Compiled<T> = (num: number) => T;
 ```
 
 ***example***
@@ -135,15 +146,39 @@ function compile(func: MapNumberFunction, inMin: number, inMax: number, outMin:
 import { map, round, compile } from "map-number";
 
 const myMap = compile(map, -1, 1, 100, 0);
-const myRound = compile(round, -1, 1, 100, 0);
 
 myMap(-0.2);
-myRound(0.33);
+myMap(0.33);
+myMap(0.5);
 
 // ... is equivalent to...
 
 map(-0.2, -1, 1, 100, 0);
-round(0.33, -1, 1, 100, 0);
+map(0.33, -1, 1, 100, 0);
+map(0.5, -1, 1, 100, 0);
+```
+
+### transform
+
+*Creates a map function where the result of the given function is transformed to a different value. This method is used internally to create the `floor`, `ceil` and `round` methods.*
+
+***syntax***
+
+```typescript
+function transform<T>(func: MapNumberFunction, transformer: (value: number) => T): MapFunction<T>;
+```
+
+***example***
+
+```javascript
+import { transform, map } from "map-number";
+
+const plusOne = transform(
+  map,
+  (value) => value + 1,
+);
+
+plusOne(0.4, 0, 1, 0, 100); // => 41
 ```
 
 ## License

diff --git a/__test__/alias.test.ts b/__test__/alias.test.ts
@@ -2,12 +2,12 @@ import { compile, create, wrap, limit, clamp } from '../src';
 
 describe('alias', () => {
 
-  test('should export compile alias', () => {
+  test('Should export compile alias', () => {
     expect(create).toBe(compile);
     expect(wrap).toBe(compile);
   });
 
-  test('should export limit alias', () => {
+  test('Should export limit alias', () => {
     expect(clamp).toBe(limit);
   });
 

diff --git a/__test__/ceil.test.ts b/__test__/ceil.test.ts
@@ -1,51 +1,45 @@
 import { ceil } from '../src';
-
-describe('ceil method', () => {
-
-  test('should return in-range output', () => {
-
-    expect(
-      ceil(23, 20, 50, 2, 5),
-    ).toBe(
-      3,
-    );
-
+import { expectValues } from './tools/test-values';
+
+describe('"ceil" method', () => {
+
+  test('Should return in-range output', () => {
+    expectValues([
+      { value: 20, expected: 2 },
+      { value: 50, expected: 5 },
+      { value: 30, expected: 3 },
+      { value: 31, expected: 4 },
+      { value: 39, expected: 4 },
+      { value: 40, expected: 4 },
+    ], ceil, 20, 50, 2, 5);
   });
 
-  test('should return out-range output', () => {
-
-    expect(
-      ceil(6, 20, 50, 2, 5),
-    ).toBe(
-      1,
-    );
-
-    expect(
-      ceil(62, 20, 50, 2, 5),
-    ).toBe(
-      7,
-    );
-
+  test('Should return out-range output', () => {
+    expectValues([
+      { value: 0, expected: 0 },
+      { value: 4, expected: 1 },
+      { value: 6, expected: 1 },
+      { value: 64, expected: 7 },
+      { value: 66, expected: 7 },
+    ], ceil, 20, 50, 2, 5);
   });
 
-  test('should invert in-range output', () => {
-
-    expect(
-      ceil(3.1, 1, 9, 9, 1),
-    ).toBe(
-      7,
-    );
-
+  test('Should invert in-range output', () => {
+    expectValues([
+      { value: 1, expected: 9 },
+      { value: 3.1, expected: 7 },
+      { value: 3.9, expected: 7 },
+      { value: 9, expected: 1 },
+    ], ceil, 1, 9, 9, 1);
   });
 
-  test('should invert out-range output', () => {
-
-    expect(
-      ceil(-1.3, 1, 9, 9, 1),
-    ).toBe(
-      12,
-    );
-
+  test('Should invert out-range output', () => {
+    expectValues([
+      { value: -1.3, expected: 12 },
+      { value: -1.9, expected: 12 },
+      { value: 10.1, expected: 0 },
+      { value: 10.9, expected: 0 },
+    ], ceil, 1, 9, 9, 1);
   });
 
 });
diff --git a/__test__/compile.test.ts b/__test__/compile.test.ts
@@ -1,18 +1,20 @@
-import { map, compile } from '../src';
+import { compile, map } from '../src';
 
-describe('wrap method', () => {
+describe('"compile" method', () => {
 
-  test('should return the correct output', () => {
+  test('Should return the correct output', () => {
 
     const boundaries: [number, number, number, number] = [2, 5, 20, 50];
-    const myMap = compile(map, ...boundaries);
+    const compiled = compile(map, ...boundaries);
 
-    const nums = [3.3, 0.01, 10];
+    const values = [
+      3.3,
+      0.01,
+      10,
+    ];
 
-    nums.forEach((num) => {
-      const myMapResult = myMap(num);
-      const mapResult = map(num, ...boundaries);
-      expect(myMapResult).toBe(mapResult);
+    values.forEach((value) => {
+      expect(compiled(value)).toBe(map(value, ...boundaries));
     });
 
   });

diff --git a/__test__/floor.test.ts b/__test__/floor.test.ts
@@ -1,51 +1,47 @@
 import { floor } from '../src';
-
-describe('floor method', () => {
-
-  test('should return in-range output', () => {
-
-    expect(
-      floor(23, 20, 50, 2, 5),
-    ).toBe(
-      2,
-    );
-
+import { expectValues } from './tools/test-values';
+
+describe('"floor" method', () => {
+
+  test('Should return in-range output', () => {
+    expectValues([
+      { value: 20, expected: 2 },
+      { value: 50, expected: 5 },
+      { value: 30, expected: 3 },
+      { value: 31, expected: 3 },
+      { value: 39, expected: 3 },
+      { value: 40, expected: 4 },
+    ], floor, 20, 50, 2, 5);
   });
 
-  test('should return out-range output', () => {
-
-    expect(
-      floor(6, 20, 50, 2, 5),
-    ).toBe(
-      0,
-    );
-
-    expect(
-      floor(62, 20, 50, 2, 5),
-    ).toBe(
-      6,
-    );
-
+  test('Should return out-range output', () => {
+    expectValues([
+      { value: 4, expected: 0 },
+      { value: 6, expected: 0 },
+      { value: 64, expected: 6 },
+      { value: 66, expected: 6 },
+    ], floor, 20, 50, 2, 5);
   });
 
-  test('should invert in-range output', () => {
-
-    expect(
-      floor(3.1, 1, 9, 9, 1),
-    ).toBe(
-      6,
-    );
-
+  test('Should invert in-range output', () => {
+    expectValues([
+      { value: 1, expected: 9 },
+      { value: 4, expected: 6 },
+      { value: 4.1, expected: 5 },
+      { value: 4.9, expected: 5 },
+      { value: 5, expected: 5 },
+      { value: 9, expected: 1 },
+    ], floor, 1, 9, 9, 1);
   });
 
-  test('should invert out-range output', () => {
-
-    expect(
-      floor(-1.3, 1, 9, 9, 1),
-    ).toBe(
-      11,
-    );
-
+  test('Should invert out-range output', () => {
+    expectValues([
+      { value: 0, expected: 10 },
+      { value: -0, expected: 10 },
+      { value: -1.3, expected: 11 },
+      { value: 10.1, expected: -1 },
+      { value: 10.9, expected: -1 },
+    ], floor, 1, 9, 9, 1);
   });
 
 });