snappier 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ba736f367d2679006c1c3d4e6569f2c454c510f7dba8e5323d7ff10d868c849
-  data.tar.gz: 9db97fcc5401fbce775bf3a902107a4503f99d95c166faf65e770d34748655f3
+  metadata.gz: e522706b988ca8ec71eb16695db3dd727aa31b3e529d0c23353828106433078f
+  data.tar.gz: 80d6a461f498c1ee78ae550c70707fdecebe9c9eea3dd1fb1b408c7eff0e5a08
 SHA512:
-  metadata.gz: db4c5f52d70e97f9409647c5bba823a47545e5221a9bc02dde35a2564750651b03b6d63a3cfcca3cc720c391228a1b075dd79b0af7897c5122eaf4dc437fff03
-  data.tar.gz: 21ab50eac9931674667972b9c0924ab46c1fd91e102507296ff98696b11c0f242179629d55a2b6e1cdaf43137ca99502e515715ec243623aa873b0de388e898a
+  metadata.gz: 266a8c2f2d3ee1fc8f1efa945d711ef9b0591fb80d6365b270e18c8c6f940782576cde9fd22da74d8978ef0dce0eb499676b2c2c81d68818d5383347782fa8d8
+  data.tar.gz: 69ddaa90ce8b412ca44b32ffc4c602a1eba8a1862462488262c8a0f4b68fa7ab2e6f95e3080b1e74c0cb8bca3fe5a97d8a090d61861fe8a2f6925f2971d90b47

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.4

data/README.md

@@ -1,28 +1,68 @@
 # Snappier
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/snappier`. To experiment with that code, run `bin/console` for an interactive prompt.
+Imagine a dream where every moment your objects whisper their truths into the ether—each change a shimmer in time, gently bottled and sealed. Snappier is the archivist of that dream: a watchful spirit that captures the essence of Ruby objects, encasing their state in crystalline snapshots. Through enchanted serializers and portals like S3, their stories are preserved across realms. You shape the ritual—what is seen, how it's told, where it rests—yet Snappier hums quietly, faithfully, beneath it all.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
-Install the gem and add to the application's Gemfile by executing:
-
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add snappier
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install snappier
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+Right, so you’ve decided to track your data like a proper psycho—every twist, every turn, every bloody mutation. You take Snappier, slap it in your Gemfile like it owes you money, and set it up to watch your objects spill their guts. You tell it how to remember—JSON, YAML, dark magic—whatever. Then you point it somewhere to stash the loot: S3, disk, down the pub. When the time comes, you take the snapshot. Click. Another wee lie safely stored. Choose life. Choose history. Choose Snappier.
+
+Call `Snappier::Take.for(entity)` in your application code and a snapshopt will be persisted via a sidekiq job (this specific dependency on sidekiq for async processing may be abstracted later).
+
+You may call this in an active record model callback (like `after_save`) or anywhere else in your application code.
+
+There is no specific dependency on active record but the methods `attributes`, `previously_new_record?` and `destroyed?` are used by default (the latter two deciding if snapshot is related to create/delete otherwise defaulting to update).
+
+To attribute changes to a specific user, call `Snappier::Who.current = "<current user description>"` and that
+information will be persisted with any subsequent snapshots.  In rails, you may set this in a `before_action`
+method to capture a description of the current user - this setting exists only in the current thread.
+
+By default snapshots are persisted to `tmp/snappier`.  You can instead persist to S3 using the `snappier-aws_s3` extension gem and the following configuration when your application starts up:
+
+```ruby
+persistence = Snappier::AwsS3::Persistence.new(
+  region: aws_region,
+  bucket_name: bucket_name,
+  credentials: aws_credentials,
+)
+Snappier::Registry.register_persistence(persistence)
+```
+
+By default, snapshot state is persisted by calling `record.attributes`, if you want to persist more or less information then you can create a module and register it when your application starts up:
+
+```ruby
+module OrderSnapshot
+  def self.snap(order)
+    order.attributes.without(:created_at, :updated_at).tap do |attributes|
+      attributes["line_items"] = order.line_items.map { |line_item| line_item.attributes }
+    end
+  end
+end
+
+Snappier::Registry.register(
+  "Order" => "OrderSnapshot"
+)
+```
+
+It is possible to replay the snapshots for a specific record which will calculate any change for presentation in a UI:
+
+```ruby
+Snappier::Replay.for(
+  type: Order,
+  id: "1"
+) { |change| pp change }
+```
 
 ## Development
 

data/lib/snappier/changes.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "fileutils"
-
 module Snappier
   module Changes
     def self.between(previous_state, current_state)
@@ -47,25 +45,29 @@ module Snappier
     end
 
     def self.append_changes_for_collections(changes, previous_collection, current_collection, path)
-      ids = Set.new
-      previous_collection ||= []
-      current_collection ||= []
-      previous_collection.each { |e| ids << e["id"] if e["id"] }
-      current_collection.each { |e| ids << e["id"] if e["id"] }
+      ids = ids_for_collections(previous_collection, current_collection)
 
       if ids.empty?
-        changes[path] = [previous_collection, current_collection]
+        changes[path] = [previous_collection, current_collection] unless previous_collection == current_collection
         return
       end
 
       ids.each do |id|
-        previous_value = previous_collection.find { |r| r["id"] == id } || {}
-        current_value = current_collection.find { |r| r["id"] == id } || {}
-        previous_value.delete("id")
-        current_value.delete("id")
+        previous_value = (previous_collection || []).find { |r| r["id"] == id } || {}
+        current_value = (current_collection || []).find { |r| r["id"] == id } || {}
+        previous_value&.delete("id")
+        current_value&.delete("id")
 
         append_changes(changes, previous_value, current_value, path + [id])
       end
     end
+
+    def self.ids_for_collections(*collections)
+      Set.new.tap do |ids|
+        collections.each do |collection|
+          (collection || []).each { |e| ids << e["id"] if e["id"] }
+        end
+      end
+    end
   end
 end

data/lib/snappier/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Snappier
-  VERSION = "0.1.4"
+  VERSION = "0.1.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: snappier
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Mark Ryall
@@ -32,6 +32,7 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- ".tool-versions"
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md