zodra 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3b3bb353dba60ee571c044f3a579258434d3d5109edc06d1ad616f83aba8a49a
+  data.tar.gz: 10f13e687eb9c91f14d4967729e06fce1c55a1d1bf782fb5fc9c5f2701de528f
+SHA512:
+  metadata.gz: c9ef51b11dc4445fd9e257d941f2c443b4c61169b1658e29ebfccfe244874c9975d8180f997b6f107139768c28a5bf4cc12c91ba42b7a394ea5810bc0e5973e0
+  data.tar.gz: 0f8ba993a332ecc464f5fa50722a6ec39eab04634616ec93709a5dd490b1aedb03776d1dd047b2250c980d61db28bb865362569c8192e9e08bba0a93a6684bd3

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 (2026-03-11)
+
+Initial release.
+
+- Type DSL: objects, enums, unions with attributes (optional, nullable, defaults, constraints, enum)
+- Type composition: `from:`, `pick:`, `omit:`, `partial:`
+- Contracts: params and response definitions per action
+- Resource routing: `Zodra.api` with nested resources and custom actions
+- Params validation: strict by default, coercion, constraints
+- Response serialization: `{ data: ... }` / `{ data: [...], meta: ... }` envelope
+- Controller mixin: `zodra_params`, `zodra_respond`, error handling
+- TypeScript export: interfaces from type definitions
+- Zod export: schemas with constraints (min, max, enum)
+- Auto-generated header in exported files
+- Rails integration: Railtie, rake tasks, Zeitwerk

data/lib/generators/zodra/install_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Zodra
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('templates', __dir__)
+
+    desc 'Creates a Zodra initializer and types directory'
+
+    def create_initializer
+      template 'initializer.rb.tt', 'config/initializers/zodra.rb'
+    end
+
+    def create_types_directory
+      empty_directory 'app/types'
+      create_file 'app/types/.keep'
+    end
+  end
+end

data/lib/generators/zodra/templates/initializer.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+Zodra.configure do |config|
+  # Directory where generated TypeScript/Zod files are written.
+  # config.output_path = "app/javascript/types"
+
+  # Key format for exported properties: :camel, :pascal, or :keep.
+  # config.key_format = :camel
+
+  # Zod import path used in generated schemas.
+  # config.zod_import = "zod"
+end

data/lib/zodra/action.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Zodra
+  class Action
+    attr_reader :name, :params, :contract, :response_definition, :errors
+
+    attr_accessor :http_method, :path, :response_type
+
+    def initialize(name:, contract: nil)
+      @name = name
+      @contract = contract
+      @params = Definition.new(name: :"#{name}_params", kind: :object)
+      @response_definition = Definition.new(name: :"#{name}_response", kind: :object)
+      @response_type = nil
+      @collection = false
+      @errors = {}
+    end
+
+    def add_error(code, status:)
+      @errors[code.to_sym] = { code: code.to_sym, status: status }
+    end
+
+    def find_error(code)
+      @errors[code.to_sym]
+    end
+
+    def collection?
+      @collection
+    end
+
+    def collection!
+      @collection = true
+    end
+
+    def response_schema
+      if response_type
+        contract&.resolve_type(response_type) || TypeRegistry.global.find!(response_type)
+      else
+        response_definition
+      end
+    end
+  end
+end

data/lib/zodra/action_builder.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Zodra
+  class ActionBuilder
+    def initialize(action)
+      @action = action
+    end
+
+    def params(from: nil, pick: nil, omit: nil, partial: false, &block)
+      if from
+        source = resolve_type(from)
+        TypeDeriver.new(source, pick:, omit:, partial:).apply(@action.params)
+      end
+
+      TypeBuilder.new(@action.params).instance_eval(&block) if block
+    end
+
+    def response(type_name = nil, collection: false, &block)
+      @action.collection! if collection
+
+      if block
+        TypeBuilder.new(@action.response_definition).instance_eval(&block)
+      elsif type_name
+        @action.response_type = type_name.to_sym
+      end
+    end
+
+    def error(code, status:)
+      @action.add_error(code, status:)
+    end
+
+    private
+
+    def resolve_type(name)
+      @action.contract&.resolve_type(name) || TypeRegistry.global.find!(name)
+    end
+  end
+end

