apiwork 0.4.0 → 0.5.0

data/lib/apiwork/introspection/param/record.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    module Param
+      # @api public
+      # Record param representing key-value maps with typed values.
+      #
+      # @example Basic usage
+      #   param.type # => :record
+      #   param.record? # => true
+      #   param.scalar? # => false
+      #
+      # @example Value type
+      #   param.of # => Param (value type) or nil
+      class Record < Base
+        # @api public
+        # The default for this param.
+        #
+        # @return [Object, nil]
+        def default
+          @dump[:default]
+        end
+
+        # @api public
+        # The example for this param.
+        #
+        # @return [Object, nil]
+        def example
+          @dump[:example]
+        end
+
+        # @api public
+        # The value type for this record.
+        #
+        # @return [Param::Base, nil]
+        def of
+          @of ||= @dump[:of] ? Param.build(@dump[:of]) : nil
+        end
+
+        # @api public
+        # Whether this param is a record.
+        #
+        # @return [Boolean]
+        def record?
+          true
+        end
+
+        # @api public
+        # Whether this param is concrete.
+        #
+        # @return [Boolean]
+        def concrete?
+          true
+        end
+
+        # @api public
+        # Converts this param to a hash.
+        #
+        # @return [Hash]
+        def to_h
+          result = super
+          result[:default] = default
+          result[:example] = example
+          result[:of] = of&.to_h
+          result
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/introspection/param/string.rb

@@ -24,6 +24,22 @@ module Apiwork
       #     param.enum_reference? # => false
       #   end
       class String < Base
+        # @api public
+        # The default for this param.
+        #
+        # @return [Object, nil]
+        def default
+          @dump[:default]
+        end
+
+        # @api public
+        # The example for this param.
+        #
+        # @return [Object, nil]
+        def example
+          @dump[:example]
+        end
+
         # @api public
         # The format for this param.
         #
@@ -48,6 +64,14 @@ module Apiwork
           @dump[:max]
         end
 
+        # @api public
+        # Whether this param is concrete.
+        #
+        # @return [Boolean]
+        def concrete?
+          true
+        end
+
         # @api public
         # Whether this param is scalar.
         #
@@ -110,7 +134,9 @@ module Apiwork
         # @return [Hash]
         def to_h
           result = super
+          result[:default] = default
           result[:enum] = enum if enum?
+          result[:example] = example
           result[:format] = format
           result[:max] = max
           result[:min] = min

data/lib/apiwork/introspection/param/time.rb

@@ -20,6 +20,30 @@ module Apiwork
       #     param.enum_reference? # => false
       #   end
       class Time < Base
+        # @api public
+        # The default for this param.
+        #
+        # @return [Object, nil]
+        def default
+          @dump[:default]
+        end
+
+        # @api public
+        # The example for this param.
+        #
+        # @return [Object, nil]
+        def example
+          @dump[:example]
+        end
+
+        # @api public
+        # Whether this param is concrete.
+        #
+        # @return [Boolean]
+        def concrete?
+          true
+        end
+
         # @api public
         # Whether this param is scalar.
         #
@@ -67,6 +91,18 @@ module Apiwork
         def formattable?
           false
         end
+
+        # @api public
+        # Converts this param to a hash.
+        #
+        # @return [Hash]
+        def to_h
+          result = super
+          result[:default] = default
+          result[:enum] = enum if enum?
+          result[:example] = example
+          result
+        end
       end
     end
   end

data/lib/apiwork/introspection/param/uuid.rb

@@ -20,6 +20,30 @@ module Apiwork
       #     param.enum_reference? # => false
       #   end
       class UUID < Base
+        # @api public
+        # The default for this param.
+        #
+        # @return [Object, nil]
+        def default
+          @dump[:default]
+        end
+
+        # @api public
+        # The example for this param.
+        #
+        # @return [Object, nil]
+        def example
+          @dump[:example]
+        end
+
+        # @api public
+        # Whether this param is concrete.
+        #
+        # @return [Boolean]
+        def concrete?
+          true
+        end
+
         # @api public
         # Whether this param is scalar.
         #
@@ -67,6 +91,18 @@ module Apiwork
         def formattable?
           false
         end
+
+        # @api public
+        # Converts this param to a hash.
+        #
+        # @return [Hash]
+        def to_h
+          result = super
+          result[:default] = default
+          result[:enum] = enum if enum?
+          result[:example] = example
+          result
+        end
       end
     end
   end

