apiwork 0.0.0.pre → 0.1.2

data/lib/apiwork/element.rb

@@ -0,0 +1,386 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class Element
+    # @!attribute [r] custom_type
+    #   @api public
+    #   The custom type name for this element.
+    #
+    #   @return [Symbol, nil]
+    # @!attribute [r] discriminator
+    #   @api public
+    #   The discriminator for this element.
+    #
+    #   @return [Symbol, nil]
+    # @!attribute [r] enum
+    #   @api public
+    #   The allowed values for this element.
+    #
+    #   @return [Array, Symbol, nil]
+    # @!attribute [r] format
+    #   @api public
+    #   The format hint for this element.
+    #
+    #   @return [Symbol, nil]
+    # @!attribute [r] inner
+    #   @api public
+    #   The inner element for nested arrays.
+    #
+    #   @return [Element, nil]
+    # @!attribute [r] max
+    #   @api public
+    #   The maximum constraint for this element.
+    #
+    #   @return [Numeric, nil]
+    # @!attribute [r] min
+    #   @api public
+    #   The minimum constraint for this element.
+    #
+    #   @return [Numeric, nil]
+    # @!attribute [r] shape
+    #   @api public
+    #   The shape for this element.
+    #
+    #   @return [Object, nil]
+    # @!attribute [r] type
+    #   @api public
+    #   The type for this element.
+    #
+    #   @return [Symbol, nil]
+    # @!attribute [r] value
+    #   @api public
+    #   The literal value for this element.
+    #
+    #   @return [Object, nil]
+    attr_reader :custom_type,
+                :discriminator,
+                :enum,
+                :format,
+                :inner,
+                :max,
+                :min,
+                :shape,
+                :type,
+                :value
+
+    def initialize
+      @custom_type = nil
+      @defined = false
+      @discriminator = nil
+      @enum = nil
+      @format = nil
+      @inner = nil
+      @max = nil
+      @min = nil
+      @shape = nil
+      @type = nil
+      @value = nil
+    end
+
+    # @api public
+    # Defines a string.
+    #
+    # @param enum [Array, Symbol, nil] (nil)
+    #   The allowed values.
+    # @param format [Symbol, nil] (nil) [:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :url, :uuid]
+    #   Format hint for exports. Does not change the type, but exports may add validation or documentation based on it.
+    #   Valid formats by type: `:string`.
+    # @param max [Integer, nil] (nil)
+    #   The maximum length.
+    # @param min [Integer, nil] (nil)
+    #   The minimum length.
+    # @return [void]
+    #
+    # @example Basic string
+    #   array :tags do
+    #     string
+    #   end
+    #
+    # @example With length constraints
+    #   array :tags do
+    #     string min: 1, max: 50
+    #   end
+    def string(enum: nil, format: nil, max: nil, min: nil)
+      of(:string, enum:, format:, max:, min:)
+    end
+
+    # @api public
+    # Defines an integer.
+    #
+    # @param enum [Array, Symbol, nil] (nil)
+    #   The allowed values.
+    # @param max [Integer, nil] (nil)
+    #   The maximum value.
+    # @param min [Integer, nil] (nil)
+    #   The minimum value.
+    # @return [void]
+    #
+    # @example Basic integer
+    #   array :counts do
+    #     integer
+    #   end
+    #
+    # @example With range constraints
+    #   array :scores do
+    #     integer min: 0, max: 100
+    #   end
+    def integer(enum: nil, max: nil, min: nil)
+      of(:integer, enum:, max:, min:)
+    end
+
+    # @api public
+    # Defines a decimal.
+    #
+    # @param max [Numeric, nil] (nil)
+    #   The maximum value.
+    # @param min [Numeric, nil] (nil)
+    #   The minimum value.
+    # @return [void]
+    #
+    # @example Basic decimal
+    #   array :amounts do
+    #     decimal
+    #   end
+    #
+    # @example With range constraints
+    #   array :prices do
+    #     decimal min: 0
+    #   end
+    def decimal(max: nil, min: nil)
+      of(:decimal, max:, min:)
+    end
+
+    # @api public
+    # Defines a number.
+    #
+    # @param max [Numeric, nil] (nil)
+    #   The maximum value.
+    # @param min [Numeric, nil] (nil)
+    #   The minimum value.
+    # @return [void]
+    #
+    # @example Basic number
+    #   array :coordinates do
+    #     number
+    #   end
+    #
+    # @example With range constraints
+    #   array :latitudes do
+    #     number min: -90, max: 90
+    #   end
+    def number(max: nil, min: nil)
+      of(:number, max:, min:)
+    end
+
+    # @api public
+    # Defines a boolean.
+    #
+    # @return [void]
+    #
+    # @example
+    #   array :flags do
+    #     boolean
+    #   end
+    def boolean
+      of(:boolean)
+    end
+
+    # @api public
+    # Defines a datetime.
+    #
+    # @return [void]
+    #
+    # @example
+    #   array :timestamps do
+    #     datetime
+    #   end
+    def datetime
+      of(:datetime)
+    end
+
+    # @api public
+    # Defines a date.
+    #
+    # @return [void]
+    #
+    # @example
+    #   array :dates do
+    #     date
+    #   end
+    def date
+      of(:date)
+    end
+
+    # @api public
+    # Defines a UUID.
+    #
+    # @return [void]
+    #
+    # @example
+    #   array :ids do
+    #     uuid
+    #   end
+    def uuid
+      of(:uuid)
+    end
+
+    # @api public
+    # Defines a time.
+    #
+    # @return [void]
+    #
+    # @example
+    #   array :times do
+    #     time
+    #   end
+    def time
+      of(:time)
+    end
+
+    # @api public
+    # Defines a binary.
+    #
+    # @return [void]
+    #
+    # @example
+    #   array :blobs do
+    #     binary
+    #   end
+    def binary
+      of(:binary)
+    end
+
+    # @api public
+    # Defines an object.
+    #
+    # @yield block defining nested structure
+    # @yieldparam object [Object]
+    # @return [void]
+    #
+    # @example instance_eval style
+    #   array :items do
+    #     object do
+    #       string :name
+    #       decimal :price
+    #     end
+    #   end
+    #
+    # @example yield style
+    #   array :items do |element|
+    #     element.object do |object|
+    #       object.string :name
+    #       object.decimal :price
+    #     end
+    #   end
+    def object(&block)
+      of(:object, &block)
+    end
+
+    # @api public
+    # Defines an array.
+    #
+    # @yield block defining element type
+    # @yieldparam element [Element]
+    # @return [void]
+    #
+    # @example instance_eval style
+    #   array :matrix do
+    #     array do
+    #       integer
+    #     end
+    #   end
+    #
+    # @example yield style
+    #   array :matrix do |element|
+    #     element.array do |inner|
+    #       inner.integer
+    #     end
+    #   end
+    def array(&block)
+      of(:array, &block)
+    end
+
+    # @api public
+    # Defines a union.
+    #
+    # @param discriminator [Symbol, nil] (nil)
+    #   The discriminator field name.
+    # @yield block defining union variants
+    # @yieldparam union [Union]
+    # @return [void]
+    #
+    # @example instance_eval style
+    #   array :payments do
+    #     union discriminator: :type do
+    #       variant tag: 'card' do
+    #         object do
+    #           string :last_four
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # @example yield style
+    #   array :payments do |element|
+    #     element.union discriminator: :type do |union|
+    #       union.variant tag: 'card' do |variant|
+    #         variant.object do |object|
+    #           object.string :last_four
+    #         end
+    #       end
+    #     end
+    #   end
+    def union(discriminator: nil, &block)
+      of(:union, discriminator:, &block)
+    end
+
+    # @api public
+    # Defines a literal value.
+    #
+    # @param value [Object]
+    #   The literal value.
+    # @return [void]
+    #
+    # @example
+    #   variant tag: 'card' do
+    #     literal value: 'card'
+    #   end
+    def literal(value:)
+      of(:literal, value:)
+    end
+
+    # @api public
+    # Defines a reference to a named type.
+    #
+    # @param type_name [Symbol]
+    #   The type to reference.
+    # @return [void]
+    #
+    # @example
+    #   array :items do
+    #     reference :item
+    #   end
+    def reference(type_name)
+      of(type_name)
+    end
+
+    def validate!
+      raise ArgumentError, 'must define exactly one type' unless @defined
+    end
+
+    def of(type, **options, &block)
+      raise NotImplementedError, "#{self.class} must implement #of"
+    end
+
+    private
+
+    def set_type(type_value, enum: nil, format: nil, max: nil, min: nil)
+      @type = type_value
+      @enum = enum
+      @format = format
+      @max = max
+      @min = min
+      @defined = true
+    end
+  end
+end

