key-vortex 0.2.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9696a877879c820dd96922f5f300b3367fae4cc7ce37c92db6efffe32e5f3f11
-  data.tar.gz: 46ac4d73acc9dbef6d60e767f8d0f8a0dcfd7a44baf56a874b60aaa3634cdc97
+  metadata.gz: ccc7720fa67e489fa24c0158866cfde5be930f1b0f68ccc04b94b77e193b69f1
+  data.tar.gz: 350476269a57fed2af54c84ccd887d828f0804d287445b1133b67d2a4b66ce7c
 SHA512:
-  metadata.gz: e2401b6a3d3d73d7122054d7511c466865d12ae2572439c9aa3905c8a255e16b3aceeb38565c214ec33c991d6b8525252c35614273f96be094b50d155b8d3235
-  data.tar.gz: 9ad900f47bd8756ac9a9bdbd2d2810bc76d96660fdbecdad0c6762ee305b4ea7f4054610119b4fb752dbdb8aac52f1f76efc229e4c6dc735beecec51c7005650
+  metadata.gz: 21a080f1f96c1d2aa6dde92071f3b5df4d73e96d11207a4cca025ad4c01be5f8f93fc4567da53087645c58f3d2d74afbede919e3ef45bc2cc63e3fe85a0341b0
+  data.tar.gz: 2c73b0c9eeae66681633c15d887c595c86aa468afed4dec676ca5527466908f33e4d084494da2dae682ed87cae82e2255ba82941d303fad57d504836225bea5a

data/.reek.yml

@@ -1,9 +1,13 @@
 detectors:
-  # TODO: Remove once design is set
   IrresponsibleModule:
-    enabled: false
+    exclude:
+      - AnotherRecordOne
+      - RecordOne
+      - RecordTwo
+      - BasicRecord
+      - BigStringRecord
 
   DuplicateMethodCall:
     exclude:
-      - KeyVortex::Record#self.define_getter
-      - KeyVortex::Record#self.define_setter
+      - KeyVortex::Record#define_getter
+      - KeyVortex::Record#define_setter

data/.rubocop.yml

@@ -13,10 +13,6 @@ Style/StringLiteralsInInterpolation:
 Layout/LineLength:
   Max: 120
 
-# TODO: Remove once design is set
-Style/Documentation:
-  Enabled: false
-
 Metrics/BlockLength:
   AllowedMethods:
     - describe

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/Gemfile

@@ -15,8 +15,10 @@ gem "guard"
 gem "guard-reek"
 gem "guard-rspec"
 gem "guard-rubocop"
+gem "guard-yard"
 
 gem "byebug"
 gem "key_vortex-contract"
 
+gem "webrick"
 gem "yard"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    key-vortex (0.2.5)
+    key-vortex (1.0.0)
 
 GEM
   remote: https://rubygems.org/
@@ -32,8 +32,11 @@ GEM
     guard-rubocop (1.5.0)
       guard (~> 2.0)
       rubocop (< 2.0)
+    guard-yard (2.2.1)
+      guard (>= 1.1.0)
+      yard (>= 0.7.0)
     json (2.6.3)
-    key_vortex-contract (0.2.4)
+    key_vortex-contract (1.0.0)
       rantly (~> 2.0.0)
       rspec (~> 3.0)
     kwalify (0.7.2)
@@ -97,6 +100,7 @@ GEM
     shellany (0.0.1)
     thor (1.2.2)
     unicode-display_width (2.4.2)
+    webrick (1.8.1)
     yard (0.9.34)
 
 PLATFORMS
@@ -108,12 +112,14 @@ DEPENDENCIES
   guard-reek
   guard-rspec
   guard-rubocop
+  guard-yard
   key-vortex!
   key_vortex-contract
   rake (~> 13.0)
   reek (~> 6.1.4)
   rspec (~> 3.0)
   rubocop (~> 1.21)
+  webrick
   yard
 
 BUNDLED WITH

data/Guardfile

@@ -26,6 +26,12 @@
 #  * zeus: 'zeus rspec' (requires the server to be started separately)
 #  * 'just' rspec: 'rspec'
 
