@haruhimemoe/next-kit 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-05
+
+### Added
+- `vcs` entry point: `createRevisionStore`, document history in MongoDB on top of `@haruhimemoe/vcs` (a new optional peer). Saves name their base revision and merge onto anything newer; conflicts write nothing and come back for the client to resolve. Also revert, diffs, author renames, history removal and autosave pruning.
+
 ## [0.6.2] - 2026-10-04
 
 ### Changed

package/README.md

@@ -13,6 +13,7 @@ The Next.js server plumbing the haruhime.moe tools share. [packs.haruhime.moe](h
 - **`/testing`:** Vitest helpers: one in-memory MongoDB per run, an msw server that refuses unhandled requests, and a fake env.
 - **`/api-keys`:** the shared key format (an app prefix like `hpk_` plus 32 random bytes), a key store over `api_keys`, and the `/api/v1` guard with the standard limits.
 - **`/docs`:** a content registry for an app's docs, guides and legal pages: sections, entries, app-made extra entries (like bb's tag pages), the path helpers a dynamic route needs, and `mdxToMarkdown` to turn bb-flavored MDX into plain Markdown. No runtime imports. **`/docs/files`:** reads the markdown files a registry's entries point at and reports drift between the registry and disk (node:fs).
+- **`/vcs`:** document history in MongoDB on top of `@haruhimemoe/vcs`: one line of revisions per document, saves merged onto whatever landed since their base, revert, diffs, and autosave pruning.
 
 Every name, path, limit and message comes from the caller. There is no root entry point; import a subpath.
 
@@ -37,6 +38,7 @@ bun add @haruhimemoe/next-kit zod
 | `api-keys` | `mongodb` ^7.6.0 |
 | `docs` | nothing else |
 | `docs/files` | nothing else (`node:fs` is built in) |
+| `vcs` | `mongodb` ^7.6.0, `@haruhimemoe/vcs` ^0.1.0 |
 
 ## Use
 
@@ -391,6 +393,41 @@ No runtime imports.
 | `readContentMarkdown(content, section, slug, { root?, siteUrl, transforms? })` | Reads a registered entry's markdown file and converts it with `mdxToMarkdown` (using the entry's `title`). `root` defaults to `process.cwd()`. Returns null for an unregistered slug; rejects (ENOENT) when the slug is registered but its file is missing. |
 | `contentFileDrift(content, { root? })` | `{ missingFiles, unregistered }`: `missingFiles` lists registered entries with no file on disk (like `"guides/x.mdx"`); `unregistered` lists `.mdx` files on disk with no registry entry. `root` defaults to `process.cwd()`. |
 
+### vcs
+
+| Export | What it does |
+| --- | --- |
+| `createRevisionStore({ db, collection, codec?, check?, maxRevisions?, maxBytes?, now? })` | A document history over one collection. `codec` is a `@haruhimemoe/vcs` codec (keyed lists, text and ignored paths). `check(value, kind)` runs before every write; throw to refuse (a content filter, say). Throws `TypeError` for a missing collection or a non-positive limit. |
+| `revisionIndexSpecs(collection)` | Unique `(docId, seq)`, `authorId`, and `(docId, kind, createdAt)`, for the app's own index list. |
+| `DEFAULT_MAX_REVISIONS` | 1000 per document; past it the oldest autosaves go. Saves are never deleted. |
+| `DEFAULT_MAX_BYTES` | 1,000,000 bytes of canonical JSON per value; past it a write throws `RangeError`. |
+| `COMMIT_ATTEMPTS` | 3: how often a commit reruns when another writer takes its seq. |
+| `DEFAULT_LIST_LIMIT`, `MAX_LIST_LIMIT` | History page size: 50 by default, 200 at most. |
+
+The store's methods:
+
+| Method | What it does |
+| --- | --- |
+| `create(docId, value, author, message?)` | The root revision (seq 0). Throws if the document already has history. |
+| `head(docId)`, `get(docId, id)` | One revision with its value, or null. |
+| `list(docId, { before?, limit? })` | Revisions newest first, without values. `before` pages by seq. |
+| `commit({ docId, base, value, author, kind?, message? })` | `base` is the `{ id, seq }` the client started from; `kind` is `"save"` (default) or `"autosave"`. Returns `committed` (base was the head), `merged` (the head moved on and the value merged onto it cleanly, written as kind `merge`), `unchanged` (the result equals the head, ignoring ignored paths; nothing written), `conflict` (nothing written; `head` and the `ValueMerge` with its conflicts, so the client can resolve and commit again on `head`) or `missing` (no such document, or no revision at or before `base` survives). A pruned `base` merges from the nearest earlier revision. |
+| `revert(docId, id, author)` | Commits that revision's value again, as kind `revert`. |
+| `diff(docId, fromId, toId)` | The `Change[]` between two revisions, or null. |
+| `renameAuthor(authorId, name)` | Rewrites the author's name on every revision (renames, deleted accounts). |
+| `removeDoc(docId)` | Deletes the whole history. |
+| `pruneAutosaves(docId, olderThan)` | Deletes autosaves older than the date that a later save, merge or revert follows. |
+| `indexSpecs()`, `ensureIndexes()` | The indexes, and building them (logs, never throws). |
+
+Notes:
+
+- Run `ensureIndexes()` (or build `revisionIndexSpecs` with your own list) before the first write. The unique `(docId, seq)` index is what stops two writers from both taking the next seq.
+- `check` can run more than once for one commit (retries), so keep it free of side effects.
+- A stale autosave that merges is kept as kind `merge`, like a save; only plain autosaves are pruned.
+- A `base` whose id is another document's revision, or whose seq doesn't match, is `missing`. Only an id that no longer exists (pruned) falls back to the nearest earlier revision.
+
+Who may read a history, and the routes around it, stay the app's.
+
 ## Migration
 
 Both apps can drop their copies for the subpaths above. Where the copies differed, this package keeps pools.haruhime.moe's behavior. What changes for packs.haruhime.moe:

package/dist/vcs/commit.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @file src/vcs/commit.ts
+ * @desc create, commit and revert. A commit whose base is the head writes the value as is. When
+ *       the head moved on, the value is merged onto it (base: the client's revision, or the
+ *       nearest earlier one if that was pruned); a clean merge is written as kind "merge", a
+ *       conflict writes nothing. A value that hashes like the head writes nothing either. When
+ *       another writer takes the next seq first, the whole thing reruns, up to COMMIT_ATTEMPTS.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { type Revision } from "@haruhimemoe/vcs";
+import { type StoreContext } from "./read.js";
+import type { CommitInput, CommitResult, RevisionAuthor } from "./types.js";
+/**
+ * @function createHistory
+ * @param ctx {StoreContext<T>} the store
+ * @param docId {string} the document
+ * @param value {T} its first value
+ * @param author {RevisionAuthor} who made it
+ * @param message {string | null | undefined} an optional note
+ * @returns {Promise<Revision<T>>} the root revision (seq 0)
+ * @throws {Error} when the document already has history
+ */
+export declare const createHistory: <T>(ctx: StoreContext<T>, docId: string, value: T, author: RevisionAuthor, message?: string | null) => Promise<Revision<T>>;
+/**
+ * @function commitRevision
+ * @param ctx {StoreContext<T>} the store
+ * @param input {CommitInput<T>} the document, the client's base revision, the value and author
+ * @returns {Promise<CommitResult<T>>} committed, merged, unchanged, conflict or missing
+ * @throws {Error} when other writers win COMMIT_ATTEMPTS times in a row; RangeError past
+ *         maxBytes; whatever `check` throws
+ */
+export declare const commitRevision: <T>(ctx: StoreContext<T>, { docId, base, value, author, kind, message }: CommitInput<T>) => Promise<CommitResult<T>>;
+/**
+ * @function revertRevision
+ * @param ctx {StoreContext<T>} the store
+ * @param docId {string} the document
+ * @param id {string} the revision whose value to restore
+ * @param author {RevisionAuthor} who is reverting
+ * @returns {Promise<CommitResult<T>>} committed (kind "revert", base = id), unchanged when the
+ *          head already holds that value, or missing
+ * @throws {Error} as commitRevision
+ */
+export declare const revertRevision: <T>(ctx: StoreContext<T>, docId: string, id: string, author: RevisionAuthor) => Promise<CommitResult<T>>;

package/dist/vcs/commit.js