data/lib/apiwork/engine.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class Engine < ::Rails::Engine
+    isolate_namespace Apiwork
+    engine_name 'apiwork'
+
+    rake_tasks do
+      load File.expand_path('../tasks/apiwork.rake', __dir__)
+    end
+
+    initializer 'apiwork.i18n' do
+      config.i18n.load_path += Dir[File.expand_path('../../config/locales/**/*.yml', __dir__)]
+    end
+
+    config.to_prepare do
+      Apiwork.prepare!
+    end
+  end
+end

data/lib/apiwork/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class Error < StandardError
+  end
+end

data/lib/apiwork/error_code/definition.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module ErrorCode
+    # @api public
+    # Represents a registered error code.
+    #
+    # Error codes define HTTP status codes and behavior for API errors.
+    # Retrieved via {ErrorCode.find} or {ErrorCode.find!}.
+    #
+    # @!attribute [r] key
+    #   @api public
+    #   The key for this error code.
+    #
+    #   @return [Symbol]
+    #
+    # @!attribute [r] status
+    #   @api public
+    #   The status for this error code.
+    #
+    #   @return [Integer]
+    #
+    # @example
+    #   error_code = Apiwork::ErrorCode.find!(:not_found)
+    #   error_code.key # => :not_found
+    #   error_code.status # => 404
+    #   error_code.attach_path? # => true
+    Definition = Struct.new(:key, :status, :attach_path, keyword_init: true) do
+      # @api public
+      # Whether this error code attaches the request path.
+      #
+      # @return [Boolean]
+      def attach_path?
+        attach_path
+      end
+
+      # @api public
+      # The description for this error code.
+      #
+      # @param locale_key [String, nil] (nil)
+      #   The I18n namespace for API-specific translations.
+      # @return [String]
+      #
+      # @example
+      #   error_code = Apiwork::ErrorCode.find!(:not_found)
+      #   error_code.description # => "Not Found"
+      #   error_code.description(locale_key: 'api/v1') # apiwork.apis.api/v1.error_codes.not_found.description
+      def description(locale_key: nil)
+        if locale_key
+          api_key = :"apiwork.apis.#{locale_key}.error_codes.#{key}.description"
+          result = I18n.translate(api_key, default: nil)
+          return result if result
+        end
+
+        global_key = :"apiwork.error_codes.#{key}.description"
+        result = I18n.translate(global_key, default: nil)
+        return result if result
+
+        key.to_s.titleize
+      end
+    end
+  end
+end

