apiwork 0.6.0 → 0.7.0

data/lib/apiwork/representation/attribute.rb

@@ -21,6 +21,14 @@ module Apiwork
         string: %i[date datetime email hostname ipv4 ipv6 password text url uuid],
       }.freeze
 
+      # @!attribute [r] default
+      #   @api public
+      #   The default for this attribute.
+      #
+      #   Returns `nil` for both "no default" and "default is explicitly `nil`".
+      #   Use {#default?} to distinguish these cases.
+      #
+      #   @return [Object, nil]
       # @!attribute [r] description
       #   @api public
       #   The description for this attribute.
@@ -71,7 +79,8 @@ module Apiwork
       #   The type for this attribute.
       #
       #   @return [Symbol]
-      attr_reader :description,
+      attr_reader :default,
+                  :description,
                   :element,
                   :empty,
                   :enum,
@@ -83,12 +92,14 @@ module Apiwork
                   :of,
                   :optional,
                   :preload,
-                  :type
+                  :type,
+                  :write_only
 
       def initialize(
         name,
         owner_representation_class,
         decode: nil,
+        default: UNSET,
         deprecated: false,
         description: nil,
         empty: false,
@@ -105,6 +116,7 @@ module Apiwork
         sortable: false,
         type: nil,
         writable: false,
+        write_only: false,
         &block
       )
         @name = name
@@ -132,6 +144,24 @@ module Apiwork
             type = :string if detected_enum && type == :integer
             optional = detect_optional(name) if optional.nil?
             nullable = detect_nullable(name) if nullable.nil?
+            default = detect_default(name, empty:, nullable:, optional:) if UNSET.equal?(default)
+
+            if @db_column && type == :string
+              detected_max = detect_string_max_length(name)
+              max = [max, detected_max].compact.min
+            end
+
+            if @db_column && type == :decimal
+              detected_min, detected_max = detect_decimal_bounds(name)
+              min = [min, detected_min].compact.max
+              max = [max, detected_max].compact.min
+            end
+
+            if @db_column && type == :integer
+              detected_min, detected_max = detect_integer_bounds(name)
+              min = [min, detected_min].compact.max
+              max = [max, detected_max].compact.min
+            end
           rescue ActiveRecord::StatementInvalid, ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished
             @db_column = false
           end
@@ -139,6 +169,7 @@ module Apiwork
 
         optional = false if optional.nil?
         nullable = false if nullable.nil?
+        default = '' if UNSET.equal?(default) && empty
 
         @filterable = filterable
         @preload = preload
@@ -157,12 +188,26 @@ module Apiwork
         @example = example
         @format = format
         @deprecated = deprecated
+        @write_only = write_only
+        @default_set = !UNSET.equal?(default)
+        @default = @default_set ? default : nil
 
         validate_min_max_range!
         validate_format!
         validate_empty!
       end
 
+      # @api public
+      # Whether this attribute has a default value.
+      #
+      # Use this to distinguish "no default" from "default is explicitly `nil`".
+      # The {#default} accessor returns `nil` in both cases.
+      #
+      # @return [Boolean]
+      def default?
+        @default_set
+      end
+
       # @api public
       # Whether this attribute is deprecated.
       #
@@ -225,6 +270,14 @@ module Apiwork
         [true, action].include?(@writable)
       end
 
+      # @api public
+      # Whether this attribute is write-only.
+      #
+      # @return [Boolean]
+      def write_only?
+        @write_only
+      end
+
       def encode(value)
         result = @empty && value.nil? ? '' : value
         @encode ? @encode.call(result) : result
@@ -265,6 +318,32 @@ module Apiwork
         end
       end
 
+      def detect_string_max_length(name)
+        column = column_for(name)
+        return nil unless column
+
+        column.limit
+      end
+
+      def detect_decimal_bounds(name)
+        column = column_for(name)
+        return [nil, nil] unless column
+        return [nil, nil] unless column.precision
+
+        scale = column.scale || 0
+        max = (10**(column.precision - scale) - 10.0**(-scale)).to_f
+        [-max, max]
+      end
+
+      def detect_integer_bounds(name)
+        column = column_for(name)
+        return [nil, nil] unless column
+
+        limit = column.limit || 4
+        max = 2**(8 * limit - 1) - 1
+        [-max - 1, max]
+      end
+
       def detect_optional(name)
         return false unless @model_class
         return false unless db_column?
@@ -277,6 +356,23 @@ module Apiwork
         column.null
       end
 
