@cratis/chronicle 6.7.1 → 6.8.0

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

@@ -0,0 +1,108 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import type { ChronicleConnection } from '../../../connection/index.js';
+import { eventType } from '../../eventTypeDecorator.js';
+import { constraint } from '../constraint.js';
+import { Constraints } from '../Constraints.js';
+import type { IConstraint } from '../IConstraint.js';
+import type { IConstraintBuilder } from '../IConstraintBuilder.js';
+import { unique } from '../unique.js';
+
+const should = chai.should();
+
+async function assertDiscoveryFails(eventTypes: Function[], constraintTypes: (new () => IConstraint)[], message: RegExp): Promise<void> {
+    const artifacts = { eventTypes, constraints: constraintTypes } as IClientArtifactsProvider;
+    const constraints = new Constraints('store', {} as ChronicleConnection, artifacts);
+    await constraints.discover().then(
+        () => should.fail('Expected incompatible constraint definitions'),
+        (error: Error) => error.message.should.match(message)
+    );
+}
+
+describe('when two fluent unique event type constraints use the same class id', () => {
+    it('should reject the duplicate id even if their wire names differ', async () => {
+        class First {}
+        class Second {}
+        eventType('merge-first')(First);
+        eventType('merge-second')(Second);
+        class FirstConstraint implements IConstraint {
+            define(builder: IConstraintBuilder): void { builder.uniqueFor(First, undefined, 'FirstName'); }
+        }
+        class SecondConstraint implements IConstraint {
+            define(builder: IConstraintBuilder): void { builder.uniqueFor(Second, undefined, 'SecondName'); }
+        }
+        constraint('SharedId')(FirstConstraint);
+        constraint('SharedId')(SecondConstraint);
+        await assertDiscoveryFails([], [FirstConstraint, SecondConstraint], /Duplicate constraint id 'SharedId'/);
+    });
+});
+
+describe('when merging fluent unique event types with different scopes', () => {
+    it('should reject the conflicting scope', async () => {
+        class First {}
+        class Second {}
+        eventType('merge-first')(First);
+        eventType('merge-second')(Second);
+        class Global implements IConstraint {
+            define(builder: IConstraintBuilder): void { builder.uniqueFor(First, undefined, 'Shared'); }
+        }
+        class Scoped implements IConstraint {
+            define(builder: IConstraintBuilder): void { builder.perEventStreamId().uniqueFor(Second, undefined, 'Shared'); }
+        }
+        constraint('Global')(Global);
+        constraint('Scoped')(Scoped);
+        await assertDiscoveryFails([], [Global, Scoped], /Conflicting scopes for constraint 'Shared'/);
+    });
+});
+
+describe('when merging a scoped fluent unique event type with a decorator', () => {
+    it('should reject the conflicting scope', async () => {
+        class First {}
+        class Second {}
+        eventType('merge-first')(First);
+        eventType('merge-second')(Second);
+        class Scoped implements IConstraint {
+            define(builder: IConstraintBuilder): void { builder.perEventSourceType().uniqueFor(First, undefined, 'Shared'); }
+        }
+        constraint('ScopedEvent')(Scoped);
+        unique('Shared')(Second);
+        await assertDiscoveryFails([Second], [Scoped], /Conflicting scopes for constraint 'Shared'/);
+    });
+});
+
+describe('when merging a scoped fluent unique property with a decorator', () => {
+    it('should reject the conflicting scope', async () => {
+        class First { address = ''; }
+        class Second { address = ''; }
+        eventType('merge-first')(First);
+        eventType('merge-second')(Second);
+        class Scoped implements IConstraint {
+            define(builder: IConstraintBuilder): void {
+                builder.perEventStreamType().unique(uniqueBuilder => uniqueBuilder.on(First, event => event.address));
+            }
+        }
+        constraint('SharedProperty')(Scoped);
+        unique('SharedProperty')(Second.prototype, 'address');
+        await assertDiscoveryFails([Second], [Scoped], /Conflicting scopes for constraint 'SharedProperty'/);
+    });
+});
+
+describe('when merging a case-insensitive fluent unique property with a decorator', () => {
+    it('should reject the conflicting casing setting', async () => {
+        class First { address = ''; }
+        class Second { address = ''; }
+        eventType('merge-first')(First);
+        eventType('merge-second')(Second);
+        class CaseInsensitive implements IConstraint {
+            define(builder: IConstraintBuilder): void {
+                builder.unique(uniqueBuilder => uniqueBuilder.on(First, event => event.address).ignoreCasing());
+            }
+        }
+        constraint('SharedProperty')(CaseInsensitive);
+        unique('SharedProperty')(Second.prototype, 'address');
+        await assertDiscoveryFails([Second], [CaseInsensitive], /Conflicting ignoreCasing for unique property constraint 'SharedProperty'/);
+    });
+});

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

