db-struct 0.1.0

data/spec/dbstruct_spec.rb

@@ -0,0 +1,452 @@
+
+require 'spec_helper'
+require 'dbstruct'
+require 'set'
+
+
+
+BOOK1_ITEMS = {title:    "The Summoning of Dragons",
+               author:   "Tubal de Malachite",
+               date:     Time.new(1989, 11, 1),
+               edition:  1}
+
+BOOK2_ITEMS = {title:    "Howe To Kille Insects",
+               author:   "Humptulip",
+               date:     Time.new(1985, 8, 1),   # guess
+               edition:  1}
+
+BOOK3_ITEMS = {title:   "Diseases of the Dragon",
+               author:  "Lady Sybil Ramkin",
+               date:    Time.new(1989, 11, 1),
+               edition: 1}
+
+
+def make_post_items(fora, users, count)
+  posts = []
+  mc = 0
+  for f in fora
+    for u in users
+      (1..count).each do
+        mc += 1
+        posts << {
+          forum:    f,
+          user:     u,
+          
+          subject:  "subject number #{mc}",
+          date:     Time.now,
+          contents: "message text #{mc}",
+        }
+      end
+    end
+  end
+
+  return posts
+end
+
+def make_posts(fora, users, count) =
+  make_post_items(fora, users, count)
+  .map{|pi| Posts.new(**pi)}
+
+
+
+
+POSTS_ITEMS = proc{
+  fora = %w{forum1 forum2 forum3}
+  users = %w{u1 u2 u3}
+
+  make_post_items(fora, users, 1)
+}.call
+
+
+describe DBStruct do
+  before(:all) do
+    @tmpdir = TmpDir.dir
+
+    dbfile = TmpDir.filepath("db.sqlite3")
+    @db = jruby?                                ?
+      Sequel.connect("jdbc:sqlite:#{dbfile}")   :
+      Sequel.sqlite(dbfile)
+    #puts "Created #{dbfile}"
+
+  end
+
+  after(:all) do
+    TmpDir.cleanup!
+  end
+
+  it "lets you define dbstruct types" do
+    Book = DBStruct.with(@db, :books) do
+      field :title,     String
+      field :author,    String
+      field :date,      Time
+      field :edition,   Integer
+
+      def foo(x) = x+x
+    end
+
+    expect( Book.items.size ) .to eq 0
+  end
+
+  book1 = nil
+  it "lets you create an instance" do
+    book1 = Book.new(**BOOK1_ITEMS)
+    expect( Book.items.size ) .to eq 1
+
+    BOOK1_ITEMS.each{|k, v| expect( book1.send(k) ) .to eq v }
+    expect( book1.to_h ) .to eq BOOK1_ITEMS
+
+    b1a = Book.items[book1.rowid]
+    expect( b1a ) .to eq book1
+    expect( b1a.to_h ) .to eq BOOK1_ITEMS
+
+    b1b = Book.items.values.first
+    expect( b1b ) .to eq book1
+  end
+
+  it "lets you define and call methods" do
+    expect( book1.foo(2) ) .to eq 4
+  end
+
+  book2 = nil
+  it "lets you create multiple instances" do
+    book2 = Book.new(**BOOK2_ITEMS)
+    expect( Book.items.size ) .to eq 2
+
+    expect( book2 ) .to_not eq book1
+    expect( book2.to_a ) .to_not eq BOOK1_ITEMS
+
+    Book.items.values.each{|item|
+      expect( Book.items[item.rowid] ) .to eq item
+    }
+  end
+
+  it "lets you change field values" do
+    book2.edition = 3
+
+    expect( book2.edition ) .to eq 3
+    expect( Book.items[book2.rowid].edition ) .to eq 3
+
+    b2a = Book.items.each
+      .map{|rowid, book| book}
+      .find{|book| book.title == BOOK2_ITEMS[:title]}
+    expect( b2a.edition ) .to eq 3
+
+    book2.edition = BOOK2_ITEMS[:edition]
+    expect( book2.edition ) .to eq BOOK2_ITEMS[:edition]
+  end
+
+  it "has various struct-like conversions" do
+    expect( book2.to_h ) .to eq BOOK2_ITEMS
+    expect( book2.to_a.to_h) .to eq BOOK2_ITEMS
+
+    BOOK2_ITEMS.each{|k, v|
+      expect( book2[k] ) .to eq v
+    }
+
+    book2[:edition] = 42
+    expect( book2.edition ) .to eq 42
+    book2.edition = BOOK2_ITEMS[:edition]
+  end
+
+  it "lets you categorize along group values" do
+    Posts = DBStruct.with(@db, :posts) do
+      group         :forum,     String
+      group         :user,      String
+
+      field         :subject,   String
+      field         :date,      Time
+      field         :contents,  String
+    end
+
+    fora = []
+    users = []
+    posts = []
+    POSTS_ITEMS.each{|post|
+      posts << Posts.new(**post)
+      fora << post[:forum]
+      users << post[:user]
+    }
+    users.uniq!
+    fora.uniq!
+
+    expect( Posts.items.size ) .to eq posts.size
+    expect( Posts.items.values.to_set ) .to eq posts.to_set
+
+    # There should be exactly one post per forum/user
+    for forum in fora
+      for user in users
+        i = Posts.items(forum, user)
+        expect( i.size ) .to eq 1
+
+        p = i.values.first
+        expect( p.forum ) .to eq forum
+        expect( p.user ) .to eq user
+      end
+    end
+
+    # nil is the wildcard when selecting across groups.  Let's test
+    # those.
+    all = []
+    for forum in fora
+      i = Posts.items(forum)
+      expected = posts.select{|ii| ii.forum == forum}.to_set
+      expect( i.values.to_set ) .to eq expected
+      all += i.values
+    end
+    expect( all.uniq.size ) .to eq all.size
+    expect( all.to_set ) .to eq posts.to_set
+
+    all = []
+    for user in users
+      i = Posts.items(nil, user)
+      expected = posts.select{|ii| ii.user == user}.to_set
+      expect( i.values.to_set ) .to eq expected
+      all += i.values
+    end
+    expect( all.uniq.size ) .to eq all.size
+    expect( all.to_set ) .to eq posts.to_set
+  end
+
+  it "lets you create custom BogoStructs around Sequel queries" do
+    q1 = Posts.where(user: %w{u1 u3}, forum: "f2")
+    ex1 = POSTS_ITEMS.select{|i|
+      %w{u1 u3}.include?i[:user] && i[:forum] == "f2"
+    }
+    expect( q1.values.uniq ) .to eq q1.values
+    expect( q1.values.size ) .to eq ex1.size
+
+    q1.values.each{|item|
+      expect( item.forum ) .to eq "f2"
+      expect( %w{u1 u3} ) .to include(item.user)
+    }
+  end
+
+  it "and it lets you chain them together, possibly using blocks" do
+    q1 = Posts.where(user: %w{u1 u3}).where{forum == "f2"}
+    ex1 = POSTS_ITEMS.select{|i|
+      %w{u1 u3}.include?i[:user] && i[:forum] == "f2"
+    }
+    expect( q1.values.uniq ) .to eq q1.values
+    expect( q1.values.size ) .to eq ex1.size
+
+    q1.values.each{|item|
+      expect( item.forum ) .to eq "f2"
+      expect( %w{u1 u3} ) .to include(item.user)
+    }
+  end
+
+  book3 = nil
+  book4 = nil
+  it "allows uninitialized fields in new items" do
+    book3 = Book.new
+    expect( book3.to_a.size ) .to eq 4
+
+    expect( book3.title ) .to eq nil
+    expect( book3.author ) .to eq nil
+    expect( book3.date ) .to eq nil
+    expect( book3.edition ) .to eq nil
+
+    book3.title = BOOK3_ITEMS[:title]
+    book3.author = BOOK3_ITEMS[:author]
+    book3.date = BOOK3_ITEMS[:date]
+    book3.edition = BOOK3_ITEMS[:edition]
+
+    expect( book3.to_h ) .to eq BOOK3_ITEMS
+
+    book4 = Book.new(title: "The Unknown Book")
+    expect( book4.title ) .to eq "The Unknown Book"
+    expect( book4.author ) .to eq nil
+    expect( book4.date ) .to eq nil
+    expect( book4.edition ) .to eq nil
+  end
+
+  it "fails if you attempt to set an unknown field." do
+    expect{ Book.new(title: "bad book", badness: 42) }
+      .to raise_error DBStruct::FieldError
+
+    expect{ book1.floop = 42 }
+      .to raise_error NoMethodError
+
+    expect{ book1[:floop] = 42 }
+      .to raise_error  DBStruct::FieldError
+  end
+  
+  it "ensures field values are of the expected type" do
+    expect{ book1.title = Time.now }
+      .to raise_error DBStruct::TypeError
+    expect{ book1.edition = "42" }
+      .to raise_error DBStruct::TypeError
+    expect{ book1.edition = Time.now }
+      .to raise_error DBStruct::TypeError
+
+    expect( book1.to_h ) .to eq BOOK1_ITEMS
+  end
+
+  book5 = nil
+  it "always allows null as a type" do
+    book1.title = nil
+    expect( book1.title ) .to eq nil
+    book1.title = BOOK1_ITEMS[:title]
+    expect( book1.to_h ) .to eq BOOK1_ITEMS
+
+    book5 = Book.new(title: "An Anonymous Book",
+                     author: nil)
+    expect( book5.title ) .to eq "An Anonymous Book"
+    expect( book5.author ) .to eq nil
+    expect( book5.date ) .to eq nil
+    expect( book5.edition ) .to eq nil
+  end
+
+  it "supports block enumeration over tables" do
+    expect( Book.items.size ) .to be > 1    # consistency check
+    
+    kv = []
+    Book.items.each{|k,v| kv.push [k,v]}
+    expect( kv.size ) .to eq Book.items.size
+
+    kv.each{|k,v|
+      expect( Book.items[k] ) .to eq v
+    }
+
+    # Test each_key
+    keys = []
+    Book.items.each_key{|rowid|
+      expect( Book.items[rowid].rowid ) .to eq rowid
+      keys.push(rowid)
+    }
+    expect( keys.size ) .to eq kv.size
+    expect( keys.to_set ) .to eq Book.items.keys.to_set
+    expect( keys.to_set ) .to eq kv.map{|k,v| k}.to_set
+    
+    # Test each_value
+    values = []
+    Book.items.each_value{|row|
+      expect( Book.items[row.rowid] ) .to eq row
+      values.push(row)
+    }
+    expect( values.size ) .to eq keys.size
+    expect( values.to_set ) .to eq Book.items.values.to_set
+    expect( values.to_set ) .to eq kv.map{|k,v| v}.to_set
+  end
+
+  it "provides enumerators as well" do
+    e = Book.items.each
+    expect( e.class ) .to eq Enumerator
+    expect( e.to_a.to_set ) .to eq Book.items.to_a.to_set
+
+    expect( Book.items.each_key.to_a.to_set ) .to eq Book.items.keys.to_set
+    expect( Book.items.each_value.to_a.to_set ) .to eq Book.items.values.to_set
+  end
+
+  it "includes Enumerable" do
+    # Just call a couple of methods to ensure that they work.  We
+    # assume the rest will work correctly.
+    expect( Book.items.any?{true} ) .to be true
+    expect( Book.items.select{true} ) .to eq Book.items.to_a
+  end
+  
+  it "fails gracefully when given an invalid row ID" do
+    # Invalid wrt the entire 
+    maxrow = Posts.items.keys.max
+    expect( Posts.items[maxrow + 1] ) .to eq nil
+
+    # Garbage row Ids should also return nil
+    expect( Posts.items[ ["garbage!!!"] ] ) .to eq nil
+
+    # Invalid key but not part of the current group.  Note that
+    # changes in the order of Post creation above could break this; we
+    # assume that there is at least one row-id that is larger than the
+    # largest row-id in this group.  If not, the following test will
+    # fail.
+    grp = Posts.items("forum1", "u1")
+    maxrow_grp = grp.keys.max
+    expect( maxrow_grp ) .to be < maxrow
+
+    outside_row = maxrow_grp + 1
+    expect( grp[outside_row] ) .to eq nil
+    expect( Posts.items[outside_row] ) .not_to eq nil
+
+    # Ditto for `where`; we abuse it to select by row-id; this may or
+    # may not be supported.
+    grp2 = Posts.where{_id < maxrow - 3}
+    expect( grp2[maxrow - 1] ) .to eq nil
+  end
+
+  it "supports row deletion but only in its group of items" do
+    fx = %w{xforum1 xforum2}
+    ux = %w{alice bob charlene}
+
+    xposts = make_posts(fx, ux, 2)
+    xposts.each{|r| expect( Posts.items[r.rowid] ) .to eq r }
+
+    f1 = Posts.items("xforum1")
+    f2 = Posts.items("xforum2")
+
+    d1 = f1.keys.first
+    
+    # Can't delete an item not in the current group
+    expect( f2.delete(d1) ) .to eq nil
+    expect( f2[d1] ) .to eq nil
+
+    # row objects can tell you if the underlying row exists
+    target = f1[d1]
+    expect( target.present? ) .to be true
+    expect( target.deleted? ) .to be false
+    
+    # Deletion returns the value and removes it from the database
+    expect( f1[d1] ) .to eq target
+    expect( f1.delete(d1) ) .to eq target
+    expect( f1[d1] ) .to eq nil
+    expect( Posts.items[d1] ) .to eq nil
+
+    # And the lingering row object should handle this gracefully
+    expect( target.present? ) .to be false
+    expect( target.deleted? ) .to be true
+    expect{ target.user }
+      .to raise_error DBStruct::MissingRowError
+  end
+
+  it "supports 'delete_if'" do
+    c = Posts.items("xforum1").size
+    Posts.items.delete_if{|k, v|
+      next false unless v.forum == "xforum1"
+      c -= 1
+      true
+    }
+    expect( Posts.items("xforum1").size ) .to eq 0
+    expect( c ) .to eq 0
+  end
+  
+  it "supports clearing per group" do
+    c = Posts.items("xforum2").size
+    expect( c ) .to be > 0
+    
+    Posts.items("xforum2").clear
+    expect( Posts.items("xforum2").size ) .to eq 0
+  end
+
+  it "can deal with any Ruby type Sequel can handle" do
+    BigTbl = DBStruct.with(@db, :bigtbl) do
+      field :i1,    Integer
+      field :s1,    String
+      field :fn1,   Fixnum
+      field :bn1,   Bignum
+      field :f1,    Float
+      field :bd1,   BigDecimal
+      field :dt1,   Date
+      field :dtt1,  DateTime
+      field :tm1,   Time
+      field :nm1,   Numeric
+      field :b1,    TrueClass
+      field :b2,    FalseClass
+    end
+
+    b1 = BigTbl.new
+
+    # TrueClass and FalseClass are shorthand for either boolean
+    b1.b2 = true
+    b1.b1 = false
+  end
+
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,48 @@
+require 'securerandom'
+require 'fileutils'
+
+SpecDir = File.realpath( File.dirname(__FILE__) )
+
+$: << File.join(SpecDir, '..', 'lib')
+$: << File.join(SpecDir, '..', 'src')
+
+def jruby?
+  return RUBY_PLATFORM == "java"
+end
+
+module TmpDir
+  @root = File.join( File.dirname(__FILE__), "tmpdata")
+  @tmpdir = File.join(@root, SecureRandom.uuid)
+  @count = 0
+
+  def self.dir
+    FileUtils.mkdir_p(@tmpdir) unless File.directory?(@tmpdir)
+    return @tmpdir
+  end
+
+  def self.filepath(name, versioned: false)
+    self.dir    # ensure @tmpdir exists
+
+    filepath = File.join(@tmpdir, name)
+    if versioned
+      while File.exist?(filepath)
+        @count += 1
+
+        nameparts = name.split('.')
+        suffix = nameparts.pop if nameparts.size > 1
+        nameparts.push @count.to_s
+        nameparts.push suffix if suffix
+
+        newname = nameparts.join(".")
+        filepath = File.join(@tmpdir, newname)
+      end
+    end
+
+    return filepath
+  end
+
+  def self.cleanup!
+    return unless File.directory?(@root)
+    FileUtils.rm_rf(@root)
+  end
+end

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: db-struct
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Reuter
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-09-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.76.0
+  name: sequel
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.76.0
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.10.0
+  name: rspec
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.10.0
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.25
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.25
+  name: yard
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.25
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.25
+description: |2
+      DBStruct is a class that, like Struct, provides a convenient way
+      to create subclasses with named fields that can be accessed via
+      the usual Ruby setters and getters.  Unlike Struct, their contents
+      are stored in a SQLite3 database.
+
+      In addition, each subclass also provides access to the database
+      via an interface that closely mimics a Ruby Hash, including
+      support for enumeration.
+email: chris@remove-this-part.blit.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- db-struct.gemspec
+- doc/DBStruct.html
+- doc/DBStruct/BogoHash.html
+- doc/DBStruct/ErrorHelpers.html
+- doc/DBStruct/Failure.html
+- doc/DBStruct/FieldError.html
+- doc/DBStruct/MissingRowError.html
+- doc/DBStruct/TypeError.html
+- doc/_index.html
+- doc/class_list.html
+- doc/css/common.css
+- doc/css/full_list.css
+- doc/css/style.css
+- doc/file.README.html
+- doc/file_list.html
+- doc/frames.html
+- doc/index.html
+- doc/js/app.js
+- doc/js/full_list.js
+- doc/js/jquery.js
+- doc/method_list.html
+- doc/top-level-namespace.html
+- gem.deps.rb
+- lib/dbstruct.rb
+- lib/internal/bogohash.rb
+- lib/internal/dbstruct_base.rb
+- lib/internal/dbstruct_class.rb
+- lib/internal/error.rb
+- lib/internal/util.rb
+- spec/dbstruct_spec.rb
+- spec/spec_helper.rb
+homepage: https://codeberg.org/suetanvil/db-struct
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- Sequel
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Persistant storage of sets of structured records.
+test_files: []