+      def detect_default(name, empty:, nullable:, optional:)
+        return UNSET unless @model_class
+        return UNSET unless db_column?
+
+        column = column_for(name)
+        return UNSET unless column
+        return UNSET if column.default_function
+
+        default = @model_class.column_defaults[name.to_s]
+        return default unless default.nil?
+
+        return '' if empty && nullable && optional
+        return nil if nullable && optional
+
+        UNSET
+      end
+
       def detect_nullable(name)
         return false unless @model_class
         return false unless db_column?

data/lib/apiwork/representation/base.rb

@@ -184,6 +184,8 @@ module Apiwork
         #   The attribute name.
         # @param decode [Proc, nil] (nil)
         #   Transform for request input (API to database). Must preserve the attribute type.
+        # @param default [Object] (UNSET)
+        #   The default value. Omit to declare no default. Pass `nil` for an explicit null default. If omitted and name maps to a database column, auto-detected from the column's static default.
         # @param deprecated [Boolean] (false)
         #   Whether deprecated. Metadata included in exports.
         # @param description [String, nil] (nil)
@@ -222,6 +224,9 @@ module Apiwork
         #   Use an explicit type or block in those cases.
         # @param writable [Boolean, Symbol] (false) [:create, :update]
         #   The write access. `true` for both create and update, `:create` for create only, `:update` for update only.
+        # @param write_only [Boolean] (false)
+        #   Whether the attribute is write-only. Write-only attributes are excluded from response
+        #   serialization and response types but remain in writable payloads.
         # @yieldparam element [Representation::Element]
         # @return [void]
         #
@@ -270,6 +275,7 @@ module Apiwork
         def attribute(
           name,
           decode: nil,
+          default: UNSET,
           deprecated: false,
           description: nil,
           empty: nil,
@@ -286,6 +292,7 @@ module Apiwork
           sortable: false,
           type: nil,
           writable: false,
+          write_only: false,
           &block
         )
           self.attributes = attributes.merge(
@@ -293,6 +300,7 @@ module Apiwork
               name,
               self,
               decode:,
+              default:,
               deprecated:,
               description:,
               empty:,
@@ -309,6 +317,7 @@ module Apiwork
               sortable:,
               type:,
               writable:,
+              write_only:,
               &block
             ),
           )

data/lib/apiwork/representation/serializer.rb

@@ -21,6 +21,8 @@ module Apiwork
         add_discriminator_field(fields) if @representation_class.subclass?
 
         @representation_class.attributes.each do |name, attribute|
+          next if attribute.write_only?
+
           value = @representation.respond_to?(name) ? @representation.public_send(name) : @representation.record.public_send(name)
           value = map_type_column_output(name, value)
           value = attribute.encode(value)

data/lib/apiwork/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apiwork
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

data/lib/apiwork.rb

@@ -4,6 +4,10 @@ require 'zeitwerk'
 require_relative 'apiwork/version'
 
 module Apiwork
+  # @api public
+  # Sentinel for an unset value. Distinguishes from explicit `nil`.
+  UNSET = Object.new.freeze
+
   class << self
     def call(env)
       routes.call(env)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apiwork
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - skiftle
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-03 00:00:00.000000000 Z
+date: 2026-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -260,8 +260,9 @@ files:
 - lib/apiwork/error_code/definition.rb
 - lib/apiwork/error_code/registry.rb
 - lib/apiwork/export.rb
+- lib/apiwork/export/apiwork.rb
+- lib/apiwork/export/apiwork_mapper.rb
 - lib/apiwork/export/base.rb
-- lib/apiwork/export/builder_mapper.rb
 - lib/apiwork/export/open_api.rb
 - lib/apiwork/export/pipeline.rb
 - lib/apiwork/export/pipeline/writer.rb

data/lib/apiwork/export/builder_mapper.rb

