Bring the TypeScript client closer to parity with the .NET client

Documentation/client-snippets/compliance/client/combining.md

@@ -0,0 +1,19 @@
+```typescript
+import { eventType, pii } from '@cratis/chronicle';
+import { ConceptAs } from '@cratis/fundamentals';
+
+@pii()
+class ComplianceClientEmailAddress extends ConceptAs<string> {
+    constructor(value: string) {
+        super(value);
+    }
+}
+
+@eventType()
+class ComplianceClientCustomerRegistered {
+    name: ComplianceClientPersonName = new ComplianceClientPersonName('');       // encrypted via concept type
+    email: ComplianceClientEmailAddress = new ComplianceClientEmailAddress('');  // encrypted via concept type
+    @pii() phoneNumber = '';                                                    // encrypted via property annotation
+    country = '';                                                               // plaintext
+}
+```

Documentation/client-snippets/compliance/client/concept-usage.md

@@ -0,0 +1,13 @@
+```typescript
+import { eventType } from '@cratis/chronicle';
+
+@eventType()
+class ComplianceClientEmployeeRegisteredWithConcept {
+    constructor(readonly name: ComplianceClientPersonName, readonly department: string) {}
+}
+
+@eventType()
+class ComplianceClientEmployeeNameChanged {
+    constructor(readonly newName: ComplianceClientPersonName) {} // also encrypted
+}
+```

Documentation/client-snippets/compliance/client/event-source-id-restriction.md

@@ -0,0 +1,11 @@
+```typescript
+import { pii } from '@cratis/chronicle';
+
+// TypeScript represents the event source identifier as the conventional 'eventSourceId'
+// property rather than a dedicated EventSourceId<T> type. Marking it @pii() throws
+// PIINotSupportedOnEventSourceId - event source identifiers are required for key lookup and
+// cannot be encrypted.
+class ComplianceClientCustomerId {
+    @pii() eventSourceId = '';
+}
+```

Documentation/client-snippets/compliance/client/registering-compliance.md

@@ -0,0 +1,10 @@
+```typescript
+import { ChronicleClient } from '@cratis/chronicle';
+
+// TypeScript has no DI-container registration step for compliance support - the PII manager
+// is available automatically as soon as you have an event store, with no separate wiring.
+async function getPIIManager(chronicleClient: ChronicleClient) {
+    const eventStore = await chronicleClient.getEventStore('Sales');
+    return eventStore.pii;
+}
+```

Documentation/client-snippets/compliance/erasure/allow-new-key.md

@@ -0,0 +1,8 @@
+```typescript
+import { ChronicleClient } from '@cratis/chronicle';
+
+async function allowNewEncryptionKeyForPerson(chronicleClient: ChronicleClient): Promise<void> {
+    const eventStore = await chronicleClient.getEventStore('Sales');
+    await eventStore.pii.allowNewEncryptionKeyFor('person-42');
+}
+```

Documentation/client-snippets/compliance/erasure/delete-key.md

@@ -0,0 +1,8 @@
+```typescript
+import { ChronicleClient } from '@cratis/chronicle';
+
+async function deletePersonEncryptionKey(chronicleClient: ChronicleClient): Promise<void> {
+    const eventStore = await chronicleClient.getEventStore('Sales');
+    await eventStore.pii.deleteEncryptionKey('person-42');
+}
+```

Documentation/client-snippets/compliance/pii-with-concepts/event-source-id-restriction.md

@@ -0,0 +1,11 @@
+```typescript
+import { pii } from '@cratis/chronicle';
+
+// TypeScript has no dedicated EventSourceId<T> type to mark PII on directly - the event
+// source identifier is always the conventional 'eventSourceId' property, and marking it
+// @pii() throws PIINotSupportedOnEventSourceId for the same reason C# forbids [PII] on a
+// concept deriving from EventSourceId<T>.
+class PiiConceptsEmployeeId {
+    @pii() eventSourceId = '';
+}
+```

Documentation/client-snippets/compliance/pii-with-concepts/surrogate-key.md

