data_model 0.4.0 → 0.5.0

data/lib/data_model/error.rb

@@ -1,34 +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
 		include Errors
 
-		TErrorList = T.type_alias { T::Array[TError] }
-		TErrorMap = T.type_alias { T::Hash[Symbol, TErrorList] }
-
-		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
@@ -36,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?
@@ -54,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
@@ -74,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
@@ -87,7 +97,9 @@ module DataModel
 			end
 		end
 
-		sig { params(registry: Registry).returns(T::Hash[Symbol, T::Array[String]]) }
+		# 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

data/lib/data_model/errors.rb

@@ -1,84 +1,96 @@
-# typed: strict
-
 module DataModel
 	# Provide Error building functionality as a mixin
 	module Errors
-		include Kernel
-		extend T::Sig
 		extend self
 
-		TTemporal = T.type_alias { T.any(::Date, ::Time, ::DateTime) }
-
 		## 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
@@ -86,139 +98,151 @@ 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
 
 		# Builders
 
-		TErrorMessageBuilder = T.type_alias { T.proc.params(ctx: T.untyped).returns(String) }
-		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 { [Errors::TTemporal, Errors::TTemporal] }
-		TFormatCtx = T.type_alias { [Object, String] }
-
 		# Get the error message builders
-		sig { returns(TErrorMessages) }
-		def self.error_messages
+		# @return [Hash{Symbol => Proc}] the error message builders
+		def error_messages
 			return {
 				type: lambda do |ctx|
-					cls, val = T.let(ctx, TClassValueCtx)
+					cls, val = ctx
 					type_error_message(cls, val)
 				end,
 
 				coerce: lambda do |ctx|
-					cls, val = T.let(ctx, TClassValueCtx)
+					cls, val = ctx
 					type_error_message(cls, val)
 				end,
 
 				missing: lambda do |ctx|
-					cls = T.let(ctx, TClassCtx)
+					cls = ctx
 					missing_error_message(cls)
 				end,
 
 				inclusion: lambda do |ctx|
-					set = T.let(ctx, TSetCtx)
+					set = ctx
 					inclusion_error_message(set)
 				end,
 
 				exclusion: lambda do |ctx|
-					set = T.let(ctx, TSetCtx)
+					set = ctx
 					exclusion_error_message(set)
 				end,
 
 				extra_keys: lambda do |ctx|
-					set = T.let(ctx, TSetCtx)
+					set = ctx
 					extra_keys_error_message(set)
 				end,
 
 				min: lambda do |ctx|
-					min, val = T.let(ctx, TWithinCtx)
+					min, val = ctx
 					min_error_message(min, val)
 				end,
 
 				max: lambda do |ctx|
-					max, val = T.let(ctx, TWithinCtx)
+					max, val = ctx
 					max_error_message(max, val)
 				end,
 
 				earliest: lambda do |ctx|
-					earliest, val = T.let(ctx, TWithinTemporalCtx)
+					earliest, val = ctx
 					early_error_message(earliest, val)
 				end,
 
 				latest: lambda do |ctx|
-					latest, val = T.let(ctx, TWithinTemporalCtx)
+					latest, val = ctx
 					late_error_message(latest, val)
 				end,
 
@@ -227,7 +251,7 @@ module DataModel
 				end,
 
 				format: lambda do |ctx|
-					format, val = T.let(ctx, TFormatCtx)
+					format, val = ctx
 					format_error_message(format, val)
 				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 }],

data/lib/data_model/fixtures/date.rb

@@ -1,22 +1,20 @@
-# typed: strict
-
 module DataModel
+	# Provides fixtures for testing date types
 	module Fixtures::Date
-		extend T::Sig
-		extend self
 		include Fixtures
+		extend self
 
-		sig { returns(::Date) }
+		# @return [Date] a date that is used by the #earliest example
 		def earliest_date
 			return ::Date.today - 1
 		end
 
-		sig { returns(::Date) }
+		# @return [Date] a date that is used by the #latest example
 		def latest_date
 			return ::Date.today + 1
 		end
 
-		sig { returns(T::Hash[Symbol, Object]) }
+		# @return [Hash{Symbol => untyped}] the variants used by each example
 		def variants
 			today = ::Date.today
 
@@ -30,22 +28,26 @@ module DataModel
 			}
 		end
 
-		sig { returns(Example) }
+		# A simple date schema
+		# @return [Example] the example
 		def simple
 			Example.new([:date], variants:)
 		end
 
-		sig { returns(Example) }
+		# A date schema that is optional
+		# @return [Example] the example
 		def optional
 			Example.new([:date, { optional: true }], variants:)
 		end
 
-		sig { returns(Example) }
+		# A date schema that has a restriction on the earliest date
+		# @return [Example] the example
 		def earliest
 			Example.new([:date, { earliest: earliest_date }], variants:)
 		end
 
-		sig { returns(Example) }
+		# A date schema that has a restriction on the latest date
+		# @return [Example] the example
 		def latest
 			Example.new([:date, { latest: latest_date }], variants:)
 		end

data/lib/data_model/fixtures/example.rb

@@ -1,21 +1,21 @@
-# typed: strict
-
 module DataModel
+	# A simple abstraction to handle test data
 	class Fixtures::Example
-		extend T::Sig
-
-		sig { params(schema: TSchema, variants: T::Hash[::Symbol, Object]).void }
+		# @param schema [Array] the schema
+		# @param variants [Hash{Symbol => untyped}] the variants used by each example
+		# @return [Schema] the schema
 		def initialize(schema, variants:)
 			@schema = schema
 			@variants = variants
 		end
 
-		sig { returns(Model) }
+		# @return [Model] the model
 		def model
 			DataModel.define(@schema)
 		end
 
-		sig { params(type: Symbol).returns([Model, Object]) }
+		# @param type [Symbol] the variant to use
+		# @return [Array(Model, untyped)] a tuple of [model, variant]
 		def [](type)
 			if !@variants.key?(type)
 				raise "#{type} is not a defined variant: #{@variants}"