@xeplr/nlp-parser 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xeplr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.js

@@ -0,0 +1,28 @@
+const { parse, parseCondition } = require('./lib/parser');
+const { evaluate, evaluateCondition, evaluateWhen, resolvePath } = require('./lib/evaluator');
+
+/**
+ * Parse a rule string into a structured action object.
+ *
+ * @param {string} rule - e.g. "if typeof $.header is string then <hide> [col1, col2]"
+ * @returns {{ action: { name, when: { lhs, op, rhs, rhsTo? }, applyOn?, value? } }}
+ */
+function parseNLP(rule) {
+  return parse(rule);
+}
+
+/**
+ * Parse + evaluate in one call.
+ * Returns the action object if the condition matches, otherwise null.
+ *
+ * @param {string} rule - the rule string
+ * @param {*} inputs - the data object ($ in the rule)
+ * @returns {object|null}
+ */
+function applyNLP(rule, inputs) {
+  const parsed = parse(rule);
+  const matches = evaluate(parsed, inputs);
+  return matches ? parsed.action : null;
+}
+
+module.exports = { parseNLP, applyNLP, evaluate, evaluateCondition, evaluateWhen, parseCondition, resolvePath };

package/lib/evaluator.js

@@ -0,0 +1,103 @@
+const { parseCondition } = require('./parser');
+
+/**
+ * Resolves a $-path against a data object.
+ * $.employee.department.name  →  data.employee.department.name
+ * $                           →  data (the root itself)
+ */
+function resolvePath(path, data) {
+  const parts = path.replace(/^\$\.?/, '').split('.');
+  let current = data;
+  for (const part of parts) {
+    if (!part) continue;
+    if (current == null) return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+/**
+ * Coerce value for numeric comparisons.
+ * If both sides can be numbers, compare as numbers.
+ */
+function toComparable(val) {
+  if (typeof val === 'number') return val;
+  if (typeof val === 'string' && !isNaN(val) && val !== '') return Number(val);
+  return val;
+}
+
+/**
+ * Evaluate a when condition object against data.
+ * when: { lhs, op, rhs, rhsTo? }
+ */
+function evaluateWhen(when, data) {
+  const raw = resolvePath(when.lhs, data);
+  const value = toComparable(raw);
+  const rhs = toComparable(when.rhs);
+
+  switch (when.op) {
+    case 'is':           return value === rhs;
+    case 'is_not':       return value !== rhs;
+    case 'is_null':      return raw == null || raw === '';
+    case 'is_not_null':  return raw != null && raw !== '';
+    case 'typeof':       return typeof raw === when.rhs;
+    case 'typeof_not':   return typeof raw !== when.rhs;
+    case '>':            return value > rhs;
+    case '<':            return value < rhs;
+    case '>=':           return value >= rhs;
+    case '<=':           return value <= rhs;
+    case 'between': {
+      const rhsTo = toComparable(when.rhsTo);
+      if (rhsTo == null) return value >= rhs;
+      return value >= rhs && value <= rhsTo;
+    }
+    case 'in': {
+      const list = Array.isArray(when.rhs) ? when.rhs : [when.rhs];
+      return list.some(item => toComparable(item) === value);
+    }
+    case 'not_in': {
+      const list = Array.isArray(when.rhs) ? when.rhs : [when.rhs];
+      return !list.some(item => toComparable(item) === value);
+    }
+    case 'starts_with': {
+      if (raw == null) return false;
+      return String(raw).toLowerCase().startsWith(String(when.rhs).toLowerCase());
+    }
+    case 'ends_with': {
+      if (raw == null) return false;
+      return String(raw).toLowerCase().endsWith(String(when.rhs).toLowerCase());
+    }
+    case 'contains': {
+      if (raw == null) return false;
+      return String(raw).toLowerCase().includes(String(when.rhs).toLowerCase());
+    }
+    case 'not_contains': {
+      if (raw == null) return false;
+      return !String(raw).toLowerCase().includes(String(when.rhs).toLowerCase());
+    }
+    default: return false;
+  }
+}
+
+/**
+ * Evaluates a parsed rule's condition against actual data.
+ * Returns true if the condition matches.
+ */
+function evaluate(parsed, data) {
+  return evaluateWhen(parsed.action.when, data);
+}
+
+/**
+ * Parse + evaluate a standalone condition string against data.
+ * No "if"/"then" needed — just the condition.
+ *
+ * @param {string} conditionStr - e.g. "$.status is active", "$.price > 100"
+ * @param {object} data         - the data object
+ * @returns {boolean}
+ */
+function evaluateCondition(conditionStr, data) {
+  var when = parseCondition(conditionStr);
+  return evaluateWhen(when, data);
+}
+
+module.exports = { evaluate, evaluateCondition, evaluateWhen, resolvePath };

package/lib/parser.js

@@ -0,0 +1,188 @@
+const { tokenize } = require('./tokenizer');
+
+/**
+ * Create a token walker with peek/advance/expect helpers.
+ */
+function createWalker(tokens) {
+  var pos = 0;
+  function peek() { return tokens[pos] || null; }
+  function advance() { return tokens[pos++]; }
+  function expect(type, value) {
+    const t = advance();
+    if (!t) throw new Error(`Unexpected end of rule, expected ${type}${value ? ' ' + value : ''}`);
+    if (t.type !== type || (value !== undefined && t.value !== value)) {
+      throw new Error(`Expected ${type} "${value || ''}", got ${t.type} "${t.value}"`);
+    }
+    return t;
+  }
+  return { peek, advance, expect };
+}
+
+/**
+ * Parse a condition from the token stream.
+ * condition := ['typeof'] path operator rhs ['and' rhs2]
+ *
+ * Returns { lhs, op, rhs, rhsTo? }
+ */
+function parseConditionTokens(w) {
+  // optional typeof
+  var usesTypeof = false;
+  if (w.peek() && w.peek().type === 'KEYWORD' && w.peek().value === 'typeof') {
+    w.advance();
+    usesTypeof = true;
+  }
+
+  var path = w.expect('PATH');
+
+  // operator
+  var op;
+  var opToken = w.peek();
+
+  if (opToken && opToken.type === 'OP') {
+    op = w.advance().value;
+    if (usesTypeof) op = 'typeof_' + op;
+  } else if (opToken && opToken.type === 'KEYWORD' && opToken.value === 'is') {
+    w.advance();
+    var negated = false;
+    if (w.peek() && w.peek().type === 'KEYWORD' && w.peek().value === 'not') {
+      w.advance();
+      negated = true;
+    }
+    if (w.peek() && w.peek().type === 'KEYWORD' && w.peek().value === 'null') {
+      w.advance();
+      op = negated ? 'is_not_null' : 'is_null';
+    } else {
+      op = usesTypeof ? 'typeof' : 'is';
+      if (negated) op += '_not';
+    }
+  } else if (opToken && opToken.type === 'KEYWORD' && opToken.value === 'not') {
+    w.advance();
+    if (w.peek() && w.peek().type === 'KEYWORD' && w.peek().value === 'in') {
+      w.advance();
+      op = 'not_in';
+    } else if (w.peek() && w.peek().type === 'KEYWORD' && w.peek().value === 'contains') {
+      w.advance();
+      op = 'not_contains';
+    } else {
+      throw new Error(`Expected "in" or "contains" after "not", got ${w.peek() ? w.peek().value : 'end of input'}`);
+    }
+  } else if (opToken && opToken.type === 'KEYWORD' && opToken.value === 'in') {
+    w.advance();
+    op = 'in';
+  } else if (opToken && opToken.type === 'KEYWORD' && opToken.value === 'starts') {
+    w.advance();
+    w.expect('KEYWORD', 'with');
+    op = 'starts_with';
+  } else if (opToken && opToken.type === 'KEYWORD' && opToken.value === 'ends') {
+    w.advance();
+    w.expect('KEYWORD', 'with');
+    op = 'ends_with';
+  } else if (opToken && opToken.type === 'KEYWORD' && opToken.value === 'contains') {
+    w.advance();
+    op = 'contains';
+  } else if (opToken && opToken.type === 'KEYWORD' && opToken.value === 'does') {
+    w.advance();
+    w.expect('KEYWORD', 'not');
+    // accept both "contain" and "contains"
+    var containToken = w.peek();
+    if (containToken && containToken.type === 'KEYWORD' && (containToken.value === 'contains' || containToken.value === 'contain')) {
+      w.advance();
+    } else {
+      throw new Error(`Expected "contain" or "contains" after "does not", got ${containToken ? containToken.value : 'end of input'}`);
+    }
+    op = 'not_contains';
+  } else if (opToken && opToken.type === 'KEYWORD' && opToken.value === 'between') {
+    w.advance();
+    op = 'between';
+  } else {
+    throw new Error(`Expected operator, got ${opToken ? opToken.type + ' ' + opToken.value : 'end of input'}`);
+  }
+
+  // rhs
+  var rhs = null;
+  var rhsTo = null;
+  if (op !== 'is_null' && op !== 'is_not_null') {
+    var rhsToken = w.peek();
+    if (rhsToken && rhsToken.type === 'STRING') {
+      rhs = w.advance().value;
+    } else if (rhsToken && rhsToken.type === 'NUMBER') {
+      rhs = w.advance().value;
+    } else if (rhsToken && rhsToken.type === 'IDENTIFIER') {
+      rhs = w.advance().value;
+    } else if (rhsToken && rhsToken.type === 'ARRAY') {
+      rhs = w.advance().value;
+    } else {
+      throw new Error(`Expected value after operator, got ${rhsToken ? rhsToken.type : 'end of input'}`);
+    }
+
+    // between X and Y
+    if (op === 'between' && w.peek() && w.peek().type === 'KEYWORD' && w.peek().value === 'and') {
+      w.advance();
+      var toToken = w.peek();
+      if (toToken && (toToken.type === 'NUMBER' || toToken.type === 'STRING' || toToken.type === 'IDENTIFIER')) {
+        rhsTo = w.advance().value;
+      } else {
+        throw new Error(`Expected second value after "and" in between, got ${toToken ? toToken.type : 'end of input'}`);
+      }
+    }
+  }
+
+  var when = { lhs: path.value, op: op, rhs: rhs };
+  if (rhsTo !== null) when.rhsTo = rhsTo;
+  return when;
+}
+
+/**
+ * Parse a full rule: "if <condition> then <action/return>"
+ */
+function parse(rule) {
+  var tokens = tokenize(rule);
+  var w = createWalker(tokens);
+
+  w.expect('KEYWORD', 'if');
+  var when = parseConditionTokens(w);
+  w.expect('KEYWORD', 'then');
+
+  // result := '<action>' '[targets]' | 'return' value
+  var next = w.peek();
+  if (!next) throw new Error('Unexpected end of rule after "then"');
+
+  if (next.type === 'ACTION') {
+    var actionName = w.advance().value;
+    var applyOn = [];
+    if (w.peek() && w.peek().type === 'ARRAY') {
+      applyOn = w.advance().value;
+    }
+    return { action: { name: actionName, when: when, applyOn: applyOn } };
+  }
+
+  if (next.type === 'KEYWORD' && next.value === 'return') {
+    w.advance();
+    var valToken = w.peek();
+    var value;
+    if (valToken && valToken.type === 'STRING') {
+      value = w.advance().value;
+    } else if (valToken && valToken.type === 'IDENTIFIER') {
+      value = w.advance().value;
+    } else {
+      throw new Error(`Expected return value, got ${valToken ? valToken.type : 'end of input'}`);
+    }
+    return { action: { name: 'return', when: when, value: value } };
+  }
+
+  throw new Error(`Expected <action> or return, got ${next.type} "${next.value}"`);
+}
+
+/**
+ * Parse a standalone condition string (no "if"/"then" needed).
+ * Input: "$.field is active" or "$.price > 100" or "$.name starts with 'Jo'"
+ *
+ * Returns: { lhs, op, rhs, rhsTo? }
+ */
+function parseCondition(conditionStr) {
+  var tokens = tokenize(conditionStr);
+  var w = createWalker(tokens);
+  return parseConditionTokens(w);
+}
+
+module.exports = { parse, parseCondition };

package/lib/tokenizer.js

@@ -0,0 +1,113 @@
+const KEYWORDS = new Set(['if', 'typeof', 'is', 'not', 'in', 'then', 'return', 'and', 'or', 'null', 'starts', 'ends', 'with', 'contains', 'contain', 'does', 'between']);
+
+function tokenize(input) {
+  const tokens = [];
+  let i = 0;
+
+  while (i < input.length) {
+    // whitespace
+    if (/\s/.test(input[i])) { i++; continue; }
+
+    // path: $...
+    if (input[i] === '$') {
+      let path = '';
+      while (i < input.length && /[a-zA-Z0-9_.$]/.test(input[i])) {
+        path += input[i++];
+      }
+      tokens.push({ type: 'PATH', value: path });
+      continue;
+    }
+
+    // comparison operators: >=, <=, >, <
+    // distinguish from <action> by peeking: if '<' is followed by '=' it's <=
+    // if '<' is followed by a word and then '>' it's an action
+    if (input[i] === '>' && input[i + 1] === '=') {
+      tokens.push({ type: 'OP', value: '>=' }); i += 2; continue;
+    }
+    if (input[i] === '>') {
+      tokens.push({ type: 'OP', value: '>' }); i++; continue;
+    }
+    if (input[i] === '<' && input[i + 1] === '=') {
+      tokens.push({ type: 'OP', value: '<=' }); i += 2; continue;
+    }
+    if (input[i] === '<') {
+      // peek ahead: if content until '>' looks like a word, it's an <action>
+      let j = i + 1;
+      let candidate = '';
+      while (j < input.length && input[j] !== '>' && input[j] !== '<' && input[j] !== '\n') {
+        candidate += input[j++];
+      }
+      if (j < input.length && input[j] === '>' && /^[a-zA-Z_][\w-]*$/.test(candidate.trim())) {
+        // it's an <action>
+        i++; // skip <
+        let name = '';
+        while (i < input.length && input[i] !== '>') {
+          name += input[i++];
+        }
+        if (i < input.length) i++; // skip >
+        tokens.push({ type: 'ACTION', value: name.trim() });
+        continue;
+      }
+      // otherwise it's the < operator
+      tokens.push({ type: 'OP', value: '<' }); i++; continue;
+    }
+
+    // array: [a, b, c]
+    if (input[i] === '[') {
+      i++;
+      let content = '';
+      while (i < input.length && input[i] !== ']') {
+        content += input[i++];
+      }
+      if (i < input.length) i++; // skip ]
+      const items = content.split(',').map(s => s.trim()).filter(Boolean);
+      tokens.push({ type: 'ARRAY', value: items });
+      continue;
+    }
+
+    // string literal: 'value' or "value"
+    if (input[i] === "'" || input[i] === '"') {
+      const quote = input[i++];
+      let str = '';
+      while (i < input.length && input[i] !== quote) {
+        str += input[i++];
+      }
+      if (i < input.length) i++; // skip closing quote
+      tokens.push({ type: 'STRING', value: str });
+      continue;
+    }
+
+    // number: 123, 3.14, -5
+    if (/[0-9]/.test(input[i]) || (input[i] === '-' && i + 1 < input.length && /[0-9]/.test(input[i + 1]))) {
+      let num = '';
+      if (input[i] === '-') { num += input[i++]; }
+      while (i < input.length && /[0-9.]/.test(input[i])) {
+        num += input[i++];
+      }
+      tokens.push({ type: 'NUMBER', value: Number(num) });
+      continue;
+    }
+
+    // word: keyword or identifier
+    if (/[a-zA-Z_]/.test(input[i])) {
+      let word = '';
+      while (i < input.length && /[a-zA-Z0-9_]/.test(input[i])) {
+        word += input[i++];
+      }
+      const lower = word.toLowerCase();
+      if (KEYWORDS.has(lower)) {
+        tokens.push({ type: 'KEYWORD', value: lower });
+      } else {
+        tokens.push({ type: 'IDENTIFIER', value: word });
+      }
+      continue;
+    }
+
+    // skip unknown characters
+    i++;
+  }
+
+  return tokens;
+}
+
+module.exports = { tokenize };

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@xeplr/nlp-parser",
+  "version": "1.0.0",
+  "description": "Isomorphic NLP rule parser — parses a simple DSL into structured action objects",
+  "main": "index.js",
+  "files": ["index.js", "lib/"],
+  "keywords": ["nlp", "parser", "dsl", "isomorphic"],
+  "author": "xeplr",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/Xeplr/xeplr-nlp-parser" },
+  "publishConfig": { "access": "public" }
+}