zod_rails 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8e1e956f2954b2200c39a4b467529911806337883bd2674b31b7a271ef560a8
-  data.tar.gz: 681139d70905f6c34ee190f629f437e015a2eb1313a76940d42b0eaf6a8ffabe
+  metadata.gz: 1163af9def212c75de8a25cc2e35fda2bbef62b372b239cd7bface8a3ae56098
+  data.tar.gz: 9d397ad7adcd549b35d059157b209a2214c2a558310ff9e860f663cad1849c47
 SHA512:
-  metadata.gz: 30a4ce819ee99ac5bcdd83e482c16cd2029136af74e6e64c04a03960c8640991cef144eab6562eb431a0205c655c857687e78f023ffe66aaa9d8c53a953a7b1e
-  data.tar.gz: 7744055379a755592beadb1010992deeba5ef0fac4d0ea5719bd67d98191264d9671d0a4ee6806e2c62a7e97e0a69997d0bd8f80eca7ed6002c52d59ae7c236c
+  metadata.gz: d1bd6a4631656247e5a0a15faf4b2928cbc1b3e9d982086b661757b3ec8eed4eecaa0fa421561165238ba997afa9fe3f8788b616d407169da281a1b6cb5821e4
+  data.tar.gz: 10edec80377e583661f8741bac4bff3647992fbc35d5dd16117564eb1d802e7f955b731259d861458d2a8137fb3ea60d8f2837f3fdc1faf1b4530e24fad1c92b

data/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to ZodRails are documented here.
 
 ## Unreleased
 
+## 0.3.2 - 2026-08-03
+
+### Upgrade Notes
+
+- Upgrade from `0.3.0` or `0.3.1` immediately. Those releases omitted the Railtie's Rake task file from the packaged
+  gem, causing `Rails.application.load_tasks` and unrelated Rails tasks such as `db:migrate` and `assets:precompile`
+  to fail with `LoadError`.
+
+### Fixed
+
+- Include `lib/tasks/zod_rails.rake` in the published gem.
+- Verify the runtime manifest and task loading in the test suite.
+
+## 0.3.1 - 2026-08-03
+
+### Upgrade Notes
+
+- Regenerate committed schemas after upgrading if your models contain PostgreSQL arrays, adapter-reported `:bigint`
+  columns, or `time` columns. Their generated wire schemas now match Rails payload shapes more closely.
+
+### Fixed
+
+- Generate `z.array(...)` schemas for PostgreSQL array columns, with inclusion constraints on elements and
+  presence, length, default, and nullability constraints on the outer array.
+- Map adapter-reported `:bigint` columns to the JSON number shape emitted by Rails.
+- Validate Rails `time` payloads as ISO datetimes with timezone-offset support.
+
+### Changed
+
+- Run a generated-schema runtime contract against the pinned Zod version in CI.
+
 ## 0.3.0 - 2026-08-03
 
 ### Upgrade Notes

data/README.md

@@ -45,6 +45,9 @@ Add to your Gemfile:
 gem "zod_rails"
 ```
 
+Use `0.3.2` or newer. Versions `0.3.0` and `0.3.1` omitted the Railtie's Rake task file from the published gem and can
+break Rails task loading.
+
 Then run:
 
 ```bash
@@ -112,19 +115,24 @@ end
 | Rails/DB Type | Zod Type |
 |---------------|----------|
 | `string`, `text` | `z.string()` |
-| `integer` | `z.int()` |
+| `integer`, `bigint` | `z.int()` |
 | `float` | `z.number()` |
-| `bigint` | `z.string()` (avoids JS `Number` overflow) |
 | `decimal` | `z.string()` (preserves `BigDecimal` precision) |
 | `boolean` | `z.boolean()` |
 | `date` | `z.iso.date()` |
 | `datetime`, `timestamp` | `z.iso.datetime({ offset: true })` |
 | `json`, `jsonb` | `z.json()` |
 | `uuid` | `z.uuid()` |
