importu 0.1.0 → 0.2.0

data/lib/importu/config_dsl.rb

@@ -0,0 +1,381 @@
+# frozen_string_literal: true
+
+# DSL methods for configuring importers.
+#
+# These methods define your import specification: what fields to extract,
+# how to convert them, where to persist, and what actions are allowed.
+#
+# ## Field Definition
+# - {#field} - Define a single field with options
+# - {#fields} - Define multiple fields at once
+# - {#converter} - Create a custom converter
+# - {#convert_to} - Reference a built-in or custom converter
+#
+# ## Persistence
+# - {#model} - Connect to a model class for persistence
+# - {#find_by} - Specify how to find existing records
+# - {#allow_actions} - Control create/update permissions
+# - {#before_save} - Hook to modify records before saving
+#
+# ## Source Configuration
+# - {#source} - Configure source-specific options
+#
+# @example Complete importer definition
+#   class BookImporter < Importu::Importer
+#     # Fields
+#     fields :title, :author
+#     field :isbn, label: "ISBN-10"
+#     field :pages, required: false, &convert_to(:integer)
+#     field :price, &convert_to(:decimal)
+#
+#     # Persistence
+#     model "Book"
+#     allow_actions :create, :update
+#     find_by :isbn
+#
+#     # Hooks
+#     before_save { object.title = object.title.titleize }
+#   end
+#
+# @see Importu::Converters for built-in converters
+# @api public
+module Importu::ConfigDSL
+
+  # Returns the current configuration hash for this importer.
+  #
+  # @return [Hash] the configuration hash
+  # @api semipublic
+  def config
+    @config ||= superclass.respond_to?(:config) \
+      ? superclass.config
+      : default_config
+  end
+
+  # Specifies which persistence actions are allowed during import.
+  #
+  # @param actions [Array<Symbol>] the actions to allow (:create and/or :update)
+  # @return [void]
+  #
+  # @example Allow only creating new records (default)
+  #   allow_actions :create
+  #
+  # @example Allow both creating and updating
+  #   allow_actions :create, :update
+  #
+  # @api public
+  def allow_actions(*actions)
+    @config = { **config,
+      backend: { **config[:backend], allowed_actions: actions.compact }
+    }
+  end
+
+  # Creates a converter reference for use with field definitions.
+  #
+  # @param type [Symbol] the converter type (:string, :integer, :date, etc.)
+  # @param options [Hash] converter-specific options
+  # @return [ConverterStub] a callable that applies the converter
+  #
+  # @example Basic usage
+  #   field :pages, &convert_to(:integer)
+  #
+  # @example With options
+  #   field :release_date, &convert_to(:date, format: "%Y-%m-%d")
+  #
+  # @api public
+  def convert_to(type, **options)
+    config[:converters].fetch(type) # validate converter exists
+    ConverterStub.for(type, **options)
+  end
+
+  # Defines a custom converter for use in field definitions.
+  #
+  # @param name [Symbol] the converter name
+  # @yield [field_name, **options] block that performs the conversion
+  # @yieldparam field_name [Symbol] the field being converted
+  # @yieldparam options [Hash] any options passed to convert_to
+  # @yieldreturn the converted value
+  # @return [void]
+  #
+  # @example Simple converter
+  #   converter(:uppercase) do |name|
+  #     value = raw(name)
+  #     value.respond_to?(:upcase) ? value.upcase : value
+  #   end
+  #
+  # @example Converter with options
+  #   converter(:varchar) do |name, length: 255|
+  #     value = trimmed(name)
+  #     value.nil? ? nil : String(value).slice(0, length)
+  #   end
+  #
+  # @api public
+  def converter(name, &block)
+    @config = { **config,
+      converters: { **config[:converters], name => block }
+    }
+  end
+
+  # Defines a single field with its configuration.
+  #
+  # @param name [Symbol] the field name (used as the key in record hashes)
+  # @param props [Hash] field options
+  # @option props [String] :label the column/key name in source data (default: field name as string)
+  # @option props [Boolean] :required whether the field must be present (default: true)
+  # @option props [Boolean] :abstract whether the field is computed, not from source (default: false)
+  # @option props [Object] :default value to use when field is nil and not required
+  # @option props [Boolean] :create include this field when creating records (default: true)
+  # @option props [Boolean] :update include this field when updating records (default: true)
+  # @yield [field_name] optional block for custom conversion logic
+  # @return [void]
+  #
+  # @example Basic field
+  #   field :title
+  #
+  # @example Field with label mapping
+  #   field :authors, label: "author"
+  #
+  # @example Field with converter
+  #   field :pages, &convert_to(:integer)
+  #
+  # @example Field with custom conversion block
+  #   field :authors do
+  #     trimmed(:authors).to_s.split(", ")
+  #   end
+  #
+  # @api public
+  def field(name, **props, &block)
+    field = config[:fields].fetch(name, field_defaults(name))
+    props[:converter] = block if block
+
+    @config = { **config,
+      fields: { **config[:fields],
+        name => { **field, **props }
+      }
+    }
+  end
+
+  # Defines multiple fields with the same configuration.
+  #
+  # @param names [Array<Symbol>] the field names
+  # @param props [Hash] field options (see {#field} for available options)
+  # @yield optional block for custom conversion (applied to all fields)
+  # @return [void]
+  #
+  # @example Multiple fields
+  #   fields :title, :author, :isbn
+  #
+  # @example Multiple fields with shared converter
+  #   fields :pages, :quantity, &convert_to(:integer)
+  #
+  # @api public
+  def fields(*names, **props, &block)
+    names.each {|name| field(name, **props, &block) }
+  end
+
+  # Specifies how to find existing records for updates.
+  #
+  # @param field_groups [Array<Symbol, Array<Symbol>>] fields to match against
+  # @yield [record] optional block for custom lookup logic
+  # @yieldparam record [Importu::Record] the record being imported
+  # @return [void]
+  #
+  # @example Single field lookup
+  #   find_by :isbn
+  #
+  # @example Multiple fields (all must match)
+  #   find_by :title, :author
+  #
+  # @example Multiple field groups (tried in order)
+  #   find_by :isbn, [:title, :author]
+  #
+  # @example Custom lookup block
+  #   find_by do |record|
+  #     find_by(title: record[:title].downcase)
+  #   end
+  #
+  # @api public
+  def find_by(*field_groups, &block)
+    finder_fields = [*field_groups, block].compact.map do |field_group|
+      field_group.respond_to?(:call) ? field_group : Array(field_group)
+    end
+
+    @config = { **config,
+      backend: { **config[:backend], finder_fields: finder_fields }
+    }
+  end
+
+  # Associates the importer with a model class for persistence.
+  #
+  # @param name [String, Class] the model class or class name
+  # @param backend [Symbol, nil] the backend to use (:active_record, :auto, or nil)
+  # @return [void]
+  #
+  # @example Basic usage
+  #   model "Book"
+  #
+  # @example With explicit backend
+  #   model "Book", backend: :active_record
+  #
+  # @example With auto-detection (default behavior)
+  #   model "Book", backend: :auto
+  #
+  # The backend can be:
+  # - nil or :auto - auto-detect from registered backends
+  # - :active_record - use ActiveRecord backend explicitly
+  # - Any other symbol registered with Importu::Backends.registry
+  #
+  # @see #allow_actions
+  # @see #find_by
+  # @api public
+  def model(name, backend: nil)
+    @config = { **config,
+      backend: { **config[:backend], name: backend, model: name }
+    }
+  end
+
+  # Defines a callback to execute just before saving a record.
+  #
+  # The block is executed in the context of an AssignmentContext, which
+  # provides access to:
+  # - object: the model instance being saved
+  # - record: the converted record data
+  # - action: :create or :update
+  #
+  # This is a backend hook. Backends may choose to honor it or ignore it.
+  # The ActiveRecord backend executes it after assigning field values but
+  # before calling save!.
+  #
+  # @yield block to execute before saving
+  # @return [void]
+  #
+  # @example Normalize title before saving
+  #   before_save { object.title = object.title.titleize }
+  #
+  # @example Set audit field
+  #   before_save { object.imported_at = Time.current }
+  #
+  # @example Conditional logic based on action
+  #   before_save do
+  #     object.created_by = "importer" if action == :create
+  #     object.updated_by = "importer" if action == :update
+  #   end
+  #
+  # @see Importu::Backends::ActiveRecord::AssignmentContext
+  # @api public
+  def before_save(&block)
+    @config = { **config,
+      backend: { **config[:backend], before_save: block }
+    }
+  end
+
+  # Configures source-specific options.
+  #
+  # @param type [Symbol] the source type (:csv, :json, :xml, :ruby)
+  # @param props [Hash] source-specific options
+  # @return [void]
+  #
+  # @example XML source with xpath
+  #   source :xml, records_xpath: "//book"
+  #
+  # @example CSV source with custom delimiter
+  #   source :csv, col_sep: "\t"
+  #
+  # @api public
+  def source(type, **props)
+    source = config[:sources].fetch(type, {})
+
+    @config = { **config,
+      sources: { **config[:sources],
+        type => { **source, **props }
+      }
+    }
+  end
+
+  # @!visibility private
+  def default_config
+    raw_converter = ->(n) { raw_value(n) }
+
+    {
+      backend: {
+        name: nil,
+        model: nil,
+        finder_fields: [],
+        before_save: nil,
+        allowed_actions: [:create],
+      },
+      sources: {
+        csv: {},
+        json: {},
+        ruby: {},
+        xml: {
+          records_xpath: nil,
+        },
+      },
+      converters: {
+        raw: raw_converter,
+        default: raw_converter,
+      },
+      fields: {},
+    }
+  end
+
+  # @!visibility private
+  def field_defaults(name)
+    {
+      name: name,
+      label: name.to_s,
+      required: true,
+      abstract: false,
+      default: nil,
+      create: true,
+      update: true,
+      converter: convert_to(:default),
+    }
+  end
+
+  # A proc-like object that stores converter type and options.
+  #
+  # This allows subclassed definitions to override a converter's behavior
+  # and have it affect already defined fields.
+  #
+  # @api private
+  class ConverterStub < Proc
+    # @return [Symbol] the converter type
+    attr_reader :type
+
+    # @return [Hash] the converter options
+    attr_reader :options
+
+    # Creates a new converter stub.
+    #
+    # @param type [Symbol] the converter type
+    # @param options [Hash] options to pass to the converter
+    # @param block [Proc] the converter implementation
+    def initialize(type, options, &block)
+      @type, @options = type, options
+      super(&block)
+    end
+
+    # Creates a stub that delegates to a named converter.
+    #
+    # @param type [Symbol] the converter type
+    # @param options [Hash] options to pass to the converter
+    # @return [ConverterStub] a new stub
+    def self.for(type, **options)
+      block = options.any? \
+        ? ->(n) { send(type, n, **options) }
+        : ->(n) { send(type, n) }
+
+      new(type, options, &block)
+    end
+
+    # Compares stubs by type and options.
+    #
+    # @param other [ConverterStub] the other stub
+    # @return [Boolean] true if type and options match
+    def ==(other)
+      type == other.type && options == other.options
+    end
+  end
+
+end

