historiographer 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f16398b9f6b0a3d58501a2115eabca0e0f93a938d04eeb4c21d3713f9b70079a
-  data.tar.gz: a460ef65372e236b001225b1028837eb7ba107e8d45d958c39d003be0cd64db4
+  metadata.gz: 23b67927669a8cddbbf3a4097aba1c238f086324ad6e277bb728525263e12381
+  data.tar.gz: bf24dcdae837fc9a443810e24d1f559a87d3c8d778acb1904c308dd11017d15f
 SHA512:
-  metadata.gz: 3b545edcfe0076f0e83f5478347a9298fce77118d7274ad39ce8304844637b7ee15980e66c02dff36321eda4e36b0defdb10b6c33cc7486fba47e780043e5f42
-  data.tar.gz: f828cf26cc357fb0b3e2750bfcc1f62dc628c1579f1fa3356062f34314545783bb6ecb80366e4ac9d6988eae8374168afeb0d29c166daa9dbd7c860074494de4
+  metadata.gz: 49c8d86b477f67c016d52aae1cb721a7d33bfecc04de761f50d7c3cc42c4481eb6b3863f2b3c89f226f2321a79c92411f70e6344f6e933bde7a2245504a876a1
+  data.tar.gz: 667b8032e144c0bc0a61cedbbffcf51dd5a90eac68ee8dfe95920e6500da6fc9f39c6b374f419907031822fa12d858b9bf79c77a8323a57192ca3c01da680b8b

data/README.md

@@ -8,21 +8,11 @@ Historiographer fixes this problem in a better way than existing auditing gems.
 
 The Audited gem has some serious flaws.
 
-🤚Hands up if your `versions` table has gotten too big to query 🤚
+1. The `versions` table quickly grows too large to query
 
-🤚Hands up if your `versions` table doesn't have the indexes you need 🤚
+2. It doesn't provide the indexes you need from your primary tables
 
-🤚Hands up if you've ever iterated over `versions` records in Ruby to recreate a snapshot of what data looked like at a point in time. 🤚
-
-Why does this happen?
-
-First, `audited` only tracks a record of what changed, so there's no way to "go back in time" and see what the data looked like back when a problem occurred without replaying every single audit.
-
-Second, it tracks changes as JSON. While some data stores have JSON querying semantics, not all do, making it very hard to ask complex questions of your historical data -- that's the whole reason you're keeping it around.
-
-Third, it doesn't maintain indexes on your data. If you maintain an index on the primary table, wouldn't you also want to look up historical records using the same columns? Historical data is MUCH larger than "latest snapshot" data, so, duh, of course you do.
-
-Finally, Audited creates just one table for all audits. Historical data is big. It's not unusual for an audited gem table to get into the many millions of rows, and need to be constantly partitioned to maintain any kind of efficiency.
+3. It doesn't provdie out-of-the-box snapshots
 
 ## How does Historiographer solve these problems?
 
@@ -30,44 +20,116 @@ Historiographer introduces the concept of _history tables:_ append-only tables t
 
 If you have a `posts` table:
 
-| id | title |
-| :----------- | :----------- |
-| 1      | My Great Post       |
-| 2 | My Second Post |
+| id  | title          |
+| :-- | :------------- |
+| 1   | My Great Post  |
+| 2   | My Second Post |
 
 You'll also have a `post_histories_table`:
 
-| id | post_id | title | history_started_at | history_ended_at | history_user_id |
-| :----------- | :----------- | :----------- | :----------- | :----------- | :----------- |
-| 1      | 1 | My Great Post | '2019-11-08' | NULL | 1 |
-| 2 | 2| My Second Post | '2019-11-08' | NULL | 1 |
+| id  | post_id | title          | history_started_at | history_ended_at | history_user_id |
+| :-- | :------ | :------------- | :----------------- | :--------------- | :-------------- |
+| 1   | 1       | My Great Post  | '2019-11-08'       | NULL             | 1               |
+| 2   | 2       | My Second Post | '2019-11-08'       | NULL             | 1               |
 
 If you change the title of the 1st post:
 
-```Post.find(1).update(title: "Title With Better SEO", history_user_id: current_user.id)```
+`Post.find(1).update(title: "Title With Better SEO", history_user_id: current_user.id)`
 
 You'll expect your `posts` table to be updated directly:
 
-| id | title |
-| :----------- | :----------- |
-| 1      | Title With Better SEO |
-| 2 | My Second Post |
+| id  | title                 |
+| :-- | :-------------------- |
+| 1   | Title With Better SEO |
+| 2   | My Second Post        |
 
 But also, your `histories` table will be updated:
 
