portable_expressions 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d220e43573965935526913968ea27b528aed8eda49f98411f532b9f8c6d134da
-  data.tar.gz: 87bacf2336c7bee890f8dedb7a14db1d79bd87d4678acc33be9a79cf93cd76e8
+  metadata.gz: e412dc48f673e5c346a0c5bba6017c8160b760765357acff869fccc576f60e74
+  data.tar.gz: fb11d81bf5e48513131bacaeb0be9ad71d380312410c13c4eb2aa67293897b32
 SHA512:
-  metadata.gz: 64009910d3f1eab111f64c7c211ed02b4e3a27c94108bcc7cf8f98b7f8548255a1215185a46b0a70c021e18d8b6301dfcccbe3af625764258fe7e0515a2c8783
-  data.tar.gz: eeda6228dbdd334fef7e3f87089e910073e3405d77f0bb426f7e6a56390a89bb0faff70ea2a38a4fe924087fe7f88adbc23e6d0dd1f7177a0ae918e2f5fc8b56
+  metadata.gz: 478d6b0c41f9081ec78c7b783b7c13bb914bdfa8a3e37d0fbcbba50c31c222145e4b278c2a648b0c3cde5adf7a99c46a5dfcbe3a157e43543e261015c71efb38
+  data.tar.gz: db7a331b82a72da08945accf6164a675104d549d5702311f1e120f9a841b70c7ee8b6d7c9d2bb20ffd11ae792d635f3674cf505d212739bd42083a8be1a92c85

data/CHANGELOG.md

@@ -1,4 +1,8 @@
 ## [Unreleased]
 
+## [0.1.1] - 2024-03-30
+- Tons of README updates
+- Rename the operand delegator from `Evaluator` -> `Operand`
+
 ## [0.1.0] - 2024-03-27
 - Initial release

data/README.md

@@ -1,29 +1,93 @@
 # PortableExpressions 🍱
 
