lode 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09a0f58842564183f26432cf94556f585303a9e4ad76ec67b614fde10510de3e'
-  data.tar.gz: 4eb739e7ba22ecb4c04f6b22e4ea7831dab6d05178883ffdef3e7699a78cde9a
+  metadata.gz: 181f4e76dd273a5cb36b0f7e3172ce3182d0359bb72162f3be463265b811ea71
+  data.tar.gz: 51569c4f0676c83a79649c10bbbf9bc7c409d768cf3e4a8660cdc22d87bd4e0b
 SHA512:
-  metadata.gz: e5dd7b40a024e01b7c2324cdb61d49c11c0960c32773c984e91c7e06f51518b0ef2a1ee01db8dc09166a4a42a33a87a46fc78c12eb490843c887eab066e9f9e4
-  data.tar.gz: c991649ef5fb8baac35d1b94ca33c3b4a88bf7eacaef249d69adbc862c7a66e5e618aa2911e8003b6dfe33cfea9aad9c2c5a72b5249f73c6f5b82dde94393804
+  metadata.gz: bb2e66a93e557a04445f3b8e17dabc734932c4a135ecfd000637e7c34d349134f83edc741b16a479694cdf267bc77122a2f18cadac5d16e846143ad3de8709df
+  data.tar.gz: cb6e4da211f9e5a4e1a6c99f0182bbed352a46c94bec3ed9200cbd2552eed6801b105d85c2fc96e0d633b3f306839c341fe269582b40d894d49cdd20430e3452

data/README.adoc

@@ -20,7 +20,7 @@ toc::[]
 - Built atop {pstore_link}.
 - Uses the _Railway Pattern_ via {dry_monads_link} for fault tolerant pipelines.
 - Emphasizes use of `Hash`, `Data`, `Struct`, or link:https://alchemists.io/projects/wholable[whole value objects] in general.
-- Great for {xdg_link} caches, simple file-based databases, or simple file stores in general.
+- Great for {xdg_link} caches, lightweight file-based databases, or simple file stores in general.
 
 == Requirements
 
@@ -66,32 +66,54 @@ To use, create a Lode instance and then use database-like messages to interact w
 ----
 lode = Lode.new "demo.store"
 
-lode.commit :links do
-  upsert({id: 1, url: "https://one.com"})
-  upsert({id: 2, url: "https://2.com"})
-  upsert({id: 3, url: "https://three.com"})
+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
 
 # Success({:id=>3, :url=>"https://three.com"})
-# (only the last record created/updated is answered back)
+# (only the last record created is answered back)
+
+lode.write(:links) { create({id: 4, url: "https://four.io"}) }
+# Success({:id=>4, :url=>"https://four.io"})
+
+lode.write(:links) { create({id: 4, url: "https://four.io"}) }
+# Failure("Record exists for id: 4.")
+
+lode.write(:links) { update({id: 1, url: "https://one.demo"}) }
+# Success({:id=>1, :url=>"https://one.demo"})
+
+lode.write(:links) { update({id: 5, url: "https://five.bogus"}) }
+# Failure("Unable to find id: 5.")
 
-lode.commit(:links) { upsert({id: 2, url: "https://two.com"}) }
+lode.write(:links) { upsert({id: 2, url: "https://two.com"}) }
 # Success({:id=>2, :url=>"https://two.com"})
 
-lode.commit(:links) { find 1 }
-# Success({:id=>1, :url=>"https://one.com"})
+lode.write(:links) { upsert({id: 5, url: "https://five.demo"}) }
+# Success({:id=>5, :url=>"https://five.demo"})
+
+lode.read(:links) { find 1 }
+# Success({:id=>1, :url=>"https://one.demo"})
 
-lode.commit(:links) { find 13 }
+lode.read(:links) { find 13 }
 # Failure("Unable to find id: 13.")
 
-lode.commit(:links) { delete 2 }
+lode.write(:links) { delete 2 }
 # Success({:id=>2, :url=>"https://two.com"})
 
-lode.commit(:links) { delete 13 }
+lode.write(:links) { delete 13 }
 # Failure("Unable to find id: 13.")
 
