@cratis/chronicle 0.0.1

package/Projections/modelBound/addFrom.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 { TypeIntrospector } from '../../types';
+
+/** Metadata stored by the addFrom property decorator. */
+export interface AddFromMetadata {
+    /** The event constructor associated with this annotation. */
+    readonly eventType: Function;
+    /** The event property name whose value is added to the read model property. Defaults to the decorated property name. */
+    readonly eventPropertyName?: string;
+}
+
+const METADATA_KEY = 'chronicle:projection:addFrom';
+
+/**
+ * Property decorator that adds an event property value to the decorated read model property.
+ * @param eventType - The event constructor.
+ * @param eventPropertyName - Optional event property name. Defaults to the property name.
+ * @returns A property decorator.
+ */
+export function addFrom(eventType: Function, eventPropertyName?: string): PropertyDecorator {
+    return (target: object, propertyKey: string | symbol) => {
+        const key = propertyKey.toString();
+        TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
+        const existing: AddFromMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];
+        const metadata: AddFromMetadata = { eventType, eventPropertyName };
+        Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target, key);
+    };
+}
+
+/**
+ * Retrieves all addFrom metadata stored on the given property.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns An array of addFrom metadata entries.
+ */
+export function getAddFromMetadata(target: object, propertyKey: string): AddFromMetadata[] {
+    return Reflect.getMetadata(METADATA_KEY, target, propertyKey) ?? [];
+}

package/Projections/modelBound/childrenFrom.ts

@@ -0,0 +1,52 @@
+// 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 { TypeIntrospector } from '../../types';
+
+/** Metadata stored by the childrenFrom property decorator. */
+export interface ChildrenFromMetadata {
+    /** The event constructor that adds children to the collection. */
+    readonly eventType: Function;
+    /** The event property name used as the key for children. Defaults to the event source identifier. */
+    readonly key?: string;
+    /** The child model property name used to uniquely identify instances in the collection. */
+    readonly identifiedBy?: string;
+    /** The event property name used as the parent key. Defaults to the event source identifier. */
+    readonly parentKey?: string;
+}
+
+const METADATA_KEY = 'chronicle:projection:childrenFrom';
+
+/**
+ * Property decorator that configures a children collection sub-projection from an event type.
+ * @param eventType - The event constructor.
+ * @param key - Optional event property name to use as the key for children.
+ * @param identifiedBy - Optional child model property name used to identify instances.
+ * @param parentKey - Optional event property name used as the parent key.
+ * @returns A property decorator.
+ */
+export function childrenFrom(
+    eventType: Function,
+    key?: string,
+    identifiedBy?: string,
+    parentKey?: string
+): PropertyDecorator {
+    return (target: object, propertyKey: string | symbol) => {
+        const propKey = propertyKey.toString();
+        TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, propKey);
+        const existing: ChildrenFromMetadata[] = Reflect.getMetadata(METADATA_KEY, target, propKey) ?? [];
+        const metadata: ChildrenFromMetadata = { eventType, key, identifiedBy, parentKey };
+        Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target, propKey);
+    };
+}
+
+/**
+ * Retrieves all childrenFrom metadata stored on the given property.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns An array of childrenFrom metadata entries.
+ */
+export function getChildrenFromMetadata(target: object, propertyKey: string): ChildrenFromMetadata[] {
+    return Reflect.getMetadata(METADATA_KEY, target, propertyKey) ?? [];
+}

package/Projections/modelBound/clearWith.ts

@@ -0,0 +1,54 @@
+// 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 { TypeIntrospector } from '../../types';
+
+/** Metadata stored by the clearWith class or property decorator. */
+export interface ClearWithMetadata {
+    /** The event constructor that clears the nested object or projection. */
+    readonly eventType: Function;
+}
+
+const CLASS_METADATA_KEY = 'chronicle:projection:clearWith:class';
+const PROPERTY_METADATA_KEY = 'chronicle:projection:clearWith:property';
+
+/**
+ * Class or property decorator that specifies the event type that clears a nested object.
+ * When used on a class, it clears the entire nested object.
+ * When used on a property, it clears only that property.
+ * @param eventType - The event constructor.
+ * @returns A class and property decorator.
+ */
+export function clearWith(eventType: Function): ClassDecorator & PropertyDecorator {
+    return (target: object, propertyKey?: string | symbol) => {
+        if (propertyKey !== undefined) {
+            const key = propertyKey.toString();
+            TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
+            const existing: ClearWithMetadata[] = Reflect.getMetadata(PROPERTY_METADATA_KEY, target, key) ?? [];
+            Reflect.defineMetadata(PROPERTY_METADATA_KEY, [...existing, { eventType }], target, key);
+        } else {
+            const existing: ClearWithMetadata[] = Reflect.getMetadata(CLASS_METADATA_KEY, target) ?? [];
+            Reflect.defineMetadata(CLASS_METADATA_KEY, [...existing, { eventType }], target);
+        }
+    };
+}
+
+/**
+ * Retrieves clearWith metadata stored on the given class constructor.
+ * @param target - The class constructor.
+ * @returns An array of clearWith metadata entries.
+ */
+export function getClearWithClassMetadata(target: Function): ClearWithMetadata[] {
+    return Reflect.getMetadata(CLASS_METADATA_KEY, target) ?? [];
+}
+
+/**
+ * Retrieves clearWith metadata stored on the given property.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns An array of clearWith metadata entries.
+ */
+export function getClearWithPropertyMetadata(target: object, propertyKey: string): ClearWithMetadata[] {
+    return Reflect.getMetadata(PROPERTY_METADATA_KEY, target, propertyKey) ?? [];
+}

