@cratis/chronicle 6.49.0 → 6.51.0

package/events/NamedTag.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InvalidNamedTag } from './InvalidNamedTag.js';
+
+// Matches .NET string.IsNullOrWhiteSpace, which also treats U+0085 and other Unicode white space as blank.
+const blank = /^\p{White_Space}*$/u;
+
+/**
+ * Associates a name with an exact, opaque event tag value. Names and values are compared exactly
+ * (ordinal and case-sensitive); one name may carry several values on the same event.
+ * Mirrors the .NET client's `NamedTag`.
+ */
+export class NamedTag {
+    /** The name of the tag. Never blank. */
+    readonly name: string;
+
+    /** The exact, opaque value of the tag. May be empty. */
+    readonly value: string;
+
+    /**
+     * Initializes a new instance of {@link NamedTag}.
+     * @param name - The name. Must be a nonblank string.
+     * @param value - The opaque value. Must be a string; the empty string is allowed.
+     * @throws {@link InvalidNamedTag} when the name is blank or not a string, or the value is not a string.
+     */
+    constructor(name: string, value: string) {
+        if (typeof name !== 'string' || blank.test(name) || typeof value !== 'string') {
+            throw new InvalidNamedTag();
+        }
+        this.name = name;
+        this.value = value;
+        Object.freeze(this);
+    }
+
+    /**
+     * Determines whether this tag has the same name and value as another, compared exactly.
+     * @param other - The tag to compare with.
+     * @returns True when both name and value are equal.
+     */
+    equals(other: NamedTag): boolean {
+        return other instanceof NamedTag && other.name === this.name && other.value === this.value;
+    }
+}

package/events/constraints/ConstraintBuilder.ts

@@ -2,6 +2,8 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { getEventTypeFor } from '../eventTypeDecorator.js';
+import { EventSequenceId } from '../../eventSequences/EventSequenceId.js';
+import { ConstraintEventSequence, normalizeConstraintEventSequences } from './ConstraintEventSequences.js';
 import { IConstraintBuilder } from './IConstraintBuilder.js';
 import { IUniqueConstraintBuilder } from './IUniqueConstraintBuilder.js';
 import { UniqueConstraintBuilder, UniqueConstraintCapture } from './UniqueConstraintBuilder.js';
@@ -28,6 +30,8 @@ export interface ConstraintCapture {
     scope: ConstraintScopeCapture;
     uniqueConstraint?: UniqueConstraintCapture;
     uniqueEventType?: UniqueEventTypeCapture;
+    /** Identifiers of the event sequences the constraint applies to; empty or omitted means every event sequence. */
+    eventSequences?: string[];
 }
 
 /**
@@ -63,6 +67,18 @@ export class ConstraintBuilder implements IConstraintBuilder {
         return this;
     }
 
+    /** @inheritdoc */
+    forEventSequences(...eventSequenceIds: ConstraintEventSequence[]): IConstraintBuilder {
+        const eventSequences = normalizeConstraintEventSequences([...(this.capture.eventSequences ?? []), ...eventSequenceIds]);
+        if (eventSequences.length > 0) this.capture.eventSequences = eventSequences;
+        return this;
+    }
+
+    /** @inheritdoc */
+    forEventLog(): IConstraintBuilder {
+        return this.forEventSequences(EventSequenceId.eventLog);
+    }
+
     /** @inheritdoc */
     unique(callback: (builder: IUniqueConstraintBuilder) => void): IConstraintBuilder {
         const uniqueCapture: UniqueConstraintCapture = {

package/events/constraints/ConstraintEventSequences.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EventSequenceId } from '../../eventSequences/EventSequenceId.js';
+
+/** An event sequence a constraint can be scoped to, by identifier or by its string value. */
+export type ConstraintEventSequence = EventSequenceId | string;
+
+/**
+ * Normalizes declared event sequences to distinct, nonblank identifier values in declaration order.
+ * @param eventSequences - The declared event sequences.
+ * @returns The normalized identifier values.
+ */
+export function normalizeConstraintEventSequences(eventSequences: readonly ConstraintEventSequence[]): string[] {
+    const values: string[] = [];
+    for (const eventSequence of eventSequences) {
+        const value = eventSequence instanceof EventSequenceId ? eventSequence.value : eventSequence;
+        if (typeof value !== 'string' || value.trim().length === 0 || values.includes(value)) continue;
+        values.push(value);
+    }
+    return values;
+}
+
+/**
+ * Combines the event sequences declared for one constraint in more than one place.
+ * An empty declaration means every event sequence and wins: combining never narrows a constraint that
+ * one declaration applies everywhere. Otherwise the result is the distinct union in declaration order.
+ * Mirrors ConstraintEventSequences.Combine in the .NET client.
+ * @param declarations - The declarations to combine; undefined or empty means every event sequence.
+ * @returns The combined declaration, empty for every event sequence.
+ */
+export function combineConstraintEventSequences(declarations: ReadonlyArray<readonly string[] | undefined>): string[] {
+    if (declarations.length === 0 || declarations.some(declaration => !declaration || declaration.length === 0)) return [];
+    const combined: string[] = [];
+    for (const declaration of declarations) {
+        for (const value of declaration!) {
+            if (!combined.includes(value)) combined.push(value);
+        }
+    }
+    return combined;
+}

package/events/constraints/Constraints.ts

@@ -15,12 +15,20 @@ import { getUniqueEventMetadata, getUniquePropertyMetadata } from './unique.js';
 import { getRemovedConstraintNames } from './removeConstraint.js';
 import { TypeIntrospector } from '../../types/TypeIntrospector.js';
 import { getEventTypeFor } from '../eventTypeDecorator.js';
+import { combineConstraintEventSequences } from './ConstraintEventSequences.js';
 
 /** Resolves the name registered with the Chronicle Kernel. */
 function wireNameOf(capture: ConstraintCapture): string {
     return capture.uniqueEventType?.name ?? capture.name;
 }
 
+/** Combine another declaration's event sequences into a capture; an empty result means every event sequence. */
+function combineEventSequencesInto(capture: ConstraintCapture, declared: readonly string[] | undefined): void {
+    const combined = combineConstraintEventSequences([capture.eventSequences, declared]);
+    if (combined.length > 0) capture.eventSequences = combined;
+    else delete capture.eventSequences;
+}
+
 const decoratorScope: ConstraintScopeCapture = {
     perEventSourceType: false,
     perEventStreamType: false,
@@ -63,6 +71,7 @@ export function compileConstraints(provider: Pick<IClientArtifactsProvider, 'eve
                 for (const id of capture.uniqueEventType.removedWithEventTypeIds ?? []) {
                     if (!removedWith.includes(id)) removedWith.push(id);
                 }
+                combineEventSequencesInto(existing, capture.eventSequences);
             } else if (existing) {
                 throw new Error(`Duplicate constraint name '${name}'.`);
             } else {
@@ -87,12 +96,14 @@ export function compileConstraints(provider: Pick<IClientArtifactsProvider, 'eve
                 if (!capture) {
                     const builder = new ConstraintBuilder(name);
                     builder.uniqueFor(eventType, eventMetadata.message, name);
+                    builder.forEventSequences(...(eventMetadata.eventSequences ?? []));
                     capture = builder.capture;
                     captures.set(name, capture);
                 } else if (!capture.uniqueEventType) {
                     throw new Error(`Constraint '${name}' is not a unique event type constraint.`);
                 } else {
                     assertMatchingScope(name, capture.scope, decoratorScope);
+                    combineEventSequencesInto(capture, eventMetadata.eventSequences);
                     if (eventMetadata.message && !capture.uniqueEventType.message) capture.uniqueEventType.message = eventMetadata.message;
                     capture.uniqueEventType.eventTypeIds ??= [capture.uniqueEventType.eventTypeId];
                     const id = getEventTypeFor(eventType).id.value;
@@ -108,8 +119,11 @@ export function compileConstraints(provider: Pick<IClientArtifactsProvider, 'eve
                 if (!capture) {
                     const builder = new ConstraintBuilder(name);
                     builder.unique(() => {});
+                    builder.forEventSequences(...(metadata.eventSequences ?? []));
                     capture = builder.capture;
                     captures.set(name, capture);
+                } else {
+                    combineEventSequencesInto(capture, metadata.eventSequences);
                 }
                 if (!capture.uniqueConstraint) throw new Error(`Constraint '${name}' is not a unique property constraint.`);
                 assertMatchingScope(name, capture.scope, decoratorScope);
@@ -188,6 +202,8 @@ export class Constraints implements IConstraints {
                 EventStreamType: capture.scope.perEventStreamType ? '*' : '',
                 EventStreamId: capture.scope.perEventStreamId ? '*' : ''
             };
+            // Empty means every event sequence, which is what the Kernel assumes when the field is omitted.
+            const eventSequences = [...new Set(capture.eventSequences ?? [])];
 
             if (capture.uniqueConstraint) {
                 const uc = capture.uniqueConstraint;
@@ -210,7 +226,8 @@ export class Constraints implements IConstraints {
                         },
                         Value1: undefined
                     },
-                    Scope: scope
+                    Scope: scope,
+                    EventSequences: eventSequences
                 };
             }
 
@@ -226,7 +243,8 @@ export class Constraints implements IConstraints {
                             EventTypeIds: uet.eventTypeIds ?? [uet.eventTypeId]
                         }
                     },
-                    Scope: scope
+                    Scope: scope,
+                    EventSequences: eventSequences
                 };
             }
 
@@ -235,7 +253,8 @@ export class Constraints implements IConstraints {
                 Type: ConstraintType.Unknown,
                 RemovedWith: [],
                 Definition: undefined,
-                Scope: scope
+                Scope: scope,
+                EventSequences: eventSequences
             };
         });
 

