commitkv 1.0.1__tar.gz → 1.1.1__tar.gz

{commitkv-1.0.1 → commitkv-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commitkv
-Version: 1.0.1
+Version: 1.1.1
 License-File: LICENSE
 Summary: Compressed key-value store for git-managed caches: append-only segments that never exceed a size limit
 License-Expression: Apache-2.0
@@ -11,6 +11,13 @@ Project-URL: Repository, https://github.com/WillBooster/commitkv
 
 # commitkv
 
+[![npm version](https://img.shields.io/npm/v/commitkv.svg)](https://www.npmjs.com/package/commitkv)
+[![license](https://img.shields.io/npm/l/commitkv.svg)](https://www.npmjs.com/package/commitkv)
+[![Test](https://github.com/WillBooster/commitkv/actions/workflows/test.yml/badge.svg)](https://github.com/WillBooster/commitkv/actions/workflows/test.yml)
+[![Test rust](https://github.com/WillBooster/commitkv/actions/workflows/test-rust.yml/badge.svg)](https://github.com/WillBooster/commitkv/actions/workflows/test-rust.yml)
+[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
+[![wbfy](https://img.shields.io/badge/wbfy-20.43.2-1e90ff.svg)](https://github.com/WillBooster/shared/tree/main/packages/wbfy)
+
 A compressed key-value store for caches that are committed to git, usable from Python,
 Node.js, and Bun.
 
@@ -80,6 +87,14 @@ store.refresh(); // pick up what other stores wrote to the directory
   writing (the first `put`, and the first after a failed one); records that other stores write
   stay invisible until one of those happens. Call `refresh` after
   replacing segments under an open store, for example by checking out another branch.
+- Stores that write to a directory at the same time each append to a segment of their own, and
+  the next run continues at most one of them. Open one store per directory in a process and share
+  it; a store per use leaves a small segment behind on every run, and a small segment
+  compresses worse because its values have few earlier ones to refer to.
+- `keys` lists the keys in the order their current values lie in the segments, oldest segment
+  first. One store's writes are listed in the order it made them; the writes of several stores
+  are grouped by segment, so their order does not tell which was made first. Read every value
+  in that order: a scattered order decodes the surrounding values again for most of them.
 - Among records of a key that stores wrote without seeing each other's, which one wins is
   unspecified, but every reader picks the same one.
 - `max_segment_bytes` / `maxSegmentBytes` must be between 1,024 and 100,000,000; the upper

{commitkv-1.0.1 → commitkv-1.1.1}/README.md

@@ -1,5 +1,12 @@
 # commitkv
 
+[![npm version](https://img.shields.io/npm/v/commitkv.svg)](https://www.npmjs.com/package/commitkv)
+[![license](https://img.shields.io/npm/l/commitkv.svg)](https://www.npmjs.com/package/commitkv)
+[![Test](https://github.com/WillBooster/commitkv/actions/workflows/test.yml/badge.svg)](https://github.com/WillBooster/commitkv/actions/workflows/test.yml)
+[![Test rust](https://github.com/WillBooster/commitkv/actions/workflows/test-rust.yml/badge.svg)](https://github.com/WillBooster/commitkv/actions/workflows/test-rust.yml)
+[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
+[![wbfy](https://img.shields.io/badge/wbfy-20.43.2-1e90ff.svg)](https://github.com/WillBooster/shared/tree/main/packages/wbfy)
+
 A compressed key-value store for caches that are committed to git, usable from Python,
 Node.js, and Bun.
 
@@ -69,6 +76,14 @@ store.refresh(); // pick up what other stores wrote to the directory
   writing (the first `put`, and the first after a failed one); records that other stores write
   stay invisible until one of those happens. Call `refresh` after
   replacing segments under an open store, for example by checking out another branch.
+- Stores that write to a directory at the same time each append to a segment of their own, and
+  the next run continues at most one of them. Open one store per directory in a process and share
+  it; a store per use leaves a small segment behind on every run, and a small segment
+  compresses worse because its values have few earlier ones to refer to.
+- `keys` lists the keys in the order their current values lie in the segments, oldest segment
+  first. One store's writes are listed in the order it made them; the writes of several stores
+  are grouped by segment, so their order does not tell which was made first. Read every value
+  in that order: a scattered order decodes the surrounding values again for most of them.
 - Among records of a key that stores wrote without seeing each other's, which one wins is
   unspecified, but every reader picks the same one.
 - `max_segment_bytes` / `maxSegmentBytes` must be between 1,024 and 100,000,000; the upper

{commitkv-1.0.1 → commitkv-1.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "commitkv"
-version = "1.0.1"
+version = "1.1.1"
 description = "Compressed key-value store for git-managed caches: append-only segments that never exceed a size limit"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -11,10 +11,10 @@ Repository = "https://github.com/WillBooster/commitkv"
 Issues = "https://github.com/WillBooster/commitkv/issues"
 
 [dependency-groups]
-dev = ["pytest>=8"]
+dev = ["black>=26.10.1", "flake8>=7.4.1", "isort>=9.0.2", "pytest==9.1.1"]
 
 [build-system]
-requires = ["maturin>=1.9,<2"]
+requires = ["maturin==1.15.0"]
 build-backend = "maturin"
 
 [tool.maturin]

{commitkv-1.0.1 → commitkv-1.1.1}/python/commitkv/_native.pyi

@@ -25,6 +25,9 @@ class Store:
 
     def __contains__(self, key: str | bytes) -> bool: ...
     def __len__(self) -> int: ...
-    def keys(self) -> list[bytes]: ...
+    def keys(self) -> list[bytes]:
+        """Lists the keys in the order their current values lie in the segments, oldest segment
+        first, which is the order one store wrote them; reading every value is fastest in this
+        order."""
     def refresh(self) -> None:
         """Picks up records that other stores wrote to the directory."""

{commitkv-1.0.1 → commitkv-1.1.1}/rust/crates/commitkv/src/store.rs

@@ -214,9 +214,14 @@ impl Store {
         self.len() == 0
     }
 
+    /// The keys in the order their current records lie in the segments, oldest segment first,
+    /// so reading every value in this order decodes each group once. This is the order one
+    /// store wrote them; stores that write at the same time fill segments of their own.
     pub fn keys(&self) -> Vec<Vec<u8>> {
         let state = self.read_state();
-        state.index.keys().map(|key| key.to_vec()).collect()
+        let mut entries: Vec<_> = state.index.iter().collect();
+        entries.sort_unstable_by_key(|(_, location)| state.position(location));
+        entries.into_iter().map(|(key, _)| key.to_vec()).collect()
     }
 
     /// Picks up records that other stores wrote to the directory since the last call, and
@@ -611,6 +616,12 @@ impl State {
         index
     }
 
+    /// Orders records by age: segment names order by creation time and offsets order within a
+    /// segment.
+    fn position(&self, location: &Location) -> (&str, u64) {
+        (&self.segments[location.segment].name, location.end)
+    }
+
     /// Adds a record that follows the scanned part of its segment; `false` when the record
     /// cannot be placed, which leaves the state unchanged.
     fn apply(&mut self, segment_index: usize, record: &Record) -> bool {
@@ -648,12 +659,11 @@ impl State {
         segment.scanned = location.end;
         segment.group_raw = group_raw_end;
         segment.raw_total = raw_total;
-        // The newest record of a key wins: segment names order by creation time and offsets
-        // order within a segment.
-        let newer = self.index.get(record.key).is_none_or(|current| {
-            (&self.segments[current.segment].name, current.end)
-                < (&self.segments[segment_index].name, location.end)
-        });
+        // The newest record of a key wins.
+        let newer = self
+            .index
+            .get(record.key)
+            .is_none_or(|current| self.position(current) < self.position(&location));
         if newer {
             self.index.insert(record.key.into(), location);
         }

{commitkv-1.0.1 → commitkv-1.1.1}/rust/crates/commitkv/tests/store.rs

@@ -55,6 +55,21 @@ fn values_survive_reopening_and_the_latest_value_of_a_key_wins() {
     assert!(keys.binary_search(&b"large".to_vec()).is_ok());
 }
 
+#[test]
+fn keys_are_listed_in_the_order_a_store_wrote_their_current_values() {
+    let dir = tempfile::tempdir().unwrap();
+    {
+        let store = Store::open(dir.path(), small_segments()).unwrap();
+        for i in 0..400 {
+            store.put(&key(i), &noise(i as u64, 1000)).unwrap();
+        }
+        store.put(&key(3), b"replaced").unwrap();
+    }
+    assert!(segment_paths(dir.path()).len() > 1);
+    let expected: Vec<Vec<u8>> = (0..400).filter(|&i| i != 3).chain([3]).map(key).collect();
+    assert_eq!(open(dir.path()).keys(), expected);
+}
+
 #[test]
 fn no_segment_exceeds_the_limit() {
     let dir = tempfile::tempdir().unwrap();