package/Projections/modelBound/count.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 { TypeIntrospector } from '../../types';
+
+/** Metadata stored by the count property decorator. */
+export interface CountMetadata {
+    /** The event constructor whose occurrences are counted. */
+    readonly eventType: Function;
+    /** Optional constant key. All events will update the same read model instance. */
+    readonly constantKey?: string;
+}
+
+const METADATA_KEY = 'chronicle:projection:count';
+
+/**
+ * Property decorator that counts the occurrences of the specified event into the decorated read model property.
+ * @param eventType - The event constructor.
+ * @param constantKey - Optional constant key value.
+ * @returns A property decorator.
+ */
+export function count(eventType: Function, constantKey?: string): PropertyDecorator {
+    return (target: object, propertyKey: string | symbol) => {
+        const key = propertyKey.toString();
+        TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
+        const existing: CountMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];
+        const metadata: CountMetadata = { eventType, constantKey };
+        Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target, key);
+    };
+}
+
+/**
+ * Retrieves all count metadata stored on the given property.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns An array of count metadata entries.
+ */
+export function getCountMetadata(target: object, propertyKey: string): CountMetadata[] {
+    return Reflect.getMetadata(METADATA_KEY, target, propertyKey) ?? [];
+}

package/Projections/modelBound/decrement.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 { TypeIntrospector } from '../../types';
+
+/** Metadata stored by the decrement property decorator. */
+export interface DecrementMetadata {
+    /** The event constructor that triggers the decrement. */
+    readonly eventType: Function;
+    /** Optional constant key. All events will update the same read model instance. */
+    readonly constantKey?: string;
+}
+
+const METADATA_KEY = 'chronicle:projection:decrement';
+
+/**
+ * Property decorator that decrements the decorated read model property each time the specified event occurs.
+ * @param eventType - The event constructor.
+ * @param constantKey - Optional constant key value.
+ * @returns A property decorator.
+ */
+export function decrement(eventType: Function, constantKey?: string): PropertyDecorator {
+    return (target: object, propertyKey: string | symbol) => {
+        const key = propertyKey.toString();
+        TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
+        const existing: DecrementMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];
+        const metadata: DecrementMetadata = { eventType, constantKey };
+        Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target, key);
+    };
+}
+
+/**
+ * Retrieves all decrement metadata stored on the given property.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns An array of decrement metadata entries.
+ */
+export function getDecrementMetadata(target: object, propertyKey: string): DecrementMetadata[] {
+    return Reflect.getMetadata(METADATA_KEY, target, propertyKey) ?? [];
+}

package/Projections/modelBound/fromEvent.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 'reflect-metadata';
+import { FromEventMetadata } from './FromEventMetadata';
+import { FromEventOptions } from './FromEventOptions';
+
+const METADATA_KEY = 'chronicle:projection:fromEvent';
+
+/**
+ * Class decorator that declares which event type populates instances of this read model.
+ * @param eventType - The event constructor.
+ * @param options - Optional key configuration.
+ * @returns A class decorator.
+ */
+export function fromEvent(eventType: Function, options?: FromEventOptions): ClassDecorator {
+    return (target: object) => {
+        const existing: FromEventMetadata[] = Reflect.getMetadata(METADATA_KEY, target) ?? [];
+        const metadata: FromEventMetadata = { eventType, ...options };
+        Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target);
+    };
+}
+
+/**
+ * Retrieves all fromEvent metadata stored on the given class constructor.
+ * @param target - The class constructor.
+ * @returns An array of fromEvent metadata entries.
+ */
+export function getFromEventMetadata(target: Function): FromEventMetadata[] {
+    return Reflect.getMetadata(METADATA_KEY, target) ?? [];
+}
+
+/**
+ * Checks whether the given class has any fromEvent metadata.
+ * @param target - The class constructor.
+ * @returns True if the class has fromEvent metadata; false otherwise.
+ */
+export function hasFromEventMetadata(target: Function): boolean {
+    return Reflect.hasMetadata(METADATA_KEY, target);
+}