data/lib/apiwork/error_code/registry.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module ErrorCode
+    class Registry < Apiwork::Registry
+      class << self
+        def register(key, attach_path: false, status:)
+          key = normalize_key(key)
+          status = Integer(status)
+
+          raise ArgumentError, "Status must be 400-599, got #{status}" unless (400..599).cover?(status)
+
+          store[key] = Definition.new(attach_path:, key:, status:)
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/error_code.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Apiwork
+  # @api public
+  module ErrorCode
+    DEFAULTS = {
+      bad_gateway: {
+        status: 502,
+      },
+      bad_request: {
+        status: 400,
+      },
+      conflict: {
+        status: 409,
+      },
+      forbidden: {
+        status: 403,
+      },
+      gateway_timeout: {
+        status: 504,
+      },
+      gone: {
+        status: 410,
+      },
+      internal_server_error: {
+        status: 500,
+      },
+      locked: {
+        status: 423,
+      },
+      method_not_allowed: {
+        status: 405,
+      },
+      not_acceptable: {
+        status: 406,
+      },
+      not_found: {
+        attach_path: true,
+        status: 404,
+      },
+      not_implemented: {
+        status: 501,
+      },
+      payment_required: {
+        status: 402,
+      },
+      precondition_failed: {
+        status: 412,
+      },
+      request_timeout: {
+        status: 408,
+      },
+      service_unavailable: {
+        status: 503,
+      },
+      too_many_requests: {
+        status: 429,
+      },
+      unauthorized: {
+        status: 401,
+      },
+      unprocessable_entity: {
+        status: 422,
+      },
+      unsupported_media_type: {
+        status: 415,
+      },
+    }.freeze
+
+    class << self
+      # @!method find(key)
+      #   @api public
+      #   Finds an error code by key.
+      #   @param key [Symbol]
+      #     The error code key.
+      #   @return [ErrorCode::Definition, nil]
+      #   @see .find!
+      #   @example
+      #     Apiwork::ErrorCode.find(:not_found)
+      #
+      # @!method find!(key)
+      #   @api public
+      #   Finds an error code by key.
+      #   @param key [Symbol]
+      #     The error code key.
+      #   @return [ErrorCode::Definition]
+      #   @raise [KeyError] if the error code is not found
+      #   @see .find
+      #   @example
+      #     Apiwork::ErrorCode.find!(:not_found)
+      #
+      # @!method register(key, attach_path: false, status:)
+      #   @api public
+      #   Registers a custom error code for use in API responses.
+      #
+      #   Error codes are used with `raises` declarations and `expose_error`
+      #   in controllers. Built-in codes (400-504) are pre-registered.
+      #
+      #   @param key [Symbol]
+      #     The unique identifier for the error code.
+      #   @param attach_path [Boolean] (false)
+      #     Include request path in error response.
+      #   @param status [Integer]
+      #     The HTTP status code (must be 400-599).
+      #   @return [ErrorCode::Definition]
+      #   @raise [ArgumentError] if status is outside 400-599 range
+      #   @see Issue
+      #
+      #   @example Register custom error code
+      #     Apiwork::ErrorCode.register :resource_locked, status: 423
+      #
+      #   @example With path attachment
+      #     Apiwork::ErrorCode.register :not_found, status: 404, attach_path: true
+      delegate :clear!,
+               :exists?,
+               :find,
+               :find!,
+               :keys,
+               :register,
+               :values,
+               to: Registry
+
+      def key_for_status(status)
+        DEFAULTS.find { |_key, config| config[:status] == status }&.first
+      end
+
+      def register_defaults!
+        DEFAULTS.each { |key, options| register(key, **options) }
+      end
+    end
+  end
+end