@vireocodedev/history 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vireocodedev
+
+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,173 @@
+# @vireocodedev/history
+
+Framework-free entity-history primitives: typed definitions, validated history
+records, and a deterministic diff engine. The package owns no React components,
+renderers, HTTP client, application entity enum, or persistence policy.
+
+React presentation belongs to `@vireocodedev/ui`, whose
+`VireoHistoryEntry` component consumes the nodes produced here.
+
+## Install
+
+```bash
+npm install @vireocodedev/history zod
+```
+
+The package is published publicly on npm; installation requires no registry
+authentication. TypeScript declarations are verified from the packed artifact
+with TypeScript 6, `moduleResolution: "Bundler"`, and `skipLibCheck: false`.
+Relative source maps with embedded source content are published intentionally
+for debugging.
+
+`zod >=4.4 <5` is the package's only peer dependency.
+
+## Define and compare an entity
+
+```ts
+import { createHistoryDefinition, createHistoryNodes } from "@vireocodedev/history";
+import { z } from "zod";
+
+const CountrySchema = z.object({
+  code: z.string(),
+  name: z.string(),
+  tax: z.number(),
+});
+
+const countryHistory = createHistoryDefinition(
+  CountrySchema,
+  {
+    label: "Country",
+    key: country => country.code,
+    format: country => country.name,
+  },
+  {
+    code: false,
+    name: { kind: "field", label: "Name" },
+    tax: {
+      kind: "field",
+      label: "Tax",
+      format: tax => `${tax}%`,
+    },
+  },
+);
+
+const nodes = createHistoryNodes(
+  countryHistory,
+  { code: "HR", name: "Croatia", tax: 25 },
+  { code: "HR", name: "Croatia", tax: 24 },
+);
+```
+
+Definitions are inferred from their Zod schema. Every schema property must be
+configured or explicitly ignored with `false`, so a newly added model field
+cannot silently disappear from history.
+
+`format` is optional and must return a string. Each emitted value preserves both
+representations:
+
+```ts
+{
+  raw: 25,
+  formatted: "25%"
+}
+```
+
+That boundary keeps the engine useful in Node and Workers while allowing UI to
+render the formatted text or make a UI-specific decision from `raw`.
+
+## Records
+
+```ts
+import { createHistoryRecordSchema } from "@vireocodedev/history";
+import { z } from "zod";
+
+const HistoryRecordSchema = createHistoryRecordSchema({
+  entityKind: z.enum(["INVOICE", "BUYER"]),
+  snapshot: z.object({ total: z.number() }),
+});
+
+const record = HistoryRecordSchema.parse(await response.json());
+```
+
+A record uses neutral actor metadata:
+
+```ts
+{
+  id: "history-1",
+  timestamp: "2026-08-22T12:00:00Z",
+  actor: { id: "user-1", label: "Alice" },
+  entity: "INVOICE",
+  entityId: "invoice-42",
+  snapshotPrevious: null,
+  snapshotCurrent: { total: 100 }
+}
+```
+
+Use `actor: null` for system-generated changes. Entity kinds remain
+application-owned; passing a Zod enum narrows and validates them.
+
+## Diff semantics
+
+- `null` and `undefined` mean a value is absent.
+- An empty string is a present value and participates in ordinary updates.
+- Added or removed empty arrays and objects remain visible as container changes.
+- `set` arrays ignore order; `ordered` arrays additionally emit deliberate moved
+  rows. Insertions and removals do not mark every shifted neighbor as moved.
+- Array item identities must be unique within each snapshot. Duplicate keys
+  throw instead of silently overwriting an item.
+- Identities are strings or finite numbers. Node paths preserve that segment
+  type; encode paths canonically rather than joining them with a delimiter.
+- Unchanged rows are omitted unless `showUnchanged: true` is requested.
+- Added, updated, removed, and unchanged nodes are emitted in deterministic
+  change order.
+- Both snapshots are parsed once by the root definition's Zod schema before
+  comparison. Parent schemas must compose the schemas owned by nested
+  definitions; nested schemas are not parsed a second time.
+
+## Value comparison and formatting
+
+Default comparison supports primitives, Dates, arrays, and plain objects. It
+uses a typed canonical representation with deterministic object-key ordering.
+Cycles, functions, symbols, Maps, Sets, and other unsupported object types throw
+instead of being silently treated as equal.
+
+Use a field's `resolveChange` when domain equality differs from structural
+equality. Return `null` to treat the field as unchanged, or `"added"`,
+`"updated"`, or `"removed"` to select an explicit change.
+
+Definitions are runtime-validated when created. Labels must be nonempty, modes
+must be supported, callbacks must be functions, and nested configurations must
+be structurally valid.
+
+## Nested definitions and collections
+
+An object field references a reusable definition:
+
+```ts
+const CustomerSchema = z.object({ address: AddressSchema });
+
+const customerHistory = createHistoryDefinition(
+  CustomerSchema,
+  { label: "Customer", key: () => "customer" },
+  { address: { kind: "object", definition: addressHistory } },
+);
+```
+
+Array object items use the nested definition's `key`. Primitive array items
+identify themselves. Use `mode: "ordered"` only when order is part of the
+audited meaning.
+
+## Public concepts
+
+- `createHistoryDefinition` creates a schema-derived entity definition.
+- `createHistoryNodes` validates and compares two optional snapshots.
+- `HistoryDefinition` and field config types describe definitions.
+- `HistoryNode`, `HistoryGroupNode`, `HistoryFieldRow`, and `HistoryValue`
+  describe emitted results.
+- `HistoryPath` and `HistoryPathSegment` describe lossless node locations.
+- `createHistoryRecordSchema`, `HistoryRecordSchema`, and the record/snapshot
+  types describe transport-neutral audit records. The factory accepts optional
+  `entityKind`, `snapshot`, and `timestamp` Zod schemas.
+
+The public surface is frozen by `api-surface.json`. Export changes require a
+Changeset and deliberate semver decision.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vireocodedev/history",
+  "version": "0.2.0",
+  "description": "Framework-free entity history definitions, diff nodes, and transport-neutral record schemas for the vireocodedev starter product.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vireocodedev/starter.git",
+    "directory": "packages/history"
+  },
+  "keywords": [
+    "history",
+    "audit-log",
+    "diff",
+    "zod",
+    "starter"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch --mode watch",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "zod": ">=4.4 <5"
+  },
+  "devDependencies": {
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vite": "^8.2.2",
+    "vite-plugin-dts": "^5.0.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org"
+  }
+}