package/Projections/modelBound/fromEvery.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';
+import { TypeIntrospector } from '../../types';
+
+/** Metadata stored by the fromEvery property decorator. */
+export interface FromEveryMetadata {
+    /** The event or event context property name to read the value from. */
+    readonly property?: string;
+    /** The event context property name to read the value from. */
+    readonly contextProperty?: string;
+}
+
+const METADATA_KEY = 'chronicle:projection:fromEvery';
+
+/**
+ * Property decorator that sets the decorated read model property from a property present on every projected event.
+ * @param property - Optional event property name. If not specified, uses the model property name.
+ * @param contextProperty - Optional event context property name.
+ * @returns A property decorator.
+ */
+export function fromEvery(property?: string, contextProperty?: string): PropertyDecorator {
+    return (target: object, propertyKey: string | symbol) => {
+        TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, propertyKey.toString());
+        const metadata: FromEveryMetadata = { property, contextProperty };
+        Reflect.defineMetadata(METADATA_KEY, metadata, target, propertyKey.toString());
+    };
+}
+
+/**
+ * Retrieves fromEvery metadata stored on the given property.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns The fromEvery metadata, or undefined if not decorated.
+ */
+export function getFromEveryMetadata(target: object, propertyKey: string): FromEveryMetadata | undefined {
+    return Reflect.getMetadata(METADATA_KEY, target, propertyKey);
+}

package/Projections/modelBound/increment.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 { TypeIntrospector } from '../../types';
+
+/** Metadata stored by the increment property decorator. */
+export interface IncrementMetadata {
+    /** The event constructor that triggers the increment. */
+    readonly eventType: Function;
+    /** Optional constant key. All events will update the same read model instance. */
+    readonly constantKey?: string;
+}
+
+const METADATA_KEY = 'chronicle:projection:increment';
+
+/**
+ * Property decorator that increments the decorated read model property each time the specified event occurs.
+ * @param eventType - The event constructor.
+ * @param constantKey - Optional constant key value.
+ * @returns A property decorator.
+ */
+export function increment(eventType: Function, constantKey?: string): PropertyDecorator {
+    return (target: object, propertyKey: string | symbol) => {
+        const key = propertyKey.toString();
+        TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
+        const existing: IncrementMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];
+        const metadata: IncrementMetadata = { eventType, constantKey };
+        Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target, key);
+    };
+}
+
+/**
+ * Retrieves all increment metadata stored on the given property.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns An array of increment metadata entries.
+ */
+export function getIncrementMetadata(target: object, propertyKey: string): IncrementMetadata[] {
+    return Reflect.getMetadata(METADATA_KEY, target, propertyKey) ?? [];
+}

package/Projections/modelBound/index.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.
+
+export { modelBound, getModelBoundMetadata, isModelBound } from './modelBound';
+export type { ModelBoundMetadata } from './modelBound';
+export { fromEvent, getFromEventMetadata, hasFromEventMetadata } from './fromEvent';
+export type { FromEventOptions } from './FromEventOptions';
+export type { FromEventMetadata } from './FromEventMetadata';
+export { setFrom, getSetFromMetadata } from './setFrom';
+export type { SetFromMetadata } from './setFrom';
+export { setFromContext, getSetFromContextMetadata } from './setFromContext';
+export type { SetFromContextMetadata } from './setFromContext';
+export { join, getJoinMetadata } from './join';
+export type { JoinMetadata } from './join';
+export { addFrom, getAddFromMetadata } from './addFrom';
+export type { AddFromMetadata } from './addFrom';
+export { subtractFrom, getSubtractFromMetadata } from './subtractFrom';
+export type { SubtractFromMetadata } from './subtractFrom';
+export { increment, getIncrementMetadata } from './increment';
+export type { IncrementMetadata } from './increment';
+export { decrement, getDecrementMetadata } from './decrement';
+export type { DecrementMetadata } from './decrement';
+export { count, getCountMetadata } from './count';
+export type { CountMetadata } from './count';
+export { childrenFrom, getChildrenFromMetadata } from './childrenFrom';
+export type { ChildrenFromMetadata } from './childrenFrom';
+export { nested, isNested } from './nested';
+export { clearWith, getClearWithClassMetadata, getClearWithPropertyMetadata } from './clearWith';
+export type { ClearWithMetadata } from './clearWith';
+export { removedWith, getRemovedWithClassMetadata, getRemovedWithPropertyMetadata } from './removedWith';
+export type { RemovedWithMetadata } from './removedWith';
+export { removedWithJoin, getRemovedWithJoinClassMetadata, getRemovedWithJoinPropertyMetadata } from './removedWithJoin';
+export type { RemovedWithJoinMetadata } from './removedWithJoin';
+export { notRewindable, isNotRewindable } from './notRewindable';
+export { setValue, getSetValueMetadata } from './setValue';
+export type { SetValueMetadata } from './setValue';
+export { fromEvery, getFromEveryMetadata } from './fromEvery';
+export type { FromEveryMetadata } from './fromEvery';