data/lib/importu/converter_context.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+require "importu/exceptions"
+
+# Execution context for field converters.
+#
+# When you define a custom converter or field block, the code executes within
+# a ConverterContext instance. This provides access to field values and other
+# converters while isolating converter code from internal implementation details.
+#
+# @example Accessing values in a custom converter
+#   converter :full_name do |field_name|
+#     # raw_value gets the untransformed source data
+#     first = raw_value(:first_name)
+#     last = raw_value(:last_name)
+#     "#{first} #{last}".strip
+#   end
+#
+# @example Referencing other fields
+#   field :tax do
+#     # field_value gets the converted value of another field
+#     subtotal = field_value(:subtotal)
+#     subtotal * 0.08
+#   end
+#
+# @api semipublic
+class Importu::ConverterContext
+  # Creates a new context with the given source data.
+  #
+  # @param data [Hash] the raw source data for one record
+  # @api private
+  def initialize(data)
+    @data = data
+  end
+
+  # Creates a context subclass configured with converters and field definitions.
+  #
+  # @param converters [Hash{Symbol => Proc}] converter name to implementation
+  # @param fields [Hash{Symbol => Hash}] field name to definition
+  # @return [Class] a configured ConverterContext subclass
+  # @api private
+  def self.with_config(converters:, fields:, **)
+    Class.new(self) do
+      define_method(:field_definitions) { fields }
+      converters.each {|name, block| define_method(name, &block) }
+    end
+  end
+
+  # Returns the converted value of a field.
+  #
+  # Runs the field's converter and applies validation. Use this when you need
+  # the final, converted value of another field.
+  #
+  # @param name [Symbol] the field name
+  # @return [Object] the converted field value
+  # @raise [Importu::FieldParseError] if conversion fails
+  # @raise [Importu::MissingField] if field is required but missing
+  # @raise [Importu::InvalidDefinition] if field is not defined
+  def field_value(name)
+    definition = fetch_field_definition(name)
+
+    begin
+      value = instance_exec(name, &definition[:converter])
+    rescue ArgumentError => e
+      # conversion of field value most likely failed
+      raise Importu::FieldParseError.new(name, e.message)
+    end
+
+    if value.nil? && definition[:required]
+      raise Importu::MissingField.new(definition, available_fields: @data.keys)
+    else
+      value.nil? ? definition[:default] : value
+    end
+  end
+
+  # Returns the raw, unconverted value from source data.
+  #
+  # Use this when you need the original value before any conversion. The value
+  # is looked up using the field's label (which defaults to the field name).
+  #
+  # @param name [Symbol] the field name
+  # @return [Object, nil] the raw source value
+  # @raise [Importu::InvalidDefinition] if field is not defined
+  def raw_value(name)
+    definition = fetch_field_definition(name)
+    @data[definition.fetch(:label)]
+  end
+
+  private def fetch_field_definition(name)
+    field_definitions.fetch(name) do
+      raise Importu::InvalidDefinition, "importer field not defined: #{name}"
+    end
+  end
+
+end

