feelin 7.0.1 → 7.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d14d729a1a7a6dfac83eae232db700fe7ee2772e6c6a73b0697d26451b9acb1f
-  data.tar.gz: f1ce26b4fe80144b014c50ee6c23d2cf8b1b018044d0143a3838933ef3c164f4
+  metadata.gz: 1d42d010d26029134be39b2bcdbd097683a00b0866820f1d816f69607b5bd053
+  data.tar.gz: cbee6c7dc98e5c2e078ebdecdbe3abac6dee702966841ffa3e5a3df399e69853
 SHA512:
-  metadata.gz: 3a1ddc86be9fadbb2043bb23b881b198c81962635276324ad4950c605078f128d3bc5e96f7cca4031633aca42f5084a042e7b20f696e86878117daf3e6d707e2
-  data.tar.gz: de182a5cdeb48279e195090b9f93c651fef336b8db7dd6b176e721e32edbd9ea6fd53d31037d789227ec0bf09ed541acf0e60e7a5931801edd25e14676c6b775
+  metadata.gz: 247e1e7cce0bf1a66df682268273282000c3ef98ba755af7ac213f5b9c978cb30aa9f68bef46e4ab49ff0c2573cf25838ed11e0da51aca861d0b30ccd268f7cf
+  data.tar.gz: 5ff326f4111002f0f65fef3e84f31bf307d1fea982372c72805936ada9484e8b579a57fe853a3a88c1cf2f35b4b116271996327498853b8ef608969a3483050b

data/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.0.3] - 2026-10-05
+
+### Changed
+
+* **Breaking:** `FEELIN.parse` is `FEELIN.parse_expression`, after feelin's own `parseExpression`.
+* **Breaking:** errors are the gem's own. A failure inside V8 is raised as `FEELIN::Error` — `FEELIN::SyntaxError` for an expression that does not parse, `FEELIN::TimeoutError` and `FEELIN::MemoryError` for a context's limits — instead of `MiniRacer::RuntimeError`, `MiniRacer::ScriptTerminatedError` and `MiniRacer::V8OutOfMemoryError`. The message names the expression, also available as `error.expression`; `error.reason` is the cause without it. An exception raised by a custom function still passes unwrapped.
+* **Breaking:** a custom function receives a date, a time and a duration as their ISO 8601 strings — the form a result has — instead of a hash of the internal fields of the JavaScript object.
+
+## [7.0.2] - 2026-10-05
+
+### Added
+
+* `FEELIN.parse` and `FEELIN.parse_unary_tests` answer the syntax tree of an expression as nested hashes (`type`, `from`, `to`, `text`, `children`), without evaluating it. A syntax error raises with the message `evaluate` gives.
+* `FEELIN::Context` — a V8 context of one's own, with the same methods as the module, optional `timeout` and `max_memory` limits, and custom functions of its own. All contexts start from one snapshot of the bundle.
+
+### Changed
+
+* Updated the bundled `feelin` JavaScript library to 7.0.2 (prototype access from FEEL expressions is prevented).
+* **Breaking:** a result is JSON-compatible. A date, a time and a duration are now the ISO 8601 strings FEEL's `string()` gives them (`"2020-01-02"`, `"10:00:00+03:00"`, `"2020-01-02T03:04:05Z"`, `"P1DT2H"`) instead of a hash of the internal fields of the JavaScript object. A function is a hash of its `parameterNames`.
+* The context is passed to V8 as an argument rather than written into the evaluated script, so V8 no longer compiles and keeps a script per distinct context. Measured speed is the same as before.
+
 ## [7.0.1] - 2026-06-22
 
 ### Changed

data/README.md

@@ -21,6 +21,16 @@ FEELIN.evaluate('for a in [1, 2, 3] return a * 2') # [ 2, 4, 6 ]
 FEELIN.evaluate("Mike's daughter.name", { 'Mike\'s daughter.name' => 'Lisa' }) # Lisa
 ```
 
+A result is JSON-compatible. A date, a time and a duration come back as ISO 8601 strings, in the form
+FEEL's own `string()` gives them:
+
+```ruby
+FEELIN.evaluate('date("2020-01-02") + duration("P1D")') # "2020-01-03"
+FEELIN.evaluate('date and time("2020-01-02T03:04:05Z")') # "2020-01-02T03:04:05Z"
+FEELIN.evaluate('time("10:00:00+03:00")')                # "10:00:00+03:00"
+FEELIN.evaluate('duration("P1DT2H")')                    # "P1DT2H"
+```
+
 ### Unary tests
 
 ```ruby
