props_template 1.0.0.alpha.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47eaa94bedc38645ef945eb7308cdc257497b063b5a9df481d491ec3bb1ae3ca
-  data.tar.gz: 48da4764807eb7924b224e98175f81c822a67e6ead927904df452d620d39e6e0
+  metadata.gz: 6e8ec3d3579ed65bb2a927d2bf7abb10c9e5f4ee4d5a5147da09e8efb1e6a030
+  data.tar.gz: f21d46d7b34d47ee191b0ddcfe68ceb506d15d316a4ad00e433ca3752d82045a
 SHA512:
-  metadata.gz: 40c1e3bfc2c99a3b37834abec4e9b8463d4585203583f9f2f7ba710d775e714a7950bf1bf60f9d86b67c34de6742a5b5a0d249e0154fb50736288123e9ebb1e4
-  data.tar.gz: 70953db156e838cf72b220f9549c3a4abc6684d5bf0b0ad8a6305b15abf56cd1bd876635248fa2c8f1e43f21241475716d1dca49605fe65279951a8f2e59ed84
+  metadata.gz: db8bb1f529058a5dc7f2be56fe29720f638194e756a229da90deb85b3b885cd8de56dab5609219c73df23d1fe4de2cb80a2edc8803bce6a550ee8a4f16c36f70
+  data.tar.gz: dc997a26a9e941c8468e8b1cf755cb3c81e6b541ca7c56661f3ecaab8a701fed67712fd368e1cea50eb8b3dba76238ae169b3b8abb6e2e07485b5a8349ba5673

data/README.md

@@ -14,6 +14,49 @@ that other libraries perform by using Oj's `StringWriter` in `rails` mode.
 
 ![benchmarks](docs/benchmarks.png)
 
