TypeScript API / laikacms/documents / DocumentsRepository

Abstract Class: DocumentsRepository

Extended by

• InMemoryDocumentsRepository
• DrizzleDocumentsRepository
• CatalogDocumentsRepository
• DocumentsJsonApiProxyRepository
• ObsidianDocumentsRepository

Constructors

Constructor

new DocumentsRepository(): DocumentsRepository;

Returns

DocumentsRepository

Methods

acquireLock()

acquireLock(
   key, 
   owner, 
   options?
): LaikaTask<{
  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

LaikaTask<{ acquiredAt: Utc; expiresAt: Utc; key: string; owner: { id: string; name: string; }; token: string & Brand<"LockToken">; }>

---

createDocument()

abstract createDocument(create): LaikaTask<{
  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

LaikaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: "published"; type: "published"; updatedAt?: string; version?: string; }>

---

createRevision()

abstract createRevision(create): LaikaTask<{
  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

LaikaTask<{ content: { [key: string]: any; }; createdAt: string; key: string; language: string; revision: string; type: "revision"; updatedAt?: string; }>

---

createUnpublished()

abstract createUnpublished(create): LaikaTask<{
  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

LaikaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: string; type: "unpublished"; updatedAt?: string; version?: string; }>

---

deleteDocument()

abstract deleteDocument(key): LaikaTask<void>;

Parameters

Parameter	Type
key	string

Returns

LaikaTask<void>

---

deleteUnpublished()

abstract deleteUnpublished(key): LaikaTask<void>;

Parameters

Parameter	Type
key	string

Returns

LaikaTask<void>

---

getCapabilities()

abstract getCapabilities(): LaikaTask<{
  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

LaikaTask<{ 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): LaikaTask<{
  content: {
   [key: string]: any;
  };
  createdAt?: string;
  key: string;
  language: string;
  status: "published";
  type: "published";
  updatedAt?: string;
  version?: string;
}>;

Parameters

Parameter	Type
key	string

Returns

LaikaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: "published"; type: "published"; updatedAt?: string; version?: string; }>

---

getLock()

getLock(key): LaikaTask<
  | {
  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

LaikaTask< | { acquiredAt: Utc; expiresAt: Utc; key: string; owner: { id: string; name: string; }; } | null>

---

getRevision()

abstract getRevision(key, revision): LaikaTask<{
  content: {
   [key: string]: any;
  };
  createdAt: string;
  key: string;
  language: string;
  revision: string;
  type: "revision";
  updatedAt?: string;
}>;

Parameters

Parameter	Type
key	string
revision	string

Returns

LaikaTask<{ content: { [key: string]: any; }; createdAt: string; key: string; language: string; revision: string; type: "revision"; updatedAt?: string; }>

---

getSyncToken()

getSyncToken(options?): LaikaTask<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

LaikaTask<string & Brand<"SyncToken">>

---

getUnpublished()

abstract getUnpublished(key): LaikaTask<{
  content: {
   [key: string]: any;
  };
  createdAt?: string;
  key: string;
  language: string;
  status: string;
  type: "unpublished";
  updatedAt?: string;
  version?: string;
}>;

Parameters

Parameter	Type
key	string

Returns

LaikaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: string; type: "unpublished"; updatedAt?: string; version?: string; }>

---

listChanges()

listChanges(options): LaikaStream<{
  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

LaikaStream<{ deleted: boolean; key: string; version?: string; }, ListChangesDone>

---

listRecords()

abstract listRecords(options): LaikaStream<
  | {
  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;
}, LaikaDone>;

Parameters

Parameter	Type
options	ListRecordsOptions

Returns

LaikaStream< | { 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; }, LaikaDone>

---

listRecordSummaries()

abstract listRecordSummaries(options): LaikaStream<
  | {
  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;
}, LaikaDone>;

Parameters

Parameter	Type
options	ListRecordsOptions

Returns

LaikaStream< | { 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; }, LaikaDone>

---

listRevisions()

abstract listRevisions(key, options): LaikaStream<{
  createdAt?: string;
  key: string;
  language: string;
  revision: string;
  type: "revision-summary";
  updatedAt?: string;
}, LaikaDone>;

Parameters

Parameter	Type
key	string
options	ListRevisionsOptions

Returns

LaikaStream<{ createdAt?: string; key: string; language: string; revision: string; type: "revision-summary"; updatedAt?: string; }, LaikaDone>

---

publish()

abstract publish(key): LaikaTask<{
  content: {
   [key: string]: any;
  };
  createdAt?: string;
  key: string;
  language: string;
  status: "published";
  type: "published";
  updatedAt?: string;
  version?: string;
}>;

Parameters

Parameter	Type
key	string

Returns

LaikaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: "published"; type: "published"; updatedAt?: string; version?: string; }>

---

refreshLock()

refreshLock(
   key, 
   token, 
   owner, 
   options?
): LaikaTask<{
  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

LaikaTask<{ acquiredAt: Utc; expiresAt: Utc; key: string; owner: { id: string; name: string; }; token: string & Brand<"LockToken">; }>

---

releaseLock()

releaseLock(key, token): LaikaTask<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

LaikaTask<void>

---

unpublish()

abstract unpublish(key, status): LaikaTask<{
  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

LaikaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: string; type: "unpublished"; updatedAt?: string; version?: string; }>

---

updateDocument()

abstract updateDocument(update): LaikaTask<{
  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

LaikaTask<{ content: { [key: string]: any; }; createdAt?: string; key: string; language: string; status: "published"; type: "published"; updatedAt?: string; version?: string; }>

---

updateUnpublished()

abstract updateUnpublished(update): LaikaTask<{
  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

LaikaTask<{ 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) => LaikaTask<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) => LaikaTask<A, R>