sack 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: efb08ab6965016ac346ea8e63141972a58ef0228
+  data.tar.gz: 37f648bcc771fc4ec30a09f2fb04b370a88b0a6d
+SHA512:
+  metadata.gz: c8e4f163b354e31e8fd9d2cf537a0e9211ed545caf64887f4fd68dc24b79e3859d9226bb80dec0862ffdf0aed07d718a6c52b8fd18ecdc6f2551294abed7de00
+  data.tar.gz: a2279b88ad6eb8083f53ce9ced7abe3c17ea4d113716daae0ff6966459f9975b1bee78eba99f03be0c5800c58cb2fa7e8336d1bd688825a196e58b51ed51d0ff

data/.gitignore

@@ -0,0 +1,3 @@
+.idea
+Gemfile.lock
+pkg

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Paul Duncan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

data/README.md

@@ -0,0 +1,291 @@
+# Sack
+
+Minimalistic Database Layer based on SQLite3
+
+## Presentation
+
+This library provides a lightweight an easy-to-use database interface.
+
+## Installation
+
+### Gemfile
+```ruby
+gem 'sack'
+```
+
+### Terminal
+```bash
+gem install -V sack
+```
+
+## Usage
+
+Sack may be used at different levels to achieve various levels of complexity.
+Let's explore the major uses.
+
+### Most basic
+
+In its simplest form, Sack provides a direct CRUD to any database, as long as you provide it with *schema* information, a connector and a connection string.
+
+```ruby
+# Define the Schema
+SCHEMA = {
+
+	# 'user' Table
+	user: {
+		
+		# ID - Auto-Increment (:ai) Primary-Key (:pk) Integer (:int)
+		id: [:int, :pk, :ai],
+		
+		# Name - String
+		name: [:str]
+	}
+}
+
+# Create a Database object using the SQLite3 Connector
+db = Sack::Database.new Sack::Connectors::SQLite3Connector, 'example.db', SCHEMA
+
+# Create
+db.create :user, name: 'foobar'
+
+# Fetch by Field
+u = db.fetch_by(:user, :name, 'foobar').first
+
+# Fetch by ID
+u = db.fetch(:user, u[:id]).first
+
+# Fetch All
+users = db.fetch_all :user
+
+# Find (fetch by ID - first result)
+u = db.find :user, u[:id]
+
+# Count
+user_count = db.count :user
+
+# Update
+db.update :user, u[:id], name: 'John Doe'
+
+# Save (Combined Create / Update)
+u[:name] = 'Jane Doe'
+db.save :user, u
+
+# Delete
+db.delete :user, u[:id]
+```
+
+### Model-based Schema
+
+Defining a Sack Schema by hand can be painful.
+Also, the concept of *relationships* between entities is not available.
+Finally, all validation has to be performed by the application.
+
+Another option is to use Sack's *Model* abstraction, providing schema generation, validation and relationships.
+
+Each model is defined using a module which includes *Sack::Database::Model*, placed inside a _root module_.
+
+The schema for the whole entity model can then be derived from this root module using *Sack::Schema.from_module*.
+
+The module presented above can be re-written as such:
+
+```ruby
+# Model Root
+module DataModel
+
+	# Users
+	module User
+		include Sack::Database::Model
+		
+		# Fields
+		field id: [:int, :pk, :ai]
+		field name: [:str]
+	end
+end
+
+# Create a Database object using the SQLite3 Connector and a Schema derived from our DataModel
+db = Sack::Database.new Sack::Connectors::SQLite3Connector, 'example.db', Sack::Database::Schema.from_module(DataModel)
+```
+
+### Validation
+
+The Model abstraction provided by Sack offers validation, which can be specified directly on the fields defined in each model.
+Let's add some validation on our user model:
+
+```ruby
+# Users
+module User
+	include Sack::Database::Model
+	
+	# Fields
+	field id: [:int, :pk, :ai]
+	field name: [:str],
+	      required: true,
+	      unique: true,
+	      min_length: 3,
+	      max_length: 24,
+	      regex: /^[a-zA-Z][a-zA-Z0-9_-]+$/,
+	      validate: :no_prefix
+	      
+	# Custom Validation Method - No Prefix
+	# @param [Database] db Database instance
+	# @param [Hash] data The entity being validated
+	# @param [Symbol] name The field being validated
+	# @param [Object] val The field's value
+	# @param [Hash] rules The field's validation rules hash (possibly containing any custom validation params)
+	# @param [Array] errors The list of errors for the entity being validated (if no error is added but the method returns false, a generic error message will be added by Sack)
+	# @return [Object] true / false (true = valid)
+	def self.no_prefix db, data, name, val, rules, errors
+		valid = !(/^mr|ms|dr|mrs /i =~ val)
+		errors << "Field [#{name}] should not include prefixes such as mr. ms. dr. etc..."
+		valid
+	end
+end
+```
+
+*Note*: The *unique* validator can be either set to _true_ to validate global unicity, or it can be set to an array of other fields to scope unicity.
+
+Validity can then be checked by the application at any time using the *is_valid?* method injected into every model.
+
+```ruby
+User.is_valid? db, name: 'foobar'
+# => true
+
+User.is_valid? db, name: nil
+# => false
+
+errors = []
+User.is_valid?(db, { name: '000' }, errors)
+# => false
+
+errors.each { |e| puts e }
+# Field [name] doesn't match allowed pattern (/^[a-zA-Z][a-zA-Z0-9_-]+$/)
+```
+
+### Relationships
+
+Using the Model abstraction, we can define relationships between our entities.
+Let's add an _article_ model and define a one-to-many relationship from users to articles.
+
+```ruby
+# User Model
+module User
+	include Sack::Database::Model
+	
+	# Fields
+	field id: [:int, :pk, :ai]
+	field name: [:str]
+	
+	# Relationships
+	has_many articles: :article, fk: :author
+end
+
+# Article Model
+module Article
+	include Sack::Database::Model
+	
+	# Fields
+	field id: [:int, :pk, :ai]
+	field author: [:int]
+	field title: [:str]
+	field body: [:txt]
+	
+	# Relationships
+	belongs_to author: :user
+end
+```
+
+This then allows us to use the relationships to simplify our lives a little.
+
+```ruby
+# Fetching association with direct parameters
+articles = User.articles db, id: 0
+
+# Fetching association with entity
+u = User.find db, id
+articles = User.articles db, u
+
+a = articles.first
+u = Article.author db, a
+```
+
+This is nice, but we can do better.
+Actually, although every entity handled by Sack is really just a *Hash* (to keep things simple), the models also inject a small router into any entity it loads.
+This allows to access an entity's associations directly, and through multiple levels.
+
+```ruby
+u = User.find db, id
+
+articles = u.articles(db)
+u = articles.first.author(db)
+
+# we can recurse as many levels as we want
+articles = u.articles(db).first.author(db).articles(db).first.author(db).articles(db)
+```
+
+#### Belongs To
+
+The belongs-to relationship injects a method in the model, with the name of the association. This method allows fetching the associated entity.
+The name of the association _MUST MATCH_ the name of the field storing the key to the associated entity.
+
+If given ONLY a name, belongs_to will auto-guess the name of the associated model (CamelCased version of the association's name).
+To alter this behavior (as in the example above - the association is called 'author' but the target model is actually 'user'), simply provide a model name:
+
+```ruby
+module Foo
+	include Sack::Database::Model
+	field id: [:int, :pk, :ai]
+end
+
+module Bar
+	include Sack::Database::Model
+	field id: [:int, :pk, :ai]
+	
+	# A 'Bar' belongs to two 'Foo's
+	field foo: [:int]
+	field other_foo: [:int]
+
+	# Target model is Foo - no need to specify it
+	belongs_to :foo
+
+	# Explicitly use Foo as the target model
+	belongs_to other_foo: :foo
+end
+```
+
+#### Has Many
+
+The has-many relationship injects a method in the model, with the name of the association. This method allows fetching the associated entities.
+The name of the association can be anything. The target model NEEDS to be specified.
+
+Unless explicitly specified, Sack will use the name of the current model to determine the foreign key (the field within the target model which holds the ID of the current model).
+
+```ruby
+module Foo
+	include Sack::Database::Model
+	field id: [:int, :pk, :ai]
+	
+	# Foreign Key in Bar is 'foo'
+	has_many bars: :bar
+	
+	# Foreign Key in Bork is 'parent'
+	has_many borks: :bork, fk: :parent
+end
+
+module Bar
+	include Sack::Database::Model
+	field id: [:int, :pk, :ai]
+	field foo: [:int]	
+	belongs_to :foo
+end
+
+module Bork
+	include Sack::Database::Model
+	field id: [:int, :pk, :ai]
+	field parent: [:int]
+	belongs_to parent: :foo
+end
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+Rake::TestTask.new do |t|
+	t.libs << 'test'
+	t.pattern = 'test/**/test*.rb'
+end
+
+task :default => :test

data/lib/sack.rb

@@ -0,0 +1,14 @@
+# Sack
+# by Eresse <eresse@eresse.net>
+
+# Internal Includes
+require 'sack/version'
+require 'sack/database'
+require 'sack/database/model'
+require 'sack/database/schema'
+require 'sack/connectors'
+
+# Sack Module:
+# Root Module for Sack.
+module Sack
+end

data/lib/sack/connectors.rb

@@ -0,0 +1,14 @@
+# Sack
+# by Eresse <eresse@eresse.net>
+
+# Connectors
+require 'sack/connectors/sqlite3'
+
+# Sack Module
+module Sack
+
+	# Connectors Module:
+	# Provides the available backend connectors for Sack database.
+	module Connectors
+	end
+end

data/lib/sack/connectors/sqlite3.rb

@@ -0,0 +1,46 @@
+# Sack
+# by Eresse <eresse@eresse.net>
+
+# External Includes
+require 'sqlite3'
+
+# Internal Includes
+require 'sack/database/sanitizer'
+
+# Sack Module
+module Sack
+
+	# Connectors Module
+	module Connectors
+
+		# SQLite3 Connector Module:
+		# Provides SQLite3 connectivity for Sack Database.
+		module SQLite3Connector
+
+			# Open:
+			# Opens a connection to an SQLite3 database.
+			# @param [String] conn_string The connection string (path to a db file)
+			# @return [Object] Database connection
+			def self.open conn_string
+				SQLite3::Database.open conn_string
+			end
+
+			# Close:
+			# Closes a previously-opened database connection.
+			# @param [Object] dbc Database connection
+			def self.close dbc
+				dbc.close
+			end
+
+			# Execute
+			# Executes an SQL statement with parameters
+			# @param [Object] dbc Database connection
+			# @param [String] q Statement
+			# @param [Array] params Statement parameters
+			# @return [Array] Statement results
+			def self.exec dbc, q
+				dbc.exec q
+			end
+		end
+	end
+end

data/lib/sack/database.rb

@@ -0,0 +1,96 @@
+# Sack
+# by Eresse <eresse@eresse.net>
+
+# External Includes
+require 'thread'
+require 'sqlite3'
+
+# Internal Includes
+require 'sack/database/data'
+
+# Sack Module
+module Sack
+
+	# Database Class:
+	# Main Database Access Class - provides CRUD methods (and a little more) against a given Schema on a provided Database Connector and Connection String.
+	class Database
+
+		# Actions:
+		# Allowed data methods
+		ACTIONS = [
+			:create_table,
+			:count,
+			:find,
+			:fetch,
+			:fetch_by,
+			:fetch_all,
+			:create,
+			:update,
+			:save,
+			:delete
+		]
+
+		# Construct:
+		# Builds a *Database* on top of a backend _connector_ and _connstring_, set to operate on _schema_.
+		# @param [Object] connector Generic database backend connector
+		# @param [String] connstring Connector-specific connection string
+		# @param [Hash] schema Schema definition - see README
+		def initialize connector, connstring, schema
+
+			# Set Connector & Connstring
+			@connector = connector
+			@connstring = connstring
+
+			# Set Schema
+			@schema = schema
+
+			# Create Lock
+			@lock = Mutex.new
+
+			# Verify Schema
+			verify_schema
+		end
+
+		# Open:
+		# Opens a session on the database for yielding.
+		def open
+
+			# Lock DB
+			@lock.synchronize do
+
+				# Open Database
+				db = @connector.open @connstring
+
+				# Yield Block
+				yield Data.new(db, @schema) if block_given?
+
+				# Close Database
+				db.close
+			end
+		end
+
+		# Verify Schema:
+		# Verifies the supplied schema against the actual database & re-creates it if necessary.
+		def verify_schema
+			open { |data| rebuild_schema data unless @schema.keys.inject(true) { |a, table| a && (data.exec "select count(*) from #{table};" rescue nil) } }
+		end
+
+		# Rebuild Schema:
+		# Re-creates the database according to the supplied schema.
+		# @param [Data] data Data access interface
+		def rebuild_schema data
+			@schema.each { |table, fields| data.create_table table, fields }
+		end
+
+		# Method Missing:
+		# Catches and routes database actions through data access interface.
+		def method_missing name, *args
+
+			# Check Action
+			raise "Unknown action [#{name}]" unless ACTIONS.include? name
+
+			# Open Database { Perform Action }
+			open { |db| return db.send name, *args }
+		end
+	end
+end