alba-inertia 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 249d46c95a7a834638b3a75adfa694fc073dbd8df7dec61c810b7c94f5c667c0
+  data.tar.gz: a20aee6a7c1ecda7a3b16bf020fec41f77c55d5d085ec71141431bbb7e1eace5
+SHA512:
+  metadata.gz: f2f3d7b2c1a04456bb9421dda758f70e8e06de0f38fa7f0db8a6f0ed52861d63deeb20c611351e38964133d22b3292b0d9a3f555ae543768244e5d250a43487e
+  data.tar.gz: 692f121c110342f99fa059f3ea4aeb2d2b4b18bffe8e12a3519ad28078ec25ee2a840b79eb37adde59e29b82d8026a0bb4707615181b56e034bdae2af432dd1f

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog],
+and this project adheres to [Semantic Versioning].
+
+## [Unreleased]
+
+## [0.1.0] - 2025-11-04
+
+- Initial release ([@skryukov])
+
+[@skryukov]: https://github.com/skryukov
+
+[Unreleased]: https://github.com/skryukov/typelizer/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/skryukov/typelizer/commits/v0.1.0
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
+[Semantic Versioning]: https://semver.org/spec/v2.0.0.html

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Svyatoslav Kryukov
+
+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,206 @@
+# Alba::Inertia
+
+Seamless integration between [Alba](https://github.com/okuramasafumi/alba) serializers and [Inertia Rails](https://inertia-rails.dev/).
+
+## Features
+
+- Support for all Inertia prop types: optional, deferred, and merge props
+- Lazy evaluation for efficient data loading on partial reloads
+- Auto-detection of resource classes based on controller/action naming
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "alba"
+gem "inertia_rails"
+gem "alba-inertia"
+```
+
+## Usage
+
+### Basic Setup
+
+Include `Alba::Inertia::Resource` in your resource classes:
+
+```ruby
+class ApplicationResource
+  include Alba::Resource
+  include Alba::Inertia::Resource
+end
+```
+
+Include `Alba::Inertia::Controller` in your controllers:
+
+```ruby
+class InertiaController < ApplicationController
+  include Alba::Inertia::Controller
+end
+```
+
+### Defining Inertia Props
+
+#### Inline `inertia:` option (recommended)
+
+```ruby
+class CoursesIndexResource < ApplicationResource
+  # Simple attributes
+  attributes :id, :title
+
+  # Optional prop (loaded only when requested)
+  has_many :courses, serializer: CourseResource, inertia: :optional
+
+  # Deferred prop (loaded in separate request)
+  has_many :students, serializer: StudentResource, inertia: :defer
+
+  # Deferred with options
+  attribute :stats, inertia: { defer: { group: 'analytics', merge: true } } do |object|
+    expensive_calculation(object)
+  end
+
+  # Merge prop (for partial reloads)
+  has_many :comments, serializer: CommentResource, inertia: { merge: { match_on: :id } }
+end
+```
+
+#### Separate `inertia_prop` declaration
+
+```ruby
+class CoursesIndexResource < ApplicationResource
+  has_many :courses, serializer: CourseResource
+  inertia_prop :courses, optional: true
+
+  attribute :stats
+  inertia_prop :stats, defer: { merge: true, group: 'analytics' }
+end
+```
+
+### Controller Integration
+
+```ruby
+class CoursesController < InertiaController
+  def index
+    @courses = Course.all
+    @current_category_id = params[:category_id]
+    # Auto-detects CoursesIndexResource and passes instance variables
+  end
+
+  def show
+    @course = Course.find(params[:id])
+
+    # With a custom component
+    render_inertia "Courses/Show"
+  end
+
+  def create
+    @course = Course.new(course_params)
+
+    if @course.save
+      redirect_to courses_path
+    else
+      # With errors
+      render_inertia inertia: { errors: user.errors }
+    end
+  end
+end
+```
+
+### Serialization Modes
+
+#### `.to_inertia` - For Inertia.js rendering
+
+Returns lazy procs and Inertia prop objects:
+
+```ruby
+resource = CoursesIndexResource.new(courses: @courses)
+resource.to_inertia
+# => { "courses" => <InertiaRails::OptionalProp>, "stats" => <Proc> }
+```
+
+#### `.as_json` - For standard JSON
+
+Returns normal data (Typelizer, API endpoints):
+
+```ruby
+resource = CoursesIndexResource.new(courses: @courses)
+resource.as_json
+# => { "courses" => [...], "stats" => 42 }
+```
+
+### Inheritance
+
+Metadata is inherited from parent resources:
+
+```ruby
+class BaseResource < ApplicationResource
+  attribute :created_at, inertia: :optional
+end
+
+class CourseResource < BaseResource
+  attributes :id, :title
+  # Inherits created_at with optional: true
+end
+```
+
+Child can override parent metadata:
+
+```ruby
+class ExtendedCourseResource < CourseResource
+  inertia_prop :created_at, defer: true  # Override parent's optional: true
+end
+```
+
+## Configuration
+
+```ruby
+Alba::Inertia.configure do |config|
+  # Render with Alba resource class by default
+  config.default_render = true
+
+  # Wrap all props in lambdas by default
+  config.lazy_by_default = true
+end
+```
+
+## Advanced Usage
+
+### Custom Serializer Selection
+
+```ruby
+render_inertia(serializer: CustomResource)
+```
+
+### Custom Props
+
+```ruby
+render_inertia(locals: { custom: 'props'})
+```
+
+## Naming Convention
+
+The controller integration follows Rails conventions:
+
+```ruby
+# Controller: CoursesController
+# Action: index
+# Expected Resource: CoursesIndexResource or CoursesIndexSerializer 
+
+# Controller: Admin::UsersController
+# Action: show
+# Expected Resource: Admin::UsersShowResource or Admin::UsersShowSerializer
+```
+
+## 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 that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/skryukov/alba-inertia.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/alba/inertia/configuration.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Alba
+  module Inertia
+    class Configuration
+      # Render with Alba resource class by default
+      attr_accessor :default_render
+
+      # Wrap all props in lambdas by default
+      attr_accessor :lazy_by_default
+
+      def initialize
+        @default_render = true
+        @lazy_by_default = true
+      end
+    end
+  end
+end

data/lib/alba/inertia/controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Alba
+  module Inertia
+    module Controller
+      private
+
+      def default_render
+        Alba::Inertia.config.default_render ? render_inertia : super
+      end
+
+      def render_inertia(component = nil, serializer: inertia_serializer_class, locals: view_assigns, **props)
+        resource = serializer&.new(locals.symbolize_keys!)
+        data = resource.respond_to?(:to_inertia) ? resource.to_inertia : resource.as_json
+
+        render inertia: component || true, props: data || {}, **props
+      end
+
+      def inertia_serializer_class
+        class_name = "#{controller_name}_#{action_name}_resource".classify
+        class_name.safe_constantize || class_name.gsub(/Resource$/, "Serializer").safe_constantize
+      end
+    end
+  end
+end

data/lib/alba/inertia/prop_builder.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Alba
+  module Inertia
+    class PropBuilder
+      class << self
+        def build(evaluation_block, options)
+          if options[:optional]
+            wrap_optional(evaluation_block, options[:optional])
+          elsif options[:defer]
+            wrap_defer(evaluation_block, options[:defer])
+          elsif options[:merge]
+            wrap_merge(evaluation_block, options[:merge])
+          elsif options[:always]
+            wrap_always(evaluation_block, options[:always])
+          else
+            Alba::Inertia.config.lazy_by_default ? evaluation_block : evaluation_block.call
+          end
+        end
+
+        private
+
+        def wrap_always(value_block, _opts)
+          ::InertiaRails.always(&value_block)
+        end
+
+        def wrap_optional(value_block, _opts)
+          ::InertiaRails.optional(&value_block)
+        end
+
+        def wrap_defer(value_block, opts)
+          if opts.is_a?(Hash)
+            options = {
+              group: opts[:group],
+              merge: opts[:merge],
+              deep_merge: opts[:deep_merge],
+              match_on: opts[:match_on]
+            }.compact
+
+            ::InertiaRails.defer(**options, &value_block)
+          else
+            ::InertiaRails.defer(&value_block)
+          end
+        end
+
+        def wrap_merge(value_block, opts)
+          if opts.is_a?(Hash)
+            options = {match_on: opts[:match_on]}.compact
+            ::InertiaRails.merge(**options, &value_block)
+          else
+            ::InertiaRails.merge(&value_block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/alba/inertia/resource.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Alba
+  module Inertia
+    module Resource
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      def self.extended(base)
+        base.include(self)
+      end
+
+      module ClassMethods
+        # Override Alba's attribute method to support inertia: option
+        #
+        # @example
+        #   attribute :stats, inertia: :optional do |object|
+        #     expensive_calc(object)
+        #   end
+        #
+        #   attribute :data, inertia: { defer: true } do |object|
+        #     object.data
+        #   end
+        def attribute(name, **options, &block)
+          extract_inertia_metadata(name, options)
+          super
+        end
+
+        # Override Alba's association method to support inertia: option
+        #
+        # @example
+        #   has_many :courses, serializer: CourseResource, inertia: { defer: true }
+        #   has_one :instructor, serializer: AuthorResource, inertia: :optional
+        #   has_many :items, serializer: ItemResource, key: :products, inertia: :optional
+        def association(name, condition = nil, **options, &block)
+          key = options[:key] || name
+          extract_inertia_metadata(key, options)
+          super
+        end
+        alias_method :one, :association
+        alias_method :many, :association
+        alias_method :has_one, :association
+        alias_method :has_many, :association
+
+        # Mark an attribute or association to be wrapped with Inertia props.
+        # This does NOT change the attribute definition itself - it only stores metadata
+        # that will be used when .to_inertia is called.
+        #
+        # @example Mark existing association as optional
+        #   has_many :courses, serializer: CourseResource
+        #   inertia_prop :courses, optional: true
+        #
+        # @example Defer with merge option
+        #   inertia_prop :stats, defer: { merge: true, group: 'analytics' }
+        #
+        # @example Merge with custom options
+        #   inertia_prop :metadata, merge: { match_on: :id, prepend: 'meta_' }
+        def inertia_prop(name, **kwargs)
+          options = {
+            optional: kwargs.delete(:optional) || false,
+            defer: kwargs.delete(:defer) || false,
+            merge: kwargs.delete(:merge) || false,
+            always: kwargs.delete(:always) || false
+          }.select { |_k, v| v.present? }
+
+          inertia_metadata[name] = options.freeze
+          auto_typelize_from_inertia(name, options)
+        end
+
+        def inertia_metadata
+          @inertia_metadata ||= begin
+            metadata = {}
+            if superclass.respond_to?(:inertia_metadata) && superclass != Alba::Resource
+              parent_metadata = superclass.inertia_metadata
+              metadata.merge!(parent_metadata) unless parent_metadata.empty?
+            end
+            metadata
+          end
+        end
+
+        private
+
+        def extract_inertia_metadata(name, options)
+          return unless options.key?(:inertia)
+
+          inertia_opts = parse_inertia_option(options.delete(:inertia))
+          inertia_prop(name, **inertia_opts) if inertia_opts.present?
+        end
+
+        def parse_inertia_option(value)
+          case value
+          when Symbol
+            # inertia: :optional => { optional: true }
+            {value => true}
+          when Array
+            # inertia: [:optional, :defer] => { optional: true, defer: true }
+            value.each_with_object({}) { |key, hash| hash[key] = true }
+          when Hash
+            # inertia: { defer: true } or { defer: { merge: true } } => unchanged
+            value
+          else
+            {}
+          end
+        end
+
+        def auto_typelize_from_inertia(name, inertia_opts)
+          return unless respond_to?(:typelize)
+
+          should_be_optional = inertia_opts[:optional].present? ||
+            inertia_opts[:defer].present? ||
+            inertia_opts[:merge].present?
+
+          typelize(name.to_sym => [optional: true]) if should_be_optional
+        end
+      end
+
+      def to_inertia
+        return {} if object.nil?
+
+        metadata = self.class.inertia_metadata
+        result = {}
+
+        self.class._attributes.each do |attr_name, attr_body|
+          attr_name_str = attr_name.to_s
+
+          evaluation_block = build_evaluation_block(attr_name, attr_body)
+
+          result[attr_name_str] = if metadata.key?(attr_name)
+            PropBuilder.build(evaluation_block, metadata[attr_name])
+          else
+            Alba::Inertia.config.lazy_by_default ? evaluation_block : evaluation_block.call
+          end
+        end
+
+        result
+      end
+
+      private
+
+      def build_evaluation_block(attr_name, attr_body)
+        serializer = self
+        obj = object
+
+        -> { serializer.send(:fetch_attribute, obj, attr_name, attr_body) }
+      end
+    end
+  end
+end

data/lib/alba/inertia/version.rb

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

data/lib/alba/inertia.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "inertia/version"
+require_relative "inertia/configuration"
+require_relative "inertia/controller"
+require_relative "inertia/prop_builder"
+require_relative "inertia/resource"
+
+module Alba
+  module Inertia
+    class << self
+      attr_accessor :configuration
+    end
+
+    def self.configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    def self.config
+      self.configuration ||= Configuration.new
+    end
+
+    def self.reset_configuration!
+      self.configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: alba-inertia
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Svyatoslav Kryukov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: alba
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: inertia_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Seamless integration between Alba and Inertia Rails.
+email:
+- me@skryukov.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/alba/inertia.rb
+- lib/alba/inertia/configuration.rb
+- lib/alba/inertia/controller.rb
+- lib/alba/inertia/prop_builder.rb
+- lib/alba/inertia/resource.rb
+- lib/alba/inertia/version.rb
+homepage: https://github.com/skryukov/typelizer
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/skryukov/typelizer/issues
+  changelog_uri: https://github.com/skryukov/typelizer/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/skryukov/typelizer/blob/main/README.md
+  homepage_uri: https://github.com/skryukov/typelizer
+  source_code_uri: https://github.com/skryukov/typelizer
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.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: Seamless integration between Alba and Inertia Rails.
+test_files: []