@lp-labs/transactional-store 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+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.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @lp-labs/transactional-store
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A compact, bounded in-memory JSON key-value store with atomic staged transactions.
+
+## Install
+
+```sh
+npm install @lp-labs/transactional-store
+```
+
+## Quickstart
+
+```js
+import { createTransactionalStore } from '@lp-labs/transactional-store';
+
+const store = createTransactionalStore({ maxEntries: 100 });
+const tx = store.begin();
+tx.set('profile:7', { name: 'Ada' });
+tx.commit();
+console.log(store.get('profile:7'));
+```
+
+## API
+
+`createTransactionalStore({ maxEntries?, maxWrites? })` creates a JSON-only store.
+`begin()` returns a transaction with `get`, `set`, `delete`, `commit`, and
+`rollback`. Reads within a transaction see its staged changes and current store
+values. `commit()` applies all staged writes synchronously or changes nothing;
+it returns write/delete counts. Capacity errors use `StoreError`; a failed
+capacity commit stays open so callers can roll it back. `snapshot()` returns a
+detached record. Default limits are 10,000 entries and 1,000 distinct writes per
+transaction; JSON values are limited to 10,000 nodes, 32 nesting levels, and
+1,000,000 characters.
+
+## Customization
+
+Set `maxEntries` and `maxWrites` when creating a store. Store only plain JSON
+values; returned values are detached copies and do not mutate stored state.
+
+## Limitations
+
+State exists only in this process and is lost when the process exits. This is
+not durable storage, a concurrent transaction scheduler, or a database with
+isolation guarantees. Transactions commit synchronously; concurrent external
+systems are not coordinated.
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,27 @@
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export interface StoreOptions {
+    maxEntries?: number;
+    maxWrites?: number;
+}
+export interface Transaction {
+    get(key: string): Json | undefined;
+    set(key: string, value: Json): void;
+    delete(key: string): void;
+    commit(): {
+        written: number;
+        deleted: number;
+    };
+    rollback(): boolean;
+}
+export interface TransactionalStore {
+    begin(): Transaction;
+    get(key: string): Json | undefined;
+    snapshot(): Record<string, Json>;
+}
+export declare class StoreError extends Error {
+    readonly code: 'invalid' | 'capacity' | 'closed';
+    constructor(code: 'invalid' | 'capacity' | 'closed', message: string);
+}
+export declare function createTransactionalStore(options?: StoreOptions): TransactionalStore;