data/lib/apiwork/introspection/param.rb

@@ -18,6 +18,7 @@ module Apiwork
           when :binary then Binary.new(dump)
           when :unknown then Unknown.new(dump)
           when :array then Array.new(dump)
+          when :record then Record.new(dump)
           when :object then Object.new(dump)
           when :union then Union.new(dump)
           when :literal then Literal.new(dump)

data/lib/apiwork/object.rb

@@ -1129,6 +1129,103 @@ module Apiwork
       )
     end
 
+    # @api public
+    # Defines an unknown.
+    #
+    # @param name [Symbol]
+    #   The name.
+    # @param as [Symbol, nil] (nil)
+    #   The target attribute name.
+    # @param default [Object, nil] (nil)
+    #   The default value.
+    # @param deprecated [Boolean] (false)
+    #   Whether deprecated. Metadata included in exports.
+    # @param description [String, nil] (nil)
+    #   The description. Metadata included in exports.
+    # @param example [Object, nil] (nil)
+    #   The example value. Metadata included in exports.
+    # @param nullable [Boolean] (false)
+    #   Whether the value can be `null`.
+    # @param optional [Boolean] (false)
+    #   Whether the param is optional.
+    # @param required [Boolean] (false)
+    #   Whether the param is required.
+    # @return [void]
+    #
+    # @example Opaque metadata
+    #   unknown :metadata
+    def unknown(
+      name,
+      as: nil,
+      default: nil,
+      deprecated: false,
+      description: nil,
+      example: nil,
+      nullable: false,
+      optional: false,
+      required: false
+    )
+      param(
+        name,
+        as:,
+        default:,
+        deprecated:,
+        description:,
+        example:,
+        nullable:,
+        optional:,
+        required:,
+        type: :unknown,
+      )
+    end
+
+    # @api public
+    # Defines an optional unknown.
+    #
+    # @param name [Symbol]
+    #   The name.
+    # @param as [Symbol, nil] (nil)
+    #   The target attribute name.
+    # @param default [Object, nil] (nil)
+    #   The default value.
+    # @param deprecated [Boolean] (false)
+    #   Whether deprecated. Metadata included in exports.
+    # @param description [String, nil] (nil)
+    #   The description. Metadata included in exports.
+    # @param example [Object, nil] (nil)
+    #   The example value. Metadata included in exports.
+    # @param nullable [Boolean] (false)
+    #   Whether the value can be `null`.
+    # @param required [Boolean] (false)
+    #   Whether the param is required.
+    # @return [void]
+    #
+    # @example Optional metadata
+    #   unknown? :metadata
+    def unknown?(
+      name,
+      as: nil,
+      default: nil,
+      deprecated: false,
+      description: nil,
+      example: nil,
+      nullable: false,
+      required: false
+    )
+      param(
+        name,
+        as:,
+        default:,
+        deprecated:,
+        description:,
+        example:,
+        nullable:,
+        required:,
+        optional: true,
+        type: :unknown,
+      )
+    end
+
     # @api public
     # Defines an object.
     #
@@ -1267,6 +1364,22 @@ module Apiwork
     #       decimal :price
     #     end
     #   end
