TypeScript API / contentia/documents / DocumentsRepository
Abstract Class: DocumentsRepository
Extended by
InMemoryDocumentsRepositoryDrizzleDocumentsRepositoryCatalogDocumentsRepositoryDocumentsJsonApiProxyRepositoryObsidianDocumentsRepository
Constructors
Constructor
new DocumentsRepository(): DocumentsRepository;Returns
DocumentsRepository
Methods
acquireLock()
acquireLock(
key,
owner,
options?
): ContentiaTask<{
acquiredAt: Utc;
expiresAt: Utc;
key: string;
owner: {
id: string;
name: string;
};
token: string & Brand<"LockToken">;
}>;Take the lock on key, or fail with LockConflictError when someone else holds it (unless force is set, which steals it and mints a new token).
Returns the lock including its token — the only place, besides refreshLock, the token is ever handed out.
Parameters
| Parameter | Type |
|---|---|
key | string |
owner | { id: string; name: string; } |
owner.id? | string |
owner.name? | string |
options? | { force?: boolean; ttlMs?: number; } |
options.force? | boolean |
options.ttlMs? | number |
Returns
ContentiaTask<{ acquiredAt: Utc; expiresAt: Utc; key: string; owner: { id: string; name: string; }; token: string & Brand<"LockToken">; }>
createDocument()
abstract createDocument(create): ContentiaTask<{
content: {
[key: string]: any;
};
createdAt?: string;
key: string;
language: string;
status: "published";
type: "published";
updatedAt?: string;
version?: string;
}>;Parameters
| Parameter | Type |
|---|---|
create | { content: { [key: string]: any; }; key: string; language: string; status: "published"; type: "published"; } |
create.content? | { [key: string]: any; } |
create.key? | string |
create.language? | string |
create.status? | "published" |
create.type? | "published" |
Returns
ContentiaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: "published"; type: "published"; updatedAt?: string; version?: string; }>
createRevision()
abstract createRevision(create): ContentiaTask<{
content: {
[key: string]: any;
};
createdAt: string;
key: string;
language: string;
revision: string;
type: "revision";
updatedAt?: string;
}>;Parameters
| Parameter | Type |
|---|---|
create | { content: { [key: string]: any; }; key: string; language: string; revision: string; type: "revision"; } |
create.content? | { [key: string]: any; } |
create.key? | string |
create.language? | string |
create.revision? | string |
create.type? | "revision" |
Returns
ContentiaTask<{ content: { [key: string]: any; }; createdAt: string; key: string; language: string; revision: string; type: "revision"; updatedAt?: string; }>
createUnpublished()
abstract createUnpublished(create): ContentiaTask<{
content: {
[key: string]: any;
};
createdAt?: string;
key: string;
language: string;
status: string;
type: "unpublished";
updatedAt?: string;
version?: string;
}>;Parameters
| Parameter | Type |
|---|---|
create | { content: { [key: string]: any; }; key: string; language: string; status: string; type: "unpublished"; } |
create.content? | { [key: string]: any; } |
create.key? | string |
create.language? | string |
create.status? | string |
create.type? | "unpublished" |
Returns
ContentiaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: string; type: "unpublished"; updatedAt?: string; version?: string; }>
deleteDocument()
abstract deleteDocument(key): ContentiaTask<void>;Parameters
| Parameter | Type |
|---|---|
key | string |
Returns
ContentiaTask<void>
deleteUnpublished()
abstract deleteUnpublished(key): ContentiaTask<void>;Parameters
| Parameter | Type |
|---|---|
key | string |
Returns
ContentiaTask<void>
getCapabilities()
abstract getCapabilities(): ContentiaTask<{
changes: | {
description: string;
supported: false;
}
| {
changeFeed: boolean;
description: string;
supported: true;
syncToken: boolean;
};
compatibilityDate: string & Brand<"DocumentsRepositoryCompatibilityDate">;
locks?: | {
description: string;
supported: false;
}
| {
description: string;
scope: "in-process" | "shared";
supported: true;
transactional: boolean;
};
pagination: | {
description: string;
supported: false;
}
| {
description: string;
styles: {
cursor: boolean;
offset: boolean;
page: boolean;
};
supported: true;
};
versionTracking: | {
description: string;
supported: false;
}
| {
description: string;
supported: true;
};
}>;Describe what this repository can do — currently which Pagination shapes it honors. Consumers can branch on this to skip or adapt looping logic.
Returns
ContentiaTask<{ changes: | { description: string; supported: false; } | { changeFeed: boolean; description: string; supported: true; syncToken: boolean; }; compatibilityDate: string & Brand<"DocumentsRepositoryCompatibilityDate">; locks?: | { description: string; supported: false; } | { description: string; scope: "in-process" | "shared"; supported: true; transactional: boolean; }; pagination: | { description: string; supported: false; } | { description: string; styles: { cursor: boolean; offset: boolean; page: boolean; }; supported: true; }; versionTracking: | { description: string; supported: false; } | { description: string; supported: true; }; }>
getDocument()
abstract getDocument(key): ContentiaTask<{
content: {
[key: string]: any;
};
createdAt?: string;
key: string;
language: string;
status: "published";
type: "published";
updatedAt?: string;
version?: string;
}>;Parameters
| Parameter | Type |
|---|---|
key | string |
Returns
ContentiaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: "published"; type: "published"; updatedAt?: string; version?: string; }>
getLock()
getLock(key): ContentiaTask<
| {
acquiredAt: Utc;
expiresAt: Utc;
key: string;
owner: {
id: string;
name: string;
};
}
| null>;Read the current lock, or null when the document is free. Returns the public projection: no token, so reading a lock never confers the right to release or write through it.
Parameters
| Parameter | Type |
|---|---|
key | string |
Returns
ContentiaTask< | { acquiredAt: Utc; expiresAt: Utc; key: string; owner: { id: string; name: string; }; } | null>
getRevision()
abstract getRevision(key, revision): ContentiaTask<{
content: {
[key: string]: any;
};
createdAt: string;
key: string;
language: string;
revision: string;
type: "revision";
updatedAt?: string;
}>;Parameters
| Parameter | Type |
|---|---|
key | string |
revision | string |
Returns
ContentiaTask<{ content: { [key: string]: any; }; createdAt: string; key: string; language: string; revision: string; type: "revision"; updatedAt?: string; }>
getSyncToken()
getSyncToken(options?): ContentiaTask<string & Brand<"SyncToken">>;Return an opaque token for the given scope (a folder, or the whole store when omitted) that changes whenever anything inside the scope changes. Compare tokens only by equality. A git implementation returns the branch head sha; a database implementation returns a sequence or max(updatedAt).
Non-abstract on purpose: existing subclasses stay source-compatible. The base implementation fails with NotImplementedError; check getCapabilities().changes before calling.
Parameters
| Parameter | Type |
|---|---|
options? | GetSyncTokenOptions |
Returns
ContentiaTask<string & Brand<"SyncToken">>
getUnpublished()
abstract getUnpublished(key): ContentiaTask<{
content: {
[key: string]: any;
};
createdAt?: string;
key: string;
language: string;
status: string;
type: "unpublished";
updatedAt?: string;
version?: string;
}>;Parameters
| Parameter | Type |
|---|---|
key | string |
Returns
ContentiaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: string; type: "unpublished"; updatedAt?: string; version?: string; }>
listChanges()
listChanges(options): ContentiaStream<{
deleted: boolean;
key: string;
version?: string;
}, ListChangesDone>;Enumerate what changed inside the scope since a previously obtained sync token. The done value carries the new sync token to resume from.
Non-abstract on purpose: existing subclasses stay source-compatible. The base implementation fails with NotImplementedError; check getCapabilities().changes before calling.
Parameters
| Parameter | Type |
|---|---|
options | ListChangesOptions |
Returns
ContentiaStream<{ deleted: boolean; key: string; version?: string; }, ListChangesDone>
listRecords()
abstract listRecords(options): ContentiaStream<
| {
createdAt?: string;
key: string;
type: "folder";
updatedAt?: string;
}
| {
content: {
[key: string]: any;
};
createdAt?: string;
key: string;
language: string;
status: "published";
type: "published";
updatedAt?: string;
version?: string;
}
| {
content: {
[key: string]: any;
};
createdAt?: string;
key: string;
language: string;
status: string;
type: "unpublished";
updatedAt?: string;
version?: string;
}, ContentiaDone>;Parameters
| Parameter | Type |
|---|---|
options | ListRecordsOptions |
Returns
ContentiaStream< | { createdAt?: string; key: string; type: "folder"; updatedAt?: string; } | { content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: "published"; type: "published"; updatedAt?: string; version?: string; } | { content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: string; type: "unpublished"; updatedAt?: string; version?: string; }, ContentiaDone>
listRecordSummaries()
abstract listRecordSummaries(options): ContentiaStream<
| {
createdAt?: string;
key: string;
language: string;
status: "published";
type: "published-summary";
updatedAt?: string;
version?: string;
}
| {
createdAt?: string;
key: string;
language: string;
status: string;
type: "unpublished-summary";
updatedAt?: string;
version?: string;
}
| {
createdAt?: string;
key: string;
type: "folder-summary";
updatedAt?: string;
}, ContentiaDone>;Parameters
| Parameter | Type |
|---|---|
options | ListRecordsOptions |
Returns
ContentiaStream< | { createdAt?: string; key: string; language: string; status: "published"; type: "published-summary"; updatedAt?: string; version?: string; } | { createdAt?: string; key: string; language: string; status: string; type: "unpublished-summary"; updatedAt?: string; version?: string; } | { createdAt?: string; key: string; type: "folder-summary"; updatedAt?: string; }, ContentiaDone>
listRevisions()
abstract listRevisions(key, options): ContentiaStream<{
createdAt?: string;
key: string;
language: string;
revision: string;
type: "revision-summary";
updatedAt?: string;
}, ContentiaDone>;Parameters
| Parameter | Type |
|---|---|
key | string |
options | ListRevisionsOptions |
Returns
ContentiaStream<{ createdAt?: string; key: string; language: string; revision: string; type: "revision-summary"; updatedAt?: string; }, ContentiaDone>
publish()
abstract publish(key): ContentiaTask<{
content: {
[key: string]: any;
};
createdAt?: string;
key: string;
language: string;
status: "published";
type: "published";
updatedAt?: string;
version?: string;
}>;Parameters
| Parameter | Type |
|---|---|
key | string |
Returns
ContentiaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: "published"; type: "published"; updatedAt?: string; version?: string; }>
refreshLock()
refreshLock(
key,
token,
owner,
options?
): ContentiaTask<{
acquiredAt: Utc;
expiresAt: Utc;
key: string;
owner: {
id: string;
name: string;
};
token: string & Brand<"LockToken">;
}>;Extend the lock the caller already holds.
Lenient by design: if the lock has expired or nobody holds it, this re-acquires rather than failing, because an editor whose refresh was late (a slept laptop, a slow network) should keep editing rather than be thrown out of a document nobody else wants. It fails with LockConflictError only when someone else now holds the lock, which is the case the editor must actually be told about.
owner is required for that re-acquire branch: reviving an expired lock has to attribute it to somebody, and the caller always knows who it is. (ADR-007 sketches this as refreshLock(key, token); the owner is the one piece that signature cannot supply.)
Parameters
| Parameter | Type |
|---|---|
key | string |
token | string & Brand<"LockToken"> |
owner | { id: string; name: string; } |
owner.id? | string |
owner.name? | string |
options? | { ttlMs?: number; } |
options.ttlMs? | number |
Returns
ContentiaTask<{ acquiredAt: Utc; expiresAt: Utc; key: string; owner: { id: string; name: string; }; token: string & Brand<"LockToken">; }>
releaseLock()
releaseLock(key, token): ContentiaTask<void>;Release the lock. Only the token-holder can: a non-matching token is a no-op, not an error, so a stale client cannot free someone else's lock and does not need to care that it failed.
Parameters
| Parameter | Type |
|---|---|
key | string |
token | string & Brand<"LockToken"> |
Returns
ContentiaTask<void>
unpublish()
abstract unpublish(key, status): ContentiaTask<{
content: {
[key: string]: any;
};
createdAt?: string;
key: string;
language: string;
status: string;
type: "unpublished";
updatedAt?: string;
version?: string;
}>;Parameters
| Parameter | Type |
|---|---|
key | string |
status | string |
Returns
ContentiaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: string; type: "unpublished"; updatedAt?: string; version?: string; }>
updateDocument()
abstract updateDocument(update): ContentiaTask<{
content: {
[key: string]: any;
};
createdAt?: string;
key: string;
language: string;
status: "published";
type: "published";
updatedAt?: string;
version?: string;
}>;Parameters
| Parameter | Type |
|---|---|
update | { content?: { [key: string]: any; }; key: string; language?: string; status?: "published"; type?: "published"; } |
update.content? | { [key: string]: any; } |
update.key? | string |
update.language? | string |
update.status? | "published" |
update.type? | "published" |
Returns
ContentiaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: "published"; type: "published"; updatedAt?: string; version?: string; }>
updateUnpublished()
abstract updateUnpublished(update): ContentiaTask<{
content: {
[key: string]: any;
};
createdAt?: string;
key: string;
language: string;
status: string;
type: "unpublished";
updatedAt?: string;
version?: string;
}>;Parameters
| Parameter | Type |
|---|---|
update | { content?: { [key: string]: any; }; key: string; language?: string; status?: string; } |
update.content? | { [key: string]: any; } |
update.key? | string |
update.language? | string |
update.status? | string |
Returns
ContentiaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: string; type: "unpublished"; updatedAt?: string; version?: string; }>
withDocumentLock()
withDocumentLock(
key,
owner,
options?
): <A, R>(use) => ContentiaTask<A, R>;Run use while holding the lock on key, releasing it afterwards on success, failure, or fiber interruption. The TTL is the backstop for the case no release can run at all, i.e. the whole node dies.
The default implementation is a bracket: mutual exclusion, no rollback of partial writes. A backend with a native transaction overrides this and advertises transactional: true; until then a caller that needs atomic multi-write must check the capability rather than assume.
The token is threaded explicitly, never through ambient context:
yield* repo.withDocumentLock(key, owner)(lock =>
repo.updateDocument(key, update, { precondition: { ifLockHeldBy: lock.token } })
);Parameters
| Parameter | Type |
|---|---|
key | string |
owner | { id: string; name: string; } |
owner.id? | string |
owner.name? | string |
options? | { force?: boolean; ttlMs?: number; } |
options.force? | boolean |
options.ttlMs? | number |
Returns
<A, R>(use) => ContentiaTask<A, R>