data/lib/importu/converters.rb

@@ -1,82 +1,137 @@
-require 'active_support/core_ext/object/blank'
-require 'active_support/core_ext/date_time/conversions'
-require 'active_support/concern'
-
-require 'bigdecimal'
+# frozen_string_literal: true
+require "bigdecimal"
+require "date"
 
+# Built-in converters for common data types.
+#
+# This module is automatically included in importers and provides these converters:
+#
+# ## :boolean
+# Converts to true/false. Accepts: true, false, 1, 0, "true", "false", "yes", "no".
+# Returns nil for nil/empty, raises ArgumentError for other values.
+#
+#     field :active, &convert_to(:boolean)
+#
+# ## :date
+# Parses date strings. Uses Date.parse by default, or Date.strptime with format option.
+#
+#     field :published, &convert_to(:date)
+#     field :published, &convert_to(:date, format: "%Y-%m-%d")
+#
+# ## :datetime
+# Parses datetime strings to Time (UTC). Uses DateTime.parse or strptime with format.
+#
+#     field :created_at, &convert_to(:datetime)
+#     field :created_at, &convert_to(:datetime, format: "%Y-%m-%d %H:%M:%S")
+#
+# ## :decimal
+# Converts to BigDecimal. Accepts numeric strings like "123.45".
+# Returns nil for nil/empty, raises ArgumentError for invalid format.
+#
+#     field :price, &convert_to(:decimal)
+#
+# ## :float
+# Converts to Float using Kernel#Float.
+#
+#     field :rating, &convert_to(:float)
+#
+# ## :integer
+# Converts to Integer (base 10). Accepts integers or numeric strings.
+#
+#     field :pages, &convert_to(:integer)
+#
+# ## :string
+# Converts to String. Trims whitespace, returns nil for empty strings.
+#
+#     field :name, &convert_to(:string)
+#
+# ## :trimmed (default)
+# Strips whitespace from strings, returns nil for empty. Non-strings pass through.
+# This is the default converter when none is specified.
+#
+#     field :title  # uses :trimmed by default
+#
+# @see Importu::ConfigDSL#converter
+# @see Importu::ConfigDSL#convert_to
+# @api semipublic
 module Importu::Converters
