data_model 0.3.0 → 0.5.0

data/lib/data_model/error.rb

@@ -1,33 +1,37 @@
-# typed: strict
-
 module DataModel
-	# Error is a class that holds errors.
+	# Error is a class that holds errors. Errors are a tuple of [name, ctx]
+	#  - name is a symbol that identifies the error
+	#  - ctx is contextual information about the error which can be used to build an error message
+	#
+	#  The error object is a structured way to store, modify, and add errors in that intermediary format.
+	#  To turn an error into a human readable message, use #to_messages, which delegates to a registry
+	#
+	#  Base errors are errors that are related to the object as a whole, and not to any specific child
+	#  Child errors are errors that are related to a specific child of the object, which may or may not apply depending on the type
 	class Error
-		extend T::Sig
-
-		TErrorList = T.type_alias { T::Array[TError] }
-		TErrorMap = T.type_alias { T::Hash[Symbol, TErrorList] }
+		include Errors
 
-		sig { void }
+		# Create a new error Object
+		# @return [Error] the new error object
 		def initialize
-			@base = T.let([], TErrorList)
-			@children = T.let({}, TErrorMap)
+			@base = []
+			@children = {}
 		end
 
 		# errors related to the object as a whole
-		sig { returns(TErrorList) }
+		# @return [Array<Array(Symbol, untyped)>] the base errors
 		def base
 			return @base
 		end
 
 		# errors related children
-		sig { returns(TErrorMap) }
+		# @return [Hash{Symbol => Array<Array(Symbol, untyped)>}] the child errors
 		def children
 			return @children
 		end
 
 		# all errors
-		sig { returns(TErrorMap) }
+		# @return [Hash{Symbol => Array<Array(Symbol, untyped)>}] all errors
 		def all
 			return children.merge(base:)
 		end
@@ -35,7 +39,8 @@ module DataModel
 		alias to_h all
 
 		# Returns true if any errors are present.
-		sig { params(blk: T.nilable(T.proc.params(error: TError).returns(T::Boolean))).returns(T::Boolean) }
+		# @param blk [Proc] an optional block to filter errors, takes an Array(Symbol, untyped) and returns boolean
+		# @return [Boolean] true if any errors are present
 		def any?(&blk)
 			if !blk
 				return !@base.empty? || !@children.empty?
@@ -53,13 +58,16 @@ module DataModel
 			return any
 		end
 
-		sig { returns(T::Boolean) }
+		# Returns true if no errors are present.
+		# @return [Boolean] true if no errors are present
 		def empty?
 			!any?
 		end
 
 		# Add an error to the error list.
-		sig { params(err: TError, child: T.nilable(T.any(Symbol, T::Array[Symbol]))).void }
+		# @param err [Array(Symbol, untyped)] the error to add
+		# @param child [Symbol, Array(Symbol)] the child to add the error to. child can be an array of symbols to specify a path if nested
+		# @return [void]
 		def add(err, child: nil)
 			if child.is_a?(Array)
 				child = child.join(".").to_sym
@@ -73,7 +81,10 @@ module DataModel
 			errs.push(err)
 		end
 
-		sig { params(name: Symbol, child: Error).void }
+		# Merge another error object into this one for child Errors
+		# @param name [Symbol] the name of the child
+		# @param child [Error] the child error object
+		# @return [void]
 		def merge_child(name, child)
 			if !child.any?
 				return
@@ -86,22 +97,11 @@ module DataModel
 			end
 		end
 
-		sig { params(blk: T.proc.params(context: Object, type: Symbol).returns(Object)).void }
-		def transform_context(&blk)
-			for error in @base
-				key, context = error
-				error[1] = blk.call(context, key)
-			end
-		end
-
-		sig { params(blk: T.proc.params(context: Object, type: Symbol).returns(Object)).void }
-		def transform_child_context(&blk)
-			for error_list in @children.values
-				for error in error_list
-					key, context = error
-					error[1] = blk.call(context, key)
-				end
-			end
+		# Get human readable error messages from error tuples
+		# @param registry [Registry] the registry to use to get error messages
+		# @return [Hash{Symbol => Array[String]}] the error messages
+		def to_messages(registry: Registry.instance)
+			return registry.error_messages(self)
 		end
 	end
 end

data/lib/data_model/errors.rb

@@ -1,83 +1,96 @@
-# typed: strict
-
 module DataModel
 	# Provide Error building functionality as a mixin
 	module Errors
