@ddd-ts-kit/kernel 0.8.0 → 0.10.0

package/README.md

@@ -735,6 +735,75 @@ the guard of an invariant: what must not happen twice is refused by a database c
 `Clock`: the fake, and enough for a single instance. The adapter between processes is in
 `@ddd-ts-kit/redis`. `acquiring(attempt, waitMs, waiting)` is the retry loop an adapter shares.
 
+### FileStorage, StoredFile, FileScanner
+
+```ts
+// The command wraps what the controller received: the bus stages it before the transaction opens.
+this.document = new FileUpload(received, 'appointment-documents');
+
+// The handler, inside the unit of work:
+const { file, fileName } = command.document;                     // a StoredFile, staged and scanned
+appointment.attachDocument(unwrap(AttachedDocument.create(file, fileName, now)), now);
+await appointments.save(appointment);
+await staging.promoteOnCommit(file.key);                         // moved to its key with the commit
+```
+
+`FileStorage` holds the content of files, never the database: `put` (a stream in, measured and
+hashed, refused with `FILE_TOO_LARGE` beyond `maxBytes`, leaving nothing), `get` (a stream out),
+`stat`, `delete`, `copy`, `move`, `list(prefix)`, and short signed links, `signedDownloadUrl` and
+`signedUploadUrl` (at most `MAX_SIGNED_URL_SECONDS`, one hour). No method takes or returns a
+whole file. A key is checked by `isFileKey` (segments of letters, digits, `.`, `-` and `_`, none
+starting with a dot) before anything is touched, and `FileKeys` generates it on the server:
+`TenantFileKeys(ids, clock, scope)` writes `tenants/<tenant>/<area>/<year>/<month>/<id>`, the
+tenant segment only when the work in progress names one (the tenant id as it is: the kernel
+refuses any other than letters, digits, `-` and `_`, so two tenants never share a prefix). The links of
+`signedUploadUrl` carry a `maxBytes`, which the storages the application serves enforce.
+
+`StoredFile` is what an aggregate keeps: `key`, `size`, `mediaType`, `checksum` (`sha256:<hex>`),
+never the provider. `FileScanner` is the hook of an antivirus or a content check, called on the
+staged file before it is accepted; `AcceptEveryFileScanner` is the one of a project that has
+none yet. `FileError` carries the refusals: `FILE_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE`,
+`FILE_NOT_FOUND`, `INVALID_FILE_KEY`, `FILE_REJECTED`, `INVALID_FILE_URL_EXPIRY`.
+
+A write to the storage is not rolled back with a transaction. `FileStaging(storage, scanner,
+reporter)` gives the order that keeps both consistent, each step once:
+
+- `stage(key, content, options)` writes under `staging/<key>` and scans; a refused file is
+  removed (`FILE_REJECTED`). A file from a client travels in its command as a `FileUpload`
+  (the `ReceivedFile` and the area of its key), staged by `fileUploadsMiddleware(desk)`, a bus
+  middleware placed after the permission and before the unit of work, so no transaction waits
+  on an upload. `upload.file` is the staged `StoredFile`.
+- `promoteOnCommit(key)` moves the file to its key as the last step of the unit of work
+  (`atCommit`, a `CommitStep` of `apply` and `undo`): a promotion that fails rolls the command
+  back, and a transaction that rolls back after it returns the file to `staging/`. A committed
+  row never points into `staging/`.
+- `deleteAfterCommit(key)` deletes, once committed, a file the aggregate no longer references
+  (`afterCommit`, at most once: a failure or a crash leaves an unreferenced file, reported).
+- `purge(olderThan)` removes the staged files older than the instant, all orphans; the job
+  `PurgeStagedFiles` runs it (the platform registers it as `files.purge-staged`, every hour,
+  for files staged a day ago or more).
+
+For a large file the client uploads straight to the storage: `uploadUrl(key, { expiresInSeconds,
+mediaType, accepted, maxBytes })` answers the `link` for the client and the `pending` grant
+(`PendingUpload`: key, size cap, media types) that the command records on the aggregate;
+`confirm(pending)`, called by a command that reads the grant back from the aggregate, never
+from the client, checks what arrived against the cap and on its bytes (`contentMatches`), scans
+it, and answers the `StoredFile`. No final key may start with `staging/` (`assertFinalKey`).
+
+`FileInspection` is the pass-through every connector streams through: it counts, hashes, and
+with an expectation holds back the first bytes until they prove the declared media type
+(`acceptsMediaType`, `contentMatches`: a PDF starts with `%PDF-`, office documents are zip
+archives, text is UTF-8 without control characters, SVG and unknown binary formats never
+match).
+
+Connectors: `InMemoryFileStorage` for the tests (`keys()` lists what it holds) and
+`LocalFileStorage({ directory, baseUrl, secret })` for development, both `ServedFileStorage`:
+their signed links point at the application, which answers them with `signedFileRoutes` of
+`@ddd-ts-kit/http`. The object store connector is `@ddd-ts-kit/s3`. Each passes
+`fileStorageContract` of `@ddd-ts-kit/testing/contracts`. Background import and export (row by
+row validation, an error report, resumption) needs a job queue the kit does not have yet: the
+ports are ready for it, see `docs/concepts/file-storage.md`.
+
 ### JobScheduler
 
 ```ts
@@ -1134,8 +1203,10 @@ the fakes, `KnexReadModelStore`, `DrizzleReadModelStore`, `PrismaReadModelStore`
 
 ### Rebuild
 
-The kit has no event store: a read model is rebuilt from the source of truth, the read
-contract the owning context publishes, behind a gateway port that answers stamped rows.
+A read model fed by events that no event store keeps is rebuilt from the source of truth, the
+read contract the owning context publishes, behind a gateway port that answers stamped rows. A
+read model of event-sourced aggregates is rebuilt from the store instead:
+[Fed by the event store](#fed-by-the-event-store).
 
 ```ts
 await new ProjectionRebuild({ table: appointments.table, source, unitOfWork }).run();