+guard "yard" do
+  watch(%r{app/.+\.rb})
+  watch(%r{lib/.+\.rb})
+  watch(%r{ext/.+\.c})
+end
+
 group :red_green_refactor, halt_on_fail: true do
   guard :rspec, cmd: "bundle exec rspec", failed_mode: :focus, all_on_pass: true do
     require "guard/rspec/dsl"

data/README.md

@@ -2,67 +2,58 @@
 
 KeyVortex provides a common abstraction around storing records in various datastores. It allows for the use of different adapters depending on the environment, and provides constraints to protect programmatically against differing constraints between them.
 
-To start using KeyVortex, you'll need to define a record:
-
-```ruby
-require "key_vortex/record"
-
-class ExampleRecord < KeyVortex::Record
-	field :a, String, length: 20
-	field :b, Integer, maximum: 100
-end
-```
+## Installation
 
-Now you can use this object in various ways:
+Add this line to your application's Gemfile:
 
-```
-> record = ExampleRecord.new(key: "foo", a: "bar", b: 10)
-=> #<ExampleRecord:0x000055fe0b5fe538 @values={:key=>"foo", :a=>"bar", :b=>10}>
-> record.a
-=> "bar"
-> record.a = "baz"
-=> "baz"
-> record.a
-=> "baz"
-> record.b = 1000
-Invalid value 1000 for b (KeyVortex::Error)
-```
+	gem 'key-vortex'
 
-You may notice that a `key` field was defined as well. This can be a String up to 36 characters long, to accomodate a GUID if that's what you wish to use.
+And then execute:
 
-In order to save the record somewhere, you'll need to choose an adapter. To keep dependencies down, these will generally be implemented in other gems, but an in memory adapter does ship with this gem.
+    $ bundle install
 
