lutaml-store 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4481af10b7c80db97bffbe2e1ad5119d615370596c46c88c84e536411d1ffdda
-  data.tar.gz: 618ad367561533d0aa576ef713dfb384173e34ec1ec0047e3cbab400af9c4dce
+  metadata.gz: b35bad6d5f81534647fb355041ff434f9155e4488121d0870ef40611c1b9dc93
+  data.tar.gz: 71bca0ca15d5134199bad07710cb2bad8b35c3369abc5426a22bfa299352ba4a
 SHA512:
-  metadata.gz: 2e22cb07d0781f6aba2c2ebc043322e5a756519284740b74661906b6f00cbce8536291967868b86fd2a1908de46e6c1d4450f35c517d4919f73020d65890dc63
-  data.tar.gz: 26f2ef6b87a85e2c020571319640ceed71955ace41c97c2052857b97bd8d68e599cf466cd349f31c802a0fda7172cd857ce1bfbed952076b7425aea07c7d2de0
+  metadata.gz: eb4a0da9eb8a5dc529d8dbac816b8e1c98cc0da1826b7c9be5e04ceb9ae92b7e1fb3bbac65eca28f7c7a90025adf7391918beb5270e5b081c92baee31ffb69c5
+  data.tar.gz: af1af6380f9cd19f0ae14f1d7fc7987ae15cc47f26535338d919fa8cac2f83ceef84a4084a7f80bf626617182da65318d0207c6086274df078b388dbb4811b65

data/docs/src/pages/stores.md

@@ -76,6 +76,28 @@ cache.fetch("key") { expensive_call }     # block runs only on miss
 
 Entries past their TTL are evicted lazily on access; when `max_size` is exceeded the least-recently-used entries are evicted first.
 
+### TTL guarantees (pinned)
+
+The TTL semantics are pinned by specs and safe to build expiry policy on:
+
+- **Persistence** — entries serialize `created_at` as ISO-8601 with
+  microsecond precision, so a FileSystem (or SQLite) cache reopened in a new
+  process keeps every entry's original clock; expiry survives restarts.
+  The memory adapter keeps no state across processes by nature.
+- **Clock** — wall clock, not monotonic. This is the deliberate trade:
+  wall-clock timestamps survive restarts, but a system clock jump changes
+  apparent freshness (a backward jump un-expires nothing an entry's absolute
+  `created_at + ttl` already expired). Consumers needing jump-immunity
+  re-derive freshness from the source.
+- **Expired reads** — `get` on an expired entry returns `nil` **and deletes
+  the entry**: the key disappears from `keys`/`size`/`exists?`.
+- **Sweep** — expiry is lazy-on-read plus an opportunistic
+  `cleanup_expired` (interval `cleanup_interval`, default 300 s) invoked
+  inside mutating reads. There is **no background reaper**; a consumer like
+  the relaton shard cache needs none.
+- **TTL values** — `ttl: nil` (and no `default_ttl`) never expires;
+  `ttl: 0` is immediately expired.
+
 ## PackageStore — multi-model packages
 
 ```ruby

data/lib/lutaml/store/adapter/memory.rb

@@ -18,6 +18,7 @@ module Lutaml
           @ttl_enabled = @config.fetch(:ttl_enabled, false)
           @ttl_data = @ttl_enabled ? {} : nil
           @default_ttl = @config[:default_ttl] || 3600
+          @max_entries = @config[:max_entries]
         end
 
         # ── Read operations (lock-free via snapshot) ──
@@ -64,6 +65,7 @@ module Lutaml
 
         def set(key, value, metadata = {})
           @write_mutex.synchronize do
+            evict_oldest_if_needed(key)
             @data[key] = value
             invalidate_snapshot
 
@@ -118,6 +120,7 @@ module Lutaml
         def bulk_set(key_value_pairs, ttl: nil)
           @write_mutex.synchronize do
             key_value_pairs.each do |key, value|
+              evict_oldest_if_needed(key)
               @data[key] = value
 
               if @ttl_enabled
@@ -255,6 +258,7 @@ module Lutaml
           snap = snapshot
           super.merge(
             size: snap.size,
+            max_entries: @max_entries,
             ttl_enabled: @ttl_enabled,
             expired_keys: @ttl_enabled ? count_expired_keys : 0
           )
@@ -279,6 +283,19 @@ module Lutaml
           @snapshot_stale = true
         end
 
+        # Capacity bound (max_entries): evict the oldest-INSERTED entry to
+        # make room. Insertion order, not access order — refreshing on read
+        # would cost the lock-free snapshot reads. Updating an existing key
+        # never evicts.
+        def evict_oldest_if_needed(incoming_key)
+          return if @max_entries.nil? || @data.key?(incoming_key) ||
+            @data.size < @max_entries
+
+          oldest = @data.each_key.first
+          @data.delete(oldest)
+          @ttl_data&.delete(oldest)
+        end
+
         def cleanup_expired_if_needed
           return unless @ttl_enabled
 

data/lib/lutaml/store/cache_store.rb

@@ -36,10 +36,12 @@ module Lutaml
 
         def to_h
           {
+            # sub-second precision: a second-truncated created_at shortens
+            # every restored TTL by up to a second (matters at small TTLs)
             value: @value,
-            created_at: @created_at.iso8601,
+            created_at: @created_at.iso8601(6),
             ttl: @ttl,
-            expires_at: expires_at&.iso8601,
+            expires_at: expires_at&.iso8601(6),
             metadata: @metadata
           }
         end

data/lib/lutaml/store/config.rb

@@ -12,7 +12,8 @@ module Lutaml
 
       def initialize(adapter_type: :memory, adapter_options: {},
                      cache: {}, monitoring: {}, events: {},
-                     compression: {}, serialization: {}, **)
+                     compression: {}, serialization: {}, adapter: nil, **)
+        adapter_type = adapter if adapter.is_a?(Hash)
         @adapter_type = normalize_adapter_type(adapter_type)
         @adapter_options = inline_adapter_options(adapter_type).merge(symbolize_keys(adapter_options))
 

data/lib/lutaml/store/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Store
-    VERSION = "0.3.1"
+    VERSION = "0.3.3"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-store
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.3
 platform: ruby
 authors:
 - Ronald Tse
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-11-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.15
+        version: 0.8.156
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.15
+        version: 0.8.156
 - !ruby/object:Gem::Dependency
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement