data_model 0.3.0 → 0.5.0

data/lib/data_model/registry.rb

@@ -0,0 +1,129 @@
+module DataModel
+	# Registry allows for different type implementations to be used by the scanner.
+	# It also acts as an error message registry, mostly for pragmatic reasons.
+	class Registry
+		# Default types that will be used if alternative type map is not given
+		# @return [Hash] the default type map
+		def self.default_types
+			Builtin.types
+		end
+
+		# Default error messages that will be used if alternative error messages are not given
+		# @return [Hash] the default error messages
+		def self.default_error_messages
+			Errors.error_messages
+		end
+
+		# Singleton instance that will be used globally unless instances given
+		# @param types [Hash] the type map to use
+		# @param errors [Hash] the error message map to use
+		# @return [Registry] the singleton instance
+		def self.instance(types: default_types, errors: default_error_messages)
+			@instance ||= new(types:, errors:)
+		end
+
+		# Register a type on the global instance
+		# @param name [Symbol] the name of the type
+		# @param type [Type] the type to register
+		# @return [void]
+		def self.register(name, type)
+			instance.register(name, type)
+		end
+
+		# Instanciate a new type registry. Default errors will always be used, but additional
+		# errors can be registered.
+		# @param types [Hash] the type map to use
+		# @param errors [Hash] the error message map to use
+		# @return [Registry] the new instance
+		def initialize(types: self.class.default_types, errors: self.class.default_error_messages)
+			@error_messages = nil
+
+			if errors
+				errors.each { |type, builder| register_error_message(type, &builder) }
+			end
+
+			@types = {}
+			types.each { |(name, type)| register(name, type) }
+		end
+
+		# Register a type on this instance
+		# @param name [Symbol] the name of the Type
+		# @param type [Type] the type to register
+		# @return [void]
+		def register(name, type)
+			@types[name] = type
+		end
+
+		# Check if a type is registered
+		# @param name [Symbol] the name of the type
+		# @return [Boolean] whether the type is registered
+		def type?(name)
+			@types.key?(name)
+		end
+
+		# Access and configure registered type
+		# @param name [Symbol] the name of the Type
+		# @param args [Hash] the arguments to pass to the Type
+		# @param params [Array] the parameters to configure the Type with
+		# @return [Type] the configured type
+		def type(name, args: {}, params: nil)
+			if !type?(name)
+				raise "#{name} is not registered as a type"
+			end
+
+			t = @types.fetch(name).new(args, registry: self)
+
+			if params
+				t.configure(params)
+			end
+
+			return t
+		end
+
+		## API
+
+		# Register a custom error message for use with custom errors
+		# @param type [Symbol] the type of error to register
+		# @param block [Proc] the block to use to build the error message, shoudl take the error context and return a string
+		# @return [void]
+		def register_error_message(type, &block)
+			error_message_builders[type] = block
+		end
+
+		# Get the error message builders
+		# @return [Hash] the error message builders
+		def error_message_builders
+			if @error_messages.nil?
+				@error_messages ||= {}
+			end
+
+			@error_messages
+		end
+
+		# Build the error message for a given error
+		# @param error [Error] the error to build the message for
+		# @return [String] the error message
+		# @raise [RuntimeError] if no error message builder is registered for the error type
+		def error_message(error)
+			type = error[0]
+			ctx = error[1]
+
+			builder = error_message_builders[type]
+
+			if builder.nil?
+				raise "no error message builder for #{type}"
+			end
+
+			builder.call(ctx)
+		end
+
+		# Build error messages from error object
+		# @param error [Error] the error to build the messages for
+		# @return [Hash] the error messages
+		def error_messages(error)
+			error.to_h.transform_values do |error_list|
+				error_list.map { |e| error_message(e) }
+			end
+		end
+	end
+end

data/lib/data_model/scanner.rb

@@ -1,43 +1,37 @@
-# typed: strict
-
-# Scan a schema into a struct that can be inspected to construct a model validator
-#
-# schema eg:
-# 	[:string, { min: 1, max: 10}]
-# 	[:tuple, { title: "coordinates" }, :double, :double]
-# 	[:hash, { open: false },
-# 		[:first_name, :string]
-# 		[:last_name, :string]]
-#
-# first param is type, which is a key lookup in the registry
-# second param is args, this is optional, but is a way to configure a type
-# rest are type params. these are used to configure a type at the point of instantiation. Think of them as generics.
-#
-# params are either
-# 	symbol, for example tuple types
-#   array, for object types to configure child properties.
 module DataModel
