zero_ruby 0.1.0.alpha2 → 0.1.0.alpha5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d8baa0973deb010422a2e5d6679af4580b9c37666b2649f383c0bf6525a77c9
-  data.tar.gz: 27e0a5593d3344c6260d96838e94ce94a8af36225b861318091ed57532a92dda
+  metadata.gz: 68451ec0c319aab33578ee4ac8aa28f61426ade64f4185047528387c5c95f3e5
+  data.tar.gz: fc5b90718c5c0aa5ee11020b02e01d422cee0108bb1095c9aac8eb184dd6c050
 SHA512:
-  metadata.gz: 83b6256cf6db475ad7f6c5de6d958f6ed72627dd2d2ae5211183d2ed2fe2c346338fbda6cb52ca79aa7aaf7c343e342e017b4015004cba3c97d351da80b679de
-  data.tar.gz: 694ac953e5df97e3a747054846612923928d24eb3a184d5f53c999895419f2ba3885fb128034c8bd54b934c976e832d8cf58fb5a7469c8ace7e75f91185266c4
+  metadata.gz: b60c2a285735db948bf33ebd52f78fc09329ed3c0a012cc000dab2eda668bf37920058dd4444317ff8bde80fcf70713014ed24186037fdf6b9acf35f32f3dc6b
+  data.tar.gz: bb7c53048a48d3c65c0303be1d67bf59368e3a2eec7ae8ce482c50e94304a8295be05ffb062e4591162a5d2cfb53f66d322b807e9c9c26c0039ec5ac3967e5d9

data/README.md

