basalt / files-versions/src / FileVersions
Class: FileVersions
Defined in: files-versions/src/versions.ts:45
Revisions of a document, on top of @basaltkit/files.
Why a separate package and not a field on FileRecord. A file record describes bytes: their size, their checksum, where they sit on the disk. A revision describes an editorial act — someone replaced the draft, and said why. Putting a version column on the byte record would make every consumer of files carry a concept most of them do not have, and would still not answer the question that matters ("what did this document look like in March?"), because two uploads of the same document are two unrelated records with no link between them.
Each revision points at a whole file, and old revisions keep pointing at their own bytes. Nothing is overwritten, which is the point: in a law firm, knowing which draft of a contract you are reading is a professional obligation, not a convenience.
Constructors
Constructor
> new FileVersions(options, tenancyActive?): FileVersions
Defined in: files-versions/src/versions.ts:51
Parameters
options
tenancyActive?
() => boolean
Whether the host app registered @basaltkit/tenancy, exactly as Files takes it. fileVersionsPlugin wires it from the same 'tenancy:active' marker, so the two services resolve a scope identically — they must, or one writes under the context tenant and the other reads under 'default'.
Returns
FileVersions
Methods
addVersion()
> addVersion(groupId, content, input): Promise<ResolvedVersion>
Defined in: files-versions/src/versions.ts:88
Uploads a new revision of an existing document.
The previous revision is untouched — it keeps its own file, its own bytes and its own place in the history.
Parameters
groupId
string
content
Buffer
input
UploadInput & object
Returns
Promise<ResolvedVersion>
at()
> at(groupId, n, tenantId?): Promise<ResolvedVersion | null>
Defined in: files-versions/src/versions.ts:116
One revision by number, with its file.
Parameters
groupId
string
n
number
tenantId?
string
Returns
Promise<ResolvedVersion | null>
create()
> create(content, input): Promise<ResolvedVersion & object>
Defined in: files-versions/src/versions.ts:73
Uploads the first revision of a new document and returns its group id.
The group id is what the application stores against its own entity — a matter's contract, a client's mandate — and it never changes again.
Parameters
content
Buffer
input
UploadInput & object
Returns
Promise<ResolvedVersion & object>
download()
> download(groupId, n?, tenantId?): Promise<{ content: Buffer; record: FileRecord; version: FileVersion; }>
Defined in: files-versions/src/versions.ts:127
Downloads a specific revision's bytes. Defaults to the current one.
Parameters
groupId
string
n?
number
tenantId?
string
Returns
Promise<{ content: Buffer; record: FileRecord; version: FileVersion; }>
history()
> history(groupId, tenantId?): Promise<FileVersion[]>
Defined in: files-versions/src/versions.ts:122
Every revision, newest first. Versions only — no file lookups.
Parameters
groupId
string
tenantId?
string
Returns
Promise<FileVersion[]>
latest()
> latest(groupId, tenantId?): Promise<ResolvedVersion | null>
Defined in: files-versions/src/versions.ts:110
The current revision of a document, with its file.
tenantId is optional and last, mirroring Files — and for the same reason. SINGLE_TENANT_SCOPE is a store key, not a tenant id: passing it back as one puts a single-tenant app's reads inside a tenant context, where the disk prefixes every path and the bytes are not.
Parameters
groupId
string
tenantId?
string
Returns
Promise<ResolvedVersion | null>