lookback 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 43cdcc71110782804391f2157ad0774dcf3f79d98f8cae47ebe76854c3cfbf3f
+  data.tar.gz: 863261fa123f9a054d9347badb1ea3f744cedb125786bbf603e3d3306ed561fc
+SHA512:
+  metadata.gz: 1039bd84ca6c688cdf3c411d14be8f819425d147a692d345ce4d0471bf9659706686603a31944a94e0044b5aaa3000d26d4637f48c64d3f1618a5e508ba630c4
+  data.tar.gz: da8fdb1a15bf80cc530f472845d2734211eb59e4aae8b33c0d73a3b9f87f5d3c5778075af1a12263d643ac2610e44278dd97076def6869d330f5b3b251483e23

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pierre Senechal
+
+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,32 @@
+# Lookback
+
+Historical record management for Ruby. **Under active development** — the
+public API may change until a `1.0` release.
+
+Lookback records and reads versions of application state. The `0.0.x` line
+ships a working in-memory snapshot backend and the public API surface
+intended to cover future backends:
+
+- Native snapshot store (persistent) — planned
+- Ruby PaperTrail adapter — planned
+- Hibernate Envers adapter (over shared datastores) — planned
+
+## Usage
+
+```ruby
+require "lookback"
+
+Lookback.track("Order", 42, { status: "pending" }, event: :create)
+Lookback.track("Order", 42, { status: "paid"    }, event: :update)
+
+Lookback.history("Order", 42).map(&:event)   # => [:create, :update]
+Lookback.latest("Order", 42).attributes      # => { status: "paid" }
+```
+
+Swap the backend by assigning `Lookback.backend = MyBackend.new`. A backend
+implements `#record(key, attributes, event:, now:)`, `#history(key)`, and
+`#latest(key)`.
+
+## License
+
+MIT. See `LICENSE.txt`.

data/lib/lookback/backends.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Lookback
+  module Backends
+    # In-memory snapshot backend. Stores an ordered list of versions per
+    # (record_class, record_id) key. Suitable for tests and single-process use;
+    # persistent stores land in later releases.
+    class Snapshot
+      Version = Struct.new(:number, :recorded_at, :attributes, :event, keyword_init: true) do
+        def to_h = { number: number, recorded_at: recorded_at, attributes: attributes, event: event }
+      end
+
+      def initialize
+        @versions = Hash.new { |h, k| h[k] = [] }
+      end
+
+      def record(key, attributes, event: :update, now: Time.now)
+        list = @versions[key]
+        version = Version.new(
+          number: list.length + 1,
+          recorded_at: now,
+          attributes: deep_dup(attributes),
+          event: event,
+        )
+        list << version
+        version
+      end
+
+      def history(key)
+        @versions[key].dup
+      end
+
+      def latest(key)
+        @versions[key].last
+      end
+
+      def clear
+        @versions.clear
+      end
+
+      private
+
+      def deep_dup(obj)
+        case obj
+        when Hash  then obj.each_with_object({}) { |(k, v), h| h[k] = deep_dup(v) }
+        when Array then obj.map { |v| deep_dup(v) }
+        else            obj.dup rescue obj
+        end
+      end
+    end
+
+    # Adapter over Ruby PaperTrail. Not implemented in this release.
+    class PaperTrail
+      def record(*, **)
+        raise Lookback::NotImplementedError, "PaperTrail adapter is under development"
+      end
+
+      def history(*)
+        raise Lookback::NotImplementedError, "PaperTrail adapter is under development"
+      end
+    end
+
+    # Adapter over Hibernate Envers (via shared datastore). Not implemented in
+    # this release.
+    class Envers
+      def record(*, **)
+        raise Lookback::NotImplementedError, "Envers adapter is under development"
+      end
+
+      def history(*)
+        raise Lookback::NotImplementedError, "Envers adapter is under development"
+      end
+    end
+  end
+end

data/lib/lookback/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Lookback
+  VERSION = "0.0.1"
+end

data/lib/lookback.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "lookback/version"
+require_relative "lookback/backends"
+
+# Lookback — historical record management for Ruby.
+#
+# This gem is under active development. The `0.0.x` line ships a working
+# in-memory snapshot backend and the public API surface intended to cover
+# future backends (Ruby PaperTrail, Hibernate Envers, and a persistent native
+# snapshot store). The public API may change until a `1.0` release.
+#
+# Basic usage:
+#
+#   Lookback.track("Order", 42, { status: "pending" }, event: :create)
+#   Lookback.track("Order", 42, { status: "paid"    }, event: :update)
+#   Lookback.history("Order", 42).map(&:event)  # => [:create, :update]
+#   Lookback.latest("Order", 42).attributes     # => { status: "paid" }
+module Lookback
+  class Error < StandardError; end
+  class NotImplementedError < Error; end
+
+  class << self
+    attr_writer :backend
+
+    def backend
+      @backend ||= Backends::Snapshot.new
+    end
+
+    def track(record_type, record_id, attributes, event: :update, now: Time.now)
+      backend.record([record_type.to_s, record_id], attributes, event: event, now: now)
+    end
+
+    def history(record_type, record_id)
+      backend.history([record_type.to_s, record_id])
+    end
+
+    def latest(record_type, record_id)
+      backend.latest([record_type.to_s, record_id])
+    end
+
+    def reset!
+      backend.respond_to?(:clear) ? backend.clear : (@backend = nil)
+    end
+
+    def api_version
+      VERSION
+    end
+
+    def supported_backends
+      %i[snapshot papertrail envers].freeze
+    end
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: lookback
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Pierre Senechal
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-12 00:00:00.000000000 Z
+dependencies: []
+description: Lookback defines the interface for a Ruby gem that manages historical
+  records and audit snapshots. This release publishes the API surface; backend adapters
+  (Envers, PaperTrail, native snapshot store) are under development.
+email:
+- psenechal@wealthsimple.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/lookback.rb
+- lib/lookback/backends.rb
+- lib/lookback/version.rb
+homepage: https://github.com/psenechal-ws/lookback
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/psenechal-ws/lookback
+  source_code_uri: https://github.com/psenechal-ws/lookback
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: API surface for a Ruby historical-record management gem.
+test_files: []