-| `time` | `z.string()` |
+| `time` | `z.iso.datetime({ offset: true })` |
 | `binary` | `z.string()` |
 | `enum` | `z.enum([...])` |
 
+PostgreSQL array columns wrap the element mapping with `z.array(...)`. Nullability and input optionality apply to the
+array itself, so a nullable `string[]` becomes `z.array(z.string()).nullable()`, while a non-null array with a database
+default becomes `z.array(z.string())` in the response schema and `z.array(z.string()).optional()` in the input schema.
+Rails inclusion validators on array attributes constrain each element, so `inclusion: { in: %w[a b] }` produces an
+element enum inside the array.
+
 ## Validation Mappings
 
 ZodRails introspects your model validations and maps them to Zod constraints:
@@ -346,7 +354,15 @@ For custom types not in the mapping table, ZodRails falls back to `z.unknown()`.
 
 ZodRails generates a useful static approximation of database columns and unconditional model validations. It cannot reproduce validations that require database access, another attribute, or runtime model state. Conditional and context-specific validations, dynamic numericality values, uniqueness, and unsupported Ruby regular-expression modes are skipped.
 
-The generated wire types must match your serializers. In particular, `bigint` and `decimal` map to strings to avoid JavaScript precision loss; configure your API serializer to emit strings for those attributes. Review generated schemas when using adapter-specific or custom ActiveRecord types.
+The generated wire types must match your serializers. Rails emits integer and bigint attributes as JSON numbers, so
+ZodRails maps both to `z.int()`. Zod intentionally rejects integers outside JavaScript's safe integer range; serialize
+large identifiers as strings and provide an application-owned schema when values can exceed that range. Decimal values
+map to strings to preserve `BigDecimal` precision. Review generated schemas when using custom serializers,
+adapter-specific types, or custom ActiveRecord types.
+
+PostgreSQL permits null elements and multidimensional values without exposing either constraint through ordinary
+column metadata. ZodRails currently generates one-dimensional arrays with non-null elements. Use an application-owned
+schema when a column intentionally stores null elements or nested arrays.
 
 ### Misconfigured model names
 
@@ -380,8 +396,13 @@ After checking out the repo:
 ```bash
 bundle install
 bundle exec rspec
+bun install --frozen-lockfile
+bun run test:contracts
 ```
 
+The Bun contract test generates a TypeScript schema and parses representative Rails payload values with the pinned Zod
+version. This complements the Ruby unit and golden tests by exercising the generated code at runtime.
+
 ## Contributing
 
 1. Fork it