+	# The scanner is responsible for scanning a schema into a data structure that is easier to work with.
+	#
+	# schema eg:
+	# 	[:string, { min: 1, max: 10}]
+	# 	[:tuple, { title: "coordinates" }, :double, :double]
+	# 	[:hash, { open: false },
+	# 		[:first_name, :string]
+	# 		[:last_name, :string]]
+	#
+	# first param is type, which is a key lookup in the registry
+	# second param is args, this is optional, but is a way to configure a type
+	# rest are type params. these are used to configure a type at the point of instantiation. Think of them as generics.
+	#
+	# params are either
+	# 	symbol, for example tuple types
+	#   array, for object types to configure child properties.
 	module Scanner
-		include Kernel
 		include Logging
-
-		extend T::Sig
 		extend self
 
-		class Node < T::Struct
-			prop :type, Symbol, default: :nothing
-			prop :args, T::Hash[Symbol, Object], default: {}
-			prop :params, T::Array[Object], default: []
-		end
+		# cant use DataModel::Struct because it would be a circular dependency
+		Node = ::Struct.new(:type, :args, :params)
 
 		# Scan a schema, which is defined as a data structure, into a struct that is easier to work with.
 		# "Syntax" validations will be enforced at this level.
-		sig { params(schema: TSchema, registry: DataModel::TypeRegistry).returns(Node) }
-		def scan(schema, registry = TypeRegistry.instance)
+		# @param schema [Array] the schema to scan
+		# @param registry [Registry] the registry to use
+		# @return [Node] the scanned node
+		def scan(schema, registry = Registry.instance)
 			# state:
 			# 	nil (start) -> :type (we have a type) -> :args (we have arguments)
 			scanned = Node.new
-			state = T.let(nil, T.nilable(Symbol))
+			state = nil
 
 			log.debug("scanning schema: #{schema.inspect}")
 
@@ -61,6 +55,7 @@ module DataModel
 						raise "expected type params at (#{dbg}), which should be either a symbol or an array"
 					end
 
+					scanned.params ||= []
 					scanned.params << token
 					log.debug("collecting params at (#{dbg})")
 

data/lib/data_model/struct.rb

@@ -0,0 +1,112 @@
+module DataModel
+	# A struct that has typed properties, which will raise when the wrong type is assigned
+	class Struct
+		class << self
+			# types configured by the prop macro
+			# @return [Hash] the types configured
+			attr_reader :types
+
+			# required types configured by the prop macro
+			# @return [Array<Symbol>] the required types configured
+			attr_reader :required_types
+		end
+
+		# Define a property on the struct.
+		# @param name [Symbol] the name of the property
+		# @param schema [Array] the schema to define
+		# @option opts [Boolean] :default the default value for the property
+		# @return [void]
+		def self.prop(name, schema, opts = {})
+			has_default = opts.key?(:default)
+			default = opts[:default]
+
+			# ensure values are initialized
+			@types ||= {}
+			@required_types ||= []
+
+			# if a prop does not have a default, it is required
+			if !has_default
+				@required_types << name
+			end
+
+			# store the data model for the prop
+			schema = Array(schema)
+			@types[name] = DataModel.define(schema)
+
+			# field getter
+			define_method(name) do
+				@values ||= {}
+				types = self.class.types
+
+				if !types.key?(name)
+					raise "No prop configured for #{name}"
+				end
+
+				if !@values.key?(name) && has_default
+					return default
+				end
+
+				return @values[name]
+			end
+
+			# field setter
+			define_method("#{name}=") do |val|
+				@values ||= {}
+				types = self.class.types
+
+				if !types.key?(name)
+					raise "No prop configured for #{name}"
+				end
+
+				model = types.fetch(name)
+
+				if @coerce
+					val, err = model.coerce(val)
+				else
+					err = model.validate(val)
+				end
+
+				if @strict && err.any?
+					errors.merge_child(prop, err)
+					raise "Invalid value for #{name}: #{err.to_messages.inspect}"
+				end
+
+				@values[name] = val
+			end
+		end
+
+		# @return [Error] the errors for this struct
+		attr_reader :errors
+
+		# @param data [Hash] the data to initialize the struct with
+		# @param coerce [Boolean] whether to coerce the data if it is not correctly typed
+		# @param strict [Boolean] whether to raise if a required field is missing
+		# @return [void]
+		def initialize(data = {}, coerce: false, strict: true)
+			@coerce = coerce
+			@strict = strict
+			@values = {}
+			@errors = Error.new
+
+			if data.nil?
+				return
+			end
+
+			for k, v in data
+				send("#{k}=", v)
+			end
+
+			for req in self.class.required_types
+				if !data.key?(req)
+					raise "Missing required field #{req}"
+				end
+			end
+		end
+
+		# convert struct to a hash
+		# @return [Hash] the struct as a hash
+		def to_hash
+			@values
+		end
+	end
+end