-		include Kernel
-		extend T::Sig
-
-		TTemporal = T.type_alias { T.any(::Date, ::Time, ::DateTime) }
+		extend self
 
 		## Constructors
 
 		# Type error applies when a value is not of the expected type
-		sig { params(cls: T.class_of(Object), value: Object).returns(TError) }
+		# @param cls [String, Array(String)] the expected class
+		# @param value [Object] the value that failed
+		# @return [Array(Symbol, untyped)] the error
 		def type_error(cls, value)
 			[:type, [cls, value]]
 		end
 
 		# Coerce error applies when a value cannot be coerced to the expected type
-		sig { params(cls: T.class_of(Object), value: Object).returns(TError) }
+		# @param cls [String] the expected class
+		# @param value [Object] the value that failed
+		# @return [Array(Symbol, untyped)] the error
 		def coerce_error(cls, value)
 			[:coerce, [cls, value]]
 		end
 
 		# Missing error applies when a value is missing
-		sig { params(cls: T.class_of(Object)).returns(TError) }
+		# @param cls [String, Array<String>] the expected class
+		# @return [Array(Symbol, untyped)] the error
 		def missing_error(cls)
 			[:missing, cls]
 		end
 
 		# Inclusion error applies when a value is not in a set of allowed values
-		sig { params(set: T::Array[T.any(Symbol, String)]).returns(TError) }
+		# @param set [Array<Symbol, String>] the set of allowed values
+		# @return [Array(Symbol, untyped)] the error
 		def inclusion_error(set)
 			[:inclusion, set]
 		end
 
 		# Exclusive error applies when a value is in a set of disallowed values
-		sig { params(set: T::Array[T.any(Symbol, String)]).returns(TError) }
+		# @param set [Array<Symbol, String>] the set of disallowed values
+		# @return [Array(Symbol, untyped)] the error
 		def exclusion_error(set)
 			[:exclusion, set]
 		end
 
 		# Blank error applies when a value is blank
-		sig { returns(TError) }
+		# @return [Array(Symbol, untyped)] the error
 		def blank_error
 			[:blank, nil]
 		end
 
 		# Extra keys error applies when a hash has extra keys
-		sig { params(keys: T::Array[Symbol]).returns(TError) }
+		# @param keys [Array<Symbol>] the extra keys
+		# @return [Array(Symbol, untyped)] the error
 		def extra_keys_error(keys)
 			[:extra_keys, keys]
 		end
 
 		# Min applies when value is less then the minimum
-		sig { params(min: Numeric, val: Numeric).returns(TError) }
+		# @param min [Numeric] the minimum value
+		# @param val [Numeric] the value that failed
+		# @return [Array(Symbol, untyped)] the error
 		def min_error(min, val)
 			[:min, [min, val]]
 		end
 
 		# Max applies when value is less then the minimum
-		sig { params(min: Numeric, val: Numeric).returns(TError) }
+		# @param min [Numeric] the minimum value
+		# @param val [Numeric] the value that failed
+		# @return [Array(Symbol, untyped)] the error
 		def max_error(min, val)
 			[:max, [min, val]]
 		end
 
 		# Earliest applies when value is earlier then earliest
-		sig { params(earliest: TTemporal, val: TTemporal).returns(TError) }
+		# @param earliest [Date, Time] the earliest value
+		# @param val [Date, Time] the value that failed
+		# @return [Array(Symbol, untyped)] the error
 		def earliest_error(earliest, val)
 			[:earliest, [earliest, val]]
 		end
 
 		# Latest applies when value is earlier then earliest
-		sig { params(latest: TTemporal, val: TTemporal).returns(TError) }
+		# @param latest [Date, Time] the latest value
+		# @param val [Date, Time] the value that failed
+		# @return [Array(Symbol, untyped)] the error
 		def latest_error(latest, val)
 			[:latest, [latest, val]]
 		end
 
 		# Format applies when value does not match a format
-		sig { params(format: Object, val: String).returns(TError) }
+		# @param format [Object] the format
+		# @param val [String] the value that failed
+		# @return [Array(Symbol, untyped)] the error
 		def format_error(format, val)
 			[:format, [format, val]]
 		end
@@ -85,212 +98,163 @@ module DataModel
 		## Messages
 
 		# Generate a message for a type error
