@cratis/chronicle 6.1.0 → 6.2.0

package/projections/VariantReclassifier.ts

@@ -0,0 +1,177 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ContractEventType, FromRecord, JoinRecord } from './declarative/ProjectionBuilderCore';
+import { GlobalHandlerPropertyNotOnVariant } from './GlobalHandlerPropertyNotOnVariant';
+import { VariantMustDeclareEntersOnEvent } from './VariantMustDeclareEntersOnEvent';
+
+const EVENT_SOURCE_ID_KEY = '$eventSourceId';
+
+/**
+ * What one variant declared about being part of a mutually exclusive group, carried from the
+ * point its definition was built to the cross-wiring pass that runs once every variant in the
+ * group is known.
+ */
+export interface VariantDeclaration {
+    /** The identity value used to group definitions for the cross-wiring pass. */
+    readonly identity: Function;
+    /** The variant's own key property name, used as the correlation property for reclassified joins. */
+    readonly key: string;
+    /** The event types that activate this variant. */
+    readonly enteringEventTypes: ContractEventType[];
+}
+
+/**
+ * A built projection definition, tagged with its variant declaration when it is one.
+ */
+export interface BuiltProjection {
+    readonly typeName: string;
+    readonly definition: Record<string, unknown>;
+    readonly variant?: VariantDeclaration;
+}
+
+function eventTypeKey(eventType: ContractEventType): string {
+    return `${eventType.Id}:${eventType.Generation}:${eventType.Tombstone}`;
+}
+
+/**
+ * Merges every mapping a globalFor shared handler declares into a variant's From records, keyed
+ * by event type. Runs before {@link reclassify} so a shared mapping for a non-entering event is
+ * turned into an update-only join exactly like a mapping declared directly on the variant.
+ * @param variantTypeName - The name of the variant type, used for error reporting.
+ * @param variantMemberNames - The property names the variant actually has.
+ * @param from - The variant's own From records.
+ * @param globalHandlers - The shared handler From records applicable to this variant's identity, keyed by handler type name.
+ * @returns The merged From records.
+ * @throws {@link GlobalHandlerPropertyNotOnVariant} when a shared mapping targets a member the variant does not have.
+ */
+export function mergeGlobalHandlers(
+    variantTypeName: string,
+    variantMemberNames: ReadonlySet<string>,
+    from: FromRecord[],
+    globalHandlers: ReadonlyMap<string, FromRecord[]>
+): FromRecord[] {
+    if (globalHandlers.size === 0) {
+        return from;
+    }
+
+    const byEventType = new Map<string, FromRecord>();
+    for (const record of from) {
+        byEventType.set(eventTypeKey(record.Key), record);
+    }
+
+    for (const [globalHandlerTypeName, globalRecords] of globalHandlers) {
+        for (const globalRecord of globalRecords) {
+            for (const propertyName of Object.keys(globalRecord.Value.Properties)) {
+                if (!variantMemberNames.has(propertyName)) {
+                    throw new GlobalHandlerPropertyNotOnVariant(globalHandlerTypeName, variantTypeName, propertyName);
+                }
+            }
+
+            const key = eventTypeKey(globalRecord.Key);
+            const existing = byEventType.get(key);
+            byEventType.set(key, existing
+                ? { Key: existing.Key, Value: { ...existing.Value, Properties: { ...existing.Value.Properties, ...globalRecord.Value.Properties } } }
+                : globalRecord);
+        }
+    }
+
+    return Array.from(byEventType.values());
+}
+
+/**
+ * Reclassifies every From record that is not one of the entering event types into an update-only
+ * join on the variant's own key. The entering event(s) keep their ordinary create-or-update From
+ * handler; everything else becomes a self-referential join that can bring an already-active
+ * instance up to date but can never create one.
+ * @param variantTypeName - The name of the variant type, used for error reporting.
+ * @param from - The variant's own (possibly merged) From records.
+ * @param join - The variant's own Join records, unaffected by reclassification.
+ * @param enteringEventTypes - The event types that activate this variant.
+ * @param variantKey - The variant's own key property name.
+ * @returns The reclassified From and Join records.
+ * @throws {@link VariantMustDeclareEntersOnEvent} when enteringEventTypes is empty.
+ */
+export function reclassify(
+    variantTypeName: string,
+    from: FromRecord[],
+    join: JoinRecord[],
+    enteringEventTypes: ContractEventType[],
+    variantKey: string
+): { from: FromRecord[]; join: JoinRecord[] } {
+    if (enteringEventTypes.length === 0) {
+        throw new VariantMustDeclareEntersOnEvent(variantTypeName);
+    }
+
+    const entering = new Set(enteringEventTypes.map(eventTypeKey));
+    const remainingFrom: FromRecord[] = [];
+    const reclassifiedJoins: JoinRecord[] = [];
+
+    for (const record of from) {
+        if (entering.has(eventTypeKey(record.Key))) {
+            remainingFrom.push(record);
+        } else {
+            reclassifiedJoins.push({
+                Key: record.Key,
+                Value: {
+                    On: variantKey,
+                    Key: record.Value.Key || EVENT_SOURCE_ID_KEY,
+                    Properties: record.Value.Properties
+                }
+            });
+        }
+    }
+
+    return { from: remainingFrom, join: [...join, ...reclassifiedJoins] };
+}
+
+/**
+ * Gives every variant a RemovedWith entry for every sibling's entering event(s), and none for
+ * its own - the mutual-exclusion cross-wiring that can only run once every variant of a group
+ * has been built.
+ *
+ * A variant cannot be told what removes it while it is being built, because its siblings are
+ * not known yet. This runs once per registration call, over every variant discovered in that
+ * call.
+ * @param projections - Every built projection definition from this registration call, tagged with its variant declaration when it is one.
+ */
+export function crossWireGroups(projections: BuiltProjection[]): void {
+    const variantEntries = projections.filter((entry): entry is BuiltProjection & { variant: VariantDeclaration } => entry.variant !== undefined);
+    if (variantEntries.length === 0) {
+        return;
+    }
+
+    const byIdentity = new Map<Function, typeof variantEntries>();
+    for (const entry of variantEntries) {
+        const group = byIdentity.get(entry.variant.identity) ?? [];
+        group.push(entry);
+        byIdentity.set(entry.variant.identity, group);
+    }
+
+    for (const entry of variantEntries) {
+        const siblings = (byIdentity.get(entry.variant.identity) ?? []).filter(sibling => sibling !== entry);
+        if (siblings.length === 0) {
+            continue;
+        }
+
+        const existingRemovedWith = (entry.definition.RemovedWith as Array<{ Key: ContractEventType; Value: { Key: string; ParentKey: string } }>) ?? [];
+        const removedWithByEventType = new Map<string, { Key: ContractEventType; Value: { Key: string; ParentKey: string } }>();
+        for (const record of existingRemovedWith) {
+            removedWithByEventType.set(eventTypeKey(record.Key), record);
+        }
+
+        for (const sibling of siblings) {
+            for (const eventType of sibling.variant.enteringEventTypes) {
+                const key = eventTypeKey(eventType);
+                if (!removedWithByEventType.has(key)) {
+                    removedWithByEventType.set(key, {
+                        Key: eventType,
+                        Value: { Key: EVENT_SOURCE_ID_KEY, ParentKey: EVENT_SOURCE_ID_KEY }
+                    });
+                }
+            }
+        }
+
+        entry.definition.RemovedWith = Array.from(removedWithByEventType.values());
+    }
+}