data/lib/tasks/zod_rails.rake

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+namespace :zod_rails do
+  desc "Generate Zod schemas for configured models (DRY_RUN=1 to preview only)"
+  task generate: :environment do
+    config = ZodRails.configuration
+    generator = ZodRails::Generator.new(output_dir: config.output_dir)
+
+    if config.models.empty?
+      puts "No models configured. Add models to ZodRails.configure { |c| c.models = ['User', 'Article'] }"
+      exit 1
+    end
+
+    resolution = ZodRails::ModelResolver.resolve(config.models)
+
+    unless resolution[:missing].empty?
+      puts "ZodRails: #{resolution[:missing].size} model(s) in config.models could not be loaded:"
+      resolution[:missing].each { |m| puts "  - #{m}" }
+      puts ""
+      puts "Check the model names in config/initializers/zod_rails.rb."
+      exit 1
+    end
+
+    unless resolution[:invalid].empty?
+      puts "ZodRails: configured constants must be concrete ActiveRecord models:"
+      resolution[:invalid].each { |model| puts "  - #{model}" }
+      exit 1
+    end
+
+    models = resolution[:resolved]
+
+    if ENV["DRY_RUN"] == "1"
+      drift = generator.check(models)
+      if drift.empty?
+        puts "ZodRails (dry run): no changes."
+      else
+        puts "ZodRails (dry run): would update #{drift.size} file(s):"
+        drift.each { |d| puts "  - #{d[:filename]} (#{d[:status]})" }
+      end
+    else
+      generated = generator.generate_all(models)
+      puts "Generated #{generated.size} schema file(s):"
+      generated.each { |f| puts "  - #{f}" }
+    end
+  end
+
+  desc "Check whether generated schemas match the current models (exits nonzero on drift)"
+  task check: :environment do
+    config = ZodRails.configuration
+    generator = ZodRails::Generator.new(output_dir: config.output_dir)
+
+    if config.models.empty?
+      puts "No models configured. Nothing to check."
+      exit 0
+    end
+
+    resolution = ZodRails::ModelResolver.resolve(config.models)
+
+    unless resolution[:missing].empty?
+      puts "ZodRails: #{resolution[:missing].size} model(s) in config.models could not be loaded:"
+      resolution[:missing].each { |m| puts "  - #{m}" }
+      exit 1
+    end
+
+    unless resolution[:invalid].empty?
+      puts "ZodRails: configured constants must be concrete ActiveRecord models:"
+      resolution[:invalid].each { |model| puts "  - #{model}" }
+      exit 1
+    end
+
+    drift = generator.check(resolution[:resolved])
+
+    if drift.empty?
+      puts "ZodRails: generated schemas are up to date."
+      exit 0
+    end
+
+    puts "ZodRails: #{drift.size} file(s) out of date:"
+    drift.each { |d| puts "  - #{d[:filename]} (#{d[:status]})" }
+    puts ""
+    puts "Run `bin/rails zod_rails:generate` to update."
+    exit 1
+  end
+
+  desc "Generate Zod schema for a specific model"
+  task :generate_model, [:model_name] => :environment do |_t, args|
+    model_name = args[:model_name]
+    unless model_name
+      puts "Usage: rails zod_rails:generate_model[ModelName]"
+      exit 1
+    end
+
+    config = ZodRails.configuration
+    generator = ZodRails::Generator.new(output_dir: config.output_dir)
+
+    resolution = ZodRails::ModelResolver.resolve([model_name])
+    if resolution[:missing].any?
+      puts "ZodRails: model '#{model_name}' could not be loaded. Check the spelling."
+      exit 1
+    end
+
+    if resolution[:invalid].any?
+      puts "ZodRails: '#{model_name}' is not a concrete ActiveRecord model."
+      exit 1
+    end
+
+    filename = generator.generate_all(resolution[:resolved]).first
+    puts "Generated: #{filename}"
+  end
+end

data/lib/zod_rails/generation/schema_builder.rb

@@ -59,7 +59,7 @@ module ZodRails
       end
 
       def string_array_inclusion(column, validations)
-        return nil unless STRING_TYPES.include?(column.type)
+        return nil if column.array || !STRING_TYPES.include?(column.type)
 
         validations.find { |validation| string_array_inclusion?(validation) }
       end
@@ -75,10 +75,11 @@ module ZodRails
         remaining = validations.reject { |validation| validation.equal?(inclusion) }
         Mapping::EnumMapper.call(
           inclusion.options[:in],
-          validation_chain: Mapping::ValidationMapper.call_all(remaining, base_type: :string),
+          validation_chain: Mapping::ValidationMapper.call_all(remaining, base_type: :string, array: column.array),
           nullable: nullable?(column, validations),
           input_schema: input_schema,
-          has_default: column.has_default
+          has_default: column.has_default,
+          array: column.array
         )
       end
 
@@ -86,10 +87,12 @@ module ZodRails
         values = inspector.enums[column.name]
         Mapping::EnumMapper.call(
           values,
-          validation_chain: Mapping::ValidationMapper.call_all(validations, base_type: :string),
+          validation_chain: Mapping::ValidationMapper.call_all(validations, base_type: :string, array: column.array),
           nullable: nullable?(column, validations),
           input_schema: input_schema,
-          has_default: column.has_default
+          has_default: column.has_default,
+          array: column.array,
+          element_validation_chain: array_element_validation_chain(column, validations)
         )
       end
 
