@cratis/chronicle 6.22.0 → 6.23.0

package/events/constraints/Constraints.ts

@@ -3,8 +3,8 @@
 
 import { ConstraintType } from '@cratis/chronicle.contracts';
 import type { ConstraintViolation } from '../../eventSequences/ConstraintViolation.js';
-import { IClientArtifactsProvider } from '../../artifacts/index.js';
-import { ChronicleConnection } from '../../connection/index.js';
+import type { IClientArtifactsProvider } from '../../artifacts/index.js';
+import type { ChronicleConnection } from '../../connection/index.js';
 import { ConstraintId } from './ConstraintId.js';
 import { IConstraint } from './IConstraint.js';
 import { IConstraints } from './IConstraints.js';
@@ -35,38 +35,22 @@ function assertMatchingScope(name: string, left: ConstraintScopeCapture, right:
     }
 }
 
-/** Manages discovery and registration of constraints with the Chronicle Kernel. */
-export class Constraints implements IConstraints {
-    private readonly _captures = new Map<string, ConstraintCapture>();
-
-    /**
-     * Creates a new {@link Constraints} instance.
-     * @param _eventStore - The name of the event store these constraints belong to.
-     * @param _connection - The connection used to communicate with the Kernel.
-     * @param _clientArtifacts - Provider for discovered client artifact types.
-     */
-    constructor(
-        private readonly _eventStore: string,
-        private readonly _connection: ChronicleConnection,
-        private readonly _clientArtifacts: IClientArtifactsProvider
-    ) {}
-
-    /** @inheritdoc */
-    async discover(): Promise<void> {
-        this._captures.clear();
-        const fluentIds = new Set<string>();
-        for (const type of this._clientArtifacts.constraints) {
-            const metadata = getConstraintMetadata(type);
+/** Compile decorator and fluent constraints using the production registration rules. */
+export function compileConstraints(provider: Pick<IClientArtifactsProvider, 'eventTypes' | 'constraints'>): Map<string, ConstraintCapture> {
+    const captures = new Map<string, ConstraintCapture>();
+    const fluentIds = new Set<string>();
+    for (const definition of provider.constraints) {
+            const metadata = getConstraintMetadata(definition);
             if (!metadata) continue;
-            if (fluentIds.has(metadata.id.value)) throw new Error(`Duplicate constraint id '${metadata.id.value}'.`);
-            fluentIds.add(metadata.id.value);
-
-            const builder = new ConstraintBuilder(metadata.id.value);
-            const instance = new (type as new () => IConstraint)();
+            const id = metadata.id.value;
+            if (fluentIds.has(id)) throw new Error(`Duplicate constraint id '${id}'.`);
+            fluentIds.add(id);
+            const builder = new ConstraintBuilder(id);
+            const instance = new (definition as new () => IConstraint)();
             instance.define(builder);
             const capture = builder.capture;
             const name = wireNameOf(capture);
-            const existing = this._captures.get(name);
+            const existing = captures.get(name);
             if (existing?.uniqueEventType && capture.uniqueEventType) {
                 assertMatchingScope(name, existing.scope, capture.scope);
                 const merged = existing.uniqueEventType;
@@ -82,12 +66,12 @@ export class Constraints implements IConstraints {
             } else if (existing) {
                 throw new Error(`Duplicate constraint name '${name}'.`);
             } else {
-                this._captures.set(name, capture);
+                captures.set(name, capture);
             }
         }
 
         const removalEvents = new Map<string, Function[]>();
-        for (const eventType of this._clientArtifacts.eventTypes) {
+        for (const eventType of provider.eventTypes) {
             for (const name of getRemovedConstraintNames(eventType)) {
                 const events = removalEvents.get(name) ?? [];
                 events.push(eventType);
@@ -95,16 +79,16 @@ export class Constraints implements IConstraints {
             }
         }
 
-        for (const eventType of this._clientArtifacts.eventTypes) {
+        for (const eventType of provider.eventTypes) {
             const eventMetadata = getUniqueEventMetadata(eventType);
             if (eventMetadata) {
                 const name = eventMetadata.name ?? eventType.name;
-                let capture = this._captures.get(name);
+                let capture = captures.get(name);
                 if (!capture) {
                     const builder = new ConstraintBuilder(name);
                     builder.uniqueFor(eventType, eventMetadata.message, name);
                     capture = builder.capture;
-                    this._captures.set(name, capture);
+                    captures.set(name, capture);
                 } else if (!capture.uniqueEventType) {
                     throw new Error(`Constraint '${name}' is not a unique event type constraint.`);
                 } else {
@@ -120,12 +104,12 @@ export class Constraints implements IConstraints {
                 const metadata = getUniquePropertyMetadata(eventType, property);
                 if (!metadata) continue;
                 const name = metadata.name ?? property;
-                let capture = this._captures.get(name);
+                let capture = captures.get(name);
                 if (!capture) {
                     const builder = new ConstraintBuilder(name);
                     builder.unique(() => {});
                     capture = builder.capture;
-                    this._captures.set(name, capture);
+                    captures.set(name, capture);
                 }
                 if (!capture.uniqueConstraint) throw new Error(`Constraint '${name}' is not a unique property constraint.`);
                 assertMatchingScope(name, capture.scope, decoratorScope);
@@ -142,7 +126,7 @@ export class Constraints implements IConstraints {
         }
 
         for (const [name, eventTypes] of removalEvents) {
-            const capture = this._captures.get(name);
+            const capture = captures.get(name);
             if (capture) {
                 if (capture.uniqueConstraint) {
                     const unique = new UniqueConstraintBuilder(capture.uniqueConstraint);
@@ -156,6 +140,40 @@ export class Constraints implements IConstraints {
                 }
             }
         }
+    return captures;
+}
+
+/** Resolve the registered message and detail substitutions without a connection. */
+export function resolveConstraintMessage(captures: ReadonlyMap<string, ConstraintCapture>, violation: ConstraintViolation): ConstraintViolation {
+    const capture = captures.get(violation.constraintId);
+    const message = capture?.uniqueConstraint?.message ?? capture?.uniqueEventType?.message;
+    if (!message) return violation;
+    let resolved = message;
+    for (const [key, value] of Object.entries(violation.details)) {
+        resolved = resolved.replaceAll(`{${key}}`, () => value);
+    }
+    return { ...violation, message: resolved };
+}
+
+/** Manages discovery and registration of constraints with the Chronicle Kernel. */
+export class Constraints implements IConstraints {
+    private _captures = new Map<string, ConstraintCapture>();
+
+    /**
+     * Creates a new {@link Constraints} instance.
+     * @param _eventStore - The name of the event store these constraints belong to.
+     * @param _connection - The connection used to communicate with the Kernel.
+     * @param _clientArtifacts - Provider for discovered client artifact types.
+     */
+    constructor(
+        private readonly _eventStore: string,
+        private readonly _connection: ChronicleConnection,
+        private readonly _clientArtifacts: IClientArtifactsProvider
+    ) {}
+
+    /** @inheritdoc */
+    async discover(): Promise<void> {
+        this._captures = compileConstraints(this._clientArtifacts);
     }
 
     /** @inheritdoc */
@@ -242,14 +260,6 @@ export class Constraints implements IConstraints {
      * @returns The violation with its configured message and substituted details, if available.
      */
     resolveMessageFor(violation: ConstraintViolation): ConstraintViolation {
-        const capture = this._captures.get(violation.constraintId);
-        const message = capture?.uniqueConstraint?.message ?? capture?.uniqueEventType?.message;
-        if (!message) return violation;
-
-        let resolved = message;
-        for (const [key, value] of Object.entries(violation.details)) {
-            resolved = resolved.replaceAll(`{${key}}`, () => value);
-        }
-        return { ...violation, message: resolved };
+        return resolveConstraintMessage(this._captures, violation);
     }
 }

package/events/constraints/for_Constraints/when_resolving_violation_messages.spec.ts

@@ -1,6 +1,9 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { readFileSync } from 'node:fs';
+import { field } from '@cratis/fundamentals';
+import { ConstraintType, type ConstraintViolation as ContractsConstraintViolation } from '@cratis/chronicle.contracts';
 import { chai, describe, it, vi } from 'vitest';
 import type { ChronicleConnection } from '../../../connection/ChronicleConnection.js';
 import type { IClientArtifactsProvider } from '../../../artifacts/IClientArtifactsProvider.js';
@@ -57,16 +60,44 @@ describe('when resolving violation messages', () => {
         const connection = {
             eventSequences: { append: vi.fn().mockResolvedValue({ Response: {
                 SequenceNumber: 0n, Errors: [], ConstraintViolations: [{
-                    ConstraintId: 'SharedAddress', Message: 'Kernel default', Details: { email: 'a$b' }
-                }]
+                    EventTypeId: 'message-registered', SequenceNumber: 0n, ConstraintType: ConstraintType.Unique,
+                    ConstraintName: 'SharedAddress', Message: 'Kernel default', Details: { email: 'a$b' }
+                } satisfies ContractsConstraintViolation]
             } }) }
         } as unknown as ChronicleConnection;
         const sequence = new EventSequence(EventSequenceId.eventLog, 'store', 'namespace', connection,
             {} as IUnitOfWorkManager, discovered.resolveMessageFor.bind(discovered));
         const result = await sequence.append('source', new Registered());
+        result.constraintViolations[0].constraintId.should.equal('SharedAddress');
         result.constraintViolations[0].message.should.equal('Address a$b already registered');
     });
 
+    it('should map a kernel wire violation name and resolve its configured message on a connected append', async () => {
+        class OracleKeyClaimed { @field(String) @unique('OracleKey', 'Already claimed: {PropertyName}={PropertyValue}') key = 'Alpha'; }
+        eventType('OracleKeyClaimed')(OracleKeyClaimed);
+        const discovered = constraints([OracleKeyClaimed]);
+        await discovered.discover();
+        const fixture = JSON.parse(readFileSync(new URL('../../../testing/fixtures/constraints.json', import.meta.url), 'utf8')) as {
+            expected: { outcomes: Array<{ wireViolations: Array<{ SequenceNumber: string; ConstraintName: string;
+                EventTypeId: string; ConstraintType: number; Message: string; Details: Record<string, string> }>;
+                violations: Array<{ message: string }> }> }
+        };
+        const wire = fixture.expected.outcomes[2].wireViolations[0];
+        const connection = {
+            eventSequences: { append: vi.fn().mockResolvedValue({ Response: {
+                SequenceNumber: 18446744073709551615n, Errors: [],
+                ConstraintViolations: [{ ...wire, SequenceNumber: BigInt(wire.SequenceNumber) }]
+            } }) }
+        } as unknown as ChronicleConnection;
+        const sequence = new EventSequence(EventSequenceId.eventLog, 'store', 'namespace', connection,
+            {} as IUnitOfWorkManager, discovered.resolveMessageFor.bind(discovered));
+        const result = await sequence.append('B', new OracleKeyClaimed());
+        result.isSuccess.should.be.false;
+        result.constraintViolations[0].constraintId.should.equal(wire.ConstraintName);
+        result.constraintViolations[0].message.should.equal(fixture.expected.outcomes[2].violations[0].message);
+        result.constraintViolations[0].message.should.not.equal(wire.Message);
+    });
+
     it('should resolve a named fluent event type with a different class id', async () => {
         const discovered = constraints([], [FluentRegistration]);
         await discovered.discover();
@@ -80,13 +111,15 @@ describe('when resolving violation messages', () => {
         const connection = {
             eventSequences: { append: vi.fn().mockResolvedValue({ Response: {
                 SequenceNumber: 0n, Errors: [], ConstraintViolations: [{
-                    ConstraintId: 'OneRegistration', Message: 'Kernel default', Details: {}
-                }]
+                    EventTypeId: 'message-once', SequenceNumber: 0n, ConstraintType: ConstraintType.UniqueEventType,
+                    ConstraintName: 'OneRegistration', Message: 'Kernel default', Details: {}
+                } satisfies ContractsConstraintViolation]
             } }) }
         } as unknown as ChronicleConnection;
         const sequence = new EventSequence(EventSequenceId.eventLog, 'store', 'namespace', connection,
             {} as IUnitOfWorkManager, discovered.resolveMessageFor.bind(discovered));
         const result = await sequence.append('source', new OnlyOnce());
+        result.constraintViolations[0].constraintId.should.equal('OneRegistration');
         result.constraintViolations[0].message.should.equal('Already registered');
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.22.0",
+    "version": "6.23.0",
     "description": "Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle, the open-source event-sourcing database",
     "author": "Cratis",
     "license": "MIT",

package/testing/EventScenario.constraint-discovery.spec.ts

@@ -0,0 +1,69 @@
+// 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 { chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { unique } from '../events/constraints/unique.js';
+import { TypeDiscoverer } from '../types/TypeDiscoverer.js';
+import { EventScenario, UnsupportedEventSequenceOperation } from './index.js';
+
+chai.should();
+
+describe('selected constraint discovery', () => {
+    it('enforces selected decorators when global discovery has been cleared', async () => {
+        class SelectedClaim {
+            @field(String) @unique('ClearedRegistryKey') key: string;
+            constructor(key: string) { this.key = key; }
+        }
+        eventType('ClearedRegistryClaim')(SelectedClaim);
+        TypeDiscoverer.default.clear();
+
+        const subject = new EventScenario({ artifacts: { eventTypes: [SelectedClaim] } });
+        (await subject.append('A', new SelectedClaim('Alpha'))).isSuccess.should.be.true;
+        const result = await subject.append('B', new SelectedClaim('Alpha'));
+        result.isSuccess.should.be.false;
+        result.constraintViolations[0].constraintId.should.equal('ClearedRegistryKey');
+        subject.appendedEvents.length.should.equal(1);
+    });
+
+    it('appends a constraint-free selected class shadowed by a later registration with the same ID', async () => {
+        class SelectedItemAdded {
+            @field(String) label: string;
+            constructor(label: string) { this.label = label; }
+        }
+        eventType('ShadowedPlainItemAdded')(SelectedItemAdded);
+        class ShadowItemAdded {
+            @field(String) name: string;
+            constructor(name: string) { this.name = name; }
+        }
+        eventType('ShadowedPlainItemAdded')(ShadowItemAdded);
+
+        const subject = new EventScenario({ artifacts: { eventTypes: [SelectedItemAdded] } });
+        (await subject.append('A', new SelectedItemAdded('Alpha'))).isSuccess.should.be.true;
+        subject.appendedEvents.length.should.equal(1);
+        subject.appendedEvents[0].content.should.deep.equal({ label: 'Alpha' });
+    });
+
+    it('rejects a globally registered constructor shadowing the selected event type ID', () => {
+        class SelectedClaim {
+            @field(String) @unique('ShadowedRegistryKey') key = 'Alpha';
+        }
+        eventType('ShadowedRegistryClaim')(SelectedClaim);
+        class ShadowClaim {
+            @field(String) key = 'Alpha';
+        }
+        eventType('ShadowedRegistryClaim')(ShadowClaim);
+
+        try {
+            new EventScenario({ artifacts: { eventTypes: [SelectedClaim] } });
+            throw new Error('Expected conflicting constructors to be rejected');
+        } catch (error) {
+            (error instanceof UnsupportedEventSequenceOperation).should.be.true;
+            (error as Error).message.should.include('artifacts.eventTypes');
+            (error as Error).message.should.include('ShadowedRegistryClaim');
+            (error as Error).message.should.include('Conflicting constructors share an event type ID');
+        }
+    });
+});