+It's really fast. 
+
+`props_template` is second only to `panko` while being feature packed. The
+`Props::Base` [class](./lib/props_template/base.rb) that be used standalone
+is the fastest among all JSON serializers. Results derived from [alba benchmarks](https://github.com/thoughtbot/alba/tree/main/benchmark).
+
+```
+    props_base_class:     1439.9 i/s
+               panko:     1287.6 i/s - 1.12x  slower
+      props_template:      998.8 i/s - 1.44x  slower
+       turbostreamer:      912.9 i/s - 1.58x  slower
+                alba:      871.0 i/s - 1.65x  slower
+         jserializer:      668.7 i/s - 2.15x  slower
+alba_with_transformation:      604.2 i/s - 2.38x  slower
+              barley:      452.2 i/s - 3.18x  slower
+        barley_cache:      441.4 i/s - 3.26x  slower
+            jbuilder:      432.6 i/s - 3.33x  slower
+     fast_serializer:      390.1 i/s - 3.69x  slower
+               rails:      374.1 i/s - 3.85x  slower
+                rabl:      310.3 i/s - 4.64x  slower
+         blueprinter:      268.4 i/s - 5.36x  slower
+       representable:      187.2 i/s - 7.69x  slower
+          simple_ams:      124.5 i/s - 11.57x  slower
+                 ams:       41.5 i/s - 34.67x  slower
+         alba_inline:       10.9 i/s - 131.64x  slower
+
+Gem versions:
+active_model_serializers: 0.10.16
+alba: 3.10.0
+barley: 0.9.0
+blueprinter: 1.2.1
+jbuilder: 2.14.1
+jserializer: 0.2.1
+panko_serializer: 0.8.4
+rabl: 0.17.0
+representable: 3.2.0
+simple_ams: 0.2.6
+turbostreamer: 1.11.0
+
+Ruby version: 3.4.8
+Apple M4 Pro
+```
+
 Caching is fast too.
 
 While other libraries spend time unmarshaling,
@@ -36,7 +79,7 @@ json.menu do
   end
 end
 
-json.dashboard(defer: :auto) do
+json.dashboard(with.defer(:auto)) do
   sleep 5
   json.complexPostMetric 500
 end
@@ -46,7 +89,7 @@ json.posts do
   paged_posts = @posts.page(page_num).per(20)
 
   json.list do
-    json.array! paged_posts, key: :id do |post|
+    json.array! paged_posts, with.id_key(:id) do |post|
       json.id post.id
       json.description post.description
       json.commentsCount post.comments.count
@@ -59,8 +102,7 @@ json.posts do
   json.total @posts.count
 end
 
-json.footer partial: 'shared/footer' do
-end
+json.footer with.partial('shared/footer')
 ```
 
 ## Installation
@@ -96,12 +138,18 @@ You can also add a [layout](#layouts).
 Defines the attribute or structure. All keys are not formatted by default. See [Change Key Format](#change-key-format) to change this behavior.
 
 ```ruby
-json.set! :authorDetails, {...options} do
+json.set! :authorDetails, with.some_option do
   json.set! :firstName, 'David'
 end
 
 # or
 
+json.authorDetails, with.some_option do
+  json.firstName 'David'
+end
+
+# or with hash options
+
 json.authorDetails, {...options} do
   json.firstName 'David'
 end
@@ -115,7 +163,7 @@ The inline form defines key and value
 | Parameter | Notes |
 | :--- | :--- |
 | key | A json object key|
-| value | A value |
+| value | A value or an [options][#options] object enabled with [partial](#partials)|
 
 ```ruby
 
@@ -126,6 +174,10 @@ json.set! :firstName, 'David'
 json.firstName 'David'
 
 # => { "firstName": "David" }
+
+# or
+
+json.postDetails with.partial("blog_post")
 ```
 
 The block form defines key and structure
@@ -133,7 +185,7 @@ The block form defines key and structure
 | Parameter | Notes |
 | :--- | :--- |
 | key | A json object key|
-| options | Additional [options](#options)|
+| options | Additional hash [options](#options) or a [options](#options) object|
 | block | Additional `json.set!`s or `json.array!`s|
 
 ```ruby
@@ -149,11 +201,12 @@ end
 ```
 
 The difference between the block form and inline form is
-  1. The block form is an internal node. Functionality such as Partials,
-  Deferment and other [options](#options) are only available on the
-  block form.
-  2. The inline form is considered a leaf node, and you can only [dig](#digging)
-  for internal nodes.
+
+1. Passing options as a [hash](#hash-options) is only available for the
+block form (also called an internal node)
+2. The inline form is considered a leaf node, if you need features like
+partials you may use [options](#options) objects only.
+3. Only internal nodes may dug for [digging](#digging)
 
 ### json.extract!
 Extracts attributes from object or hash in 1 line
@@ -189,7 +242,7 @@ Generates an array of json objects.
 collection = [ {name: 'john'}, {name: 'jim'} ]
 
 json.details do
-  json.array! collection, {...options} do |person|
+  json.array! collection, with.some_option do |person|
     json.firstName person[:name]
   end
 end
@@ -306,11 +359,29 @@ option.
 `application.json.props` when first running `rails superglue:install:web`
 
 ## Options
-Options Functionality such as Partials, Deferments, and Caching can only be
-set on a block. It is normal to see empty blocks.
+
+PropsTemplate provides a `with` helper to build a `Props::Option` object that enable
+functionality such as Partials, Deferments, and Caching
+
+The following are equivalent:
+
+```ruby
+json.post(with.partial('blog_post') 
+```
+
+or 
+
+```ruby
+json.post(Props::Options.new.partial('blog_post') 
+```
+### Hash options
+
+Previously, a normal hash was supported for internal nodes as long as an empty
+block accompanied the option. This option is still supported, but its
+recommended to use the `with` option builder.
 
 ```ruby
-json.post(partial: 'blog_post') do
+json.post(partial: 'blog_post', locals: {post: @post}) do
 end
 ```
 
@@ -321,6 +392,10 @@ Partials are supported. The following will render the file
 with @post, which you can use inside the partial.
 
 ```ruby
+json.one_post(with.partial("posts/blog_post", locals: {post: @post}))
+
+# or with hash options
+
 json.one_post partial: ["posts/blog_post", locals: {post: @post}] do
 end
 ```
@@ -332,8 +407,7 @@ Usage with arrays:
 # Without `as:` option you can use blog_post variable (name is based on partial's name) inside partial
 
 json.posts do
-  json.array! @posts, partial: ["posts/blog_post", locals: {foo: 'bar'}, as: 'post'] do
-  end
+  json.array! @posts, with.partial("posts/blog_post", locals: {foo: 'bar'}, as: 'post')
 end
 ```
 
@@ -344,16 +418,14 @@ cause performance problems. It's best used for things like a shared header or fo
 Do:
 
 ```ruby
-json.partial! partial: "header", locals: {user: @user} do
-end
+json.partial! with.partial("header", locals: {user: @user}) 
 ```
 
 or
 
 ```ruby
 json.posts do
-  json.array! @posts, partial: ["posts/blog_post", locals: {post: @post}] do
-  end
+  json.array! @posts, with.partial("posts/blog_post", locals: {post: @post})
 end
 ```
 
@@ -374,8 +446,7 @@ update cross cutting concerns like a header bar.
 
 ```ruby
 # index.json.props
-json.header partial: ["profile", fragment: "header"] do
-end
+json.header with.partial("profile").fragment("header")
 
 # _profile.json.props
 json.profile do
@@ -390,8 +461,7 @@ When using fragments with Arrays, the argument **MUST** be a lamda:
 ```ruby
 require 'props_template/core_ext'
 
-json.array! ['foo', 'bar'], partial: ["footer", fragment: ->(x){ x == 'foo'}] do
-end
+json.array! ['foo', 'bar'], with.partial("footer").fragment(->(x){ x == 'foo'})
 ```
 
 ### Caching
@@ -402,19 +472,18 @@ use [push_json](http://www.ohler.com/oj/doc/Oj/StringWriter.html#push_json-insta
 Usage:
 
 ```ruby
-json.author(cache: "some_cache_key") do
+json.author(with.cache("some_cache_key")) do
   json.firstName "tommy"
 end
 
 # or
 
-json.profile(cache: "cachekey", partial: ["profile", locals: {foo: 1}]) do
-end
+json.profile(with.cache("cachekey").partial("profile", locals: {foo: 1}))
 
 # or nest it
 
-json.author(cache: "some_cache_key") do
-  json.address(cache: "some_other_cache_key") do
+json.author(with.cache("some_cache_key")) do
+  json.address(with.cache("some_other_cache_key")) do
     json.zip 11214
   end
 end
@@ -425,7 +494,7 @@ When used with arrays, PropsTemplate will use `Rails.cache.read_multi`.
 ```ruby
 require 'props_template/core_ext'
 
-opts = { cache: ->(i){ ['a', i] } }
+opts = with.cache(->(i){ ['a', i] } )
 
 json.array! [4,5], opts do |x|
   json.top "hello" + x.to_s
@@ -433,7 +502,7 @@ end
 
 # or on arrays with partials
 
-opts = { cache: (->(d){ ['a', d.id] }), partial: ["blog_post", as: :blog_post] }
+opts = with.cache(->(d){ ['a', d.id] }).partial("blog_post", as: :blog_post)
 
 json.array! @options, opts do
 end
@@ -457,7 +526,7 @@ store.
 Usage:
 
 ```ruby
-json.dashboard(defer: :manual) do
+json.dashboard(with.defer(:manual)) do
   sleep 10
   json.someFancyMetric 42
 end
@@ -465,7 +534,7 @@ end
 
 # or you can explicitly pass a placeholder
 
-json.dashboard(defer: [:manual, placeholder: {}]) do
+json.dashboard(with.defer(:manual, placeholder: {})) do
   sleep 10
   json.someFancyMetric 42
 end
@@ -476,7 +545,7 @@ A auto option is available:
 **Note** This is a [SuperglueJS][1] specific functionality.
 
 ```ruby
-json.dashboard(defer: :auto) do
+json.dashboard(with.defer(:auto)) do
   sleep 10
   json.someFancyMetric 42
 end
@@ -514,11 +583,11 @@ data = [
 ]
 
 json.posts
-  json.array! data, key: :some_id do |item|
+  json.array! data, with.id_key(:some_id) do |item|
     # By using :key, props_template will append `json.some_id item.some_id`
     # automatically
 
-    json.contact(defer: :auto) do
+    json.contact(with.defer(:auto)) do
       json.address '123 example drive'
     end
   end
@@ -623,7 +692,10 @@ A single layout is supported. To use, create an `application.json.props` in
 ```ruby
 json.data do
   # template runs here.
-  yield json
+  _.call(json)
+  # NOTE: you can also use `yield json` instead, but prism sees this as
+  # a syntax error, so the `_.call(json)` is a workaround.
+  # See: https://github.com/thoughtbot/props_template/issues/58
 end
 
 json.header do

data/lib/props_template/base.rb

@@ -9,13 +9,17 @@ module Props
   class InvalidScopeForChildError < StandardError; end
 
   class Base
+    attr_accessor :item_context
+
     def initialize(encoder = nil)
       @stream = Oj::StringWriter.new(mode: :rails)
       @scope = nil
+      @item_context = nil
     end
 
-    def set_block_content!(options = {})
+    def set_content!(options = {})
       @scope = nil
+      @item_context = nil
       yield
       if @scope.nil?
         @stream.push_object
@@ -26,7 +30,7 @@ module Props
     def handle_set_block(key, options)
       key = format_key(key)
       @stream.push_key(key)
-      set_block_content!(options) do
+      set_content!(options) do
         yield
       end
     end
@@ -59,30 +63,17 @@ module Props
       nil
     end
 
-    def refine_item_options(item, options)
-      options
-    end
-
     def handle_collection_item(collection, item, index, options)
-      set_block_content!(options) do
+      @item_context = item
+
+      set_content!(options) do
         yield
       end
     end
 
-    def refine_all_item_options(all_options)
-      all_options
-    end
-
     def handle_collection(collection, options)
-      all_opts = collection.map do |item|
-        refine_item_options(item, options.clone)
-      end
-
-      all_opts = refine_all_item_options(all_opts)
-
       collection.each_with_index do |item, index|
-        pass_opts = all_opts[index]
-        handle_collection_item(collection, item, index, pass_opts) do
+        handle_collection_item(collection, item, index, options) do
           # todo: remove index?
           yield item, index
         end
@@ -97,13 +88,20 @@ module Props
         raise InvalidScopeForArrayError.new("array! expects exclusive use of this block")
       end
 
-      if collection.nil?
-        @child_index = nil
-        yield
-      else
-        handle_collection(collection, options) do |item, index|
-          yield item, index
+      if block_given?
+        if collection.nil?
+          @child_index = nil
+          yield
+        else
+          handle_collection(collection, options) do |item, index|
+            yield item, index
+          end
         end
+      elsif options.is_a?(Props::Options)
+        options.valid_for_set!
+        handle_collection(collection, options) {}
+      else
+        raise ArgumentError.new("array! requires a block when no Props::Options object is given")
       end
 
       @scope = :array
@@ -147,7 +145,7 @@ module Props
       child_index += 1
 
       # this changes the scope to nil so child in a child will break
-      set_block_content!(options) do
+      set_content!(options) do
         yield
       end
 

data/lib/props_template/base_with_extensions.rb

@@ -26,10 +26,10 @@ module Props
       @traveled_path.join(".")
     end
 
-    def set_block_content!(options = {})
+    def set_content!(options = {})
       return super if !@em.has_extensions(options)
 
-      @em.handle(options) do
+      @em.handle(options, item_context) do
         yield
       end
     end
@@ -51,11 +51,12 @@ module Props
     end
 
     def set!(key, options = {}, &block)
-      if block
-        options = @em.refine_options(options)
+      if !block && options.is_a?(Props::Options)
+        options.valid_for_set!
+        super {}
+      else
+        super
       end
-
-      super
     end
 
     def handle_set_block(key, options)
@@ -73,16 +74,37 @@ module Props
       nil
     end
 
+    def handle_collection(collection, options)
+      if options[:cache]
+        key, rest = [*options[:cache]]
+
+        if ::Proc === key
+          cache_keys = collection.map do |item|
+            key.call(item)
+          end
+          @em.load_cache(cache_keys, rest || {})
+        end
+      end
+
+      super
+    end
+
     def handle_collection_item(collection, item, index, options)
       if !options[:key]
         @traveled_path.push(index)
       else
-        id, val = options[:key]
+        if (key = options[:key])
+          val = if item.respond_to? key
+            item.send(key)
+          elsif item.is_a? Hash
+            item[key] || item[key.to_sym]
+          end
+        end
 
-        if id.nil?
+        if key.nil?
           @traveled_path.push(index)
         else
-          @traveled_path.push("#{id}=#{val}")
+          @traveled_path.push("#{key}=#{val}")
         end
       end
 
@@ -91,25 +113,5 @@ module Props
       @traveled_path.pop
       nil
     end
-
-    def refine_all_item_options(all_options)
-      @em.refine_all_item_options(all_options)
-    end
-
-    def refine_item_options(item, options)
-      return options if options.empty?
-
-      if (key = options[:key])
-        val = if item.respond_to? key
-          item.send(key)
-        elsif item.is_a? Hash
-          item[key] || item[key.to_sym]
-        end
-
-        options[:key] = [options[:key], val]
-      end
-
-      @em.refine_options(options, item)
-    end
   end
 end

data/lib/props_template/extension_manager.rb

@@ -1,6 +1,9 @@
 module Props
   class ExtensionManager
-    attr_reader :base, :builder, :context
+    attr_reader :base, :builder, :context, :cache, :partialer
+
+    delegate :load_cache, to: :cache
+    delegate :find_and_add_template, to: :partialer
 
     def initialize(base, defered = [], fragments = [])
       @base = base
@@ -16,22 +19,6 @@ module Props
       @deferment.disable!
     end
 
-    def refine_options(options, item = nil)
-      options = @partialer.refine_options(options, item)
-      if !@deferment.disabled
-        options = @deferment.refine_options(options, item)
-      end
-
-      Cache.refine_options(options, item)
-    end
-
-    def refine_all_item_options(all_options)
-      return all_options if all_options.empty?
-
-      all_options = @partialer.find_and_add_template(all_options)
-      @cache.multi_fetch_and_add_results(all_options)
-    end
-
     def deferred
       @deferment.deferred
     end
@@ -44,26 +31,35 @@ module Props
       options[:defer] || options[:cache] || options[:partial] || options[:key]
     end
 
-    def handle(options)
+    def handle(options, item_context = nil)
       return yield if !has_extensions(options)
 
-      if options[:defer] && !@deferment.disabled
-        placeholder = @deferment.handle(options)
+      if (key = options[:key]) && item_context
+        val = if item_context.respond_to? key
+          item_context.send(key)
+        elsif item_context.is_a? Hash
+          item_context[key] || item_context[key.to_sym]
+        end
+      end
+
+      deferment_type = @deferment.extract_deferment_type(options, item_context) if !@deferment.disabled
+
+      if deferment_type
+        placeholder = @deferment.handle(options, deferment_type, key, val)
         base.stream.push_value(placeholder)
-        @fragment.handle(options)
+        @fragment.handle(options, item_context)
       else
-        handle_cache(options) do
-          base.set_block_content! do
+        handle_cache(options, item_context) do
+          base.set_content! do
             if options[:partial]
-              @fragment.handle(options)
-              @partialer.handle(options)
+              @fragment.handle(options, item_context)
+              @partialer.handle(options, item_context)
             else
               yield
             end
 
-            if options[:key]
-              id, val = options[:key]
-              base.set!(id, val)
+            if key && val
+              base.set!(key, val)
             end
           end
         end
@@ -72,11 +68,13 @@ module Props
 
     private
 
-    def handle_cache(options)
+    def handle_cache(options, item)
       if options[:cache]
         recently_cached = false
 
-        state = @cache.cache(*options[:cache]) do
+        key, rest = Cache
+          .normalize_options(options[:cache], item)
+        state = @cache.cache(key, rest) do
           recently_cached = true
           result = nil
           start = base.stream.to_s.length
@@ -93,7 +91,7 @@ module Props
           result
         end
 
-        meta, raw_json = state.split("\n")
+        meta, raw_json = state.split("\n", 2)
         next_deferred, next_fragments = Oj.load(meta)
         deferred.push(*next_deferred)
         fragments.push(*next_fragments)

data/lib/props_template/extensions/cache.rb

@@ -2,23 +2,22 @@ module Props
   class Cache
     delegate :controller, :safe_concat, to: :@context
 
-    def self.refine_options(options, item = nil)
-      return options if !options[:cache]
+    attr_reader :results
 
-      pass_opts = options.clone
-      key, rest = [*options[:cache]]
+    def initialize(context)
+      @context = context
+      @results = {}
+    end
+
+    def self.normalize_options(options, item = nil)
+      key, rest = [*options]
       rest ||= {}
 
       if item && ::Proc === key
         key = key.call(item)
       end
 
-      pass_opts[:cache] = [key, rest]
-      pass_opts
-    end
-
-    def initialize(context)
-      @context = context
+      [key, rest]
     end
 
     attr_reader :context
@@ -48,36 +47,21 @@ module Props
 
       keys.each do |k|
         ckey = key_to_ckey[k]
-        result[k] = read_caches[ckey]
+
+        if read_caches[ckey]
+          result[k] = read_caches[ckey]
+        end
       end
 
       result
     end
 
-    def multi_fetch_and_add_results(all_options)
-      first_opts = all_options[0]
-
-      if first_opts[:cache] && controller.perform_caching
-        keys = all_options.map { |i| i[:cache][0] }
-        c_opts = first_opts[:cache][1]
-        result = multi_fetch(keys, c_opts)
-
-        all_options.map do |opts|
-          key = opts[:cache][0]
-
-          if result.key? key
-            opts[:cache][1][:result] = result[key]
-          end
-
-          opts
-        end
-      else
-        all_options
-      end
+    def load_cache(keys, options = {})
+      @results = results.merge multi_fetch(keys, options)
     end
 
-    # Copied from jbuilder
-    #
+    # The below was copied from the wonderful jbuilder library Its also MIT
+    # licensed, so no issues there.  Thanks to the jbuilder authors!
 
     def cache(key = nil, options = {})
       if controller.perform_caching
@@ -90,10 +74,9 @@ module Props
     end
 
     def cache_fragment_for(key, options, &block)
-      key = cache_key(key, options)
-
-      return options[:result] if options[:result]
+      return results[key] if results[key]
 
+      key = cache_key(key, options)
       read_fragment_cache(key, options) || write_fragment_cache(key, options, &block)
     end
 

data/lib/props_template/extensions/deferment.rb

@@ -13,37 +13,27 @@ module Props
     end
 
     def refine_options(options, item = nil)
-      return options if !options[:defer]
-      pass_opts = options.clone
-
-      type, rest = [*options[:defer]]
-      rest ||= {
-        placeholder: {}
-      }
-
-      if item
-        type = (Proc === type) ? type.call(item) : type
-      end
-
-      if type
-        pass_opts[:defer] = [type, rest]
-      else
-        pass_opts.delete(:defer)
-      end
+      options.clone
+    end
 
-      pass_opts
+    def extract_deferment_type(options, item)
+      type, _ = [*options[:defer]]
+      (Proc === type) ? type.call(item) : type
     end
 
-    def handle(options)
+    def handle(options, type, key, val)
       return if !options[:defer]
 
-      type, rest = options[:defer]
+      _, rest = [*options[:defer]]
+      rest ||= {
+        placeholder: {}
+      }
+
       placeholder = rest[:placeholder]
       success_action = rest[:success_action]
       fail_action = rest[:fail_action]
 
-      if type.to_sym == :auto && options[:key]
-        key, val = options[:key]
+      if type.to_sym == :auto && key && val
         placeholder = {}
         placeholder[key] = val
       end

data/lib/props_template/extensions/fragment.rb

@@ -7,7 +7,7 @@ module Props
       @fragments = fragments
     end
 
-    def self.fragment_name_from_options(options)
+    def self.fragment_name_from_options(options, item = nil)
       return if !options[:partial]
 
       _, partial_opts = [*options[:partial]]
@@ -15,13 +15,17 @@ module Props
 
       fragment = partial_opts[:fragment]
 
+      if item && ::Proc === fragment
+        fragment = fragment.call(item)
+      end
+
       if String === fragment || Symbol === fragment
         fragment.to_s
       end
     end
 
-    def handle(options)
-      fragment_name = self.class.fragment_name_from_options(options)
+    def handle(options, item_context = nil)
+      fragment_name = self.class.fragment_name_from_options(options, item_context)
       path = @base.traveled_path
         .map { |item| item.is_a?(Array) ? item[0] : item }
         .join(".")

data/lib/props_template/extensions/partial_renderer.rb

@@ -45,22 +45,6 @@ module Props
       end
     end
 
-    def find_and_add_template(all_options)
-      first_opts = all_options[0]
-
-      if first_opts[:partial]
-        partial_opts = block_opts_to_render_opts(@builder, first_opts)
-        template = find_template(partial_opts)
-
-        all_options.map do |opts|
-          opts[:_template] = template
-          opts
-        end
-      else
-        all_options
-      end
-    end
-
     def find_template(partial_opts)
       partial = partial_opts[:partial]
       template_keys = retrieve_template_keys(partial_opts)
@@ -78,7 +62,7 @@ module Props
 
     def block_opts_to_render_opts(builder, options)
       partial, pass_opts = [*options[:partial]]
-      pass_opts ||= {}
+      pass_opts = pass_opts&.clone || {}
       pass_opts[:locals] ||= {}
       pass_opts[:partial] = partial
       pass_opts[:formats] = [:json]
@@ -91,9 +75,17 @@ module Props
       pass_opts
     end
 
-    def handle(options)
-      partial_opts = block_opts_to_render_opts(@builder, options)
-      template = options[:_template] || find_template(partial_opts)
+    def handle(options, item = nil)
+      return options if !options[:partial]
+
+      normalized_options = normalize_options(options, item)
+      partial_opts = block_opts_to_render_opts(@builder, normalized_options)
+      template = if options[:_template]
+        options[:_template]
+      else
+        # mutate the original options to bypass find_template a second time.
+        options[:_template] = find_template(partial_opts)
+      end
 
       render_partial(template, @context, partial_opts)
     end
@@ -133,8 +125,10 @@ module Props
     end
 
     def refine_options(options, item = nil)
-      return options if !options[:partial]
+      options.clone
+    end
 
+    def normalize_options(options, item = nil)
       partial, rest = [*options[:partial]]
       rest = (rest || {}).clone
       locals = (rest[:locals] || {}).clone
@@ -150,21 +144,9 @@ module Props
         raise_invalid_option_as(as) unless /\A[a-z_]\w*\z/.match?(as.to_s)
 
         locals[as] = item
-
-        if (fragment_name = rest[:fragment])
-          if item && ::Proc === fragment_name
-            fragment_name = fragment_name.call(item)
-          end
-
-          rest[:fragment] = fragment_name.to_s
-        end
       end
 
-      pass_opts = options.clone
-      pass_opts[:partial] = [partial, rest]
-
-      pass_opts
+      {partial: [partial, rest]}
     end
   end
 end
-

data/lib/props_template/helper.rb

@@ -0,0 +1,7 @@
+module Props
+  module Helper
+    def with
+      Props::Options.new
+    end
+  end
+end

data/lib/props_template/options.rb

@@ -0,0 +1,39 @@
+module Props
+  class Options < Hash
+    class InvalidOptionError < StandardError; end
+
+    def partial(partial_name, opts = {})
+      self[:partial] = [partial_name, opts]
+      self
+    end
+
+    def defer(type, placeholder: {}, **opts)
+      self[:defer] = [type, {placeholder: placeholder}.merge(opts)]
+      self
+    end
+
+    def fragment(fragment)
+      raise "Fragment can't be defined without a partial. Please use `partial` first" if !self[:partial]
+
+      self[:partial][1][:fragment] = fragment
+      self
+    end
+
+    def cache(id_or_block)
+      return unless id_or_block
+
+      self[:cache] = id_or_block
+      self
+    end
+
+    def id_key(key_name)
+      self[:key] = key_name
+      self
+    end
+
+    def valid_for_set!
+      raise InvalidOptionError.new("Props::Options can't be empty") if empty?
+      raise InvalidOptionError.new("The partial option must be used with an inline `set!`") if !key?(:partial)
+    end
+  end
+end

data/lib/props_template/railtie.rb

@@ -6,6 +6,7 @@ module Props
     initializer :props_template do
       ActiveSupport.on_load :action_view do
         ActionView::Template.register_template_handler :props, Props::Handler
+        ActionView::Base.include Props::Helper
         require "props_template/dependency_tracker"
         require "props_template/layout_patch"
         require "props_template/partial_patch"

data/lib/props_template/searcher.rb

@@ -12,6 +12,7 @@ module Props
       @traveled_path = []
       @partialer = Partialer.new(self, context, builder)
       @fragment_name = nil
+      @found_item = nil
     end
 
     def deferred!
@@ -30,7 +31,7 @@ module Props
         pass_opts[:path_suffix] = traveled_path
       end
 
-      fragment_name = Fragment.fragment_name_from_options(pass_opts)
+      fragment_name = Fragment.fragment_name_from_options(pass_opts, @found_item)
       if fragment_name
         @fragment_name = fragment_name
         @fragment_path = @traveled_path.clone
@@ -38,15 +39,15 @@ module Props
 
       fragment_context = @fragment_name
 
-      [@found_block, @traveled_path, pass_opts, @fragment_path, fragment_context]
+      [@found_block, @traveled_path, pass_opts, @fragment_path, fragment_context, @found_item]
     end
 
-    def set_block_content!(*args)
+    def set_content!(*args)
       yield
     end
 
     def set!(key, options = {}, &block)
-      return if @found_block || !block
+      return if @found_block || !block && !options.is_a?(Props::Options)
 
       if @search_path[@depth] == key.to_s
         @traveled_path.push(key)
@@ -97,21 +98,11 @@ module Props
 
         if item
           pass_opts = @partialer.refine_options(options, item)
-
-          if (key = pass_opts[:key])
-            val = if item.respond_to? key
-              item.send(key)
-            elsif item.is_a? Hash
-              item[key] || item[key.to_sym]
-            end
-
-            pass_opts[:key] = [pass_opts[:key], val]
-          end
-
           @traveled_path.push(key_index)
 
           if @depth == @search_path.size - 1
             @found_options = pass_opts
+            @found_item = item
             @found_block = proc {
               yield item, 0
             }
@@ -120,7 +111,7 @@ module Props
 
           @depth += 1
           if pass_opts[:partial]
-            fragment_name = Fragment.fragment_name_from_options(pass_opts)
+            fragment_name = Fragment.fragment_name_from_options(pass_opts, item)
             if fragment_name
               @fragment_name = fragment_name
               @fragment_path = @traveled_path.clone

data/lib/props_template/test.md

@@ -0,0 +1,28 @@
+array
+handle_collection
+  all_opts = collection.map do |item|
+    refine_item_options(item, options)
+  end
+  creates clone of the opts using 
+  refine_item_options clones original options
+    then subsequently the ext refine_item_options
+    gets called first, 
+
+  refine_all_item_options <- operates on the entire collection
+
+  handle_collection_item
+    set_content options
+
+
+ 
+base with ExtensionManager
+    refine_all_item_options - overrided with ext manager
+      - which attahes a _template with partialer
+       to it AND multifetch and attaches it to cache
+       as [key, result]
+
+    refine_item_options
+      - transforms key: :id to key = [key, val]
+      - passes to refine_options
+          which is then asks the searcher the cache and
+          deferment to mutate the option

data/lib/props_template/version.rb

@@ -1,3 +1,3 @@
 module Props
-  VERSION = "1.0.0.alpha.3".freeze
+  VERSION = "1.0.0".freeze
 end

data/lib/props_template.rb

@@ -9,6 +9,8 @@ require "active_support/core_ext/string/output_safety"
 require "active_support/core_ext/array"
 require "props_template/searcher"
 require "props_template/handler"
+require "props_template/options"
+require "props_template/helper"
 require "props_template/version"
 
 require "active_support"
@@ -28,7 +30,7 @@ module Props
       :deferred!,
       :fragments!,
       :disable_deferments!,
-      :set_block_content!,
+      :set_content!,
       :traveled_path!,
       :fragment_context!,
       to: :builder!
@@ -51,13 +53,14 @@ module Props
         options.delete(:dig)
 
         @builder.set!(key, options, &block)
-        found_block, found_path, found_options, fragment_path, fragment_context = @builder.found!
+        found_block, found_path, found_options, fragment_path, fragment_context, found_item = @builder.found!
         @found_path = found_path || []
         @fragment_context = fragment_context
         @builder = prev_builder
         @fragment_path = fragment_path
 
         if found_block
+          @builder.item_context = found_item
           set!(key, found_options, &found_block)
         end
       else

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: props_template
 version: !ruby/object:Gem::Version
-  version: 1.0.0.alpha.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Johny Ho
@@ -83,10 +83,13 @@ files:
 - lib/props_template/extensions/fragment.rb
 - lib/props_template/extensions/partial_renderer.rb
 - lib/props_template/handler.rb
+- lib/props_template/helper.rb
 - lib/props_template/layout_patch.rb
+- lib/props_template/options.rb
 - lib/props_template/partial_patch.rb
 - lib/props_template/railtie.rb
 - lib/props_template/searcher.rb
+- lib/props_template/test.md
 - lib/props_template/version.rb
 homepage: https://github.com/thoughtbot/props_template/
 licenses:
@@ -99,7 +102,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="