apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/api/router.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module API
+    class Router
+      class << self
+        def draw
+          new.draw
+        end
+      end
+
+      def draw
+        api_classes = Registry.values
+        router = self
+
+        set = ActionDispatch::Routing::RouteSet.new
+
+        set.draw do
+          api_classes.each do |api_class|
+            next if api_class.base_path.blank? || api_class.root_resource.blank?
+
+            if api_class.export_configs.any?
+              scope path: api_class.transform_path(api_class.base_path) do
+                api_class.export_configs.each do |export_name, export_config|
+                  next unless case export_config.endpoint.mode
+                              when :always then true
+                              when :never then false
+                              when :auto then Rails.env.development?
+                              end
+
+                  get export_config.endpoint.path || "/.#{export_name}",
+                      defaults: { export_name:, api_base_path: api_class.base_path },
+                      to: 'apiwork/exports#show'
+                end
+              end
+            end
+
+            scope module: api_class.namespaces.map(&:to_s).join('/').underscore,
+                  path: api_class.transform_path(api_class.base_path) do
+              router.draw_resources(self, api_class.root_resource.resources, api_class)
+            end
+
+            scope path: api_class.transform_path(api_class.base_path) do
+              match '*unmatched', to: 'apiwork/errors#not_found', via: :all
+            end
+          end
+        end
+
+        set
+      end
+
+      def draw_resources(context, resources_hash, api_class)
+        resources_hash.each_value do |resource|
+          resource_method = resource.singular ? :resource : :resources
+          options = {
+            constraints: resource.constraints,
+            controller: resource.controller,
+            defaults: resource.defaults,
+            except: resource.except,
+            only: resource.only,
+            param: resource.param,
+          }.compact
+
+          path_option = api_class.transform_path(resource.path || resource.name)
+          options[:path] = path_option unless path_option == resource.name.to_s
+
+          router = self
+
+          context.instance_eval do
+            send(resource_method, resource.name, **options) do
+              if resource.member_actions.any?
+                member do
+                  resource.member_actions.each_value do |action|
+                    action_path = api_class.transform_path(action.name)
+                    if action_path == action.name.to_s
+                      send(action.method, action.name)
+                    else
+                      send(action.method, action.name, path: action_path)
+                    end
+                  end
+                end
+              end
+
+              if resource.collection_actions.any?
+                collection do
+                  resource.collection_actions.each_value do |action|
+                    action_path = api_class.transform_path(action.name)
+                    if action_path == action.name.to_s
+                      send(action.method, action.name)
+                    else
+                      send(action.method, action.name, path: action_path)
+                    end
+                  end
+                end
+              end
+
+              router.draw_resources(self, resource.resources, api_class)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/api/type_registry/definition.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module API
+    class TypeRegistry
+      class Definition
+        attr_reader :deprecated,
+                    :description,
+                    :discriminator,
+                    :example,
+                    :kind,
+                    :name,
+                    :scope
+
+        def initialize(
+          name,
+          kind:,
+          scope: nil,
+          block: nil,
+          deprecated: false,
+          description: nil,
+          discriminator: nil,
+          example: nil,
+          fragment: false
+        )
+          @name = name
+          @kind = kind
+          @scope = scope
+          @block = block
+          @deprecated = deprecated
+          @description = description
+          @discriminator = discriminator
+          @example = example
+          @fragment = fragment
+          @shape = nil
+        end
+
+        def deprecated?
+          @deprecated == true
+        end
+
+        def fragment?
+          @fragment == true
+        end
+
+        def object?
+          @kind == :object
+        end
+
+        def union?
+          @kind == :union
+        end
+
+        def shape
+          ensure_shape_built!
+          @shape
+        end
+
+        def params
+          shape.params if object?
+        end
+
+        def variants
+          shape.variants if union?
+        end
+
+        def merge(block:, deprecated:, description:, example:)
+          Definition.new(
+            @name,
+            block: merge_blocks(@block, block),
+            deprecated: deprecated || @deprecated,
+            description: description || @description,
+            discriminator: @discriminator,
+            example: example || @example,
+            fragment: @fragment,
+            kind: @kind,
+            scope: @scope,
+          )
+        end
+
+        private
+
+        def merge_blocks(existing_block, new_block)
+          return existing_block unless new_block
+          return new_block unless existing_block
+
+          proc do |shape|
+            if existing_block.arity.positive?
+              existing_block.call(shape)
+            else
+              shape.instance_eval(&existing_block)
+            end
+            if new_block.arity.positive?
+              new_block.call(shape)
+            else
+              shape.instance_eval(&new_block)
+            end
+          end
+        end
+
+        def ensure_shape_built!
+          return if @shape
+
+          @shape = if object?
+                     Object.new
+                   else
+                     Union.new(discriminator: @discriminator)
+                   end
+
+          return unless @block
+
+          @block.arity.positive? ? @block.call(@shape) : @shape.instance_eval(&@block)
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/api/type_registry.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module API
+    class TypeRegistry
+      def initialize
+        @store = {}
+      end
+
+      def register(
+        name,
+        kind:,
+        scope: nil,
+        deprecated: false,
+        description: nil,
+        discriminator: nil,
+        example: nil,
+        fragment: false,
+        &block
+      )
+        key = scoped_name(scope, name)
+
+        if @store.key?(key)
+          validate_kind_consistency!(key, kind)
+          merge(key, block:, deprecated:, description:, example:)
+        else
+          @store[key] = Definition.new(
+            key,
+            block:,
+            deprecated:,
+            description:,
+            discriminator:,
+            example:,
+            fragment:,
+            kind:,
+            scope:,
+          )
+        end
+      end
+
+      def [](name)
+        @store[name]
+      end
+
+      def key?(name)
+        @store.key?(name)
+      end
+
+      def each_pair(&block)
+        @store.each_pair(&block)
+      end
+
+      def exists?(name, scope: nil)
+        find(name, scope:).present?
+      end
+
+      def find(name, scope: nil)
+        definition = scope ? @store[scoped_name(scope, name)] : nil
+        definition || @store[name]
+      end
+
+      def scoped_name(scope, name)
+        return name unless scope
+
+        prefix = scope.respond_to?(:scope_prefix) ? scope.scope_prefix : nil
+        return name unless prefix
+        return prefix.to_sym if name.nil?
+        return prefix.to_sym if name.to_s.empty?
+        return name.to_sym if name.to_s == prefix
+
+        [prefix, name].join('_').to_sym
+      end
+
+      def clear!
+        @store.clear
+      end
+
+      private
+
+      def validate_kind_consistency!(key, new_kind)
+        definition = @store[key]
+        return if definition.kind == new_kind
+
+        raise ConfigurationError,
+              "Cannot redefine :#{key} as #{new_kind}, already defined as #{definition.kind}"
+      end
+
+      def merge(key, block:, deprecated:, description:, example:)
+        definition = @store[key]
+        @store[key] = definition.merge(
+          block:,
+          deprecated:,
+          description:,
+          example:,
+        )
+      end
+    end
+  end
+end