data/lib/data_model/testing/minitest.rb

@@ -1,15 +1,18 @@
-# typed: strict
-
 require "minitest/assertions"
 
 module DataModel
+	# Provides assertions for minitest
 	module Testing::Minitest
-		extend T::Sig
 		include Minitest::Assertions
-		include Kernel
 
-		sig { params(err: Error, type: Symbol, key: T.nilable(Symbol)).void }
+		# Assert that a child model error was found.
+		# @param err [Error] the error to check
+		# @param type [Symbol] the type of error to check for
+		# @param key [Array(Symbol)] limit checking to a specific child key
+		# @return [void]
 		def assert_child_model_error(err, type, key = nil)
+			refute_nil(err)
+
 			assert(err.children.any?, "validate was successful, but should not have been")
 
 			for k in key ? [key] : err.children.keys
@@ -18,8 +21,13 @@ module DataModel
 			end
 		end
 
-		sig { params(err: Error, type: Symbol).void }
+		# Assert that a model error was found.
+		# @param err [Error] the error to check
+		# @param type [Symbol] the type of error to check for
+		# @return [void]
 		def assert_model_error(err, type)
+			refute_nil err
+
 			assert(err.base.any?, "validate was successful, but should not have been")
 
 			found = err.base.any? { |(t, _ctx)| t == type }
@@ -27,8 +35,14 @@ module DataModel
 			assert(found, "validation was not successful, but #{type} error was not found #{err.inspect}")
 		end
 
-		sig { params(err: Error, type: T.nilable(Symbol), key: T.nilable(Symbol)).void }
+		# Assert that no child error is found
+		# @param err [Error] the error to check
+		# @param type [Symbol] the type of error to check for
+		# @param key [Symbol, Array<Symbol>] limit checking to a specific child key
+		# @return [void]
 		def refute_child_model_error(err, type = nil, key = nil)
+			refute_nil(err)
+
 			if !err.any?
 				return
 			end
@@ -44,8 +58,13 @@ module DataModel
 			end
 		end
 
-		sig { params(err: Error, type: T.nilable(Symbol)).void }
+		# Assert that no base error is present
+		# @param err [Error] the error to check
+		# @param type [Symbol] the type of error to check for
+		# @return [void]
 		def refute_model_error(err, type = nil)
+			refute_nil(err)
+
 			if !err.any?
 				return
 			end
@@ -60,8 +79,13 @@ module DataModel
 			refute(found, "#{type} error was found #{err.inspect}")
 		end
 
-		sig { params(err: Error, type: T.nilable(Symbol)).void }
+		# Assert that no errors are present
+		# @param err [Error] the error to check
+		# @param type [Symbol] the type of error to check for
+		# @return [void]
 		def refute_all_errors(err, type = nil)
+			refute_nil(err)
+
 			if !err.any?
 				return
 			end

data/lib/data_model/testing.rb

@@ -1,5 +1,3 @@
-# typed: strict
-
 module DataModel
 	module Testing
 	end

data/lib/data_model/type.rb

@@ -1,32 +1,36 @@
-# typed: strict
-
-# Mixin included on every type. Type::Generic and Type::Parent are higher level specializations.
 module DataModel
+	# @abstract Base class for all types.
+	# Types have arguments, which configure the act of reading / validating / coercing data.
+	# They also have parameters, which configure the type itself, such as generic or child specification
+	# Arguments are passed to the type when it is invoked, and parameters are passed to the type when it is configured.
+	# Parameters are really only used in complex types, such as Array or Hash. If you don't need them, you can ignore them.
 	class Type
-		extend T::Sig
-		extend T::Helpers
-
-		abstract!
-
-		TArguments = T.type_alias { T::Hash[Symbol, T.untyped] }
-		TTypeParams = T.type_alias { T::Array[Object] }
-		TTypeResult = T.type_alias { [Object, Error] }
-
-		sig { params(args: TArguments, registry: TypeRegistry).void }
-		def initialize(args, registry: TypeRegistry.instance)
+		# @param args [Hash] type arguments, configures the reading process
+		# @param registry [Registry] the registry to use
+		# @return [void]
+		def initialize(args, registry: Registry.instance)
 			@type_args = args
 			@type_registry = registry
 		end
 
