rndb 0.1.1

data/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

data/README.md

@@ -0,0 +1,96 @@
+[![test](https://github.com/kranzky/rndb/actions/workflows/test.yml/badge.svg)](https://github.com/kranzky/rndb/actions/workflows/test.yml)
+[![Coverage Status](https://coveralls.io/repos/github/kranzky/rndb/badge.svg?branch=main)](https://coveralls.io/github/kranzky/rndb?branch=main)
+
+# RnDB
+
+RnDB is a procedurally-generated fake database.
+
+## Usage
+
+First, create tables with columns that may have a pre-determined distribution of
+values (which can be queried on), or which may have a lambda for generating a
+random value, or both (such as for the `weight` column below).
+
+```
+class Widget < RnDB::Table
+  column :colour, { red: 0.3, green: 0.12, brown: 0.01, blue: 0.5, orange: 0.07 }
+  column :weight, { light: 0.3, medium: 0.64, heavy: 0.06 }, -> value do
+    range =
+      case value
+      when :light
+        (0.0..5.0)
+      when :medium
+        (6.0..9.0)
+      when :heavy
+        (10.0..20.0)
+      end
+    self.rand(range)
+  end
+  column :name, -> { Faker::Games::Pokemon.name }
+end
+```
+
+Next, create a database with an optional random seed (`137` in the example
+below), and add the table to the database, specifying the number of records to
+simulate (in this case, one trillion).
+
+```
+DB = RnDB::Database.new(137)
+DB.add_table(Widget, 1e12)
+```
+
+Finally, fetch some records!
+
+```
+puts Widget.count
+puts Widget[1234567890].name
+puts Widget.find { |widget| (3.1415..3.1416).include?(widget.weight) }.attributes
+```
+
+Which will display the following:
+
+```
+1000000000000
+Charmander
+{:id=>61520, :weight=>3.1415121332762386, :colour=>:red, :name=>"Exeggcute"}
+```
+
+Note that the `find` command tested over sixty thousand records in just a second
+or two without needing to generate all attributes of each record first. But an
+even faster way of honing in on a particular record is to run a query, such as:
+
+```
+query = Widget.where(colour: [:brown, :orange], :weight => :heavy)
+```
+
+You can then retrieve random records that match the query with `sample`, use
+`pluck` to retrieve specific attributes without generating all of them, and use
+`find` or `filter` to further refine your search, like this:
+
+```
+puts query.count
+puts query.sample.pluck(:colour, :weight)
+puts query.lazy.filter { |ball| ball.name == 'Pikachu' }.map(&:id).take(10).to_a
+```
+
+Which will display the following:
+
+```
+4800000000
+{:colour=>:orange, :weight=>16.096085279047017}
+[429400000068, 429400000087, 429400000875, 429400000885, 429400000914, 429400001036, 429400001062, 429400001330, 429400001341, 429400001438]
+```
+
+Note that we used the `lazy` enumerator when filtering records to prevent
+running the block on all records before performing the `map` and taking the
+first ten results.
+
+## Release Process
+
+1. `rake version:bump:whatever`
+2. `rake git:release BRANCH=main`
+3. Create new release on GitHub to trigger ship workflow
+
+## Copyright
+
+Copyright (c) 2021 Jason Hutchens. See LICENSE for further details.

data/Rakefile

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  warn e.message
+  warn "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+require 'juwelier'
+Juwelier::Tasks.new do |gem|
+  gem.name = "rndb"
+  gem.homepage = "https://github.com/kranzky/rndb"
+  gem.license = "Unlicense"
+  gem.summary = "RnDB is an procedurally-generated mock database."
+  gem.description = ""
+  gem.email = "lloyd@kranzky.com"
+  gem.authors = ["Lloyd Kranzky"]
+  gem.required_ruby_version = ">= 2.1"
+end
+Juwelier::RubygemsDotOrgTasks.new
+
+require 'yard'
+YARD::Rake::YardocTask.new
+
+task default: :clean

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/lib/rndb.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'rndb/database'
+require 'rndb/slice'
+require 'rndb/thicket'
+require 'rndb/table'
+require 'rndb/query'

data/lib/rndb/database.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RnDB
+  class Database
+    attr_accessor :prng
+    attr_reader :seed
+
+    # Opens a new fake database. A seed for the PRNG may be optionally supplied.
+    def initialize(seed=Time.now.to_i)
+      raise "database already open" unless Thread.current[:rndb_database].nil?
+      Thread.current[:rndb_database] = self
+      @prng = Random
+      @seed = seed
+    end
+
+    # Add a Table to the database, specifying the number of records to simulate.
+    def add_table(klass, size)
+      klass.send(:_migrate, size.to_i)
+    end
+
+    # Dump the table schemas as a hash.
+    def schema
+      Thread.current[:rndb_tables]
+    end
+  end
+end

data/lib/rndb/query.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RnDB
+  class Query
+    include Enumerable
+
+    # Query records of the given table based on the IDs in the supplied Thicket.
+    def initialize(table, ids)
+      @table, @ids = table, ids
+    end
+
+    # Delegate counting to the Thicket.
+    def count
+      @ids.count
+    end
+
+    # Retrieve the ID of an index into this query and use it to instantiate a record.
+    def [](index)
+      @table[@ids[index]]
+    end
+
+    # Implemented to be consistent with #first, which we get by magic.
+    def last
+      self[-1] unless count.zero?
+    end
+
+    # Delegate iteration to the Thicket, yielding records to the caller.
+    def each
+      @ids.each { |id| yield @table[id] }
+    end
+
+    # Return an array or a hash of plucked values, avoiding generation of all attributes.
+    def pluck(*args)
+      @ids.map do |id|
+        if args.count == 1
+          @table.value(id, args.first)
+        else
+          args.map do |attribute|
+            [attribute, @table.value(id, attribute)]
+          end.to_h
+        end
+      end
+    end
+
+    # Return a new query that takes a random sampling of IDs from the current query.
+    def sample(limit=1)
+      _db.prng.srand
+      self.class.new(@table, @ids.sample(limit, _db.prng))
+    end
+
+    private
+
+    def _db
+      Thread.current[:rndb_database]
+    end
+  end
+end

data/lib/rndb/slice.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RnDB
+  class Slice < Range
+    # A range that knows how to sort and intersect itself, private to Thickets.
+    def initialize(min, max)
+      super(min.to_i, max.to_i)
+    end
+
+    # Just in case the Range implementation is inefficient.
+    def count
+      max - min + 1
+    end
+
+    # Because Slices in a Thicket are disjoint, we can sort by min or max.
+    def <=>(other)
+      min <=> other.min
+    end
+
+    # We need to intersect slices when processing query constraints.
+    def &(other)
+      return nil if min > other.max || max < other.min
+      self.class.new([min, other.min].max, [max, other.max].min)
+    end
+  end
+end

data/lib/rndb/table.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'byebug'
+
+module RnDB
+  class Table
+    attr_reader :id
+
+    # Create a new record wit the given ID.
+    def initialize(id)
+      _validate!
+      @id = id
+    end
+
+    # Generate all attributes, which may be expensive.
+    def attributes
+      _generate_all
+    end
+
+    # Return the attributes as a hash.
+    def to_h
+      attributes
+    end
+
+    # Return a stringified version of the attributes hash.
+    def to_s
+      to_h.to_s
+    end
+
+    private
+
+    def _generate_all
+      _schema[:columns].each_key do |name|
+        _generate_column(name)
+      end
+      @_attributes
+    end
+
+    def _generate_column(name)
+      @_attributes ||= { id: @id }
+      @_attributes[name] ||= self.class.value(@id, name)
+    end
+
+    def _validate!
+      self.class.send(:_validate!)
+    end
+
+    def _schema
+      self.class.send(:_schema)
+    end
+
+    class << self
+      include Enumerable
+
+      # Return the name of the table, which is derived from the class name.
+      def table_name
+        name.downcase.to_sym
+      end
+
+      # Return a new record corresponding to the specified index.
+      def [](index)
+        _validate!
+        new(index) if index < count
+      end
+
+      # Return a Query that matches the supplied constraints
+      def where(constraints={})
+        _validate!
+        ids = Thicket.new(0..._schema[:size])
+        constraints.each do |attribute, values|
+          column = _schema[:columns][attribute]
+          other = Array(values).reduce(Thicket.new) do |thicket, value|
+            thicket | column[:mapping][value]
+          end
+          ids &= other
+        end
+        Query.new(self, ids)
+      end
+
+      # Return all records.
+      def all
+        where
+      end
+
+      # Count all records, delegating this to the all Query.
+      def count
+        all.count
+      end
+
+      # Return the last record, to be consistent with #first, which we get by magic.
+      def last
+        all.last
+      end
+
+      # Iterate over all records, delegating this to the all Query
+      def each(&block)
+        all.each(&block)
+      end
+
+      # Pluck specified attributes from all records, delegating this to the all query.
+      def pluck(*args)
+        all.pluck(args)
+      end
+
+      # Return a Querty that contains a random sampling of records.
+      def sample(limit=1)
+        all.sample(limit)
+      end
+
+      # Add a new column to the Table model.
+      def column(attribute, *args)
+        args.each do |arg|
+          index =
+            case arg
+            when Hash
+              :distribution
+            when Proc
+              :generator
+            else
+              raise "unsupported column parameter"
+            end
+          _schema[:columns][attribute][index] = arg
+        end
+        define_method(attribute) do
+          _generate_column(attribute)
+        end
+      end
+
+      # Generate a random number, intended to be used in lambdas. The number
+      # will have been seeded appropriately to ensure determinism.
+      def rand(args)
+        _validate!
+        _db.prng.rand(args)
+      end
+
+      # Retrieve the value of the given attribute for the given ID.
+      def value(id, attribute)
+        _validate!
+        return id if attribute == :id
+        column = _schema[:columns][attribute]
+        value =
+          unless column[:distribution].nil?
+            column[:mapping].find do |_, ids|
+              ids.include?(id)
+            end&.first
+          end
+        unless column[:generator].nil?
+          _seed_prng(id, attribute)
+          value =
+            if column[:distribution].nil?
+              column[:generator].call
+            else
+              column[:generator].call(value)
+            end
+        end
+        value
+      end
+
+      private
+
+      def _db
+        Thread.current[:rndb_database]
+      end
+
+      def _schema
+        Thread.current[:rndb_tables] ||= Hash.new do |tables, name|
+          tables[name] = {
+            class: nil,
+            size: 0,
+            columns: Hash.new do |columns, key|
+              columns[key] = {
+                distribution: nil,
+                mapping: {},
+                generator: nil
+              }
+            end
+          }
+        end
+        Thread.current[:rndb_tables][table_name]
+      end
+
+      def _migrate(size)
+        raise "table already migrated" unless _schema[:class].nil?
+        ids = Thicket.new(0...size)
+        _schema[:columns].each_value do |column|
+          distribution = column[:distribution]
+          next if distribution.nil?
+          raise "distribution must sum to unity" unless distribution.values.sum == 1
+          min = 0.0
+          column[:distribution].each do |value, probability|
+            max = min + probability
+            column[:mapping][value] = ids * (min..max)
+            min = max
+          end
+          ids =
+            column[:mapping].values.reduce(Thicket.new) do |thicket, other|
+              thicket | other
+            end
+        end
+        _schema[:size] = size
+        _schema[:class] = self
+      end
+
+      def _seed_prng(id, attribute)
+        tuple = [_db.seed, table_name, attribute, id].join('-')
+        digest = Digest::SHA256.hexdigest(tuple)
+        value = digest.to_i(16) % 18_446_744_073_709_551_616
+        _db.prng.srand(value)
+        Faker::Config.random = _db.prng
+        value
+      end
+
+      def _validate!
+        @valid ||= (self == _schema[:class])
+        raise "table not added to database" unless @valid
+      end
+    end
+  end
+end