package/projections/declarative/IProjectionBuilderFor.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 { PropertyAccessor } from '@cratis/fundamentals';
 import { IProjectionBuilder } from './IProjectionBuilder';
 
 /**
@@ -35,4 +36,25 @@ export interface IProjectionBuilderFor<TReadModel>
      * @returns This builder for fluent chaining.
      */
     passive(): IProjectionBuilderFor<TReadModel>;
+
+    /**
+     * Declares this projection to be one of several mutually exclusive representations of the
+     * same logical entity. Entering one variant removes the entity from every sibling variant
+     * of the same identity.
+     * @param identity - The type anchoring the logical identity shared by every variant. Does not need to be a read model itself.
+     * @param keyAccessor - Accessor for the property on this variant used as its own key.
+     * @returns This builder for fluent chaining.
+     */
+    variantOf(identity: Function, keyAccessor: PropertyAccessor<TReadModel>): IProjectionBuilderFor<TReadModel>;
+
+    /**
+     * Names an event that may create or resurrect this variant. Repeatable - a variant may enter
+     * on more than one event. Every other event this projection is built from is automatically
+     * reclassified into an update-only join: it can bring an already-active instance up to date,
+     * but it can never create or resurrect one.
+     * @param eventType - The event constructor.
+     * @param key - Optional event property name used as the key. Defaults to the event source identifier.
+     * @returns This builder for fluent chaining.
+     */
+    entersOn(eventType: Function, key?: string): IProjectionBuilderFor<TReadModel>;
 }

package/projections/declarative/ProjectionBuilderFor.ts

@@ -9,7 +9,7 @@ import { IChildrenBuilder } from './IChildrenBuilder';
 import { INestedBuilder } from './INestedBuilder';
 import { IProjectionBuilderFor } from './IProjectionBuilderFor';
 import { NestedBuilder } from './NestedBuilder';
