Journal
このコンテンツはまだ日本語訳がありません。
Defined in: src/persistence/Journal.ts:10
Pluggable event journal — the persistence-plugin boundary. Core ships with an in-memory reference implementation and a SQLite-based one; the interface is deliberately narrow so third-party plug-ins (Cassandra, ScyllaDB, Postgres, …) only have to implement four methods.
Properties
Section titled “Properties”events?
Section titled “events?”
readonlyoptionalevents?:JournalEventBus
Defined in: src/persistence/Journal.ts:95
Optional in-process notification bus. When present, the read-side
query layer subscribes here for sub-poll-interval push delivery
(see JournalEventBus). Journals that span processes (Cassandra,
Postgres) leave it undefined — the query layer falls back to
the polling loop.
Methods
Section titled “Methods”append()
Section titled “append()”append<
E>(persistenceId,events,expectedSeq,tags?):Promise<PersistentEvent<E>[]>
Defined in: src/persistence/Journal.ts:17
Append events to the stream of persistenceId, enforcing optimistic
concurrency: the current highest sequence number MUST equal expectedSeq
or the call throws JournalConcurrencyError. Returns the written events
with their assigned sequence numbers.
Type Parameters
Section titled “Type Parameters”E = unknown
Parameters
Section titled “Parameters”persistenceId
Section titled “persistenceId”string
events
Section titled “events”readonly E[]
expectedSeq
Section titled “expectedSeq”number
readonly string[]
Returns
Section titled “Returns”Promise<PersistentEvent<E>[]>
close()?
Section titled “close()?”
optionalclose():Promise<void>
Defined in: src/persistence/Journal.ts:98
Best-effort teardown; idempotent.
Returns
Section titled “Returns”Promise<void>
delete()
Section titled “delete()”delete(
persistenceId,toSeq):Promise<void>
Defined in: src/persistence/Journal.ts:57
Delete events up to and including toSeq — used when compacting past
a snapshot. Only ever a prefix, so what survives is a suffix that
read still returns contiguously, and sequence numbers never rewind:
highestSeq keeps reporting the high-water mark afterwards.
Parameters
Section titled “Parameters”persistenceId
Section titled “persistenceId”string
number
Returns
Section titled “Returns”Promise<void>
highestSeq()
Section titled “highestSeq()”highestSeq(
persistenceId):Promise<number>
Defined in: src/persistence/Journal.ts:49
Current highest sequence number for persistenceId — 0 if no events exist.
Parameters
Section titled “Parameters”persistenceId
Section titled “persistenceId”string
Returns
Section titled “Returns”Promise<number>
persistenceIds()
Section titled “persistenceIds()”persistenceIds():
Promise<string[]>
Defined in: src/persistence/Journal.ts:60
Persistence IDs currently known to the journal (useful for projections).
Returns
Section titled “Returns”Promise<string[]>
persistenceIdsPaginated()?
Section titled “persistenceIdsPaginated()?”
optionalpersistenceIdsPaginated(afterPersistenceId,limit):Promise<string[]>
Defined in: src/persistence/Journal.ts:83
One ascending page of persistence ids: those strictly greater than
afterPersistenceId — all of them when it is undefined — capped at
limit. Returning fewer than limit means the journal is exhausted.
Optional on purpose. Not every store can enumerate ids in order:
DynamoDB reaches partition keys only through a full table scan, and
MongoDB’s distinct has no cursor. A journal without a sorted index
over its ids omits this, and the query layer falls back to
persistenceIds() plus an in-process slice — correct, just not cheaper
than the full list. Implement it wherever a sorted key exists; that is
what keeps currentPersistenceIdsPaginated from materialising a million
rows to hand back the first 256.
Which ascending order is the backend’s business. afterPersistenceId
is compared in the same order the page is sorted by, so Postgres’ collated
ORDER BY and SQLite’s byte-wise one are both fine — a paginated walk only
needs the order to be total and stable within one journal. What a
journal must not do is mix two orders across calls, which would make the
cursor skip ids.
Parameters
Section titled “Parameters”afterPersistenceId
Section titled “afterPersistenceId”string | undefined
number
Returns
Section titled “Returns”Promise<string[]>
read()
Section titled “read()”read<
E>(persistenceId,fromSeq,toSeq?):Promise<PersistentEvent<E>[]>
Defined in: src/persistence/Journal.ts:42
Return the events in [fromSeq, …, toSeq], ascending by sequence
number. toSeq defaults to the current highest sequence number.
Both bounds are inclusive — fromSeq is the first event returned,
not an “after” cursor.
Ordering and contiguity are part of the contract, and replay
enforces them (#122). Consecutive entries must differ by exactly
one, every sequenceNr must be a safe integer ≥ 1, and nothing may
fall outside the requested window. delete compacts a prefix,
never a hole in the middle, so a gap inside the returned slice can
only mean a defect — a missing ORDER BY, a half-written append, a
store someone else can write. replayState raises
JournalIntegrityError instead of folding it, because an actor
that recovers from a shuffled or holed stream reaches a state that
never existed and then fails every later persist with a
JournalConcurrencyError that has no visible cause.
Type Parameters
Section titled “Type Parameters”E = unknown
Parameters
Section titled “Parameters”persistenceId
Section titled “persistenceId”string
fromSeq
Section titled “fromSeq”number
toSeq?
Section titled “toSeq?”number
Returns
Section titled “Returns”Promise<PersistentEvent<E>[]>