@@ -0,0 +1,16 @@
+```typescript
+import { eventType, Guid } from '@cratis/chronicle';
+
+// ✅ Surrogate key as event source identifier - TypeScript event source identifiers are
+// plain strings, so a randomly generated Guid works well with no dedicated identity type
+// required.
+function createSurrogateEmployeeId(): string {
+    return Guid.create().toString();
+}
+
+// ✅ Sensitive values stored in PII-marked concept properties instead
+@eventType()
+class PiiConceptsSurrogateEmployeeRegistered {
+    constructor(readonly nationalId: PiiConceptsNationalIdNumber, readonly name: PiiConceptsPersonName) {}
+}
+```

Documentation/client-snippets/compliance/pii-with-concepts/why-concept-level.md

@@ -0,0 +1,35 @@
+```typescript
+import { eventType, pii } from '@cratis/chronicle';
+import { ConceptAs } from '@cratis/fundamentals';
+
+// ❌ Property-level: requires repetition across every event
+@eventType()
+class PiiConceptsComparisonEmployeeRegistered {
+    @pii() name = '';
+    department = '';
+}
+
+@eventType()
+class PiiConceptsComparisonEmployeeNameChanged {
+    @pii() newName = ''; // must remember @pii() again
+}
+
+// ✅ Concept-level: declare once, apply everywhere automatically
+@pii()
+class PiiConceptsComparisonPersonName extends ConceptAs<string> {
+    constructor(value: string) {
+        super(value);
+    }
+}
+
+@eventType()
+class PiiConceptsComparisonEmployeeRegisteredGood {
+    name: PiiConceptsComparisonPersonName = new PiiConceptsComparisonPersonName(''); // encrypted
+    department = '';
+}
+
+@eventType()
+class PiiConceptsComparisonEmployeeNameChangedGood {
+    newName: PiiConceptsComparisonPersonName = new PiiConceptsComparisonPersonName(''); // also encrypted, no extra annotation needed
+}
+```

Documentation/client-snippets/compliance/pii/event-source-id-restriction.md

@@ -0,0 +1,11 @@
+```typescript
+import { pii } from '@cratis/chronicle';
+
+// TypeScript has no dedicated EventSourceId<T> type - the event source identifier is always
+// the conventional 'eventSourceId' property. Marking it @pii() throws
+// PIINotSupportedOnEventSourceId at decoration time, for the same reason C# forbids [PII] on
+// EventSourceId<T>: encrypting it would make its own decryption key unfindable.
+class PiiAttrEmployeeId {
+    @pii() eventSourceId = '';
+}
+```

Documentation/client-snippets/compliance/pii/import.md

@@ -0,0 +1,3 @@
+```typescript
+import { pii } from '@cratis/chronicle';
+```

Documentation/client-snippets/compliance/pii/nested-value-object.md

@@ -0,0 +1,23 @@
+```typescript
+import { pii } from '@cratis/chronicle';
+import { ConceptAs } from '@cratis/fundamentals';
+
+@pii()
+class PiiAttrDateOfBirth extends ConceptAs<string> {
+    constructor(value: string) {
+        super(value);
+    }
+}
+
+// The concept sits one level down, inside a value object.
+class PiiAttrVerifiedDateOfBirth {
+    dateOfBirth: PiiAttrDateOfBirth = new PiiAttrDateOfBirth('');
+    verifiedBy = '';
+}
+
+// Chronicle still finds it: dateOfBirth.dateOfBirth is encrypted, verifiedBy is not.
+class PiiAttrExpressVerification {
+    name = '';
+    dateOfBirth: PiiAttrVerifiedDateOfBirth = new PiiAttrVerifiedDateOfBirth();
+}
+```

Documentation/client-snippets/compliance/pii/value-object-class.md

@@ -0,0 +1,16 @@
+```typescript
+import { pii } from '@cratis/chronicle';
+
+// Every value this type holds is personal, so mark the type once.
+@pii()
+class PiiAttrDiagnosis {
+    condition = '';
+    diagnosedBy = '';
+}
+
+// Both condition and diagnosedBy are encrypted wherever a PiiAttrDiagnosis appears.
+class PiiAttrPatientRecord {
+    name = '';
+    diagnosis: PiiAttrDiagnosis = new PiiAttrDiagnosis();
+}
+```