-lode.commit(:links, &:all)
-# Success([{:id=>1, :url=>"https://one.com"}, {:id=>3, :url=>"https://three.com"}])
+lode.read(:links, &:all)
+# Success(
+#   [
+#     {:id=>1, :url=>"https://one.demo"},
+#     {:id=>3, :url=>"https://three.com"},
+#     {:id=>4, :url=>"https://four.io"},
+#     {:id=>5, :url=>"https://five.demo"}
+#   ]
+# )
 ----
 
 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.
@@ -178,7 +200,7 @@ Given the above, you could now create and find _link_ records by _slug_ like so:
 
 [source,ruby]
 ----
-lode.commit(:links) { upsert({id: 1, slug: :demo, url: "https://demo.com"}) }
+lode.write(:links) { upsert({id: 1, slug: :demo, url: "https://demo.com"}) }
 lode.read(:links) { find :demo }
 
 # Success({:id=>1, :slug=>:demo, :url=>"https://demo.com"})
@@ -201,7 +223,7 @@ As mentioned when configuring a Lode instance, two _types_ of tables are availab
 [source,ruby]
 ----
 lode = Lode.new "demo.store"
-lode.commit(:links) { upsert({id: 1, url: "https://one.com"}) }
+lode.write(:links) { upsert({id: 1, url: "https://one.com"}) }
 # Success({:id=>1, :url=>"https://one.com"})
 ----
 
@@ -216,13 +238,13 @@ lode = Lode.new("demo.store") do |config|
   config.register :links, model: Model
 end
 
-lode.commit :links do
+lode.write :links do
   upsert({id: 1, url: "https://one.com"})
-  upsert Model[id: 2, url: "https://"]
+  upsert Model[id: 2, url: "https://two.com"]
 end
 
-lode.commit(:links, &:all)
-# Success([#<data Model id=1, url="https://one.com">, #<data Model id=2, url="https://">])
+lode.read(:links, &:all)
+# Success([#<data Model id=1, url="https://one.com">, #<data Model id=2, url="https://two.com">])
 ----
 
 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.
@@ -231,7 +253,9 @@ 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 a record by primary key.
+* `#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.
 
@@ -241,8 +265,8 @@ All of the above (except `#primary_key`) support an optional `:key` keyword argu
 
 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:
 
-* `#commit`: Allows you to read and write records as a single transaction.
-* `#read`: Allows you to _only_ read data from your object store as a single transaction. Write operations will result in an exception.
+* `#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:
 
@@ -250,14 +274,14 @@ Both of the above methods require you to supply the table name and a block with
 ----
 lode = Lode.new "demo.store"
 
-# Read/Write
-lode.commit(:links) { upsert({id: 1, url: "https://demo.com"}) }
-
 # Read Only
 lode.read(:links) { find 1 }
+
+# Write/Read
+lode.write(:links) { upsert({id: 1, url: "https://demo.com"}) }
 ----
 
-Attempting to `#read` with a _write_ operation will result in an error. Example:
+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:
 
 [source,ruby]
 ----
@@ -265,7 +289,7 @@ lode.read(:links) { delete 1 }
 # in read-only transaction (PStore::Error)
 ----
 
-For those familiar with {pstore_link} behavior, a commit and read operation is the equivalent of the following using `PStore` directly:
+For those familiar with {pstore_link} behavior, a write and read operation is the equivalent of the following using `PStore` directly:
 
 [source,ruby]
 ----
@@ -273,7 +297,7 @@ require "pstore"
 
 store = PStore.new "demo.store"
 
-# Read/Write
+# Write/Read
 store.transaction do |store|
   store[:links] = store.fetch(:links, []).append({id: 1, url: "https://demo.com"})
 end

data/lib/lode/client.rb

@@ -24,7 +24,14 @@ module Lode
 
     def read(key, &) = transact(__method__, key, &)
 
-    def commit(key, &) = transact(__method__, key, &)
+    def write(key, &) = transact(:commit, key, &)
+
+    def commit(key, &)
+      warn "`#{self.class}##{__method__}` is deprecated, use `#write` instead.",
+           category: :deprecated
+
+      write(key, &)
+    end
 
     private
 