@@ -31,6 +41,38 @@ FEELIN.unary_test('1', 1) # true
 FEELIN.unary_test('[1..end]', 1, { 'end' => 10 }) # true
 ```
 
+### Syntax tree
+
+`parse_expression` and `parse_unary_tests` answer the syntax tree of an expression without evaluating it — for
+translating FEEL into something else (SQL, for one) or inspecting what an expression refers to.
+
+```ruby
+FEELIN.parse_expression('price > 10')
+# { "type" => "Expression", "from" => 0, "to" => 10, "text" => "price > 10", "children" => [
+#   { "type" => "Comparison", "from" => 0, "to" => 10, "text" => "price > 10", "children" => [
+#     { "type" => "VariableName", "from" => 0, "to" => 5, "text" => "price", "children" => [
+#       { "type" => "Identifier", "from" => 0, "to" => 5, "text" => "price", "children" => [] } ] },
+#     { "type" => "CompareOp", "from" => 6, "to" => 7, "text" => ">", "children" => [] },
+#     { "type" => "NumericLiteral", "from" => 8, "to" => 10, "text" => "10", "children" => [] } ] } ] }
+
+FEELIN.parse_unary_tests('[1..end], > 5')
+```
+
+The tree is the one feelin's parser ([lezer-feel](https://github.com/nikku/lezer-feel)) builds, node for
+node: `type` is the grammar's name of the node, and keywords and punctuation (`if`, `(`, `,`) are nodes as
+well. `from` / `to` are the span in the expression, counted in UTF-16 code units as JavaScript counts —
+for text outside the Basic Multilingual Plane that differs from Ruby's character index, so take `text`
+rather than slicing the expression.
+
+The optional second argument is a context, of which only the names matter: it is what lets a name with
+spaces in it be read as one name.
+
+```ruby
+FEELIN.parse_expression("Mike's daughter.name + 1", { "Mike's daughter.name" => nil })
+```
+
+An expression that does not parse raises `FEELIN::SyntaxError`, with the same message `evaluate` gives.
+
 ### Custom functions
 
 ```ruby
@@ -38,6 +80,62 @@ FEELIN.add_function('rates', proc { [10, 20] })
 FEELIN.evaluate('every rate in rates() satisfies rate < 10') # false
 ```
 
+Arguments reach the function in the form a result has: a date, a time and a duration as their ISO 8601
+strings, wherever they are among the arguments. What the function returns is plain data to FEEL — an ISO
+string it returns is a string there, and `date(...)` makes a date of it.
+
+```ruby
+FEELIN.add_function('last day of month', proc do |date|
+  day = Date.iso8601(date)
+  Date.new(day.year, day.month, -1).iso8601
+end)
+FEELIN.evaluate('date(last day of month(date("2024-02-10"))) + duration("P1D")') # "2024-03-01"
+```
+
+### A context of one's own
+
+The methods above work on one shared V8 context, which has no limits. `FEELIN::Context` is a separate
+one with the same methods — for an expression that is not trusted to end or to stay small, or for custom
+functions the rest of the process should not see.
+
+```ruby
+context = FEELIN::Context.new(timeout: 1_000, max_memory: 64_000_000) # ms, bytes; both optional
+
+context.add_function('rate', proc { 0.2 })
+context.evaluate('price * rate()', { 'price' => 100 }) # 20
+context.parse_expression('price * rate()')
+
+context.dispose
+```
+
+Past its timeout an evaluation raises `FEELIN::TimeoutError`, past its memory `FEELIN::MemoryError`.
+Contexts are created from one snapshot of the bundle, so a new one does not load feelin again.
+
+### Errors
+
+Whatever goes wrong inside V8 is raised as a `FEELIN::Error`, never as an error of MiniRacer. Its message
+names the expression, which is also there as `error.expression`; `error.reason` is what went wrong without
+it.
+
+| error | when |
+|---|---|
+| `FEELIN::SyntaxError` | the expression does not parse |
+| `FEELIN::TimeoutError` | the evaluation ran past the context's `timeout` |
+| `FEELIN::MemoryError` | the evaluation ran past the context's `max_memory` |
+| `FEELIN::Error` | anything else, and the parent of the three above |
+
+```ruby
+begin
+  FEELIN.evaluate('1 +')
+rescue FEELIN::SyntaxError => e
+  e.message    # "1 +" is not a FEEL expression: Incomplete <ArithmeticExpression>
+  e.expression # 1 +
+  e.reason     # Incomplete <ArithmeticExpression>
+end
+```
+
+An exception raised by a custom function is not wrapped: it reaches the caller as it was raised.
+
 ## Development
 
 The gem embeds the [feelin](https://github.com/nikku/feelin) JavaScript library, pre-bundled into a single file that is loaded into the V8 context at runtime. The JavaScript sources live in `lib/feelin/js`.

data/lib/feelin/js/dist/feelin.js

@@ -24,6 +24,7 @@ var feel = (() => {
     date: () => date,
     duration: () => duration,
     evaluate: () => evaluate,
+    json: () => json,
     parseExpression: () => parseExpression,
     parseUnaryTests: () => parseUnaryTests,
     unaryTest: () => unaryTest
@@ -11477,6 +11478,56 @@ var feel = (() => {
   });
 
   // node_modules/feelin/dist/index.js
+  function parseParameterNames(fn2) {
+    if (Array.isArray(fn2.$args)) {
+      return fn2.$args;
+    }
+    const code = fn2.toString();
+    const match2 = /^(?:[^(]*\s*)?\(([^)]+)?\)/.exec(code);
+    if (!match2) {
+      throw new Error("failed to parse params: " + code);
+    }
+    const [_, params] = match2;
+    if (!params) {
+      return [];
+    }
+    return params.split(",").map((p) => p.trim());
+  }
+  function notImplemented(thing) {
+    return new Error(`not implemented: ${thing}`);
+  }
+  function isNotImplemented(err) {
+    return /^not implemented/.test(err.message);
+  }
+  function has2(context, name2) {
+    if (Object.prototype.hasOwnProperty.call(context, name2)) {
+      return true;
+    }
+    for (let proto = Object.getPrototypeOf(context); proto && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+      const descriptor = Object.getOwnPropertyDescriptor(proto, name2);
+      if (descriptor) {
+        return typeof descriptor.get === "function";
+      }
+    }
+    return false;
+  }
+  function getFromContext(name2, context) {
+    if (["nil", "boolean", "number", "string"].includes(getType(context))) {
+      return void 0;
+    }
+    if (has2(context, name2)) {
+      return context[name2];
+    }
+    const normalizedName = normalizeContextKey(name2);
+    if (has2(context, normalizedName)) {
+      return context[normalizedName];
+    }
+    const entry = Object.entries(context).find(([key]) => normalizedName === normalizeContextKey(key));
+    if (entry) {
+      return entry[1];
+    }
+    return void 0;
+  }
   function isNil2(e) {
     return e === null || e === void 0;
   }
@@ -11620,7 +11671,7 @@ var feel = (() => {
       if (aEntries.length !== bEntries.length) {
         return false;
       }
-      return aEntries.every(([key, value]) => key in b && equals(value, b[key]));
+      return aEntries.every(([key, value]) => has2(b, key) && equals(value, b[key]));
     }
     if (aType === "range") {
       return [
@@ -11672,44 +11723,6 @@ var feel = (() => {
       return this.fn.call(null, ...params);
     }
   };
-  function parseParameterNames(fn2) {
-    if (Array.isArray(fn2.$args)) {
-      return fn2.$args;
-    }
-    const code = fn2.toString();
-    const match2 = /^(?:[^(]*\s*)?\(([^)]+)?\)/.exec(code);
-    if (!match2) {
-      throw new Error("failed to parse params: " + code);
-    }
-    const [_, params] = match2;
-    if (!params) {
-      return [];
-    }
-    return params.split(",").map((p) => p.trim());
-  }
-  function notImplemented(thing) {
-    return new Error(`not implemented: ${thing}`);
-  }
-  function isNotImplemented(err) {
-    return /^not implemented/.test(err.message);
-  }
-  function getFromContext(name2, context) {
-    if (["nil", "boolean", "number", "string"].includes(getType(context))) {
-      return void 0;
-    }
-    if (name2 in context) {
-      return context[name2];
-    }
-    const normalizedName = normalizeContextKey(name2);
-    if (normalizedName in context) {
-      return context[normalizedName];
-    }
-    const entry = Object.entries(context).find(([key]) => normalizedName === normalizeContextKey(key));
-    if (entry) {
-      return entry[1];
-    }
-    return void 0;
-  }
   function duration(opts) {
     if (typeof opts === "number") {
       return Duration.fromMillis(opts);
@@ -12236,7 +12249,7 @@ var feel = (() => {
         if (key === null) {
           return FALSE;
         }
-        if (key in context2) {
+        if (has2(context2, key)) {
           return FALSE;
         }
         return Object.assign(Object.assign({}, context2), { [entry.key]: entry.value });
@@ -13626,5 +13639,77 @@ var feel = (() => {
     }
     return String(value);
   }
+
+  // entry.js
+  function syntaxError(input, node) {
+    const parent = node.parent;
+    let message, position = { from: node.from, to: node.to };
+    if (node.from !== node.to) {
+      message = `Unrecognized token in <${parent.name}>`;
+    } else {
+      let next = null;
+      for (let current = node; current && !next; current = current.parent) {
+        next = current.nextSibling;
+      }
+      if (next) {
+        message = `Unrecognized token <${next.name}> in <${parent.name}>`;
+        position = { from: next.from, to: next.to };
+      } else {
+        message = `Incomplete <${(parent.enterUnfinishedNodesBefore(node.to) || parent).name}>`;
+      }
+    }
+    return new SyntaxError2(message, { input: input.slice(position.from, position.to), position });
+  }
+  function toAst(tree, input) {
+    const build = (node) => {
+      if (node.type.isError) {
+        throw syntaxError(input, node);
+      }
+      const children = [];
+      for (let child = node.firstChild; child; child = child.nextSibling) {
+        children.push(build(child));
+      }
+      return { type: node.name, from: node.from, to: node.to, text: input.slice(node.from, node.to), children };
+    };
+    return build(tree.topNode);
+  }
+  function replacer(key, value) {
+    const raw = this[key];
+    if (raw && (raw.isLuxonDateTime || raw.isLuxonDuration)) {
+      return evaluate("string(v)", { v: raw }).value;
+    }
+    return value;
+  }
+  var toJson = (value) => JSON.stringify(value === void 0 ? null : value, replacer);
+  var functions = {};
+  var hasFunctions = false;
+  function readContext(contextJson) {
+    const context = (contextJson == null ? null : JSON.parse(contextJson)) || {};
+    return hasFunctions ? Object.assign(context, functions) : context;
+  }
+  function guarded(fn2) {
+    return (...args) => {
+      try {
+        return fn2(...args);
+      } catch (error) {
+        if (error instanceof SyntaxError2) {
+          error.name = "FeelSyntaxError";
+        }
+        throw error;
+      }
+    };
+  }
+  var json = {
+    evaluate: guarded((expression, contextJson) => toJson(evaluate(expression, readContext(contextJson)).value)),
+    unaryTest: guarded((expression, contextJson) => toJson(unaryTest(expression, readContext(contextJson)).value)),
+    parseExpression: guarded((expression, contextJson) => JSON.stringify(toAst(parseExpression(expression, readContext(contextJson)), expression))),
+    parseUnaryTests: guarded((expression, contextJson) => JSON.stringify(toAst(parseUnaryTests(expression, readContext(contextJson)), expression))),
+    addFunction: (name2) => {
+      functions[name2] = function(...args) {
+        return globalThis[name2](...JSON.parse(toJson(args)));
+      };
+      hasFunctions = true;
+    }
+  };
   return __toCommonJS(entry_exports);
 })();

data/lib/feelin/js/entry.js

@@ -1 +1,112 @@
+import { evaluate, unaryTest, parseExpression, parseUnaryTests, SyntaxError } from 'feelin';
+
 export * from 'feelin';
+
+// The JSON boundary of the Ruby wrapper: everything below takes its context as a JSON string and answers
+// with one, so no value is marshalled between Ruby and V8 element by element, and no script is compiled
+// per call — a call is a function call, whatever the data.
+
+// feelin keeps its own syntax error reporting private, and parseExpression / parseUnaryTests answer with a
+// tree that has error nodes in it instead of throwing. Same messages and positions as evaluate() gives.
+function syntaxError(input, node) {
+  const parent = node.parent;
+
+  let message, position = { from: node.from, to: node.to };
+
+  if (node.from !== node.to) {
+    message = `Unrecognized token in <${parent.name}>`;
+  } else {
+    let next = null;
+
+    for (let current = node; current && !next; current = current.parent) {
+      next = current.nextSibling;
+    }
+
+    if (next) {
+      message = `Unrecognized token <${next.name}> in <${parent.name}>`;
+      position = { from: next.from, to: next.to };
+    } else {
+      message = `Incomplete <${(parent.enterUnfinishedNodesBefore(node.to) || parent).name}>`;
+    }
+  }
+
+  return new SyntaxError(message, { input: input.slice(position.from, position.to), position });
+}
+
+// The lezer tree as plain data, every node of it, tokens included: `type` is the grammar's name for the
+// node, `from` / `to` its span in the input (in UTF-16 code units, as JavaScript counts), `text` that span.
+function toAst(tree, input) {
+  const build = (node) => {
+    if (node.type.isError) {
+      throw syntaxError(input, node);
+    }
+
+    const children = [];
+
+    for (let child = node.firstChild; child; child = child.nextSibling) {
+      children.push(build(child));
+    }
+
+    return { type: node.name, from: node.from, to: node.to, text: input.slice(node.from, node.to), children };
+  };
+
+  return build(tree.topNode);
+}
+
+// A FEEL date, time or duration is a luxon object, and what luxon gives it in JSON is not FEEL's form (a
+// date becomes a date-time at midnight, a time gets a date of 1900-01-01 and the zone of the machine). So
+// it is replaced by FEEL's own string of it — what `string(value)` answers, ISO 8601. JSON.stringify hands
+// a replacer the value AFTER its toJSON, hence the look at the holder.
+function replacer(key, value) {
+  const raw = this[key];
+
+  if (raw && (raw.isLuxonDateTime || raw.isLuxonDuration)) {
+    return evaluate('string(v)', { v: raw }).value;
+  }
+
+  return value;
+}
+
+const toJson = (value) => JSON.stringify(value === undefined ? null : value, replacer);
+
+// Custom functions, by name. Each forwards to the global the Ruby side attached under that name; the
+// `(...args)` forwarder is deliberate: feelin reads a function's source to learn its parameters, so a bare
+// reference to the (native) attached global would be seen as taking no arguments.
+//
+// The arguments go to Ruby in the form a result does — through the same JSON, so a date, time or duration
+// among them, however deep, is its ISO 8601 string there too and not the fields of a luxon object.
+const functions = {};
+let hasFunctions = false;
+
+function readContext(contextJson) {
+  const context = (contextJson == null ? null : JSON.parse(contextJson)) || {};
+
+  return hasFunctions ? Object.assign(context, functions) : context;
+}
+
+// A syntax error leaves under a name of its own: across the V8 boundary an error is only its name and its
+// message, and feelin's SyntaxError keeps the name `Error`.
+function guarded(fn) {
+  return (...args) => {
+    try {
+      return fn(...args);
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        error.name = 'FeelSyntaxError';
+      }
+
+      throw error;
+    }
+  };
+}
+
+export const json = {
+  evaluate: guarded((expression, contextJson) => toJson(evaluate(expression, readContext(contextJson)).value)),
+  unaryTest: guarded((expression, contextJson) => toJson(unaryTest(expression, readContext(contextJson)).value)),
+  parseExpression: guarded((expression, contextJson) => JSON.stringify(toAst(parseExpression(expression, readContext(contextJson)), expression))),
+  parseUnaryTests: guarded((expression, contextJson) => JSON.stringify(toAst(parseUnaryTests(expression, readContext(contextJson)), expression))),
+  addFunction: (name) => {
+    functions[name] = function(...args) { return globalThis[name](...JSON.parse(toJson(args))); };
+    hasFunctions = true;
+  }
+};

data/lib/feelin/js/package-lock.json

@@ -5,7 +5,7 @@
   "packages": {
     "": {
       "dependencies": {
-        "feelin": "^7.0.1"
+        "feelin": "^7.0.2"
       },
       "devDependencies": {
         "esbuild": "^0.28.1"
@@ -520,9 +520,9 @@
       }
     },
     "node_modules/feelin": {
-      "version": "7.0.1",
-      "resolved": "https://registry.npmjs.org/feelin/-/feelin-7.0.1.tgz",
-      "integrity": "sha512-P7jSNHxMfDMW7zojApEUClEOugv/J7UZEVvSG4Cuyzwxh1QiB1XXgBREkEEamdy3igHHzm+20lv0Mt3pws3teA==",
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/feelin/-/feelin-7.0.2.tgz",
+      "integrity": "sha512-+3L+9P+bdDowtzlLSvTQPiv47dDXWVW0gaF4WBOFb3jNTTGremw+KOXpteO4r/a8Uw26uNvVTtPhWMQMbM6irg==",
       "license": "MIT",
       "dependencies": {
         "@lezer/common": "^1.5.2",
@@ -558,9 +558,9 @@
       }
     },
     "node_modules/min-dash": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/min-dash/-/min-dash-5.0.0.tgz",
-      "integrity": "sha512-EGuoBnVL7/Fnv2sqakpX5WGmZehZ3YMmLayT7sM8E9DRU74kkeyMg4Rik1lsOkR2GbFNeBca4/L+UfU6gF0Edw==",
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/min-dash/-/min-dash-5.1.0.tgz",
+      "integrity": "sha512-HAvN6XzmCQj+js43G9sJRRw8kj/7DvoxN7qhoIN9Xo5ZN1NMljtpyKs/NunXmw0QSWwlgZzNv6tLeEa4xaZ0tg==",
       "license": "MIT"
     }
   }

data/lib/feelin/js/package.json

@@ -4,7 +4,7 @@
     "build": "esbuild entry.js --bundle --format=iife --global-name=feel --platform=browser --outfile=dist/feelin.js"
   },
   "dependencies": {
-    "feelin": "^7.0.1"
+    "feelin": "^7.0.2"
   },
   "devDependencies": {
     "esbuild": "^0.28.1"

data/lib/feelin/version.rb

@@ -1,3 +1,3 @@
 module FEELIN
-  VERSION = "7.0.1"
+  VERSION = "7.0.3"
 end

data/lib/feelin.rb

@@ -4,61 +4,144 @@ require "json"
 module FEELIN
   # Pre-built single-file IIFE bundle (feelin + its dependencies), produced by
   # `npm run build` in lib/feelin/js. It exposes the feelin API on the global
-  # `feel`. feelin is distributed as an ES module, so it is bundled ahead of time
-  # rather than assembled at load time.
+  # `feel`, and under `feel.json` the functions this wrapper calls. feelin is
+  # distributed as an ES module, so it is bundled ahead of time rather than
+  # assembled at load time.
   BUNDLE_PATH = File.expand_path("feelin/js/dist/feelin.js", __dir__)
 
-  @@functions = Set.new
+  # What goes wrong inside V8 is raised as one of these, never as a MiniRacer
+  # error: the message names the expression, which is also kept in `expression`,
+  # and `reason` is what went wrong without it. An exception raised by a custom
+  # function is not one of them and passes as it is.
+  class Error < StandardError
+    attr_reader :expression, :reason
 
-  # NOTE: the context is serialized to JSON and interpolated into the eval, rather
-  # than passed as a native Ruby object via MiniRacer#call. That was measured to be
-  # ~15-20% FASTER: JSON.generate (C) plus V8's highly-optimized parsing beats
-  # mini_racer's element-by-element Ruby->V8 marshalling, and it lets custom
-  # functions be injected straight into the context (no per-call merge).
-  def self.evaluate(expression, context = nil)
-    context_json = serialize_context(context)
-
-    unwrap(@@context.eval("feel.evaluate(#{JSON.generate(expression)}, #{context_json})"))
+    def initialize(message, expression = nil, reason = message)
+      super(message)
+      @expression = expression
+      @reason = reason
+    end
   end
 
-  def self.unary_test(expression, value, context = {})
-    context_json = serialize_context({ **context, '?' => value })
+  # the expression does not parse
+  class SyntaxError < Error; end
 
-    unwrap(@@context.eval("feel.unaryTest(#{JSON.generate(expression)}, #{context_json})"))
-  end
+  # the evaluation ran past the context's `timeout`
+  class TimeoutError < Error; end
 
-  def self.add_function(name, proc)
-    @@functions.add(name)
-    @@context.attach(name, proc)
-  end
+  # the evaluation ran past the context's `max_memory`
+  class MemoryError < Error; end
+
+  # A V8 context with feelin loaded. The module-level methods below work on one
+  # shared context without limits; a context of one's own is for an expression
+  # that is not trusted to end or to stay small — `timeout` (ms) and `max_memory`
+  # (bytes) are its limits, and going over one raises TimeoutError or
+  # MemoryError — and for custom functions that the shared context should not
+  # see.
+  #
+  # Every context starts from one snapshot of the bundle, so creating one does
+  # not load and compile feelin again.
+  #
+  # The context goes into V8 as a JSON string and the result comes back as one
+  # (`feel.json.*` in js/entry.js). That keeps a call a function call with
+  # arguments: the data is never written into a script of its own, which V8 would
+  # compile and keep for every distinct context. And it is how a date, time or
+  # duration arrives as its ISO 8601 string, the form FEEL's `string()` gives
+  # it, instead of the internal fields of the object V8 holds.
+  class Context
+    class << self
+      def snapshot
+        @snapshot ||= MiniRacer::Snapshot.new(File.read(BUNDLE_PATH))
+      end
+    end
+
+    def initialize(timeout: nil, max_memory: nil)
+      @timeout = timeout
+      limits = { timeout: timeout, max_memory: max_memory }.compact
+      @context = MiniRacer::Context.new(snapshot: self.class.snapshot, **limits)
+    end
+
+    def evaluate(expression, context = nil)
+      call("evaluate", expression, context)
+    end
+
+    def unary_test(expression, value, context = {})
+      call("unaryTest", expression, { **context, '?' => value })
+    end
+
+    # The syntax tree of an expression, without evaluating it: nested hashes of
+    # `type` (the grammar's node name), `from` / `to` (the span in the expression,
+    # counted in UTF-16 code units), `text` (that span) and `children`. Tokens are
+    # nodes too. The context only supplies the names of the variables, which is
+    # what lets a name with spaces in it be read as one. An expression that does
+    # not parse raises SyntaxError, as it does in `evaluate`.
+    def parse_expression(expression, context = nil)
+      call("parseExpression", expression, context)
+    end
+
+    def parse_unary_tests(expression, context = nil)
+      call("parseUnaryTests", expression, context)
+    end
+
+    def add_function(name, proc)
+      @context.attach(name, proc)
+      @context.call("feel.json.addFunction", name)
+    end
+
+    def dispose
+      @context.dispose
+    end
 
-  private
+    private
 
-  # feelin (>= 7) returns an EvaluationResult `{ value, warnings }`; callers expect
-  # the bare value.
-  def self.unwrap(result)
-    result.is_a?(Hash) && result.key?("warnings") ? result["value"] : result
+    SYNTAX_ERROR = /\AFeelSyntaxError: /
+
+    def call(function, expression, context)
+      JSON.parse(@context.call("feel.json.#{function}", expression, context.nil? ? nil : JSON.generate(context)))
+    rescue MiniRacer::ScriptTerminatedError
+      raise failure(TimeoutError, expression, "took longer than #{@timeout} ms", "")
+    rescue MiniRacer::V8OutOfMemoryError
+      raise failure(MemoryError, expression, "ran out of memory", "")
+    rescue MiniRacer::Error => e
+      reason = e.message.lines.first.to_s.strip
+
+      raise failure(SyntaxError, expression, reason.sub(SYNTAX_ERROR, ''), " is not a FEEL expression:") if reason.match?(SYNTAX_ERROR)
+
+      raise failure(Error, expression, reason.sub(/\AError: /, ''), ":")
+    end
+
+    def failure(error, expression, reason, link)
+      error.new("#{expression.inspect}#{link} #{reason}", expression, reason)
+    end
   end
 
-  # Builds the JS evaluation context. When custom functions are registered they
-  # must be injected into every context as forwarders to their attached globals.
-  # Each function is emitted as a QUOTED key forwarding to globalThis[name] so
-  # that names containing spaces (e.g. "string join") are valid JS; an empty
-  # context is coerced to nil to avoid producing an invalid "{,...}" literal. The
-  # `(...args)` forwarder is deliberate: feelin reads a function's source to learn
-  # its parameters, so a bare reference to the (native) attached global would be
-  # seen as taking no arguments.
-  def self.serialize_context(context)
-    return JSON.generate(context) if @@functions.empty?
-
-    context = nil if context.respond_to?(:empty?) && context.empty?
-    functions_json = @@functions.map do |name|
-      %("#{name}":function(...args){return globalThis["#{name}"](...args)})
-    end.join(",")
-
-    context.nil? ? "{#{functions_json}}" : "#{JSON.generate(context)[0...-1]},#{functions_json}}"
+  class << self
+    def evaluate(expression, context = nil)
+      shared.evaluate(expression, context)
+    end
+
+    def unary_test(expression, value, context = {})
+      shared.unary_test(expression, value, context)
+    end
+
+    def parse_expression(expression, context = nil)
+      shared.parse_expression(expression, context)
+    end
+
+    def parse_unary_tests(expression, context = nil)
+      shared.parse_unary_tests(expression, context)
+    end
+
+    def add_function(name, proc)
+      shared.add_function(name, proc)
+    end
+
+    private
+
+    def shared
+      @shared
+    end
   end
 
-  @@context = MiniRacer::Context.new
-  @@context.eval(File.read(BUNDLE_PATH))
+  @shared = Context.new
 end

data/spec/feelin/feelin_spec.rb

@@ -36,6 +36,174 @@ RSpec.describe FEELIN do
     end
   end
 
+  describe "custom function arguments" do
+    it "passes a date, a time and a duration as their ISO 8601 strings" do
+      seen = nil
+      FEELIN.add_function('seen', proc { |*args| seen = args; nil })
+
+      FEELIN.evaluate('seen(date("2020-01-02"), time("10:00:00+03:00"), date and time("2020-01-02T03:04:05Z"), duration("P1DT2H"))')
+
+      expect(seen).to eq [ '2020-01-02', '10:00:00+03:00', '2020-01-02T03:04:05Z', 'P1DT2H' ]
+    end
+
+    it "does so inside a list and a context, and leaves the rest as it is" do
+      seen = nil
+      FEELIN.add_function('seen', proc { |*args| seen = args; nil })
+
+      FEELIN.evaluate('seen([ @"2020-01-02" ], { on: @"2020-01-03", n: 1.5 }, "text", null, true)')
+
+      expect(seen).to eq [ [ '2020-01-02' ], { 'on' => '2020-01-03', 'n' => 1.5 }, 'text', nil, true ]
+    end
+  end
+
+  describe "temporal results" do
+    it "answers a date, a time and a duration in their ISO 8601 form" do
+      expect(FEELIN.evaluate('date("2020-01-02")')).to eq '2020-01-02'
+      expect(FEELIN.evaluate('time("10:00:00+03:00")')).to eq '10:00:00+03:00'
+      expect(FEELIN.evaluate('date and time("2020-01-02T03:04:05Z")')).to eq '2020-01-02T03:04:05Z'
+      expect(FEELIN.evaluate('duration("P1DT2H")')).to eq 'P1DT2H'
+    end
+
+    it "does so inside a list and a context too" do
+      expect(FEELIN.evaluate('{ on: date(day) + duration("P1D"), all: [ @"2020-01-02" ] }', { 'day' => '2020-05-06' }))
+        .to eq('on' => '2020-05-07', 'all' => [ '2020-01-02' ])
+    end
+
+    it "answers null for what has no value" do
+      expect(FEELIN.evaluate('missing')).to be_nil
+      expect(FEELIN.evaluate('{ a: missing }')).to eq('a' => nil)
+    end
+  end
+
+  describe FEELIN::Context do
+    it "evaluates in a context of its own, with its own functions" do
+      context = FEELIN::Context.new
+      context.add_function('only here', proc { 7 })
+
+      expect(context.evaluate('only here() + n', { 'n' => 1 })).to eq 8
+      expect(FEELIN.evaluate('only here()')).to be_nil
+    ensure
+      context&.dispose
+    end
+
+    it "stops an expression that runs past its timeout" do
+      context = FEELIN::Context.new(timeout: 50)
+
+      expect { context.evaluate('count(for a in 1..3000, b in 1..3000 return a * b)') }
+        .to raise_error(FEELIN::TimeoutError, /took longer than 50 ms/)
+    ensure
+      context&.dispose
+    end
+
+    # the context reaches V8 as an argument, not as the text of a script: a script
+    # per distinct context is compiled and kept, and ran a limited context out of
+    # memory
+    it "evaluates over context after context without its memory growing" do
+      context = FEELIN::Context.new(max_memory: 8_000_000)
+
+      results = Array.new(10_000) { |index| context.evaluate('"L" + string(old.n)', { 'old' => { 'n' => index } }) }
+
+      expect(results.values_at(0, 9_999)).to eq %w[L0 L9999]
+    ensure
+      context&.dispose
+    end
+  end
+
+  describe "errors" do
+    it "raises a syntax error that names the expression" do
+      expect { FEELIN.evaluate('1 +') }.to raise_error(FEELIN::SyntaxError, '"1 +" is not a FEEL expression: Incomplete <ArithmeticExpression>') do |error|
+        expect(error.expression).to eq '1 +'
+        expect(error.reason).to eq 'Incomplete <ArithmeticExpression>'
+      end
+      expect { FEELIN.unary_test('[1..', 1) }.to raise_error(FEELIN::SyntaxError)
+    end
+
+    it "raises nothing of MiniRacer's" do
+      expect { FEELIN.evaluate('1 +') }.to raise_error(FEELIN::Error) { |error| expect(error).not_to be_a(MiniRacer::Error) }
+    end
+
+    it "raises a memory error past the context's limit" do
+      context = FEELIN::Context.new(max_memory: 4_000_000)
+
+      expect { context.evaluate('for a in 1..300000 return { n: a, s: string(a) }') }.to raise_error(FEELIN::MemoryError, /ran out of memory/)
+    ensure
+      context&.dispose
+    end
+
+    it "lets an exception of a custom function through as it is" do
+      FEELIN.add_function('fails', proc { raise ArgumentError, 'no' })
+
+      expect { FEELIN.evaluate('fails()') }.to raise_error(ArgumentError, 'no')
+    end
+  end
+
+  describe "#parse_expression" do
+    # the types of a tree, nested as the tree is, tokens left out
+    def shape(node)
+      children = node['children'].reject { |child| child['children'].empty? && child['type'] !~ /\A[A-Z]/ }
+      children.empty? ? node['type'] : { node['type'] => children.map { |child| shape(child) } }
+    end
+
+    it "answers the syntax tree without evaluating the expression" do
+      tree = FEELIN.parse_expression('a.b + 1 > 2')
+
+      expect(shape(tree)).to eq(
+        'Expression' => [ {
+          'Comparison' => [
+            { 'ArithmeticExpression' => [
+              { 'PathExpression' => [ { 'VariableName' => [ 'Identifier' ] }, { 'PathName' => [ 'Identifier' ] } ] },
+              'ArithOp',
+              'NumericLiteral'
+            ] },
+            'CompareOp',
+            'NumericLiteral'
+          ]
+        } ]
+      )
+    end
+
+    it "gives every node its span and its text" do
+      comparison = FEELIN.parse_expression('a.b + 1 > 2')['children'].first
+
+      expect(comparison.slice('type', 'from', 'to', 'text')).to eq('type' => 'Comparison', 'from' => 0, 'to' => 11, 'text' => 'a.b + 1 > 2')
+      expect(comparison['children'].map { |child| child['text'] }).to eq [ 'a.b + 1', '>', '2' ]
+    end
+
+    it "reads a name with spaces as one name when the context has it" do
+      tree = FEELIN.parse_expression("Mike's daughter.name + 1", { "Mike's daughter.name" => 'Lisa' })
+      name = tree['children'].first['children'].first
+
+      expect(name.slice('type', 'text')).to eq('type' => 'VariableName', 'text' => "Mike's daughter.name")
+    end
+
+    it "raises on an expression that does not parse" do
+      expect { FEELIN.parse_expression('1 +') }.to raise_error(FEELIN::SyntaxError, /Incomplete <ArithmeticExpression>/)
+      expect { FEELIN.parse_expression('1 + ) 2') }.to raise_error(FEELIN::SyntaxError, /Unrecognized token/)
+    end
+
+    it "reports a syntax error as evaluate reports it" do
+      [ '1 +', '{ a: 1', 'if x then', '1 + ) 2', '1 2', '[1, 2' ].each do |expression|
+        expected = begin
+          FEELIN.evaluate(expression)
+        rescue FEELIN::SyntaxError => e
+          e.message
+        end
+
+        expect { FEELIN.parse_expression(expression) }.to raise_error(FEELIN::SyntaxError, expected), expression
+      end
+    end
+  end
+
+  describe "#parse_unary_tests" do
+    it "answers the syntax tree of unary tests" do
+      tree = FEELIN.parse_unary_tests('[1..end], > 5')
+      tests = tree['children'].first['children'].select { |child| child['type'] == 'PositiveUnaryTest' }
+
+      expect(tree['type']).to eq 'UnaryTests'
+      expect(tests.map { |test| test['text'] }).to eq [ '[1..end]', '> 5' ]
+    end
+  end
+
   describe "#unary_test" do
     context "without context" do
       it "should not fail" do

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: feelin
 version: !ruby/object:Gem::Version
-  version: 7.0.1
+  version: 7.0.3
 platform: ruby
 authors:
 - Dmitry Arkhipov
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mini_racer
@@ -82,7 +81,6 @@ metadata:
   homepage_uri: https://github.com/ekzo-dev/ruby-feelin
   source_code_uri: https://github.com/ekzo-dev/ruby-feelin
   changelog_uri: https://github.com/ekzo-dev/ruby-feelin/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -97,8 +95,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: feelin Ruby wrapper
 test_files: []