HeadGym KV Store

This repository contains an append-only namespaced pointer KV store.

TBD: AbortSignal Fixes

The AbortSignal implementation for getLatest, listLatest, and history functions is currently under investigation. The related tests have been temporarily disabled. Further work is needed to ensure proper handling of AbortSignal for these operations, especially considering the non-blocking nature of underlying file system operations.

Description

The HeadGym KV Store is an append-only, namespaced key-value store designed for efficient data management. It provides a simple yet powerful interface for storing and retrieving data, with a focus on immutability and historical data access. This store is particularly useful for applications requiring a verifiable history of data changes or for scenarios where data integrity and auditability are paramount.

Installation & Usage

Installation

To install the HeadGym KV Store, use npm or yarn:

npm install headgymkv
# or
yarn add headgymkv

Usage

Here's a basic example of how to use the HeadGym KV Store:

import { createStore } from './index'; // Assuming usage from within the project or a similar setup
import { join } from 'path';
import { promises as fs } from 'fs';

async function main() {
  const TEST_ROOT_DIR = join(__dirname, '.test_stores');
  const uniqueDir = join(TEST_ROOT_DIR, `store-${Date.now()}-${Math.random().toString(36).substring(7)}`);
  const store = await createStore({ root: uniqueDir });

  try {
    // Put a record
    const pointer = await store.put('testns', 'id1', 'file:///path/to/id1.txt', { tags: ['tag1'] });
    console.log('Record put:', pointer);

    // Get the latest record
    const latest = await store.getLatest('testns', 'id1');
    console.log('Latest record:', latest);

    // Update the record
    const updatedPointer = await store.put('testns', 'id1', 'file:///path/to/id1_v2.txt', { tags: ['tag1', 'v2'] });
    console.log('Record updated:', updatedPointer);

    // Get the updated record
    const updatedLatest = await store.getLatest('testns', 'id1');
    console.log('Updated latest record:', updatedLatest);

    // Get history
    const history = await store.history('testns', 'id1');
    console.log('Record history:', history);

    // Delete the record
    const deletedPointer = await store.del('testns', 'id1', 'test delete');
    console.log('Record deleted:', deletedPointer);

    // Try to get the deleted record (should be undefined by default)
    const afterDelete = await store.getLatest('testns', 'id1');
    console.log('Record after delete (should be undefined):', afterDelete);

    // Get deleted record including deleted ones
    const afterDeleteIncludingDeleted = await store.getLatest('testns', 'id1', { includeDeleted: true });
    console.log('Record after delete (including deleted):', afterDeleteIncludingDeleted);

    // List latest records in a namespace
    await store.put('listns', 'item1', 'uri1');
    await store.put('listns', 'item2', 'uri2');
    const list = await store.listLatest('listns');
    console.log('Latest records in listns:', list);

  } finally {
    await store.close();
    // Clean up the test directory
    if (await fs.stat(TEST_ROOT_DIR).catch(() => null)) {
      await fs.rm(TEST_ROOT_DIR, { recursive: true, force: true });
    }
  }
}

main().catch(console.error);

Release Process

To publish a new version of this package to npm, follow these steps:

1. Update the version in package.json: Increment the version number according to semantic versioning (e.g., patch, minor, major).
2. Commit your changes: Commit all code changes, including the updated package.json.
3. Create a new Git tag: Create an annotated tag matching the new version number.

   git tag -a vX.Y.Z -m "Release version X.Y.Z"

   Replace X.Y.Z with the actual version number.
4. Push the tag to GitHub: Push the newly created tag to your remote repository. This action typically triggers the CI/CD pipeline to publish the package to npm.

   git push origin vX.Y.Z
   # or to push all tags
   git push origin --tags