data_model 0.4.0 → 0.5.0

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::Registry).returns(Node) }
+		# @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: Registry).void }
+		# @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.4.0"
+	VERSION = "0.5.0"
 end

data/lib/data_model.rb

@@ -1,5 +1,3 @@
-# typed: strict
-
 require "logger"
 require "bigdecimal"
 require "date"
@@ -7,27 +5,17 @@ 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: Registry).returns(Model) }
+	# @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)
 
@@ -42,7 +30,10 @@ 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)
 		Registry.register(name, type)
 	end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: data_model
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Matt Briggs
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-05-18 00:00:00.000000000 Z
+date: 2023-05-30 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: sorbet
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -123,7 +109,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: sorbet-runtime
+  name: steep
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -162,10 +148,12 @@ files:
 - ".ruby-version"
 - ".shadowenv.d/.gitignore"
 - ".shadowenv.d/550-ruby.lisp"
+- ".solargraph.yml"
 - Gemfile
 - Gemfile.lock
 - Guardfile
 - Rakefile
+- Steepfile
 - data_model.gemspec
 - lib/data_model.rb
 - lib/data_model/boolean.rb
@@ -177,6 +165,9 @@ files:
 - lib/data_model/builtin/float.rb
 - lib/data_model/builtin/hash.rb
 - lib/data_model/builtin/integer.rb
+- lib/data_model/builtin/numeric.rb
+- lib/data_model/builtin/object.rb
+- lib/data_model/builtin/or.rb
 - lib/data_model/builtin/string.rb
 - lib/data_model/builtin/symbol.rb
 - lib/data_model/builtin/time.rb
@@ -190,6 +181,9 @@ files:
 - lib/data_model/fixtures/float.rb
 - lib/data_model/fixtures/hash.rb
 - lib/data_model/fixtures/integer.rb
+- lib/data_model/fixtures/numeric.rb
+- lib/data_model/fixtures/object.rb
+- lib/data_model/fixtures/or.rb
 - lib/data_model/fixtures/string.rb
 - lib/data_model/fixtures/symbol.rb
 - lib/data_model/fixtures/time.rb
@@ -197,18 +191,11 @@ files:
 - lib/data_model/model.rb
 - lib/data_model/registry.rb
 - lib/data_model/scanner.rb
+- lib/data_model/struct.rb
 - lib/data_model/testing.rb
 - lib/data_model/testing/minitest.rb
 - lib/data_model/type.rb
 - lib/data_model/version.rb
-- sorbet/config
-- sorbet/rbi/annotations/rainbow.rbi
-- sorbet/rbi/gems/minitest@5.18.0.rbi
-- sorbet/rbi/gems/zeitwerk.rbi
-- sorbet/rbi/gems/zeitwerk@2.6.7.rbi
-- sorbet/rbi/todo.rbi
-- sorbet/tapioca/config.yml
-- sorbet/tapioca/require.rb
 homepage: https://github.com/mbriggs/data_model
 licenses:
 - MIT

data/sorbet/config

@@ -1,4 +0,0 @@
---dir
-.
---ignore=/tmp/
---ignore=/vendor/bundle