@sandsoftwaresolutions/json-store 0.0.0-stage → 0.1.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @sandsoftwaresolutions/json-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.
+[![CI](https://github.com/SandSoftwareSolutions/ss-json-store/actions/workflows/ci.yml/badge.svg)](https://github.com/SandSoftwareSolutions/ss-json-store/actions/workflows/ci.yml)
+
+A small database for the things that do not need a database: settings, state, a few records, in one JSON file. Safe writes, updates that never get lost, and migrations when the shape changes. No dependencies.
+
+## Install
+
+```bash
+npm install @sandsoftwaresolutions/json-store
+```
+
+Works with `import` and `require()`, and ships TypeScript types for both.
+
+## Usage
+
+```js
+import { openStore } from "@sandsoftwaresolutions/json-store";
+
+const store = await openStore({
+  path: "/var/lib/myapp/state.json",
+  defaults: { lastRun: 0, failures: 0 }
+});
+
+store.get();                                   // { lastRun: 0, failures: 0 } (a copy)
+await store.update((state) => { state.failures += 1; });   // change in place...
+await store.update((state) => ({ ...state, lastRun: Date.now() })); // ...or return a new value
+await store.set({ lastRun: 0, failures: 0 });  // replace everything
+```
+
+## What it takes care of
+
+- **Atomic writes.** The file is written to a temporary file, flushed, and renamed over the old one, so a crash or power cut never leaves half a file.
+- **No lost updates.** Updates run one after the other, in order, even when the callbacks are async. Fifty `update` calls at the same time give fifty changes.
+- **Rollback.** If your callback throws or the write fails, the data stays as it was.
+- **What is in memory is what is on disk.** The data goes through JSON on every change, so a `Date` becomes a string, `undefined` fields disappear and `NaN`/`Infinity` become `null` right away, not only after a restart. `Map`, `Set` and class instances are not supported.
+- **Copies, not references.** `get()` returns a copy, so changing it by accident changes nothing.
+- **A private file.** A new file is created with permissions `600`, because stores tend to hold tokens. The permissions of an existing file are kept exactly.
+- **It refuses to destroy what it does not understand.** A corrupt file, a file that is not a store, or a file from a newer version of your program is *never* overwritten: you get an error that names the file. The same goes when a migration throws, whatever the error. A byte order mark at the start of the file is ignored.
+
+## Migrations
+
+The file is `{ "version": 1, "data": { ... } }`. When the shape of your data changes, raise `version` and add a migration:
+
+```js
+const store = await openStore({
+  path, version: 3, defaults: { first: "", last: "", tags: [] },
+  migrations: {
+    2: (old) => ({ first: old.name.split(" ")[0], last: old.name.split(" ").slice(1).join(" ") }),
+    3: (old) => ({ ...old, tags: [] })
+  }
+});
+```
+
+Each migration upgrades from the version before it. The old file is kept as `<path>.v1.bak` before the first write of the new shape. A missing migration is an error at startup. `backup: true` also keeps `<path>.bak` of the previous content on every write.
+
+## Not for everything
+
+The whole file is read once and written on every change. That is fine for kilobytes, not for megabytes or heavy traffic; for that use SQLite (`@sandsoftwaresolutions/sqlite-kit`). One process should own the file; for several, add `@sandsoftwaresolutions/file-lock`.

package/dist/index.cjs

@@ -0,0 +1,136 @@
+"use strict";
+const { randomBytes } = require("node:crypto");
+const { constants } = require("node:fs");
+const { mkdir, open, readFile, rename, stat, unlink } = require("node:fs/promises");
+const { basename, dirname, join } = require("node:path");
+
+// What goes into the file is JSON, so that is also what the store holds in memory: a Date is a string, undefined fields are gone,
+// and what get() returns right after an update is exactly what a reopened store returns.
+const plain = (value) => {
+  const text = JSON.stringify(value);
+  return text === undefined ? undefined : JSON.parse(text);
+};
+
+async function writeAtomic(path, text) {
+  const temp = join(dirname(path), `.${basename(path)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
+  let mode = 0o600;
+  let keep = false;
+  try {
+    mode = (await stat(path)).mode & 0o7777;
+    keep = true;
+  } catch {
+    // New file: private by default, because stores often hold settings and tokens.
+  }
+  const handle = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, mode);
+  try {
+    if (keep && process.platform !== "win32") await handle.chmod(mode); // exactly as before, whatever the umask
+    await handle.writeFile(text);
+    await handle.sync();
+  } catch (error) {
+    await handle.close().catch(() => {});
+    await unlink(temp).catch(() => {});
+    throw error;
+  }
+  await handle.close();
+  try {
+    await rename(temp, path);
+  } catch (error) {
+    await unlink(temp).catch(() => {});
+    throw error;
+  }
+}
+
+/**
+ * A small store for one JSON file: settings, state, a few records. Writes are atomic (a crash never leaves half a file), changes
+ * are applied one at a time in order (so two quick updates do not lose one), and the file has a version number so you can change
+ * its shape later with migrations.
+ *
+ * Options: `path`, `defaults` (value for a new store; the starting point), `version` (current version, default 1),
+ * `migrations` ({ 2: (data) => newData, 3: ... } each upgrades from the version before it), `backup` (keep `<path>.bak` of the
+ * previous file on every write, default false).
+ * The file looks like `{ "version": 1, "data": { ... } }`.
+ */
+async function openStore({ path, defaults = {}, version = 1, migrations = {}, backup = false } = {}) {
+  if (typeof path !== "string" || path === "") throw new TypeError("json-store: path is required");
+  if (!Number.isInteger(version) || version < 1) throw new RangeError("json-store: version must be a whole number, 1 or more");
+  for (let v = 2; v <= version; v++) {
+    if (typeof migrations[v] !== "function") throw new TypeError(`json-store: missing migration for version ${v}`);
+  }
+  await mkdir(dirname(path), { recursive: true });
+
+  let data;
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    // Only a missing file starts a new store. Anything that goes wrong after this point (a failing migration, a failing write)
+    // must never be mistaken for a missing file, or the data in the file would be replaced by the defaults.
+    if (error.code !== "ENOENT") throw error;
+  }
+  if (text !== undefined) {
+    let file;
+    try {
+      file = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+    } catch (error) {
+      throw new SyntaxError(`json-store: ${path} is not valid JSON (${error.message}). It was not touched; fix or remove it.`);
+    }
+    if (file === null || typeof file !== "object" || !Number.isInteger(file.version) || !("data" in file)) {
+      throw new SyntaxError(`json-store: ${path} is not a store file (expected { version, data }). It was not touched.`);
+    }
+    if (file.version < 1) throw new RangeError(`json-store: ${path} has version ${file.version}; versions start at 1. It was not touched.`);
+    if (file.version > version) throw new RangeError(`json-store: ${path} is version ${file.version}, newer than this program understands (${version}). It was not touched.`);
+    data = file.data;
+    for (let v = file.version + 1; v <= version; v++) data = plain(await migrations[v](structuredClone(data)));
+    if (file.version < version) await persist(file.version);
+  } else {
+    data = plain(defaults);
+    if (data === undefined) data = {};
+    await persist();
+  }
+
+  let queue = Promise.resolve();
+  async function persist(fromVersion) {
+    if (backup || fromVersion !== undefined) {
+      // Keep the old file before replacing it with a changed shape, and on every write when backup is on.
+      try {
+        const old = await readFile(path, "utf8");
+        await writeAtomic(fromVersion !== undefined ? `${path}.v${fromVersion}.bak` : `${path}.bak`, old);
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    await writeAtomic(path, `${JSON.stringify({ version, data }, null, 2)}\n`);
+  }
+
+  const api = {
+    /** A copy of the current data. Changing the copy changes nothing; use `update`. */
+    get: () => structuredClone(data),
+    /**
+     * Changes the data: `await store.update((d) => { d.count++; })` (change it in place) or return a new value.
+     * Updates run one after the other. If `fn` throws or the write fails, the data stays as it was.
+     */
+    update(fn) {
+      const run = queue.then(async () => {
+        const draft = structuredClone(data);
+        const result = await fn(draft);
+        const before = data;
+        data = result === undefined ? plain(draft) : plain(result);
+        try {
+          await persist();
+        } catch (error) {
+          data = before;
+          throw error;
+        }
+        return structuredClone(data);
+      });
+      queue = run.catch(() => {});
+      return run;
+    },
+    /** Replaces everything. */
+    set: (value) => api.update(() => structuredClone(value)),
+    path
+  };
+  return api;
+}
+
+exports.openStore = openStore;

package/dist/index.d.cts

@@ -0,0 +1,22 @@
+export interface StoreOptions<T> {
+  path: string;
+  /** The starting value for a new store. Default {}. */
+  defaults?: T;
+  /** Current version of the data's shape. Default 1. */
+  version?: number;
+  /** `{ 2: (old) => new, 3: ... }`: each upgrades the data from the version before it. */
+  migrations?: Record<number, (data: any) => any | Promise<any>>;
+  /** Keep `<path>.bak` of the previous file on every write. */
+  backup?: boolean;
+}
+
+export interface Store<T> {
+  /** A copy: changing it changes nothing. */
+  get(): T;
+  /** Change `draft` in place, or return a new value. Runs after earlier updates. Rolls back if it throws or the write fails. */
+  update(fn: (draft: T) => T | void | Promise<T | void>): Promise<T>;
+  set(value: T): Promise<T>;
+  readonly path: string;
+}
+
+export function openStore<T = Record<string, unknown>>(options: StoreOptions<T>): Promise<Store<T>>;

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@sandsoftwaresolutions/json-store",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A small JSON file store: atomic writes, ordered updates, rollback and versioned migrations. Never overwrites a file it does not understand.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./src/index.d.ts",
+        "default": "./src/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test && node scripts/build-cjs.mjs --check",
+    "pack:check": "npm pack --dry-run",
+    "build": "node scripts/build-cjs.mjs",
+    "prepack": "node scripts/build-cjs.mjs"
+  },
+  "keywords": [
+    "json",
+    "store",
+    "settings",
+    "state",
+    "migrations"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SandSoftwareSolutions/ss-json-store.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SandSoftwareSolutions/ss-json-store/issues"
+  },
+  "homepage": "https://github.com/SandSoftwareSolutions/ss-json-store#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,22 @@
+export interface StoreOptions<T> {
+  path: string;
+  /** The starting value for a new store. Default {}. */
+  defaults?: T;
+  /** Current version of the data's shape. Default 1. */
+  version?: number;
+  /** `{ 2: (old) => new, 3: ... }`: each upgrades the data from the version before it. */
+  migrations?: Record<number, (data: any) => any | Promise<any>>;
+  /** Keep `<path>.bak` of the previous file on every write. */
+  backup?: boolean;
+}
+
+export interface Store<T> {
+  /** A copy: changing it changes nothing. */
+  get(): T;
+  /** Change `draft` in place, or return a new value. Runs after earlier updates. Rolls back if it throws or the write fails. */
+  update(fn: (draft: T) => T | void | Promise<T | void>): Promise<T>;
+  set(value: T): Promise<T>;
+  readonly path: string;
+}
+
+export function openStore<T = Record<string, unknown>>(options: StoreOptions<T>): Promise<Store<T>>;

package/src/index.js

@@ -0,0 +1,133 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, readFile, rename, stat, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+// What goes into the file is JSON, so that is also what the store holds in memory: a Date is a string, undefined fields are gone,
+// and what get() returns right after an update is exactly what a reopened store returns.
+const plain = (value) => {
+  const text = JSON.stringify(value);
+  return text === undefined ? undefined : JSON.parse(text);
+};
+
+async function writeAtomic(path, text) {
+  const temp = join(dirname(path), `.${basename(path)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
+  let mode = 0o600;
+  let keep = false;
+  try {
+    mode = (await stat(path)).mode & 0o7777;
+    keep = true;
+  } catch {
+    // New file: private by default, because stores often hold settings and tokens.
+  }
+  const handle = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, mode);
+  try {
+    if (keep && process.platform !== "win32") await handle.chmod(mode); // exactly as before, whatever the umask
+    await handle.writeFile(text);
+    await handle.sync();
+  } catch (error) {
+    await handle.close().catch(() => {});
+    await unlink(temp).catch(() => {});
+    throw error;
+  }
+  await handle.close();
+  try {
+    await rename(temp, path);
+  } catch (error) {
+    await unlink(temp).catch(() => {});
+    throw error;
+  }
+}
+
+/**
+ * A small store for one JSON file: settings, state, a few records. Writes are atomic (a crash never leaves half a file), changes
+ * are applied one at a time in order (so two quick updates do not lose one), and the file has a version number so you can change
+ * its shape later with migrations.
+ *
+ * Options: `path`, `defaults` (value for a new store; the starting point), `version` (current version, default 1),
+ * `migrations` ({ 2: (data) => newData, 3: ... } each upgrades from the version before it), `backup` (keep `<path>.bak` of the
+ * previous file on every write, default false).
+ * The file looks like `{ "version": 1, "data": { ... } }`.
+ */
+export async function openStore({ path, defaults = {}, version = 1, migrations = {}, backup = false } = {}) {
+  if (typeof path !== "string" || path === "") throw new TypeError("json-store: path is required");
+  if (!Number.isInteger(version) || version < 1) throw new RangeError("json-store: version must be a whole number, 1 or more");
+  for (let v = 2; v <= version; v++) {
+    if (typeof migrations[v] !== "function") throw new TypeError(`json-store: missing migration for version ${v}`);
+  }
+  await mkdir(dirname(path), { recursive: true });
+
+  let data;
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    // Only a missing file starts a new store. Anything that goes wrong after this point (a failing migration, a failing write)
+    // must never be mistaken for a missing file, or the data in the file would be replaced by the defaults.
+    if (error.code !== "ENOENT") throw error;
+  }
+  if (text !== undefined) {
+    let file;
+    try {
+      file = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+    } catch (error) {
+      throw new SyntaxError(`json-store: ${path} is not valid JSON (${error.message}). It was not touched; fix or remove it.`);
+    }
+    if (file === null || typeof file !== "object" || !Number.isInteger(file.version) || !("data" in file)) {
+      throw new SyntaxError(`json-store: ${path} is not a store file (expected { version, data }). It was not touched.`);
+    }
+    if (file.version < 1) throw new RangeError(`json-store: ${path} has version ${file.version}; versions start at 1. It was not touched.`);
+    if (file.version > version) throw new RangeError(`json-store: ${path} is version ${file.version}, newer than this program understands (${version}). It was not touched.`);
+    data = file.data;
+    for (let v = file.version + 1; v <= version; v++) data = plain(await migrations[v](structuredClone(data)));
+    if (file.version < version) await persist(file.version);
+  } else {
+    data = plain(defaults);
+    if (data === undefined) data = {};
+    await persist();
+  }
+
+  let queue = Promise.resolve();
+  async function persist(fromVersion) {
+    if (backup || fromVersion !== undefined) {
+      // Keep the old file before replacing it with a changed shape, and on every write when backup is on.
+      try {
+        const old = await readFile(path, "utf8");
+        await writeAtomic(fromVersion !== undefined ? `${path}.v${fromVersion}.bak` : `${path}.bak`, old);
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    await writeAtomic(path, `${JSON.stringify({ version, data }, null, 2)}\n`);
+  }
+
+  const api = {
+    /** A copy of the current data. Changing the copy changes nothing; use `update`. */
+    get: () => structuredClone(data),
+    /**
+     * Changes the data: `await store.update((d) => { d.count++; })` (change it in place) or return a new value.
+     * Updates run one after the other. If `fn` throws or the write fails, the data stays as it was.
+     */
+    update(fn) {
+      const run = queue.then(async () => {
+        const draft = structuredClone(data);
+        const result = await fn(draft);
+        const before = data;
+        data = result === undefined ? plain(draft) : plain(result);
+        try {
+          await persist();
+        } catch (error) {
+          data = before;
+          throw error;
+        }
+        return structuredClone(data);
+      });
+      queue = run.catch(() => {});
+      return run;
+    },
+    /** Replaces everything. */
+    set: (value) => api.update(() => structuredClone(value)),
+    path
+  };
+  return api;
+}