@@ -0,0 +1,113 @@
+/**
+ * @file src/vcs/commit.ts
+ * @desc create, commit and revert. A commit whose base is the head writes the value as is. When
+ *       the head moved on, the value is merged onto it (base: the client's revision, or the
+ *       nearest earlier one if that was pruned); a clean merge is written as kind "merge", a
+ *       conflict writes nothing. A value that hashes like the head writes nothing either. When
+ *       another writer takes the next seq first, the whole thing reruns, up to COMMIT_ATTEMPTS.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { mergeValue } from "@haruhimemoe/vcs";
+import { isDuplicateKeyError } from "../mongo/duplicate.js";
+import { COMMIT_ATTEMPTS } from "./options.js";
+import { readAtOrBefore, readById, readHead, readOne } from "./read.js";
+import { insertRevision, valueHash } from "./write.js";
+/**
+ * @function createHistory
+ * @param ctx {StoreContext<T>} the store
+ * @param docId {string} the document
+ * @param value {T} its first value
+ * @param author {RevisionAuthor} who made it
+ * @param message {string | null | undefined} an optional note
+ * @returns {Promise<Revision<T>>} the root revision (seq 0)
+ * @throws {Error} when the document already has history
+ */
+export const createHistory = async (ctx, docId, value, author, message) => {
+    try {
+        return await insertRevision(ctx, { docId, seq: 0, kind: "root", value, author, message });
+    }
+    catch (error) {
+        if (isDuplicateKeyError(error))
+            throw new Error(`createHistory: ${docId} already has history`);
+        throw error;
+    }
+};
+/** Writes at head.seq + 1 unless the value equals head. null: someone else took the seq. */
+const writeNext = async (ctx, head, input, merged) => {
+    const hash = await valueHash(ctx, input.value);
+    if (hash === head.valueHash)
+        return { status: "unchanged", revision: head };
+    try {
+        const revision = await insertRevision(ctx, { ...input, seq: head.seq + 1 }, hash);
+        return { status: merged ? "merged" : "committed", revision };
+    }
+    catch (error) {
+        if (isDuplicateKeyError(error))
+            return null;
+        throw error;
+    }
+};
+/** The client's base, or the nearest earlier revision if it was pruned. null when the id
+ *  belongs to another revision or document, or nothing earlier survives. */
+const mergeBase = async (ctx, docId, base) => {
+    const found = await readById(ctx, base.id);
+    if (found)
+        return found.docId === docId && found.seq === base.seq ? found : null;
+    return readAtOrBefore(ctx, docId, base.seq - 1);
+};
+const tooBusy = (docId) => new Error(`commit: ${docId} kept changing; gave up after ${COMMIT_ATTEMPTS} attempts`);
+/**
+ * @function commitRevision
+ * @param ctx {StoreContext<T>} the store
+ * @param input {CommitInput<T>} the document, the client's base revision, the value and author
+ * @returns {Promise<CommitResult<T>>} committed, merged, unchanged, conflict or missing
+ * @throws {Error} when other writers win COMMIT_ATTEMPTS times in a row; RangeError past
+ *         maxBytes; whatever `check` throws
+ */
+export const commitRevision = async (ctx, { docId, base, value, author, kind = "save", message = null }) => {
+    for (let attempt = 0; attempt < COMMIT_ATTEMPTS; attempt++) {
+        const head = await readHead(ctx, docId);
+        if (!head || base.seq > head.seq)
+            return { status: "missing" };
+        let result;
+        if (base.id === head.id) {
+            result = await writeNext(ctx, head, { docId, kind, value, author, message }, false);
+        }
+        else {
+            const from = await mergeBase(ctx, docId, base);
+            if (!from)
+                return { status: "missing" };
+            const merged = mergeValue(from.value, value, head.value, ctx.options.codec);
+            if (!merged.clean)
+                return { status: "conflict", head, merged };
+            result = await writeNext(ctx, head, { docId, kind: "merge", value: merged.value, author, message, base: from.id }, true);
+        }
+        if (result)
+            return result;
+    }
+    throw tooBusy(docId);
+};
+/**
+ * @function revertRevision
+ * @param ctx {StoreContext<T>} the store
+ * @param docId {string} the document
+ * @param id {string} the revision whose value to restore
+ * @param author {RevisionAuthor} who is reverting
+ * @returns {Promise<CommitResult<T>>} committed (kind "revert", base = id), unchanged when the
+ *          head already holds that value, or missing
+ * @throws {Error} as commitRevision
+ */
+export const revertRevision = async (ctx, docId, id, author) => {
+    for (let attempt = 0; attempt < COMMIT_ATTEMPTS; attempt++) {
+        const [head, target] = await Promise.all([readHead(ctx, docId), readOne(ctx, docId, id)]);
+        if (!head || !target)
+            return { status: "missing" };
+        const input = { docId, kind: "revert", value: target.value, author, base: id };
+        const result = await writeNext(ctx, head, input, false);
+        if (result)
+            return result;
+    }
+    throw tooBusy(docId);
+};

package/dist/vcs/docs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file src/vcs/docs.ts
+ * @desc The stored form of a revision (createdAt as a Date, _id as the id), the conversions to
+ *       and from it, and the indexes the store needs. Internal.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import type { Revision, RevisionMeta } from "@haruhimemoe/vcs";
+import type { IndexSpec } from "../mongo/indexes.js";
+/** A revision as MongoDB holds it. */
+export type RevisionDoc<T> = Omit<Revision<T>, "id" | "createdAt"> & {
+    _id: string;
+    createdAt: Date;
+};
+/** Every field but the value, for history lists. */
+export declare const META_PROJECTION: {
+    readonly value: 0;
+};
+/**
+ * @function toMeta
+ * @param doc {Omit<RevisionDoc<unknown>, "value">} a stored revision without its value
+ * @returns {RevisionMeta} the public metadata, field by field (stray stored fields stay out)
+ */
+export declare const toMeta: (doc: Omit<RevisionDoc<unknown>, "value">) => RevisionMeta;
+/**
+ * @function toRevision
+ * @param doc {RevisionDoc<T>} a stored revision
+ * @returns {Revision<T>} the public shape (id, ISO createdAt) with its value
+ */
+export declare const toRevision: <T>(doc: RevisionDoc<T>) => Revision<T>;
+/**
+ * @function revisionIndexSpecs
+ * @param collection {string} the revisions collection
+ * @returns {IndexSpec[]} unique (docId, seq) (history order, and what catches two writers),
+ *          authorId (renames), and (docId, kind, createdAt) (autosave pruning)
+ */
+export declare const revisionIndexSpecs: (collection: string) => IndexSpec[];

package/dist/vcs/docs.js