-```
-> require "key_vortex/adapter/memory"
-> vortex = KeyVortex.vortex(:memory, ExampleRecord)
-> vortex.save(ExampleRecord.new(key: "foo", a: "a", b: 10))
-> vortex.find("foo")
-=> #<ExampleRecord:0x0000560781f480b0 @values={:key=>"foo", :a=>"a", :b=>10}>
-```
+Or install it yourself as:
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/key_vortex`. To experiment with that code, run `bin/console` for an interactive prompt.
+    $ gem install key-vortex
 
-TODO: Delete this and the text above, and describe your gem
+## Usage
 
-## Installation
+To start using KeyVortex, you'll need to define a [record](https://rubydoc.info/gems/key-vortex/KeyVortex/Record/):
 
-Add this line to your application's Gemfile:
+	require "key_vortex/record"
 
-```ruby
-gem 'key-vortex'
-```
+	class ExampleRecord < KeyVortex::Record
+		field :a, String, length: 20
+		field :b, Integer, maximum: 100
+	end
 
-And then execute:
+Now you can use this object in various ways:
 
-    $ bundle install
+	> record = ExampleRecord.new(key: "foo", a: "bar", b: 10)
+	=> #<ExampleRecord:0x000055fe0b5fe538 @values={:key=>"foo", :a=>"bar", :b=>10}>
+	> record.a
+	=> "bar"
+	> record.a = "baz"
+	=> "baz"
+	> record.a
+	=> "baz"
+	> record.b = 1000
+	Invalid value 1000 for b (KeyVortex::Error)
 
-Or install it yourself as:
+You may notice that a `key` field was defined as well. This can be a String up to 36 characters long, to accomodate a GUID if that's what you wish to use.
 
-    $ gem install key-vortex
+In order to save the record somewhere, you'll need to choose an [adapter](https://rubydoc.info/gems/key-vortex/KeyVortex/Adapter).
 
-## Usage
+	> require "key_vortex/adapter/memory"
+	> vortex = KeyVortex.vortex(:memory, ExampleRecord)
+	> vortex.save(ExampleRecord.new(key: "foo", a: "a", b: 10))
+	> vortex.find("foo")
+	=> #<ExampleRecord:0x0000560781f480b0 @values={:key=>"foo", :a=>"a", :b=>10}>
+	> vortex.remove("foo")
+	> vortex.find("foo")
+	=> nil
 
-TODO: Write usage instructions here
+As you can see, you have the ability to `save`, `find` and `remove` records. Once a record is saved, it can be referenced by the `key`.
 
 ## Development
 
@@ -72,7 +63,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/key-vortex. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/key-vortex/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/Lambda-Null/key-vortex. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/Lambda-Null/key-vortex/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -80,4 +71,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the KeyVortex project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/key-vortex/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the KeyVortex project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/Lambda-Null/key-vortex/blob/main/CODE_OF_CONDUCT.md).

data/lib/key_vortex/adapter/memory.rb

@@ -5,25 +5,45 @@ require "key_vortex/adapter"
 
 class KeyVortex
   class Adapter
+    # An in-memory implementation of an adapter. While typically not
+    # useful in production, it can provide a convenient implementation
+    # for unit testing.
     class Memory < KeyVortex::Adapter
+      # A pass-through to the constructor which is used by
+      # {KeyVortex.vortex}.
+      # @param items [Hash]
+      # @param limitations [Array of KeyVortex::Limitation]
+      # @return [KeyVortex::Adapter::Memory]
       def self.build(items: {}, limitations: [])
         new(items, limitations: limitations)
       end
 
+      # Create a new instance of the in-memory adapter. By default, it
+      # has no limitations, but since it's most likely testing an
+      # adapter which is more restrictive, it accepts a list of
+      # limitations to apply.
+      # @param items [Hash] The seed values that should be considered already saved.
+      # @param limitations [Array of KeyVortex::Limitation]
       def initialize(items, limitations: [])
         super()
         @items = items
         limitations.each { |limit| register_limitation(limit) }
       end
 
+      # Save the record to the provided hash using {Record#key} as the
+      # key.
+      # @param record [Record]
       def save(record)
         @items[record.key] = record
       end
 
-      def find(id)
-        @items[id]
+      # @param key [String]
+      # @return [Record, nil] The record with {Record#key} set to key
+      def find(key)
+        @items[key]
       end
 
+      # Remove the record with {Record#key} set to key
       def remove(key)
         @items.delete(key)
       end

data/lib/key_vortex/adapter.rb

@@ -1,19 +1,54 @@
 # frozen_string_literal: true
 
 class KeyVortex
+  # Adapters bridge the gap between the main logic of KeyVortex and
+  # individual backends. When using a backend, it can have various
+  # limitations on particular data types. KeyVortex will guarantee that
+  # these limitations are more permissive then the Records used to
+  # interact with it.
+  #
+  # To keep dependencies down, the subclasses you'll actually use will
+  # be implemented in other gems, but an in memory adapter does ship
+  # with this gem.  Here are some that are available:
+  #
+  # * {https://github.com/Lambda-Null/key_vortex-stashify Stashify}: File/blob storage
+  #
+  # == Building Adapters
+  #
+  # For an adapter to work with KeyVortex, it needs to inherit from
+  # this class. In addition, it needs to override the following
+  # methods:
+  #
+  # * save({KeyVortex::Record}) => Anything
+  # * find(String) => {KeyVortex::Record}
+  # * remove(String) => Anything
+  #
+  # There is {https://github.com/Lambda-Null/key_vortex-contract a separate gem},
+  # which provides a set of shared examples enforcing the correct
+  # behavior of those methods. PRs to include your gem in the list in
+  # the previous section will be accepted if they conform to that
+  # contract.
   class Adapter
     def initialize
       @limitations = {}
     end
 
+    # Get the limitation for the type of a given field.
+    # @param field [KeyVortex::Field]
+    # @return [KeyVortex::Limitation]
     def limitation_for(field)
       @limitations[field.limitation.type]
     end
 
+    # Apply the provided limitation to the adapter.
+    # @param limitation [KeyVortex::Limitation]
     def register_limitation(limitation)
       @limitations[limitation.type] = limitation
     end
 
+    # Provide the symbol used when using the factory method
+    # {KeyVortex.vortex}.
+    # @return [Symbol] A symbol representing this class
     def self.symbol
       name.split(":").last.downcase.to_sym
     end

data/lib/key_vortex/constraint/base.rb

@@ -1,16 +1,31 @@
 # frozen_string_literal: true
 
 class KeyVortex
-  class Constraint
+  module Constraint
+    # Base class all other constraints inherit from. Does not define
+    # all of the properties necessary for a constraint, and so is
+    # inappropriate to be used directly.
     class Base
+      # Comparing constraints is only valid when compared to other
+      # instances of the same constraint. This helps other parts of
+      # the system determine if this is true.
+      # @param constraint [Base]
+      # @return [Boolean]
       def applies_to?(constraint)
         attribute == constraint.attribute
       end
 
+      # The individual constraint is responsible for making the
+      # ultimate determination of if it is within another
+      # constraint. What's common to all of them, though, is that they
+      # must be the same class.
       def within?(constraint)
         constraint.instance_of?(self.class)
       end
 
+      # A text description of the constraint. Assumes subclasses
+      # define the methods attribute and limit.
+      # @return [String]
       def to_s
         "#{attribute}: #{limit}"
       end

data/lib/key_vortex/constraint/length.rb

@@ -3,23 +3,32 @@
 require "key_vortex/constraint/base"
 
 class KeyVortex
-  class Constraint
+  module Constraint
+    # Enforces that objects which respond to #length less than the
+    # specified limit.
     class Length < KeyVortex::Constraint::Base
+      # @return [Integer] The upper bound allowed when calling #length on a value
       attr_reader :limit
 
+      # @param limit [Integer] The maximum allowed value
       def initialize(limit)
         super()
         @limit = limit
       end
 
+      # @return [Symbol] :length
       def attribute
         :length
       end
 
+      # @param constraint [Length]
+      # @return [Boolean] True if limit <= constraint.limit
       def within?(constraint)
         super && limit <= constraint.limit
       end
 
+      # @param value [Object] Must respond to #length
+      # @return [Boolean] True if length <= limit
       def accepts?(value)
         value.length <= limit
       end

data/lib/key_vortex/constraint/maximum.rb

@@ -3,23 +3,32 @@
 require "key_vortex/constraint/base"
 
 class KeyVortex
-  class Constraint
+  module Constraint
+    # Enforces that objects which respond to #<= are less than the
+    # defined limit.
     class Maximum < KeyVortex::Constraint::Base
+      # @return [Integer] The maximum allowed value
       attr_reader :limit
 
+      # @param limit [Integer] The maximum allowed value
       def initialize(limit)
         super()
         @limit = limit
       end
 
+      # @return [Symbol] :maximum
       def attribute
         :maximum
       end
 
+      # @param constraint [Maximum]
+      # @return [Boolean] True if limit <= constraint.limit
       def within?(constraint)
         super && limit <= constraint.limit
       end
 
+      # @param value [Object] Must respond to #<=
+      # @return [Boolean] True if value <= limit
       def accepts?(value)
         value <= limit
       end

data/lib/key_vortex/constraint/minimum.rb

@@ -3,23 +3,32 @@
 require "key_vortex/constraint/base"
 
 class KeyVortex
-  class Constraint
+  module Constraint
+    # Enforces that objects which respond to #>= are greater than the
+    # defined limit.
     class Minimum < KeyVortex::Constraint::Base
+      # @return [Integer] The minimum allowed value
       attr_reader :limit
 
+      # @param limit [Integer] The minimum allowed value
       def initialize(limit)
         super()
         @limit = limit
       end
 
+      # @return [Symbol] :minimum
       def attribute
-        :maximum
+        :minimum
       end
 
+      # @param constraint [Minimum]
+      # @return [Boolean] True if limit >= constraint.limit
       def within?(constraint)
         super && limit >= constraint.limit
       end
 
+      # @param value [Object] Must respond to #>=
+      # @return [Boolean] True if value >= limit
       def accepts?(value)
         value >= limit
       end

data/lib/key_vortex/constraint.rb

@@ -6,18 +6,55 @@ require "key_vortex/constraint/maximum"
 require "key_vortex/constraint/minimum"
 
 class KeyVortex
-  class Constraint
-    def self.build(attribute, value)
+  # Constraints define a restriction on the values which can be used
+  # for {KeyVortex::Record} and {KeyVortex::Adapter}. Although they
+  # are somewhat varied, they do have some common properties.
+  #
+  # All constraints have some sort of attribute name and limit. In
+  # most situations, instead of the constructor, this pair will be
+  # used to specify the constraint. For example, you would typically
+  # specify a length like this:
+  #
+  #  length: 10
+  #
+  # All constraints will inherit from
+  # {KeyVortex::Constraint::Base}. Because of the common ancestor,
+  # along with the need to have a single file loading all constraints,
+  # {KeyVortex::Constraint} is a module instead of the base class to
+  # avoid a circular dependency.
+  #
+  # All constraints can determine if a value is valid for them.
+  #
+  # All constraints, when compared with other instances of themselves,
+  # it can always be determined if ones limitations fit within the
+  # others. More formally, given an instance x of a constraint, an
+  # instance y of the same constraint fits within x if and only if for
+  # all values v that are valid for y, v is also valid for x.
+  module Constraint
+    # Factory enabling the specification of constraints by attribute
+    # names instead of constructors.
+    # @param attribute [Symbol]
+    # @param limit [Object]
+    # @return [KeyVortex::Constraint::Base] Subclass specified by attribute
+    # @raise [KeyVortex::Error] If the attribute is unknown
+    def self.build(attribute, limit)
       case attribute
       when :length
-        KeyVortex::Constraint::Length.new(value)
+        KeyVortex::Constraint::Length.new(limit)
       when :maximum
-        KeyVortex::Constraint::Maximum.new(value)
+        KeyVortex::Constraint::Maximum.new(limit)
       when :minimum
-        KeyVortex::Constraint::Minimum.new(value)
+        KeyVortex::Constraint::Minimum.new(limit)
       else
         raise KeyVortex::Error, "Unexpected attribute: #{attribute}"
       end
     end
   end
 end
+
+#
+# Adapters can also have constraints, though, and if a particular
+# type is more constrained then the record KeyVortex will refuse to
+# use that record. If you don't specify any constraints, for
+# example, the adapter will throw an error unless it is also
+# unconstrained on that type.

data/lib/key_vortex/field.rb

@@ -4,9 +4,23 @@ require "key_vortex/constraint"
 require "key_vortex/limitation"
 
 class KeyVortex
+  # Defines a value that can be set on a {Record}. This generally
+  # isn't built directly, you should use the {Record#field} directive
+  # most of the time. This class ties a name to a {Limitation}, and
+  # delegates most questions on to the latter.
   class Field
-    attr_reader :name, :limitation
+    # @return [Symbol] the name of the field
+    attr_reader :name
+    # @return [Limitation] the restrictions placed upon this field
+    attr_reader :limitation
 
+    # Creates an instance of this class and converts any
+    # attribute/limit constraint pairs into {KeyVortex::Constraint}
+    # objects.
+    # @param name [Symbol] Name of the field
+    # @param type [Class] Type used for limitation
+    # @param constraints_array [Constraint::Base] Any constraints already constructed can be passed in as well
+    # @param constraints_hash [Hash] key/value pairs that will be passed on to {Constraint#build}
     def initialize(name, type, *constraints_array, **constraints_hash)
       @name = name
       @limitation = KeyVortex::Limitation.new(type)
@@ -17,15 +31,20 @@ class KeyVortex
       end)
     end
 
+    # @param adapter [Adapter]
+    # @return [Boolean] true if the limitations for this field fit within the corresponding limitations for the adapter
     def within?(adapter)
       limitation = adapter.limitation_for(self)
       !limitation || self.limitation.within?(limitation)
     end
 
+    # @param value [Object]
+    # @return [Boolean] true if the value is valid for {#limitation}
     def accepts?(value)
       limitation.accepts?(value)
     end
 
+    # Enable JSON additions for the class used for this field.
     def enable_json_additions
       @limitation.enable_json_additions
     end

data/lib/key_vortex/limitation.rb

@@ -1,14 +1,37 @@
 # frozen_string_literal: true
 
 class KeyVortex
+  # Represents a collection of {KeyVortex::Constraint constraints}
+  # which apply to a given class. While these can be constructed
+  # directly, the intended mechanism for applying these to a record is
+  # through {KeyVortex::Record.field}.
+  #
+  # Two independent concepts which commonly use the same terminology
+  # exist in this project. Consider the term "allows", is that
+  # referring to what values are allowed or what constraints are
+  # allowed? To help navigate these two concepts, the following
+  # terminology convention is used throughout this codebase:
+  # * Encompass/Within: Used when comparing limitations and constraints to each other
+  # * Accepts/Rejects: Used when determining if a value is valid for constraints
   class Limitation
-    attr_reader :type, :constraints
+    # @return [Class] The class these constraints applies to.
+    attr_reader :type
 
+    # @return [Array] The constraints which apply to this class.
+    attr_reader :constraints
+
+    # @param type [Class]
+    # @param constraints [KeyValue::Constraint]
     def initialize(type, *constraints)
       @type = type
-      @constraints = constraints
+      @constraints = []
+      add_constraint(*constraints)
     end
 
+    # Add constraints to this limitation. It is also possible to do
+    # this through the constructor, but it is sometimes easier to do
+    # it one at a time.
+    # @param constraints [KeyVortex::Constraint::Base]
     def add_constraint(*constraints)
       constraints.each do |constraint|
         unless constraint.is_a?(KeyVortex::Constraint::Base)
@@ -20,24 +43,42 @@ class KeyVortex
       @constraints += constraints
     end
 
-    def encompasses?(limitation)
-      @constraints.all? do |constraint|
-        limitation.encompasses_constraint?(constraint)
+    # Determine if any of the constraints in the provided limitation
+    # exceed this limitation's constraints.
+    # @param limitation [KeyVortex::Limitation]
+    # @return [Boolean]
+    def within?(limitation)
+      limitation.constraints.all? do |constraint|
+        within_constraint?(constraint)
       end
     end
 
-    def encompasses_constraint?(constraint)
-      applicable_constraints(constraint).any? do |con|
-        con.within?(constraint)
-      end
+    # Determine if a given value meets all of the constraints.
+    # @param value [type]
+    # @return [Boolean]
+    def accepts?(value)
+      value.is_a?(type) && @constraints.all? { |constraint| constraint.accepts?(value) }
     end
 
-    def within?(limitation)
-      limitation.constraints.all? do |constraint|
-        within_constraint?(constraint)
-      end
+    # Ensure that JSON additions for {type} are loaded in case the
+    # record needs to be serialized.
+    def enable_json_additions
+      path = JSON_ADDITIONS[@type.class.name]
+      require path if path
+    end
+
+    # Return information about this limitation. The information will
+    # be formatted as follows:
+    #  Limitation: String
+    #    minimum: 10
+    #    maximum: 100
+    # @return [String]
+    def to_s
+      "Limitation: #{@type}\n\t#{@constraints.join('\n\t')}"
     end
 
+    private
+
     def within_constraint?(constraint)
       applicable_constraints(constraint).any? do |con|
         con.within?(constraint)
@@ -50,10 +91,6 @@ class KeyVortex
       end
     end
 
-    def accepts?(value)
-      value.is_a?(type) && @constraints.all? { |constraint| constraint.accepts?(value) }
-    end
-
     JSON_ADDITIONS = {
       BigDecimal: "json/add/bigdecimal",
       Complex: "json/add/complex",
@@ -69,14 +106,5 @@ class KeyVortex
       Symbol: "json/add/symbol",
       Time: "json/add/time"
     }.freeze
-
-    def enable_json_additions
-      path = JSON_ADDITIONS[@type.class.name]
-      require path if path
-    end
-
-    def to_s
-      "Limitation: #{@type}\n\t#{@constraints.join('\n\t')}"
-    end
   end
 end

data/lib/key_vortex/record.rb

@@ -6,54 +6,135 @@ require "key_vortex/field"
 require "key_vortex/limitation"
 
 class KeyVortex
+  # To represent a structured piece of information you want to save,
+  # it has to be a subclass of KeyVortex::Record. There will always be
+  # field named {#key}, which is at most 36 characters long, but keys
+  # with any other name can also be added.
+  #
+  #  class ExampleRecord < KeyVortex::Record
+  #    field :a, Integer, minimum: 10, maximum: 100
+  #    field :b, String, length: 100
+  #    field :c, Integer
+  #  end
+  #
+  # See {field} for more details on how those directives are
+  # structured. When you're ready to use the class, values can be
+  # provided either in the constructor like this:
+  #
+  #  ExampleRecord.new(
+  #    a: 15,
+  #    b: "foo",
+  #    c: 1000,
+  #  )
+  #
+  # Or set after the object is created like this:
+  #
+  #  r = ExampleRecord.new
+  #  r.a = 15
+  #  r.b = "foo"
+  #  r.c = 1000
+  #
+  # In either case, the values can be retrieved as attributes after
+  # they're set:
+  #
+  #  r.a # 15
+  #  r.b # "foo"
+  #  r.c # 1000
   class Record
-    def self.fields
-      field_hash.values
-    end
+    class << self
+      # @return [Array] All of the fields declared for this class.
+      def fields
+        field_hash.values
+      end
 
-    def self.field_hash
-      @field_hash ||= {}
-    end
+      # Declares what values are tracked by this record.
+      # When declaring a field, it follows this general format:
+      #
+      #   field :field_name, ClassName, constraint1: contraint1_value, constraint2: constraint2_value
+      #
+      # From a record's perspective any number of
+      # {KeyVortex::Constraint constraints} are valid, including none
+      # at all.
+      # @return [Field] The created field
+      def field(name, type, **constraints)
+        field = KeyVortex::Field.new(name, type, **constraints)
+        register_field(field)
+        field
+      end
 
-    def self.field(name, type, **constraints_hash)
-      register_field(KeyVortex::Field.new(name, type, **constraints_hash))
-    end
+      # Convert a json parse result into a record for this class. This
+      # is what's called when this command is used:
+      #
+      #   JSON.parse(json, create_additions: true)
+      #
+      # See {#to_json} for an example of the JSON structure this
+      # example expects.
+      # @return [Record] Subclasses will return an instance of themselves
+      def json_create(object)
+        new(object["values"])
+      end
 
-    def self.field_constraints(field)
-      @field_hash[field]
-    end
+      protected
 
-    def self.register_field(field)
-      field_hash[field.name] = field
-      field.enable_json_additions
-      define_getter(field)
-      define_setter(field)
-    end
+      def register_field(field)
+        field_hash[field.name] = field
+        field.enable_json_additions
+        define_getter(field)
+        define_setter(field)
+      end
 
-    def self.define_getter(field)
-      define_method(field.name) { @values[field.name] }
-    end
+      private
 
-    def self.define_setter(field)
-      define_method("#{field.name}=") do |val|
-        raise KeyVortex::Error, "Invalid value #{val} for #{field.name}" unless field.accepts?(val)
+      def field_hash
+        @field_hash ||= {}
+      end
 
-        @values[field.name] = val
+      def define_getter(field)
+        define_method(field.name) { @values[field.name] }
       end
-    end
 
-    def self.inherited(subclass)
-      super
-      fields.each do |field|
-        subclass.register_field(field)
+      def define_setter(field)
+        define_method("#{field.name}=") do |val|
+          raise KeyVortex::Error, "Invalid value #{val} for #{field.name}" unless field.accepts?(val)
+
+          @values[field.name] = val
+        end
+      end
+
+      def inherited(subclass)
+        super
+        fields.each do |field|
+          subclass.register_field(field)
+        end
       end
     end
 
-    # Long enough to accomodate a GUID
+    # @!attribute key
+    #   The key used to save and retrieve this record. Every field has
+    #   a key defined, it can be a String up to 36 characters long,
+    #   which is enough to accomodate a GUID if that's what you want
+    #   to use.
+    #   @return [String]
     field :key, String, length: 36
 
+    # A hash of all of the attributes, in which the keys are symbols.
+    # @example
+    #   {
+    #     a: 15,
+    #     b: "foo",
+    #     c: 1000,
+    #   }
+    #
+    # @return [Hash]
     attr_reader :values
 
+    # Values can optionally be specified when the object is created.
+    # @example
+    #  ExampleRecord.new(
+    #    a: 15,
+    #    b: "foo",
+    #    c: 1000,
+    #  )
     def initialize(values = {})
       @values = {}
       values.each do |name, value|
@@ -61,19 +142,33 @@ class KeyVortex
       end
     end
 
+    # Two records are equal if they are the same class and have the
+    # same values.
+    # @return [Boolean]
     def ==(other)
       self.class == other.class && values == other.values
     end
 
+    # Converts the record into a JSON string appropriate for parsing
+    # using the create_additions option. Here is an example of the
+    # format that's produced.
+    #
+    #   {
+    #     "json_class": "ExampleRecord",
+    #     "values": {
+    #       "key": "foo",
+    #       "a": 15,
+    #       "b": "bar",
+    #       "c": 1000
+    #     }
+    #   }
+    #
+    # @return [String] JSON representation of the object
     def to_json(*args)
       {
         JSON.create_id => self.class.name,
         "values" => @values
       }.to_json(*args)
     end
-
-    def self.json_create(object)
-      new(object["values"])
-    end
   end
 end

data/lib/key_vortex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class KeyVortex
-  VERSION = "0.2.5"
+  VERSION = "1.0.0"
 end

data/lib/key_vortex.rb

@@ -2,14 +2,29 @@
 
 require_relative "key_vortex/version"
 
+# Defines the API you'll interact with when using this gem. Much of
+# the functionality is delegated to other classes.
 class KeyVortex
+  # General purpose error used when issues arise within this gem.
   class Error < StandardError; end
 
+  # Register an adapter class so that {.vortex} knows about it.
+  # @param adapter_class [Class]
   def self.register(adapter_class)
     @adapter_registry ||= {}
     @adapter_registry[adapter_class.symbol] = adapter_class
   end
 
+  # Creates an instance of {KeyVortex} with an appropriate
+  # {Adapter}. An adapter class must have been associated with the
+  # adapter_symbol by calling {.register}, this should have been done
+  # by the file which defined that class. So, when you require
+  # "key_vortex/adapter/memory" the :memory symbol will be defined for
+  # use here.
+  # @param adapter_symbol [Symbol]
+  # @param record_class [Class] The class must inherit from {Record}
+  # @param options [Hash] Options that will be passed through to .build on the adapter
+  # @return [KeyVortex]
   def self.vortex(adapter_symbol, record_class, **options)
     new(
       @adapter_registry[adapter_symbol].build(**options),
@@ -17,8 +32,16 @@ class KeyVortex
     )
   end
 
-  attr_reader :adapter, :record_class
+  # @return [Adapter]
+  attr_reader :adapter
+  # @return [Class] Subclass of {Record}
+  attr_reader :record_class
 
+  # While you are able to create the object directly, it's easier to
+  # do so through {.vortex}.
+  # @param adapter [Adapter] The backend that will be used to save and retrieve records
+  # @param record_class [Class] The subclass of {Record} which will be saved and retreived
+  # @raise [Error] If the constraints of the record_class do not fit within the constraints of the adapter
   def initialize(adapter, record_class)
     @adapter = adapter
     @record_class = record_class
@@ -33,15 +56,25 @@ class KeyVortex
     end
   end
 
+  # Add the record to the {#adapter}. Once this is done, {#find} will
+  # return this record when passed the {Record#key}.
+  # @param record [Record] Must match {#record_class}
   def save(record)
     @adapter.save(record)
   end
 
-  def find(id)
-    @adapter.find(id)
+  # Retrieve a record that has had {#save} called on it.
+  # @param key [String]
+  # @return [Record] The {Record} with {Record#key} set to key
+  # @return [nil] if no record is found
+  def find(key)
+    @adapter.find(key)
   end
 
-  def remove(id)
-    @adapter.remove(id)
+  # Remove the {Record} with {Record#key} set to key from the
+  # {#adapter}.
+  # @param key [String]
+  def remove(key)
+    @adapter.remove(key)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: key-vortex
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 1.0.0
 platform: ruby
 authors:
 - Lambda Null
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-07-14 00:00:00.000000000 Z
+date: 2023-07-16 00:00:00.000000000 Z
 dependencies: []
 description: Defines abstractions that can be built on top of for key/value storage
   on different technologies (file, s3, sql, redis, etc.)
@@ -21,6 +21,7 @@ files:
 - ".reek.yml"
 - ".rspec"
 - ".rubocop.yml"
+- ".yardopts"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock