From ab591f94275d003ef2dd636fbed5442edb07c452 Mon Sep 17 00:00:00 2001 From: ismail reida Date: Tue, 3 Nov 2026 23:19:05 +0100 Subject: [PATCH] Add match(): most specific partial pattern lookup --- README.md | 19 +++++++++++++++++-- devisPattern.js | 20 +++++++++++++++++++- package.json | 4 ++-- test/devisPattern.js | 44 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 82 insertions(+), 5 deletions(-) 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.

Version @@ -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); +});