@@ -0,0 +1,49 @@
+/**
+ * @file src/vcs/docs.ts
+ * @desc The stored form of a revision (createdAt as a Date, _id as the id), the conversions to
+ *       and from it, and the indexes the store needs. Internal.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+/** Every field but the value, for history lists. */
+export const META_PROJECTION = { value: 0 };
+/**
+ * @function toMeta
+ * @param doc {Omit<RevisionDoc<unknown>, "value">} a stored revision without its value
+ * @returns {RevisionMeta} the public metadata, field by field (stray stored fields stay out)
+ */
+export const toMeta = (doc) => ({
+    id: doc._id,
+    docId: doc.docId,
+    seq: doc.seq,
+    kind: doc.kind,
+    valueHash: doc.valueHash,
+    authorId: doc.authorId,
+    authorName: doc.authorName,
+    message: doc.message,
+    createdAt: doc.createdAt.toISOString(),
+    ...(doc.base === undefined ? {} : { base: doc.base }),
+    ...(doc.forkOf === undefined ? {} : { forkOf: doc.forkOf }),
+    ...(doc.upstream === undefined ? {} : { upstream: doc.upstream }),
+});
+/**
+ * @function toRevision
+ * @param doc {RevisionDoc<T>} a stored revision
+ * @returns {Revision<T>} the public shape (id, ISO createdAt) with its value
+ */
+export const toRevision = (doc) => ({
+    ...toMeta(doc),
+    value: doc.value,
+});
+/**
+ * @function revisionIndexSpecs
+ * @param collection {string} the revisions collection
+ * @returns {IndexSpec[]} unique (docId, seq) (history order, and what catches two writers),
+ *          authorId (renames), and (docId, kind, createdAt) (autosave pruning)
+ */
+export const revisionIndexSpecs = (collection) => [
+    { collection, key: { docId: 1, seq: -1 }, unique: true },
+    { collection, key: { authorId: 1 } },
+    { collection, key: { docId: 1, kind: 1, createdAt: 1 } },
+];