package/dist/cjs/index.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StoreError = void 0;
+exports.createTransactionalStore = createTransactionalStore;
+class StoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'StoreError';
+    }
+}
+exports.StoreError = StoreError;
+const deleted = Symbol('deleted');
+function keyOf(key) {
+    if (typeof key !== 'string' || key.length < 1 || key.length > 256)
+        throw new StoreError('invalid', 'Keys must contain 1..256 characters.');
+}
+function clone(value) {
+    let nodes = 0;
+    let characters = 0;
+    const visit = (item, depth) => {
+        if (++nodes > 10_000 || depth > 32)
+            throw new StoreError('capacity', 'Value exceeds JSON limits.');
+        if (item === null || typeof item === 'boolean')
+            return item;
+        if (typeof item === 'string') {
+            characters += item.length;
+            if (characters > 1_000_000)
+                throw new StoreError('capacity', 'Value exceeds the text limit.');
+            return item;
+        }
+        if (typeof item === 'number' && Number.isFinite(item))
+            return item;
+        if (Array.isArray(item)) {
+            if (Reflect.ownKeys(item).length !== item.length + 1)
+                throw new StoreError('invalid', 'Arrays must be dense and contain no extra properties.');
+            const result = [];
+            for (let index = 0; index < item.length; index++) {
+                const descriptor = Object.getOwnPropertyDescriptor(item, String(index));
+                if (!descriptor?.enumerable || !('value' in descriptor))
+                    throw new StoreError('invalid', 'Arrays must contain enumerable data elements.');
+                result.push(visit(descriptor.value, depth + 1));
+            }
+            return result;
+        }
+        if (typeof item !== 'object' ||
+            (Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null))
+            throw new StoreError('invalid', 'Values must be plain JSON-compatible data.');
+        const entries = [];
+        for (const name of Reflect.ownKeys(item)) {
+            const descriptor = typeof name === 'string' ? Object.getOwnPropertyDescriptor(item, name) : undefined;
+            if (typeof name !== 'string' || !descriptor?.enumerable || !('value' in descriptor))
+                throw new StoreError('invalid', 'Objects must use enumerable string data properties.');
+            if (name.length > 256)
+                throw new StoreError('invalid', 'Object keys are limited to 256 characters.');
+            characters += name.length;
+            if (characters > 1_000_000)
+                throw new StoreError('capacity', 'Value exceeds the text limit.');
+            entries.push([name, visit(descriptor.value, depth + 1)]);
+        }
+        return Object.fromEntries(entries);
+    };
+    return visit(value, 0);
+}
+function limit(value, name, max = 1_000_000) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > max)
+        throw new StoreError('invalid', `${name} must be an integer from 1 to ${max}.`);
+    return value;
+}
+function createTransactionalStore(options = {}) {
+    if (options === null ||
+        typeof options !== 'object' ||
+        Array.isArray(options) ||
+        (Object.getPrototypeOf(options) !== Object.prototype && Object.getPrototypeOf(options) !== null))
+        throw new StoreError('invalid', 'Options must be a plain object.');
+    for (const key of Reflect.ownKeys(options)) {
+        const descriptor = typeof key === 'string' ? Object.getOwnPropertyDescriptor(options, key) : undefined;
+        if (typeof key !== 'string' ||
+            !['maxEntries', 'maxWrites'].includes(key) ||
+            !descriptor?.enumerable ||
+            !('value' in descriptor) ||
+            typeof descriptor.value !== 'number')
+            throw new StoreError('invalid', 'Options contain an unsupported or invalid field.');
+    }
+    const maxEntries = limit(options.maxEntries ?? 10_000, 'maxEntries');
+    const maxWrites = limit(options.maxWrites ?? 1000, 'maxWrites', 100_000);
+    const values = new Map();
+    const ensurePresent = (key) => {
+        keyOf(key);
+        return values.get(key);
+    };
+    return {
+        get(key) {
+            const value = ensurePresent(key);
+            return value === undefined ? undefined : clone(value);
+        },
+        snapshot() {
+            return Object.fromEntries([...values].map(([key, value]) => [key, clone(value)]));
+        },
+        begin() {
+            const changes = new Map();
+            let open = true;
+            const assertOpen = () => {
+                if (!open)
+                    throw new StoreError('closed', 'Transaction is no longer open.');
+            };
+            return {
+                get(key) {
+                    assertOpen();
+                    keyOf(key);
+                    const staged = changes.get(key);
+                    if (staged === deleted)
+                        return undefined;
+                    if (staged !== undefined)
+                        return clone(staged);
+                    const value = values.get(key);
+                    return value === undefined ? undefined : clone(value);
+                },
+                set(key, value) {
+                    assertOpen();
+                    keyOf(key);
+                    if (!changes.has(key) && changes.size >= maxWrites)
+                        throw new StoreError('capacity', 'Transaction write limit reached.');
+                    changes.set(key, clone(value));
+                },
+                delete(key) {
+                    assertOpen();
+                    keyOf(key);
+                    if (!changes.has(key) && changes.size >= maxWrites)
+                        throw new StoreError('capacity', 'Transaction write limit reached.');
+                    changes.set(key, deleted);
+                },
+                commit() {
+                    assertOpen();
+                    let size = values.size;
+                    for (const [key, value] of changes) {
+                        const existed = values.has(key);
+                        if (value === deleted && existed)
+                            size--;
+                        else if (value !== deleted && !existed)
+                            size++;
+                    }
+                    if (size > maxEntries)
+                        throw new StoreError('capacity', 'Commit would exceed maxEntries.');
+                    let written = 0;
+                    let removed = 0;
+                    for (const [key, value] of changes) {
+                        if (value === deleted) {
+                            if (values.delete(key))
+                                removed++;
+                        }
+                        else {
+                            values.set(key, clone(value));
+                            written++;
+                        }
+                    }
+                    open = false;
+                    return { written, deleted: removed };
+                },
+                rollback() {
+                    if (!open)
+                        return false;
+                    open = false;
+                    changes.clear();
+                    return true;
+                },
+            };
+        },
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,27 @@
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export interface StoreOptions {
+    maxEntries?: number;
+    maxWrites?: number;
+}
+export interface Transaction {
+    get(key: string): Json | undefined;
+    set(key: string, value: Json): void;
+    delete(key: string): void;
+    commit(): {
+        written: number;
+        deleted: number;
+    };
+    rollback(): boolean;
+}
+export interface TransactionalStore {
+    begin(): Transaction;
+    get(key: string): Json | undefined;
+    snapshot(): Record<string, Json>;
+}
+export declare class StoreError extends Error {
+    readonly code: 'invalid' | 'capacity' | 'closed';
+    constructor(code: 'invalid' | 'capacity' | 'closed', message: string);
+}
+export declare function createTransactionalStore(options?: StoreOptions): TransactionalStore;

package/dist/esm/index.js

@@ -0,0 +1,166 @@
+export class StoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'StoreError';
+    }
+}
+const deleted = Symbol('deleted');
+function keyOf(key) {
+    if (typeof key !== 'string' || key.length < 1 || key.length > 256)
+        throw new StoreError('invalid', 'Keys must contain 1..256 characters.');
+}
+function clone(value) {
+    let nodes = 0;
+    let characters = 0;
+    const visit = (item, depth) => {
+        if (++nodes > 10_000 || depth > 32)
+            throw new StoreError('capacity', 'Value exceeds JSON limits.');
+        if (item === null || typeof item === 'boolean')
+            return item;
+        if (typeof item === 'string') {
+            characters += item.length;
+            if (characters > 1_000_000)
+                throw new StoreError('capacity', 'Value exceeds the text limit.');
+            return item;
+        }
+        if (typeof item === 'number' && Number.isFinite(item))
+            return item;
+        if (Array.isArray(item)) {
+            if (Reflect.ownKeys(item).length !== item.length + 1)
+                throw new StoreError('invalid', 'Arrays must be dense and contain no extra properties.');
+            const result = [];
+            for (let index = 0; index < item.length; index++) {
+                const descriptor = Object.getOwnPropertyDescriptor(item, String(index));
+                if (!descriptor?.enumerable || !('value' in descriptor))
+                    throw new StoreError('invalid', 'Arrays must contain enumerable data elements.');
+                result.push(visit(descriptor.value, depth + 1));
+            }
+            return result;
+        }
+        if (typeof item !== 'object' ||
+            (Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null))
+            throw new StoreError('invalid', 'Values must be plain JSON-compatible data.');
+        const entries = [];
+        for (const name of Reflect.ownKeys(item)) {
+            const descriptor = typeof name === 'string' ? Object.getOwnPropertyDescriptor(item, name) : undefined;
+            if (typeof name !== 'string' || !descriptor?.enumerable || !('value' in descriptor))
+                throw new StoreError('invalid', 'Objects must use enumerable string data properties.');
+            if (name.length > 256)
+                throw new StoreError('invalid', 'Object keys are limited to 256 characters.');
+            characters += name.length;
+            if (characters > 1_000_000)
+                throw new StoreError('capacity', 'Value exceeds the text limit.');
+            entries.push([name, visit(descriptor.value, depth + 1)]);
+        }
+        return Object.fromEntries(entries);
+    };
+    return visit(value, 0);
+}
+function limit(value, name, max = 1_000_000) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > max)
+        throw new StoreError('invalid', `${name} must be an integer from 1 to ${max}.`);
+    return value;
+}
+export function createTransactionalStore(options = {}) {
+    if (options === null ||
+        typeof options !== 'object' ||
+        Array.isArray(options) ||
+        (Object.getPrototypeOf(options) !== Object.prototype && Object.getPrototypeOf(options) !== null))
+        throw new StoreError('invalid', 'Options must be a plain object.');
+    for (const key of Reflect.ownKeys(options)) {
+        const descriptor = typeof key === 'string' ? Object.getOwnPropertyDescriptor(options, key) : undefined;
+        if (typeof key !== 'string' ||
+            !['maxEntries', 'maxWrites'].includes(key) ||
+            !descriptor?.enumerable ||
+            !('value' in descriptor) ||
+            typeof descriptor.value !== 'number')
+            throw new StoreError('invalid', 'Options contain an unsupported or invalid field.');
+    }
+    const maxEntries = limit(options.maxEntries ?? 10_000, 'maxEntries');
+    const maxWrites = limit(options.maxWrites ?? 1000, 'maxWrites', 100_000);
+    const values = new Map();
+    const ensurePresent = (key) => {
+        keyOf(key);
+        return values.get(key);
+    };
+    return {
+        get(key) {
+            const value = ensurePresent(key);
+            return value === undefined ? undefined : clone(value);
+        },
+        snapshot() {
+            return Object.fromEntries([...values].map(([key, value]) => [key, clone(value)]));
+        },
+        begin() {
+            const changes = new Map();
+            let open = true;
+            const assertOpen = () => {
+                if (!open)
+                    throw new StoreError('closed', 'Transaction is no longer open.');
+            };
+            return {
+                get(key) {
+                    assertOpen();
+                    keyOf(key);
+                    const staged = changes.get(key);
+                    if (staged === deleted)
+                        return undefined;
+                    if (staged !== undefined)
+                        return clone(staged);
+                    const value = values.get(key);
+                    return value === undefined ? undefined : clone(value);
+                },
+                set(key, value) {
+                    assertOpen();
+                    keyOf(key);
+                    if (!changes.has(key) && changes.size >= maxWrites)
+                        throw new StoreError('capacity', 'Transaction write limit reached.');
+                    changes.set(key, clone(value));
+                },
+                delete(key) {
+                    assertOpen();
+                    keyOf(key);
+                    if (!changes.has(key) && changes.size >= maxWrites)
+                        throw new StoreError('capacity', 'Transaction write limit reached.');
+                    changes.set(key, deleted);
+                },
+                commit() {
+                    assertOpen();
+                    let size = values.size;
+                    for (const [key, value] of changes) {
+                        const existed = values.has(key);
+                        if (value === deleted && existed)
+                            size--;
+                        else if (value !== deleted && !existed)
+                            size++;
+                    }
+                    if (size > maxEntries)
+                        throw new StoreError('capacity', 'Commit would exceed maxEntries.');
+                    let written = 0;
+                    let removed = 0;
+                    for (const [key, value] of changes) {
+                        if (value === deleted) {
+                            if (values.delete(key))
+                                removed++;
+                        }
+                        else {
+                            values.set(key, clone(value));
+                            written++;
+                        }
+                    }
+                    open = false;
+                    return { written, deleted: removed };
+                },
+                rollback() {
+                    if (!open)
+                        return false;
+                    open = false;
+                    changes.clear();
+                    return true;
+                },
+            };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/transactional-store",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A bounded in-memory key-value store with atomic staged transactions.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build && node scripts/check-types.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}