typed_attrs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11ede186057fb2f00a926b578dfa7ea647842bf76a1f3f3904b71b3b7f8cbff1
+  data.tar.gz: 7a1e677adbc23fa563fc600bd842fbe1ba82531c1b5f743f804f32582c2b450e
+SHA512:
+  metadata.gz: 1b1c68d5519e6b4ed951264bbcc60e276c3378e853f448f4cf92d903af0aaa2d967d48954ec392a94aed5b6ad102479cedff76baab530c3eeb1a77cc8fa7a2bf
+  data.tar.gz: 5062ae18a4d829f802b1593f21be45fb98da5258563ecdbfc75641c7de7ab331806360f597a0bd23a73c68cff4e0b49cddde24d766c16bc1c18c32fb68313fb4

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-01-05
+
+### Added
+- Initial release
+- Type-safe ActiveRecord attributes using Sorbet T::Struct
+- Support for JSON/JSONB columns (PostgreSQL, MySQL, SQLite)
+- TypeProcessor architecture with Registry pattern
+- Support for nested T::Struct, arrays, hashes, and union types (discriminated unions)
+- T.nilable(...) support for optional types
+- ActiveModel::Validations integration with indexed error messages
+- Tapioca DSL compiler for automatic RBI generation
+- Comprehensive test suite with 92%+ code coverage
+- Database integration tests for SQLite3, MySQL, and PostgreSQL

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Speria
+
+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,355 @@
+# TypedAttrs
+
+A Ruby gem that brings type-safe structured data to ActiveRecord using Sorbet's `T::Struct`. Store complex, nested objects in JSON/JSONB columns with full type safety, validation, and seamless integration with Sorbet's type system.
+
+## Key Features
+
+- 🎯 **Rich Types**: Nested structs, arrays, hashes, union types (discriminated unions), and nilable types
+- ✅ **Validation**: Automatic validation with indexed error messages for nested structures
+- 🗄️ **Database Agnostic**: PostgreSQL, MySQL, and SQLite support
+- 🔄 **Transparent Conversion**: Seamless conversion between `T::Struct` and JSON
+- 🛠️ **Tapioca Integration**: Automatic RBI file generation
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'typed_attrs'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Basic Usage (Single T::Struct)
+
+```ruby
+# Define your Sorbet struct
+class Product < T::Struct
+  const :name, String
+  const :price, Integer
+end
+
+# Use it as a typed attribute
+class Order < ActiveRecord::Base
+  attribute :product, TypedAttrs.to_type(Product)
+end
+
+# Assign with Hash
+order = Order.new
+order.product = { name: "Ruby Book", price: 3000 }
+
+# Assign with T::Struct
+order.product = Product.new(name: "Ruby Book", price: 3000)
+
+# Access as T::Struct
+order.product.name  # => "Ruby Book"
+order.product.price # => 3000
+
+# Save to database (stored as jsonb)
+order.save
+```
+
+### Array Type
+
+```ruby
+class Color < T::Struct
+  const :name, String
+  const :hex, String
+end
+
+class Palette < ActiveRecord::Base
+  attribute :colors, TypedAttrs.to_type(T::Array[Color])
+end
+
+palette = Palette.new
+palette.colors = [
+  { name: "Red", hex: "#FF0000" },
+  { name: "Blue", hex: "#0000FF" }
+]
+
+palette.colors[0].name # => "Red"
+```
+
+### Hash Type
+
+```ruby
+class BoxSize < T::Struct
+  const :width, Integer
+  const :height, Integer
+end
+
+class Layout < ActiveRecord::Base
+  attribute :box_sizes, TypedAttrs.to_type(T::Hash[String, BoxSize])
+end
+
+layout = Layout.new
+layout.box_sizes = {
+  "small" => { width: 100, height: 50 },
+  "large" => { width: 200, height: 100 }
+}
+
+layout.box_sizes["small"].width # => 100
+```
+
+### Union Type (Discriminated Union)
+
+```ruby
+module PetType
+  extend T::Helpers
+  extend TypedAttrs::DiscriminatedUnion
+
+  sealed!
+  discriminator_key "animal_type"
+end
+
+class Dog < T::Struct
+  include PetType
+
+  def self.discriminator = "dog"
+
+  const :name, String
+  const :breed, String
+end
+
+class Cat < T::Struct
+  include PetType
+
+  def self.discriminator = "cat"
+
+  const :name, String
+  const :lives, Integer
+end
+
+class PetOwner < ActiveRecord::Base
+  attribute :pet, TypedAttrs.to_type(PetType)
+end
+
+owner = PetOwner.new
+owner.pet = { animal_type: "dog", name: "Buddy", breed: "Golden Retriever" }
+# => #<Dog name="Buddy" breed="Golden Retriever">
+
+owner.pet = { animal_type: "cat", name: "Whiskers", lives: 9 }
+# => #<Cat name="Whiskers" lives=9>
+```
+
+### Nested Structs
+
+```ruby
+class Address < T::Struct
+  const :street, String
+  const :city, String
+end
+
+class Company < T::Struct
+  const :name, String
+  const :address, Address
+end
+
+class Employee < ActiveRecord::Base
+  attribute :company, TypedAttrs.to_type(Company)
+end
+
+employee = Employee.new
+employee.company = {
+  name: "Acme Corp",
+  address: { street: "123 Main St", city: "Springfield" }
+}
+
+employee.company.address.city # => "Springfield"
+```
+
+### Default Values
+
+```ruby
+class Settings < T::Struct
+  const :theme, String, default: "light"
+  const :notifications, T::Boolean, default: true
+  const :page_size, Integer, default: 20
+end
+
+class User < ActiveRecord::Base
+  attribute :settings, TypedAttrs.to_type(Settings)
+end
+
+user = User.new
+user.settings = {}
+user.settings.theme         # => "light"
+user.settings.notifications # => true
+user.settings.page_size     # => 20
+```
+
+### Validation
+
+TypedAttrs integrates with ActiveModel::Validations:
+
+```ruby
+class Product < T::Struct
+  include ActiveModel::Validations
+
+  const :name, String
+  const :price, Integer
+
+  validates :name, presence: true
+  validates :price, numericality: { greater_than: 0 }
+end
+
+class Order < ActiveRecord::Base
+  attribute :product, TypedAttrs.to_type(Product)
+  validates :product, typed_attrs: true
+end
+
+order = Order.new
+order.product = { name: "", price: -100 }
+order.valid? # => false
+order.errors.full_messages
+# => ["Product.name can't be blank", "Product.price must be greater than 0"]
+```
+
+Array elements are validated with indexed error keys:
+
+```ruby
+class Tag < T::Struct
+  include ActiveModel::Validations
+
+  const :name, String
+  validates :name, presence: true
+end
+
+class Article < T::Struct
+  const :title, String
+  const :tags, T::Array[Tag]
+end
+
+class Post < ActiveRecord::Base
+  attribute :article, TypedAttrs.to_type(Article)
+  validates :article, typed_attrs: true
+end
+
+post = Post.new
+post.article = { title: "Hello", tags: [{ name: "ruby" }, { name: "" }] }
+post.valid? # => false
+post.errors.full_messages
+# => ["Article.tags[1].name can't be blank"]
+```
+
+## Supported Features
+
+- ✅ Type-safe attributes using Sorbet `T::Struct`
+- ✅ PostgreSQL, MySQL, and SQLite (json/jsonb columns)
+- ✅ Primitive types: `String`, `Integer`, `Float`, `Boolean`, `Symbol`, `Date`, `Time`
+- ✅ Complex types: `T::Array`, `T::Hash`, Union types, `T.nilable`
+- ✅ Nested structs with arbitrary depth
+- ✅ Default values
+- ✅ Validation with indexed error messages
+- ✅ Automatic RBI generation via Tapioca
+
+## Type Mapping
+
+TypedAttrs automatically converts between Ruby/Sorbet types and JSON for database storage:
+
+| Ruby/Sorbet Type | JSON Type | Notes |
+|-----------------|-----------|-------|
+| `String` | `string` | Direct mapping |
+| `Integer` | `number` | Direct mapping |
+| `Float` | `number` | Direct mapping |
+| `T::Boolean` | `boolean` | Direct mapping |
+| `Symbol` | `string` | Serialized to string, deserialized back to symbol |
+| `Date` | `string` | ISO 8601 format (e.g., `"2025-10-08"`) |
+| `Time` | `string` | ISO 8601 with timezone (e.g., `"2025-10-08T15:30:00+09:00"`) |
+| `T::Struct` | `object` | Nested object with properties |
+| `T::Array[T]` | `array` | Array of specified type |
+| `T::Hash[String, T]` | `object` | Object with string keys and typed values |
+| `T.nilable(T)` | `null` or type | Allows null values |
+| Union (discriminated) | `object` | Object with discriminator key |
+
+### Examples
+
+```ruby
+# Symbol type - stored as string in JSON
+class Tag < T::Struct
+  const :name, String
+  const :status, Symbol  # :active, :archived, etc.
+end
+
+# Database: { "name": "ruby", "status": "active" }
+# Ruby:     Tag.new(name: "ruby", status: :active)
+
+# Date and Time types - stored as ISO 8601 strings
+class Event < T::Struct
+  const :title, String
+  const :date, Date
+  const :start_time, Time
+end
+
+# Database: { "title": "Meeting", "date": "2025-10-08", "start_time": "2025-10-08T15:30:00+09:00" }
+# Ruby:     Event.new(title: "Meeting", date: Date.new(2025, 10, 8), start_time: Time.new(2025, 10, 8, 15, 30, 0, "+09:00"))
+
+# Nested struct - stored as nested object
+class Address < T::Struct
+  const :street, String
+  const :city, String
+end
+
+class Company < T::Struct
+  const :name, String
+  const :address, Address
+end
+
+# Database: { "name": "Acme", "address": { "street": "123 Main", "city": "NYC" } }
+# Ruby:     Company.new(name: "Acme", address: Address.new(...))
+
+# Array type - stored as JSON array
+attribute :colors, TypedAttrs.to_type(T::Array[Color])
+# Database: [{ "name": "Red", "hex": "#FF0000" }, ...]
+# Ruby:     [Color.new(name: "Red", hex: "#FF0000"), ...]
+
+# Hash type - stored as JSON object
+attribute :sizes, TypedAttrs.to_type(T::Hash[String, BoxSize])
+# Database: { "small": { "width": 100, "height": 50 }, ... }
+# Ruby:     { "small" => BoxSize.new(width: 100, height: 50), ... }
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+### Running Tests
+
+```bash
+# Run all tests and linters (default task)
+bundle exec rake
+
+# Run tests only
+bundle exec rspec
+
+# Run unit tests only
+bundle exec rspec --tag type:unit
+
+# Run integration tests only (with SQLite, MySQL, PostgreSQL)
+bundle exec rspec --tag type:integration
+```
+
+### Code Quality and Type Checking
+
+```bash
+# Run RuboCop (linter)
+bundle exec rubocop
+bundle exec rubocop -a  # Auto-fix
+
+# Run Sorbet type checker
+bundle exec srb tc
+bundle exec rake sorbet:tc
+
+# Update RBI files (Tapioca)
+bundle exec rake sorbet:update
+```
+
+## License
+
+MIT License. See LICENSE file for details.

data/lib/active_model/validations/typed_attrs_validator.rb

@@ -0,0 +1,48 @@
+# typed: strict
+# frozen_string_literal: true
+
+module ActiveModel
+  module Validations
+    class TypedAttrsValidator < ActiveModel::EachValidator
+      extend T::Sig
+
+      sig { params(record: T.untyped, attribute: T.any(String, Symbol), value: T.untyped).void }
+      def validate_each(record, attribute, value)
+        return if value.nil?
+
+        attribute_type = get_typed_attribute_type(record, attribute)
+        return unless attribute_type
+
+        processor = attribute_type.processor
+        processor.traverse(value, path: "") do |_type_spec, node, path|
+          next unless node.respond_to?(:valid?)
+          next if node.valid?
+
+          node.errors.each do |error|
+            error_key = build_error_key(attribute, path, error.attribute)
+            record.errors.add(error_key, error.message)
+          end
+        end
+      end
+
+      private
+
+      sig { params(attribute: T.any(::String, Symbol), path: ::String, error_attribute: Symbol).returns(::String) }
+      def build_error_key(attribute, path, error_attribute)
+        if path.empty?
+          "#{attribute}.#{error_attribute}"
+        else
+          "#{attribute}#{path}.#{error_attribute}"
+        end
+      end
+
+      sig { params(record: T.untyped, attribute: T.any(String, Symbol)).returns(T.nilable(TypedAttrs::Types::Type)) }
+      def get_typed_attribute_type(record, attribute)
+        return nil unless record.class.respond_to?(:attribute_types)
+
+        attribute_type = record.class.attribute_types[attribute.to_s]
+        attribute_type.is_a?(TypedAttrs::Types::Type) ? attribute_type : nil
+      end
+    end
+  end
+end

data/lib/tapioca/dsl/compilers/typed_attribute.rb

@@ -0,0 +1,87 @@
+# typed: true
+# frozen_string_literal: true
+
+return unless defined?(Tapioca)
+return unless defined?(ActiveRecord::Base)
+
+require "tapioca/dsl"
+
+module Tapioca
+  module Dsl
+    module Compilers
+      class TypedAttribute < Tapioca::Dsl::Compiler
+        extend T::Sig
+
+        ConstantType = type_member { { fixed: T.class_of(ActiveRecord::Base) } }
+
+        sig { override.void }
+        def decorate
+          attributes = T.let(
+            constant.attribute_types.select { |_name, type| typed_attribute_type?(type) },
+            T::Hash[String, ActiveModel::Type::Value]
+          )
+
+          return if attributes.empty?
+
+          root.create_path(constant) do |klass|
+            attributes.each do |attr_name, type|
+              create_attribute_methods(klass, attr_name, type)
+            end
+          end
+        end
+
+        sig { override.returns(T::Enumerable[Module]) }
+        def self.gather_constants
+          descendants = T.cast(
+            ActiveRecord::Base.descendants.reject(&:abstract_class?),
+            T::Array[T.class_of(ActiveRecord::Base)]
+          )
+
+          descendants.select do |klass|
+            klass.attribute_types.values.any? { |type| typed_attribute_type?(type) }
+          rescue ActiveRecord::StatementInvalid
+            false
+          end
+        end
+
+        class << self
+          def typed_attribute_type?(type)
+            type.is_a?(TypedAttrs::Types::Type)
+          end
+        end
+
+        private
+
+        sig { params(type: ActiveModel::Type::Value).returns(T::Boolean) }
+        def typed_attribute_type?(type)
+          self.class.typed_attribute_type?(type)
+        end
+
+        sig { params(klass: RBI::Scope, attr_name: String, type: ActiveModel::Type::Value).void }
+        def create_attribute_methods(klass, attr_name, type)
+          case type
+          when TypedAttrs::Types::Type
+            create_type_attribute_methods(klass, attr_name, type)
+          end
+        end
+
+        sig { params(klass: RBI::Scope, attr_name: String, type: TypedAttrs::Types::Type).void }
+        def create_type_attribute_methods(klass, attr_name, type)
+          type_spec = type.instance_variable_get(:@type_spec)
+          type_string = type_spec.name
+
+          klass.create_method(
+            attr_name,
+            return_type: type_string
+          )
+
+          klass.create_method(
+            "#{attr_name}=",
+            parameters: [create_param("value", type: "T.untyped")],
+            return_type: type_string
+          )
+        end
+      end
+    end
+  end
+end

data/lib/typed_attrs/discriminated_union.rb

@@ -0,0 +1,51 @@
+# typed: true
+# frozen_string_literal: true
+
+module TypedAttrs
+  # To use DiscriminatedUnion, follow these steps:
+  #
+  # 1. Create a union module by extending T::Helpers and DiscriminatedUnion
+  # 2. Call sealed! and discriminator_key to configure the union
+  # 3. For each union member, include the union module
+  # 4. Define self.discriminator method to return the discriminator value
+  #
+  # Example:
+  #   module AnimalUnion
+  #     extend T::Helpers
+  #     extend TypedAttrs::DiscriminatedUnion
+  #
+  #     sealed!
+  #     discriminator_key "animal_type"
+  #   end
+  #
+  #   class Dog < T::Struct
+  #     include AnimalUnion
+  #
+  #     def self.discriminator = "dog"
+  #   end
+  module DiscriminatedUnion
+    extend T::Sig
+    extend T::Helpers
+
+    sig { params(key: String).void }
+    def discriminator_key(key)
+      @discriminator_key = T.let(key, T.nilable(String))
+    end
+
+    sig { returns(T.nilable(String)) }
+    def _get_discriminator_key
+      @discriminator_key
+    end
+
+    sig { params(base: T.untyped).void }
+    def included(base)
+      super
+
+      union_module = self
+
+      base.define_singleton_method(:discriminator_key) do
+        union_module._get_discriminator_key
+      end
+    end
+  end
+end

data/lib/typed_attrs/type_helpers.rb

@@ -0,0 +1,45 @@
+# typed: strict
+# frozen_string_literal: true
+
+module TypedAttrs
+  module TypeHelpers
+    include Kernel
+    extend T::Sig
+
+    # Check if a class is a T::Struct subclass
+    sig { params(klass: T.untyped).returns(T::Boolean) }
+    def struct_class?(klass)
+      return false unless klass.is_a?(Class)
+      return false unless klass.respond_to?(:<)
+
+      !!(klass < T::Struct)
+    end
+
+    # Check if a type object represents T.nilable(...)
+    sig { params(type_object: T.untyped).returns(T::Boolean) }
+    def nilable_type?(type_object)
+      return false unless type_object.is_a?(T::Types::Union)
+      return false unless type_object.respond_to?(:types)
+
+      types = T.unsafe(type_object).types
+      # Union must contain NilClass and exactly one non-nil type
+      has_nil = types.any? { |t| t.respond_to?(:raw_type) && t.raw_type == NilClass }
+      non_nil_count = types.count { |t| !t.respond_to?(:raw_type) || t.raw_type != NilClass }
+
+      has_nil && non_nil_count == 1
+    end
+
+    # Extract the inner type from T.nilable(Foo) -> Foo
+    sig { params(nilable_type: T.untyped).returns(T.untyped) }
+    def extract_nilable_inner_type(nilable_type)
+      raise ArgumentError, "Not a nilable type" unless nilable_type?(nilable_type)
+
+      types = T.unsafe(nilable_type).types
+      non_nil_types = types.reject { |t| t.respond_to?(:raw_type) && t.raw_type == NilClass }
+
+      raise ArgumentError, "T.nilable must have at least one non-nil type" if non_nil_types.empty?
+
+      non_nil_types.first
+    end
+  end
+end