@@ -0,0 +1,92 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it, vi } from 'vitest';
+import type { ChronicleConnection } from '../../../connection/ChronicleConnection.js';
+import type { IClientArtifactsProvider } from '../../../artifacts/IClientArtifactsProvider.js';
+import { EventSequence } from '../../../eventSequences/EventSequence.js';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import type { IUnitOfWorkManager } from '../../../transactions/IUnitOfWorkManager.js';
+import { eventType } from '../../eventTypeDecorator.js';
+import { constraint } from '../constraint.js';
+import { Constraints } from '../Constraints.js';
+import type { IConstraint } from '../IConstraint.js';
+import type { IConstraintBuilder } from '../IConstraintBuilder.js';
+import { unique } from '../unique.js';
+
+const should = chai.should();
+class Registered { email = ''; }
+class OnlyOnce {}
+eventType('message-registered')(Registered);
+eventType('message-once')(OnlyOnce);
+unique('SharedAddress', 'Address {email} already registered')(Registered.prototype, 'email');
+unique('OneRegistration', 'Already registered')(OnlyOnce);
+
+class FluentRegistration implements IConstraint {
+    define(builder: IConstraintBuilder): void {
+        builder.uniqueFor(OnlyOnce, 'Already registered', 'OneRegistration');
+    }
+}
+constraint('FluentRegistration')(FluentRegistration);
+
+class FluentAddress implements IConstraint {
+    define(builder: IConstraintBuilder): void {
+        builder.unique(uniqueBuilder => uniqueBuilder.on(Registered, event => event.email).withMessage('Address {email} already registered'));
+    }
+}
+constraint('SharedAddress')(FluentAddress);
+
+function constraints(types: Function[], constraintTypes: (new () => IConstraint)[] = []): Constraints {
+    const artifacts = { eventTypes: types, constraints: constraintTypes } as IClientArtifactsProvider;
+    return new Constraints('store', { constraints: { register: vi.fn() } } as unknown as ChronicleConnection, artifacts);
+}
+
+describe('when resolving violation messages', () => {
+    it('should substitute detail values literally and preserve unknown violations', async () => {
+        const discovered = constraints([Registered]);
+        await discovered.discover();
+        discovered.resolveMessageFor({ constraintId: 'SharedAddress', message: 'Kernel', details: { email: '$& $$ $` $\'' } }).message
+            .should.equal('Address $& $$ $` $\' already registered');
+        const violation = { constraintId: 'unknown', message: 'Kernel default', details: {} };
+        discovered.resolveMessageFor(violation).should.equal(violation);
+    });
+
+    it('should resolve fluent withMessage values on append results', async () => {
+        const discovered = constraints([Registered], [FluentAddress]);
+        await discovered.discover();
+        const connection = {
+            eventSequences: { append: vi.fn().mockResolvedValue({ Response: {
+                SequenceNumber: 0n, Errors: [], ConstraintViolations: [{
+                    ConstraintId: 'SharedAddress', Message: 'Kernel default', Details: { email: 'a$b' }
+                }]
+            } }) }
+        } 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].message.should.equal('Address a$b already registered');
+    });
+
+    it('should resolve a named fluent event type with a different class id', async () => {
+        const discovered = constraints([], [FluentRegistration]);
+        await discovered.discover();
+        discovered.resolveMessageFor({ constraintId: 'OneRegistration', message: 'Kernel', details: {} }).message
+            .should.equal('Already registered');
+    });
+
+    it('should resolve decorated event type messages on append results', async () => {
+        const discovered = constraints([OnlyOnce]);
+        await discovered.discover();
+        const connection = {
+            eventSequences: { append: vi.fn().mockResolvedValue({ Response: {
+                SequenceNumber: 0n, Errors: [], ConstraintViolations: [{
+                    ConstraintId: 'OneRegistration', Message: 'Kernel default', Details: {}
+                }]
+            } }) }
+        } 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].message.should.equal('Already registered');
+    });
+});