data/lib/zodra/api_builder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Zodra
+  class ApiBuilder
+    def initialize(api_definition)
+      @api_definition = api_definition
+    end
+
+    def resources(name, contract: nil, controller: nil, only: nil, except: nil, &block)
+      resource = Resource.new(name:, singular: false, contract:, controller:, only:, except:)
+      ResourceBuilder.new(resource).instance_eval(&block) if block
+      @api_definition.add_resource(resource)
+      resource
+    end
+
+    def resource(name, contract: nil, controller: nil, only: nil, except: nil, &block)
+      resource = Resource.new(name:, singular: true, contract:, controller:, only:, except:)
+      ResourceBuilder.new(resource).instance_eval(&block) if block
+      @api_definition.add_resource(resource)
+      resource
+    end
+  end
+end

data/lib/zodra/api_definition.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Zodra
+  class ApiDefinition
+    attr_reader :base_path, :resources
+
+    def initialize(base_path:)
+      @base_path = base_path
+      @resources = []
+    end
+
+    def add_resource(resource)
+      @resources << resource
+    end
+
+    def namespaces
+      @base_path.split('/').reject(&:empty?).map(&:to_sym)
+    end
+
+    def controller_namespace
+      namespaces.join('/')
+    end
+  end
+end

data/lib/zodra/api_registry.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Zodra
+  class ApiRegistry
+    include Enumerable
+
+    def self.global
+      @global ||= new
+    end
+
+    def initialize
+      @store = {}
+    end
+
+    def register(base_path)
+      raise DuplicateTypeError, "API '#{base_path}' is already registered" if @store.key?(base_path)
+
+      @store[base_path] = ApiDefinition.new(base_path:)
+    end
+
+    def find(base_path)
+      @store[base_path]
+    end
+
+    def each(&)
+      @store.each_value(&)
+    end
+
+    def clear!
+      @store.clear
+    end
+  end
+end

data/lib/zodra/attribute.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Zodra
+  class Attribute
+    attr_reader :name, :type, :format, :default, :min, :max, :enum, :of, :reference_name
+
+    def initialize(name:, type:, optional: false, nullable: false, format: nil,
+                   default: nil, min: nil, max: nil, enum: nil, of: nil, reference_name: nil)
+      @name = name.to_sym
+      @type = type.to_sym
+      @optional = optional
+      @nullable = nullable
+      @format = format
+      @default = default
+      @min = min
+      @max = max
+      @enum = enum
+      @of = of
+      @reference_name = reference_name
+    end
+
+    def optional?
+      @optional
+    end
+
+    def nullable?
+      @nullable
+    end
+
+    def reference?
+      type == :reference
+    end
+
+    def array?
+      type == :array
+    end
+
+    def dependency_name
+      if reference?
+        reference_name.to_sym
+      elsif array? && of
+        of.to_sym
+      end
+    end
+  end
+end

data/lib/zodra/configuration.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Zodra
+  class Configuration
+    DEFAULTS = {
+      output_path: 'app/javascript/types',
+      key_format: :camel,
+      zod_import: 'zod',
+      strict_params: true
+    }.freeze
+
+    attr_accessor :output_path, :key_format, :zod_import, :strict_params
+
+    def initialize
+      DEFAULTS.each { |key, value| public_send(:"#{key}=", value) }
+    end
+  end
+end

data/lib/zodra/contract.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Zodra
+  class Contract
+    attr_reader :name, :actions, :types
+
+    def initialize(name:)
+      @name = name
+      @actions = {}
+      @types = TypeRegistry.new
+    end
+
+    def add_action(action_name)
+      action = Action.new(name: action_name, contract: self)
+      @actions[action_name.to_sym] = action
+      action
+    end
+
+    def find_action(action_name)
+      @actions[action_name.to_sym]
+    end
+
+    def resolve_type(type_name)
+      types.find(type_name) || TypeRegistry.global.find!(type_name)
+    end
+
+    alias find! resolve_type
+
+    def find(type_name)
+      types.find(type_name) || TypeRegistry.global.find(type_name)
+    end
+  end
+end

