:toc: macro :toclevels: 5 :figure-caption!:
:dry_monads_link: link:https://dry-rb.org/gems/dry-monads[Dry Monads] :pstore_link: link:https://github.com/ruby/pstore[PStore] :ruby_link: link:https://www.ruby-lang.org[Ruby] :xdg_link: link:https://alchemists.io/projects/xdg[XDG]
= Lode
Lode -- as in geological deposit or a vein of minerals -- is a {pstore_link} of object data that can be mined for valuable information.
As noted in the {pstore_link} documentation all objects are marshaled which is not without caveats and dangers but, if you only need a simple object store, {pstore_link} is a solution. Lode takes this a step further by allowing you to have a pipeline workflow along with a Domain Specific Language (DSL) for creating, updating, finding, and deleting records.
toc::[]
== Features
Hash, Data, Struct, or link:https://alchemists.io/projects/wholable[whole value objects] in general.== Requirements
. {ruby_link}.
== Setup
To install with security, run:
To install without security, run:
You can also add the gem directly to your project:
Once the gem is installed, you only need to require it:
== Usage
To use, create a Lode instance and then use database-like messages to interact with your table of records as desired. For example, the following creates a table of links and stores them within the demo.store file and then interacts with those records:
lode = Lode.new "demo.store"
lode.write :links do create({id: 1, url: "https://one.com"}) create({id: 2, url: "https://2.com"}) create({id: 3, url: "https://three.com"}) end
lode.write(:links) { create({id: 4, url: "https://four.io"}) }
lode.write(:links) { create({id: 4, url: "https://four.io"}) }
lode.write(:links) { update({id: 1, url: "https://one.demo"}) }
lode.write(:links) { update({id: 5, url: "https://five.bogus"}) }
lode.write(:links) { upsert({id: 2, url: "https://two.com"}) }
lode.write(:links) { upsert({id: 5, url: "https://five.demo"}) }
lode.read(:links) { find 1 }
lode.read(:links) { find 13 }
lode.write(:links) { delete 2 }
lode.write(:links) { delete 13 }
lode.read(:links, &:all)
The default configuration is set up to use a primitive Hash which is the default behavior when using {pstore_link}. Everything answered back is a result monad as provided by the {dry_monads_link} gem so you can leverage the Railway Pattern to build robust, fault tolerant, pipelines.
=== Configuration
Lode can be configured using a block or a keyword argument. The following are identical:
lode = Lode.new "demo.store" do |config| config.mode = :max config.table = Lode::Tables::Value config.primary_key = :name end
The default configuration consists of the following attributes:
Each key can be configured as follows:
store: Any object that adhere's to the {pstore_link} Object API. You'll most likely never need to change this but is available if desired. Default: PStore.mode: The mode determines {pstore_link} behavior and can be one of the following:
** :default: The default mode and is identical to PStore.new path.
** :thread: Ensures a thread safe PStore instance is created. This is identical to PStore.new path, true.
** :file: Ensures a file safe PStore instance is created. This is identical to setting store.ultra_safe = true on a PStore instance.
** :max: Ensures a thread and file safe PStore instance is created for situations where you need maximum safety.table: Defines the type of table used to interact with your records. The following values are supported:
** Lode::Tables::Dictionary: The default value which allows you to interact with a Hash of records but would also work with any object that can respond to +#[]+ and +#[]=+.
** Lode::Tables::Value: Allows you to interact with whole value objects like Data, Struct, or link:https://alchemists.io/projects/wholable[whole value objects] in general which have attribute readers and writers.primary_key: Defines the primary key used when interacting with your table of records (useful when finding or upserting records). Default: :id.registry: Used for registering default settings for your tables. This is not meant to be used directly but is documented for transparency.=== Paths
Upon initialization, and when given a file, the file is only created once you start saving records. Although, when given a nested path, the full parent path will be created in anticipation of the file eventually being created. Example:
Lode.new "demo.store"
demo.store can eventually be saved.=== Registry
The registry is part of the configuration and directly accessible via a Lode instance. The registry allows you to customize individual table behavior as desired. For instance, you could have a Hash table or value table (i.e. Data, Struct, etc). Additionally, each table can have different primary keys too. The registry accepts three arguments in this format:
.... key, model:, primary_key: ....
The default model is a Hash but could be Data, Struct, or any value object. The default primary key is :id but could be any attribute that uniquely identifies a record. This means the following is identical when registering default table settings:
lode = Lode.new("demo.store") { |config| config.register :links, primary_key: :slug }
Given the above, you could now create and find link records by slug like so:
lode.write(:links) { upsert({id: 1, slug: :demo, url: "https://demo.com"}) } lode.read(:links) { find :demo }
Keep in mind that the registry only defines default behavior. You can override default behavior by specifying a key. Example:
lode.read(:links) { find 1, key: :id }
Even though the default primary key was registered to be :slug, we were able to use :id instead. The optional :key keyword argument is also available for all table methods.
=== Tables
As mentioned when configuring a Lode instance, two types of tables are available to you. The default (i.e. Lode::Tables::Dictionary) allows you to interact with Hash records which is compatible with default PStore functionality. Example:
lode = Lode.new "demo.store" lode.write(:links) { upsert({id: 1, url: "https://one.com"}) }
The second, and more powerful table type, is a value object table (i.e. Lode::Tables::Value). Here's an example using a Data model:
Model = Data.define :id, :url
lode = Lode.new("demo.store") do |config| config.table = Lode::Tables::Value config.register :links, model: Model end
lode.write :links do upsert({id: 1, url: "https://one.com"}) upsert Model[id: 2, url: "https://two.com"] end
lode.read(:links, &:all)
The above would work with a Struct or any value object. One of many conveniences when using value objects -- as shown above -- is you can upsert records using a Hash or an instance of your value object.
Each table supports the following methods:
#primary_key: Answers the primary key as defined when the table was registered or the default key (i.e. :id).#all: Answers all records for a table.#find: Finds an existing record by primary key or answers a failure if not found.#create: Creates a new record by primary key or answers a failure if record already exists.#update: Updates an existing record by primary key or answers a failure if the record can't be found.#upsert: Creates or updates a new or existing record by primary key.#delete: Deletes an existing record by primary key.All of the above (except #primary_key) support an optional :key keyword argument which allows you to use a different key that is not the primary key if desired.
=== Read/Write
You've already seen a few examples of how to read and write to your object store but, to be explicit, the following are supported:
#read: Allows you to only read data from your object store in a single transaction. Any write operation will result in an exception.#write: Allows you to write (and read) records in a single transaction.Both of the above methods require you to supply the table name and a block with operations. Since a table name must always be supplied this means you can interact with multiple tables within the same file store or you can write different tables to different files. Up to you. Here's an example of a basic write and read operation:
lode = Lode.new "demo.store"
lode.read(:links) { find 1 }
Attempting to write within a read transaction will result in an error. For example, notice delete is being used within the read transaction which causes an exception:
lode.read(:links) { delete 1 }
For those familiar with {pstore_link} behavior, a write and read operation is the equivalent of the following using PStore directly:
require "pstore"
store = PStore.new "demo.store"
store.transaction do |store| store[:links] = store.fetch(:links, []).append({id: 1, url: "https://demo.com"}) end
store.transaction(true) { |store| store.fetch(:links, []).find { |record| record[:id] == 1 } }
=== Store
If at any time you need access to the original PStore instance, you can ask for it. Example:
lode = Lode.new "demo.store" load.store
== Development
To contribute, run:
You can also use the IRB console for direct access to all objects:
== Tests
To test, run:
== link:https://alchemists.io/policies/license[License]
== link:https://alchemists.io/policies/security[Security]
== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]
== link:https://alchemists.io/policies/contributions[Contributions]
== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]
== link:https://alchemists.io/projects/lode/versions[Versions]
== link:https://alchemists.io/community[Community]
== Credits
FAQs
Unknown package
We found that lode demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.