inertia_rails-camelize_props 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 54cfcff4bf70fe371ccf072b30e358ca3b172314995265be7348200af42006e7
+  data.tar.gz: 43ed1dae335109693b46daf79998492de2b82fef6178814e33e73899d0b14881
+SHA512:
+  metadata.gz: 3a4981c3afa1dacfce183dc94919fa4ec174ff6a3431709c5bbddb70ca9e4cabdc41884322c498f40bb9dd2ad0110eedfdcab0b8be93cc03b483896e77324bbd
+  data.tar.gz: 0f42ba571549bf7e43a778c48376e3ea547bfa87625058d59b4e76cceb25e59a6f9f0307ceb31ddbc630c5c2993e924937595a1c2b998e24869e10f9d80d25c7

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Takafumi ONAKA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,142 @@
+# InertiaRails::CamelizeProps
+
+Write props in `snake_case` in Rails, receive them in `camelCase` in your components — without breaking merge props, infinite scroll, deferred props, or partial reloads.
+
+## Installation
+
+```ruby
+gem "inertia_rails-camelize_props"
+```
+
+## Usage
+
+```ruby
+InertiaRails.configure do |config|
+  config.camelize_props = true
+end
+```
+
+Or per controller, like any other Inertia Rails option:
+
+```ruby
+class MediaController < ApplicationController
+  inertia_config(camelize_props: true)
+end
+```
+
+Then keep writing Rails as usual:
+
+```ruby
+render inertia: "Media/Index", props: {
+  media_list: InertiaRails.scroll(pagy) { ... },
+}
+```
+
+and refer to props by their camelCase names on the client:
+
+```jsx
+<InfiniteScroll data="mediaList">
+```
+
+## What gets camelized
+
+### Responses
+
+Keys are converted:
+
+```ruby
+props: { user_profile: { display_name: "John Doe" } }
+```
+
+```json
+"props": { "userProfile": { "displayName": "John Doe" } }
+```
+
+That happens at every level, once the props have been resolved, so whatever a block returned is converted like anything else. The keys of the flash are converted too.
+
+A page also names props outside of `props`, in the metadata that tells the client what to merge, what to fetch later and what it already holds. Those names are converted to match, which is what keeps those features working — an infinite scroll over `media_list` goes out as:
+
+```json
+{
+  "props":       { "mediaList": [...] },
+  "scrollProps": { "mediaList": { "pageName": "cursor" } },
+  "mergeProps":  ["mediaList"]
+}
+```
+
+The rest of that metadata is `prependProps`, `deepMergeProps`, `matchPropsOn`, `deferredProps`, `onceProps`, `rescuedProps` and `sharedProps`.
+
+What is left alone names no prop: the group a deferred prop is batched under, the query parameter a scroll prop paginates with, and a `once` key you supplied yourself.
+
+### Requests
+
+A frontend written in camelCase submits camelCase, so the parameters are renamed before the action runs:
+
+```ruby
+# the request arrives as { mediaItem: { mediaId: …, createdAt: … } }
+params.expect(media_item: [:media_id, :created_at])
+```
+
+Only requests carrying `X-Inertia` are renamed.
+
+The partial reload headers (`X-Inertia-Partial-Data`, `X-Inertia-Partial-Except`, `X-Inertia-Reset`, `X-Inertia-Except-Once-Props`) are matched against both the camelCase and the original name, so a frontend that still sends `media_list` keeps working.
+
+## Caveats
+
+- This gem patches private Inertia Rails internals, so an Inertia Rails upgrade may need a new release here.
+- A name with a digit straight after an underscore does not survive the round trip: `address_line_1` goes out as `addressLine1` and comes back as `address_line1`, since case cannot mark a word boundary in front of a digit. Name attributes without an underscore in front of a digit.
+- Every key is a name to be converted, so do not build keys out of user input. A value that needs arbitrary keys can go as a JSON string, or as an array of objects carrying the key as a field.
+- Remove any other case conversion: a key-renaming `prop_transformer`, which still runs before this one, or [inertia-caseshift](https://github.com/skryukov/inertia-caseshift) on the client.
+
+## The problem
+
+Inertia Rails already has `prop_transformer`, and its documentation suggests using it to camelize keys:
+
+```ruby
+config.prop_transformer = ->(props:) { props.deep_transform_keys { |key| key.to_s.camelize(:lower) } }
+```
+
+This silently breaks every feature that refers to a prop *by name*. Only the props hash is transformed, so the response disagrees with itself — here, an infinite scroll over `media_list`:
+
+```json
+{
+  "props":       { "mediaList": [] },
+  "scrollProps": { "media_list": { "pageName": "cursor" } },
+  "mergeProps":  ["media_list"]
+}
+```
+
+The client looks up `props["media_list"]` to merge into, finds nothing, and replaces the accumulated list instead of appending to it.
+
+Prop names appear in four places, and `prop_transformer` reaches only the first:
+
+1. the keys of the props hash
+2. the response metadata — `mergeProps`, `scrollProps`, `deferredProps`, `onceProps`, `matchPropsOn`, … — which list prop names *as values*
+3. partial reload request headers (`X-Inertia-Partial-Data` and friends), matched server-side
+4. prop options such as `match_on:` and `append:`, which are strings on the prop object rather than keys of any hash
+
+Moving the `prop_transformer` call to a different point does not help. A hash transform can only run *after* evaluation, since the keys inside a lazy prop's return value do not exist before it; but name matching must finish *before* evaluation, because skipping the evaluation of unrequested props is the whole point of partial reloads. Wherever the transform sits, the matching happens on the other side of it — and the `match_on:` strings are never keys of any hash, so no transform of one reaches them at all.
+
+The shape is wrong. A `Hash -> Hash` transformer can only hand the adapter a transformed **result**, and a result is the one thing that cannot be reused: the protocol needs the **mapping** itself, a per-key function it can apply to a single name wherever that name turns up. No `Hash -> Hash` function, called at any point, can supply that.
+
+## Why this gem exists
+
+Rails names things in `snake_case` and JavaScript in `camelCase`, and neither side should have to take up the other's convention to be understood. Something between them has to carry the difference, and the adapter is already there, writing the props and the protocol's names around them.
+
+Inertia Rails offers `prop_transformer`, which the problem above rules out. What answers it is not a `Hash -> Hash` transformation but a naming rule: something the adapter holds and applies to one name at a time, wherever a name appears. The Elixir adapter already offers one, behind a [`camelize_props`](https://inertia.hexdocs.pm/readme.html) flag.
+
+[Pull request 267](https://redirect.github.com/inertiajs/inertia-rails/pull/267) tried before, reading the problem as merge props being left out rather than as the shape of the transformer, and added a second lambda for them. Inertia Rails means to deprecate `prop_transformer` rather than improve it, which is right: a `Hash -> Hash` function is the wrong shape for this. This gem adds `camelize_props` instead.
+
+[inertia-caseshift](https://github.com/skryukov/inertia-caseshift) answers the same question on the client, in both directions, with one implementation serving every backend. This answers it on the server instead.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/onk/inertia_rails-camelize_props.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/inertia_rails/camelize_props/controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  module CamelizeProps
+    # Renames the parameters a request arrived with to the names the
+    # application declared, so that everything downstream — `permit`, `expect`,
+    # a nested form, a gem that reads `params` — sees what it expects.
+    #
+    # Only requests that are part of the Inertia conversation are renamed. The
+    # convention holds between this application and the frontend it handed its
+    # names to, and nowhere else.
+    module Controller
+      def self.install(controller = ::ActionController::Base)
+        controller.before_action do
+          next unless inertia_configuration.camelize_props && request.inertia?
+
+          params.deep_transform_keys! { |key| key.to_s.underscore }
+        end
+      end
+    end
+  end
+end

data/lib/inertia_rails/camelize_props/key_list.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  module CamelizeProps
+    # The prop names a partial reload asked for, which arrive in camelCase
+    # because that is how the client was given them. A name is looked up in
+    # both forms, so that a frontend still naming props as Rails declared
+    # them keeps working.
+    class KeyList < Array
+      def include?(name)
+        super || super(Naming.path(name))
+      end
+    end
+  end
+end

data/lib/inertia_rails/camelize_props/metadata.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  module CamelizeProps
+    # Camelizes the names a page carries outside of `props`: the metadata the
+    # client reads to decide what to merge, defer or remember, and the flash it
+    # reads by key. All of them were chosen by the application and handed to
+    # the client, so all of them follow the same convention.
+    module Metadata
+      PATH_LISTS = %i[mergeProps prependProps deepMergeProps matchPropsOn rescuedProps sharedProps].freeze
+
+      def self.camelize(page)
+        page.to_h { |name, value| [name, camelize_entry(name, value)] }
+      end
+
+      def self.camelize_entry(name, value)
+        return camelize_paths(value) if PATH_LISTS.include?(name)
+
+        case name
+        when :deferredProps then camelize_grouped_paths(value)
+        when :scrollProps then camelize_keyed_paths(value)
+        when :onceProps then camelize_once(value)
+        when :flash then Naming.deep(value)
+        else value
+        end
+      end
+      private_class_method :camelize_entry
+
+      def self.camelize_paths(paths)
+        paths.map { |path| Naming.path(path) }
+      end
+      private_class_method :camelize_paths
+
+      # The group a deferred prop belongs to is named by the application and is
+      # not a prop name.
+      def self.camelize_grouped_paths(groups)
+        groups.transform_values { |paths| camelize_paths(paths) }
+      end
+      private_class_method :camelize_grouped_paths
+
+      # A scroll prop's value describes its pagination rather than any prop.
+      def self.camelize_keyed_paths(paths)
+        paths.transform_keys { |path| Naming.path(path) }
+      end
+      private_class_method :camelize_keyed_paths
+
+      # A once key only names a prop when the application did not supply one of
+      # its own, in which case it is an opaque identifier and stays as it is.
+      def self.camelize_once(once_props)
+        once_props.to_h do |once_key, entry|
+          path = entry[:prop]
+          [once_key.to_s == path.to_s ? Naming.path(once_key) : once_key, entry.merge(prop: Naming.path(path))]
+        end
+      end
+      private_class_method :camelize_once
+    end
+  end
+end

data/lib/inertia_rails/camelize_props/naming.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module InertiaRails
+  module CamelizeProps
+    # The mapping this gem owns. Every conversion goes through a single name at
+    # a time, so the same mapping serves prop keys, the paths in the protocol
+    # metadata, and the matching of names arriving in partial reload headers.
+    module Naming
+      # Preserves the String/Symbol type of the original, so that keys Inertia
+      # Rails looks up by symbol keep matching after conversion.
+      def self.key(name)
+        camelized = name.to_s.camelize(:lower)
+        name.is_a?(Symbol) ? camelized.to_sym : camelized
+      end
+
+      # Prop paths are dot separated ("user.first_name"), and each segment is a
+      # name in its own right. Array indices camelize to themselves.
+      def self.path(path)
+        path.to_s.split(".").map { |segment| segment.camelize(:lower) }.join(".")
+      end
+
+      def self.deep(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(name, nested), result| result[key(name)] = deep(nested) }
+        when Array
+          value.map { |item| deep(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/inertia_rails/camelize_props/option.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "inertia_rails"
+
+module InertiaRails
+  module CamelizeProps
+    # Registers `camelize_props` as an Inertia Rails option, so that it can be
+    # set globally or per controller like any other one.
+    #
+    # Inertia Rails builds its option list into frozen constants as it loads,
+    # and rejects any option it does not recognize, so adding one means
+    # replacing those constants rather than adding to them.
+    module Option
+      NAME = :camelize_props
+
+      def self.install(configuration = ::InertiaRails::Configuration)
+        return if configuration::OPTION_NAMES.include?(NAME)
+
+        defaults = configuration::DEFAULTS.merge(NAME => false).freeze
+        replace_constant(configuration, :DEFAULTS, defaults)
+        replace_constant(configuration, :OPTION_NAMES, defaults.keys.freeze)
+        define_accessors(configuration)
+      end
+
+      def self.replace_constant(configuration, name, value)
+        configuration.send(:remove_const, name)
+        configuration.const_set(name, value)
+      end
+      private_class_method :replace_constant
+
+      # Inertia Rails defines an accessor for each option it knows about while
+      # it loads, which has already happened by now.
+      def self.define_accessors(configuration)
+        configuration.define_method(NAME) { evaluate_option(options[NAME]) }
+        configuration.define_method(:"#{NAME}=") { |value| @options[NAME] = value }
+      end
+      private_class_method :define_accessors
+    end
+  end
+end

data/lib/inertia_rails/camelize_props/props_resolver.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "inertia_rails"
+
+module InertiaRails
+  module CamelizeProps
+    # Matches the names a partial reload asked for against the props. The
+    # requested names are in camelCase, the paths here are not, so each path is
+    # offered in both forms and Inertia Rails' own matching decides.
+    module PropsResolver
+      def self.install(resolver = ::InertiaRails::PropsResolver)
+        resolver.prepend(self)
+      end
+
+      private
+
+      def explicitly_requested?(path)
+        candidates(path).any? { |candidate| super(candidate) }
+      end
+
+      # A prop survives an `only` filter as soon as one of its names was asked
+      # for, so it is excluded only when every one of them was left out.
+      def excluded_by_only_partial_keys?(path)
+        candidates(path).all? { |candidate| super(candidate) }
+      end
+
+      def excluded_by_except_partial_keys?(path)
+        candidates(path).any? { |candidate| super(candidate) }
+      end
+
+      def candidates(path)
+        return [path] unless partial_keys.is_a?(KeyList)
+
+        [path, Naming.path(path)].uniq
+      end
+    end
+  end
+end

data/lib/inertia_rails/camelize_props/renderer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "inertia_rails"
+
+module InertiaRails
+  module CamelizeProps
+    # Camelizes the page once the renderer has finished building it. Every way a
+    # page leaves Rails is covered from here, because the response body, the
+    # `data-page` of the initial HTML and the payload posted to the SSR server
+    # are all built from this one hash.
+    module Renderer
+      def self.install(renderer = ::InertiaRails::Renderer)
+        renderer.prepend(self)
+      end
+
+      private
+
+      def page
+        page = super
+        return page unless @configuration.camelize_props
+        return page if @camelized
+
+        @camelized = true
+        @page = Metadata.camelize(page).merge(props: camelize_page_props(page[:props]))
+      end
+
+      # The names a partial reload asked for are matched against the props by
+      # the resolver, which recognizes this list as holding client-side names.
+      def parse_header(name)
+        keys = super
+        return keys unless @configuration.camelize_props
+
+        KeyList.new(keys || [])
+      end
+
+      # The meta prop carries serialized meta tags rather than props, under a
+      # name Inertia Rails and the client both address directly.
+      def camelize_page_props(props)
+        Naming.deep(props.except(:_inertia_meta)).merge(props.slice(:_inertia_meta))
+      end
+    end
+  end
+end

data/lib/inertia_rails/camelize_props/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module InertiaRails
+  module CamelizeProps
+    VERSION = "0.1.0"
+  end
+end

data/lib/inertia_rails/camelize_props.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "camelize_props/version"
+require_relative "camelize_props/naming"
+require_relative "camelize_props/key_list"
+require_relative "camelize_props/metadata"
+require_relative "camelize_props/option"
+require_relative "camelize_props/controller"
+require_relative "camelize_props/props_resolver"
+require_relative "camelize_props/renderer"
+
+InertiaRails::CamelizeProps::Option.install
+ActiveSupport.on_load(:action_controller_base) do
+  InertiaRails::CamelizeProps::Controller.install(self)
+end
+
+InertiaRails::CamelizeProps::PropsResolver.install
+InertiaRails::CamelizeProps::Renderer.install

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: inertia_rails-camelize_props
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Takafumi ONAKA
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: inertia_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.22.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.22.0
+description: Camelizes prop names on the server, including Inertia's protocol metadata
+  and partial reload headers.
+email:
+- takafumi.onaka@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/inertia_rails/camelize_props.rb
+- lib/inertia_rails/camelize_props/controller.rb
+- lib/inertia_rails/camelize_props/key_list.rb
+- lib/inertia_rails/camelize_props/metadata.rb
+- lib/inertia_rails/camelize_props/naming.rb
+- lib/inertia_rails/camelize_props/option.rb
+- lib/inertia_rails/camelize_props/props_resolver.rb
+- lib/inertia_rails/camelize_props/renderer.rb
+- lib/inertia_rails/camelize_props/version.rb
+homepage: https://github.com/onk/inertia_rails-camelize_props
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/onk/inertia_rails-camelize_props
+  source_code_uri: https://github.com/onk/inertia_rails-camelize_props
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Server-side snake_case to camelCase prop conversion for Inertia Rails.
+test_files: []