data/lib/zodra/contract_builder.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Zodra
+  class ContractBuilder
+    def initialize(contract)
+      @contract = contract
+    end
+
+    def action(name, &block)
+      action = @contract.add_action(name)
+      ActionBuilder.new(action).instance_eval(&block) if block
+      action
+    end
+
+    def type(name, from: nil, pick: nil, omit: nil, partial: false, &block)
+      definition = @contract.types.register(name, kind: :object)
+
+      if from
+        source = @contract.resolve_type(from) || TypeRegistry.global.find!(from)
+        TypeDeriver.new(source, pick:, omit:, partial:).apply(definition)
+      end
+
+      TypeBuilder.new(definition).instance_eval(&block) if block
+      definition
+    end
+
+    def enum(name, values:)
+      @contract.types.register(name, kind: :enum, values:)
+    end
+
+    def union(name, discriminator:, &block)
+      definition = @contract.types.register(name, kind: :union, discriminator:)
+      UnionBuilder.new(definition).instance_eval(&block) if block
+      definition
+    end
+  end
+end

data/lib/zodra/contract_registry.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Zodra
+  class ContractRegistry
+    include Enumerable
+
+    def self.global
+      @global ||= new
+    end
+
+    def initialize
+      @store = {}
+    end
+
+    def register(name)
+      name = name.to_sym
+      raise DuplicateTypeError, "Contract :#{name} is already registered" if @store.key?(name)
+
+      @store[name] = Contract.new(name:)
+    end
+
+    def find(name)
+      @store[name.to_sym]
+    end
+
+    def find!(name)
+      @store.fetch(name.to_sym) { raise KeyError, "Contract :#{name} is not registered" }
+    end
+
+    def exists?(name)
+      @store.key?(name.to_sym)
+    end
+
+    def each(&)
+      @store.each_value(&)
+    end
+
+    def clear!
+      @store.clear
+    end
+  end
+end

data/lib/zodra/controller.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Zodra
+  module Controller
+    extend ActiveSupport::Concern
+
+    RAILS_INTERNAL_KEYS = %w[controller action format].freeze
+
+    included do
+      wrap_parameters false
+
+      rescue_from Zodra::ParamsError do |error|
+        render json: { errors: transform_error_keys(error.errors) }, status: :unprocessable_entity
+      end
+    end
+
+    class_methods do
+      def zodra_contract(name)
+        @zodra_contract_name = name.to_sym
+      end
+
+      def zodra_contract_name
+        @zodra_contract_name
+      end
+
+      def zodra_rescue(action_name, exception_class, as:)
+        @zodra_rescue_mappings ||= []
+        @zodra_rescue_mappings << { action_name: action_name.to_sym, exception_class:, code: as.to_sym }
+
+        rescue_from exception_class do |exception|
+          handle_zodra_business_error(exception)
+        end
+      end
+
+      def zodra_rescue_mappings
+        @zodra_rescue_mappings || []
+      end
+    end
+
+    private
+
+    def zodra_params
+      @zodra_params ||= begin
+        raw = request.parameters.except(*RAILS_INTERNAL_KEYS)
+        result = ParamsParser.call(raw, schema: zodra_action.params)
+        raise ParamsError, result.errors unless result.valid?
+
+        result.params
+      end
+    end
+
+    def zodra_respond(object, status: :ok)
+      schema = zodra_action.response_schema
+      serialized = serialize_response(object, schema)
+      render json: { data: serialized }, status:
+    end
+
+    def zodra_respond_collection(objects, status: :ok, meta: nil)
+      schema = zodra_action.response_schema
+      serialized = objects.map { |object| serialize_response(object, schema) }
+
+      response_body = { data: serialized }
+      response_body[:meta] = meta if meta
+      render json: response_body, status:
+    end
+
+    def zodra_errors(errors, status: :unprocessable_entity)
+      normalized = normalize_errors(errors)
+      validate_error_keys!(normalized)
+      render json: { errors: transform_error_keys(normalized) }, status:
+    end
+
+    def zodra_action
+      @zodra_action ||= zodra_contract.find_action(action_name) ||
+                        raise(Zodra::Error,
+                              "Action :#{action_name} not found in contract :#{self.class.zodra_contract_name}")
+    end
+
+    def zodra_contract
+      @zodra_contract ||= ContractRegistry.global.find!(self.class.zodra_contract_name)
+    end
+
+    def serialize_response(object, schema)
+      key_format = Zodra.configuration.key_format
+      ResponseSerializer.call(object, schema, key_format:, type_resolver: zodra_contract)
+    end
+
+    def handle_zodra_business_error(exception)
+      mapping = self.class.zodra_rescue_mappings.find do |m|
+        m[:action_name] == action_name.to_sym && exception.is_a?(m[:exception_class])
+      end
+
+      raise exception unless mapping
+
+      error_definition = zodra_action.find_error(mapping[:code])
+      status = error_definition ? error_definition[:status] : :internal_server_error
+
+      render json: { error: { code: mapping[:code].to_s, message: exception.message } }, status:
+    end
+
+    def normalize_errors(errors)
+      if errors.respond_to?(:to_hash)
+        errors.to_hash
+      elsif errors.respond_to?(:messages)
+        errors.messages
+      else
+        errors
+      end
+    end
+
+    def validate_error_keys!(errors)
+      return unless valid_error_keys_for_action
+
+      unknown_keys = errors.keys.map(&:to_sym) - valid_error_keys_for_action
+      return if unknown_keys.empty?
+
+      message = "Unknown error keys #{unknown_keys.inspect} for action :#{action_name}. " \
+                "Valid keys: #{valid_error_keys_for_action.inspect}"
+
+      raise Zodra::Error, message if defined?(Rails) && !Rails.env.production?
+
+      Zodra.logger&.warn("[Zodra] #{message}")
+    end
+
+    def valid_error_keys_for_action
+      return @valid_error_keys_for_action if defined?(@valid_error_keys_for_action)
+
+      param_keys = zodra_action.params.attributes.keys
+      @valid_error_keys_for_action = param_keys.empty? ? nil : param_keys + [:base]
+    end
+
+    def transform_error_keys(errors)
+      key_format = Zodra.configuration.key_format
+      return errors if key_format == :keep
+
+      errors.transform_keys { |key| ResponseSerializer.send(:transform_key, key, key_format) }
+    end
+  end
+end

