@jiplabs/versioning

Generic, port-based append-only event journal with durable monotonic sequencing.

Status: V0.1.x frozen contract · License: MIT

This library is product-agnostic. JipComply is one consumer that wires PostgreSQL via adapters; the package itself has no @jipcomply/* runtime dependencies.

Non-goals

• Full event sourcing / replay
• State reconstruction at time T
• Payload schema upcasting
• Distributed transaction atomicity
• Built-in database adapters

Install

npm install @jiplabs/versioning

Minimal usage

import {
  appendEvent,
  listEvents,
  type VersioningPorts,
} from "@jiplabs/versioning";

declare const ports: VersioningPorts;

await appendEvent(ports, {
  entityId: "entity-1",
  type: "EXAMPLE_CREATED",
  actor: "system",
  payload: { id: "example-1" },
});

const events = await listEvents(ports, "entity-1");

journalSeq from the repository is the ordering authority; timestamp is descriptive metadata only.

Public API (V0)

| Export | Role | |---|---| | appendEvent | Append via ports | | listEvents | Global journal or by entityId | | assertEventIsAppendOnly | Surface marker (no update/delete helpers) | | VersionedEvent, AppendEventInput | Domain types | | VersioningPorts / VersioningRepository | Injected adapters |

Product-specific event type taxonomies stay outside this package.

Architecture boundary

| Direction | Rule | |---|---| | Product / adapters → @jiplabs/versioning | Allowed | | @jiplabs/versioning → product packages | Forbidden |

V0 stability

Semantic behavior of the V0.1.x public API is frozen. Publication packaging may advance to npm 0.1.1 without changing domain semantics.

License

MIT © 2026 JipLabs