+![Gem Version](https://img.shields.io/gem/v/portable_expressions) ![Gem Total Downloads](https://img.shields.io/gem/dt/portable_expressions)
+
 A simple and flexible pure Ruby library for building and evaluating expressions. Expressions can be serialized to and built from JSON strings for portability.
 
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
-  `bundle add portable_expressions`
+`bundle add portable_expressions`
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-  `gem install portable_expressions`
+`gem install portable_expressions`
+
+## Why would I need this?
+
+`PortableExpressions` can be a powerful tool when designing stateless components. It's useful when you want to transmit the actual _logic_ you want to run (i.e. an `Expression`) along with its inputs. By making your logic or procedure stateless, you can decouple services from one another in interesting and scalable ways.
+
+Consider a serverless function (e.g. [AWS Lambda](https://aws.amazon.com/lambda/)) that adds 2 inputs together and some application code that calls it:
+
+```ruby
+# Serverless function
+def add(input1, input2)
+  input1 + input2
+end
+
+# Application code
+serverless_function_call(:add, 1, 2) #=> 3
+```
+
+So far so good, but what if you want to multiply the inputs instead? Well, you could define another function:
+
+```ruby
+def multiply(input1, input2)
+  input1 * input2
+end
+```
+
+But what happens as complexity increases, e.g. you want to run more steps? You could continue to define specific functions, but it would be a lot simpler if there was a way to tell the function what steps to run, the same way you tell it what the inputs are. Let's rewrite our function using `PortableExpressions`:
+
+```ruby
+# Serverless function
+def run_expression(expression_json, environment_json)
+  expression = PortableExpressions.from_json(expression_json) # This is your logic, or steps.
+  environment = PortableExpressions.from_json(environment_json) # These are your inputs.
+  environment.evaluate(expression) # This is your output!
+end
+
+# Application code
+add_step = PortableExpressions::Expression.new(
+  :+,
+  PortableExpressions::Variable.new("input1"),
+  PortableExpressions::Variable.new("input2")
+)
+multiply_step = PortableExpressions::Expression.new(
+  :*,
+  add_step,
+  PortableExpressions::Variable.new("input3")
+)
+inputs = PortableExpressions::Environment.new(
+  "input1" => 1,
+  "input2" => 2,
+  "input3" => 3
+)
+
+serverless_function_call(:run_expression, multiply_step.to_json, inputs.to_json) #=> 9
+```
+
+This is an oversimplified example to illustrate the kind of code you can write when your logic or procedure is **stateless** and **serializable**. In your application, the inputs and procedure may come from different sources.
+
+We demonstrated arithmetic here, but the `operator` can be _any Ruby method_ that the `operands` respond to, which means your `Expressions` can do a lot more than just add or multiply numbers.
+
+See [example use cases](#example-use-cases) for more ideas.
 
 ## Usage
 
 > [!IMPORTANT]
-> When using the gem, all references to the models below must be prefixed with `PortableExpressions::`. This is omitted in the README for simplicity.
+> When using the gem, all references to the models below must be prefixed with `PortableExpressions::` when used in your project. This is omitted in the README for simplicity.
 
 ### Scalar
 
-A `Scalar` is the simplest object that can be evaluated. It holds a single `value`. When used in an `Expression`, this `value` must respond to the symbol (i.e. support the method) defined by the `Expression#operator`.
+A `Scalar` is the simplest object that can be evaluated. It holds a single `value`. When used in an `Expression`, this `value` must respond to the symbol (i.e. support the method) defined by the `Expression#operator`. The `value` must also be serializable to JSON; `Array` and `Hash` are allowed types as long as their elements are all serializable as well.
 
 ```ruby
 Scalar.new(1)
 Scalar.new("some string")
+Scalar.new([1.2, 3.4, 5.6])
+Scalar.new({ "foo" => "bar" })
 ```
 
 ### Variable
@@ -51,8 +115,6 @@ Evaluating an `Expression` does the following:
 
 In this way evaluation is "lazy"; it won't evaluate a `Variable` or `Expression` until the `operand` is about to be used.
 
-An `Expression` can store its result back into the `Environment` by defining an `output`.
-
 ```ruby
 # addition
 addition = Expression.new(:+, Scalar.new(1), Scalar.new(2))
@@ -60,18 +122,51 @@ addition = Expression.new(:+, Scalar.new(1), Scalar.new(2))
 # multiplication
 multiplication = Expression.new(:*, Variable.new("variable_a"), Scalar.new(2))
 
-# storing output
-storing_output = Expression.new(:+, Scalar.new(1), Scalar.new(2), output: "one_plus_two")
-
 environment = Environment.new(
   "variable_a" => 2
 )
 environment.evaluate(addition) #=> 3
 environment.evaluate(multiplication) #=> 4
+```
+
+#### Storing `output`
+
+An `Expression` can store its result back into the `Environment` by defining an `output`. Writing the result to the `Environment` is an `Expression`'s way of updating the state.
+
+```ruby
+environment = Environment.new
+storing_output = Expression.new(:+, Scalar.new(1), Scalar.new(2), output: "one_plus_two")
 environment.evaluate(storing_output) #=> 3
+environment.variables #=> { "one_plus_two" => 3 }
+```
 
-environment.variables
-#=> { "variable_a" => 2, "one_plus_two" => 3 }
+Storing output allows us to write composable `Expressions` that build on each other instead of having to nest them. This allows us to do things like parallelize expensive parts of our procedure. For example, consider a set of `Expressions` for solving the gravitational force formula:
+
+$$F_g = \frac{G \cdot m_1 \cdot m_2}{r^2}$$
+
+```ruby
+grav_constant = Scalar.new(BigDecimal(6.7 / 10**11))
+numerator = Expression.new(:*, grav_constant, Variable.new("mass1"), Variable.new("mass2"), output: "numerator")
+denominator = Expression.new(:**, Variable.new("distance"), 2, output: "denominator") # aka "r"
+
+grav_force = Expression.new(:/, Variable.new("numerator"), Variable.new("denominator"))
+```
+
+At this point, we can compute the numerator and denominator independently, in any order.
+
+```ruby
+environment = Environment.new(
+  "mass1" => 123.45,
+  "mass1" => 54.321,
+  "distance" => 67.89,
+)
+
+# In parallel...
+environment.evaluate(numerator)
+environment.evaluate(denominator)
+
+# When all components are finished
+environment.evaluate(grav_force)
 ```
 
 #### Special `operators`
@@ -132,6 +227,21 @@ environment.variables["variable_a"] = 2
 environment.evaluate(Variable.new("variable_a")) # => 2
 ```
 
+> [!CAUTION]
+> Ruby `symbols` are converted to `strings` when serialized to JSON, and remain `strings` when that JSON is parsed.
+
+```ruby
+environment = Environment.new(foo: "bar")
+
+variable_foo = Variable.new(:foo)
+environment.evaluate(variable_foo) #=> "bar"
+
+variable_foo = PortableExpressions.from_json(variable_foo.to_json)
+environment.evaluate(variable_foo) #=> MissingVariableError
+```
+
+In this example, the same error can be thrown if the `Environment` is serialized and parsed, even if the `Variable` remains unchanged. For this reason, it's recommended to use `strings` for all `Variable` names.
+
 ### Serialization (to JSON)
 
 All models including the `Environment` support serialization via:
@@ -165,7 +275,7 @@ variable_score_a = PortableExpressions.from_json(variable_json)
 environment.evaluate(variable_score_a) #=> 100
 ```
 
-### Beyond math
+### Example use cases
 
 The examples throughout the README show simple arithmetic to illustrate the mechanics of the library. However, `Scalars` and `Variables` can hold any type of value that's JSON serializable, which allows for more complex use cases such as:
 
@@ -178,7 +288,7 @@ a_greater_than_b = Expression.new(
   Variable.new("variable_a"),
   Variable.new("variable_b"),
 )
-conditional = Expression.new(
+condition = Expression.new(
   :and,
   a_greater_than_b,
   Variable.new("variable_c"),
@@ -187,7 +297,7 @@ Environment.new(
   "variable_a" => 2,
   "variable_b" => 1,
   "variable_c" => "truthy",
-).evaluate(conditional)
+).evaluate(condition)
 #=> true
 ```
 
@@ -237,7 +347,7 @@ user_owns_resource_and_has_permission = Expression.new(:and, user_owns_resource,
 File.write("user_owns_resource_and_has_permission.json", user_owns_resource_and_has_permission.to_json)
 ```
 
-Or we might define a policy the relies on the `output` of other policies. This means that the `Environment` must run the dependencies first in order for their `output` to be available in the `Environment#variables`.
+Or we might define a policy the relies on the `output` of other policies. The `Environment` must `evaluate` the dependencies first in order for their `output` to be available for the following `Expressions`.
 
 ```ruby
 user_owns_resource_and_has_permission = Expression.new(
@@ -253,7 +363,8 @@ File.write("user_owns_resource.json", user_owns_resource.to_json)
 File.write("user_owns_resource_and_has_permission.json", user_owns_resource_and_has_permission.to_json)
 ```
 
-These examples demonstrate portability via JSON files, but we can just as easily serve the policy directly to anyone who needs it via some HTTP controller:
+> [!TIP]
+> These examples demonstrate portability via JSON files, but we can just as easily serve the policy directly to anyone who needs it via some HTTP controller:
 
 ```ruby
 # E.g. Rails via an `ActionController`
@@ -267,10 +378,10 @@ Then, some consumer with access to the user's permissions and context around the
 
 ```ruby
 environment = Environment.new(
-  "user_permissions" => user.permissions #=> ["blog.read", "blog.write", "comment.read", "comment.write"]
-  "resource" => some_model.resource_name #=> "comment"
-  "action" => "read"
-  "resource_owner" => some_model.user_id
+  "user_permissions" => user.permissions, #=> ["blog.read", "blog.write", "comment.read", "comment.write"]
+  "resource" => some_model.resource_name, #=> "comment"
+  "action" => "read",
+  "resource_owner" => some_model.user_id,
   "user_id" => user.id
 )
 
@@ -281,12 +392,12 @@ user_owns_resource_and_has_permission = PortableExpressions.from_json(
 environment.evaluate(user_owns_resource_and_has_permission) #=> true
 
 # Individual policies
-user_has_permission = PortableExpressions.from_json(File.read("user_has_permission.json"))
-user_owns_resource = PortableExpressions.from_json(File.read("user_owns_resource.json"))
-user_owns_resource_and_has_permission = PortableExpressions.from_json(
-  File.read("user_owns_resource_and_has_permission.json")
-)
-environment.evaluate(user_has_permission, user_owns_resource, user_owns_resource_and_has_permission) #=> true
+user_owns_resource_and_has_permission = [
+  PortableExpressions.from_json(File.read("user_has_permission.json")),
+  PortableExpressions.from_json(File.read("user_owns_resource.json")),
+  PortableExpressions.from_json(File.read("user_owns_resource_and_has_permission.json"))
+]
+environment.evaluate(*user_owns_resource_and_has_permission) #=> true
 ```
 
 ## Development

data/lib/portable_expressions/environment.rb

@@ -20,9 +20,7 @@ module PortableExpressions
     end
 
     def as_json
-      super.merge(
-        variables: variables
-      )
+      super.merge(variables: variables)
     end
 
     private
@@ -37,7 +35,7 @@ module PortableExpressions
         end
       when Expression
         value = object.operands
-                      .map { |operand| Evaluator.new(evaluate(operand)) }
+                      .map { |operand| Operand.new(evaluate(operand)) }
                       .reduce(object.operator)
 
         variables[object.output] = value if object.output

data/lib/portable_expressions/modules/serializable.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module PortableExpressions
+  # Adds JSON serialization capabilities to each object.
   module Serializable
     def as_json
       {
@@ -9,11 +10,7 @@ module PortableExpressions
     end
 
     def to_json(pretty: false)
-      if pretty
-        JSON.pretty_generate(as_json)
-      else
-        JSON.generate(as_json)
-      end
+      pretty ? JSON.pretty_generate(as_json) : JSON.generate(as_json)
     end
   end
 end

data/lib/portable_expressions/{evaluator.rb → operand.rb}

@@ -3,7 +3,7 @@
 module PortableExpressions
   # Used to wrap `operands` when evaluating an `Expression`. This allows us to "extend" the functionality of an object
   # without polluting the app wide definition.
-  class Evaluator < SimpleDelegator
+  class Operand < SimpleDelegator
     def and(other)
       __getobj__ && other.__getobj__
     end

data/lib/portable_expressions/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PortableExpressions
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/portable_expressions.rb

@@ -6,12 +6,13 @@ require "json"
 
 require_relative "portable_expressions/version"
 require_relative "portable_expressions/modules/serializable"
-require_relative "portable_expressions/evaluator"
+require_relative "portable_expressions/operand"
 require_relative "portable_expressions/scalar"
 require_relative "portable_expressions/variable"
 require_relative "portable_expressions/expression"
 require_relative "portable_expressions/environment"
 
+# See the README for details.
 module PortableExpressions
   Error = Class.new(StandardError)
 
@@ -22,7 +23,7 @@ module PortableExpressions
 
   # @param json [String, Hash]
   # @return [Expression, Scalar, Variable, Environment]
-  def self.from_json(json)
+  def self.from_json(json) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength
     json = JSON.parse(json) if json.is_a?(String)
 
     case json["object"]
@@ -30,8 +31,7 @@ module PortableExpressions
       Environment.new(**json["variables"])
     when Expression.name
       operator = json["operator"].to_sym
-      operands_json = json["operands"]
-      operands = operands_json.map { |operand_json| from_json(operand_json) }
+      operands = json["operands"].map { |operand_json| from_json(operand_json) }
 
       Expression.new(operator, *operands)
     when Variable.name
@@ -39,7 +39,7 @@ module PortableExpressions
     when Scalar.name
       Scalar.new(json["value"])
     else
-      raise DeserializationError, "Object class #{json["object"]} does not support deserialization."
+      raise DeserializationError, "Object type #{json["object"]} not supported for deserialization."
     end
   rescue JSON::ParserError => e
     raise DeserializationError, "Unable to parse JSON: #{e.message}."

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portable_expressions
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Omkar Moghe
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-27 00:00:00.000000000 Z
+date: 2024-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -52,9 +52,9 @@ files:
 - Rakefile
 - lib/portable_expressions.rb
 - lib/portable_expressions/environment.rb
-- lib/portable_expressions/evaluator.rb
 - lib/portable_expressions/expression.rb
 - lib/portable_expressions/modules/serializable.rb
+- lib/portable_expressions/operand.rb
 - lib/portable_expressions/scalar.rb
 - lib/portable_expressions/variable.rb
 - lib/portable_expressions/version.rb