data/lib/apiwork/api/union.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module API
+    # @api public
+    # Block context for defining reusable union types.
+    #
+    # Accessed via `union :name do` in API or contract definitions.
+    # Use {#variant} to define possible types.
+    #
+    # @see API::Element Block context for variant types
+    # @see Contract::Union Block context for inline unions
+    #
+    # @example instance_eval style
+    #   union :payment_method, discriminator: :type do
+    #     variant tag: 'card' do
+    #       object do
+    #         string :last_four
+    #       end
+    #     end
+    #     variant tag: 'bank' do
+    #       object do
+    #         string :account_number
+    #       end
+    #     end
+    #   end
+    #
+    # @example yield style
+    #   union :payment_method, discriminator: :type do |union|
+    #     union.variant tag: 'card' do |variant|
+    #       variant.object do |object|
+    #         object.string :last_four
+    #       end
+    #     end
+    #     union.variant tag: 'bank' do |variant|
+    #       variant.object do |object|
+    #         object.string :account_number
+    #       end
+    #     end
+    #   end
+    class Union < Apiwork::Union
+      private
+
+      def build_element
+        Element.new
+      end
+    end
+  end
+end

data/lib/apiwork/api.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Apiwork
+  # @api public
+  module API
+    class << self
+      # @!method find(base_path)
+      #   @api public
+      #   Finds an API by base path.
+      #   @param base_path [String]
+      #     The API base path.
+      #   @return [Class<API::Base>, nil]
+      #   @see .find!
+      #   @example
+      #     Apiwork::API.find('/api/v1')
+      #
+      # @!method find!(base_path)
+      #   @api public
+      #   Finds an API by base path.
+      #   @param base_path [String]
+      #     The API base path.
+      #   @return [Class<API::Base>]
+      #   @raise [KeyError] if the API is not found
+      #   @see .find
+      #   @example
+      #     Apiwork::API.find!('/api/v1')
+      delegate :clear!,
+               :exists?,
+               :find,
+               :find!,
+               :keys,
+               :unregister,
+               :values,
+               to: Registry
+
+      # @api public
+      # Defines a new API at the given base path.
+      #
+      # This is the main entry point for creating an Apiwork API.
+      # The block receives an API recorder for defining resources,
+      # types, and configuration.
+      #
+      # @param base_path [String]
+      #   The API base path.
+      # @yield block for API definition
+      # @return [Class<API::Base>]
+      #
+      # @example Basic API
+      #   Apiwork::API.define '/api/v1' do
+      #     resources :users
+      #     resources :posts
+      #   end
+      #
+      # @example With configuration
+      #   Apiwork::API.define '/api/v1' do
+      #     key_format :camel
+      #
+      #     resources :invoices
+      #   end
+      def define(base_path, &block)
+        return unless block
+
+        Class.new(Base).tap do |klass|
+          klass.mount(base_path)
+          klass.class_eval(&block)
+        end
+      end
+
+      # @api public
+      # The introspection data for an API.
+      #
+      # @param base_path [String]
+      #   The API base path.
+      # @param locale [Symbol, nil] (nil)
+      #   The locale for descriptions.
+      # @return [Introspection::API]
+      #
+      # @example
+      #   Apiwork::API.introspect('/api/v1')
+      def introspect(base_path, locale: nil)
+        find!(base_path).introspect(locale:)
+      end
+    end
+  end
+end