-  extend ActiveSupport::Concern
+  # Defines built-in converters when included in a class.
+  #
+  # @api private
+  def self.included(base)
+    base.class_eval do
 
-  included do
-    converter :raw do |name,options|
-      definition = definitions[name] \
-        or raise "importer field not defined: #{name}"
+      converter :boolean do |name|
+        value = trimmed(name)
+        case value
+          when nil then nil
+          when true, 1, /\A(?:true|yes|1)\z/i then true
+          when false, 0, /\A(?:false|no|0)\z/i then false
+          else raise ArgumentError, "invalid boolean value '#{value}'"
+        end
+      end
 
-      label = definition[:label]
-      raise Importu::MissingField, definition unless data.key?(label)
-      data[label]
-    end
+      converter :date do |name, format: nil|
+        if value = trimmed(name)
+          format \
+            ? Date.strptime(value, format)
+            : Date.parse(value)
+        end
+      end
 
-    converter :clean do |name,options|
-      value = convert(name, :raw, options)
-      value.is_a?(String) \
-        ? (value.blank? ? nil : value.strip)
-        : value
-    end
+      converter :datetime do |name, format: nil|
+        if value = trimmed(name)
+          dt = format \
+            ? DateTime.strptime(value, format)
+            : DateTime.parse(value)
+          # Convert DateTime to Time without triggering ActiveSupport deprecation
+          offset_seconds = (dt.offset * 86_400).to_i
+          Time.new(dt.year, dt.month, dt.day, dt.hour, dt.min, dt.sec, offset_seconds).utc
+        end
+      end
 