-import { ProjectionBuilderCore } from './ProjectionBuilderCore';
+import { ContractEventType, ProjectionBuilderCore } from './ProjectionBuilderCore';
 
 /**
  * Concrete implementation of {@link IProjectionBuilderFor} that accumulates projection
@@ -21,6 +21,9 @@ export class ProjectionBuilderFor<TReadModel> extends ProjectionBuilderCore<TRea
     private _containerName: string | undefined;
     private _rewindable: boolean = true;
     private _active: boolean = true;
+    private _variantIdentity: Function | undefined;
+    private _variantKey: string | undefined;
+    private readonly _enteringEventTypes: ContractEventType[] = [];
 
     constructor() {
         super();
@@ -51,6 +54,42 @@ export class ProjectionBuilderFor<TReadModel> extends ProjectionBuilderCore<TRea
         return this;
     }
 
+    /** @inheritdoc */
+    variantOf(identity: Function, keyAccessor: PropertyAccessor<TReadModel>): this {
+        const handler = new PropertyPathResolverProxyHandler();
+        const proxy = new Proxy({}, handler);
+        keyAccessor(proxy as TReadModel);
+
+        this._variantIdentity = identity;
+        this._variantKey = handler.property;
+        return this;
+    }
+
+    /** @inheritdoc */
+    entersOn(eventType: Function, key?: string): this {
+        const contractType = this.toContractEventType(eventType);
+        this._enteringEventTypes.push(contractType);
+        if (key) {
+            const fromEntry = this._from.find(record => record.Key.Id === contractType.Id && record.Key.Generation === contractType.Generation);
+            if (fromEntry) {
+                fromEntry.Value.Key = key;
+            }
+        }
+        return this;
+    }
+
+    /**
+     * Gets the variant declaration this builder accumulated, if any.
+     * @returns The variant declaration, or undefined when this projection is not a variant.
+     */
+    getVariantDeclaration(): { identity: Function; key: string; enteringEventTypes: ContractEventType[] } | undefined {
+        if (!this._variantIdentity || !this._variantKey) {
+            return undefined;
+        }
+
+        return { identity: this._variantIdentity, key: this._variantKey, enteringEventTypes: this._enteringEventTypes };
+    }
+
     /** @inheritdoc */
     children<TChildModel>(
         targetPropertyAccessor: PropertyAccessor<TReadModel>,

package/projections/index.ts

@@ -7,5 +7,7 @@ export { Projections } from './Projections';
 export type { ProjectionState } from './ProjectionState';
 export type { ProjectionQueryResult } from './ProjectionQueryResult';
 export { UnableToQueryProjection } from './UnableToQueryProjection';
+export { VariantMustDeclareEntersOnEvent } from './VariantMustDeclareEntersOnEvent';
+export { GlobalHandlerPropertyNotOnVariant } from './GlobalHandlerPropertyNotOnVariant';
 export * from './declarative';
 export * from './modelBound';

package/projections/modelBound/entersOn.ts

@@ -0,0 +1,39 @@
+// 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';
+
+/** Metadata stored by the entersOn class decorator. */
+export interface EntersOnMetadata {
+    /** The event constructor that may create or resurrect the variant. */
+    readonly eventType: Function;
+    /** The event property name used as the key. Defaults to the event source identifier. */
+    readonly key?: string;
+}
+
+const METADATA_KEY = 'chronicle:projection:entersOn';
+
+/**
+ * Class decorator that names an event that may create or resurrect a read model variant.
+ * Repeatable - a variant may enter on more than one event. Every event a variant projects
+ * from that is not named here is automatically reclassified into an update-only join: it
+ * can bring an already-active instance up to date, but it can never create or resurrect one.
+ * @param eventType - The event constructor.
+ * @param key - Optional event property name used as the key. Defaults to the event source identifier.
+ * @returns A class decorator.
+ */
+export function entersOn(eventType: Function, key?: string): ClassDecorator {
+    return (target: object) => {
+        const existing: EntersOnMetadata[] = Reflect.getMetadata(METADATA_KEY, target) ?? [];
+        Reflect.defineMetadata(METADATA_KEY, [...existing, { eventType, key }], target);
+    };
+}
+
+/**
+ * Retrieves entersOn metadata stored on the given class constructor.
+ * @param target - The class constructor.
+ * @returns An array of entersOn metadata entries.
+ */
+export function getEntersOnMetadata(target: Function): EntersOnMetadata[] {
+    return Reflect.getMetadata(METADATA_KEY, target) ?? [];
+}

package/projections/modelBound/globalFor.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 'reflect-metadata';
+import { Constructor } from '@cratis/fundamentals';
+import { DecoratorType, TypeDiscoverer } from '../../types';
+
+/** Metadata stored by the globalFor class decorator. */
+export interface GlobalForMetadata {
+    /** The type anchoring the logical identity this shared handler applies its mappings to. */
+    readonly identity: Function;
+}
+
+const METADATA_KEY = 'chronicle:projection:globalFor';
+
+/**
+ * Class decorator that declares a shared handler class whose mappings apply to every variant
+ * of the given identity, without repeating them on each variant type. A mapping that targets
+ * a member some variant lacks is a declaration error, not a silently skipped mapping.
+ *
+ * A class decorated only with globalFor is never registered as a projection on its own - it is
+ * merged into every variant of its identity before those variants are registered.
+ * @param identity - The type anchoring the logical identity this handler's mappings apply to.
+ * @returns A class decorator.
+ */
+export function globalFor(identity: Function): ClassDecorator {
+    return (target: object) => {
+        const constructor = target as Constructor;
+        Reflect.defineMetadata(METADATA_KEY, { identity }, target);
+        TypeDiscoverer.default.register(DecoratorType.GlobalForHandler, constructor, constructor.name);
+    };
+}
+
+/**
+ * Retrieves globalFor metadata stored on the given class constructor.
+ * @param target - The class constructor.
+ * @returns The globalFor metadata, or undefined if the class is not a shared handler.
+ */
+export function getGlobalForMetadata(target: Function): GlobalForMetadata | undefined {
+    return Reflect.getMetadata(METADATA_KEY, target);
+}

package/projections/modelBound/index.ts

@@ -39,3 +39,9 @@ export { fromAll, getFromAllMetadata } from './fromAll';
 export type { FromAllMetadata } from './fromAll';
 export { noAutoMap, isNoAutoMap, isPropertyNoAutoMap } from './noAutoMap';
 export { eventSequence, eventLog, getEventSequenceMetadata } from './eventSequence';
+export { variantOf, getVariantOfMetadata } from './variantOf';
+export type { VariantOfMetadata } from './variantOf';
+export { entersOn, getEntersOnMetadata } from './entersOn';
+export type { EntersOnMetadata } from './entersOn';
+export { globalFor, getGlobalForMetadata } from './globalFor';
+export type { GlobalForMetadata } from './globalFor';

package/projections/modelBound/variantOf.ts

@@ -0,0 +1,38 @@
+// 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';
+
+/** Metadata stored by the variantOf class decorator. */
+export interface VariantOfMetadata {
+    /** The type anchoring the logical identity every variant of this group shares. */
+    readonly identity: Function;
+    /** The property name on this variant used as its own key, and as the correlation property for reclassified joins. */
+    readonly key: string;
+}
+
+const METADATA_KEY = 'chronicle:projection:variantOf';
+
+/**
+ * Class decorator that declares a read model to be one of several mutually exclusive
+ * representations of the same logical entity. Entering one variant removes the entity
+ * from every sibling variant of the same identity.
+ * @param identity - The type anchoring the logical identity shared by every variant. Does not need to be a read model itself.
+ * @param key - The property name on this variant used as its own key.
+ * @returns A class decorator.
+ */
+export function variantOf(identity: Function, key: string): ClassDecorator {
+    return (target: object) => {
+        const metadata: VariantOfMetadata = { identity, key };
+        Reflect.defineMetadata(METADATA_KEY, metadata, target);
+    };
+}
+
+/**
+ * Retrieves variantOf metadata stored on the given class constructor.
+ * @param target - The class constructor.
+ * @returns The variantOf metadata, or undefined if the class is not a variant.
+ */
+export function getVariantOfMetadata(target: Function): VariantOfMetadata | undefined {
+    return Reflect.getMetadata(METADATA_KEY, target);
+}

package/readModels/ReadModels.spec.ts

@@ -33,7 +33,8 @@ function createReadModels(readModelType: Constructor, releaseResponse: Record<st
         constraints: [],
         projections: [],
         webhooks: [],
-        eventTypeMigrations: []
+        eventTypeMigrations: [],
+        globalForHandlers: []
     } as IClientArtifactsProvider;
 
     const readModels = new ReadModels('test-store', 'test-namespace', connection, clientArtifacts, 'default-sink');

package/reducers/Reducers.spec.ts

@@ -62,7 +62,8 @@ function createArtifacts(reducers: Constructor[]): IClientArtifactsProvider {
         constraints: [],
         projections: [],
         webhooks: [],
-        eventTypeMigrations: []
+        eventTypeMigrations: [],
+        globalForHandlers: []
     };
 }
 

package/types/DecoratorType.ts

@@ -30,5 +30,8 @@ export enum DecoratorType {
     Webhook = 'webhook',
 
     /** Event type migration artifacts discovered through the eventTypeMigration decorator. */
-    EventTypeMigration = 'eventTypeMigration'
+    EventTypeMigration = 'eventTypeMigration',
+
+    /** Global read model variant handler artifacts discovered through the globalFor decorator. */
+    GlobalForHandler = 'globalForHandler'
 }