data/lib/apiwork/configurable.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Configurable
+    extend ActiveSupport::Concern
+
+    class << self
+      def define(extends: nil, &block)
+        Class.new do
+          include Configurable
+
+          self.options = extends.options.dup if extends
+
+          class_eval(&block) if block
+        end
+      end
+    end
+
+    included do
+      class_attribute :options, default: {}, instance_predicate: false
+    end
+
+    # @!method option(name, type:, default: nil, enum: nil, &block)
+    #   @!scope class
+    #   @api public
+    #   Defines a configuration option.
+    #
+    #   For nested options, use `type: :hash` with a block. Inside the block,
+    #   call `option` to define child options.
+    #
+    #   @param name [Symbol]
+    #     The option name.
+    #   @param type [Symbol] [:boolean, :hash, :integer, :string, :symbol]
+    #     The option type.
+    #   @param default [Object, nil] (nil)
+    #     The default value.
+    #   @param enum [Array, nil] (nil)
+    #     The allowed values.
+    #   @yield block evaluated in {Configuration::Option} context (for :hash type)
+    #   @return [void]
+    #   @see Configuration::Option
+    #
+    #   @example Symbol option
+    #     option :locale, type: :symbol, default: :en
+    #
+    #   @example String option with enum
+    #     option :version, type: :string, default: '5', enum: %w[4 5]
+    #
+    #   @example Nested options
+    #     option :pagination, type: :hash do
+    #       option :strategy, type: :symbol, default: :offset, enum: %i[offset cursor]
+    #       option :default_size, type: :integer, default: 20
+    #       option :max_size, type: :integer, default: 100
+    #     end
+
+    class_methods do
+      def inherited(subclass)
+        super
+        subclass.options = options.dup
+      end
+
+      def option(name, default: nil, enum: nil, type:, &block)
+        options[name] = Configuration::Option.new(name, type, default:, enum:, &block)
+      end
+
+      def default_options
+        options.transform_values(&:effective_default).compact
+      end
+    end
+  end
+end

