feelin 7.0.2 → 7.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a2aab7f50ce55a02f7c45876a113972cf952c23ab505a2a95f527c213015591
-  data.tar.gz: 68ffbc5239c2f1387ea5982e6af9b7c9fc619a93ab43e42c2750a981cfb6813c
+  metadata.gz: 1d42d010d26029134be39b2bcdbd097683a00b0866820f1d816f69607b5bd053
+  data.tar.gz: cbee6c7dc98e5c2e078ebdecdbe3abac6dee702966841ffa3e5a3df399e69853
 SHA512:
-  metadata.gz: da2fea8b67b029c34710ee51f1c0e3f491eb974e2270a83eaed1ac6d88935148882e56bbde7a7709e4543ffada442181f3b02ed14d407b9c0671087d59e46f95
-  data.tar.gz: 3cf684bb66042782c7415b16d2cca27608ed45f2dc9eb2a83b6e25a4cfab1806cbd1c4c04148417651060164137491d654e67e21361ba79e4ca5ba47ff7d608c
+  metadata.gz: 247e1e7cce0bf1a66df682268273282000c3ef98ba755af7ac213f5b9c978cb30aa9f68bef46e4ab49ff0c2573cf25838ed11e0da51aca861d0b30ccd268f7cf
+  data.tar.gz: 5ff326f4111002f0f65fef3e84f31bf307d1fea982372c72805936ada9484e8b579a57fe853a3a88c1cf2f35b4b116271996327498853b8ef608969a3483050b

data/CHANGELOG.md

@@ -5,6 +5,14 @@ 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
@@ -18,10 +26,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * **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.
 
-### Not updated
-
-* `feelin` 8.2.0 was tried and held back: evaluating an expression that names a variable takes about twice as long there (8.2.0 looks every variable name up among the built-ins on each `evaluate`), and it produces enough garbage to run a context with `max_memory: 64_000_000` out of memory after ~10 000 evaluations.
-
 ## [7.0.1] - 2026-06-22
 
 ### Changed

data/README.md

@@ -43,11 +43,11 @@ FEELIN.unary_test('[1..end]', 1, { 'end' => 10 }) # true
 
 ### Syntax tree
 
-`parse` and `parse_unary_tests` answer the syntax tree of an expression without evaluating it — for
+`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('price > 10')
+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" => [
@@ -68,10 +68,10 @@ The optional second argument is a context, of which only the names matter: it is
 spaces in it be read as one name.
 
 ```ruby
-FEELIN.parse("Mike's daughter.name + 1", { "Mike's daughter.name" => nil })
+FEELIN.parse_expression("Mike's daughter.name + 1", { "Mike's daughter.name" => nil })
 ```
 
-An expression that does not parse raises `MiniRacer::RuntimeError`, with the same message `evaluate` gives.
+An expression that does not parse raises `FEELIN::SyntaxError`, with the same message `evaluate` gives.
 
 ### Custom functions
 
@@ -80,6 +80,18 @@ 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
@@ -91,14 +103,38 @@ context = FEELIN::Context.new(timeout: 1_000, max_memory: 64_000_000) # ms, byte
 
 context.add_function('rate', proc { 0.2 })
 context.evaluate('price * rate()', { 'price' => 100 }) # 20
-context.parse('price * rate()')
+context.parse_expression('price * rate()')
 
 context.dispose
 ```
 
-Past its timeout an evaluation raises `MiniRacer::ScriptTerminatedError`, past its memory
-`MiniRacer::V8OutOfMemoryError`. Contexts are created from one snapshot of the bundle, so a new one does
-not load feelin again.
+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
 

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

@@ -13687,14 +13687,26 @@ var feel = (() => {
     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: (expression, contextJson) => toJson(evaluate(expression, readContext(contextJson)).value),
-    unaryTest: (expression, contextJson) => toJson(unaryTest(expression, readContext(contextJson)).value),
-    parseExpression: (expression, contextJson) => JSON.stringify(toAst(parseExpression(expression, readContext(contextJson)), expression)),
-    parseUnaryTests: (expression, contextJson) => JSON.stringify(toAst(parseUnaryTests(expression, readContext(contextJson)), expression)),
+    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](...args);
+        return globalThis[name2](...JSON.parse(toJson(args)));
       };
       hasFunctions = true;
     }

data/lib/feelin/js/entry.js

