@cratis/chronicle 3.1.1 → 5.0.0

package/eventSequences/EventSequence.ts

@@ -3,13 +3,16 @@
 
 import { ChronicleConnection } from '../connection';
 import { SpanStatusCode } from '@opentelemetry/api';
-import type { AppendedEvent as ContractsAppendedEvent } from '@cratis/chronicle.contracts';
+import type { AppendedEventResponse as ContractsAppendedEvent } from '@cratis/chronicle.contracts';
 import { Constructor, Guid, JsonSerializer } from '@cratis/fundamentals';
 import { getEventTypeFor } from '../events/eventTypeDecorator';
 import type { AppendedEvent } from '../events/AppendedEvent';
 import { EventType } from '../events/EventType';
 import { EventTypeId } from '../events/EventTypeId';
 import { EventTypeGeneration } from '../events/EventTypeGeneration';
+import { Tag } from '../events/Tag';
+import { getTagsFor } from '../events/tagDecorator';
+import { mergeTags } from '../events/mergeTags';
 import { DecoratorType } from '../types/DecoratorType';
 import { TypeDiscoverer } from '../types/TypeDiscoverer';
 import { toClientFailedPartition } from '../observation/toClientFailedPartition';
@@ -37,6 +40,7 @@ import { identityProvider, Identity } from '../identity';
 import { causationManager, CausationType } from '../auditing';
 import { correlationIdManager } from '../correlation';
 import { fromContractsGuid, toContractsGuid } from '../connection/Guid';
+import { ensureCommandResponse, ensureCommandSuccess, ensureQuerySuccess } from '../connection/callResults';
 import type { ConcurrencyScope } from './ConcurrencyScope';
 import { IUnitOfWorkManager } from '../transactions/IUnitOfWorkManager';
 
@@ -64,7 +68,10 @@ export class EventSequence implements IEventSequence {
         const correlationId = options?.correlationId === undefined
             ? Guid.as(correlationIdManager.current.value)
             : Guid.as(options.correlationId);
-        const content = JsonSerializer.serialize(event);
+        const content = JSON.parse(JsonSerializer.serialize(event));
+
+        // Merge static tags declared on the event type with tags supplied at append time.
+        const tags = mergeTags(getTagsFor(event.constructor as Function), options?.tags);
 
         causationManager.add(CausationType.appendEvent, { eventType: eventType.id.value });
         const causationChain = causationManager.getCurrentChain();
@@ -108,17 +115,18 @@ export class EventSequence implements IEventSequence {
                     })),
                     CausedBy: toContractsCausedBy(identity),
                     ConcurrencyScope: this.toContractConcurrencyScope(options?.concurrencyScope),
-                    Tags: [],
+                    Tags: tags,
                     Occurred: undefined,
                     Subject: eventSourceId
                 });
 
+                const appendResponse = ensureCommandResponse('append event', response);
                 const duration = Date.now() - startTime;
                 const result = this.mapAppendResponse(
-                    response.SequenceNumber,
-                    response.ConstraintViolations ?? [],
-                    response.Errors ?? [],
-                    response.ConcurrencyViolation
+                    appendResponse.SequenceNumber,
+                    appendResponse.ConstraintViolations ?? [],
+                    appendResponse.Errors ?? [],
+                    appendResponse.ConcurrencyViolation
                 );
                 span.setAttribute('chronicle.sequence_number', result.sequenceNumber.value.toString());
                 span.setStatus({ code: SpanStatusCode.OK });
@@ -149,7 +157,8 @@ export class EventSequence implements IEventSequence {
                                 eventType,
                                 occurred: new Date(),
                                 correlationId: correlationId.toString(),
-                                causation: causationChain.map(c => ({ type: c.type.name, properties: { ...c.properties } }))
+                                causation: causationChain.map(c => ({ type: c.type.name, properties: { ...c.properties } })),
+                                tags: tags.map(value => new Tag(value))
                             },
                             eventType,
                             content: event as Record<string, unknown>
