Support InertiaRails.once prop

[skryukov]

This PR adds support for InertiaRails.once prop.

See Inertia Rails docs for more details: https://inertia-once.inertia-rails.pages.dev/guide/once-props

Related PRs:
Laravel adapter: inertiajs/inertia-laravel#793
Client-side: inertiajs/inertia#2732
Docs: inertiajs/docs#11

[cloudflare-workers-and-pages]

Deploying inertia-rails with    Cloudflare Pages

Latest commit:	6964831
Status:	✅  Deploy successful!
Preview URL:	https://bd6ef87b.inertia-rails.pages.dev
Branch Preview URL:	https://inertia-once.inertia-rails.pages.dev

View logs

[Copilot]

Pull request overview

This PR adds support for "once props" in InertiaRails - a feature that allows props to be resolved once on the server and cached by the client across subsequent page navigations. This is particularly useful for expensive-to-compute data, large datasets, or rarely-changing data like dropdown options.

Key changes:

• Introduces InertiaRails.once() helper method for creating once props with optional expiration times, custom keys, and fresh flag
• Adds once: true parameter support to existing prop types (deferred, optional, merge) for integration
• Implements client-side caching protocol via X-Inertia-Except-Once-Props header and onceProps metadata

Reviewed changes

Copilot reviewed 21 out of 22 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
lib/inertia_rails/prop_onceable.rb	Core module providing once prop functionality including expiration calculation and fresh flag support
lib/inertia_rails/once_prop.rb	New OnceProp class that always has once? returning true
lib/inertia_rails/renderer.rb	Updates rendering logic to handle once prop exclusion, add onceProps metadata to page object, and check X-Inertia-Except-Once-Props header
lib/inertia_rails/base_prop.rb	Updates initialize signature to accept keyword arguments for prop options
lib/inertia_rails/defer_prop.rb	Prepends PropOnceable module for once support
lib/inertia_rails/optional_prop.rb	Prepends PropOnceable module for once support
lib/inertia_rails/merge_prop.rb	Prepends PropOnceable module for once support
lib/inertia_rails/inertia_rails.rb	Adds InertiaRails.once() helper method and requires PropOnceable module
spec/inertia/once_prop_spec.rb	Unit tests for OnceProp class covering all functionality
spec/inertia/prop_onceable_spec.rb	Tests for PropOnceable module integration with DeferProp, OptionalProp, and MergeProp
spec/inertia/rendering_spec.rb	Comprehensive integration tests covering once prop rendering, caching, expiration, custom keys, and interaction with partial reloads
spec/dummy/app/controllers/inertia_render_test_controller.rb	Test controller actions for various once prop scenarios
spec/dummy/config/routes.rb	Routes for once prop test endpoints
docs/guide/once-props.md	Complete documentation for once props feature
docs/guide/the-protocol.md	Protocol documentation updates for once props including new header and page object metadata
docs/guide/shared-data.md	Documentation for sharing once props globally
docs/guide/partial-reloads.md	Documentation for combining once props with partial reloads
docs/guide/merging-props.md	Documentation for combining once props with merge props
docs/guide/deferred-props.md	Documentation for combining once props with deferred props
docs/cookbook/handling-validation-error-types.md	Code formatting improvements for type definitions
docs/.vitepress/config.mts	Adds once props to documentation navigation
docs/package-lock.json	Dependency updates for documentation tooling

Files not reviewed (1)

• docs/package-lock.json: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bknoles]

Looks great. I expected the implementation to be trickier than this ended up being. Good sign that our prop type POROs are a good abstraction 💪.

[bknoles]

A crime against English but totally consistent with Rails naming conventions 😀

[bknoles]

i like this. cleaner to read b/c the logic is better described