package/Projections/modelBound/join.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 'reflect-metadata';
+import { TypeIntrospector } from '../../types';
+
+/** Metadata stored by the join property decorator. */
+export interface JoinMetadata {
+    /** The event constructor associated with this annotation. */
+    readonly eventType: Function;
+    /** The read model property name used to form the join relationship. */
+    readonly on?: string;
+    /** The event property name to read the joined value from. Defaults to the decorated property name. */
+    readonly eventPropertyName?: string;
+}
+
+const METADATA_KEY = 'chronicle:projection:join';
+
+/**
+ * Property decorator that configures a join relationship with an event type.
+ * @param eventType - The event constructor.
+ * @param on - Optional property name on the read model to join on.
+ * @param eventPropertyName - Optional event property name. Defaults to the property name.
+ * @returns A property decorator.
+ */
+export function join(eventType: Function, on?: string, eventPropertyName?: string): PropertyDecorator {
+    return (target: object, propertyKey: string | symbol) => {
+        const key = propertyKey.toString();
+        TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
+        const existing: JoinMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];
+        const metadata: JoinMetadata = { eventType, on, eventPropertyName };
+        Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target, key);
+    };
+}
+
+/**
+ * Retrieves all join metadata stored on the given property.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns An array of join metadata entries.
+ */
+export function getJoinMetadata(target: object, propertyKey: string): JoinMetadata[] {
+    return Reflect.getMetadata(METADATA_KEY, target, propertyKey) ?? [];
+}

package/Projections/modelBound/modelBound.ts

@@ -0,0 +1,59 @@
+// 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 { ProjectionId } from '../ProjectionId';
+import { DecoratorType, TypeDiscoverer } from '../../types';
+
+/** Metadata key used to store model-bound projection information on a class. */
+const MODEL_BOUND_METADATA_KEY = 'chronicle:modelBound';
+
+/**
+ * Metadata stored on a model-bound projection class.
+ */
+export interface ModelBoundMetadata {
+    /** The unique identifier for the projection. */
+    readonly id: ProjectionId;
+
+    /** The optional explicit event sequence identifier. */
+    readonly eventSequenceId: string | undefined;
+}
+
+/**
+ * TypeScript decorator that marks a class as a model-bound projection.
+ * @param id - The unique identifier for the projection. Defaults to the class name if omitted.
+ * @param eventSequenceId - Optional explicit event sequence identifier.
+ * @returns A class decorator.
+ */
+export function modelBound(id: string = '', eventSequenceId?: string): ClassDecorator {
+    return (target: object) => {
+        const constructor = target as Function;
+        const projectionId = new ProjectionId(id || constructor.name);
+        const metadata: ModelBoundMetadata = { id: projectionId, eventSequenceId };
+        Reflect.defineMetadata(MODEL_BOUND_METADATA_KEY, metadata, target);
+        TypeDiscoverer.default.register(
+            DecoratorType.ModelBoundProjection,
+            constructor as Constructor,
+            projectionId.value
+        );
+    };
+}
+
+/**
+ * Gets the {@link ModelBoundMetadata} associated with a class decorated with {@link modelBound}.
+ * @param target - The class constructor to retrieve metadata for.
+ * @returns The associated metadata, or undefined if not decorated.
+ */
+export function getModelBoundMetadata(target: Function): ModelBoundMetadata | undefined {
+    return Reflect.getMetadata(MODEL_BOUND_METADATA_KEY, target);
+}
+
+/**
+ * Checks whether a class has been decorated with {@link modelBound}.
+ * @param target - The class constructor to check.
+ * @returns True if the class has a model-bound decorator; false otherwise.
+ */
+export function isModelBound(target: Function): boolean {
+    return Reflect.hasMetadata(MODEL_BOUND_METADATA_KEY, target);
+}