@@ -98,10 +101,12 @@ module ZodRails
           column.type,
           nullable: nullable?(column, validations),
           input_schema: input_schema,
-          has_default: column.has_default
+          has_default: column.has_default,
+          array: column.array,
+          element_validation_chain: array_element_validation_chain(column, validations)
         )
 
-        validation_chain = Mapping::ValidationMapper.call_all(validations, base_type: column.type)
+        validation_chain = Mapping::ValidationMapper.call_all(validations, base_type: column.type, array: column.array)
         insert_validation_chain(base_type, validation_chain)
       end
 
@@ -126,6 +131,13 @@ module ZodRails
         end
       end
 
+      def array_element_validation_chain(column, validations)
+        return "" unless column.array
+
+        element_validations = validations.select { |validation| validation.kind == :inclusion }
+        Mapping::ValidationMapper.call_all(element_validations, base_type: column.type)
+      end
+
       def filtered_columns
         inspector.columns.reject { |col| excluded_columns.include?(col.name) }
       end

data/lib/zod_rails/introspection/column_info.rb

@@ -3,13 +3,14 @@
 module ZodRails
   module Introspection
     class ColumnInfo
-      attr_reader :name, :type, :nullable, :has_default
+      attr_reader :name, :type, :nullable, :has_default, :array
 
-      def initialize(name:, type:, nullable:, has_default:)
+      def initialize(name:, type:, nullable:, has_default:, array: false)
         @name = name
         @type = type
         @nullable = nullable
         @has_default = has_default
+        @array = array
         freeze
       end
 
@@ -19,7 +20,8 @@ module ZodRails
           type: column.type,
           nullable: column.null,
           has_default: !column.default.nil? ||
-            (column.respond_to?(:default_function) && !column.default_function.nil?)
+            (column.respond_to?(:default_function) && !column.default_function.nil?),
+          array: column.respond_to?(:array?) && column.array?
         )
       end
 
@@ -28,12 +30,13 @@ module ZodRails
           name == other.name &&
           type == other.type &&
           nullable == other.nullable &&
-          has_default == other.has_default
+          has_default == other.has_default &&
+          array == other.array
       end
       alias eql? ==
 
       def hash
-        [self.class, name, type, nullable, has_default].hash
+        [self.class, name, type, nullable, has_default, array].hash
       end
     end
   end

data/lib/zod_rails/mapping/enum_mapper.rb

@@ -3,16 +3,30 @@
 module ZodRails
   module Mapping
     class EnumMapper
-      def self.call(values, nullable: false, input_schema: false, has_default: false, validation_chain: "")
+      def self.call(values, nullable: false, input_schema: false, array: false, **options)
+        has_default = options.fetch(:has_default, false)
+        validation_chain = options.fetch(:validation_chain, "")
+        element_validation_chain = options.fetch(:element_validation_chain, "")
         names = values.is_a?(Hash) ? values.keys : values
         quoted = names.map { |name| JSON.generate(name.to_s) }
         enum = "z.enum([#{quoted.join(", ")}])"
-        base = validation_chain.empty? ? enum : "z.string()#{validation_chain}.pipe(#{enum})"
+        base = if array
+                 array_schema(enum, element_validation_chain, validation_chain)
+               elsif validation_chain.empty?
+                 enum
+               else
+                 "z.string()#{validation_chain}.pipe(#{enum})"
+               end
 
         suffix = determine_suffix(nullable: nullable, input_schema: input_schema, has_default: has_default)
         "#{base}#{suffix}"
       end
 
+      def self.array_schema(enum, element_validation_chain, array_validation_chain)
+        element = element_validation_chain.empty? ? enum : "z.string()#{element_validation_chain}.pipe(#{enum})"
+        "z.array(#{element})#{array_validation_chain}"
+      end
+
       def self.determine_suffix(nullable:, input_schema:, has_default:)
         return "" unless nullable || has_default
 
@@ -23,7 +37,7 @@ module ZodRails
         end
       end
 
-      private_class_method :determine_suffix
+      private_class_method :array_schema, :determine_suffix
     end
   end
 end

