datavolve 0.9.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2026 Pavel Grinchenko
+
+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

@@ -0,0 +1,289 @@
+# datavolve
+
+Tiny, type-safe evolutions for versioned data. Storage-agnostic, dependency-free, synchronous.
+
+[![npm version](https://img.shields.io/npm/v/datavolve.svg)](https://www.npmjs.com/package/datavolve)
+[![Bundle size](https://img.shields.io/badge/Bundle_size-258_B-brightgreen)](https://github.com/psd-coder/datavolve/blob/main/packages/datavolve/package.json)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+`datavolve` brings an old persisted value forward to its latest shape through a chain of forward-only evolutions. Point it at whatever you persisted last year (localStorage, IndexedDB, a synced blob, a config file) and get back the shape your code expects today, with full type inference along the way.
+
+## Features
+
+- ✅ Full type inference through the evolution chain — no intermediate annotations
+- ✅ Forward-only, pure `(prev) => next` transforms — no reverse evolutions, no side effects
+- ✅ Total `run` — returns a discriminated result, never throws
+- ✅ Storage-agnostic — the version comes in as an argument; `datavolve` never reads or writes it
+- ✅ Zero dependencies, tiny (258 B), ESM-only
+
+## Installation
+
+```bash
+# npm
+npm install datavolve
+
+# pnpm
+pnpm add datavolve
+
+# yarn
+yarn add datavolve
+```
+
+Requires an ESM environment. No peer dependencies.
+
+## Core Concepts
+
+Real apps change the shape of the data they persist. A returning user's browser can hold data written by a version of your app from six months ago. Without an evolution step that old value flows into new code and either crashes or, worse, silently corrupts state. `datavolve` is the small primitive that closes that gap: declare how each version differs from the last, and let it walk any stored value up to the current shape.
+
+It is useful wherever the shape of persisted client data evolves over time:
+
+- localStorage / sessionStorage state
+- IndexedDB records
+- A synced JSON blob or config file
+- Any versioned value read back by newer code
+
+## Usage
+
+### Step 1: Declare your evolutions
+
+You add evolutions in order, starting at version `1`. Each one takes the previous version's value and returns the next. The input to the **first** evolution is `unknown` on purpose — it is genuinely untrusted data, and narrowing it is the evolution's job.
+
+```typescript
+import { datavolve } from "datavolve";
+
+const settings = datavolve()
+  .add(1, (raw) => ({ theme: "light" })) // legacy -> v1
+  .add(2, (v1) => ({ ...v1, fontScale: 1 })) // v1 -> v2
+  .add(3, (v2) => ({ ...v2, theme: v2.theme === "light" ? "day" : "night" })); // v2 -> v3
+```
+
+### Step 2: Run against stored data
+
+You tell `run` what version the incoming data is; `datavolve` never looks for a `version` field inside your value. Data with no version at all is version `0` and runs the whole chain.
+
+```typescript
+const result = settings.run(storedValue, storedVersion);
+```
+
+### Step 3: Handle the result
+
+`run` returns a discriminated result, so the compiler makes you handle failure. Each error `code` carries exactly the fields relevant to it. On success the result carries the evolved `value` together with the `version` it is now at (always `latestVersion`), so you can persist the upgraded data in one place.
+
+```typescript
+if (result.success) {
+  useSettings(result.value); // typed as the v3 shape
+  save({ version: result.version, value: result.value }); // store them together
+} else {
+  switch (result.error.code) {
+    case "ahead":
+      // stored data is newer than this build understands
+      promptUserToUpdateApp(result.error.latestVersion);
+      break;
+    case "malformed":
+      // fromVersion was negative or non-integer
+      resetToDefaults();
+      break;
+    case "failed":
+      // one of your evolutions threw; the original error is in `cause`
+      report(result.error.cause);
+      resetToDefaults();
+      break;
+  }
+}
+```
+
+## Narrowing Untrusted Input
+
+The first evolution's input is `unknown`. Narrow it with a runtime check, not a cast. Either a small type guard (zero dependencies):
+
+```typescript
+const isRecord = (x: unknown): x is Record<string, unknown> =>
+  typeof x === "object" && x !== null;
+
+datavolve().add(1, (legacy) => {
+  const old = isRecord(legacy) ? legacy : {};
+  return { theme: old["theme"] === "light" ? "light" : "dark" };
+});
+```
+
+or a validator you already use (Valibot, Zod, etc.):
+
+```typescript
+import * as v from "valibot";
+
+const legacySchema = v.object({ theme: v.optional(v.string()) });
+
+datavolve().add(1, (legacy) => {
+  const old = v.parse(legacySchema, legacy); // throws on garbage -> reported as `failed`
+  return { theme: old.theme === "light" ? "light" : "dark" };
+});
+```
+
+A raw `as` would skip the check and let malformed legacy data through untyped — exactly what you don't want at this boundary.
+
+## API
+
+### `datavolve()`
+
+Creates an empty, immutable datavolve instance.
+
+### `.add(version, evolve)`
+
+Appends an evolution and returns a **new** datavolve instance whose output type is inferred from `evolve`'s return value.
+
+- `version` — a positive integer, sequential from `1`. Adding a non-sequential version throws immediately (a build-time programmer error), which also protects you from silently misaligning stored data if an evolution is deleted.
+- `evolve` — `(prev) => next`. `prev` is `unknown` for version `1`, and the previous evolution's output type thereafter.
+
+### `.run(data, fromVersion)`
+
+Runs the applicable evolutions. **Total** — it never throws; an evolution that itself throws is caught and reported. Returns an `EvolveResult`.
+
+- `data: unknown` — the stored value.
+- `fromVersion: number` — the version `data` is currently at. Required.
+
+### `.latestVersion`
+
+The highest version datavolve knows about. Use it to stamp data on write-back:
+
+```typescript
+storage.setItem(
+  key,
+  JSON.stringify({ version: settings.latestVersion, value }),
+);
+```
+
+### Types
+
+```typescript
+type EvolveResult<T> =
+  | { success: true; value: T; version: number } // version = the version `value` is now at (always latestVersion)
+  | { success: false; error: EvolveError };
+
+type EvolveError =
+  | { code: "ahead"; fromVersion: number; latestVersion: number }
+  | { code: "malformed"; fromVersion: number }
+  | { code: "failed"; failedVersion: number; cause: unknown };
+
+type Datavolve<T>; // the datavolve instance, generic over its latest output type
+```
+
+## Version Behavior
+
+| `fromVersion`                     | Result                                                              |
+| --------------------------------- | ------------------------------------------------------------------- |
+| `=== latestVersion`               | success, value returned unchanged (no-op fast path)                 |
+| `0 ≤ fromVersion < latestVersion` | success, evolutions `(fromVersion, latestVersion]` applied in order |
+| `> latestVersion`                 | failure `ahead`                                                     |
+| `< 0` or non-integer              | failure `malformed`                                                 |
+| an evolution throws                | failure `failed` (with `cause`)                                     |
+
+## Validation
+
+`datavolve` does **no** validation of its own — the inferred output type of `run` is a _claim_ each evolution makes, not a runtime guarantee that untrusted stored data matches. Make it a guarantee by driving each evolution with a schema. Define one schema per version (each reusing the previous where it can), and let every evolution validate the shape it receives and transform it to the next with [Valibot](https://valibot.dev)'s `transform` pipeline:
+
+```typescript
+import * as v from "valibot";
+
+// One schema per version — each reuses the previous one's entries where it can.
+const settingsV1 = v.object({
+  theme: v.picklist(["light", "dark"]),
+});
+const settingsV2 = v.object({
+  ...settingsV1.entries,
+  fontScale: v.number(),
+});
+const settingsV3 = v.object({
+  ...settingsV2.entries,
+  sidebar: v.boolean(),
+});
+// v4 deprecates `sidebar`: omit the key, keep the rest.
+const settingsV4 = v.omit(settingsV3, ["sidebar"]);
+const settingsV5 = v.object({
+  ...settingsV4.entries,
+  theme: v.picklist(["day", "night"]),
+});
+// update this when a new version is added to the chain
+const settingsLatest = settingsV5;
+
+type Settings = v.InferOutput<typeof settingsLatest>;
+
+// Each evolution validates the previous shape and transforms it to the next.
+const toV2 = v.pipe(
+  settingsV1,
+  v.transform((s) => ({ ...s, fontScale: 1 })),
+);
+const toV3 = v.pipe(
+  settingsV2,
+  v.transform((s) => ({ ...s, sidebar: true })),
+);
+const toV4 = v.pipe(
+  settingsV3,
+  v.transform(({ sidebar, ...rest }) => rest),
+);
+const toV5 = v.pipe(
+  settingsV4,
+  v.transform((s) => ({
+    ...s,
+    theme: s.theme === "light" ? ("day" as const) : ("night" as const),
+  })),
+);
+
+const settings = datavolve()
+  .add(1, (raw) => v.parse(settingsV1, raw)) // legacy -> v1
+  .add(2, (prev) => v.parse(toV2, prev))
+  .add(3, (prev) => v.parse(toV3, prev))
+  .add(4, (prev) => v.parse(toV4, prev))
+  .add(5, (prev) => v.parse(toV5, prev));
+
+const result = settings.run(storedValue, storedVersion);
+if (result.success) {
+  const value: Settings = result.value; // inferred *and* runtime-checked
+  useSettings(value);
+}
+```
+
+Every evolution parses its input, so a value is validated at whatever version it enters the chain — corrupt or unexpected data surfaces as a `failed` result (`v.parse` throws, and `run` turns any thrown error into `failed`). You handle it through the same branch you already handle, with no extra `try`/`catch`.
+
+The only value not re-checked is one already at `latestVersion`: it skips the chain and is returned unchanged (the no-op fast path). That is the shape your app just wrote, so it is trusted.
+
+## Persisting to localStorage
+
+`datavolve` never touches storage — you own the `{ version, value }` envelope and decide where it lives. A typical `localStorage` read evolves the stored value up to the latest shape and re-stores it, so the next read is a no-op; a fresh write stamps the current `latestVersion`:
+
+```typescript
+const KEY = "settings";
+
+// Read: evolve stored data up to the latest shape, then re-store it.
+function load(): Settings {
+  const raw = localStorage.getItem(KEY);
+  const stored = raw ? JSON.parse(raw) : { version: 0, value: null }; // no data -> version 0
+
+  const result = settings.run(stored.value, stored.version);
+  if (!result.success) return defaults; // reset on ahead / malformed / failed
+
+  // persist the upgraded shape so the next read skips the chain
+  localStorage.setItem(
+    KEY,
+    JSON.stringify({ version: result.version, value: result.value }),
+  );
+  return result.value;
+}
+
+// Write: a fresh in-app change is already the latest shape, so stamp latestVersion.
+function save(value: Settings): void {
+  localStorage.setItem(
+    KEY,
+    JSON.stringify({ version: settings.latestVersion, value }),
+  );
+}
+```
+
+## Design Notes
+
+- **Forward-only.** This evolves persisted client state; you never roll a user's storage back, so there are no down evolutions.
+- **Synchronous.** Persisted-state evolutions are pure shape transforms. Keeping `run` sync means it fits synchronous read paths. Need async evolutions? [Open an issue](https://github.com/psd-coder/datavolve/issues) — an async variant is ready to build if there is demand.
+- **Result over throw.** A newer-than-expected stored value is expected control flow, not an exception. Returning a discriminated result makes handling every reason compiler-enforced.
+
+## License
+
+[MIT](./LICENSE.md)

package/dist/index.d.mts

@@ -0,0 +1,29 @@
+//#region src/index.d.ts
+type EvolveError = {
+  code: "ahead";
+  fromVersion: number;
+  latestVersion: number;
+} | {
+  code: "malformed";
+  fromVersion: number;
+} | {
+  code: "failed";
+  failedVersion: number;
+  cause: unknown;
+};
+type EvolveResult<T> = {
+  success: true;
+  value: T;
+  version: number;
+} | {
+  success: false;
+  error: EvolveError;
+};
+type Datavolve<Out> = {
+  readonly latestVersion: number;
+  add<NewOut>(version: number, evolve: (prev: Out) => NewOut): Datavolve<NewOut>;
+  run(data: unknown, fromVersion: number): EvolveResult<Out>;
+};
+declare function datavolve(): Datavolve<unknown>;
+//#endregion
+export { Datavolve, EvolveError, EvolveResult, datavolve };

package/dist/index.mjs

@@ -0,0 +1,52 @@
+//#region src/index.ts
+function create(evolutions) {
+	const latestVersion = evolutions.length;
+	return {
+		latestVersion,
+		add(version, evolve) {
+			const expected = latestVersion + 1;
+			if (!Number.isInteger(version) || version !== expected) throw new Error(`datavolve: expected ${expected}, got ${version}`);
+			return create([...evolutions, evolve]);
+		},
+		run(data, fromVersion) {
+			if (!Number.isInteger(fromVersion) || fromVersion < 0) return {
+				success: false,
+				error: {
+					code: "malformed",
+					fromVersion
+				}
+			};
+			if (fromVersion > latestVersion) return {
+				success: false,
+				error: {
+					code: "ahead",
+					fromVersion,
+					latestVersion
+				}
+			};
+			let value = data;
+			for (let index = fromVersion; index < latestVersion; index++) try {
+				value = evolutions[index](value);
+			} catch (cause) {
+				return {
+					success: false,
+					error: {
+						code: "failed",
+						failedVersion: index + 1,
+						cause
+					}
+				};
+			}
+			return {
+				success: true,
+				value,
+				version: latestVersion
+			};
+		}
+	};
+}
+function datavolve() {
+	return create([]);
+}
+//#endregion
+export { datavolve };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "datavolve",
+  "version": "0.9.0",
+  "description": "",
+  "license": "MIT",
+  "author": "Pavel Grinchenko <psdcoder@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "psd-coder/datavolve"
+  },
+  "files": [
+    "dist/*",
+    "package.json",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@size-limit/esbuild": "^12.1.0",
+    "@size-limit/file": "^12.0.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "oxfmt": "^0.58.0",
+    "oxlint": "^1.56.0",
+    "publint": "^0.3.18",
+    "size-limit": "^12.0.1",
+    "tsdown": "0.22.5",
+    "typescript": "^7.0.2",
+    "valibot": "^1.4.2",
+    "vitest": "4.1.10"
+  },
+  "size-limit": [
+    {
+      "path": ".size-check/index.mjs",
+      "limit": "258B"
+    }
+  ],
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "tsdown",
+    "build:size": "tsdown --minify --out-dir .size-check --no-dts",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "pnpm run /^typecheck:/",
+    "typecheck:src": "tsc -p tsconfig.json --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json --noEmit",
+    "lint": "pnpm run /^lint:/",
+    "lint:oxlint": "oxlint .",
+    "lint:types": "pnpm run typecheck",
+    "lint:size": "pnpm run build:size && size-limit",
+    "format": "pnpm run /^format:/",
+    "format:oxlint": "oxlint --fix --fix-suggestions .",
+    "format:oxfmt": "oxfmt src/",
+    "format:check": "oxfmt --check src/"
+  }
+}