+    #
+    # @example Array of discriminated union
+    #   array :notifications do
+    #     union discriminator: :type do
+    #       variant tag: 'email' do
+    #         object do
+    #           string :address
+    #         end
+    #       end
+    #       variant tag: 'sms' do
+    #         object do
+    #           string :phone
+    #         end
+    #       end
+    #     end
+    #   end
     def array(
       name,
       as: nil,
@@ -1320,6 +1433,22 @@ module Apiwork
     #   array? :labels do
     #     string
     #   end
+    #
+    # @example Optional array of discriminated union
+    #   array? :items do
+    #     union discriminator: :type do
+    #       variant tag: 'text' do
+    #         object do
+    #           string :content
+    #         end
+    #       end
+    #       variant tag: 'image' do
+    #         object do
+    #           string :url
+    #         end
+    #       end
+    #     end
+    #   end
     def array?(
       name,
       as: nil,
@@ -1346,6 +1475,113 @@ module Apiwork
       )
     end
 
+    # @api public
+    # Defines a record.
+    #
+    # @param name [Symbol]
+    #   The name.
+    # @param as [Symbol, nil] (nil)
+    #   The target attribute name.
+    # @param default [Object, nil] (nil)
+    #   The default value.
+    # @param deprecated [Boolean] (false)
+    #   Whether deprecated. Metadata included in exports.
+    # @param description [String, nil] (nil)
+    #   The description. Metadata included in exports.
+    # @param nullable [Boolean] (false)
+    #   Whether the value can be `null`.
+    # @param optional [Boolean] (false)
+    #   Whether the param is optional.
+    # @param required [Boolean] (false)
+    #   Whether the param is required.
+    # @yield block defining value type
+    # @return [void]
+    #
+    # @example Record of integers
+    #   record :scores do
+    #     integer
+    #   end
+    #
+    # @example Record of objects
+    #   record :settings do
+    #     object do
+    #       string :value
+    #       boolean :enabled
+    #     end
+    #   end
+    def record(
+      name,
+      as: nil,
+      default: nil,
+      deprecated: false,
+      description: nil,
+      nullable: false,
+      optional: false,
+      required: false,
+      &block
+    )
+      param(
+        name,
+        as:,
+        default:,
+        deprecated:,
+        description:,
+        nullable:,
+        optional:,
+        required:,
+        type: :record,
+        &block
+      )
+    end
+
+    # @api public
+    # Defines an optional record.
+    #
+    # @param name [Symbol]
+    #   The name.
+    # @param as [Symbol, nil] (nil)
+    #   The target attribute name.
+    # @param default [Object, nil] (nil)
+    #   The default value.
+    # @param deprecated [Boolean] (false)
+    #   Whether deprecated. Metadata included in exports.
+    # @param description [String, nil] (nil)
+    #   The description. Metadata included in exports.
+    # @param nullable [Boolean] (false)
+    #   Whether the value can be `null`.
+    # @param required [Boolean] (false)
+    #   Whether the param is required.
+    # @yield block defining value type
+    # @return [void]
+    #
+    # @example Optional record
+    #   record? :metadata do
+    #     string
+    #   end
+    def record?(
+      name,
+      as: nil,
+      default: nil,
+      deprecated: false,
+      description: nil,
+      nullable: false,
+      required: false,
+      &block
+    )
+      param(
+        name,
+        as:,
+        default:,
+        deprecated:,
+        description:,
+        nullable:,
+        required:,
+        optional: true,
+        type: :record,
+        &block
+      )
+    end
+
     # @api public
     # Defines a union.
     #
@@ -1552,6 +1788,8 @@ module Apiwork
       optional: false,
       required: false
     )
+      reference_type = to || name
+
       param(
         name,
         as:,
@@ -1561,7 +1799,8 @@ module Apiwork
         nullable:,
         optional:,
         required:,
-        type: to || name,
+        custom_type: reference_type,
+        type: reference_type,
       )
     end
 
@@ -1598,6 +1837,8 @@ module Apiwork
       nullable: false,
       required: false
     )
+      reference_type = to || name
+
       param(
         name,
         as:,
@@ -1606,8 +1847,9 @@ module Apiwork
         description:,
         nullable:,
         required:,
+        custom_type: reference_type,
         optional: true,
-        type: to || name,
+        type: reference_type,
       )
     end
 

data/lib/apiwork/representation/attribute.rb

@@ -117,7 +117,7 @@ module Apiwork
           element.validate!
           @element = element
           type = element.type
-          @of = element.inner&.type if element.type == :array
+          @of = element.inner&.type if [:array, :record].include?(element.type)
         end
 
         if owner_representation_class.model_class.present?

data/lib/apiwork/representation/base.rb

@@ -69,6 +69,7 @@ module Apiwork
       class_attribute :inheritance, default: nil, instance_accessor: false
 
       class_attribute :_adapter_config, default: {}, instance_accessor: false
+      class_attribute :type_definitions, default: {}, instance_accessor: false
 
       # @!attribute [r] context
       #   @api public
@@ -540,6 +541,110 @@ module Apiwork
           )
         end
 
