createVersion
createVersion<
DataModel>(props):Promise<number>
Defined in: packages/core/src/versions/model.ts:55
Appends one immutable snapshot row to vex_versions.
Called by every write path in this spec that changes a document’s stored
content or publish status (saveDraft, publish, unpublish, and the
bootstrap snapshot saveDraft takes of a published row’s “v1 published”
state on first edit) — never called directly by a Convex handler.
Type Parameters
Section titled “Type Parameters”DataModel
Section titled “DataModel”DataModel extends GenericDataModel
Parameters
Section titled “Parameters”Input props.
collection
Section titled “collection”string
The collection slug the versioned document belongs to.
createdBy?
Section titled “createdBy?”string
The acting user’s id, when known.
GenericMutationCtx<DataModel>
A Convex mutation context (vex_versions is written here).
documentId
Section titled “documentId”string
The document’s _id, stringified. Always the
published row’s _id once one exists, or the sole draft row’s _id
for a never-published document — the published _id never changes
(design-review §2.2), so this never needs to be re-pointed mid-history.
parentVersion?
Section titled “parentVersion?”number
The version number this one was derived from (omitted for a document’s very first version).
publishedAt?
Section titled “publishedAt?”number
Set once a document has ever been published, carried forward on every subsequent version (including drafts) so “was this ever live” survives unpublish. Omitted for content that has never been published.
restoredFrom?
Section titled “restoredFrom?”number
Set only when this version’s content came from restoring an older version — the source version’s number.
snapshot
Section titled “snapshot”Record<string, unknown>
The document’s user-defined fields, already stripped via extractUserFields by the caller.
status
Section titled “status”"draft" | "published"
"draft" or "published" — the state THIS
snapshot captures, independent of the row’s CURRENT status by the time
anyone reads it back.
Returns
Section titled “Returns”Promise<number>
The new version’s row number — one greater than the document’s
current latest version, or 1 if it has none yet.