data/lib/zodra/definition.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Zodra
+  class Definition
+    attr_reader :name, :kind, :discriminator, :values, :attributes, :variants
+
+    def initialize(name:, kind:, discriminator: nil, values: nil)
+      @name = name
+      @kind = kind
+      @discriminator = discriminator
+      @values = values
+      @attributes = {}
+      @variants = []
+    end
+
+    def object?
+      kind == :object
+    end
+
+    def enum?
+      kind == :enum
+    end
+
+    def union?
+      kind == :union
+    end
+
+    def add_attribute(attribute_name, **)
+      @attributes[attribute_name.to_sym] = Attribute.new(name: attribute_name, **)
+    end
+
+    def add_variant(tag, attributes: {})
+      @variants << Variant.new(tag:, attributes:)
+    end
+  end
+end

data/lib/zodra/export/contract_mapper.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Zodra
+  module Export
+    class ContractMapper
+      def initialize(api_definitions, contracts)
+        @api_definitions = api_definitions
+        @contracts = contracts
+      end
+
+      def generate
+        return '' if @contracts.empty?
+
+        parts = []
+        parts << build_import
+        parts << build_contracts_map
+        parts << build_base_url if @api_definitions.any?
+        parts.join("\n\n")
+      end
+
+      private
+
+      def build_import
+        schema_names = contract_names.map { |name| "#{pascal_case(name)}Contract" }
+        "import { #{schema_names.join(', ')} } from './schemas';"
+      end
+
+      def build_contracts_map
+        entries = contract_names.map do |name|
+          "  #{camel_case(name)}: #{pascal_case(name)}Contract"
+        end
+
+        "export const contracts = {\n#{entries.join(",\n")},\n} as const;"
+      end
+
+      def build_base_url
+        base_path = @api_definitions.first.base_path
+        "export const baseUrl = '#{base_path}';"
+      end
+
+      def contract_names
+        @contract_names ||= resolve_contract_names
+      end
+
+      def resolve_contract_names
+        if @api_definitions.any?
+          collect_resource_names(@api_definitions)
+        else
+          @contracts.map(&:name).map(&:to_s)
+        end
+      end
+
+      def collect_resource_names(api_definitions)
+        names = []
+        api_definitions.each do |api|
+          api.resources.each { |resource| collect_names_recursive(resource, names) }
+        end
+        names
+      end
+
+      def collect_names_recursive(resource, names)
+        names << resource.contract_name.to_s
+        resource.children.each { |child| collect_names_recursive(child, names) }
+      end
+
+      def pascal_case(name)
+        name.to_s.split('_').map(&:capitalize).join
+      end
+
+      def camel_case(name)
+        parts = name.to_s.split('_')
+        parts.first + parts[1..].map(&:capitalize).join
+      end
+    end
+  end
+end