@cratis/chronicle 6.1.0 → 6.2.0

package/projections/Projections.declarativeVariants.spec.ts

@@ -0,0 +1,157 @@
+// 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 { describe, expect, it, vi } from 'vitest';
+import { IClientArtifactsProvider } from '../artifacts';
+import { ChronicleConnection } from '../connection';
+import { eventType } from '../events/eventTypeDecorator';
+import { IProjectionBuilderFor } from './declarative/IProjectionBuilderFor';
+import { IProjectionFor } from './declarative/IProjectionFor';
+import { projection } from './declarative/projection';
+import { Projections } from './Projections';
+import { VariantMustDeclareEntersOnEvent } from './VariantMustDeclareEntersOnEvent';
+
+class IssueCreated {
+    title!: string;
+}
+eventType()(IssueCreated);
+
+class PullRequestCreated {
+    pullRequestUrl!: string;
+}
+eventType()(PullRequestCreated);
+
+class BuildCompleted {
+    buildStatus!: string;
+}
+eventType()(BuildCompleted);
+
+/** Anchors the logical identity shared by the two declarative variants below. */
+class DecWorkItem {}
+
+class DecBacklogItem {
+    id!: string;
+    title!: string;
+}
+
+class DecBacklogItemProjection implements IProjectionFor<DecBacklogItem> {
+    define(builder: IProjectionBuilderFor<DecBacklogItem>): void {
+        builder.variantOf(DecWorkItem, m => m.id).entersOn(IssueCreated);
+    }
+}
+projection('DecBacklogItem', DecBacklogItem)(DecBacklogItemProjection);
+
+class DecPullRequestItem {
+    id!: string;
+    pullRequestUrl!: string;
+    buildStatus!: string;
+}
+
+class DecPullRequestItemProjection implements IProjectionFor<DecPullRequestItem> {
+    define(builder: IProjectionBuilderFor<DecPullRequestItem>): void {
+        builder
+            .variantOf(DecWorkItem, m => m.id)
+            .entersOn(PullRequestCreated)
+            .from(PullRequestCreated)
+            .from(BuildCompleted);
+    }
+}
+projection('DecPullRequestItem', DecPullRequestItem)(DecPullRequestItemProjection);
+
+class DecUndeclaredVariant {
+    id!: string;
+}
+
+class DecUndeclaredVariantProjection implements IProjectionFor<DecUndeclaredVariant> {
+    define(builder: IProjectionBuilderFor<DecUndeclaredVariant>): void {
+        builder.variantOf(DecWorkItem, m => m.id).from(IssueCreated);
+    }
+}
+projection('DecUndeclaredVariant', DecUndeclaredVariant)(DecUndeclaredVariantProjection);
+
+interface CapturedDefinition {
+    Identifier: string;
+    From: Array<{ Key: { Id: string }; Value: { Properties: Record<string, string>; Key: string } }>;
+    Join: Array<{ Key: { Id: string }; Value: { On: string; Properties: Record<string, string>; Key: string } }>;
+    RemovedWith: Array<{ Key: { Id: string }; Value: { Key: string; ParentKey: string } }>;
+}
+
+function createProjections(projections: (new (...args: unknown[]) => unknown)[]) {
+    const registerMock = vi.fn().mockResolvedValue(undefined);
+    const registerManyMock = vi.fn().mockResolvedValue(undefined);
+    const connection = {
+        readModels: { registerMany: registerManyMock },
+        projections: { register: registerMock }
+    } as unknown as ChronicleConnection;
+
+    const clientArtifacts: IClientArtifactsProvider = {
+        eventTypes: [],
+        readModels: [],
+        reactors: [],
+        reducers: [],
+        seeders: [],
+        constraints: [],
+        projections: projections as unknown as IClientArtifactsProvider['projections'],
+        webhooks: [],
+        eventTypeMigrations: [],
+        globalForHandlers: []
+    };
+
+    const projectionsInstance = new Projections('test-store', 'test-namespace', connection, clientArtifacts, 'test-sink');
+    return { projections: projectionsInstance, registerMock };
+}
+
+function definitionsFor(registerMock: ReturnType<typeof vi.fn>): Map<string, CapturedDefinition> {
+    const byIdentifier = new Map<string, CapturedDefinition>();
+    for (const call of registerMock.mock.calls) {
+        const request = call[0] as { Projections: CapturedDefinition[] };
+        for (const definition of request.Projections) {
+            byIdentifier.set(definition.Identifier, definition);
+        }
+    }
+    return byIdentifier;
+}
+
+describe('Projections', () => {
+    describe('when registering a declarative variant that projects from an event that is not its entering event', () => {
+        it('should reclassify it into an update-only self-referential join', async () => {
+            const { projections, registerMock } = createProjections([DecBacklogItemProjection, DecPullRequestItemProjection]);
+
+            await projections.register();
+
+            const definitions = definitionsFor(registerMock);
+            const pullRequestItem = definitions.get('DecPullRequestItem')!;
+
+            expect(pullRequestItem.From.some(entry => entry.Key.Id === 'BuildCompleted')).toBe(false);
+
+            const buildCompletedJoin = pullRequestItem.Join.find(entry => entry.Key.Id === 'BuildCompleted');
+            expect(buildCompletedJoin).toBeDefined();
+            expect(buildCompletedJoin!.Value.On).toBe('id');
+            expect(buildCompletedJoin!.Value.Key).toBe('$eventSourceId');
+        });
+    });
+
+    describe('when two declarative variants of the same identity are registered together', () => {
+        it('should cross-wire mutual exclusion between them', async () => {
+            const { projections, registerMock } = createProjections([DecBacklogItemProjection, DecPullRequestItemProjection]);
+
+            await projections.register();
+
+            const definitions = definitionsFor(registerMock);
+            const backlogItem = definitions.get('DecBacklogItem')!;
+            const pullRequestItem = definitions.get('DecPullRequestItem')!;
+
+            expect(backlogItem.RemovedWith.some(entry => entry.Key.Id === 'PullRequestCreated')).toBe(true);
+            expect(pullRequestItem.RemovedWith.some(entry => entry.Key.Id === 'IssueCreated')).toBe(true);
+        });
+    });
+
+    describe('when a declarative variant does not declare an entersOn event', () => {
+        it('should throw VariantMustDeclareEntersOnEvent', async () => {
+            const { projections } = createProjections([DecUndeclaredVariantProjection]);
+
+            await expect(projections.register()).rejects.toThrow(VariantMustDeclareEntersOnEvent);
+        });
+    });
+});