@@ -223,8 +232,13 @@ export class EventSequence implements IEventSequence {
         const resolveConcurrencyScope = (eventSourceId: string) =>
             this.toContractConcurrencyScope(concurrencyScopesByEventSourceId?.[eventSourceId] ?? defaultConcurrencyScope);
 
-        const eventsToAppend = eventsForEventSourceIds.map(({ eventSourceId, event, eventStreamType, eventStreamId, eventSourceType, subject }) => {
+        const eventsToAppend = eventsForEventSourceIds.map(({ eventSourceId, event, eventStreamType, eventStreamId, eventSourceType, subject, tags: instanceTags }) => {
             const eventType = getEventTypeFor(event.constructor as Function);
+
+            // Merge static tags declared on the event type, tags carried by this specific
+            // EventForEventSourceId entry, and tags supplied at call time for the whole batch.
+            const tags = mergeTags(getTagsFor(event.constructor as Function), instanceTags, appendOptions?.tags);
+
             return {
                 EventSourceType: eventSourceType ?? 'Default',
                 EventSourceId: eventSourceId,
@@ -235,14 +249,8 @@ export class EventSequence implements IEventSequence {
                     Generation: eventType.generation.value,
                     Tombstone: eventType.tombstone
                 },
-                Content: JsonSerializer.serialize(event),
-                Causation: batchCausationChain.map(c => ({
-                    Occurred: { Value: c.occurred.toISOString() },
-                    Type: c.type.name,
-                    Properties: { ...c.properties }
-                })),
-                CausedBy: toContractsCausedBy(identity),
-                Tags: [],
+                Content: JSON.parse(JsonSerializer.serialize(event)),
+                Tags: tags,
                 Occurred: undefined,
                 Subject: subject ?? eventSourceId
             };
@@ -267,7 +275,7 @@ export class EventSequence implements IEventSequence {
             span.setAttribute('chronicle.events_count', eventsForEventSourceIds.length);
             const startTime = Date.now();
             try {
-                const response = await this._connection.eventSequences.appendMany({
+                const response = await this._connection.eventSequences.appendManyForEventSources({
                     EventStore: this._eventStoreName,
                     Namespace: this._namespace,
                     EventSequenceId: this.id.value,
@@ -279,21 +287,23 @@ export class EventSequence implements IEventSequence {
                         Properties: { ...c.properties }
                     })),
                     CausedBy: toContractsCausedBy(identity),
-                    ConcurrencyScopes: {
-                        ...Object.fromEntries(distinctEventSourceIds.map(eventSourceId => [eventSourceId, resolveConcurrencyScope(eventSourceId)]))
-                    }
+                    ConcurrencyScopes: distinctEventSourceIds.map(eventSourceId => ({
+                        EventSourceId: eventSourceId,
+                        Scope: resolveConcurrencyScope(eventSourceId)
+                    }))
                 });
 
+                const appendManyResponse = ensureCommandResponse('append many events', response);
                 const duration = Date.now() - startTime;
                 // Mirrors the C# client: every per-event AppendResult in a batch carries all
                 // constraint violations and the first concurrency violation of the whole batch —
                 // the wire response doesn't correlate either back to a specific event index.
-                const firstConcurrencyViolation = (response.ConcurrencyViolations ?? [])[0];
-                const result = (response.SequenceNumbers ?? []).map((sequenceNumber: bigint, index: number) =>
+                const firstConcurrencyViolation = (appendManyResponse.ConcurrencyViolations ?? [])[0];
+                const result = (appendManyResponse.SequenceNumbers ?? []).map((sequenceNumber: bigint, index: number) =>
                     this.mapAppendResponse(
                         sequenceNumber,
-                        response.ConstraintViolations ?? [],
-                        (response.Errors ?? []).filter((_: string, errorIndex: number) => errorIndex === index),
+                        appendManyResponse.ConstraintViolations ?? [],
+                        (appendManyResponse.Errors ?? []).filter((_: string, errorIndex: number) => errorIndex === index),
                         firstConcurrencyViolation
                     )
                 );
@@ -334,7 +344,8 @@ export class EventSequence implements IEventSequence {
                                     eventType,
                                     occurred: occurredAt,
                                     correlationId: correlationId.toString(),
-                                    causation: causationEntries
+                                    causation: causationEntries,
+                                    tags: eventsToAppend[index].Tags.map(value => new Tag(value))
                                 },
                                 eventType,
                                 content: event as Record<string, unknown>
@@ -385,18 +396,19 @@ export class EventSequence implements IEventSequence {
                 span.setAttribute('chronicle.event_source_id', eventSourceId);
             }
             try {
-                const response = await this._connection.eventSequences.getTailSequenceNumber({
+                const response = await this._connection.eventSequences.tailSequenceNumber({
                     EventStore: this._eventStoreName,
                     Namespace: this._namespace,
                     EventSequenceId: this.id.value,
                     EventSourceId: eventSourceId ?? '',
-                    EventTypes: this.toContractEventTypes(filterEventTypes ?? []),
+                    EventTypeIds: this.joinEventTypeIds(filterEventTypes ?? []),
                     EventSourceType: eventSourceType ?? 'Default',
                     EventStreamId: eventStreamId ?? '',
                     EventStreamType: eventStreamType ?? 'Default'
                 });
 
-                const result = new EventSequenceNumber(response.SequenceNumber ?? 0n);
+                const data = ensureQuerySuccess('get tail sequence number', response);
+                const result = new EventSequenceNumber(data?.SequenceNumber ?? 0n);
                 span.setAttribute('chronicle.sequence_number', result.value.toString());
                 span.setStatus({ code: SpanStatusCode.OK });
                 return result;
@@ -431,7 +443,7 @@ export class EventSequence implements IEventSequence {
                     EventSourceId: eventSourceId
                 });
 
-                const result = response.HasEvents ?? false;
+                const result = ensureQuerySuccess('has events for event source', response)?.HasEvents ?? false;
                 span.setAttribute('chronicle.has_events', result);
                 span.setStatus({ code: SpanStatusCode.OK });
                 return result;
@@ -451,7 +463,8 @@ export class EventSequence implements IEventSequence {
         eventTypes: Constructor[],
         eventStreamType?: string,
         eventStreamId?: string,
-        eventSourceType?: string
+        // Kept for IEventSequence signature compatibility; the wire no longer carries an event source type for this query.
+        _eventSourceType?: string
     ): Promise<AppendedEvent[]> {
         return ChronicleTracer.startActiveSpan('chronicle.event_sequences.get_for_event_source_id_and_event_types', async span => {
             span.setAttribute('chronicle.event_store', this._eventStoreName);
@@ -459,18 +472,17 @@ export class EventSequence implements IEventSequence {
             span.setAttribute('chronicle.event_sequence_id', this.id.value);
             span.setAttribute('chronicle.event_source_id', eventSourceId);
             try {
-                const response = await this._connection.eventSequences.getForEventSourceIdAndEventTypes({
+                const response = await this._connection.eventSequences.forEventSourceIdAndEventTypes({
                     EventStore: this._eventStoreName,
                     Namespace: this._namespace,
                     EventSequenceId: this.id.value,
-                    EventSourceType: eventSourceType ?? 'Default',
                     EventSourceId: eventSourceId,
                     EventStreamType: eventStreamType ?? 'Default',
                     EventStreamId: eventStreamId ?? '',
-                    EventTypes: this.toContractEventTypes(eventTypes)
+                    EventTypeIds: this.joinEventTypeIds(eventTypes)
                 });
 
-                const result = (response.Events ?? []).map(event => this.toClientAppendedEvent(event));
+                const result = ensureQuerySuccess('get events for event source id and event types', response).map(event => this.toClientAppendedEvent(event));
                 span.setStatus({ code: SpanStatusCode.OK });
                 return result;
             } catch (error) {
@@ -495,17 +507,16 @@ export class EventSequence implements IEventSequence {
             span.setAttribute('chronicle.event_sequence_id', this.id.value);
             span.setAttribute('chronicle.sequence_number', sequenceNumber.value.toString());
             try {
-                const response = await this._connection.eventSequences.getEventsFromEventSequenceNumber({
+                const response = await this._connection.eventSequences.fromSequenceNumber({
                     EventStore: this._eventStoreName,
                     Namespace: this._namespace,
                     EventSequenceId: this.id.value,
                     FromEventSequenceNumber: sequenceNumber.value,
-                    ToEventSequenceNumber: 0n,
                     EventSourceId: eventSourceId ?? '',
-                    EventTypes: this.toContractEventTypes(filterEventTypes ?? [])
+                    EventTypeIds: this.joinEventTypeIds(filterEventTypes ?? [])
                 });
 
-                const result = (response.Events ?? []).map(event => this.toClientAppendedEvent(event));
+                const result = ensureQuerySuccess('get events from sequence number', response).map(event => this.toClientAppendedEvent(event));
                 span.setStatus({ code: SpanStatusCode.OK });
                 return result;
             } catch (error) {
@@ -523,7 +534,6 @@ export class EventSequence implements IEventSequence {
         causationManager.add(CausationType.redact, { sequenceNumber: sequenceNumber.value.toString() });
         const causationChain = causationManager.getCurrentChain();
         const identity = identityProvider.getCurrent();
-        const correlationId = Guid.as(correlationIdManager.current.value);
 
         return ChronicleTracer.startActiveSpan('chronicle.event_sequences.redact', async span => {
             span.setAttribute('chronicle.event_store', this._eventStoreName);
@@ -531,20 +541,19 @@ export class EventSequence implements IEventSequence {
             span.setAttribute('chronicle.event_sequence_id', this.id.value);
             span.setAttribute('chronicle.sequence_number', sequenceNumber.value.toString());
             try {
-                await this._connection.eventSequences.redact({
+                ensureCommandSuccess('redact event', await this._connection.eventSequences.redact({
                     EventStore: this._eventStoreName,
                     Namespace: this._namespace,
                     EventSequenceId: this.id.value,
                     SequenceNumber: sequenceNumber.value,
                     Reason: reason,
-                    CorrelationId: toContractsGuid(correlationId),
                     Causation: causationChain.map(c => ({
                         Occurred: { Value: c.occurred.toISOString() },
                         Type: c.type.name,
                         Properties: { ...c.properties }
                     })),
                     CausedBy: toContractsCausedBy(identity)
-                });
+                }));
                 span.setStatus({ code: SpanStatusCode.OK });
             } catch (error) {
                 span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
@@ -561,15 +570,7 @@ export class EventSequence implements IEventSequence {
         causationManager.add(CausationType.redactForEventSource, { eventSourceId });
         const causationChain = causationManager.getCurrentChain();
         const identity = identityProvider.getCurrent();
-        const correlationId = Guid.as(correlationIdManager.current.value);
-        const wireEventTypes = (eventTypes ?? []).map(constructor => {
-            const eventType = getEventTypeFor(constructor as unknown as Function);
-            return {
-                Id: eventType.id.value,
-                Generation: eventType.generation.value,
-                Tombstone: eventType.tombstone
-            };
-        });
+        const wireEventTypeIds = (eventTypes ?? []).map(constructor => getEventTypeFor(constructor as unknown as Function).id.value);
 
         return ChronicleTracer.startActiveSpan('chronicle.event_sequences.redact_for_event_source', async span => {
             span.setAttribute('chronicle.event_store', this._eventStoreName);
@@ -577,21 +578,20 @@ export class EventSequence implements IEventSequence {
             span.setAttribute('chronicle.event_sequence_id', this.id.value);
             span.setAttribute('chronicle.event_source_id', eventSourceId);
             try {
-                await this._connection.eventSequences.redactForEventSource({
+                ensureCommandSuccess('redact event source', await this._connection.eventSequences.redactForEventSource({
                     EventStore: this._eventStoreName,
                     Namespace: this._namespace,
                     EventSequenceId: this.id.value,
                     EventSourceId: eventSourceId,
                     Reason: reason,
-                    EventTypes: wireEventTypes,
-                    CorrelationId: toContractsGuid(correlationId),
+                    EventTypes: wireEventTypeIds,
                     Causation: causationChain.map(c => ({
                         Occurred: { Value: c.occurred.toISOString() },
                         Type: c.type.name,
                         Properties: { ...c.properties }
                     })),
                     CausedBy: toContractsCausedBy(identity)
-                });
+                }));
                 span.setStatus({ code: SpanStatusCode.OK });
             } catch (error) {
                 span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
@@ -636,9 +636,10 @@ export class EventSequence implements IEventSequence {
                     EventStreamId: eventStreamId
                 });
 
-                const result: CompleteStreamResult = response.IsSuccess
-                    ? { isSuccess: true, sequenceNumber: new EventSequenceNumber(response.SequenceNumber ?? 0n) }
-                    : { isSuccess: false, error: this.toClientCompleteStreamError(response.Error) };
+                const completeStreamResponse = ensureCommandResponse('complete stream', response);
+                const result: CompleteStreamResult = completeStreamResponse.IsSuccess
+                    ? { isSuccess: true, sequenceNumber: new EventSequenceNumber(completeStreamResponse.SequenceNumber ?? 0n) }
+                    : { isSuccess: false, error: this.toClientCompleteStreamError(completeStreamResponse.Error) };
 
                 span.setStatus({ code: SpanStatusCode.OK });
                 return result;
@@ -658,15 +659,8 @@ export class EventSequence implements IEventSequence {
         return error === 1 ? CompleteStreamError.DefaultStreamCannotBeCompleted : CompleteStreamError.AlreadyCompleted;
     }
 
-    private toContractEventTypes(eventTypes: Constructor[]) {
-        return eventTypes.map(constructor => {
-            const eventType = getEventTypeFor(constructor as unknown as Function);
-            return {
-                Id: eventType.id.value,
-                Generation: eventType.generation.value,
-                Tombstone: eventType.tombstone
-            };
-        });
+    private joinEventTypeIds(eventTypes: Constructor[]): string {
+        return eventTypes.map(constructor => getEventTypeFor(constructor as unknown as Function).id.value).join(',');
     }
 
     private toClientAppendedEvent(wireEvent: ContractsAppendedEvent): AppendedEvent {
@@ -687,7 +681,8 @@ export class EventSequence implements IEventSequence {
                 causation: (context.Causation ?? []).map(c => ({
                     type: c.Type,
                     properties: { ...c.Properties }
-                }))
+                })),
+                tags: (context.Tags ?? []).map(value => new Tag(value))
             },
             eventType,
             content: JSON.parse(wireEvent.Content) as Record<string, unknown>

package/events/EventContext.ts

@@ -3,6 +3,7 @@
 
 import { EventType } from './EventType';
 import { CausationEntry } from './CausationEntry';
+import { Tag } from './Tag';
 
 /**
  * Represents contextual information about an appended event.
@@ -25,4 +26,7 @@ export interface EventContext {
 
     /** The causation chain for the event. */
     readonly causation: ReadonlyArray<CausationEntry>;
+
+    /** The tags the event carries. */
+    readonly tags: ReadonlyArray<Tag>;
 }

package/events/EventTypes.ts

@@ -4,6 +4,7 @@
 import { Constructor } from '@cratis/fundamentals';
 import { IClientArtifactsProvider } from '../artifacts';
 import { ChronicleConnection } from '../connection';
+import { ensureCommandSuccess } from '../connection/callResults';
 import { EventTypeId } from './EventTypeId';
 import { IEventTypes } from './IEventTypes';
 import { getEventTypeMetadata, getEventTypeJsonSchemaFor } from './eventTypeDecorator';
@@ -163,11 +164,11 @@ export class EventTypes implements IEventTypes {
             return;
         }
 
-        await this._connection.eventTypes.register({
+        ensureCommandSuccess('register event types', await this._connection.eventTypes.registerEventTypes({
             EventStore: this._eventStore,
             Types: registrations,
             DisableValidation: false
-        });
+        }));
     }
 
     /** @inheritdoc */

package/events/Tag.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents a tag associated with an event, observer, or read model.
+ */
+export class Tag {
+    constructor(readonly value: string) {}
+
+    /** @inheritdoc */
+    toString(): string {
+        return this.value;
+    }
+}

package/events/filterEventsByTagDecorator.ts

@@ -0,0 +1,51 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { Tag } from './Tag';
+import { mergeTags } from './mergeTags';
+
+/** Metadata key used to store the tags a reactor or reducer filters events by. */
+const FILTER_TAGS_METADATA_KEY = 'chronicle:filterEventsByTag';
+
+/**
+ * TypeScript decorator that restricts a reactor or reducer so that it only handles events
+ * that carry a specific tag. This is the TypeScript equivalent of the C# `[FilterEventsByTag]`
+ * attribute.
+ *
+ * Apply this decorator to a `@reactor()` or `@reducer()`-decorated class to filter the observed
+ * event stream to events tagged with the given value. Use {@link tag}/{@link tags} when the
+ * intent is to *label* an observer for discoverability; use this decorator when the intent is
+ * to *filter* which events reach it. Applying the decorator more than once accumulates filter
+ * tags - a class handles events carrying any of the applied tags.
+ *
+ * @param value - The tag value that an event must carry in order to be dispatched to the observer.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```typescript
+ * @reactor()
+ * @filterEventsByTag('vip')
+ * class VipWelcomeReactor {
+ *     async customerRegistered(event: CustomerRegistered): Promise<void> {
+ *         console.log(`Welcome VIP customer ${event.emailAddress}`);
+ *     }
+ * }
+ * ```
+ */
+export function filterEventsByTag(value: string): ClassDecorator {
+    return (target: object) => {
+        const existing = (Reflect.getMetadata(FILTER_TAGS_METADATA_KEY, target) as Tag[] | undefined) ?? [];
+        const merged = mergeTags(existing, [value]).map(tagValue => new Tag(tagValue));
+        Reflect.defineMetadata(FILTER_TAGS_METADATA_KEY, merged, target);
+    };
+}
+
+/**
+ * Gets all filter tags applied to a class via {@link filterEventsByTag}.
+ * @param target - The class constructor to retrieve filter tags for.
+ * @returns The filter tags applied to the class, or an empty array if none are.
+ */
+export function getFilterTagsFor(target: Function): Tag[] {
+    return (Reflect.getMetadata(FILTER_TAGS_METADATA_KEY, target) as Tag[] | undefined) ?? [];
+}

package/events/index.ts

@@ -11,5 +11,9 @@ export type { CausationEntry } from './CausationEntry';
 export type { AppendedEvent } from './AppendedEvent';
 export type { IEventTypes } from './IEventTypes';
 export { EventTypes } from './EventTypes';
+export { Tag } from './Tag';
+export { tag, tags, getTagsFor } from './tagDecorator';
+export { filterEventsByTag, getFilterTagsFor } from './filterEventsByTagDecorator';
+export { mergeTags } from './mergeTags';
 export * from './constraints';
 export * from './migrations';

package/events/mergeTags.spec.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import { Tag } from './Tag';
+import { mergeTags } from './mergeTags';
+
+describe('mergeTags', () => {
+    describe('when merging a single source of strings', () => {
+        it('should return the values unchanged', () => {
+            expect(mergeTags(['a', 'b'])).toEqual(['a', 'b']);
+        });
+    });
+
+    describe('when merging several sources', () => {
+        it('should combine them in order', () => {
+            expect(mergeTags(['a'], ['b'], ['c'])).toEqual(['a', 'b', 'c']);
+        });
+    });
+
+    describe('when the same value appears in more than one source', () => {
+        it('should keep only the first occurrence', () => {
+            expect(mergeTags(['a', 'b'], ['b', 'c'])).toEqual(['a', 'b', 'c']);
+        });
+    });
+
+    describe('when a source holds Tag instances', () => {
+        it('should unwrap them to their values', () => {
+            expect(mergeTags([new Tag('a')], ['b'])).toEqual(['a', 'b']);
+        });
+    });
+
+    describe('when a source is undefined', () => {
+        it('should skip it', () => {
+            expect(mergeTags(['a'], undefined, ['b'])).toEqual(['a', 'b']);
+        });
+    });
+
+    describe('when a value is blank', () => {
+        it('should drop it, so an empty tag never reaches the wire', () => {
+            expect(mergeTags(['a', '', '   '])).toEqual(['a']);
+        });
+    });
+
+    describe('when there are no sources at all', () => {
+        it('should return an empty list', () => {
+            expect(mergeTags()).toEqual([]);
+        });
+    });
+});

package/events/mergeTags.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Tag } from './Tag';
+
+/**
+ * Merges one or more sources of tags - static tags declared on a type, tags carried by an
+ * individual event instance, and tags supplied at call time - into a single, distinct list of
+ * tag values. Mirrors the .NET client, which merges static, instance, and dynamic tags the
+ * same way before sending an append request.
+ * @param sources - The tag sources to merge. Each may be a mix of strings and {@link Tag} instances,
+ * or undefined when that source contributed no tags.
+ * @returns The distinct, merged tag values.
+ */
+export function mergeTags(...sources: ReadonlyArray<Iterable<string | Tag> | undefined>): string[] {
+    const values = new Set<string>();
+    for (const source of sources) {
+        if (!source) continue;
+        for (const entry of source) {
+            const value = typeof entry === 'string' ? entry : entry.value;
+            if (value.trim().length > 0) {
+                values.add(value);
+            }
+        }
+    }
+    return [...values];
+}

package/events/tagDecorator.spec.ts

@@ -0,0 +1,115 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import { getTagsFor, tag, tags } from './tagDecorator';
+import { filterEventsByTag, getFilterTagsFor } from './filterEventsByTagDecorator';
+
+describe('tag', () => {
+    describe('when a class carries no tags', () => {
+        class Untagged {}
+
+        it('should report no tags', () => {
+            expect(getTagsFor(Untagged)).toEqual([]);
+        });
+    });
+
+    describe('when decorating a class with a single tag', () => {
+        class SingleTagged {}
+        tag('analytics')(SingleTagged);
+
+        it('should carry that tag', () => {
+            expect(getTagsFor(SingleTagged).map(_ => _.value)).toEqual(['analytics']);
+        });
+    });
+
+    describe('when decorating a class with several tags at once', () => {
+        class MultiTagged {}
+        tag('analytics', 'user-action')(MultiTagged);
+
+        it('should carry every tag', () => {
+            expect(getTagsFor(MultiTagged).map(_ => _.value)).toEqual(['analytics', 'user-action']);
+        });
+    });
+
+    describe('when applying the decorator more than once', () => {
+        class Accumulated {}
+        tag('first')(Accumulated);
+        tag('second')(Accumulated);
+
+        it('should accumulate rather than replace', () => {
+            expect(getTagsFor(Accumulated).map(_ => _.value)).toEqual(['first', 'second']);
+        });
+    });
+
+    describe('when the same tag is applied twice', () => {
+        class Duplicated {}
+        tag('same')(Duplicated);
+        tag('same')(Duplicated);
+
+        it('should keep it once', () => {
+            expect(getTagsFor(Duplicated).map(_ => _.value)).toEqual(['same']);
+        });
+    });
+
+    describe('when using the plural tags decorator', () => {
+        class PluralTagged {}
+        tags('a', 'b')(PluralTagged);
+
+        it('should behave identically to tag', () => {
+            expect(getTagsFor(PluralTagged).map(_ => _.value)).toEqual(['a', 'b']);
+        });
+    });
+
+    describe('when two classes are tagged separately', () => {
+        class FirstTagged {}
+        class SecondTagged {}
+        tag('one')(FirstTagged);
+        tag('two')(SecondTagged);
+
+        it('should not leak tags between them', () => {
+            expect(getTagsFor(FirstTagged).map(_ => _.value)).toEqual(['one']);
+            expect(getTagsFor(SecondTagged).map(_ => _.value)).toEqual(['two']);
+        });
+    });
+});
+
+describe('filterEventsByTag', () => {
+    describe('when a class carries no filter', () => {
+        class Unfiltered {}
+
+        it('should report no filter tags', () => {
+            expect(getFilterTagsFor(Unfiltered)).toEqual([]);
+        });
+    });
+
+    describe('when decorating a class with a filter tag', () => {
+        class Filtered {}
+        filterEventsByTag('vip')(Filtered);
+
+        it('should carry that filter tag', () => {
+            expect(getFilterTagsFor(Filtered).map(_ => _.value)).toEqual(['vip']);
+        });
+    });
+
+    describe('when applying the decorator more than once', () => {
+        class MultiFiltered {}
+        filterEventsByTag('vip')(MultiFiltered);
+        filterEventsByTag('premium')(MultiFiltered);
+
+        it('should accumulate, so the observer handles events carrying any of them', () => {
+            expect(getFilterTagsFor(MultiFiltered).map(_ => _.value)).toEqual(['vip', 'premium']);
+        });
+    });
+
+    describe('when a class is both labeled and filtered', () => {
+        class LabeledAndFiltered {}
+        tag('reporting')(LabeledAndFiltered);
+        filterEventsByTag('vip')(LabeledAndFiltered);
+
+        it('should keep labeling and filtering separate', () => {
+            expect(getTagsFor(LabeledAndFiltered).map(_ => _.value)).toEqual(['reporting']);
+            expect(getFilterTagsFor(LabeledAndFiltered).map(_ => _.value)).toEqual(['vip']);
+        });
+    });
+});