data/lib/apiwork/configuration/option.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class Configuration
+    # @api public
+    # Block context for nested configuration options.
+    #
+    # Used inside `option :name, type: :hash do ... end` blocks
+    # in {Adapter::Base} and {Export::Base} subclasses.
+    #
+    # @see Adapter::Base
+    # @see Export::Base
+    # @see Configuration
+    #
+    # @example instance_eval style
+    #   option :pagination, type: :hash do
+    #     option :strategy, type: :symbol, default: :offset
+    #     option :default_size, type: :integer, default: 20
+    #   end
+    #
+    # @example yield style
+    #   option :pagination, type: :hash do |option|
+    #     option.option :strategy, type: :symbol, default: :offset
+    #     option.option :default_size, type: :integer, default: 20
+    #   end
+    class Option
+      include Validatable
+
+      attr_reader :children,
+                  :default,
+                  :enum,
+                  :name,
+                  :type
+
+      def initialize(name, type, children: nil, default: nil, enum: nil, &block)
+        @name = name
+        @type = type
+        @default = default
+        @enum = enum
+        @children = children || {}
+
+        return unless block && type == :hash
+
+        block.arity.positive? ? yield(self) : instance_eval(&block)
+      end
+
+      # @api public
+      # Defines a nested option.
+      #
+      # @param name [Symbol]
+      #   The option name.
+      # @param default [Object, nil] (nil)
+      #   The default value.
+      # @param enum [Array, nil] (nil)
+      #   The allowed values.
+      # @param type [Symbol] [:boolean, :hash, :integer, :string, :symbol]
+      #   The option type.
+      # @yield block for nested options (type: :hash)
+      # @yieldparam option [Option]
+      # @return [void]
+      #
+      # @example instance_eval style
+      #   option :pagination, type: :hash do
+      #     option :strategy, type: :symbol, default: :offset
+      #     option :default_size, type: :integer, default: 20
+      #   end
+      #
+      # @example yield style
+      #   option :pagination, type: :hash do |option|
+      #     option.option :strategy, type: :symbol, default: :offset
+      #     option.option :default_size, type: :integer, default: 20
+      #   end
+      def option(name, default: nil, enum: nil, type:, &block)
+        @children[name] = Option.new(name, type, default:, enum:, &block)
+      end
+
+      def nested?
+        children.any?
+      end
+
+      def effective_default
+        return default unless nested?
+
+        children.transform_values(&:default)
+      end
+
+      def validate!(value)
+        return if value.nil?
+
+        if nested?
+          raise ConfigurationError, "#{name} must be a Hash" unless value.is_a?(Hash)
+
+          validate_children!(value)
+        else
+          validate_type!(value)
+          validate_enum!(value) if enum
+        end
+      end
+
+      def cast(value)
+        return nil if value.nil?
+        return value unless value.is_a?(String)
+
+        case type
+        when :symbol then value.to_sym
+        when :string then value
+        when :integer then value.to_i
+        when :boolean then %w[true 1 yes].include?(value.downcase)
+        when :hash then value
+        end
+      end
+
+      private
+
+      def validate_children!(hash)
+        hash.each do |key, value|
+          child = children[key]
+          raise ConfigurationError, "Unknown option: #{name}.#{key}" unless child
+
+          child.validate!(value)
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/configuration/validatable.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class Configuration
+    module Validatable
+      private
+
+      def validate_type!(value)
+        valid = case type
+                when :symbol then value.is_a?(Symbol)
+                when :string then value.is_a?(String)
+                when :integer then value.is_a?(Integer)
+                when :hash then value.is_a?(Hash)
+                end
+        raise ConfigurationError, "#{name} must be #{type}, got #{value.class}" unless valid
+      end
+
+      def validate_enum!(value)
+        return if enum.include?(value)
+
+        raise ConfigurationError, "#{name} must be one of #{enum.inspect}, got #{value.inspect}"
+      end
+    end
+  end
+end