@@ -1170,6 +1241,40 @@ privileges granted on the table by name, row security policies and triggers are
 and are restored by the migration that follows, and the indexes of the copy keep the names
 PostgreSQL derived for them.
 
+### Fed by the event store
+
+A projection of event-sourced aggregates can be fed by the store rather than where the domain
+events are dispatched: `@Projection('scheduling.attendance-history', { feed: 'event-store' })`.
+The dispatcher then never calls it (`@ddd-ts-kit/di` registers no handler for it); a catch-up
+subscription does, under the name of the projection, and the same projection rebuilds its read
+model from position zero.
+
+```ts
+const apply = applyingProjection(projection, serializer); // the @On methods, by event name
+
+const subscription = new CatchUpSubscription({ name: 'scheduling.attendance-history', store, checkpoints, unitOfWork, apply });
+
+await subscription.catchUp(); // or poll() from a job: one batch, one unit of work
+
+await new EventStoreProjectionRebuild({
+  table: history.table,
+  store,
+  unitOfWork,
+  applierOn: (copy) => applyingProjection(new AttendanceHistoryProjection(copy), serializer),
+}).run();
+```
+
+| Piece | What it does |
+|---|---|
+| `CatchUpSubscription` | Reads the store after the checkpoint of its subscriber (`CheckpointStore`), applies a batch and moves the checkpoint in one unit of work. A failure applies none of the batch; two runs of one subscriber never both move it (`ConcurrencyError`). A new projection starts at zero, so it catches up on the whole history |
+| `applyingProjection(projection, serializer)` | (`@ddd-ts-kit/kernel/declarations`) hands each stored event an `@On` method applies, read back by the serializer of its aggregate, to that method; passes over the rest of the store |
+| `storedStampOf(event)` | The stamp of an event read from the store: its id, instant and version in its stream, so the rows of one stream are ordered by the stream, not by clocks. `undefined` for an event that did not come from a store |
+| `EventStoreProjectionRebuild` | Fills an empty copy of the table by replaying the store from position zero through the projection built over the copy (`ShadowReadModelStore`); then, in one transaction, holds the writers, replays what was appended meanwhile and puts the copy in place of the table. The subscription goes on from its checkpoint; what it applies again is stale against the copy. A failed rebuild leaves the table as it was |
+
+A projection fed by the store applies the domain events of its context only: an integration
+event reaches a projection where it is consumed, and `@On(definition)` on such a projection
+throws when the file loads.
+
 ### Seen from outside
 
 Through the ports that exist. `@ddd-ts-kit/di` counts `projection_events_total` by `context`,
