RubyGems - inertia_jb - Versions diffs - 0.2.0 → 0.3.0 - Mend

inertia_jb 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73afc6da5300453502fb918b78a802c92401b8dbe91fa6307ed4523a664c9716
-  data.tar.gz: 0fb62ff6422c754317d18f6ddcf49cb46982822a931f72db2773999117ea9652
+  metadata.gz: c821eb8ccc74579d17f768744858bb9a14f7838201dd2ff89be61f8f70298780
+  data.tar.gz: 4e385aefbe3adcdcd6069b422382cd91cc7cbe208f2275230433110a761a4d3d
 SHA512:
-  metadata.gz: cf13cab4f4de7bf9973354d12b590e58473c873a0eb07a84ea14b28a87d32e1ef6c57310c7255f4b7c92e828b66463e12d5d67c25f55c9cb12d558ac8e1d6970
-  data.tar.gz: '08e77238e1754dcdd0e2e74df5e984d38bab7c922ea9fa755495e09b50c056ef674eff9df8ea26dd0db3d91eca09ab1973b4744129da93064f691fccae40c4e9'
+  metadata.gz: fb985df39ed4ec250604244d93c968884b8d4a47588e031126d48f5b9489e5015192fc021de81c4b4e4d06018714065ed757046ec9728ed7804f930f073dd95e
+  data.tar.gz: d3e94480c54b50667a66c9416a59d6124e410b6d5da165e3344137128c9b2b88b111e07897ffccc0b56a915c955e060a0c103129813d476a99e085af337f2ccf

data/README.md CHANGED Viewed

@@ -63,9 +63,6 @@ Hashes, so there is zero impedance mismatch: no DSL to learn, no intermediate
 representation, and the full power of Ruby for building collections and
 conditionals.
-> Coming from `props_template`? That gem streams JSON strings, which don't map
-> cleanly onto Inertia's Hash-based resolver. jb's plain-Hash output is the
-> natural fit, which is why this gem is built on it.
 ## Installation
@@ -95,31 +92,6 @@ a layout; Inertia (XHR) visits always return a bare JSON body with no layout.
 The layout is chosen from inertia-rails' `config.layout`, matching
 `InertiaRails::Renderer`'s own semantics:
-```ruby
-# config/initializers/inertia_rails.rb
-InertiaRails.configure do |config|
-  config.default_render = false
-  # config.layout = true      # (default) use the controller's normal layout
-  # config.layout = "inertia" # use app/views/layouts/inertia.html.erb
-  # config.layout = false     # no layout — render just the <div id="app"> root
-end
-```
-- `true` / `nil` — the controller's default layout, resolved the normal Rails
-  way (`app/views/layouts/application.html.erb`, or any `layout "..."`
-  declaration in the controller).
-- A **String** — that named layout (`app/views/layouts/<name>.html.erb`).
-- `false` — no layout at all; the response is only the `<div id="app"
-  data-page="…">` root, so you provide `<html>`/`<head>`/asset tags elsewhere.
-Because `config.layout` is scoped per controller in inertia-rails, you can also
-set it on a single controller with `inertia_config layout: "..."`. Plain
-(non-Inertia) `.html.erb` actions in the same app keep their layout regardless
-of this setting.
-> **Note:** this gem does not perform server-side rendering (SSR), so
-> `inertia_ssr_head` in your layout will always be empty.
 ## Templates and partials
@@ -145,11 +117,75 @@ of this setting.
 which you embed directly. Don't name partials `.html.inertia` — that extension
 triggers the Inertia response wrapper and is only for top-level page templates.