+        # @api public
+        # Defines an object type for this representation.
+        #
+        # The type is copied to the contract that uses this representation. Attributes can reference
+        # it by name via `type:`. In exports, the type is scoped to the contract.
+        #
+        # @param name [Symbol]
+        #   The object name.
+        # @param deprecated [Boolean] (false)
+        #   Whether deprecated. Metadata included in exports.
+        # @param description [String, nil] (nil)
+        #   The description. Metadata included in exports.
+        # @param example [Object, nil] (nil)
+        #   The example. Metadata included in exports.
+        # @yieldparam object [API::Object]
+        # @return [void]
+        #
+        # @example Define and reference
+        #   object :address do
+        #     string :street
+        #     string :city
+        #     string :postal_code
+        #   end
+        #
+        #   attribute :shipping_address, type: :address
+        #   attribute :billing_address, type: :address
+        def object(
+          name,
+          deprecated: false,
+          description: nil,
+          example: nil,
+          &block
+        )
+          self.type_definitions = type_definitions.merge(
+            name.to_sym => {
+              block:,
+              kind: :object,
+              options: {
+                deprecated:,
+                description:,
+                example:,
+              },
+            },
+          )
+        end
+
+        # @api public
+        # Defines a union type for this representation.
+        #
+        # The type is copied to the contract that uses this representation. Attributes can reference
+        # it by name via `type:`. In exports, the type is scoped to the contract.
+        #
+        # @param name [Symbol]
+        #   The union name.
+        # @param deprecated [Boolean] (false)
+        #   Whether deprecated. Metadata included in exports.
+        # @param description [String, nil] (nil)
+        #   The description. Metadata included in exports.
+        # @param discriminator [Symbol, nil] (nil)
+        #   The discriminator field name.
+        # @param example [Object, nil] (nil)
+        #   The example. Metadata included in exports.
+        # @yieldparam union [API::Union]
+        # @return [void]
+        #
+        # @example Define and reference
+        #   union :content_block, discriminator: :kind do
+        #     variant tag: 'text' do
+        #       object do
+        #         string :body
+        #       end
+        #     end
+        #     variant tag: 'image' do
+        #       object do
+        #         string :url
+        #         integer :width
+        #         integer :height
+        #       end
+        #     end
+        #   end
+        #
+        #   attribute :content, type: :content_block
+        def union(
+          name,
+          deprecated: false,
+          description: nil,
+          discriminator: nil,
+          example: nil,
+          &block
+        )
+          self.type_definitions = type_definitions.merge(
+            name.to_sym => {
+              block:,
+              kind: :union,
+              options: {
+                deprecated:,
+                description:,
+                discriminator:,
+                example:,
+              },
+            },
+          )
+        end
+
         # @api public
         # The type name for this representation.
         #

data/lib/apiwork/representation/element.rb

@@ -11,10 +11,11 @@ module Apiwork
     # Only complex types are allowed at the top level:
     # - {#object} for key-value structures
     # - {#array} for ordered collections
+    # - {#record} for key-value maps with typed values
     # - {#union} for polymorphic structures
     #
     # Inside these blocks, the full type DSL is available including
-    # nested objects, arrays, primitives, and unions.
+    # nested objects, arrays, records, primitives, and unions.
     #
     # @see API::Element Block context for array elements
     # @see API::Object Block context for object fields
@@ -74,15 +75,15 @@ module Apiwork
     #   end
     class Element < Apiwork::Element
       def validate!
-        raise ConfigurationError, 'must define exactly one type (object, array, or union)' unless @defined
+        raise ConfigurationError, 'must define exactly one type (object, array, record, or union)' unless @defined
       end
 
       # @api public
       # Defines the element type.
       #
-      # Only complex types (:object, :array, :union) are allowed.
+      # Only complex types (:object, :array, :record, :union) are allowed.
       #
-      # @param type [Symbol] [:array, :object, :union]
+      # @param type [Symbol] [:array, :object, :record, :union]
       #   The element type.
       # @param discriminator [Symbol, nil] (nil)
       #   The discriminator field name. Unions only.
@@ -110,6 +111,15 @@ module Apiwork
           @inner = inner
           @shape = inner.shape
           @defined = true
+        when :record
+          raise ConfigurationError, 'record requires a block' unless block
+
+          inner = API::Element.new
+          block.arity.positive? ? yield(inner) : inner.instance_eval(&block)
+          inner.validate!
+          @type = :record
+          @inner = inner
+          @defined = true
         when :union
           raise ConfigurationError, 'union requires a block' unless block
 
@@ -120,7 +130,7 @@ module Apiwork
           @discriminator = discriminator
           @defined = true
         else
-          raise ConfigurationError, "Representation::Element only supports :object, :array, :union - got #{type.inspect}"
+          raise ConfigurationError, "Representation::Element only supports :object, :array, :record, :union - got #{type.inspect}"
         end
       end
     end