Documentation/client-snippets/compliance/read-models/projection-lineage.md

@@ -0,0 +1,26 @@
+```typescript
+import { eventType, fromEvent, pii, readModel } from '@cratis/chronicle';
+import { ConceptAs } from '@cratis/fundamentals';
+
+@pii()
+class ComplianceReadModelsPersonName extends ConceptAs<string> {
+    constructor(value: string) {
+        super(value);
+    }
+}
+
+@eventType()
+class ComplianceReadModelsEmployeeRegistered {
+    constructor(readonly name: ComplianceReadModelsPersonName, readonly department: string) {}
+}
+
+// Chronicle's projection pipeline carries PII lineage automatically from the source event
+// property into the read model - no @pii() is needed here even though `name` is a plain
+// string. It is still encrypted at rest because it came from a PII-marked event property.
+@readModel()
+@fromEvent(ComplianceReadModelsEmployeeRegistered)
+class ComplianceReadModelsEmployee {
+    name = '';
+    department = '';
+}
+```

Documentation/client-snippets/compliance/read-models/querying.md

@@ -0,0 +1,11 @@
+```typescript
+import { IEventStore } from '@cratis/chronicle';
+
+class ComplianceReadModelsEmployeeService {
+    constructor(private readonly eventStore: IEventStore) {}
+
+    getEmployee(id: string): Promise<ComplianceReadModelsEmployee> {
+        return this.eventStore.readModels.getInstanceById(ComplianceReadModelsEmployee, id);
+    }
+}
+```

Documentation/client-snippets/compliance/read-models/reducer-explicit-pii.md

@@ -0,0 +1,25 @@
+```typescript
+import { eventType, pii, reducer } from '@cratis/chronicle';
+
+@eventType()
+class ComplianceReadModelsPatientAdmitted {
+    constructor(readonly name: string, readonly admittedAt: Date) {}
+}
+
+// Reducer-backed read models do not inherit PII lineage from the source event automatically -
+// mark the property explicitly.
+class ComplianceReadModelsPatientSummary {
+    @pii() name = '';
+    lastAdmittedAt = new Date();
+}
+
+@reducer('PatientSummaryReducer', undefined, ComplianceReadModelsPatientSummary)
+class ComplianceReadModelsPatientSummaryReducer {
+    async patientAdmitted(
+        event: ComplianceReadModelsPatientAdmitted,
+        current?: ComplianceReadModelsPatientSummary
+    ): Promise<ComplianceReadModelsPatientSummary> {
+        return { name: event.name, lastAdmittedAt: event.admittedAt };
+    }
+}
+```

Documentation/client-snippets/concepts/correlation-identity-causation/renaming-an-identity.md

@@ -0,0 +1,7 @@
+```typescript
+import { IEventStore } from '@cratis/chronicle';
+
+async function renameAnIdentity(eventStore: IEventStore): Promise<void> {
+    await eventStore.identities.rename('subject-42', 'Jane Austen');
+}
+```

Documentation/client-snippets/concepts/designing-read-models/constructor-may-not-run.md

@@ -0,0 +1,3 @@
+```text
+TypeScript does not support this workflow yet.
+```

Documentation/client-snippets/concepts/event-type-migrations/map-values.md

@@ -0,0 +1,3 @@
+```text
+TypeScript does not support this workflow yet.
+```

Documentation/client-snippets/concepts/geospatial/events-and-read-models.md

@@ -0,0 +1,3 @@
+```text
+TypeScript does not support this workflow yet.
+```

Documentation/client-snippets/concepts/geospatial/projection.md

@@ -0,0 +1,3 @@
+```text
+TypeScript does not support this workflow yet.
+```

Documentation/client-snippets/concepts/geospatial/types.md

@@ -0,0 +1,3 @@
+```text
+TypeScript does not support this workflow yet.
+```