@@ -1,184 +0,0 @@
-# frozen_string_literal: true
-
-module Apiwork
-  module Export
-    class BuilderMapper
-      class << self
-        def map(export, surface)
-          new(export).map(surface)
-        end
-      end
-
-      def initialize(export)
-        @export = export
-      end
-
-      def map(surface)
-        build_builders(surface.types)
-      end
-
-      def build_builders(types)
-        builders = types.sort_by { |name, _type| name.to_s }.flat_map do |name, type|
-          if type.union?
-            build_union_builders(name, type, types)
-          elsif type.object?
-            [build_object_builder(name, type)]
-          end
-        end.compact
-
-        builders.join("\n\n")
-      end
-
-      private
-
-      def build_object_builder(name, type)
-        type_name = pascal_case(name)
-        defaulted, required = classify_fields(type.shape)
-
-        if defaulted.empty?
-          build_passthrough_builder(type_name)
-        elsif required.empty?
-          build_all_defaulted_builder(type_name, defaulted)
-        else
-          build_mixed_builder(type_name, defaulted, required)
-        end
-      end
-
-      def build_passthrough_builder(type_name)
-        "export function build#{type_name}(fields: #{type_name}): #{type_name} {\n" \
-          "  return fields;\n" \
-          '}'
-      end
-
-      def build_all_defaulted_builder(type_name, defaulted)
-        defaults = build_defaults_body(defaulted)
-
-        "export function build#{type_name}(fields?: Partial<#{type_name}>): #{type_name} {\n" \
-          "  return {\n" \
-          "#{defaults}\n" \
-          "    ...fields,\n" \
-          "  };\n" \
-          '}'
-      end
-
-      def build_mixed_builder(type_name, defaulted, required)
-        required_keys = required.keys.map { |name| "'#{@export.transform_key(name)}'" }.sort.join(' | ')
-        fields_type = "Pick<#{type_name}, #{required_keys}> & Partial<#{type_name}>"
-        defaults = build_defaults_body(defaulted)
-
-        "export function build#{type_name}(fields: #{fields_type}): #{type_name} {\n" \
-          "  return {\n" \
-          "#{defaults}\n" \
-          "    ...fields,\n" \
-          "  };\n" \
-          '}'
-      end
-
-      def build_defaults_body(defaulted)
-        defaulted.sort_by { |name, _param| name.to_s }.map do |name, param|
-          "    #{@export.transform_key(name)}: #{serialize_default(param)},"
-        end.join("\n")
-      end
-
-      def build_union_builders(name, type, types)
-        type_name = pascal_case(name)
-        builders = [build_passthrough_builder(type_name)]
-
-        if type.discriminator
-          type.variants.each do |variant|
-            next unless variant.tag
-            next if variant.reference? && types.key?(variant.reference)
-
-            builders << build_variant_builder(type_name, type.discriminator, variant)
-          end
-        end
-
-        builders
-      end
-
-      def build_variant_builder(type_name, discriminator, variant)
-        discriminator_key = @export.transform_key(discriminator)
-        builder_name = variant.reference? ? "build#{pascal_case(variant.reference)}" : "build#{type_name}#{pascal_case(variant.tag)}"
-        extract_type = "Extract<#{type_name}, { #{discriminator_key}: '#{variant.tag}' }>"
-
-        variant_defaults = {}
-        variant_required = {}
-
-        variant_defaults, variant_required = classify_fields(variant.shape) if variant.object? && variant.shape.any?
-
-        fields_type = build_variant_fields_type(extract_type, discriminator_key, variant_defaults, variant_required)
-
-        body_lines = ["    #{discriminator_key}: '#{variant.tag}',"]
-        variant_defaults.sort_by { |name, _param| name.to_s }.each do |name, param|
-          body_lines << "    #{@export.transform_key(name)}: #{serialize_default(param)},"
-        end
-        body_lines << '    ...fields,'
-
-        "export function #{builder_name}(fields: #{fields_type}): #{type_name} {\n" \
-          "  return {\n" \
-          "#{body_lines.join("\n")}\n" \
-          "  };\n" \
-          '}'
-      end
-
-      def build_variant_fields_type(extract_type, discriminator_key, defaulted, required)
-        omitted_type = "Omit<#{extract_type}, '#{discriminator_key}'>"
-
-        if required.empty? && defaulted.empty?
-          omitted_type
-        elsif required.empty?
-          "Partial<#{omitted_type}>"
-        else
-          required_keys = required.keys.map { |name| "'#{@export.transform_key(name)}'" }.sort.join(' | ')
-          "Pick<#{omitted_type}, #{required_keys}> & Partial<#{omitted_type}>"
-        end
-      end
-
-      def classify_fields(shape)
-        defaulted = {}
-        required = {}
-
-        shape.sort_by { |name, _param| name.to_s }.each do |name, param|
-          if defaulted_field?(param)
-            defaulted[name] = param
-          else
-            required[name] = param
-          end
-        end
-
-        [defaulted, required]
-      end
-
-      def defaulted_field?(param)
-        return true if param.nullable?
-        return true if param.respond_to?(:default) && !param.default.nil?
-
-        false
-      end
-
-      def serialize_default(param)
-        if param.respond_to?(:default) && !param.default.nil?
-          serialize_value(param.default)
-        elsif param.nullable?
-          'null'
-        end
-      end
-
-      def serialize_value(value)
-        case value
-        when String then "'#{value.gsub("'", "\\\\'")}'"
-        when Integer, Float then value.to_s
-        when BigDecimal then value.to_s('F')
-        when TrueClass, FalseClass then value.to_s
-        when Array then '[]'
-        when Hash then '{}'
-        else value.to_s
-        end
-      end
-
-      def pascal_case(name)
-        name.to_s.camelize(:upper)
-      end
-    end
-  end
-end