+## Sharing a partial with a plain JSON API
+An Inertia page and a plain JSON endpoint are both, in the end, just **a Hash**,
+so a single jb partial can back both. Name the partial **without a format**
+(`_message.jb`, not `_message.html.jb`) so it resolves for the `html` format
+Inertia uses *and* the `json` format a normal API request uses:
+```ruby
+# app/views/messages/_message.jb
+{
+  id:      message.id,
+  content: message.content,
+  author:  render(partial: "authors/author", object: message.author)
+}
+```
+```ruby
+# app/views/messages/show.html.inertia   — the Inertia page
+{ **render(partial: "messages/message", object: @message) }
+```
+```ruby
+# app/views/messages/index.html.inertia   — nested under a key
+{ messages: render(partial: "messages/message", collection: @messages, as: :message) }
+```
+```ruby
+# app/views/messages/show.json.jb        — a plain JSON endpoint
+render(partial: "messages/message", object: @message)
+```
+Note the asymmetry: the JSON endpoint can return that Array at the top level,
+but the Inertia page **must** nest it under a key (`{ posts: … }`) — Inertia
+props must be an object, never a top-level Array.
+> **Gotcha — wrap the page template in a Hash literal.** A `.html.inertia` page
+> must **not** be a bare top-level `render(partial: …)`:
+>
+> ```ruby
+> # ❌ props get misread as the component name
+> render(partial: "messages/message", object: @message)
+>
+> # ✅ spread into a real Hash literal
+> { **render(partial: "messages/message", object: @message) }
+> ```
+>
+> jb's `render(partial:)` returns a `Jb::TemplateResult` (a delegator), not a
+> true `Hash`. inertia-rails decides *"is this props or a component name?"* with
+> `component.is_a?(Hash)`, so a bare partial result is taken for a component name
+> and your props end up in the `component` field. Wrapping it in a literal
+> `{ **… }` — or nesting it under a key, e.g. `{ message: render(…) }` — makes
+> the top-level value a genuine `Hash`, which inertia-rails reads as props. A
+> `.json.jb` endpoint never hits this, because jb serializes its top-level result
+> with `to_json` directly.
+If you'd rather keep a format-specific partial (`_message.json.jb`), borrow the
+`:json` variant from the Inertia side with `formats:`:
+```ruby
+# app/views/messages/show.html.inertia
+{ **render(partial: "messages/message", object: @message, formats: [:json]) }
+```
 ## Inertia prop types
 Because props are just a Hash, Inertia's special prop types are plain values you
 drop in. Inside a `.html.inertia` template you can use the short helpers