package/projections/Projections.modelBoundCompleteness.spec.ts

@@ -149,7 +149,8 @@ function createProjections(readModels: (new (...args: unknown[]) => unknown)[])
         constraints: [],
         projections: [],
         webhooks: [],
-        eventTypeMigrations: []
+        eventTypeMigrations: [],
+        globalForHandlers: []
     };
 
     const projections = new Projections('test-store', 'test-namespace', connection, clientArtifacts, 'test-sink');

package/projections/Projections.operationalSurface.spec.ts

@@ -82,7 +82,8 @@ async function createDiscoveredProjections() {
         constraints: [],
         projections: [DeclarativeSummaryProjection] as unknown as IClientArtifactsProvider['projections'],
         webhooks: [],
-        eventTypeMigrations: []
+        eventTypeMigrations: [],
+        globalForHandlers: []
     };
 
     const projections = new Projections('test-store', 'test-namespace', connection, clientArtifacts, 'test-sink');

package/projections/Projections.spec.ts

@@ -82,7 +82,8 @@ function createProjections(readModels: (new (...args: unknown[]) => unknown)[])
         constraints: [],
         projections: [],
         webhooks: [],
-        eventTypeMigrations: []
+        eventTypeMigrations: [],
+        globalForHandlers: []
     };
 
     const projections = new Projections('test-store', 'test-namespace', connection, clientArtifacts, 'test-sink');

package/projections/Projections.ts

@@ -50,7 +50,11 @@ import { isNotRewindable } from './modelBound/notRewindable';
 import { isPassive } from './modelBound/passive';
 import { getRemovedWithClassMetadata, getRemovedWithPropertyMetadata } from './modelBound/removedWith';
 import { getRemovedWithJoinClassMetadata, getRemovedWithJoinPropertyMetadata } from './modelBound/removedWithJoin';
+import { getVariantOfMetadata } from './modelBound/variantOf';
+import { getEntersOnMetadata } from './modelBound/entersOn';
+import { getGlobalForMetadata } from './modelBound/globalFor';
 import { UnableToQueryProjection } from './UnableToQueryProjection';