@@ -2,13 +2,10 @@
 
 A Ruby gem for handling [Zero](https://zero.rocicorp.dev/) mutations with type safety, validation, and full protocol support.
 
-0.1.0.alpha1
-
 ## Features
 
-- **Type coercion & checking** - String, Integer, Float, Boolean, ID, BigInt, ISO8601Date, ISO8601DateTime with automatic conversion and runtime type validation
-- **Type generation** - Generates typescript types you can use for your frontend mutators
-- **Argument validation** - length, numericality, format, inclusion, exclusion, etc.
+- **Type coercion & validation** - Built on [dry-types](https://dry-rb.org/gems/dry-types/) with String, Integer, Float, Boolean, ID, ISO8601Date, ISO8601DateTime
+- **Type generation** - Generates TypeScript types for your frontend mutators
 - **LMID tracking** - Duplicate and out-of-order mutation detection using Zero's `zero_0.clients` table
 - **Push protocol** - Version validation, transaction wrapping, retry logic
 
@@ -22,18 +19,20 @@ gem 'zero_ruby'
 
 ## Usage
 
-
 ### 1. Define mutations
 
+By default, the entire `execute` method runs inside a transaction with LMID (Last Mutation ID) tracking. Use [`skip_auto_transaction`](#manual-transaction-control) to manually control what runs inside the LMID transaction.
+
 ```ruby
 # app/zero/mutations/post_update.rb
 module Mutations
   class PostUpdate < ApplicationMutation
-    argument :id, ID, required: true
-    argument :post_input, Types::PostInput, required: true
+    argument :id, Types::ID
+    argument :post_input, Types::PostInput
 
     def execute(id:, post_input:)
       post = current_user.posts.find(id)
+      authorize! post, to: :update?
       post.update!(**post_input)
     end
   end
@@ -94,43 +93,22 @@ end
 match '/zero/push', to: 'zero#push', via: [:get, :post]
 ```
 
-## Base classes (optional)
-
-Create base classes to share behavior across mutations and input types:
-
-```ruby
-# app/zero/types/base_input_object.rb
-module Types
-  class BaseInputObject < ZeroRuby::InputObject
-    # Add shared behavior across all input objects here
-  end
-end
-
-# app/zero/mutations/application_mutation.rb
-class ApplicationMutation < ZeroRuby::Mutation
-  def current_user
-    ctx[:current_user]
-  end
-end
-```
-
 ## Define custom input types (optional)
 
 ```ruby
 # app/zero/types/post_input.rb
 module Types
   class PostInput < Types::BaseInputObject
-    argument :title, String, required: true,
-      validates: { length: { minimum: 1, maximum: 200 } }
-    argument :body, String, required: false
-    argument :published, Boolean, required: false, default: false
+    argument :title, Types::String.constrained(min_size: 1, max_size: 200)
+    argument :body, Types::String.optional
+    argument :published, Types::Boolean.default(false)
   end
 end
 ```
 
 ## Configuration
 
-Create an initializer to customize settings (all options have sensible defaults):
+Create an initializer to customize settings:
 
 ```ruby
 # config/initializers/zero_ruby.rb
@@ -138,8 +116,8 @@ ZeroRuby.configure do |config|
   # Storage backend (:active_record is the only built-in option)
   config.lmid_store = :active_record
 
-  # Retry attempts for transient errors
-  config.max_retry_attempts = 3
+  # Retry attempts for transient errors (default: 1)
+  config.max_retry_attempts = 1
 
   # Push protocol version (reject requests with different version)
   config.supported_push_version = 1
@@ -164,7 +142,7 @@ ZeroRuby generates TypeScript type definitions from your Ruby mutations. GET req
 }
 ```
 
-### Using with Zero Mutators
+### Use with Zero Mutators
 
 ```typescript
 import { defineMutator, defineMutators } from '@rocicorp/zero'
@@ -188,55 +166,126 @@ export const mutators = defineMutators({
 export type Mutators = typeof mutators
 ```
 
-## Validation
+## Types
+
+ZeroRuby provides types built on [dry-types](https://dry-rb.org/gems/dry-types/). When you inherit from `ZeroRuby::Mutation` or `ZeroRuby::InputObject`, types are available via the `Types` module:
 
 ```ruby
-argument :name, String, required: true,
-  validates: {
-    length: { minimum: 1, maximum: 100 },
-    format: { with: /\A[a-z]+\z/i, message: "only letters allowed" },
-    allow_blank: false
-  }
+# Basic types
+argument :name, Types::String
+argument :count, Types::Integer
+argument :price, Types::Float
+argument :active, Types::Boolean
+argument :id, Types::ID               # Non-empty string
+argument :date, Types::ISO8601Date
+argument :timestamp, Types::ISO8601DateTime
+
+# Optional types (accepts nil)
+argument :nickname, Types::String.optional
+
+# Default values
+argument :status, Types::String.default("draft")
+argument :enabled, Types::Boolean.default(false)
+```
 
-argument :age, Integer, required: true,
-  validates: {
-    numericality: { greater_than: 0, less_than: 150 }
-  }
+## Validation with Constraints
 
-argument :status, String, required: true,
-  validates: {
-    inclusion: { in: %w[draft published archived] }
-  }
+Use dry-types constraints for validation:
 
-argument :username, String, required: true,
-  validates: {
-    exclusion: { in: %w[admin root system], message: "is reserved" }
-  }
+```ruby
+# Length constraints
+argument :title, Types::String.constrained(min_size: 1, max_size: 200)
+argument :code, Types::String.constrained(size: 6)  # Exact size
 
-argument :email, String, required: true,
-  validates: {
-    allow_null: false,
-    allow_blank: false
-  }
+# Numeric constraints
+argument :age, Types::Integer.constrained(gt: 0, lt: 150)
+argument :quantity, Types::Integer.constrained(gteq: 1, lteq: 100)
+
+# Format (regex)
+argument :slug, Types::String.constrained(format: /\A[a-z0-9-]+\z/)
+
+# Inclusion
+argument :status, Types::String.constrained(included_in: %w[draft published archived])
+
+# Exclusion
+argument :username, Types::String.constrained(excluded_from: %w[admin root system])
+
+# Non-empty (filled)
+argument :email, Types::String.constrained(filled: true)
+
+# Combine constraints
+argument :name, Types::String.constrained(min_size: 1, max_size: 100, format: /\A[a-zA-Z ]+\z/)
 ```
 
-## Type coercion & checking
+### Available Constraints
+
+| Constraint | Description | Example |
+|------------|-------------|---------|
+| `min_size` | Minimum length | `min_size: 1` |
+| `max_size` | Maximum length | `max_size: 200` |
+| `size` | Exact length | `size: 6` |
+| `gt` | Greater than | `gt: 0` |
+| `gteq` | Greater than or equal | `gteq: 1` |
+| `lt` | Less than | `lt: 100` |
+| `lteq` | Less than or equal | `lteq: 99` |
+| `format` | Regex pattern | `format: /\A\d+\z/` |
+| `included_in` | Value must be in list | `included_in: %w[a b c]` |
+| `excluded_from` | Value must not be in list | `excluded_from: %w[x y]` |
+| `filled` | Non-empty string | `filled: true` |
+
+## Type coercion
 
-Types automatically coerce compatible values and raise `CoercionError` for invalid input:
+Types automatically coerce compatible values:
 
 | Type | Accepts | Rejects |
 |------|---------|---------|
-| `String` | Any value (via `.to_s`) | - |
-| `Integer` | `42`, `"42"`, `3.7` → `3` | `"abc"`, `""`, arrays, hashes |
-| `Float` | `3.14`, `"3.14"`, `42` → `42.0` | `"abc"`, `""`, arrays, hashes |
-| `Boolean` | `true`, `false`, `"true"`, `"false"`, `0`, `1` | `"yes"`, `"maybe"`, other values |
-| `ID` | `"abc"`, `123` → `"123"`, `:sym` → `"sym"` | `""`, arrays, hashes |
-| `BigInt` | `123`, `"9007199254740993"` | `"abc"`, `""`, floats |
-| `ISO8601Date` | `"2025-01-15"`, `Date`, `Time` → `Date` | `"invalid"`, `""`, integers |
-| `ISO8601DateTime` | `"2025-01-15T10:30:00Z"`, `Time`, `DateTime` | `"invalid"`, `""`, integers |
+| `String` | `"hello"` | `nil` |
+| `Integer` | `42`, `"42"`, `3.7` → `3` | `"abc"`, `""` |
+| `Float` | `3.14`, `"3.14"`, `42` → `42.0` | `"abc"`, `""` |
+| `Boolean` | `true`, `false`, `"true"`, `"false"` | `"yes"`, `1`, `0` |
+| `ID` | `"abc"` | `""` (empty string) |
+| `ISO8601Date` | `"2025-01-15"` → `Date` | `"invalid"`, `""` |
+| `ISO8601DateTime` | `"2025-01-15T10:30:00Z"` → `DateTime` | `"invalid"`, `""` |
+
+## Manual transaction control
+
+By default, the entire `execute` method runs inside a transaction in order to atomically commit database changes with the LMID update. Use `skip_auto_transaction` when you need to run code before or after the transaction:
+
+```ruby
+class PostUpdate < ApplicationMutation
+  skip_auto_transaction
+
+  argument :id, Types::ID
+  argument :post_input, Types::PostInput
+
+  def execute(id:, post_input:)
+    # 1. Pre-transaction (LMID incremented on error)
+    post = current_user.posts.find(id)
+    authorize! post, to: :update?
+
+    # 2. Transaction (Transaction rolled back, LMID incremented on error)
+    transact do
+      post.update!(**post_input)
+    end
+
+    # 3. Post-commit - only runs if transact succeeded
+    NotificationService.notify_update(id)
+  end
+end
+```
+
+With `skip_auto_transaction`, you **must** call `transact { }` or `TransactNotCalledError` is raised.
+
+### LMID behavior by phase
+
+| Phase | On Error |
+|-------|----------|
+| Pre-transaction | LMID advanced in separate transaction |
+| Transaction | LMID advanced in separate transaction (original tx rolled back) |
+| Post-commit | LMID already committed with transaction |
 
 ## References
 
 - [Zero Documentation](https://zero.rocicorp.dev/docs/mutators)
 - [Zero Server Implementation](https://github.com/rocicorp/mono/blob/main/packages/zero-server/src/process-mutations.ts)
-- Inspired by [graphql-ruby](https://github.com/rmosolgo/graphql-ruby)
+- [dry-types Documentation](https://dry-rb.org/gems/dry-types/)

data/lib/zero_ruby/configuration.rb

@@ -6,22 +6,17 @@ module ZeroRuby
   # @example
   #   ZeroRuby.configure do |config|
   #     config.lmid_store = :active_record
-  #     config.max_retry_attempts = 3
   #   end
   class Configuration
     # LMID (Last Mutation ID) tracking settings
     # The LMID store backend: :active_record or a custom LmidStore instance
     attr_accessor :lmid_store
 
-    # Maximum retry attempts for ApplicationError during mutation processing
-    attr_accessor :max_retry_attempts
-
     # The push version supported by this configuration
     attr_accessor :supported_push_version
 
     def initialize
       @lmid_store = :active_record
-      @max_retry_attempts = 3
       @supported_push_version = 1
     end
 

data/lib/zero_ruby/error_formatter.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "dry/schema"
+
+module ZeroRuby
+  # Formats Dry::Types and Dry::Struct errors into user-friendly messages
+  # using dry-schema's built-in message templates.
+  module ErrorFormatter
+    # Get the dry-schema messages backend for English
+    MESSAGES = Dry::Schema::Messages::YAML.build
+
+    class << self
+      # Format a Dry::Struct::Error into user-friendly messages
+      # @param error [Dry::Struct::Error] The struct error
+      # @return [Array<String>] Formatted error messages
+      def format_struct_error(error)
+        message = error.message
+
+        if message.include?("is missing")
+          match = message.match(/:(\w+) is missing/)
+          field = match ? match[1] : "field"
+          ["#{field} is required"]
+        elsif message.include?("has invalid type")
+          # Matches both ":title has invalid type" and "has invalid type for :title"
+          match = message.match(/:(\w+) has invalid type/) ||
+            message.match(/has invalid type for :(\w+)/)
+          field = match ? match[1] : "field"
+          ["#{field}: invalid type"]
+        elsif message.include?("violates constraints")
+          # Extract constraint info and format it
+          [format_constraint_message(message)]
+        else
+          [message]
+        end
+      end
+
+      # Format a Dry::Types::CoercionError into user-friendly message
+      # @param error [Dry::Types::CoercionError] The coercion error
+      # @return [String] Formatted error message
+      def format_coercion_error(error)
+        message = error.message
+        input = error.respond_to?(:input) ? error.input : nil
+
+        type = extract_type_name(message)
+        if input
+          value_str = format_value(input)
+          "#{value_str} is not a valid #{type}"
+        else
+          lookup_message(:type?, type) || "must be a #{type}"
+        end
+      end
+
+      # Format a Dry::Types::ConstraintError into user-friendly message
+      # @param error [Dry::Types::ConstraintError] The constraint error
+      # @return [String] Formatted error message
+      def format_constraint_error(error)
+        format_constraint_message(error.message)
+      end
+
+      private
+
+      # Format a constraint violation message
+      def format_constraint_message(message)
+        # Parse predicate and args from messages like:
+        # "max_size?(50, \"value\") failed" or "gt?(0, 0) failed"
+        if (match = message.match(/(\w+\?)\(([^)]*)\)/))
+          predicate = match[1]
+          args_str = match[2]
+          args = parse_args(args_str)
+
+          lookup_message(predicate, *args) || fallback_message(predicate, args)
+        else
+          message
+        end
+      end
+
+      # Look up a message from dry-schema's message templates
+      def lookup_message(predicate, *args)
+        # Convert predicate to symbol without ?
+        key = predicate.to_s.chomp("?").to_sym
+
+        # Try to get message from dry-schema
+        begin
+          result = MESSAGES.call(key, path: [:base], tokens: build_tokens(key, args))
+          result&.text
+        rescue
+          nil
+        end
+      end
+
+      # Build tokens hash for message interpolation
+      def build_tokens(key, args)
+        case key
+        when :max_size, :min_size, :size
+          {num: args[0]}
+        when :gt, :gteq, :lt, :lteq
+          {num: args[0]}
+        when :included_in, :excluded_from
+          {list: args[0]}
+        when :format
+          {format: args[0]}
+        else
+          {num: args[0]}
+        end
+      end
+
+      # Fallback messages when dry-schema lookup fails
+      def fallback_message(predicate, args)
+        case predicate
+        when "max_size?"
+          "size cannot be greater than #{args[0]}"
+        when "min_size?"
+          "size cannot be less than #{args[0]}"
+        when "gt?"
+          "must be greater than #{args[0]}"
+        when "gteq?"
+          "must be greater than or equal to #{args[0]}"
+        when "lt?"
+          "must be less than #{args[0]}"
+        when "lteq?"
+          "must be less than or equal to #{args[0]}"
+        when "included_in?"
+          "must be one of: #{args[0]}"
+        when "format?"
+          "is in invalid format"
+        when "filled?"
+          "must be filled"
+        else
+          "is invalid"
+        end
+      end
+
+      # Parse args from constraint error message
+      def parse_args(args_str)
+        # Simple parsing - split by comma and clean up
+        args_str.split(",").map do |arg|
+          arg = arg.strip
+          if arg.start_with?('"') && arg.end_with?('"')
+            arg[1..-2] # Remove quotes
+          elsif arg.match?(/^-?\d+$/)
+            arg.to_i
+          elsif arg.match?(/^-?\d+\.\d+$/)
+            arg.to_f
+          else
+            arg
+          end
+        end
+      end
+
+      # Extract type name from error message
+      def extract_type_name(message)
+        case message
+        when /Integer/ then "integer"
+        when /Float/ then "number"
+        when /String/ then "string"
+        when /Bool|TrueClass|FalseClass/ then "boolean"
+        when /Date/ then "date"
+        when /Array/ then "array"
+        when /Hash/ then "object"
+        else "value"
+        end
+      end
+
+      # Format a value for display in error messages
+      def format_value(value)
+        return "nil" if value.nil?
+
+        str = value.to_s
+        (str.length > 50) ? "#{str[0, 50]}..." : str
+      end
+    end
+  end
+end

data/lib/zero_ruby/errors.rb

@@ -90,7 +90,8 @@ module ZeroRuby
 
   # Raised for database transaction errors.
   # Triggers top-level PushFailed with reason: "database"
-  class DatabaseError < Error
+  # Wraps unexpected errors during transaction execution (matching TS behavior).
+  class TransactionError < Error
   end
 
   # Raised when push data is malformed or missing required fields.
@@ -102,4 +103,12 @@ module ZeroRuby
   # Wrapped as app error per Zero protocol (no "internal" error type at mutation level)
   class InternalError < Error
   end
+
+  # Raised when a mutation doesn't call the transact block.
+  # All mutations MUST call transact.call { ... } to wrap their database operations.
+  class TransactNotCalledError < Error
+    def initialize
+      super("Mutation must call transact block")
+    end
+  end
 end

data/lib/zero_ruby/input_object.rb

@@ -1,120 +1,82 @@
 # frozen_string_literal: true
 
-require_relative "argument"
-require_relative "errors"
-require_relative "validator"
+require "dry-struct"
+require_relative "types"
+require_relative "type_names"
 
 module ZeroRuby
   # Base class for input objects (nested argument types).
-  # Similar to GraphQL-Ruby's InputObject pattern.
+  # Uses Dry::Struct for type coercion and validation.
+  #
+  # Includes ZeroRuby::TypeNames for convenient type access via the Types module
+  # (e.g., Types::String, Types::ID, Types::Boolean).
   #
   # @example
   #   class Types::PostInput < ZeroRuby::InputObject
-  #     argument :id, ID, required: true
-  #     argument :title, String, required: true
-  #     argument :body, String, required: false
+  #     argument :id, Types::ID
+  #     argument :title, Types::String.constrained(min_size: 1, max_size: 200)
+  #     argument :body, Types::String.optional
+  #     argument :published, Types::Boolean.default(false)
   #   end
   #
   #   class PostCreate < ZeroRuby::Mutation
-  #     argument :post_input, Types::PostInput, required: true
-  #     argument :notify, Boolean, required: false
+  #     argument :post_input, Types::PostInput
+  #     argument :notify, Types::Boolean.default(false)
   #
-  #     def execute(post_input:, notify: nil)
-  #       Post.create!(**post_input)
+  #     def execute
+  #       # args[:post_input].title, args[:post_input].body, etc.
+  #       # Or use **args[:post_input] to splat into method calls
   #     end
   #   end
-  class InputObject
-    include TypeNames
+  class InputObject < Dry::Struct
+    include ZeroRuby::TypeNames
+
+    # Transform string keys to symbols (for JSON input)
+    transform_keys(&:to_sym)
+
+    # Use permissive schema that allows omitting optional attributes
+    # This matches the behavior where missing optional keys are omitted from result
+    schema schema.strict(false)
 
     class << self
-      # Declare an argument for this input object
-      def argument(name, type, required: true, validates: nil, default: Argument::NOT_PROVIDED, description: nil, **options)
-        arguments[name.to_sym] = Argument.new(
-          name: name,
-          type: type,
-          required: required,
-          validates: validates,
-          default: default,
-          description: description,
-          **options
-        )
-      end
+      # Alias attribute to argument for DSL compatibility
+      # @param name [Symbol] The argument name
+      # @param type [Dry::Types::Type] The type (from ZeroRuby::Types)
+      # @param description [String, nil] Optional description (stored for documentation, not passed to Dry::Struct)
+      def argument(name, type, description: nil, **_options)
+        # Store description for documentation/TypeScript generation
+        argument_descriptions[name.to_sym] = description if description
 
-      # Get all declared arguments (including inherited)
-      def arguments
-        @arguments ||= if superclass.respond_to?(:arguments)
-          superclass.arguments.dup
+        # Use attribute? for optional types (allows key to be omitted)
+        # Use attribute for required types (key must be present)
+        if optional_type?(type)
+          attribute?(name, type)
         else
-          {}
+          attribute(name, type)
         end
       end
 
-      # Coerce and validate raw input
-      # @param raw_args [Hash] Raw input
-      # @param ctx [Hash] The context hash
-      # @return [Hash] Validated and coerced hash (only includes keys present in input or with defaults)
-      # @raise [ZeroRuby::ValidationError] If validation fails
-      def coerce(value, ctx)
-        return nil if value.nil?
-        return nil unless value.is_a?(Hash)
-
-        validated = {}
-        errors = []
-
-        arguments.each do |name, arg|
-          key_present = value.key?(name) || value.key?(name.to_s)
-          val = if key_present
-            value[name].nil? ? value[name.to_s] : value[name]
-          end
-
-          # Check required
-          if arg.required? && !key_present && !arg.has_default?
-            errors << "#{name} is required"
-            next
-          end
-
-          # Apply default if key not present
-          if !key_present && arg.has_default?
-            validated[name] = arg.default
-            next
-          end
-
-          # Skip if key not present (don't add to validated hash)
-          next unless key_present
-
-          # Handle nil values - include in hash but skip coercion
-          if val.nil?
-            validated[name] = nil
-            next
-          end
-
-          # Type coercion (handles nested InputObjects)
-          begin
-            coerced = arg.coerce(val, ctx)
-          rescue CoercionError => e
-            errors << "#{name}: #{e.message}"
-            next
-          rescue ValidationError => e
-            # Nested InputObject validation errors - prefix with field name
-            e.errors.each do |err|
-              errors << "#{name}.#{err}"
-            end
-            next
-          end
+      # Get stored argument descriptions
+      def argument_descriptions
+        @argument_descriptions ||= {}
+      end
 
-          # Run validators
-          if arg.validators.any?
-            validation_errors = Validator.validate!(arg.validators, nil, ctx, coerced)
-            validation_errors.each do |err|
-              errors << "#{name} #{err}"
-            end
-          end
+      # Check if a type is optional (can accept nil or has a default)
+      def optional_type?(type)
+        return false unless type.respond_to?(:optional?)
+        type.optional? || (type.respond_to?(:default?) && type.default?)
+      end
 
-          validated[name] = coerced
+      # Returns argument metadata for TypeScript generation
+      # @return [Hash<Symbol, Hash>] Map of argument name to metadata
+      def arguments_metadata
+        schema.keys.each_with_object({}) do |key, hash|
+          hash[key.name] = {
+            type: key.type,
+            required: key.required?,
+            name: key.name
+          }
         end
-
-        raise ValidationError.new(errors) if errors.any?
-        validated
       end
     end
   end