@mkrause/match - npm Package Compare versions

Comparing version 1.0.5 to 1.0.6

LICENSE.md

@@ -1,2 +0,2 @@
-Copyright (c) 2017 M. Krause
+Copyright (c) 2017 M.R. Krause
 
@@ -3,0 +3,0 @@ Permission is hereby granted, free of charge, to any person obtaining a copy

package.json

 {
     "name": "@mkrause/match",
-    "version": "1.0.5",
-    "description": "Pattern matching utility for JavaScript.",
+    "version": "1.0.6",
+    "description": "Matching utility for JavaScript.",
     "author": "mkrause",
@@ -6,0 +6,0 @@ "license": "MIT",

README.md

 
 # match.js
 
-JavaScript pattern matching utility.
+JavaScript matching utility. Allows you to branch on a value using a list of different possible cases.
 
@@ -9,6 +9,14 @@
 
-Using an object:
+The `match` function takes a value, and a list of cases, and returns either the first case that matches, or an exception otherwise.
 
 ```js
-    const { match } = require('@mkrause/match');
+    import match from '@mkrause/match'; // If using ES6 modules
+    const { match } = require('@mkrause/match'); // If using ES5
+    
+    match(<value>, <case-list>);
+```
+
+The case list can be specified in one of two ways. If the value is a string (or if we're using a custom matcher, see below) then we can use an object where the value is matched against each property name.
+
+```js
     const result = match('foo', {
@@ -21,10 +29,9 @@ foo: 42,
 
-Using a predicate list:
+Alternatively, we can specify a list of predicates (functions) using `match.case(<predicate>, <result>)`. Each predicate is given the value and should return a boolean indicating whether there is a match.
 
 ```js
-    const { match } = require('@mkrause/match');
-    const result = match({ value: 42 }, [
-        match.case(({ value }) => value > 0, +1),
-        match.case(({ value }) => value == 0, 0),
-        match.case(({ value }) => value < 0, -1),
+    const result = match({ position: 42 }, [
+        match.case(x => x.position > 0, +1),
+        match.case(x => x.position == 0, 0),
+        match.case(x => x.position < 0, -1),
     ]);
@@ -34,3 +41,31 @@ result === 1;
 
+A case result can be either a plain value, or a function:
 
+```js
+    const result = match('apple', {
+        apple: () => processApple(),
+        orange: () => processOrange(),
+    });
+```
+
+A default case can be specified as fallback. With an object as case list, a special symbol `match.default` is available which can be used as unambiguous property name. With a case list, use `match.otherwise`.
+
+```js
+    const result = match('pear', {
+        apple: () => processApple(),
+        orange: () => processOrange(),
+        [match.default]: fruitType => processOther(fruitType),
+    });
+    
+    const result = match({ color: 'yellow' }, [
+        match.case(({ color }) => color === 'red', 0xff0000),
+        match.case(({ color }) => color === 'green', 0x00ff00),
+        match.case(({ color }) => color === 'blue', 0x0000ff),
+        match.otherwise('unknown color!'),
+    ]);
+```
+
+If no case matches, and no fallback is given, an exception is thrown.
+
+
 ## Custom match semantics
@@ -41,3 +76,3 @@
 ```js
-    const { matcher } = require('@mkrause/match');
+    import { matcher } from '@mkrause/match';
     
@@ -61,3 +96,3 @@ const match = matcher(subject => {
 ```js
-    const { matchType, matchSingleKey } = require('@mkrause/match');
+    import { matchType, matchSingleKey } from '@mkrause/match';
     
@@ -64,0 +99,0 @@ const action = { type: 'CREATE_USER', error: false, payload: { name: 'John' } };

src/match.js

@@ -27,3 +27,3 @@ 'use strict';
     case: (predicate, value) => [predicate, value],
-    otherwise: fn => [defaultCase, fn ],
+    otherwise: fn => [defaultCase, fn],
     default: defaultCase,
@@ -30,0 +30,0 @@ };

No alert changes

Improved metrics

Total package byte prevSize

16137

10.82%

Number of lines in readme file

110

46.67%

No dependency changes