package/dist/vcs/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file src/vcs/index.ts
+ * @desc @haruhimemoe/next-kit/vcs: createRevisionStore, a document history in MongoDB on top of
+ *       @haruhimemoe/vcs. One line of revisions per document; a save names the revision it
+ *       started from and is merged onto anything that landed since. Routes, auth and who may see
+ *       a history stay the app's. Server only: loads mongodb and @haruhimemoe/vcs.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import type { RevisionStore, RevisionStoreOptions } from "./types.js";
+export { revisionIndexSpecs } from "./docs.js";
+export { COMMIT_ATTEMPTS, DEFAULT_MAX_BYTES, DEFAULT_MAX_REVISIONS, } from "./options.js";
+export { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from "./read.js";
+export type { CommitInput, CommitResult, RevisionAuthor, RevisionStore, RevisionStoreOptions, } from "./types.js";
+/**
+ * @function createRevisionStore
+ * @param options {RevisionStoreOptions<T>} db, collection, and optional codec, check and limits
+ * @returns {RevisionStore<T>} the store
+ * @throws {TypeError} for a missing collection or a non-positive limit
+ */
+export declare const createRevisionStore: <T>(options: RevisionStoreOptions<T>) => RevisionStore<T>;

package/dist/vcs/index.js

@@ -0,0 +1,45 @@
+/**
+ * @file src/vcs/index.ts
+ * @desc @haruhimemoe/next-kit/vcs: createRevisionStore, a document history in MongoDB on top of
+ *       @haruhimemoe/vcs. One line of revisions per document; a save names the revision it
+ *       started from and is merged onto anything that landed since. Routes, auth and who may see
+ *       a history stay the app's. Server only: loads mongodb and @haruhimemoe/vcs.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { ensureIndexes } from "../mongo/indexes.js";
+import { commitRevision, createHistory, revertRevision } from "./commit.js";
+import { revisionIndexSpecs } from "./docs.js";
+import { diffRevisions, pruneAutosaves, removeHistory, renameAuthor } from "./maintenance.js";
+import { resolveOptions } from "./options.js";
+import { readHead, readList, readOne, storeContext } from "./read.js";
+export { revisionIndexSpecs } from "./docs.js";
+export { COMMIT_ATTEMPTS, DEFAULT_MAX_BYTES, DEFAULT_MAX_REVISIONS, } from "./options.js";
+export { DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from "./read.js";
+/**
+ * @function createRevisionStore
+ * @param options {RevisionStoreOptions<T>} db, collection, and optional codec, check and limits
+ * @returns {RevisionStore<T>} the store
+ * @throws {TypeError} for a missing collection or a non-positive limit
+ */
+export const createRevisionStore = (options) => {
+    const resolved = resolveOptions(options);
+    const ctx = storeContext(resolved);
+    return {
+        indexSpecs: () => revisionIndexSpecs(resolved.collection),
+        ensureIndexes: async () => {
+            await ensureIndexes(await resolved.db(), revisionIndexSpecs(resolved.collection));
+        },
+        create: (docId, value, author, message) => createHistory(ctx, docId, value, author, message),
+        head: (docId) => readHead(ctx, docId),
+        get: (docId, id) => readOne(ctx, docId, id),
+        list: (docId, listOptions) => readList(ctx, docId, listOptions),
+        commit: (input) => commitRevision(ctx, input),
+        revert: (docId, id, author) => revertRevision(ctx, docId, id, author),
+        diff: (docId, fromId, toId) => diffRevisions(ctx, docId, fromId, toId),
+        renameAuthor: (authorId, name) => renameAuthor(ctx, authorId, name),
+        removeDoc: (docId) => removeHistory(ctx, docId),
+        pruneAutosaves: (docId, olderThan) => pruneAutosaves(ctx, docId, olderThan),
+    };
+};

package/dist/vcs/maintenance.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file src/vcs/maintenance.ts
+ * @desc diff between two revisions, author renames, deleting a document's history and pruning
+ *       old autosaves. Internal.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { type Change } from "@haruhimemoe/vcs";
+import { type StoreContext } from "./read.js";
+/** The changes from one revision to another, or null if either is gone. */
+export declare const diffRevisions: <T>(ctx: StoreContext<T>, docId: string, fromId: string, toId: string) => Promise<Change[] | null>;
+/** Rewrites authorName on every revision by this author. */
+export declare const renameAuthor: <T>(ctx: StoreContext<T>, authorId: string, name: string) => Promise<number>;
+/** Deletes every revision of a document. */
+export declare const removeHistory: <T>(ctx: StoreContext<T>, docId: string) => Promise<number>;
+/** Deletes autosaves older than the date with a later non-autosave revision after them. */
+export declare const pruneAutosaves: <T>(ctx: StoreContext<T>, docId: string, olderThan: Date) => Promise<number>;

package/dist/vcs/maintenance.js

@@ -0,0 +1,34 @@
+/**
+ * @file src/vcs/maintenance.ts
+ * @desc diff between two revisions, author renames, deleting a document's history and pruning
+ *       old autosaves. Internal.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { diffValue } from "@haruhimemoe/vcs";
+import { readOne } from "./read.js";
+/** The changes from one revision to another, or null if either is gone. */
+export const diffRevisions = async (ctx, docId, fromId, toId) => {
+    const [from, to] = await Promise.all([readOne(ctx, docId, fromId), readOne(ctx, docId, toId)]);
+    return from && to ? diffValue(from.value, to.value, ctx.options.codec) : null;
+};
+/** Rewrites authorName on every revision by this author. */
+export const renameAuthor = async (ctx, authorId, name) => (await (await ctx.collection()).updateMany({ authorId }, { $set: { authorName: name } }))
+    .modifiedCount;
+/** Deletes every revision of a document. */
+export const removeHistory = async (ctx, docId) => (await (await ctx.collection()).deleteMany({ docId })).deletedCount;
+/** Deletes autosaves older than the date with a later non-autosave revision after them. */
+export const pruneAutosaves = async (ctx, docId, olderThan) => {
+    const collection = await ctx.collection();
+    const lastSave = await collection.findOne({ docId, kind: { $ne: "autosave" } }, { sort: { seq: -1 }, projection: { seq: 1 } });
+    if (!lastSave)
+        return 0;
+    const result = await collection.deleteMany({
+        docId,
+        kind: "autosave",
+        seq: { $lt: lastSave.seq },
+        createdAt: { $lt: olderThan },
+    });
+    return result.deletedCount;
+};

package/dist/vcs/options.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file src/vcs/options.ts
+ * @desc Checks createRevisionStore's options and fills in the defaults. Internal.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { type Codec } from "@haruhimemoe/vcs";
+import type { RevisionStoreOptions } from "./types.js";
+/** Revisions kept per document before the oldest autosaves go. */
+export declare const DEFAULT_MAX_REVISIONS = 1000;
+/** Largest value, in bytes of canonical JSON. */
+export declare const DEFAULT_MAX_BYTES = 1000000;
+/** How many times commit retries when another writer takes its seq. */
+export declare const COMMIT_ATTEMPTS = 3;
+/** Options with every default filled in. */
+export type ResolvedOptions<T> = Required<Omit<RevisionStoreOptions<T>, "check">> & {
+    check: NonNullable<RevisionStoreOptions<T>["check"]> | null;
+    codec: Codec;
+};
+/**
+ * @function resolveOptions
+ * @param options {RevisionStoreOptions<T>} the caller's options
+ * @returns {ResolvedOptions<T>} the same with defaults
+ * @throws {TypeError} for an empty collection name or a non-positive limit
+ */
+export declare const resolveOptions: <T>(options: RevisionStoreOptions<T>) => ResolvedOptions<T>;

package/dist/vcs/options.js

@@ -0,0 +1,38 @@
+/**
+ * @file src/vcs/options.ts
+ * @desc Checks createRevisionStore's options and fills in the defaults. Internal.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { defineCodec } from "@haruhimemoe/vcs";
+/** Revisions kept per document before the oldest autosaves go. */
+export const DEFAULT_MAX_REVISIONS = 1000;
+/** Largest value, in bytes of canonical JSON. */
+export const DEFAULT_MAX_BYTES = 1_000_000;
+/** How many times commit retries when another writer takes its seq. */
+export const COMMIT_ATTEMPTS = 3;
+const positiveInt = (name, value) => {
+    if (!Number.isInteger(value) || value < 1)
+        throw new TypeError(`createRevisionStore: ${name} must be a positive integer`);
+    return value;
+};
+/**
+ * @function resolveOptions
+ * @param options {RevisionStoreOptions<T>} the caller's options
+ * @returns {ResolvedOptions<T>} the same with defaults
+ * @throws {TypeError} for an empty collection name or a non-positive limit
+ */
+export const resolveOptions = (options) => {
+    if (!options.collection)
+        throw new TypeError("createRevisionStore: collection is required");
+    return {
+        db: options.db,
+        collection: options.collection,
+        codec: options.codec ?? defineCodec({}),
+        check: options.check ?? null,
+        maxRevisions: positiveInt("maxRevisions", options.maxRevisions ?? DEFAULT_MAX_REVISIONS),
+        maxBytes: positiveInt("maxBytes", options.maxBytes ?? DEFAULT_MAX_BYTES),
+        now: options.now ?? Date.now,
+    };
+};

package/dist/vcs/read.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file src/vcs/read.ts
+ * @desc The store's context (options plus the typed collection) and its reads: head, one
+ *       revision, the nearest revision at or before a seq, and history pages. Internal.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import type { Revision, RevisionMeta } from "@haruhimemoe/vcs";
+import type { Collection } from "mongodb";
+import { type RevisionDoc } from "./docs.js";
+import type { ResolvedOptions } from "./options.js";
+/** Largest history page. */
+export declare const MAX_LIST_LIMIT = 200;
+/** History page size when none is asked for. */
+export declare const DEFAULT_LIST_LIMIT = 50;
+/** What every store function shares. */
+export type StoreContext<T> = {
+    options: ResolvedOptions<T>;
+    collection: () => Promise<Collection<RevisionDoc<T>>>;
+};
+/**
+ * @function storeContext
+ * @param options {ResolvedOptions<T>} resolved options
+ * @returns {StoreContext<T>} the context
+ */
+export declare const storeContext: <T>(options: ResolvedOptions<T>) => StoreContext<T>;
+/** The latest revision of a document, or null. */
+export declare const readHead: <T>(ctx: StoreContext<T>, docId: string) => Promise<Revision<T> | null>;
+/** One revision of a document, or null. */
+export declare const readOne: <T>(ctx: StoreContext<T>, docId: string, id: string) => Promise<Revision<T> | null>;
+/** A revision by id alone, whatever its document, or null. */
+export declare const readById: <T>(ctx: StoreContext<T>, id: string) => Promise<Revision<T> | null>;
+/** The revision with the largest seq at or below `seq`, or null. */
+export declare const readAtOrBefore: <T>(ctx: StoreContext<T>, docId: string, seq: number) => Promise<Revision<T> | null>;
+/** A history page, newest first, without values. */
+export declare const readList: <T>(ctx: StoreContext<T>, docId: string, { before, limit }?: {
+    before?: number;
+    limit?: number;
+}) => Promise<RevisionMeta[]>;

package/dist/vcs/read.js

@@ -0,0 +1,53 @@
+/**
+ * @file src/vcs/read.ts
+ * @desc The store's context (options plus the typed collection) and its reads: head, one
+ *       revision, the nearest revision at or before a seq, and history pages. Internal.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { META_PROJECTION, toMeta, toRevision } from "./docs.js";
+/** Largest history page. */
+export const MAX_LIST_LIMIT = 200;
+/** History page size when none is asked for. */
+export const DEFAULT_LIST_LIMIT = 50;
+/**
+ * @function storeContext
+ * @param options {ResolvedOptions<T>} resolved options
+ * @returns {StoreContext<T>} the context
+ */
+export const storeContext = (options) => ({
+    options,
+    collection: async () => (await options.db()).collection(options.collection),
+});
+/** The latest revision of a document, or null. */
+export const readHead = async (ctx, docId) => {
+    const doc = await (await ctx.collection()).findOne({ docId }, { sort: { seq: -1 } });
+    return doc ? toRevision(doc) : null;
+};
+/** One revision of a document, or null. */
+export const readOne = async (ctx, docId, id) => {
+    const doc = await (await ctx.collection()).findOne({ _id: id, docId });
+    return doc ? toRevision(doc) : null;
+};
+/** A revision by id alone, whatever its document, or null. */
+export const readById = async (ctx, id) => {
+    const doc = await (await ctx.collection()).findOne({ _id: id });
+    return doc ? toRevision(doc) : null;
+};
+/** The revision with the largest seq at or below `seq`, or null. */
+export const readAtOrBefore = async (ctx, docId, seq) => {
+    const doc = await (await ctx.collection()).findOne({ docId, seq: { $lte: seq } }, { sort: { seq: -1 } });
+    return doc ? toRevision(doc) : null;
+};
+/** A history page, newest first, without values. */
+export const readList = async (ctx, docId, { before, limit = DEFAULT_LIST_LIMIT } = {}) => {
+    const size = Number.isFinite(limit)
+        ? Math.max(1, Math.min(MAX_LIST_LIMIT, Math.floor(limit)))
+        : DEFAULT_LIST_LIMIT;
+    const filter = before !== undefined && Number.isInteger(before) ? { docId, seq: { $lt: before } } : { docId };
+    const docs = await (await ctx.collection())
+        .find(filter, { projection: META_PROJECTION, sort: { seq: -1 }, limit: size })
+        .toArray();
+    return docs.map((doc) => toMeta(doc));
+};

package/dist/vcs/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @file src/vcs/types.ts
+ * @desc The revision store's public shapes: its options, who is writing, what commit and revert
+ *       return, and the store itself.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import type { Change, Codec, Revision, RevisionKind, RevisionMeta, RevisionRef, ValueMerge } from "@haruhimemoe/vcs";
+import type { Db } from "mongodb";
+import type { IndexSpec } from "../mongo/indexes.js";
+/** Who is writing a revision. */
+export type RevisionAuthor = {
+    id: string;
+    name: string;
+};
+/** createRevisionStore's options. */
+export type RevisionStoreOptions<T> = {
+    /** The connected database. */
+    db: () => Promise<Db>;
+    /** The app's revisions collection, like "pool_revisions". */
+    collection: string;
+    /** Keyed lists, text paths and ignored paths of T (default: none). */
+    codec?: Codec;
+    /** Runs before every write (create, commit, merge, revert). Throw to refuse the value. */
+    check?: (value: T, kind: RevisionKind) => void | Promise<void>;
+    /** Per document. Past it, the oldest autosaves go; saves are never deleted. Default 1000. */
+    maxRevisions?: number;
+    /** Largest value, in bytes of canonical JSON. Default 1,000,000. */
+    maxBytes?: number;
+    /** The clock (ms). Default Date.now. */
+    now?: () => number;
+};
+/** What commit and revert return. Only "committed" and "merged" wrote anything. */
+export type CommitResult<T> = {
+    status: "committed";
+    revision: Revision<T>;
+} | {
+    status: "merged";
+    revision: Revision<T>;
+} | {
+    status: "unchanged";
+    revision: Revision<T>;
+} | {
+    status: "conflict";
+    head: Revision<T>;
+    merged: ValueMerge<T>;
+} | {
+    status: "missing";
+};
+/** commit's input. */
+export type CommitInput<T> = {
+    docId: string;
+    /** The revision the client started from (its id and seq). */
+    base: RevisionRef;
+    value: T;
+    author: RevisionAuthor;
+    kind?: "save" | "autosave";
+    message?: string | null;
+};
+/** A revision store over one collection. */
+export type RevisionStore<T> = {
+    /** The indexes the store needs, for the app's own index list. */
+    indexSpecs: () => IndexSpec[];
+    /** Builds those indexes (logs, never throws). */
+    ensureIndexes: () => Promise<void>;
+    /** Starts a document's history (seq 0). Throws if it already has one. */
+    create: (docId: string, value: T, author: RevisionAuthor, message?: string | null) => Promise<Revision<T>>;
+    head: (docId: string) => Promise<Revision<T> | null>;
+    get: (docId: string, id: string) => Promise<Revision<T> | null>;
+    /** Newest first, without values. `before`: only revisions with a lower seq. */
+    list: (docId: string, options?: {
+        before?: number;
+        limit?: number;
+    }) => Promise<RevisionMeta[]>;
+    commit: (input: CommitInput<T>) => Promise<CommitResult<T>>;
+    /** Commits an earlier revision's value again (kind "revert", base = that revision). */
+    revert: (docId: string, id: string, author: RevisionAuthor) => Promise<CommitResult<T>>;
+    /** The changes from one revision to another, or null if either is gone. */
+    diff: (docId: string, fromId: string, toId: string) => Promise<Change[] | null>;
+    /** Rewrites an author's name on every revision (renames, deleted accounts). */
+    renameAuthor: (authorId: string, name: string) => Promise<number>;
+    /** Deletes a document's whole history. */
+    removeDoc: (docId: string) => Promise<number>;
+    /** Deletes autosaves older than the date that a later non-autosave revision follows. */
+    pruneAutosaves: (docId: string, olderThan: Date) => Promise<number>;
+};

package/dist/vcs/types.js

@@ -0,0 +1,9 @@
+/**
+ * @file src/vcs/types.ts
+ * @desc The revision store's public shapes: its options, who is writing, what commit and revert
+ *       return, and the store itself.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+export {};

package/dist/vcs/write.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file src/vcs/write.ts
+ * @desc The one way a revision gets written: size cap, then the app's check, then an insert at a
+ *       given seq. The unique (docId, seq) index makes a second writer at the same seq fail with
+ *       a duplicate key, which the caller retries. After an insert, the oldest autosaves past
+ *       maxRevisions go. Internal.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { type Revision } from "@haruhimemoe/vcs";
+import type { RevisionDoc } from "./docs.js";
+import type { StoreContext } from "./read.js";
+import type { RevisionAuthor } from "./types.js";
+/** What insertRevision writes besides the value. */
+export type NewRevision<T> = Pick<RevisionDoc<T>, "docId" | "seq" | "kind"> & {
+    value: T;
+    author: RevisionAuthor;
+    message?: string | null | undefined;
+    base?: string | undefined;
+};
+/**
+ * @function valueHash
+ * @param ctx {StoreContext<T>} the store
+ * @param value {T} a value
+ * @returns {Promise<string>} the hash of the value without the codec's ignored paths
+ */
+export declare const valueHash: <T>(ctx: StoreContext<T>, value: T) => Promise<string>;
+/**
+ * @function insertRevision
+ * @param ctx {StoreContext<T>} the store
+ * @param input {NewRevision<T>} the revision to write
+ * @param hash {string | undefined} the value's hash, when the caller already has it
+ * @returns {Promise<Revision<T>>} the written revision
+ * @throws {RangeError} past maxBytes; whatever `check` throws; a duplicate key error when the
+ *         seq is taken
+ */
+export declare const insertRevision: <T>(ctx: StoreContext<T>, input: NewRevision<T>, hash?: string) => Promise<Revision<T>>;

package/dist/vcs/write.js

@@ -0,0 +1,69 @@
+/**
+ * @file src/vcs/write.ts
+ * @desc The one way a revision gets written: size cap, then the app's check, then an insert at a
+ *       given seq. The unique (docId, seq) index makes a second writer at the same seq fail with
+ *       a duplicate key, which the caller retries. After an insert, the oldest autosaves past
+ *       maxRevisions go. Internal.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { canonicalJson, hashValue, withoutIgnored } from "@haruhimemoe/vcs";
+import { toRevision } from "./docs.js";
+/**
+ * @function valueHash
+ * @param ctx {StoreContext<T>} the store
+ * @param value {T} a value
+ * @returns {Promise<string>} the hash of the value without the codec's ignored paths
+ */
+export const valueHash = (ctx, value) => hashValue(withoutIgnored(value, ctx.options.codec));
+/**
+ * @function insertRevision
+ * @param ctx {StoreContext<T>} the store
+ * @param input {NewRevision<T>} the revision to write
+ * @param hash {string | undefined} the value's hash, when the caller already has it
+ * @returns {Promise<Revision<T>>} the written revision
+ * @throws {RangeError} past maxBytes; whatever `check` throws; a duplicate key error when the
+ *         seq is taken
+ */
+export const insertRevision = async (ctx, input, hash) => {
+    const { options } = ctx;
+    const size = new TextEncoder().encode(canonicalJson(input.value)).length;
+    if (size > options.maxBytes)
+        throw new RangeError(`revision is ${size} bytes, over the ${options.maxBytes} limit`);
+    await options.check?.(input.value, input.kind);
+    const doc = {
+        _id: globalThis.crypto.randomUUID(),
+        docId: input.docId,
+        seq: input.seq,
+        kind: input.kind,
+        valueHash: hash ?? (await valueHash(ctx, input.value)),
+        authorId: input.author.id,
+        authorName: input.author.name,
+        message: input.message ?? null,
+        createdAt: new Date(options.now()),
+        ...(input.base === undefined ? {} : { base: input.base }),
+        value: input.value,
+    };
+    const collection = await ctx.collection();
+    await collection.insertOne(doc);
+    // Best effort: the revision is written, so a failed prune must not look like a failed save.
+    await pruneOverCap(ctx, input.docId, input.seq).catch((error) => {
+        console.error(`revisions: pruning ${input.docId} failed`, error);
+    });
+    return toRevision(doc);
+};
+/** Deletes the oldest autosaves (never the head) while the document is over maxRevisions. */
+const pruneOverCap = async (ctx, docId, headSeq) => {
+    const collection = await ctx.collection();
+    const over = (await collection.countDocuments({ docId })) - ctx.options.maxRevisions;
+    if (over <= 0)
+        return;
+    const oldest = await collection
+        .find({ docId, kind: "autosave", seq: { $lt: headSeq } }, { projection: { _id: 1 } })
+        .sort({ seq: 1 })
+        .limit(over)
+        .toArray();
+    if (oldest.length > 0)
+        await collection.deleteMany({ _id: { $in: oldest.map((doc) => doc._id) } });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haruhimemoe/next-kit",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "The Next.js plumbing the haruhime.moe tools share: JSON route helpers, rate limits and budgets in MongoDB, bearer machine auth, zod env parsing, a connect-once MongoDB client with safe index builds, better-auth with osu! sign-in, the signed-in marker and account store for the browser, SEO: metadata, robots.txt, sitemaps, JSON-LD and llms.txt, and per-app API keys and the /api/v1 guard.",
   "keywords": [
     "nextjs",
@@ -70,6 +70,10 @@
       "types": "./dist/docs/files/index.d.ts",
       "default": "./dist/docs/files/index.js"
     },
+    "./vcs": {
+      "types": "./dist/vcs/index.d.ts",
+      "default": "./dist/vcs/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -101,6 +105,7 @@
   "peerDependencies": {
     "@haruhimemoe/osu": "^0.2.0 || ^0.3.0 || ^0.4.0",
     "@haruhimemoe/ui": "^0.5.0 || ^0.6.0 || ^0.7.0 || ^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0",
+    "@haruhimemoe/vcs": "^0.1.0",
     "better-auth": "^1.7.5",
     "mongodb": "^7.6.0",
     "mongodb-memory-server": "^11.3.0",
@@ -118,6 +123,9 @@
     "@haruhimemoe/ui": {
       "optional": true
     },
+    "@haruhimemoe/vcs": {
+      "optional": true
+    },
     "better-auth": {
       "optional": true
     },
@@ -147,6 +155,7 @@
     "@biomejs/biome": "2.5.14",
     "@haruhimemoe/osu": "0.2.0",
     "@haruhimemoe/ui": "0.5.0",
+    "@haruhimemoe/vcs": "0.1.0",
     "@testing-library/dom": "10.4.2",
     "@testing-library/react": "16.3.3",
     "@types/node": "26.6.2",