-		sig { returns(TArguments) }
+		# @return [Hash] the type arguments
 		attr_reader :type_args
 
-		# configure must be overridden to use params
-		sig { overridable.params(params: TTypeParams).void }
+		# @return [Registry] the type Registry
+		attr_reader :type_registry
+
+		# configure must be overridden to use params. If you don't need params, you can ignore this.
+		# @param params [Array] type parameters, configures the type itself
+		# @return [void]
 		def configure(params); end
 
-		# invoke another type by name
-		sig { params(name: Symbol, val: Object, coerce: T::Boolean, args: Type::TArguments, params: T.nilable(TTypeParams)).returns(TTypeResult) }
+		# invoke another type by name. This is useful for specifying types like UUIDs which are specialized strings
+		# @param name [Symbol] the name of the type to invoke
+		# @param val [Object] the value to read
+		# @param coerce [Boolean] whether to coerce the value
+		# @param args [Hash] type arguments, configures the reading process
+		# @param params [Array] type parameters, configures the type itself
+		# @return [Array(Object, Error)] the result of reading the value
 		def invoke(name, val, coerce: false, args: {}, params: nil)
 			t = instantiate(name, args:, params:)
 
@@ -35,16 +39,28 @@ module DataModel
 			return result
 		end
 
-		# instanciate another type
-		sig { params(name: Symbol, args: Type::TArguments, params: T.nilable(TTypeParams)).returns(Type) }
+		# instanciate another type by name
+		# @param name [Symbol] the name of the type to instantiate
+		# @param args [Hash] type arguments, configures the reading Process
+		# @param params [Array] type parameters, configures the type itself
+		# @return [Type] the instantiated type
 		def instantiate(name, args: {}, params: nil)
 			t = @type_registry.type(name, args:, params:)
 
 			return t
 		end
 
-		# default reader
-		sig { abstract.params(data: Object, coerce: T::Boolean).returns(TTypeResult) }
+		# @abstract default reader, must be overridden for a type to be useful
+		# @param data [untyped] the data to read
+		# @param coerce [Boolean] whether to coerce the value
+		# @return [Array(Object, Error)] the result of reading the value
 		def read(data, coerce: false); end
+
+		# name of the type without module prefix as a string
+		# useful for generating error messages
+		# @return [String] the type name
+		def type_name
+			@type_name ||= self.class.name.split("::").last
+		end
 	end
 end

data/lib/data_model/version.rb

@@ -1,5 +1,3 @@
-# typed: strict
-
 module DataModel
-	VERSION = "0.3.0"
+	VERSION = "0.5.0"
 end

data/lib/data_model.rb

@@ -1,5 +1,3 @@
-# typed: strict
-
 require "logger"
 require "bigdecimal"
 require "date"
@@ -7,28 +5,18 @@ require "time"
 
 require "bundler/setup"
 require "zeitwerk"
-require "sorbet-runtime"
 
-loader = T.let(Zeitwerk::Loader.for_gem, Zeitwerk::Loader)
+loader = Zeitwerk::Loader.for_gem
 loader.setup
 
 module DataModel
-	extend T::Sig
 	extend self
 
-	TSchema = T.type_alias { T::Array[Object] }
-	TData = T.type_alias { Object }
-
-	# an error is a tuple of [error_type, error_context], where context
-	# provides additional information about the error
-	TError = T.type_alias { [Symbol, Object] }
-
-	# a map of symbol => type, suitable for sending to a TypeRegistry
-	TTypeMap = T.type_alias { T::Hash[Symbol, T.class_of(Type)] }
-
 	# Scan a schema and create a data model, which is a configured type.
-	sig { params(schema: TSchema, registry: TypeRegistry).returns(Model) }
-	def define(schema, registry: TypeRegistry.instance)
+	# @param schema [Array] the schema to define
+	# @param registry [Registry] the registry to use
+	# @return [Model] the model built from the schema
+	def define(schema, registry: Registry.instance)
 		scanned = Scanner.scan(schema, registry)
 
 		type = registry.type(
@@ -42,8 +30,11 @@ module DataModel
 		return model
 	end
 
-	sig { params(name: Symbol, type: T.class_of(Type)).void }
+	# Register a global type, which is available to all models.
+	# @param name [Symbol] the name of the Type
+	# @param type [Type] the type to register
+	# @return [void]
 	def register_global_type(name, type)
-		TypeRegistry.register(name, type)
+		Registry.register(name, type)
 	end
 end