package/Projections/modelBound/nested.ts

@@ -0,0 +1,29 @@
+// 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 { TypeIntrospector } from '../../types';
+
+const METADATA_KEY = 'chronicle:projection:nested';
+
+/**
+ * Property decorator that marks a single nullable property as a nested sub-projection object.
+ * The nested type should carry its own fromEvent and optionally clearWith decorators.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ */
+export function nested(target: object, propertyKey: string | symbol): void {
+    const key = propertyKey.toString();
+    TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
+    Reflect.defineMetadata(METADATA_KEY, true, target, key);
+}
+
+/**
+ * Checks whether the given property is marked as a nested sub-projection.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns True if the property is marked as nested; false otherwise.
+ */
+export function isNested(target: object, propertyKey: string): boolean {
+    return Reflect.hasMetadata(METADATA_KEY, target, propertyKey);
+}

package/Projections/modelBound/notRewindable.ts

@@ -0,0 +1,24 @@
+// 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';
+
+const METADATA_KEY = 'chronicle:projection:notRewindable';
+
+/**
+ * Class decorator that marks a model-bound projection as not rewindable.
+ * A not-rewindable projection only processes new events; it cannot replay history.
+ * @param target - The class constructor.
+ */
+export function notRewindable(target: Function): void {
+    Reflect.defineMetadata(METADATA_KEY, true, target);
+}
+
+/**
+ * Checks whether the given class is marked as not rewindable.
+ * @param target - The class constructor.
+ * @returns True if the class is marked as not rewindable; false otherwise.
+ */
+export function isNotRewindable(target: Function): boolean {
+    return Reflect.hasMetadata(METADATA_KEY, target);
+}

package/Projections/modelBound/removedWith.ts

@@ -0,0 +1,60 @@
+// 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 { TypeIntrospector } from '../../types';
+
+/** Metadata stored by the removedWith class or property decorator. */
+export interface RemovedWithMetadata {
+    /** The event constructor that triggers removal. */
+    readonly eventType: Function;
+    /** The event property name that identifies the instance to remove. Defaults to the event source identifier. */
+    readonly key?: string;
+    /** The event property name that identifies the parent instance (for children). Defaults to the event source identifier. */
+    readonly parentKey?: string;
+}
+
+const CLASS_METADATA_KEY = 'chronicle:projection:removedWith:class';
+const PROPERTY_METADATA_KEY = 'chronicle:projection:removedWith:property';
+
+/**
+ * Class or property decorator that specifies the event type that removes a read model instance or child.
+ * When used on a class, it removes the read model instance.
+ * When used on a property, it removes a child from the collection.
+ * @param eventType - The event constructor.
+ * @param key - Optional event property name used as the key to identify the instance to remove.
+ * @param parentKey - Optional event property name used as the parent key (for children only).
+ * @returns A class and property decorator.
+ */
+export function removedWith(eventType: Function, key?: string, parentKey?: string): ClassDecorator & PropertyDecorator {
+    return (target: object, propertyKey?: string | symbol) => {
+        if (propertyKey !== undefined) {
+            const propKey = propertyKey.toString();
+            TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, propKey);
+            const existing: RemovedWithMetadata[] = Reflect.getMetadata(PROPERTY_METADATA_KEY, target, propKey) ?? [];
+            Reflect.defineMetadata(PROPERTY_METADATA_KEY, [...existing, { eventType, key, parentKey }], target, propKey);
+        } else {
+            const existing: RemovedWithMetadata[] = Reflect.getMetadata(CLASS_METADATA_KEY, target) ?? [];
+            Reflect.defineMetadata(CLASS_METADATA_KEY, [...existing, { eventType, key, parentKey }], target);
+        }
+    };
+}
+
+/**
+ * Retrieves removedWith metadata stored on the given class constructor.
+ * @param target - The class constructor.
+ * @returns An array of removedWith metadata entries.
+ */
+export function getRemovedWithClassMetadata(target: Function): RemovedWithMetadata[] {
+    return Reflect.getMetadata(CLASS_METADATA_KEY, target) ?? [];
+}
+
+/**
+ * Retrieves removedWith metadata stored on the given property.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns An array of removedWith metadata entries.
+ */
+export function getRemovedWithPropertyMetadata(target: object, propertyKey: string): RemovedWithMetadata[] {
+    return Reflect.getMetadata(PROPERTY_METADATA_KEY, target, propertyKey) ?? [];
+}