zero_ruby 0.1.0.alpha1 → 0.1.0.alpha4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba93bb14b442ea97c4ac597b0c97e7b9e0ec00a334e5f2fd6bb3ee7639d47302
-  data.tar.gz: 741f8f22deb20a49cf7ffd75a03657faf28d561ad32a03debb74f4f5b4e41de8
+  metadata.gz: 8d78f7995f5a44093ed0202e53dd345587f73a2d2a675e31c158fe01ed392e6e
+  data.tar.gz: 9fbbb4cdce370fca8c035e0fad0cd0dbbeaa9ace5cf92061cdab6274223987ae
 SHA512:
-  metadata.gz: bab7af54647503b8322eef911336dd9abfe952eaa574baa7f61da57e72e234754a03287354f24af6022b15731097c43a51b5ba67ecb441d0dcc148de834b7b2d
-  data.tar.gz: 9a4015f062da3df3cdfbc32fc00f747046dee0a30d03228995b59049b9ce2a44c0df10836db173f906ceb8aebd76d935a116576d74848187c88470b7aeb3c4bd
+  metadata.gz: 6b4e963190e7911e4b9b137933165bd20eebabf2e9a183f9ae7404e0f3ab6b00c2f321098fdf58aaf2ab84fbca7490e1e82b47bb5ed2e3616aa10151173ba2ba
+  data.tar.gz: 35b53c46c18655067e7e393893539fa451baf956a3f3a827cd9edfd340e33b29eb55ef9327297ae279a3604717244f3d04cf5ddb2bba5f28308b200c6f724b19

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,58 +19,27 @@ gem 'zero_ruby'
 
 ## Usage
 
-### 1. 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
-```
-
-### 2. 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
-  end
-end
-```
+### 1. Define mutations
 
-### 3. 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, 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
 end
 ```
 
-### 4. Register mutations in schema
+### 2. Register mutations in schema
 
 ```ruby
 # app/zero/app_schema.rb
@@ -85,7 +51,7 @@ class ZeroSchema < ZeroRuby::Schema
 end
 ```
 
-### 5. Add controller
+### 3. Add zero_controller and route
 
 ```ruby
 # app/controllers/zero_controller.rb
@@ -112,23 +78,34 @@ class ZeroController < ApplicationController
     end
   rescue JSON::ParserError => e
     render json: {
-      error: {
-        kind: "PushFailed",
-        reason: "Parse",
-        message: "Invalid JSON: #{e.message}"
-      }
+      kind: "PushFailed",
+      origin: "server",
+      reason: "parse",
+      message: "Invalid JSON: #{e.message}",
+      mutationIDs: []
     }, status: :bad_request
   end
 end
 ```
 
-### 6. Add route
-
 ```ruby
 # config/routes.rb
 match '/zero/push', to: 'zero#push', via: [:get, :post]
 ```
 
+## Define custom input types (optional)
+
+```ruby
+# app/zero/types/post_input.rb
+module Types
+  class PostInput < Types::BaseInputObject
+    argument :title, Types::String.constrained(min_size: 1, max_size: 200)
+    argument :body, Types::String.optional
+    argument :published, Boolean.default(false)
+  end
+end
+```
+
 ## Configuration
 
 Create an initializer to customize settings (all options have sensible defaults):
@@ -139,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
@@ -165,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'
@@ -179,7 +156,7 @@ export const mutators = defineMutators({
     update: defineMutator(postsUpdateArgsSchema, async ({ tx, args }) => {
       await tx.mutate.posts.update({
         id: args.id,
-        ...(args.postInput.title !== undefined && { title: args.postInput.title }),
+        title: args.postInput.title,
         updatedAt: Date.now(),
       })
     }),
@@ -189,57 +166,131 @@ 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`, the following are available:
 
-Built-in validators:
+- **Direct constants**: `ID`, `Boolean`, `ISO8601Date`, `ISO8601DateTime`
+- **Via Types module**: `Types::String`, `Types::Integer`, `Types::Float`
+
+(Note: `String`, `Integer`, `Float` can't be direct constants because they conflict with Ruby's built-in classes)
 
 ```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, Boolean
+argument :id, ID                    # Non-empty string
+argument :date, ISO8601Date
+argument :timestamp, ISO8601DateTime
+
+# Optional types (accepts nil)
+argument :nickname, Types::String.optional
+
+# Default values
+argument :status, Types::String.default("draft")
+argument :enabled, 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` |
 
-Types automatically coerce compatible values and raise `CoercionError` for invalid input:
+## Type coercion
+
+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, 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,171 @@
+# 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")
+          match = message.match(/:(\w+) has invalid type/)
+          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 StandardError
+          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

@@ -87,4 +87,28 @@ module ZeroRuby
       "ooo"
     end
   end
+
+  # Raised for database transaction errors.
+  # Triggers top-level PushFailed with reason: "database"
+  # Wraps unexpected errors during transaction execution (matching TS behavior).
+  class DatabaseTransactionError < Error
+  end
+
+  # Raised when push data is malformed or missing required fields.
+  # Triggers top-level PushFailed with reason: "parse"
+  class ParseError < Error
+  end
+
+  # Raised for unexpected internal server errors.
+  # 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