data/lib/lode/tables/abstract.rb

@@ -22,18 +22,38 @@ module Lode
 
       def all = Success records.dup.freeze
 
-      def find value, key: primary_key
-        fail NoMethodError,
-             "`#{self.class}##{__method__} #{method(__method__).parameters}` must be implemented."
+      def find id, key: primary_key
+        records.find { |record| primary_id(record, key:) == id }
+               .then do |record|
+                 return Success record if record
+
+                 Failure "Unable to find #{key}: #{id.inspect}."
+               end
+      end
+
+      def create record, key: primary_key
+        id = primary_id(record, key:)
+
+        find(id, key:).bind { Failure "Record exists for #{key}: #{id}." }
+                      .or do |error|
+                        return append record if error.include? "Unable to find"
+
+                        Failure error
+                      end
       end
 
-      def upsert value, key: primary_key
+      def update change, key: primary_key
+        id = primary_id(change, key:)
+        find(id, key:).bind { |existing| revise existing, change }
+      end
+
+      def upsert record, key: primary_key
         fail NoMethodError,
              "`#{self.class}##{__method__} #{method(__method__).parameters}` must be implemented."
       end
 
-      def delete value, key: primary_key
-        find(value, key:).fmap do |record|
+      def delete id, key: primary_key
+        find(id, key:).fmap do |record|
           records.delete record
           store[key] = records
           record
@@ -44,10 +64,15 @@ module Lode
 
       attr_reader :store, :key, :setting, :records
 
-      def update existing, record
-        records.supplant existing, record
+      def primary_id record, key: primary_key
+        fail NoMethodError,
+             "`#{self.class}##{__method__} #{method(__method__).parameters}` must be implemented."
+      end
+
+      def revise existing, change
+        records.supplant existing, change
         store[key] = records
-        Success record
+        Success change
       end
 
       def append record

data/lib/lode/tables/dictionary.rb

@@ -8,21 +8,16 @@ module Lode
     class Dictionary < Abstract
       include Dry::Monads[:result]
 
-      def find value, key: primary_key
-        records.find { |record| record[key] == value }
-               .then do |record|
-                 return Success record if record
-
-                 Failure "Unable to find #{key}: #{value.inspect}."
-               end
-      end
-
-      def upsert value, key: primary_key
-        find(value[key]).either(
-          -> existing { update existing, value },
-          proc { append value }
+      def upsert change, key: primary_key
+        find(change[key], key:).either(
+          -> existing { revise existing, change },
+          proc { append change }
         )
       end
+
+      protected
+
+      def primary_id(record, key: primary_key) = record[key]
     end
   end
 end

data/lib/lode/tables/value.rb

@@ -8,30 +8,25 @@ module Lode
     class Value < Abstract
       include Dry::Monads[:result]
 
-      def find value, key: primary_key
-        records.find { |record| record.public_send(key) == value }
-               .then do |record|
-                 return Success record if record
+      def upsert change, key: primary_key
+        record = record_for change
 
-                 Failure "Unable to find #{key}: #{value.inspect}."
-               end
-      end
-
-      def upsert value, key: primary_key
-        record = record_for value
-
-        find(record.public_send(key)).either(
-          -> existing { update existing, record },
+        find(primary_id(record, key:)).either(
+          -> existing { revise existing, record },
           proc { append record }
         )
       end
 
+      protected
+
+      def primary_id(record, key: primary_key) = record.public_send(key)
+
       private
 
       # :reek:FeatureEnvy
-      def record_for value
+      def record_for change
         model = setting.model
-        value.is_a?(model) ? value : model[**value.to_h]
+        change.is_a?(model) ? change : model[**change.to_h]
       end
     end
   end

data/lode.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "lode"
-  spec.version = "1.3.0"
+  spec.version = "1.4.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/lode"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lode
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2024-04-21 00:00:00.000000000 Z
+date: 2024-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-monads
@@ -125,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.5.10
 signing_key:
 specification_version: 4
 summary: A monadic store of marshaled objects.