diff --git a/README.md b/README.md
index 7185e6d..c45bb50 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
# DevisPattern
->An exact-match pattern matcher on JavaScript object properties.
+>A pattern matcher on JavaScript object properties.
@@ -44,10 +44,21 @@ devisPattern.call({
## Matching rules
-A pattern matches only an identical pattern: same keys, same values, same key order. Patterns are compared by their `JSON.stringify` form, so `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` are different patterns, and `{ a: 1 }` does not match `{ a: 1, b: 2 }`.
+`find` matches only an identical pattern: same keys, same values, same key order. Patterns are compared by their `JSON.stringify` form, so `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` are different patterns, and `{ a: 1 }` does not match `{ a: 1, b: 2 }`.
When the same pattern is added twice, the first handler is kept.
+`match` is the partial lookup used by Devis 4.1: a registered pattern matches when all its keys appear in the looked-up pattern with the same values. The pattern with the most keys wins, and the first registered wins a tie:
+
+```JavaScript
+devisPattern.add({ role: "math" }, any);
+devisPattern.add({ role: "math", cmd: "sum" }, sum);
+
+devisPattern.match({ role: "math", cmd: "sum", version: 2 }); // { handle: sum, size: 2 }
+devisPattern.match({ role: "math", cmd: "divide" }); // { handle: any, size: 1 }
+devisPattern.match({ cmd: "sum" }); // null
+```
+
## API
### new DevisPattern()
@@ -62,6 +73,10 @@ Registers a pattern and the handler returned when an identical pattern is looked
Returns the handler registered for this pattern, or `null`.
+### .match( {...pattern...} )
+
+Returns `{ handle, size }` for the most specific registered pattern contained in this one, where `size` is its number of keys, or `null`.
+
### .call( {...pattern...}, [{...arguments...}], callback )
Calls the handler registered for this pattern with `(arguments, callback)`. `arguments` defaults to `{}`. Does nothing when no handler matches.
diff --git a/devisPattern.js b/devisPattern.js
index f12e4b0..8d88ccc 100644
--- a/devisPattern.js
+++ b/devisPattern.js
@@ -7,13 +7,17 @@ class devisPattern {
this.path = [];
this.id = 0;
this.index = new Map();
+ this.entries = [];
}
add(path, handle) {
this.path[this.id] = handle;
const key = JSON.stringify(path);
// First registration wins, as with the former native addon.
- if (!this.index.has(key)) {this.index.set(key, this.id);}
+ if (!this.index.has(key)) {
+ this.index.set(key, this.id);
+ this.entries.push({ path: path, id: this.id });
+ }
this.id++;
return this;
}
@@ -24,6 +28,20 @@ class devisPattern {
else {return null;}
}
+ // Most specific registered pattern whose keys all appear in path with the same values; the first registered wins a tie.
+ match(path) {
+ const exact = this.find(path);
+ if (exact) {return { handle: exact, size: Object.keys(path).length };}
+ let best = null;
+ for (const entry of this.entries) {
+ const keys = Object.keys(entry.path);
+ if (best && keys.length <= best.size) {continue;}
+ const matches = keys.every((key) => Object.hasOwn(path, key) && JSON.stringify(path[key]) === JSON.stringify(entry.path[key]));
+ if (matches) {best = { handle: this.path[entry.id], size: keys.length };}
+ }
+ return best;
+ }
+
call(path, args, callback) {
if (!callback) {
callback = args;
diff --git a/package.json b/package.json
index 275a83e..898ee78 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
{
"name": "devisPattern",
- "version": "2.0.0",
- "description": "An exact-match pattern matcher on JavaScript object properties",
+ "version": "2.1.0",
+ "description": "An exact and partial pattern matcher on JavaScript object properties",
"main": "devisPattern.js",
"files": [
"devisPattern.js"
diff --git a/test/devisPattern.js b/test/devisPattern.js
index a313ad7..f868db1 100644
--- a/test/devisPattern.js
+++ b/test/devisPattern.js
@@ -67,3 +67,47 @@ test("list returns a JSON array string of registered patterns", () => {
matcher.add({ cmd: "b", n: 1 }, () => {});
assert.deepStrictEqual(JSON.parse(matcher.list()), [{ cmd: "a" }, { cmd: "b", n: 1 }]);
});
+
+test("match returns the handle of an identical pattern with its key count", () => {
+ const matcher = new DevisP();
+ const sum = () => {};
+ matcher.add({ role: "math", cmd: "sum" }, sum);
+ assert.deepStrictEqual(matcher.match({ role: "math", cmd: "sum" }), { handle: sum, size: 2 });
+});
+
+// A caller may send more keys than the handler cares about, such as a version or a tenant.
+test("match resolves a registered pattern contained in a larger one", () => {
+ const matcher = new DevisP();
+ const sum = () => {};
+ matcher.add({ role: "math", cmd: "sum" }, sum);
+ assert.strictEqual(matcher.match({ role: "math", cmd: "sum", version: 2 }).handle, sum);
+ assert.strictEqual(matcher.match({ role: "math" }), null);
+ assert.strictEqual(matcher.match({ role: "math", cmd: "divide" }), null);
+});
+
+// A generic handler must not shadow a specific one, whatever the registration order.
+test("match prefers the pattern with the most keys", () => {
+ const matcher = new DevisP();
+ const any = () => {};
+ const sum = () => {};
+ matcher.add({ role: "math" }, any);
+ matcher.add({ role: "math", cmd: "sum" }, sum);
+ assert.strictEqual(matcher.match({ role: "math", cmd: "sum", x: 1 }).handle, sum);
+ assert.strictEqual(matcher.match({ role: "math", cmd: "divide" }).handle, any);
+});
+
+test("match keeps the first registered pattern on a tie", () => {
+ const matcher = new DevisP();
+ const byRole = () => {};
+ matcher.add({ role: "math" }, byRole);
+ matcher.add({ cmd: "sum" }, () => {});
+ assert.strictEqual(matcher.match({ role: "math", cmd: "sum" }).handle, byRole);
+});
+
+test("match compares values, not only keys", () => {
+ const matcher = new DevisP();
+ matcher.add({ role: "math", options: { precise: true } }, () => {});
+ assert.notStrictEqual(matcher.match({ role: "math", options: { precise: true } }), null);
+ assert.strictEqual(matcher.match({ role: "math", options: { precise: false } }), null);
+ assert.strictEqual(matcher.match({ role: "1" }), null);
+});