package/events/constraints/index.ts

@@ -6,6 +6,8 @@ export type { IConstraint } from './IConstraint.js';
 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 { removeConstraint } from './removeConstraint.js';
 export type { ConstraintMetadata } from './constraint.js';
 export type { IConstraints } from './IConstraints.js';
 export { Constraints } from './Constraints.js';

package/events/constraints/removeConstraint.ts

@@ -0,0 +1,28 @@
+// 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 { ChronicleClassDecorator } from '../../types/standardDecoratorMetadata.js';
+
+const KEY = 'chronicle:constraint:remove';
+
+/**
+ * Marks an event class as releasing a named constraint when appended. May be applied repeatedly.
+ * @param name - Exact name of the constraint to release.
+ * @returns A class decorator.
+ */
+export function removeConstraint(name: string): ChronicleClassDecorator {
+    return (target: object) => {
+        const existing = Reflect.getOwnMetadata(KEY, target) as string[] | undefined ?? [];
+        Reflect.defineMetadata(KEY, [...existing, name], target);
+    };
+}
+
+/** Gets the constraint names released by this event class. */
+export function getRemovedConstraintNames(type: Function): string[] {
+    const names: string[] = [];
+    for (let current: object | null = type; current && current !== Function.prototype; current = Object.getPrototypeOf(current)) {
+        names.push(...(Reflect.getOwnMetadata(KEY, current) as string[] | undefined ?? []));
+    }
+    return [...new Set(names)];
+}

package/events/constraints/unique.ts

@@ -0,0 +1,45 @@
+// 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 { ChronicleClassOrPropertyDecorator, decorateClassOrProperty, getPropertyMetadata, getTypeOrFieldMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { TypeIntrospector } from '../../types/TypeIntrospector.js';
+
+const CLASS_KEY = 'chronicle:constraint:unique:class';
+const PROPERTY_KEY = 'chronicle:constraint:unique:property';
+
+interface UniqueMetadata {
+    name?: string;
+    message?: string;
+}
+
+/**
+ * Marks an event class as unique per event source, or an event property as unique across event sources.
+ * The optional name defaults to the class or property name. Like the .NET attribute, this decorator
+ * does not offer ignore-casing; use a fluent constraint for case-insensitive uniqueness.
+ * @param name - Optional shared constraint name.
+ * @param message - Optional fixed violation message.
+ * @returns A class or public instance field decorator.
+ */
+export function unique(name?: string, message?: string): ChronicleClassOrPropertyDecorator {
+    return decorateClassOrProperty((target, property) => {
+        const metadata: UniqueMetadata = { name, message };
+        if (property !== undefined) {
+            const key = property.toString();
+            TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
+            Reflect.defineMetadata(PROPERTY_KEY, metadata, target, key);
+        } else {
+            Reflect.defineMetadata(CLASS_KEY, metadata, target);
+        }
+    });
+}
+
+/** Gets the unique constraint declared on an event class, if present. */
+export function getUniqueEventMetadata(type: Function): UniqueMetadata | undefined {
+    return getTypeOrFieldMetadata<UniqueMetadata>(CLASS_KEY, type);
+}
+
+/** Gets the unique constraint declared on an event property, if present. */
+export function getUniquePropertyMetadata(type: Function, property: string): UniqueMetadata | undefined {
+    return getPropertyMetadata<UniqueMetadata>(PROPERTY_KEY, type.prototype, property);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.7.1",
+    "version": "6.8.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",