package/events/constraints/IConstraintBuilder.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { ConstraintEventSequence } from './ConstraintEventSequences.js';
 import { IUniqueConstraintBuilder } from './IUniqueConstraintBuilder.js';
 
 /**
@@ -26,6 +27,25 @@ export interface IConstraintBuilder {
      */
     perEventStreamId(): IConstraintBuilder;
 
+    /**
+     * Applies the constraints defined on this builder only to specific event sequences.
+     * By default a constraint applies to every event sequence its event types are appended to, and each
+     * sequence keeps its own index. The Kernel neither validates nor indexes a constraint for a sequence it does
+     * not apply to, so a fact forwarded to another sequence (such as the outbox) does not claim a value there.
+     * It applies to every constraint on this builder wherever in the chain it is called; calling it again adds
+     * to the event sequences already declared.
+     * @param eventSequenceIds - The event sequences the constraints apply to.
+     * @returns This builder for fluent chaining.
+     */
+    forEventSequences(...eventSequenceIds: ConstraintEventSequence[]): IConstraintBuilder;
+
+    /**
+     * Applies the constraints defined on this builder only to the event log.
+     * Shorthand for {@link IConstraintBuilder.forEventSequences} with `EventSequenceId.eventLog`.
+     * @returns This builder for fluent chaining.
+     */
+    forEventLog(): IConstraintBuilder;
+
     /**
      * Starts building a unique constraint using a fluent builder callback.
      * @param callback - Callback that configures the unique constraint via {@link IUniqueConstraintBuilder}.

package/events/constraints/UniqueOptions.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ConstraintEventSequence } from './ConstraintEventSequences.js';
+
+/** Options for the {@link unique} decorator. Mirrors the .NET UniqueAttribute. */
+export interface UniqueOptions {
+    /** Optional shared constraint name; defaults to the class or property name. */
+    name?: string;
+
+    /** Optional fixed violation message. */
+    message?: string;
+
+    /**
+     * The event sequences the constraint applies to. Empty or omitted means every event sequence.
+     * When several declarations share a constraint name, their event sequences are combined, and a
+     * declaration naming none keeps the constraint applying to every event sequence.
+     */
+    eventSequences?: ConstraintEventSequence[];
+}