-| id | post_id | title | history_started_at | history_ended_at | history_user_id |
-| :----------- | :----------- | :----------- | :----------- | :----------- | :----------- |
-| 1      | 1 | My Great Post | '2019-11-08' | '2019-11-09' | 1 |
-| 2 | 2| My Second Post | '2019-11-08' | NULL | 1 |
-| 1      | 1 | Title With Better SEO | '2019-11-09' | NULL | 1 |
+| id  | post_id | title                 | history_started_at | history_ended_at | history_user_id |
+| :-- | :------ | :-------------------- | :----------------- | :--------------- | :-------------- |
+| 1   | 1       | My Great Post         | '2019-11-08'       | '2019-11-09'     | 1               |
+| 2   | 2       | My Second Post        | '2019-11-08'       | NULL             | 1               |
+| 1   | 1       | Title With Better SEO | '2019-11-09'       | NULL             | 1               |
 
 A few things have happened here:
 
 1. The primary table (`posts`) is updated directly
 2. The existing history for `post_id=1` is timestamped when its `history_ended_at`, so that we can see when the post had the title "My Great Post"
-3. A new history record is appended to the table containing a complete snapshot of the record, and a `NULL` `history_ended_at`. That's because this is the current history. 
+3. A new history record is appended to the table containing a complete snapshot of the record, and a `NULL` `history_ended_at`. That's because this is the current history.
 4. A record of _who_ made the change is saved (`history_user_id`). You can join to your users table to see more data.
 
+## Snapshots
+
+Snapshots are particularly useful for two key use cases:
+
+### 1. Time Travel & Auditing
+
+When you need to see exactly what your data looked like at a specific point in time - not just individual records, but entire object graphs with all their associations. This is invaluable for:
+
+- Debugging production issues ("What did the entire order look like when this happened?")
+- Compliance requirements ("Show me the exact state of this patient's record on January 1st")
+- Auditing complex workflows ("What was the state of this loan application when it was approved?")
+
+### 2. Machine Learning & Analytics
+
+When you need immutable snapshots of data for:
+
+- Training data versioning
+- Feature engineering
+- Model validation
+- A/B test analysis
+- Ensuring reproducibility of results
+
+### Taking Snapshots
+
+You can take a snapshot of a record and all its associated records:
+
+```ruby
+post = Post.find(1)
+post.snapshot(history_user_id: current_user.id)
+```
+
+This will:
+
+1. Create a history record for the post
+2. Create history records for all associated records (comments, author, etc.)
+3. Link these history records together with a shared `snapshot_id`
+
+You can retrieve the latest snapshot using:
+
+```ruby
+post = Post.find(1)
+snapshot = post.latest_snapshot
+
+# Access associated records from the snapshot
+snapshot.comments # Returns CommentHistory records
+snapshot.author   # Returns AuthorHistory record
+```
+
+Snapshots are immutable - you cannot modify history records that are part of a snapshot. This guarantees that your historical data remains unchanged, which is crucial for both auditing and machine learning applications.
+
+### Snapshot-Only Mode
+
+If you want to only track snapshots and not record every individual change, you can configure Historiographer to operate in snapshot-only mode:
+
+```ruby
+Historiographer::Configuration.mode = :snapshot_only
+```
+
+In this mode:
+
+- Regular updates/changes will not create history records
+- Only explicit calls to `snapshot` will create history records
+- Each snapshot still captures the complete state of the record and its associations
+
+This can be useful when:
+
+- You only care about specific points in time rather than every change
+- You want to reduce the number of history records created
+- You need to capture the state of complex object graphs at specific moments
+- You're versioning training data for machine learning models
+- You need to maintain immutable audit trails at specific checkpoints
+
 # Getting Started
 
 Whenever you include the `Historiographer` gem in your ActiveRecord model, it allows you to insert, update, or delete data as you normally would.
@@ -78,18 +140,33 @@ class Post < ActiveRecord::Base
 end
 ```
 
-By default, Historiographer will require all SQL-backed methods to provide a `history_user_id` to track who made the changes.
+### History Modes
+
+Historiographer supports two modes of operation:
+
+1. **:histories mode** (default) - Records history for every change to a record
+2. **:snapshot_only mode** - Only records history when explicitly taking snapshots
+
+You can configure the mode globally:
 
 ```ruby
-Post.create(title: "My Post", history_user_id: current_user.id) # => OK
-Post.create(title: "My Post") # => Error!
+# In an initializer
+Historiographer::Configuration.mode = :histories  # Default mode
+# or
+Historiographer::Configuration.mode = :snapshot_only
 ```
 
-Many existing models will be better off using `Historiographer::Safe` when getting started, which will not raise an error, but will alert you of locations where your app is missing `history_user_id`. 
+Or per model using `historiographer_mode`:
 
 ```ruby
 class Post < ActiveRecord::Base