data/lib/zod_rails/mapping/type_mapper.rb

@@ -7,25 +7,29 @@ module ZodRails
         string: "z.string()",
         text: "z.string()",
         integer: "z.int()",
-        bigint: "z.string()",
+        bigint: "z.int()",
         float: "z.number()",
         decimal: "z.string()",
         boolean: "z.boolean()",
         date: "z.iso.date()",
         datetime: "z.iso.datetime({ offset: true })",
         timestamp: "z.iso.datetime({ offset: true })",
-        time: "z.string()",
+        time: "z.iso.datetime({ offset: true })",
         json: "z.json()",
         jsonb: "z.json()",
         uuid: "z.uuid()",
         binary: "z.string()"
       }.freeze
 
-      def self.call(type, nullable: false, input_schema: false, has_default: false)
+      def self.call(type, nullable: false, input_schema: false, array: false, **options)
+        has_default = options.fetch(:has_default, false)
+        element_validation_chain = options.fetch(:element_validation_chain, "")
         base = TYPE_MAP.fetch(type.to_sym) do
           ZodRails.logger.warn("ZodRails: Unknown type '#{type}', falling back to z.unknown()")
           "z.unknown()"
         end
+        base = "#{base}#{element_validation_chain}"
+        base = "z.array(#{base})" if array
 
         suffix = determine_suffix(nullable: nullable, input_schema: input_schema, has_default: has_default)
         "#{base}#{suffix}"

data/lib/zod_rails/mapping/validation_mapper.rb

@@ -13,35 +13,37 @@ module ZodRails
       NUMERIC_ZOD_TYPES = %i[integer float].freeze
       STRING_ZOD_TYPES = %i[string text].freeze
 
-      def self.call(validation, base_type:)
+      def self.call(validation, base_type:, array: false)
         return "" if validation.conditional? || no_op_presence?(validation)
 
         case validation.kind
-        when :presence then map_presence(validation, base_type)
-        when :length then map_length(validation, base_type)
-        when :numericality then map_numericality(validation, base_type)
-        when :format then map_format(validation, base_type)
-        when :inclusion then map_inclusion(validation, base_type)
+        when :presence then map_presence(validation, base_type, array)
+        when :length then map_length(validation, base_type, array)
+        when :numericality then map_numericality(validation, base_type, array)
+        when :format then map_format(validation, base_type, array)
+        when :inclusion then map_inclusion(validation, base_type, array)
         else ""
         end
       end
 
-      def self.call_all(validations, base_type:)
+      def self.call_all(validations, base_type:, array: false)
         constraints = { min: nil, max: nil, length: nil, others: [] }
 
         validations.each do |v|
-          collect_constraints(v, base_type, constraints)
+          collect_constraints(v, base_type, constraints, array)
         end
 
         build_chain(constraints)
       end
 
-      def self.map_presence(_validation, base_type)
+      def self.map_presence(_validation, base_type, array)
+        return ".min(1)" if array
+
         STRING_ZOD_TYPES.include?(base_type) ? ".min(1)#{presence_suffix}" : ""
       end
 
-      def self.map_length(validation, base_type)
-        return "" unless STRING_ZOD_TYPES.include?(base_type)
+      def self.map_length(validation, base_type, array)
+        return "" unless array || STRING_ZOD_TYPES.include?(base_type)
 
         parts = []
         opts = validation.options
@@ -56,8 +58,8 @@ module ZodRails
         parts.join
       end
 
-      def self.map_numericality(validation, base_type)
-        return "" unless NUMERIC_ZOD_TYPES.include?(base_type)
+      def self.map_numericality(validation, base_type, array)
+        return "" if array || !NUMERIC_ZOD_TYPES.include?(base_type)
 
         validation.options.filter_map do |key, value|
           method = NUMERICALITY_MAP[key]
@@ -65,8 +67,8 @@ module ZodRails
         end.join
       end
 