@@ -1179,6 +1284,106 @@ A projection is subscribed as a consumer under its name, so each delivery is one
 <projection>` span, with the calls to its read model below it, and an event buried after its
 retries reaches the error reporter as for any consumer.
 
+## Event sourcing
+
+Chosen per aggregate, never per project: the other aggregates of the context keep their state
+in tables. When to choose it and what it costs:
+[docs/concepts/event-sourcing.md](../../docs/concepts/event-sourcing.md).
+
+```ts
+// domain/aggregates/attendance-record.aggregate.ts
+type AttendanceEvent = AttendanceRecordOpened | NoShowNoted;
+
+export class AttendanceRecord extends EventSourcedAggregate<AttendanceEvent, AttendanceState> {
+  private state: AttendanceState = { noShows: 0 };
+
+  private constructor(id: string) {
+    super(id);
+  }
+
+  static open(id: string, now: Date): AttendanceRecord {
+    const record = new AttendanceRecord(id);
+
+    record.record(new AttendanceRecordOpened(id, now));
+
+    return record;
+  }
+
+  static rehydrate(id: string, history: AggregateHistory<AttendanceEvent, AttendanceState>): AttendanceRecord {
+    const record = new AttendanceRecord(id);
+
+    return record.replay(history, (state) => record.restore(state));
+  }
+
+  noteNoShow(appointmentId: string, now: Date): void {
+    if (this.state.noShows >= 3) {
+      throw AttendanceRecordError.alreadyBarred(this.id);
+    }
+
+    this.record(new NoShowNoted(this.id, now, appointmentId));
+  }
+
+  protected appliers(): Appliers<AttendanceEvent> {
+    return {
+      [AttendanceRecordOpened.eventName]: () => undefined,
+      [NoShowNoted.eventName]: (event) => this.applyNoShowNoted(event),
+    };
+  }
+
+  private restore(state: AttendanceState): void {
+    this.state = state;
+  }
+
+  private applyNoShowNoted(event: NoShowNoted): void {
+    this.state = { noShows: this.state.noShows + 1 };
+  }
+}
+```
+
+| Piece | What it does |
+|---|---|
+| `EventSourcedAggregate<E, S>` | A command checks its invariants on the state, then `record(event)`: the event is applied through the method `appliers()` names for it, and kept for the save. Only apply methods (and `restore`, for a snapshot) change the state (`event-sourcing/state-in-apply`). `appliers()` must name every event of the union, or it does not compile |
+| `replay(history, restore?)` | Rebuilds from `{ snapshot?, events }`, through the same apply methods, recording nothing. `version` is the number of events of the stream the aggregate reflects |
+| `appendChanges(aggregate, append)` | What a repository adapter calls: the events recorded since the load and the version the stream must still have; on success the aggregate is at the new version |
+| `EventStore` | The port: `append(stream, expectedVersion, events)` (a `ConcurrencyError` when somebody appended first, nothing kept of it), `readStream(stream, after?)`, `readAll(after, limit)` in the order the appends committed, `head()`. `InMemoryEventStore` here; PostgreSQL through every ORM adapter. Held to `eventStoreContract` |
+| `defineStoredEvent(Event, spec)` | How one event is stored: `version` of its shape, `encode(event): NamedData` (plain data, dates kept as ISO text), `decode(data, envelope)` reading each field by type (`data.text('x')`, `data.instant('at')`, `data.record('amount')`), and `upcasters` from each older version |
+| `EventSerializer<E>` | Every stored event of one aggregate (`StoredEventTypes<E>`: one entry per event, or it does not compile). A stored event is never rewritten: it is upcast when read. An event of a later shape than the release knows, or a version without upcaster, is an `UnreadableEventError` |
+| `EventSourcedRepository` | What the repository adapter delegates to: `findById` replays the stream `<category>-<id>` (from the last snapshot), `save` appends in the transaction of the unit of work; the events then leave with the save like any other |
+| `SnapshotPolicy` | Per aggregate: `every` so many events, a `version` of the shape (another one is ignored, the stream replayed), `encode` and `decode`. `expectSnapshotEquivalence` of `@ddd-ts-kit/testing` proves a snapshot rebuilds the state a full replay does |
+| `personalData(subject, value)` | Marks a personal value in `encode`. `PersonalDataCipher` over a `SubjectKeyStore` seals it with the key of its data subject (AES-256-GCM); `SubjectKeyStore.erase(subject)` destroys the key, and a replay then reads `ERASED_PERSONAL_DATA` |
+
+```ts
+// infrastructure/persistence/event-store-attendance-record.repository.ts
+@Repository(AttendanceRecordRepository)
+export class EventStoreAttendanceRecordRepository implements AttendanceRecordRepository {
+  private readonly streams: EventSourcedRepository<AttendanceRecord, AttendanceEvent, AttendanceState>;
+
+  constructor(store: EventStore, snapshots: SnapshotStore, cipher: PersonalDataCipher) {
+    this.streams = new EventSourcedRepository({
+      store,
+      category: 'scheduling.attendance-record',
+      serializer: new EventSerializer<AttendanceEvent>(attendanceRecordEvents, { cipher }),
+      rehydrate: (id, history) => AttendanceRecord.rehydrate(id, history),
+      snapshots: { store: snapshots, every: 50, version: 1, encode: (record) => record.toState(), decode: stateOf },
+    });
+  }
+
+  findById(id: string): Promise<AttendanceRecord | undefined> {
+    return this.streams.findById(id);
+  }
+
+  save(record: AttendanceRecord): Promise<void> {
+    return this.streams.save(record);
+  }
+}
+```
+
+**No double write.** The store joins the transaction of the unit of work, and the publisher of
+the integration events is a handler of the domain events that runs before the commit and
+writes the outbox: the stream and the outbox records commit together or not at all.
+`eventStoreUnitOfWorkContract` of `@ddd-ts-kit/testing` proves it for each transactional store:
+nothing is published for an append rolled back or refused by a concurrency conflict.
+
 ## How to extend
 
 `Session`, `ExecutionContext`, `Actor`, `AuditEntry` and `ErrorReport` each have an empty interface that a project fills by

package/dist/application/criteria/index.d.ts

@@ -0,0 +1,33 @@
+export * from './filter-operator.js';
+export * from './field-value.js';
+export * from './field-of.js';
+export * from './operator-of.js';
+export * from './operand-of.js';
+export * from './filter-node.js';
+export * from './filters.js';
+export * from './criteria.js';
+export * from './field-type.js';
+export * from './field-type-of.js';
+export * from './field-rule.js';
+export * from './field-declaration.js';
+export * from './criteria-limits.js';
+export * from './criteria-declaration.js';
+export * from './criteria-definition.js';
+export * from './criteria-definition-error.js';
+export * from './define-criteria.js';
+export * from './criteria-violation.js';
+export * from './validate-criteria.js';
+export * from './invalid-criteria-error.js';
+export * from './read-scope.js';
+export * from './read-scope-mapping.js';
+export * from './unmapped-read-scope-error.js';
+export * from './scoped-criteria.js';
+export * from './scoped.js';
+export * from './predicate.js';
+export * from './criteria-plan.js';
+export * from './plan-criteria.js';
+export * from './page-of-plan.js';
+export * from './select-rows.js';
+export * from './evaluate-plan.js';
+export * from './evaluate-criteria.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/application/criteria/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/application/criteria/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC"}

package/dist/application/criteria/index.js

@@ -0,0 +1,33 @@
+export * from './filter-operator.js';
+export * from './field-value.js';
+export * from './field-of.js';
+export * from './operator-of.js';
+export * from './operand-of.js';
+export * from './filter-node.js';
+export * from './filters.js';
+export * from './criteria.js';
+export * from './field-type.js';
+export * from './field-type-of.js';
+export * from './field-rule.js';
+export * from './field-declaration.js';
+export * from './criteria-limits.js';
+export * from './criteria-declaration.js';
+export * from './criteria-definition.js';
+export * from './criteria-definition-error.js';
+export * from './define-criteria.js';
+export * from './criteria-violation.js';
+export * from './validate-criteria.js';
+export * from './invalid-criteria-error.js';
+export * from './read-scope.js';
+export * from './read-scope-mapping.js';
+export * from './unmapped-read-scope-error.js';
+export * from './scoped-criteria.js';
+export * from './scoped.js';
+export * from './predicate.js';
+export * from './criteria-plan.js';
+export * from './plan-criteria.js';
+export * from './page-of-plan.js';
+export * from './select-rows.js';
+export * from './evaluate-plan.js';
+export * from './evaluate-criteria.js';
+//# sourceMappingURL=index.js.map

package/dist/application/criteria/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/application/criteria/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC"}

package/dist/application/event-sourcing/appended.d.ts

@@ -0,0 +1,8 @@
+/** Where an append left its stream and the store. */
+export interface Appended {
+    /** The version of the stream after the append. */
+    readonly version: number;
+    /** The position of the last event appended; the position of the store when nothing was. */
+    readonly position: number;
+}
+//# sourceMappingURL=appended.d.ts.map

package/dist/application/event-sourcing/appended.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appended.d.ts","sourceRoot":"","sources":["../../../src/application/event-sourcing/appended.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,MAAM,WAAW,QAAQ;IACvB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B"}

package/dist/application/event-sourcing/appended.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=appended.js.map

package/dist/application/event-sourcing/appended.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appended.js","sourceRoot":"","sources":["../../../src/application/event-sourcing/appended.ts"],"names":[],"mappings":""}

package/dist/application/event-sourcing/define-stored-event.d.ts

@@ -0,0 +1,10 @@
+import type { DomainEvent } from '../../domain/domain-event.js';
+import type { DomainEventType } from '../../declarations/model/domain-event-type.js';
+import type { StoredEventSpec } from './stored-event-spec.js';
+import type { StoredEventType } from './stored-event-type.js';
+/**
+ * Declares how an event of `type` is stored, in the event codec of its aggregate (infrastructure):
+ * `defineStoredEvent(NoShowNoted, { version: 1, encode: (event): NoShowNotedData => ({ ... }), decode: ... })`.
+ */
+export declare function defineStoredEvent<E extends DomainEvent, Data extends object>(type: DomainEventType<E>, spec: StoredEventSpec<E, Data>): StoredEventType<E>;
+//# sourceMappingURL=define-stored-event.d.ts.map

package/dist/application/event-sourcing/define-stored-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-stored-event.d.ts","sourceRoot":"","sources":["../../../src/application/event-sourcing/define-stored-event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+CAA+C,CAAC;AAErF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EAAE,IAAI,SAAS,MAAM,EAC1E,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,EACxB,IAAI,EAAE,eAAe,CAAC,CAAC,EAAE,IAAI,CAAC,GAC7B,eAAe,CAAC,CAAC,CAAC,CAiBpB"}

package/dist/application/event-sourcing/define-stored-event.js

@@ -0,0 +1,22 @@
+import { storedDataOf } from './stored-data-of.js';
+/**
+ * Declares how an event of `type` is stored, in the event codec of its aggregate (infrastructure):
+ * `defineStoredEvent(NoShowNoted, { version: 1, encode: (event): NoShowNotedData => ({ ... }), decode: ... })`.
+ */
+export function defineStoredEvent(type, spec) {
+    if (!Number.isInteger(spec.version) || spec.version < 1) {
+        throw new TypeError(`The stored version of ${type.name} is a whole number from 1, not ${spec.version}`);
+    }
+    return {
+        version: spec.version,
+        upcasters: spec.upcasters ?? {},
+        encode: (event) => {
+            if (!(event instanceof type)) {
+                throw new TypeError(`"${event.name}" is declared as a ${type.name} and was recorded as another class`);
+            }
+            return storedDataOf(spec.encode(event));
+        },
+        decode: (data, envelope) => spec.decode(data, envelope),
+    };
+}
+//# sourceMappingURL=define-stored-event.js.map

package/dist/application/event-sourcing/define-stored-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-stored-event.js","sourceRoot":"","sources":["../../../src/application/event-sourcing/define-stored-event.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAInD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAwB,EACxB,IAA8B;IAE9B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,SAAS,CAAC,yBAAyB,IAAI,CAAC,IAAI,kCAAkC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1G,CAAC;IAED,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,EAAE;QAC/B,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;YAChB,IAAI,CAAC,CAAC,KAAK,YAAY,IAAI,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,IAAI,sBAAsB,IAAI,CAAC,IAAI,oCAAoC,CAAC,CAAC;YACzG,CAAC;YAED,OAAO,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,CAAC;QACD,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC;KACxD,CAAC;AACJ,CAAC"}

package/dist/application/event-sourcing/erased-personal-data.d.ts

@@ -0,0 +1,3 @@
+/** What a replay reads in place of a personal value whose data subject was erased: the key that sealed it is gone. */
+export declare const ERASED_PERSONAL_DATA = "[erased]";
+//# sourceMappingURL=erased-personal-data.d.ts.map

package/dist/application/event-sourcing/erased-personal-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"erased-personal-data.d.ts","sourceRoot":"","sources":["../../../src/application/event-sourcing/erased-personal-data.ts"],"names":[],"mappings":"AAAA,sHAAsH;AACtH,eAAO,MAAM,oBAAoB,aAAa,CAAC"}

package/dist/application/event-sourcing/erased-personal-data.js

@@ -0,0 +1,3 @@
+/** What a replay reads in place of a personal value whose data subject was erased: the key that sealed it is gone. */
+export const ERASED_PERSONAL_DATA = '[erased]';
+//# sourceMappingURL=erased-personal-data.js.map

package/dist/application/event-sourcing/erased-personal-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"erased-personal-data.js","sourceRoot":"","sources":["../../../src/application/event-sourcing/erased-personal-data.ts"],"names":[],"mappings":"AAAA,sHAAsH;AACtH,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC"}

package/dist/application/event-sourcing/event-envelope.d.ts

@@ -0,0 +1,9 @@
+/** What a stored event says besides its data, handed to `decode` to build the domain event back. */
+export interface EventEnvelope {
+    readonly id: string;
+    readonly aggregateId: string;
+    readonly occurredAt: Date;
+    /** Its rank in its stream. */
+    readonly version: number;
+}
+//# sourceMappingURL=event-envelope.d.ts.map

package/dist/application/event-sourcing/event-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-envelope.d.ts","sourceRoot":"","sources":["../../../src/application/event-sourcing/event-envelope.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B"}

package/dist/application/event-sourcing/event-envelope.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=event-envelope.js.map

package/dist/application/event-sourcing/event-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-envelope.js","sourceRoot":"","sources":["../../../src/application/event-sourcing/event-envelope.ts"],"names":[],"mappings":""}

package/dist/application/event-sourcing/event-to-append.d.ts

@@ -0,0 +1,15 @@
+import type { StoredData } from './stored-data.js';
+/** An event as the store is handed it: serialized, not yet placed in its stream. */
+export interface EventToAppend {
+    /** Unique in the store. */
+    readonly id: string;
+    /** The name the domain event carries, `<context>.<aggregate>.<fact>`. */
+    readonly type: string;
+    /** The version of the shape of `data`; a stored event is never rewritten, it is upcast when read. */
+    readonly schemaVersion: number;
+    readonly data: StoredData;
+    /** What is not the fact itself: correlation, causation, actor. */
+    readonly metadata?: StoredData;
+    readonly occurredAt: Date;
+}
+//# sourceMappingURL=event-to-append.d.ts.map

package/dist/application/event-sourcing/event-to-append.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-to-append.d.ts","sourceRoot":"","sources":["../../../src/application/event-sourcing/event-to-append.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qGAAqG;IACrG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;CAC3B"}

package/dist/application/event-sourcing/event-to-append.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=event-to-append.js.map

package/dist/application/event-sourcing/event-to-append.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-to-append.js","sourceRoot":"","sources":["../../../src/application/event-sourcing/event-to-append.ts"],"names":[],"mappings":""}

package/dist/application/event-sourcing/index.d.ts

@@ -0,0 +1,21 @@
+export * from './appended.js';
+export * from './define-stored-event.js';
+export * from './erased-personal-data.js';
+export * from './event-envelope.js';
+export * from './event-to-append.js';
+export * from './is-stored-data.js';
+export * from './is-stored-list.js';
+export * from './personal-data.js';
+export * from './stored-data-of.js';
+export * from './stored-data.js';
+export * from './stored-event-data.js';
+export * from './stored-event-spec.js';
+export * from './stored-event-type.js';
+export * from './stored-event-types.js';
+export * from './stored-event.js';
+export * from './stored-json.js';
+export * from './stored-snapshot.js';
+export * from './subject-key.js';
+export * from './unreadable-event-error.js';
+export * from './upcaster.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/application/event-sourcing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/application/event-sourcing/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,eAAe,CAAC"}

package/dist/application/event-sourcing/index.js

@@ -0,0 +1,21 @@
+export * from './appended.js';
+export * from './define-stored-event.js';
+export * from './erased-personal-data.js';
+export * from './event-envelope.js';
+export * from './event-to-append.js';
+export * from './is-stored-data.js';
+export * from './is-stored-list.js';
+export * from './personal-data.js';
+export * from './stored-data-of.js';
+export * from './stored-data.js';
+export * from './stored-event-data.js';
+export * from './stored-event-spec.js';
+export * from './stored-event-type.js';
+export * from './stored-event-types.js';
+export * from './stored-event.js';
+export * from './stored-json.js';
+export * from './stored-snapshot.js';
+export * from './subject-key.js';
+export * from './unreadable-event-error.js';
+export * from './upcaster.js';
+//# sourceMappingURL=index.js.map

package/dist/application/event-sourcing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/application/event-sourcing/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,eAAe,CAAC"}

package/dist/application/event-sourcing/is-stored-data.d.ts

@@ -0,0 +1,5 @@
+import type { StoredData } from './stored-data.js';
+import type { StoredJson } from './stored-json.js';
+/** Whether a stored value is an object, not a list nor a scalar. */
+export declare function isStoredData(value: StoredJson | undefined): value is StoredData;
+//# sourceMappingURL=is-stored-data.d.ts.map

package/dist/application/event-sourcing/is-stored-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-stored-data.d.ts","sourceRoot":"","sources":["../../../src/application/event-sourcing/is-stored-data.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,KAAK,IAAI,UAAU,CAE/E"}

package/dist/application/event-sourcing/is-stored-data.js

@@ -0,0 +1,5 @@
+/** Whether a stored value is an object, not a list nor a scalar. */
+export function isStoredData(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=is-stored-data.js.map

package/dist/application/event-sourcing/is-stored-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-stored-data.js","sourceRoot":"","sources":["../../../src/application/event-sourcing/is-stored-data.ts"],"names":[],"mappings":"AAGA,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAAC,KAA6B;IACxD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/dist/application/event-sourcing/is-stored-list.d.ts

@@ -0,0 +1,4 @@
+import type { StoredJson } from './stored-json.js';
+/** Whether a stored value is a list. */
+export declare function isStoredList(value: StoredJson | undefined): value is readonly StoredJson[];
+//# sourceMappingURL=is-stored-list.d.ts.map

package/dist/application/event-sourcing/is-stored-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-stored-list.d.ts","sourceRoot":"","sources":["../../../src/application/event-sourcing/is-stored-list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,KAAK,IAAI,SAAS,UAAU,EAAE,CAE1F"}

package/dist/application/event-sourcing/is-stored-list.js

@@ -0,0 +1,5 @@
+/** Whether a stored value is a list. */
+export function isStoredList(value) {
+    return Array.isArray(value);
+}
+//# sourceMappingURL=is-stored-list.js.map

package/dist/application/event-sourcing/is-stored-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-stored-list.js","sourceRoot":"","sources":["../../../src/application/event-sourcing/is-stored-list.ts"],"names":[],"mappings":"AAEA,wCAAwC;AACxC,MAAM,UAAU,YAAY,CAAC,KAA6B;IACxD,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC"}

package/dist/application/event-sourcing/personal-data.d.ts

@@ -0,0 +1,14 @@
+/** A personal value in the data `encode` answers, until the serializer seals it. */
+export interface PersonalValue {
+    readonly $personal: {
+        readonly subject: string;
+        readonly value: string;
+    };
+}
+/**
+ * Marks a personal value of the data of a stored event, in `encode`: `note: personalData(patientId, note)`.
+ * The serializer seals it with the key of its data subject before it reaches the store, and opens
+ * it when the event is read; once the subject is erased, the read gives `ERASED_PERSONAL_DATA`.
+ */
+export declare function personalData(subject: string, value: string): PersonalValue;
+//# sourceMappingURL=personal-data.d.ts.map

package/dist/application/event-sourcing/personal-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"personal-data.d.ts","sourceRoot":"","sources":["../../../src/application/event-sourcing/personal-data.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAE1E"}

package/dist/application/event-sourcing/personal-data.js

@@ -0,0 +1,9 @@
+/**
+ * Marks a personal value of the data of a stored event, in `encode`: `note: personalData(patientId, note)`.
+ * The serializer seals it with the key of its data subject before it reaches the store, and opens
+ * it when the event is read; once the subject is erased, the read gives `ERASED_PERSONAL_DATA`.
+ */
+export function personalData(subject, value) {
+    return { $personal: { subject, value } };
+}
+//# sourceMappingURL=personal-data.js.map

package/dist/application/event-sourcing/personal-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"personal-data.js","sourceRoot":"","sources":["../../../src/application/event-sourcing/personal-data.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,KAAa;IACzD,OAAO,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC;AAC3C,CAAC"}

package/dist/application/event-sourcing/stored-data-of.d.ts

@@ -0,0 +1,9 @@
+import type { StoredData } from './stored-data.js';
+/**
+ * The JSON an event store keeps for what `encode` answered: a date becomes its ISO text, a field
+ * holding `undefined` is left out. Anything else that is not plain data (a class instance, a
+ * function, a number that is not finite) is refused with a TypeError: encode maps value objects
+ * to their fields, the store never guesses.
+ */
+export declare function storedDataOf(value: object): StoredData;
+//# sourceMappingURL=stored-data-of.d.ts.map

package/dist/application/event-sourcing/stored-data-of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stored-data-of.d.ts","sourceRoot":"","sources":["../../../src/application/event-sourcing/stored-data-of.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAQtD"}