-		sig { params(cls: T.class_of(Object), value: Object).returns(String) }
+		# @param cls [String] the expected class
+		# @param value [Object] the value that failed
+		# @return [String] the message
 		def type_error_message(cls, value)
-			"#{value.inspect} is not a #{cls.name}, it is a #{value.class.name}"
+			names = Array(cls).join(" or ")
+			"#{value.inspect} is not a #{names}, it is a #{value.class.name}"
 		end
 
 		# Generate a message for a coerce error
-		sig { params(cls: T.class_of(Object), value: Object).returns(String) }
+		# @param cls [String] the expected class
+		# @param value [Object] the value that failed
+		# @return [String] the message
 		def coerce_error_message(cls, value)
-			"cannot be coerced to #{cls.name}, it is a #{value.class.name}"
+			names = Array(cls).join(" or ")
+			"cannot be coerced to #{names}, it is a #{value.class.name}"
 		end
 
 		# Generate a message for a missing error
-		sig { params(cls: T.class_of(Object)).returns(String) }
+		# @param cls [String, Array<String>] the expected class
+		# @return [String] the message
 		def missing_error_message(cls)
-			"missing value, expected a #{cls.name}"
+			names = Array(cls).join(" or ")
+			"missing value, expected a #{names}"
 		end
 
 		# Generate a message for an inclusion error
-		sig { params(set: T::Array[Symbol]).returns(String) }
+		# @param set [Array<Symbol, String>] the set of allowed values
+		# @return [String] the message
 		def inclusion_error_message(set)
 			"must be one of #{set.join(', ')}"
 		end
 
 		# Generate a message for an exclusion error
-		sig { params(set: T::Array[Symbol]).returns(String) }
+		# @param set [Array<Symbol, String>] the set of disallowed values
+		# @return [String] the message
 		def exclusion_error_message(set)
 			"must not be one of #{set.join(', ')}"
 		end
 
 		# Generate a message for a blank error
-		sig { returns(String) }
+		# @return [String] the message
 		def blank_error_message
 			"cannot be blank"
 		end
 
 		# Generate a message for an extra keys error
-		sig { params(keys: T::Array[Symbol]).returns(String) }
+		# @param keys [Array<Symbol>] the extra keys
+		# @return [String] the message
 		def extra_keys_error_message(keys)
 			"more elements found in closed hash then specified children: #{keys.join(', ')}"
 		end
 
 		# Generate a message for a min error
-		sig { params(min: Numeric, val: Numeric).returns(String) }
+		# @param min [Numeric] the minimum value
+		# @param val [Numeric] the value that failed
+		# @return [String] the message
 		def min_error_message(min, val)
 			"value is less than the minimum of #{min}, it is #{val}"
 		end
 
 		# Generate a message for a min error
-		sig { params(max: Numeric, val: Numeric).returns(String) }
+		# @param max [Numeric] the maximum value
+		# @param val [Numeric] the value that failed
+		# @return [String] the message
 		def max_error_message(max, val)
 			"value is more than the maximum of #{max}, it is #{val}"
 		end
 
 		# Generate a message for a value that occurs earlier then the specified earliest point
-		sig { params(earliest: TTemporal, val: TTemporal).returns(String) }
+		# @param earliest [Date, Time] the earliest value
+		# @param val [Date, Time] the value that failed
+		# @return [String] the message
 		def early_error_message(earliest, val)
 			"value #{val} is before #{earliest}"
 		end
 
 		# Generate a message for a value that occurs later then the specified latest  point
-		sig { params(latest: TTemporal, val: TTemporal).returns(String) }
+		# @param latest [Date, Time] the latest value
+		# @param val [Date, Time] the value that failed
+		# @return [String] the message
 		def late_error_message(latest, val)
 			"value #{val} is after #{latest}"
 		end
 
 		# Generate a message for a value that does not match the format
-		sig { params(format: Object, val: String).returns(String) }
+		# @param format [Object] the format
+		# @param val [String] the value that failed
+		# @return [String] the message
 		def format_error_message(format, val)
 			"value #{val} does not match format #{format}"
 		end
 