-      def self.map_format(validation, base_type)
-        return "" unless STRING_ZOD_TYPES.include?(base_type)
+      def self.map_format(validation, base_type, array)
+        return "" if array || !STRING_ZOD_TYPES.include?(base_type)
 
         regex = validation.options[:with]
         return "" unless regex
@@ -74,7 +76,9 @@ module ZodRails
         RegexpMapper.call(regex)&.then { |expression| ".regex(#{expression})" } || ""
       end
 
-      def self.map_inclusion(validation, base_type)
+      def self.map_inclusion(validation, base_type, array)
+        return "" if array
+
         values = validation.options[:in] || validation.options[:within]
         return "" unless values.is_a?(Array)
 
@@ -112,27 +116,35 @@ module ZodRails
         ".pipe(z.union([#{literals}]))"
       end
 
-      def self.collect_constraints(validation, base_type, constraints)
+      def self.collect_constraints(validation, base_type, constraints, array)
         return if validation.conditional? || no_op_presence?(validation)
+        return collect_array_constraints(validation, base_type, constraints) if array
 
         case validation.kind
-        when :presence then handle_presence_constraint(base_type, constraints)
-        when :length then handle_length_constraint(validation, base_type, constraints)
+        when :presence then handle_presence_constraint(base_type, constraints, false)
+        when :length then handle_length_constraint(validation, base_type, constraints, false)
         when :numericality then handle_numericality_constraint(validation, base_type, constraints)
         when :format then handle_format_constraint(validation, base_type, constraints)
         when :inclusion then handle_inclusion_constraint(validation, base_type, constraints)
         end
       end
 
-      def self.handle_presence_constraint(base_type, constraints)
-        return unless STRING_ZOD_TYPES.include?(base_type)
+      def self.collect_array_constraints(validation, base_type, constraints)
+        case validation.kind
+        when :presence then handle_presence_constraint(base_type, constraints, true)
+        when :length then handle_length_constraint(validation, base_type, constraints, true)
+        end
+      end
+
+      def self.handle_presence_constraint(base_type, constraints, array)
+        return unless array || STRING_ZOD_TYPES.include?(base_type)
 
         constraints[:min] = [constraints[:min] || 0, 1].max
-        constraints[:others] << presence_suffix
+        constraints[:others] << presence_suffix unless array
       end
 
-      def self.handle_length_constraint(validation, base_type, constraints)
-        return unless STRING_ZOD_TYPES.include?(base_type)
+      def self.handle_length_constraint(validation, base_type, constraints, array)
+        return unless array || STRING_ZOD_TYPES.include?(base_type)
 
         opts = validation.options
         constraints[:length] = opts[:is] if opts[:is]
@@ -213,14 +225,13 @@ module ZodRails
         value.is_a?(Numeric) && (!value.respond_to?(:finite?) || value.finite?)
       end
 
-      def self.no_op_presence?(validation)
-        validation.kind == :presence && validation.options[:allow_blank]
-      end
+      def self.no_op_presence?(validation) = validation.kind == :presence && validation.options[:allow_blank]
 
       private_class_method :map_presence, :map_length, :map_numericality, :map_format, :map_inclusion,
                            :build_array_inclusion_suffix, :string_array_for_string_type?,
                            :numeric_array_for_numeric_type?, :build_string_enum_suffix,
-                           :build_numeric_literal_suffix, :collect_constraints, :build_chain,
+                           :build_numeric_literal_suffix, :collect_constraints, :collect_array_constraints,
+                           :build_chain,
                            :handle_presence_constraint, :handle_length_constraint, :handle_format_constraint,
                            :handle_inclusion_constraint, :apply_range_inclusion, :apply_array_inclusion,
                            :handle_numericality_constraint, :apply_numeric_range, :presence_suffix, :static_number?,

data/lib/zod_rails/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zod_rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Matt Kelly
@@ -75,6 +75,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- lib/tasks/zod_rails.rake
 - lib/zod_rails.rb
 - lib/zod_rails/configuration.rb
 - lib/zod_rails/generation/file_writer.rb