+import { BuiltProjection, crossWireGroups, mergeGlobalHandlers, reclassify, VariantDeclaration } from './VariantReclassifier';
 
 interface ResolvedModelBoundMetadata {
     id: ProjectionId;
@@ -132,11 +136,21 @@ export class Projections implements IProjections {
 
         this._logger.info('Registering projections', { declarativeCount: this._declarative.size, modelBoundCount: this._modelBound.size });
 
-        const projections = [
+        const builtProjections: BuiltProjection[] = [
             ...Array.from(this._declarative.values()).map(type => this.buildDeclarativeDefinition(type)),
             ...Array.from(this._modelBound.values()).map(type => this.buildModelBoundDefinition(type))
         ];
 
+        // Cross-wiring can only run once every variant in this registration call is known, so it
+        // runs here rather than as each definition is built - and LastUpdated is computed only
+        // afterward, so a RemovedWith entry it adds is reflected in the hash sent to the kernel.
+        crossWireGroups(builtProjections);
+        for (const built of builtProjections) {
+            built.definition.LastUpdated = { Value: this.computeStableLastUpdated(built.definition) };
+        }
+
+        const projections = builtProjections.map(built => built.definition);
+
         if (projections.length === 0) {
             this._logger.info('No projections to register');
             return;
@@ -380,7 +394,7 @@ export class Projections implements IProjections {
         return '{}';
     }
 
-    private buildDeclarativeDefinition(type: Constructor): any {
+    private buildDeclarativeDefinition(type: Constructor): BuiltProjection {
         const metadata = getProjectionMetadata(type);
         if (!metadata) {
             throw new Error(`Type '${type.name}' is missing declarative projection metadata.`);
@@ -405,8 +419,21 @@ export class Projections implements IProjections {
             }
         }
 
-        definition.LastUpdated = { Value: this.computeStableLastUpdated(definition) };
-        return definition;
+        let variant: VariantDeclaration | undefined;
+        const variantDeclaration = builder.getVariantDeclaration();
+        if (variantDeclaration) {
+            const reclassified = reclassify(
+                type.name,
+                definition.From as any,
+                definition.Join as any,
+                variantDeclaration.enteringEventTypes,
+                variantDeclaration.key);
+            definition.From = reclassified.from;
+            definition.Join = reclassified.join;
+            variant = variantDeclaration;
+        }
+
+        return { typeName: type.name, definition, variant };
     }
 
     private inferReadModelIdentifier(mappedProperties: string[]): string | undefined {
@@ -429,7 +456,7 @@ export class Projections implements IProjections {
         return matchingReadModels[0].metadata!.id.value;
     }
 
-    private buildModelBoundDefinition(type: Constructor): any {
+    private buildModelBoundDefinition(type: Constructor): BuiltProjection {
         const metadata = this.resolveModelBoundMetadata(type);
         if (!metadata) {
             throw new Error(`Type '${type.name}' is missing model-bound projection metadata.`);
@@ -533,6 +560,39 @@ export class Projections implements IProjections {
             }
         }
 
+        let from = Array.from(fromByEventType.values());
+        let join = Array.from(joinByEventType.values());
+        let variant: VariantDeclaration | undefined;
+
+        const variantMetadata = getVariantOfMetadata(type);
+        if (variantMetadata) {
+            const entersOnList = getEntersOnMetadata(type);
+            const enteringEventTypes = entersOnList.map(entersOn => {
+                const contractType = toContractEventType(entersOn.eventType);
+                if (entersOn.key) {
+                    const entry = ensureFromEntry(fromByEventType, entersOn.eventType);
+                    entry.Value.Key = entersOn.key;
+                }
+                return contractType;
+            });
+            from = Array.from(fromByEventType.values());
+
+            const globalHandlers = new Map<string, FromRecord[]>();
+            for (const handlerType of this._clientArtifacts.globalForHandlers) {
+                const globalForMetadata = getGlobalForMetadata(handlerType);
+                if (globalForMetadata?.identity === variantMetadata.identity) {
+                    globalHandlers.set(handlerType.name, this.buildFromRecordsForType(handlerType));
+                }
+            }
+
+            const memberNames = new Set(getReadModelMetadata(type)?.members.keys() ?? properties);
+            const merged = mergeGlobalHandlers(type.name, memberNames, from, globalHandlers);
+            const reclassified = reclassify(type.name, merged, join, enteringEventTypes, variantMetadata.key);
+            from = reclassified.from;
+            join = reclassified.join;
+            variant = { identity: variantMetadata.identity, key: variantMetadata.key, enteringEventTypes };
+        }
+
         const definition: Record<string, unknown> = {
             EventSequenceId: metadata.eventSequenceId ?? EventSequenceId.eventLog.value,
             Identifier: metadata.id.value,
@@ -540,8 +600,8 @@ export class Projections implements IProjections {
             IsActive: !isPassive(type),
             IsRewindable: !isNotRewindable(type),
             InitialModelState: '{}',
-            From: Array.from(fromByEventType.values()),
-            Join: Array.from(joinByEventType.values()),
+            From: from,
+            Join: join,
             Children: childrenByProperty,
             FromEvery: [],
             All: {
@@ -557,8 +617,37 @@ export class Projections implements IProjections {
             NoAutoMapProperties: properties.filter(property => isPropertyNoAutoMap(prototype, property)),
             Nested: nestedByProperty
         };
-        definition.LastUpdated = { Value: this.computeStableLastUpdated(definition) };
-        return definition;
+        return { typeName: type.name, definition, variant };
+    }
+
+    /**
+     * Builds the raw From records for an arbitrary type using the same property-mapping rules as
+     * a model-bound read model - used to fold a globalFor shared handler's mappings into every
+     * variant of its identity.
+     * @param type - The type to build From records for.
+     * @returns The built From records.
+     */
+    private buildFromRecordsForType(type: Constructor): FromRecord[] {
+        const fromByEventType = new Map<string, FromRecord>();
+        const fromEvents = getFromEventMetadata(type);
+        for (const fromEvent of fromEvents) {
+            const eventType = toContractEventType(fromEvent.eventType);
+            fromByEventType.set(getEventTypeMapKey(eventType), {
+                Key: eventType,
+                Value: {
+                    Properties: {},
+                    Key: fromEvent.constantKey ?? fromEvent.key ?? '$eventSourceId',
+                    ParentKey: fromEvent.parentKey ?? ''
+                }
+            });
+        }
+
+        const prototype = type.prototype;
+        for (const property of TypeIntrospector.getTrackedProperties(type)) {
+            applyPropertyMappings(prototype, property, fromByEventType);
+        }
+
+        return Array.from(fromByEventType.values());
     }
 
     private resolveModelBoundMetadata(type: Constructor): ResolvedModelBoundMetadata | undefined {

package/projections/Projections.variants.spec.ts

@@ -0,0 +1,253 @@
+// 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 { describe, expect, it, vi } from 'vitest';
+import { IClientArtifactsProvider } from '../artifacts';
+import { ChronicleConnection } from '../connection';
+import { eventType } from '../events/eventTypeDecorator';
+import { readModel } from '../readModels/readModel';
+import { entersOn } from './modelBound/entersOn';
+import { fromEvent } from './modelBound/fromEvent';
+import { globalFor } from './modelBound/globalFor';
+import { setFrom } from './modelBound/setFrom';
+import { variantOf } from './modelBound/variantOf';
+import { GlobalHandlerPropertyNotOnVariant } from './GlobalHandlerPropertyNotOnVariant';
+import { VariantMustDeclareEntersOnEvent } from './VariantMustDeclareEntersOnEvent';
+import { Projections } from './Projections';
+
+// Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
+// fixtures don't depend on the test runner's decorator-syntax support.
+
+class IssueCreated {
+    title!: string;
+}
+eventType()(IssueCreated);
+
+class PullRequestCreated {
+    pullRequestUrl!: string;
+}
+eventType()(PullRequestCreated);
+
+class BuildCompleted {
+    buildStatus!: string;
+}
+eventType()(BuildCompleted);
+
+class TitleChanged {
+    title!: string;
+}
+eventType()(TitleChanged);
+
+/** Anchors the logical identity shared by every variant below. Never itself a read model. */
+class WorkItem {}
+
+class BacklogItem {
+    id!: string;
+    title!: string;
+}
+setFrom(IssueCreated, 'title')(BacklogItem.prototype, 'title');
+variantOf(WorkItem, 'id')(BacklogItem);
+entersOn(IssueCreated)(BacklogItem);
+fromEvent(IssueCreated)(BacklogItem);
+readModel()(BacklogItem);
+
+class PullRequestItem {
+    id!: string;
+    title!: string;
+    pullRequestUrl!: string;
+    buildStatus!: string;
+}
+setFrom(PullRequestCreated, 'pullRequestUrl')(PullRequestItem.prototype, 'pullRequestUrl');
+setFrom(BuildCompleted, 'buildStatus')(PullRequestItem.prototype, 'buildStatus');
+variantOf(WorkItem, 'id')(PullRequestItem);
+entersOn(PullRequestCreated)(PullRequestItem);
+fromEvent(PullRequestCreated)(PullRequestItem);
+fromEvent(BuildCompleted)(PullRequestItem);
+readModel()(PullRequestItem);
+
+/** A shared handler with no entering event of its own - never registered as its own projection. */
+class TitleHandler {
+    title!: string;
+}
+setFrom(TitleChanged, 'title')(TitleHandler.prototype, 'title');
+globalFor(WorkItem)(TitleHandler);
+
+/** A variant missing an entersOn declaration entirely. */
+class UndeclaredVariant {
+    id!: string;
+    title!: string;
+}
+setFrom(IssueCreated, 'title')(UndeclaredVariant.prototype, 'title');
+variantOf(WorkItem, 'id')(UndeclaredVariant);
+fromEvent(IssueCreated)(UndeclaredVariant);
+readModel()(UndeclaredVariant);
+
+/** A separate identity, used to prove sibling cross-wiring stays scoped to one identity. */
+class OtherIdentity {}
+
+class OtherVariant {
+    id!: string;
+}
+variantOf(OtherIdentity, 'id')(OtherVariant);
+entersOn(IssueCreated)(OtherVariant);
+fromEvent(IssueCreated)(OtherVariant);
+readModel()(OtherVariant);
+
+interface CapturedDefinition {
+    Identifier: string;
+    From: Array<{ Key: { Id: string }; Value: { Properties: Record<string, string>; Key: string } }>;
+    Join: Array<{ Key: { Id: string }; Value: { On: string; Properties: Record<string, string>; Key: string } }>;
+    RemovedWith: Array<{ Key: { Id: string }; Value: { Key: string; ParentKey: string } }>;
+}
+
+function createProjections(readModels: (new (...args: unknown[]) => unknown)[], globalForHandlers: (new (...args: unknown[]) => unknown)[] = []) {
+    const registerMock = vi.fn().mockResolvedValue(undefined);
+    const registerManyMock = vi.fn().mockResolvedValue(undefined);
+    const connection = {
+        readModels: { registerMany: registerManyMock },
+        projections: { register: registerMock }
+    } as unknown as ChronicleConnection;
+
+    const clientArtifacts: IClientArtifactsProvider = {
+        eventTypes: [],
+        readModels: readModels as unknown as IClientArtifactsProvider['readModels'],
+        reactors: [],
+        reducers: [],
+        seeders: [],
+        constraints: [],
+        projections: [],
+        webhooks: [],
+        eventTypeMigrations: [],
+        globalForHandlers: globalForHandlers as unknown as IClientArtifactsProvider['globalForHandlers']
+    };
+
+    const projections = new Projections('test-store', 'test-namespace', connection, clientArtifacts, 'test-sink');
+    return { projections, registerMock };
+}
+
+function definitionsFor(registerMock: ReturnType<typeof vi.fn>): Map<string, CapturedDefinition> {
+    const byIdentifier = new Map<string, CapturedDefinition>();
+    for (const call of registerMock.mock.calls) {
+        const request = call[0] as { Projections: CapturedDefinition[] };
+        for (const definition of request.Projections) {
+            byIdentifier.set(definition.Identifier, definition);
+        }
+    }
+    return byIdentifier;
+}
+
+describe('Projections', () => {
+    describe('when registering a variant that enters on its own event', () => {
+        it('should keep the entering event as a create-or-update From handler', async () => {
+            const { projections, registerMock } = createProjections([BacklogItem, PullRequestItem]);
+
+            await projections.register();
+
+            const definitions = definitionsFor(registerMock);
+            const backlogItem = definitions.get('BacklogItem')!;
+            const issueCreated = backlogItem.From.find(entry => entry.Key.Id === 'IssueCreated');
+            expect(issueCreated).toBeDefined();
+            expect(issueCreated!.Value.Properties.title).toBe('title');
+        });
+    });
+
+    describe('when a variant projects from an event that is not its entering event', () => {
+        it('should reclassify it into an update-only self-referential join', async () => {
+            const { projections, registerMock } = createProjections([BacklogItem, PullRequestItem]);
+
+            await projections.register();
+
+            const definitions = definitionsFor(registerMock);
+            const pullRequestItem = definitions.get('PullRequestItem')!;
+
+            expect(pullRequestItem.From.some(entry => entry.Key.Id === 'BuildCompleted')).toBe(false);
+
+            const buildCompletedJoin = pullRequestItem.Join.find(entry => entry.Key.Id === 'BuildCompleted');
+            expect(buildCompletedJoin).toBeDefined();
+            expect(buildCompletedJoin!.Value.On).toBe('id');
+            expect(buildCompletedJoin!.Value.Key).toBe('$eventSourceId');
+            expect(buildCompletedJoin!.Value.Properties.buildStatus).toBe('buildStatus');
+        });
+    });
+
+    describe('when two variants of the same identity are registered together', () => {
+        it('should cross-wire mutual exclusion between them', async () => {
+            const { projections, registerMock } = createProjections([BacklogItem, PullRequestItem]);
+
+            await projections.register();
+
+            const definitions = definitionsFor(registerMock);
+            const backlogItem = definitions.get('BacklogItem')!;
+            const pullRequestItem = definitions.get('PullRequestItem')!;
+
+            const backlogRemovedByPullRequest = backlogItem.RemovedWith.find(entry => entry.Key.Id === 'PullRequestCreated');
+            expect(backlogRemovedByPullRequest).toBeDefined();
+
+            const pullRequestRemovedByBacklog = pullRequestItem.RemovedWith.find(entry => entry.Key.Id === 'IssueCreated');
+            expect(pullRequestRemovedByBacklog).toBeDefined();
+        });
+
+        it('should not cross-wire a variant of a different identity', async () => {
+            const { projections, registerMock } = createProjections([BacklogItem, PullRequestItem, OtherVariant]);
+
+            await projections.register();
+
+            const definitions = definitionsFor(registerMock);
+            const otherVariant = definitions.get('OtherVariant')!;
+
+            expect(otherVariant.RemovedWith.length).toBe(0);
+        });
+    });
+
+    describe('when a globalFor shared handler applies to a group', () => {
+        it('should merge its mapping into every variant', async () => {
+            const { projections, registerMock } = createProjections([BacklogItem, PullRequestItem], [TitleHandler]);
+
+            await projections.register();
+
+            const definitions = definitionsFor(registerMock);
+            const backlogItem = definitions.get('BacklogItem')!;
+            const pullRequestItem = definitions.get('PullRequestItem')!;
+
+            const backlogTitleChanged = backlogItem.Join.find(entry => entry.Key.Id === 'TitleChanged');
+            expect(backlogTitleChanged).toBeDefined();
+            expect(backlogTitleChanged!.Value.Properties.title).toBe('title');
+
+            const pullRequestTitleChanged = pullRequestItem.Join.find(entry => entry.Key.Id === 'TitleChanged');
+            expect(pullRequestTitleChanged).toBeDefined();
+            expect(pullRequestTitleChanged!.Value.Properties.title).toBe('title');
+        });
+
+        it('should never register the shared handler as its own projection', async () => {
+            const { projections, registerMock } = createProjections([BacklogItem, PullRequestItem], [TitleHandler]);
+
+            await projections.register();
+
+            const definitions = definitionsFor(registerMock);
+            expect(definitions.has('TitleHandler')).toBe(false);
+        });
+    });
+
+    describe('when a variant does not declare an entersOn event', () => {
+        it('should throw VariantMustDeclareEntersOnEvent', async () => {
+            const { projections } = createProjections([UndeclaredVariant]);
+
+            await expect(projections.register()).rejects.toThrow(VariantMustDeclareEntersOnEvent);
+        });
+    });
+
+    describe('when a globalFor shared handler maps to a property a variant does not have', () => {
+        class MismatchedHandler {
+            unrelatedProperty!: string;
+        }
+        setFrom(TitleChanged, 'title')(MismatchedHandler.prototype, 'unrelatedProperty');
+        globalFor(WorkItem)(MismatchedHandler);
+
+        it('should throw GlobalHandlerPropertyNotOnVariant', async () => {
+            const { projections } = createProjections([BacklogItem, PullRequestItem], [MismatchedHandler]);
+
+            await expect(projections.register()).rejects.toThrow(GlobalHandlerPropertyNotOnVariant);
+        });
+    });
+});

package/projections/VariantMustDeclareEntersOnEvent.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Error thrown when a read model variant does not declare at least one entersOn event.
+ */
+export class VariantMustDeclareEntersOnEvent extends Error {
+    /**
+     * Creates a new {@link VariantMustDeclareEntersOnEvent}.
+     * @param typeName - The name of the variant type missing an entersOn declaration.
+     */
+    constructor(typeName: string) {
+        super(`Read model variant '${typeName}' does not declare an entersOn event. A variant must name at least one event that may create or resurrect it.`);
+        this.name = 'VariantMustDeclareEntersOnEvent';
+    }
+}