-(`optional`, `always`, `defer`, `scroll`, `merge`, `deep_merge`) or the full
+(`optional`, `always`, `defer`, `scroll`, `merge`, `deep_merge`, `once`, `cache`) or the full
 `InertiaRails.*` methods.
 ```ruby
@@ -171,23 +207,24 @@ drop in. Inside a `.html.inertia` template you can use the short helpers
   # Infinite scrolling (accepts a paginator or explicit metadata).
   feed: scroll(@pagy) {
     render(partial: "feed/item", collection: @items)
+  },
+  # Sent once and cached client-side; skipped on later visits until reset.
+  flash: once { session.delete(:flash) },
+  # Server-side cached via Rails.cache; the block's JSON output is reused
+  # across requests until the cache entry expires.
+  report: cache("posts/#{@post.id}/report", expires_in: 5.minutes) {
+    render(partial: "reports/report", object: @post.report)
   }
 }
 ```
 See the inertia-rails docs for [partial reloads](https://inertiajs.com/partial-reloads),
-[deferred props](https://inertiajs.com/deferred-props), and
-[infinite scroll](https://inertia-rails.dev/guide/infinite-scroll).
-## Caching
-Use plain Rails caching — you're caching Ruby Hashes:
-```ruby
-@posts.map do |post|
-  Rails.cache.fetch(post) { render(partial: "posts/post", object: post) }
-end
-```
+[deferred props](https://inertiajs.com/deferred-props),
+[infinite scroll](https://inertia-rails.dev/guide/infinite-scroll),
+[once props](https://inertia-rails.dev/guide/once-props), and
+[prop caching](https://inertia-rails.dev/guide/prop-caching).
 ## camelCase keys

data/lib/inertia_jb/helper.rb CHANGED Viewed

@@ -37,5 +37,16 @@ module InertiaJb
     def deep_merge(...)
       ::InertiaRails.deep_merge(...)
     end
+    # Sent once and cached client-side; skipped on later visits unless reset or expired.
+    def once(...)
+      ::InertiaRails.once(...)
+    end
+    # Server-side cached via Rails.cache; the block's result is stored as JSON
+    # and reused on subsequent requests until the cache expires.
+    def cache(...)
+      ::InertiaRails.cache(...)
+    end
   end
 end

data/lib/inertia_jb/version.rb CHANGED Viewed

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 module InertiaJb
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/test/controller_test.rb CHANGED Viewed

@@ -29,11 +29,18 @@ class TestController < ActionController::Base
   def special
     @id = 1
   end
+  # once (client-cached) + cache (server-cached).
+  def cached
+    @call_count = 0
+  end
 end
 class ControllerTest < ActionController::TestCase
   tests TestController
+  include ActiveSupport::Testing::TimeHelpers
   TEMPLATES = {
     "layouts/application.html.erb" => "<html><body><%= yield %></body></html>",
     "test/index.html.inertia"      => "{ content: 'content' }",
@@ -45,7 +52,10 @@ class ControllerTest < ActionController::TestCase
     "authors/_author.html.jb"  => "{ id: author[:id], name: author[:name] }",
     "comments/_comment.html.jb" => "{ body: comment[:body] }",
     "test/special.html.inertia" =>
-      "{ id: @id, stats: optional { { visits: 42 } }, feed: defer(group: :feed) { [1, 2, 3] } }"
+      "{ id: @id, stats: optional { { visits: 42 } }, feed: defer(group: :feed) { [1, 2, 3] } }",
+    "test/cached.html.inertia" =>
+      "{ flash: once { 'hello' }, " \
+      "report: cache('report', expires_in: 1.minute) { Time.current.to_f } }"
   }.freeze
   def setup
@@ -53,7 +63,7 @@ class ControllerTest < ActionController::TestCase
     @routes = ActionDispatch::Routing::RouteSet.new
     @routes.draw do
-      %i[index nested collection with_partial special].each do |action|
+      %i[index nested collection with_partial special cached].each do |action|
         get action.to_s => "test##{action}"
       end
     end
@@ -65,6 +75,7 @@ class ControllerTest < ActionController::TestCase
   def teardown
     super
     @routes.clear!
+    Rails.cache.clear
   end
   # ---- basic rendering -----------------------------------------------------
@@ -158,6 +169,50 @@ class ControllerTest < ActionController::TestCase
     assert_equal({ "feed" => ["feed"] }, page["deferredProps"])
   end
+  # ---- once props (client-cached) -----------------------------------------
+  def test_once_prop_included_on_first_visit
+    inertia_get :cached
+    page = JSON.parse(response.body)
+    assert_equal "hello", page.dig("props", "flash")
+    assert_equal({ "flash" => { "prop" => "flash" } }, page["onceProps"])
+  end
+  def test_once_prop_excluded_when_client_reports_it_cached
+    inertia_get :cached,
+                headers: {
+                  "X-Inertia-Partial-Component" => "test/cached",
+                  "X-Inertia-Except-Once-Props" => "flash"
+                }
+    page = JSON.parse(response.body)
+    refute page["props"].key?("flash"), "once prop should be absent when client reports it cached"
+  end
+  # ---- cached props (server-cached) ---------------------------------------
+  def test_cached_prop_serves_same_value_across_requests
+    inertia_get :cached
+    first = JSON.parse(response.body).dig("props", "report")
+    inertia_get :cached
+    second = JSON.parse(response.body).dig("props", "report")
+    assert_equal first, second, "cached prop should return the same value across requests"
+  end
+  def test_cached_prop_recomputes_after_expiry
+    inertia_get :cached
+    first = JSON.parse(response.body).dig("props", "report")
+    travel_to 2.minutes.from_now do
+      inertia_get :cached
+      second = JSON.parse(response.body).dig("props", "report")
+      refute_equal first, second, "cached prop should recompute after expiry"
+    end
+  end
   private
   def inertia_get(action, headers: {})

data/test/test_helper.rb CHANGED Viewed

@@ -6,6 +6,7 @@ require "action_controller/railtie"
 require "inertia_rails"
 require "inertia_jb"
 require "active_support/testing/autorun"
+require "active_support/testing/time_helpers"
 ActiveSupport.test_order = :random
@@ -14,6 +15,7 @@ ActiveSupport.test_order = :random
 Class.new(Rails::Application) do
   config.secret_key_base = "secret"
   config.eager_load = false
+  config.cache_store = :memory_store
 end.initialize!
 InertiaRails.configure do |c|

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: inertia_jb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - kikyous
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inertia_rails