-  include Historiographer::Safe
+  include Historiographer
+  historiographer_mode :snapshot_only  # Only record history when .snapshot is called
+end
+
+class Comment < ActiveRecord::Base
+  include Historiographer
+  historiographer_mode :histories  # Record history for every change (default)
 end
 ```
 
@@ -210,12 +287,11 @@ end
 == Mysql Install
 
 For contributors on OSX, you may have difficulty installing mysql:
- 
+
 ```
 gem install mysql2 -v '0.4.10' --source 'https://rubygems.org/' -- --with-ldflags=-L/usr/local/opt/openssl/lib --with-cppflags=-I/usr/local/opt/openssl/include
 ```
 
-
 == Copyright
 
 Copyright (c) 2016-2020 brettshollenberger. See LICENSE.txt for

data/{Gemfile → Users/brettshollenberger/programming/historiographer/Gemfile}

@@ -19,7 +19,6 @@ group :development, :test do
 end
 
 group :development do
-  gem 'bundler', '~> 1.0'
   gem 'jeweler', git: 'https://github.com/technicalpickles/jeweler', branch: 'master'
   gem 'rdoc', '~> 3.12'
   gem 'simplecov', '>= 0'

data/Users/brettshollenberger/programming/historiographer/Gemfile.lock

@@ -0,0 +1,341 @@
+GIT
+  remote: https://github.com/technicalpickles/jeweler
+  revision: 2ab86309fc2494ba2a4e9c86c514742cd4f681c2
+  branch: master
+  specs:
+    jeweler (2.3.9)
+      builder
+      bundler
+      git (>= 1.2.5)
+      github_api (~> 0.16.0)
+      highline (>= 1.6.15)
+      nokogiri (>= 1.5.10)
+      psych
+      rake
+      rdoc
+      semver2
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (7.1.5)
+      actionpack (= 7.1.5)
+      activesupport (= 7.1.5)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (7.1.5)
+      actionpack (= 7.1.5)
+      activejob (= 7.1.5)
+      activerecord (= 7.1.5)
+      activestorage (= 7.1.5)
+      activesupport (= 7.1.5)
+      mail (>= 2.7.1)
+      net-imap
+      net-pop
+      net-smtp
+    actionmailer (7.1.5)
+      actionpack (= 7.1.5)
+      actionview (= 7.1.5)
+      activejob (= 7.1.5)
+      activesupport (= 7.1.5)
+      mail (~> 2.5, >= 2.5.4)
+      net-imap
+      net-pop
+      net-smtp
+      rails-dom-testing (~> 2.2)
+    actionpack (7.1.5)
+      actionview (= 7.1.5)
+      activesupport (= 7.1.5)
+      nokogiri (>= 1.8.5)
+      racc
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    actiontext (7.1.5)
+      actionpack (= 7.1.5)
+      activerecord (= 7.1.5)
+      activestorage (= 7.1.5)
+      activesupport (= 7.1.5)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (7.1.5)
+      activesupport (= 7.1.5)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (7.1.5)
+      activesupport (= 7.1.5)
+      globalid (>= 0.3.6)
+    activemodel (7.1.5)
+      activesupport (= 7.1.5)
+    activerecord (7.1.5)
+      activemodel (= 7.1.5)
+      activesupport (= 7.1.5)
+      timeout (>= 0.4.0)
+    activerecord-import (1.8.1)
+      activerecord (>= 4.2)
+    activestorage (7.1.5)
+      actionpack (= 7.1.5)
+      activejob (= 7.1.5)
+      activerecord (= 7.1.5)
+      activesupport (= 7.1.5)
+      marcel (~> 1.0)
+    activesupport (7.1.5)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      mutex_m
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0)
+    addressable (2.4.0)
+    base64 (0.2.0)
+    benchmark (0.4.0)
+    bigdecimal (3.1.8)
+    builder (3.3.0)
+    coderay (1.1.3)
+    concurrent-ruby (1.3.4)
+    connection_pool (2.4.1)
+    crass (1.0.6)
+    database_cleaner (2.1.0)
+      database_cleaner-active_record (>= 2, < 3)
+    database_cleaner-active_record (2.2.0)
+      activerecord (>= 5.a)
+      database_cleaner-core (~> 2.0.0)
+    database_cleaner-core (2.0.1)
+    date (3.4.0)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    diff-lcs (1.5.1)
+    docile (1.4.1)
+    drb (2.2.1)
+    erubi (1.13.0)
+    factory_bot (6.5.0)
+      activesupport (>= 5.0.0)
+    factory_bot_rails (6.4.4)
+      factory_bot (~> 6.5)
+      railties (>= 5.0.0)
+    faraday (0.9.2)
+      multipart-post (>= 1.2, < 3)
+    ffi (1.17.0-arm64-darwin)
+    ffi (1.17.0-x86_64-darwin)
+    formatador (1.1.0)
+    git (1.11.0)
+      rchardet (~> 1.8)
+    github_api (0.16.0)
+      addressable (~> 2.4.0)
+      descendants_tracker (~> 0.0.4)
+      faraday (~> 0.8, < 0.10)
+      hashie (>= 3.4)
+      mime-types (>= 1.16, < 3.0)
+      oauth2 (~> 1.0)
+    globalid (1.2.1)
+      activesupport (>= 6.1)
+    guard (2.19.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      lumberjack (>= 1.0.12, < 2.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.13.0)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    hashie (5.0.0)
+    highline (3.1.1)
+      reline
+    i18n (1.14.6)
+      concurrent-ruby (~> 1.0)
+    io-console (0.7.2)
+    irb (1.12.0)
+      rdoc
+      reline (>= 0.4.2)
+    json (1.8.6)
+    jwt (2.9.3)
+      base64
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.6.1)
+    loofah (2.23.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    lumberjack (1.2.10)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.0.4)
+    method_source (1.1.0)
+    mime-types (2.99.3)
+    mini_mime (1.1.5)
+    minitest (5.25.1)
+    multi_json (1.15.0)
+    multi_xml (0.6.0)
+    multipart-post (2.4.1)
+    mutex_m (0.2.0)
+    mysql2 (0.5.0)
+    nenv (0.3.0)
+    net-imap (0.4.18)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.0)
+      net-protocol
+    nio4r (2.7.4)
+    nokogiri (1.16.7-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.16.7-x86_64-darwin)
+      racc (~> 1.4)
+    notiffany (0.1.3)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    oauth2 (1.4.8)
+      faraday (>= 0.8, < 3.0)
+      jwt (>= 1.0, < 3.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (>= 1.2, < 3)
+    paranoia (3.0.0)
+      activerecord (>= 6, < 8.1)
+    pg (1.5.9)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    psych (5.2.0)
+      stringio
+    racc (1.8.1)
+    rack (2.2.10)
+    rack-session (1.0.2)
+      rack (< 3)
+    rack-test (2.1.0)
+      rack (>= 1.3)
+    rackup (1.0.1)
+      rack (< 3)
+      webrick
+    rails (7.1.5)
+      actioncable (= 7.1.5)
+      actionmailbox (= 7.1.5)
+      actionmailer (= 7.1.5)
+      actionpack (= 7.1.5)
+      actiontext (= 7.1.5)
+      actionview (= 7.1.5)
+      activejob (= 7.1.5)
+      activemodel (= 7.1.5)
+      activerecord (= 7.1.5)
+      activestorage (= 7.1.5)
+      activesupport (= 7.1.5)
+      bundler (>= 1.15.0)
+      railties (= 7.1.5)
+    rails-dom-testing (2.2.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.0)
+      loofah (~> 2.21)
+      nokogiri (~> 1.14)
+    railties (7.1.5)
+      actionpack (= 7.1.5)
+      activesupport (= 7.1.5)
+      irb
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      zeitwerk (~> 2.6)
+    rake (13.2.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    rchardet (1.8.0)
+    rdoc (3.12.2)
+      json (~> 1.4)
+    reline (0.5.11)
+      io-console (~> 0.5)
+    rollbar (3.6.0)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.2)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    securerandom (0.3.1)
+    semver2 (3.4.2)
+    shellany (0.0.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+    standalone_migrations (7.2.0)
+      activerecord (>= 6.0.0, < 8.0)
+      nokogiri (~> 1.14)
+      railties (>= 6.0.0, < 8.0)
+      rake (>= 10.0)
+    stringio (3.1.2)
+    thor (1.3.2)
+    thread_safe (0.3.6)
+    timecop (0.9.10)
+    timeout (0.4.2)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    webrick (1.9.0)
+    websocket-driver (0.7.6)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.6.18)
+
+PLATFORMS
+  arm64-darwin
+  x86_64-darwin
+
+DEPENDENCIES
+  activerecord (>= 6)
+  activerecord-import
+  activesupport
+  database_cleaner
+  factory_bot_rails
+  guard
+  guard-rspec
+  jeweler!
+  mysql2 (= 0.5)
+  paranoia
+  pg
+  pry
+  rails (>= 6)
+  rdoc (~> 3.12)
+  rollbar
+  rspec
+  simplecov
+  standalone_migrations
+  timecop
+
+RUBY VERSION
+   ruby 3.0.2p107
+
+BUNDLED WITH
+   2.5.23

data/Users/brettshollenberger/programming/historiographer/Guardfile

@@ -0,0 +1,4 @@
+guard :rspec, cmd: "bundle exec rspec" do
+  watch(%r{^spec/.+\.rb$}) { |_m| "spec/historiographer_spec.rb" }
+  watch(%r{^lib/(.+)\.rb$}) { |_m| "spec/historiographer_spec.rb" }
+end

data/Users/brettshollenberger/programming/historiographer/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2016 Brett Shollenberger
+
+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.