Documentation/client-snippets/concepts/subject/implicit-with-attribute.md

@@ -0,0 +1,3 @@
+```text
+TypeScript does not support this workflow yet.
+```

Documentation/client-snippets/concepts/tagging-reactors/mixed-approach.md

@@ -0,0 +1,23 @@
+```typescript
+import { EventContext, eventType, reactor, tag } from '@cratis/chronicle';
+
+@eventType()
+class TaggingReactorsOrderShipped {
+    constructor(readonly phoneNumber: string, readonly trackingNumber: string) {}
+}
+
+interface TaggingReactorsSmsService {
+    sendShippingNotification(phoneNumber: string, trackingNumber: string): Promise<void>;
+}
+
+@reactor()
+@tag('Notifications', 'SMS')
+@tag('Customer')
+class TaggingReactorsSmsNotificationReactor {
+    constructor(private readonly smsService: TaggingReactorsSmsService) {}
+
+    async taggingReactorsOrderShipped(event: TaggingReactorsOrderShipped, _context: EventContext): Promise<void> {
+        await this.smsService.sendShippingNotification(event.phoneNumber, event.trackingNumber);
+    }
+}
+```

Documentation/client-snippets/concepts/tagging-reactors/multiple-tags-multiple-attributes.md

@@ -0,0 +1,24 @@
+```typescript
+import { EventContext, eventType, reactor, tag } from '@cratis/chronicle';
+
+@eventType()
+class TaggingReactorsProductStockChanged {
+    constructor(readonly productId: string, readonly newQuantity: number) {}
+}
+
+interface TaggingReactorsInventoryApi {
+    updateStock(productId: string, newQuantity: number): Promise<void>;
+}
+
+@reactor()
+@tag('Integration')
+@tag('ExternalAPI')
+@tag('Inventory')
+class TaggingReactorsInventorySyncReactor {
+    constructor(private readonly inventoryApi: TaggingReactorsInventoryApi) {}
+
+    async taggingReactorsProductStockChanged(event: TaggingReactorsProductStockChanged, _context: EventContext): Promise<void> {
+        await this.inventoryApi.updateStock(event.productId, event.newQuantity);
+    }
+}
+```

Documentation/client-snippets/concepts/tagging-reactors/multiple-tags-single-attribute.md

@@ -0,0 +1,22 @@
+```typescript
+import { EventContext, eventType, reactor, tag } from '@cratis/chronicle';
+
+@eventType()
+class TaggingReactorsCustomerRegistered {
+    constructor(readonly email: string, readonly name: string) {}
+}
+
+interface TaggingReactorsWelcomeEmailService {
+    sendWelcomeEmail(email: string, name: string): Promise<void>;
+}
+
+@reactor()
+@tag('Notifications', 'Customer', 'Email')
+class TaggingReactorsCustomerNotificationReactor {
+    constructor(private readonly emailService: TaggingReactorsWelcomeEmailService) {}
+
+    async taggingReactorsCustomerRegistered(event: TaggingReactorsCustomerRegistered, _context: EventContext): Promise<void> {
+        await this.emailService.sendWelcomeEmail(event.email, event.name);
+    }
+}
+```

Documentation/client-snippets/concepts/tagging-reactors/single-tag.md

@@ -0,0 +1,22 @@
+```typescript
+import { EventContext, eventType, reactor, tag } from '@cratis/chronicle';
+
+@eventType()
+class TaggingReactorsOrderPlaced {
+    constructor(readonly customerId: string, readonly orderId: string) {}
+}
+
+interface TaggingReactorsEmailService {
+    sendOrderConfirmation(customerId: string, orderId: string): Promise<void>;
+}
+
+@reactor()
+@tag('Notifications')
+class TaggingReactorsOrderConfirmationReactor {
+    constructor(private readonly emailService: TaggingReactorsEmailService) {}
+
+    async taggingReactorsOrderPlaced(event: TaggingReactorsOrderPlaced, _context: EventContext): Promise<void> {
+        await this.emailService.sendOrderConfirmation(event.customerId, event.orderId);
+    }
+}
+```