feelin 4.3.1 → 7.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a4fbc790ded4b8ab96b849b340e47ca9caf6e823a81ed6d089ffefe8f2681f1
-  data.tar.gz: fdd926deebf949cdb3ff1c30bf9e6973127505172ec97a823326de72392c6783
+  metadata.gz: 3a2aab7f50ce55a02f7c45876a113972cf952c23ab505a2a95f527c213015591
+  data.tar.gz: 68ffbc5239c2f1387ea5982e6af9b7c9fc619a93ab43e42c2750a981cfb6813c
 SHA512:
-  metadata.gz: 6f52af2eff46b10aef4a0d0c241643bcd2ab76df7adefe78ebff16cd68b626573001b1da1e3458308a6d864eba4f6f55bce7823059483811a52c2654bbaf4150
-  data.tar.gz: af1942c3a6f320a189068a2d788a230b465c6c0ffffc7b5e1b83e38b928a7d2f9102980e20088de7c98c1ce4bfaac665df839a10f2ca4f7e0b80a9d9f433cd5b
+  metadata.gz: da2fea8b67b029c34710ee51f1c0e3f491eb974e2270a83eaed1ac6d88935148882e56bbde7a7709e4543ffada442181f3b02ed14d407b9c0671087d59e46f95
+  data.tar.gz: 3cf684bb66042782c7415b16d2cca27608ed45f2dc9eb2a83b6e25a4cfab1806cbd1c4c04148417651060164137491d654e67e21361ba79e4ca5ba47ff7d608c

data/.gitignore

@@ -3,4 +3,8 @@ log/*.log
 .byebug_history
 *.gem
 Gemfile.lock
-.idea
+.idea
+
+# JS dependencies — only needed to (re)build lib/feelin/js/dist/feelin.js,
+# which is committed. Run `npm install` in lib/feelin/js to restore.
+node_modules/

data/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.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.
+
+### 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
+
+* Updated the bundled `feelin` JavaScript library to 7.0.1.
+* Rebuilt the JavaScript bundle with [esbuild](https://esbuild.github.io/). `feelin` is now distributed as an ES module, so it is pre-bundled into a single IIFE file (`lib/feelin/js/dist/feelin.js`) instead of being assembled from CommonJS at load time.
+* `evaluate` / `unary_test` unwrap feelin 7's `EvaluationResult { value, warnings }` envelope, so callers keep receiving the bare value.
+
+### Fixed
+
+* `serialize_context` built invalid JavaScript (a leading comma, `{,…}`) for an empty context once a custom function was registered.
+* `serialize_context` built invalid JavaScript for custom function names containing spaces (e.g. `string join`); function names are now emitted as quoted keys forwarding to the attached global.
+
 ## [4.3.1] - 2025-03-26
 
 * Initial release

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` 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')
+# { "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("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.
+
 ### Custom functions
 
 ```ruby
@@ -38,6 +80,55 @@ FEELIN.add_function('rates', proc { [10, 20] })
 FEELIN.evaluate('every rate in rates() satisfies rate < 10') # false
 ```
 
+### 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('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.
+
+## 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`.
+
+### Updating the JavaScript dependencies
+
+```bash
+cd lib/feelin/js
+npm install                  # install the pinned versions
+npm install feelin@<version> # bump feelin to a specific version
+```
+
+### Building the bundle
+
+`feelin` is distributed as an ES module, so it is bundled ahead of time with [esbuild](https://esbuild.github.io/) into `lib/feelin/js/dist/feelin.js` — an IIFE that exposes the feelin API on the global `feel`. The entry point is `lib/feelin/js/entry.js`.
+
+```bash
+cd lib/feelin/js
+npm run build
+```
+
+Commit the regenerated `dist/feelin.js` together with the updated `package.json` / `package-lock.json`.
+
+### Running the tests
+
+```bash
+bundle exec rspec
+```
+
 ## Versioning policy
 
 Because this library is a wrapper - it is released with the same major/minor version numbers as the underlying feelin library

data/feelin.gemspec

@@ -12,10 +12,14 @@ Gem::Specification.new do |spec|
   spec.description = "This gem uses embed V8 JavaScript engine and feelin JavaScript library to parse and evaluate DMN FEEL expressions"
   spec.license     = "MIT"
 
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri']   = 'https://github.com/ekzo-dev/ruby-feelin/CHANGELOG.md'
+
   spec.files = `git ls-files -z`.split("\x0")
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "mini_racer",      "~> 0.18"
+  spec.add_dependency "mini_racer",      "~> 0.21"
 
   spec.add_development_dependency "rspec",   "3.12.0"
   spec.add_development_dependency "byebug", "11.1.3"