-    converter :string do |name,options|
-      convert(name, :clean, options).try(:to_s)
-    end
+      converter :decimal do |name|
+        value = trimmed(name)
+        case value
+          when nil then nil
+          when BigDecimal then value
+          when /\A-?\d+(?:\.\d+)?\Z/ then BigDecimal(value)
+          else raise ArgumentError, "invalid decimal value '#{value}'"
+        end
+      end
 
-    converter :integer do |name,options|
-      value = convert(name, :clean, options)
-      value.nil? ? nil : Integer(value)
-    end
+      converter :float do |name|
+        value = trimmed(name)
+        value.nil? ? nil : Float(value)
+      end
 
-    converter :float do |name,options|
-      value = convert(name, :clean, options)
-      value.nil? ? nil : Float(value)
-    end
+      converter :integer do |name|
+        value = trimmed(name)
 
-    converter :decimal do |name,options|
-      value = convert(name, :clean, options)
-      case value
-        when nil then nil
-        when BigDecimal then value
-        when /\A-?\d+(?:\.\d+)?\Z/ then BigDecimal(value)
-        else raise ArgumentError, "invalid decimal value '#{value}'"
+        case value
+          when nil then nil
+          when Integer then value
+          else Integer(value.to_s, 10)
+        end
       end
-    end
 
-    converter :boolean do |name,options|
-      value = convert(name, :clean, options)
-      case value
-        when nil then nil
-        when true, 'true', 'yes', '1', 1 then true
-        when false, 'false', 'no', '0', 0 then false
-        else raise ArgumentError, "invalid boolean value '#{value}'"
+      converter :string do |name|
+        value = trimmed(name)
+        value.nil? ? nil : String(value)
       end
-    end
 
-    converter :date do |name,options|
-      if value = convert(name, :clean, options)
-        # TODO: options[:date_format] is deprecated
-        date_format = options[:date_format] || options[:format]
-        date_format \
-          ? Date.strptime(value, date_format)
-          : Date.parse(value)
+      converter :trimmed do |name|
+        value = raw_value(name)
+        if value.is_a?(String)
+          new_value = value.strip
+          new_value.empty? ? nil : new_value
+        else
+          value
+        end
       end
-    end
 
-    converter :datetime do |name,options|
-      if value = convert(name, :clean, options)
-        # TODO: options[:date_format] is deprecated
-        date_format = options[:date_format] || options[:format]
-        date_format \
-          ? DateTime.strptime(value, date_format).utc
-          : DateTime.parse(value).utc
-      end
-    end
+      converter :default, &convert_to(:trimmed)
 
+    end
   end
 end

data/lib/importu/definition.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+require "importu/config_dsl"
+require "importu/converters"
+
+# Base class for import definitions.
+#
+# Definition provides the DSL for declaring fields, converters, and import
+# configuration. Extend this class to create reusable field definitions that
+# can be shared across multiple importers.
+#
+# @example Creating a reusable definition
+#   class BookFields < Importu::Definition
+#     fields :title, :author
+#     field :isbn, &convert_to(:string)
+#   end
+#
+# @see Importu::Importer
+# @see Importu::ConfigDSL
+# @api public
+class Importu::Definition
+  extend Importu::ConfigDSL
+  include Importu::Converters
+end