package/events/constraints/for_Constraints/against_a_kernel/when_appending_to_event_sequences_a_constraint_is_scoped_to.integration.spec.ts

@@ -0,0 +1,118 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { randomUUID } from 'node:crypto';
+import { afterAll, beforeAll, chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import { ChronicleClient } from '../../../../ChronicleClient.js';
+import { ChronicleOptions } from '../../../../ChronicleOptions.js';
+import type { IClientArtifactsProvider } from '../../../../artifacts/index.js';
+import { EventSequenceId } from '../../../../eventSequences/EventSequenceId.js';
+import type { IEventSequence } from '../../../../eventSequences/IEventSequence.js';
+import type { IEventStore } from '../../../../IEventStore.js';
+import { eventType } from '../../../eventTypeDecorator.js';
+import { constraint } from '../../constraint.js';
+import type { IConstraint } from '../../IConstraint.js';
+import type { IConstraintBuilder } from '../../IConstraintBuilder.js';
+import { unique } from '../../unique.js';
+
+chai.should();
+
+// Runs against a real Chronicle kernel; skipped locally unless the connection string is set (see vitest.integration.config.ts).
+const connectionString = process.env.CHRONICLE_INTEGRATION_CONNECTION_STRING;
+
+@eventType()
+class HandleClaimed {
+    @field(String) handle = '';
+}
+
+@eventType()
+class NicknameClaimed {
+    @field(String) nickname = '';
+}
+
+@eventType()
+@unique({ name: 'OneProfilePerUser', eventSequences: [EventSequenceId.eventLog] })
+class ProfileCreated {
+    @field(String) label = '';
+}
+
+@constraint('UniqueHandleOnEventLog')
+class UniqueHandleOnEventLog implements IConstraint {
+    define(builder: IConstraintBuilder): void {
+        builder.forEventLog().unique(_ => _.on(HandleClaimed, e => e.handle));
+    }
+}
+
+@constraint('UniqueNicknameEverywhere')
+class UniqueNicknameEverywhere implements IConstraint {
+    define(builder: IConstraintBuilder): void {
+        builder.unique(_ => _.on(NicknameClaimed, e => e.nickname));
+    }
+}
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [HandleClaimed, NicknameClaimed, ProfileCreated],
+    readModels: [],
+    reactors: [],
+    reducers: [],
+    seeders: [],
+    constraints: [UniqueHandleOnEventLog, UniqueNicknameEverywhere],
+    projections: [],
+    webhooks: [],
+    eventTypeMigrations: [],
+    globalForHandlers: []
+};
+
+const handle = (value: string) => Object.assign(new HandleClaimed(), { handle: value });
+const nickname = (value: string) => Object.assign(new NicknameClaimed(), { nickname: value });
+
+describe.skipIf(!connectionString && !process.env.CI)('when appending to event sequences a constraint is scoped to against a kernel', () => {
+    const storeName = `Sequenced${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+    let client: ChronicleClient;
+    let store: IEventStore;
+    let outbox: IEventSequence;
+
+    beforeAll(async () => {
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+            discoveryPatterns: [],
+            clientArtifactsProvider: artifacts
+        }));
+        store = await client.getEventStore(storeName);
+        outbox = store.getEventSequence(new EventSequenceId('outbox'));
+    });
+
+    afterAll(() => client?.dispose());
+
+    it('validates an event-log constraint on the event log', async () => {
+        (await store.eventLog.append(randomUUID(), handle('ada'))).isSuccess.should.be.true;
+        const rejected = await store.eventLog.append(randomUUID(), handle('ada'));
+        rejected.isSuccess.should.be.false;
+        rejected.constraintViolations[0].constraintId.should.equal('UniqueHandleOnEventLog');
+    });
+
+    it('neither validates nor claims an event-log constraint in the outbox', async () => {
+        (await store.eventLog.append(randomUUID(), handle('grace'))).isSuccess.should.be.true;
+        (await outbox.append(randomUUID(), handle('grace'))).isSuccess.should.be.true;
+        (await outbox.append(randomUUID(), handle('grace'))).isSuccess.should.be.true;
+    });
+
+    it('keeps a forwarded value from claiming the event-log value', async () => {
+        (await outbox.append(randomUUID(), handle('linus'))).isSuccess.should.be.true;
+        (await store.eventLog.append(randomUUID(), handle('linus'))).isSuccess.should.be.true;
+    });
+
+    it('validates a decorated event-log constraint only on the event log', async () => {
+        const source = randomUUID();
+        (await store.eventLog.append(source, new ProfileCreated())).isSuccess.should.be.true;
+        (await store.eventLog.append(source, new ProfileCreated())).isSuccess.should.be.false;
+        (await outbox.append(source, new ProfileCreated())).isSuccess.should.be.true;
+        (await outbox.append(source, new ProfileCreated())).isSuccess.should.be.true;
+    });
+
+    it('validates an unscoped constraint in the outbox against its own index', async () => {
+        (await store.eventLog.append(randomUUID(), nickname('margaret'))).isSuccess.should.be.true;
+        (await outbox.append(randomUUID(), nickname('margaret'))).isSuccess.should.be.true;
+        (await outbox.append(randomUUID(), nickname('margaret'))).isSuccess.should.be.false;
+    });
+});

package/events/constraints/for_Constraints/when_scoping_to_event_sequences/given/registered_constraints.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { vi } from 'vitest';
+import type { Constraint, RegisterConstraintsRequest } from '@cratis/chronicle.contracts';
+import type { IClientArtifactsProvider } from '../../../../../artifacts/index.js';
+import type { ChronicleConnection } from '../../../../../connection/index.js';
+import { Constraints } from '../../../Constraints.js';
+
+/**
+ * Registers the given constraint classes and decorated event types and returns the registered wire definitions by name.
+ * @param constraints - The constraint classes.
+ * @param eventTypes - The event types whose decorators contribute constraints.
+ * @returns The registered constraints keyed by name.
+ */
+export async function registeredConstraints(constraints: Function[], eventTypes: Function[] = []): Promise<Map<string, Constraint>> {
+    const register = vi.fn().mockResolvedValue({});
+    const connection = { constraints: { register } } as unknown as ChronicleConnection;
+    const artifacts = {
+        eventTypes, readModels: [], reactors: [], reducers: [], seeders: [], constraints,
+        projections: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+    } as unknown as IClientArtifactsProvider;
+    await new Constraints('store', connection, artifacts).register();
+    const request = register.mock.calls[0][0] as RegisterConstraintsRequest;
+    return new Map(request.Constraints.map(registered => [registered.Name, registered]));
+}

package/events/constraints/for_Constraints/when_scoping_to_event_sequences/with_fluent_builder.spec.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeAll, chai, describe, it } from 'vitest';
+import type { Constraint } from '@cratis/chronicle.contracts';
+import { EventSequenceId } from '../../../../eventSequences/EventSequenceId.js';
+import { eventType } from '../../../eventTypeDecorator.js';
+import { constraint } from '../../constraint.js';
+import type { IConstraintBuilder } from '../../IConstraintBuilder.js';
+import { registeredConstraints } from './given/registered_constraints.js';
+
+chai.should();
+
+class NameRegistered { name = ''; }
+class OnlyOnce {}
+eventType('name-registered')(NameRegistered);
+eventType('only-once')(OnlyOnce);
+
+class UnscopedName { define(builder: IConstraintBuilder) { builder.unique(unique => unique.on(NameRegistered, event => event.name)); } }
+constraint('unscoped-name')(UnscopedName);
+class EventLogName { define(builder: IConstraintBuilder) { builder.unique(unique => unique.on(NameRegistered, event => event.name)).forEventLog(); } }
+constraint('event-log-name')(EventLogName);
+class SelectedOnce {
+    define(builder: IConstraintBuilder) {
+        builder.forEventSequences(new EventSequenceId('outbox'), 'inbox', ' ', 'outbox')
+            .uniqueFor(OnlyOnce, undefined, 'selected-once')
+            .forEventSequences(EventSequenceId.eventLog);
+    }
+}
+constraint('selected-once-constraint')(SelectedOnce);
+
+describe('when scoping constraints to event sequences with the fluent builder', () => {
+    let registered: Map<string, Constraint>;
+    beforeAll(async () => { registered = await registeredConstraints([UnscopedName, EventLogName, SelectedOnce]); });
+
+    it('should register an unscoped constraint for every event sequence', () => registered.get('unscoped-name')!.EventSequences.should.deep.equal([]));
+    it('should register a constraint declared after the definition for the event log', () => registered.get('event-log-name')!.EventSequences.should.deep.equal(['event-log']));
+    it('should register distinct nonblank event sequences across every call in declaration order', () =>
+        registered.get('selected-once')!.EventSequences.should.deep.equal(['outbox', 'inbox', 'event-log']));
+});

package/events/constraints/for_Constraints/when_scoping_to_event_sequences/with_legacy_decorators.legacy.spec.ts

@@ -0,0 +1,47 @@
+// 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 { field } from '@cratis/fundamentals';
+import { beforeAll, chai, describe, it } from 'vitest';
+import type { Constraint } from '@cratis/chronicle.contracts';
+import { EventSequenceId } from '../../../../eventSequences/EventSequenceId.js';
+import { eventType } from '../../../eventTypeDecorator.js';
+import { unique } from '../../unique.js';
+import { registeredConstraints } from './given/registered_constraints.js';
+
+chai.should();
+
+@eventType('legacy-account-opened')
+@unique({ name: 'legacy-one-account', message: 'Already opened', eventSequences: [EventSequenceId.eventLog] })
+class AccountOpened { @field(String) label = ''; }
+
+@eventType('legacy-account-noted')
+@unique('legacy-unscoped-account')
+class AccountNoted { @field(String) label = ''; }
+
+@eventType('legacy-email-registered')
+class EmailRegistered {
+    @field(String) @unique({ name: 'legacy-email', eventSequences: ['event-log'] }) email = '';
+    @field(String) @unique({ name: 'legacy-alias' }) alias = '';
+}
+
+@eventType('legacy-email-forwarded')
+class EmailForwarded {
+    @field(String) @unique({ name: 'legacy-email', eventSequences: ['outbox'] }) email = '';
+    @field(String) @unique({ name: 'legacy-alias', eventSequences: ['outbox'] }) alias = '';
+}
+
+describe('when scoping legacy unique decorators to event sequences', () => {
+    let registered: Map<string, Constraint>;
+    beforeAll(async () => { registered = await registeredConstraints([], [AccountOpened, AccountNoted, EmailRegistered, EmailForwarded]); });
+
+    it('should register a decorated event type for the declared event sequences', () =>
+        registered.get('legacy-one-account')!.EventSequences.should.deep.equal(['event-log']));
+    it('should register the positional form for every event sequence', () =>
+        registered.get('legacy-unscoped-account')!.EventSequences.should.deep.equal([]));
+    it('should combine the event sequences of properties sharing a constraint name', () =>
+        registered.get('legacy-email')!.EventSequences.should.deep.equal(['event-log', 'outbox']));
+    it('should keep a shared constraint applying everywhere when one property names no event sequence', () =>
+        registered.get('legacy-alias')!.EventSequences.should.deep.equal([]));
+});

package/events/constraints/for_Constraints/when_scoping_to_event_sequences/with_merged_declarations.spec.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeAll, chai, describe, it } from 'vitest';
+import type { Constraint } from '@cratis/chronicle.contracts';
+import { eventType } from '../../../eventTypeDecorator.js';
+import { constraint } from '../../constraint.js';
+import type { IConstraintBuilder } from '../../IConstraintBuilder.js';
+import { registeredConstraints } from './given/registered_constraints.js';
+
+chai.should();
+
+class Opened {}
+class Closed {}
+class Archived {}
+eventType('merge-opened')(Opened);
+eventType('merge-closed')(Closed);
+eventType('merge-archived')(Archived);
+
+class OpenedOnLog { define(builder: IConstraintBuilder) { builder.forEventLog().uniqueFor(Opened, undefined, 'narrowed'); } }
+constraint('opened-on-log')(OpenedOnLog);
+class ClosedOnOutbox { define(builder: IConstraintBuilder) { builder.forEventSequences('outbox').uniqueFor(Closed, undefined, 'narrowed'); } }
+constraint('closed-on-outbox')(ClosedOnOutbox);
+class OpenedEverywhere { define(builder: IConstraintBuilder) { builder.uniqueFor(Opened, undefined, 'widened'); } }
+constraint('opened-everywhere')(OpenedEverywhere);
+class ArchivedOnLog { define(builder: IConstraintBuilder) { builder.forEventLog().uniqueFor(Archived, undefined, 'widened'); } }
+constraint('archived-on-log')(ArchivedOnLog);
+
+describe('when scoping merged unique event type declarations to event sequences', () => {
+    let registered: Map<string, Constraint>;
+    beforeAll(async () => { registered = await registeredConstraints([OpenedOnLog, ClosedOnOutbox, OpenedEverywhere, ArchivedOnLog]); });
+
+    it('should combine the event sequences of every declaration', () => registered.get('narrowed')!.EventSequences.should.deep.equal(['event-log', 'outbox']));
+    it('should keep a constraint applying everywhere when one declaration names no event sequence', () =>
+        registered.get('widened')!.EventSequences.should.deep.equal([]));
+});

package/events/constraints/for_Constraints/when_scoping_to_event_sequences/with_standard_decorators.standard.spec.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { field } from '@cratis/fundamentals';
+import { beforeAll, chai, describe, it } from 'vitest';
+import type { Constraint } from '@cratis/chronicle.contracts';
+import { EventSequenceId } from '../../../../eventSequences/EventSequenceId.js';
+import { eventType } from '../../../eventTypeDecorator.js';
+import { unique } from '../../unique.js';
+import { registeredConstraints } from './given/registered_constraints.js';
+
+chai.should();
+
+@eventType('standard-account-opened')
+@unique({ name: 'standard-one-account', message: 'Already opened', eventSequences: [EventSequenceId.eventLog] })
+class AccountOpened { @field(String) label = ''; }
+
+@eventType('standard-account-noted')
+@unique('standard-unscoped-account')
+class AccountNoted { @field(String) label = ''; }
+
+@eventType('standard-email-registered')
+class EmailRegistered {
+    @field(String) @unique({ name: 'standard-email', eventSequences: ['event-log'] }) email = '';
+    @field(String) @unique({ name: 'standard-alias' }) alias = '';
+}
+
+@eventType('standard-email-forwarded')
+class EmailForwarded {
+    @field(String) @unique({ name: 'standard-email', eventSequences: ['outbox'] }) email = '';
+    @field(String) @unique({ name: 'standard-alias', eventSequences: ['outbox'] }) alias = '';
+}
+
+describe('when scoping standard unique decorators to event sequences', () => {
+    let registered: Map<string, Constraint>;
+    beforeAll(async () => { registered = await registeredConstraints([], [AccountOpened, AccountNoted, EmailRegistered, EmailForwarded]); });
+
+    it('should register a decorated event type for the declared event sequences', () =>
+        registered.get('standard-one-account')!.EventSequences.should.deep.equal(['event-log']));
+    it('should register the positional form for every event sequence', () =>
+        registered.get('standard-unscoped-account')!.EventSequences.should.deep.equal([]));
+    it('should combine the event sequences of properties sharing a constraint name', () =>
+        registered.get('standard-email')!.EventSequences.should.deep.equal(['event-log', 'outbox']));
+    it('should keep a shared constraint applying everywhere when one property names no event sequence', () =>
+        registered.get('standard-alias')!.EventSequences.should.deep.equal([]));
+});

package/events/constraints/index.ts

@@ -7,6 +7,8 @@ export type { IConstraintBuilder } from './IConstraintBuilder.js';
 export type { IUniqueConstraintBuilder } from './IUniqueConstraintBuilder.js';
 export { constraint, getConstraintMetadata, isConstraint } from './constraint.js';
 export { unique } from './unique.js';
+export type { UniqueOptions } from './UniqueOptions.js';
+export type { ConstraintEventSequence } from './ConstraintEventSequences.js';
 export { removeConstraint } from './removeConstraint.js';
 export type { ConstraintMetadata } from './constraint.js';
 export type { IConstraints } from './IConstraints.js';

package/events/constraints/unique.ts

@@ -4,6 +4,8 @@
 import 'reflect-metadata';
 import { ChronicleClassOrPropertyDecorator, decorateClassOrProperty, getPropertyMetadata, getTypeOrFieldMetadata } from '../../types/propertyDecoratorMetadata.js';
 import { TypeIntrospector } from '../../types/TypeIntrospector.js';
+import { normalizeConstraintEventSequences } from './ConstraintEventSequences.js';
+import type { UniqueOptions } from './UniqueOptions.js';
 
 const CLASS_KEY = 'chronicle:constraint:unique:class';
 const PROPERTY_KEY = 'chronicle:constraint:unique:property';
@@ -11,6 +13,8 @@ const PROPERTY_KEY = 'chronicle:constraint:unique:property';
 interface UniqueMetadata {
     name?: string;
     message?: string;
+    /** Normalized event sequence identifiers; omitted means every event sequence. */
+    eventSequences?: string[];
 }
 
 /**
@@ -21,9 +25,25 @@ interface UniqueMetadata {
  * @param message - Optional fixed violation message.
  * @returns A class or public instance field decorator.
  */
-export function unique(name?: string, message?: string): ChronicleClassOrPropertyDecorator {
+export function unique(name?: string, message?: string): ChronicleClassOrPropertyDecorator;
+/**
+ * Marks an event class as unique per event source, or an event property as unique across event sources,
+ * optionally applying the constraint only to selected event sequences.
+ * @param options - The constraint name, message and event sequences.
+ * @returns A class or public instance field decorator.
+ */
+export function unique(options: UniqueOptions): ChronicleClassOrPropertyDecorator;
+export function unique(nameOrOptions?: string | UniqueOptions, message?: string): ChronicleClassOrPropertyDecorator {
+    const options: UniqueOptions = typeof nameOrOptions === 'object' && nameOrOptions !== null
+        ? nameOrOptions
+        : { name: nameOrOptions, message };
+    const eventSequences = normalizeConstraintEventSequences(options.eventSequences ?? []);
+    const metadata: UniqueMetadata = {
+        name: options.name,
+        message: options.message,
+        ...(eventSequences.length > 0 ? { eventSequences } : {})
+    };
     return decorateClassOrProperty((target, property) => {
-        const metadata: UniqueMetadata = { name, message };
         if (property !== undefined) {
             const key = property.toString();
             TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);