@@ -72,6 +72,9 @@ const toJson = (value) => JSON.stringify(value === undefined ? null : value, rep
 // 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;
 
@@ -81,13 +84,29 @@ function readContext(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: (expression, contextJson) => toJson(evaluate(expression, readContext(contextJson)).value),
-  unaryTest: (expression, contextJson) => toJson(unaryTest(expression, readContext(contextJson)).value),
-  parseExpression: (expression, contextJson) => JSON.stringify(toAst(parseExpression(expression, readContext(contextJson)), expression)),
-  parseUnaryTests: (expression, contextJson) => JSON.stringify(toAst(parseUnaryTests(expression, readContext(contextJson)), expression)),
+  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](...args); };
+    functions[name] = function(...args) { return globalThis[name](...JSON.parse(toJson(args))); };
     hasFunctions = true;
   }
 };

data/lib/feelin/version.rb

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

data/lib/feelin.rb

@@ -9,12 +9,35 @@ module FEELIN
   # assembled at load time.
   BUNDLE_PATH = File.expand_path("feelin/js/dist/feelin.js", __dir__)
 
+  # 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
+
+    def initialize(message, expression = nil, reason = message)
+      super(message)
+      @expression = expression
+      @reason = reason
+    end
+  end
+
+  # the expression does not parse
+  class SyntaxError < Error; end
+
+  # the evaluation ran past the context's `timeout`
+  class TimeoutError < Error; 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 MiniRacer's limits, and going over one raises
-  # MiniRacer::ScriptTerminatedError or MiniRacer::V8OutOfMemoryError — and for
-  # custom functions that the shared context should not see.
+  # (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.
@@ -33,6 +56,7 @@ module FEELIN
     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
@@ -50,8 +74,8 @@ module FEELIN
     # 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, as it does in `evaluate`.
-    def parse(expression, context = nil)
+    # not parse raises SyntaxError, as it does in `evaluate`.
+    def parse_expression(expression, context = nil)
       call("parseExpression", expression, context)
     end
 
@@ -70,8 +94,24 @@ module FEELIN
 
     private
 
+    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
 
@@ -84,8 +124,8 @@ module FEELIN
       shared.unary_test(expression, value, context)
     end
 
-    def parse(expression, context = nil)
-      shared.parse(expression, context)
+    def parse_expression(expression, context = nil)
+      shared.parse_expression(expression, context)
     end
 
     def parse_unary_tests(expression, context = nil)

data/spec/feelin/feelin_spec.rb

@@ -36,6 +36,26 @@ 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'
@@ -70,7 +90,7 @@ RSpec.describe FEELIN 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(MiniRacer::ScriptTerminatedError)
+        .to raise_error(FEELIN::TimeoutError, /took longer than 50 ms/)
     ensure
       context&.dispose
     end
@@ -89,13 +109,35 @@ RSpec.describe FEELIN do
     end
   end
 
-  describe "syntax errors" do
-    it "raises on an expression that does not parse" do
-      expect { FEELIN.evaluate('1 +') }.to raise_error(MiniRacer::RuntimeError, /Incomplete <ArithmeticExpression>/)
+  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" do
+  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]/ }
@@ -103,7 +145,7 @@ RSpec.describe FEELIN do
     end
 
     it "answers the syntax tree without evaluating the expression" do
-      tree = FEELIN.parse('a.b + 1 > 2')
+      tree = FEELIN.parse_expression('a.b + 1 > 2')
 
       expect(shape(tree)).to eq(
         'Expression' => [ {
@@ -121,33 +163,33 @@ RSpec.describe FEELIN do
     end
 
     it "gives every node its span and its text" do
-      comparison = FEELIN.parse('a.b + 1 > 2')['children'].first
+      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("Mike's daughter.name + 1", { "Mike's daughter.name" => 'Lisa' })
+      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, as evaluate does" do
-      expect { FEELIN.parse('1 +') }.to raise_error(MiniRacer::RuntimeError, /Incomplete <ArithmeticExpression>/)
-      expect { FEELIN.parse('1 + ) 2') }.to raise_error(MiniRacer::RuntimeError, /Unrecognized token/)
+    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 MiniRacer::RuntimeError => e
+        rescue FEELIN::SyntaxError => e
           e.message
         end
 
-        expect { FEELIN.parse(expression) }.to raise_error(MiniRacer::RuntimeError, expected), expression
+        expect { FEELIN.parse_expression(expression) }.to raise_error(FEELIN::SyntaxError, expected), expression
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: feelin
 version: !ruby/object:Gem::Version
-  version: 7.0.2
+  version: 7.0.3
 platform: ruby
 authors:
 - Dmitry Arkhipov