-		## API
-		# TODO: split this file
-
-		TErrorMessageBuilder = T.type_alias { T.proc.params(ctx: T.untyped).returns(String) }
-
-		# Register a custom error message for use with custom errors
-		sig { params(type: Symbol, block: TErrorMessageBuilder).void }
-		def register_error_message(type, &block)
-			error_message_builders[type] = block
-		end
-
-		TErrorMessages = T.type_alias { T::Hash[Symbol, TErrorMessageBuilder] }
-		TClassValueCtx = T.type_alias { [T.class_of(Object), Object] }
-		TClassCtx = T.type_alias { T.class_of(Object) }
-		TSetCtx = T.type_alias { T::Array[Symbol] }
-		TWithinCtx = T.type_alias { [Numeric, Numeric] }
-		TWithinTemporalCtx = T.type_alias { [TTemporal, TTemporal] }
-		TFormatCtx = T.type_alias { [Object, String] }
+		# Builders
 
 		# Get the error message builders
-		sig { returns(TErrorMessages) }
-		def error_message_builders
-			if @error_messages.nil?
-				@error_messages ||= T.let({}, T.nilable(TErrorMessages))
-
-				# wire up defaults
-
-				register_error_message(:type) do |ctx|
-					cls, val = T.let(ctx, TClassValueCtx)
+		# @return [Hash{Symbol => Proc}] the error message builders
+		def error_messages
+			return {
+				type: lambda do |ctx|
+					cls, val = ctx
 					type_error_message(cls, val)
-				end
+				end,
 
-				register_error_message(:coerce) do |ctx|
-					cls, val = T.let(ctx, TClassValueCtx)
-					coerce_error_message(cls, val)
-				end
+				coerce: lambda do |ctx|
+					cls, val = ctx
+					type_error_message(cls, val)
+				end,
 
-				register_error_message(:missing) do |ctx|
-					cls = T.let(ctx, TClassCtx)
+				missing: lambda do |ctx|
+					cls = ctx
 					missing_error_message(cls)
-				end
+				end,
 
-				register_error_message(:inclusion) do |ctx|
-					set = T.let(ctx, TSetCtx)
+				inclusion: lambda do |ctx|
+					set = ctx
 					inclusion_error_message(set)
-				end
+				end,
 
-				register_error_message(:exclusion) do |ctx|
-					set = T.let(ctx, TSetCtx)
+				exclusion: lambda do |ctx|
+					set = ctx
 					exclusion_error_message(set)
-				end
+				end,
 
-				register_error_message(:extra_keys) do |ctx|
-					set = T.let(ctx, TSetCtx)
+				extra_keys: lambda do |ctx|
+					set = ctx
 					extra_keys_error_message(set)
-				end
+				end,
 
-				register_error_message(:min) do |ctx|
-					min, val = T.let(ctx, TWithinCtx)
+				min: lambda do |ctx|
+					min, val = ctx
 					min_error_message(min, val)
-				end
+				end,
 
-				register_error_message(:max) do |ctx|
-					max, val = T.let(ctx, TWithinCtx)
+				max: lambda do |ctx|
+					max, val = ctx
 					max_error_message(max, val)
-				end
+				end,
 
-				register_error_message(:earliest) do |ctx|
-					earliest, val = T.let(ctx, TWithinTemporalCtx)
+				earliest: lambda do |ctx|
+					earliest, val = ctx
 					early_error_message(earliest, val)
-				end
+				end,
 
-				register_error_message(:latest) do |ctx|
-					latest, val = T.let(ctx, TWithinTemporalCtx)
+				latest: lambda do |ctx|
+					latest, val = ctx
 					late_error_message(latest, val)
-				end
+				end,
 
-				register_error_message(:blank) do
+				blank: lambda do
 					blank_error_message
-				end
+				end,
 
-				register_error_message(:format) do |ctx|
-					format, val = T.let(ctx, TFormatCtx)
+				format: lambda do |ctx|
+					format, val = ctx
 					format_error_message(format, val)
 				end
-			end
-
-			@error_messages
-		end
-
-		# Build the error message for a given error
-		sig { params(error: TError).returns(String) }
-		def error_message(error)
-			type = T.let(error[0], Symbol)
-			ctx = T.let(error[1], T.untyped)
-
-			builder = error_message_builders[type]
-
-			if builder.nil?
-				raise "no error message builder for #{type}"
-			end
-
-			builder.call(ctx)
-		end
-
-		# TODO: separate builders from other use cases for this mixin
-		# Build error messages from error object
-		sig { params(error: Error).returns(T::Hash[Symbol, T::Array[String]]) }
-		def error_messages(error)
-			error.to_h.transform_values do |error_list|
-				error_list.map { |e| error_message(e) }
-			end
-		end
-
-		sig { params(error: Error, from: T.class_of(Object), to: T.class_of(Object)).void }
-		def set_error_class(error, from, to)
-			error.transform_context do |ctx, type|
-				case type
-				when :type, :coerce
-					cls, val = T.cast(ctx, TClassValueCtx)
-					if cls == from
-						[to, val]
-					else
-						[cls, val]
-					end
-				when :missing
-					if ctx == from
-						[to, val]
-					else
-						[cls, val]
-					end
-				else
-					[cls, val]
-				end
-			end
+			}
 		end
 	end
 end

data/lib/data_model/fixtures/array.rb

@@ -1,12 +1,22 @@
-# typed: strict
-
 module DataModel
+	# test fixtures for array type
 	module Fixtures::Array
 		extend self
-		extend T::Sig
 		include Fixtures
 
-		sig { returns(Example) }
+		# a simple array of any types
+		# @return [Example] the example
+		def any_array
+			Example.new(
+				[:array],
+				variants: {
+					mixed: ["a", 2, [], ::Object.new]
+				},
+			)
+		end
+
+		# a simple array of strings example
+		# @return [Example] the example
 		def string_array
 			Example.new(
 				[:array, :string],
@@ -16,12 +26,13 @@ module DataModel
 					number: [1, ["1"]],
 					missing: nil,
 					numbers: [[1, 2, 3], ["1", "2", "3"]],
-					other_type: Object.new
+					other_type: ::Object.new
 				},
 			)
 		end
 
-		sig { returns(Example) }
+		# a simple array of strings that wraps single values
+		# @return [Example] the example
 		def wrapping_string_array
 			Example.new(
 				[:array, { wrap_single_value: true }, :string],
@@ -31,12 +42,13 @@ module DataModel
 					number: [1, ["1"]],
 					missing: nil,
 					numbers: [[1, 2, 3], ["1", "2", "3"]],
-					other_type: Object.new
+					other_type: ::Object.new
 				},
 			)
 		end
 
-		sig { returns(Example) }
+		# an optional example
+		# @return [Example] the example
 		def optional_string_array
 			Example.new(
 				[:array, { optional: true }, :string],
@@ -47,7 +59,8 @@ module DataModel
 			)
 		end
 
-		sig { returns(Example) }
+		# an array of optional strings
+		# @return [Example] the example
 		def array_optional_string
 			Example.new(
 				[:array, [:string, { optional: true }]],

data/lib/data_model/fixtures/big_decimal.rb

@@ -1,14 +1,13 @@
-# typed: strict
-
 require "bigdecimal/util"
 
 module DataModel
+	# test fixtures for BigDecimal
 	module Fixtures::BigDecimal
 		include Fixtures
-		extend T::Sig
 		extend self
 
-		sig { returns(Example) }
+		# a simple decimal example
+		# @return [Example] the example
 		def simple
 			Example.new(
 				[:decimal],
@@ -20,7 +19,8 @@ module DataModel
 			)
 		end
 
-		sig { returns(Example) }
+		# a decimal example that is optional
+		# @return [Example] the example
 		def optional
 			Example.new(
 				[:decimal, { optional: true }],
@@ -30,7 +30,8 @@ module DataModel
 			)
 		end
 
-		sig { returns(Example) }
+		# a decimal example that has a restriction on the minimum value
+		# @return [Example] the example
 		def min
 			Example.new(
 				[:decimal, { min: 5 }],
@@ -41,7 +42,8 @@ module DataModel
 			)
 		end
 
-		sig { returns(Example) }
+		# a decimal example that has a restriction on the maximum value
+		# @return [Example] the example
 		def max
 			Example.new(
 				[:decimal, { max: 5 }],

data/lib/data_model/fixtures/boolean.rb

@@ -1,12 +1,11 @@
-# typed: strict
-
 module DataModel
+	# test fixtures for boolean type
 	module Fixtures::Boolean
-		extend T::Sig
 		extend self
 		include Fixtures
 
-		sig { returns(Example) }
+		# a simple boolean example
+		# @return [Example] the example
 		def simple
 			Example.new(
 				[:boolean],
@@ -19,7 +18,8 @@ module DataModel
 			)
 		end
 
-		sig { returns(Example) }
+		# a boolean example that is optional
+		# @return [Example] the example
 		def optional
 			Example.new(
 				[:boolean, { optional: true }],