@cratis/chronicle 6.27.0 → 6.28.0

package/connection/ChronicleConnection.auth.spec.ts

@@ -1,7 +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 { afterEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest';
 import { createServer, ServerError, type ServiceImplementation } from 'nice-grpc';
 import { ConnectionServiceDefinition, EventStoresDefinition, ServerDefinition } from '@cratis/chronicle.contracts';
 import { status } from '@grpc/grpc-js';
@@ -233,20 +233,24 @@ describe('ChronicleConnection authentication', () => {
 
     it('keeps retrying proxy 403 responses without an OAuth error code', async () => {
         const random = vi.spyOn(Math, 'random').mockReturnValue(0);
-        const checks = vi.fn();
+        // Restore even when the test times out, so a hang cannot leak the stub into later tests.
+        onTestFinished(() => random.mockRestore());
+        let fourthCheck!: () => void;
+        const reachedFourthCheck = new Promise<void>(resolve => fourthCheck = resolve);
+        const checks = vi.fn(() => { if (checks.mock.calls.length === 4) fourthCheck(); });
         const port = await listenAuthenticated(checks);
         fetchToken.mockRejectedValue(new OAuthTokenHttpError(403, '<html>blocked</html>'));
         const client = new ChronicleClient(ChronicleOptions.fromConnectionString(`chronicle://user:secret@127.0.0.1:${port}?disableTls=true`, { discoveryPatterns: [] }));
         clients.push(client);
-        const pending = client.getEventStores().then(() => undefined, error => error as Error);
-        try {
-            await new Promise(resolve => setTimeout(resolve, 3900));
-            expect(checks.mock.calls.length).toBeGreaterThanOrEqual(4);
-            client.dispose();
-            expect((await pending).message).toMatch(/disposed/);
-        } finally {
-            random.mockRestore();
-        }
+        let settled = false;
+        const pending = client.getEventStores().then(() => undefined, error => error as Error).finally(() => settled = true);
+        // Wait for the fourth attempt itself rather than a wall-clock window; a credential
+        // rejection would stop after three attempts and settle the call instead.
+        await Promise.race([reachedFourthCheck, pending]);
+        expect(settled).toBe(false);
+        expect(checks.mock.calls.length).toBeGreaterThanOrEqual(4);
+        client.dispose();
+        expect((await pending).message).toMatch(/disposed/);
     }, 15000);
 
     it('rejects an API key after three unauthenticated kernel responses', async () => {

package/dist/projections/modelBound/childrenFrom.d.ts

@@ -13,6 +13,25 @@ export interface ChildrenFromMetadata {
     /** The event property name used as the parent key. Defaults to the event source identifier. */
     readonly parentKey?: string;
 }
+/** Options for the options form of the childrenFrom property decorator. */
+export interface ChildrenFromOptions {
+    /** The child type, for TypeScript runtimes without emitted generic metadata. */
+    readonly childType?: 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;
+}
+/**
+ * Property decorator that configures a children collection sub-projection from an event type.
+ * Use this form to name the child type and an explicit child key together.
+ * @param eventType - The event constructor.
+ * @param options - The child type, key, identifiedBy and parentKey.
+ * @returns A property decorator.
+ */
+export declare function childrenFrom(eventType: Function, options: ChildrenFromOptions): ChroniclePropertyDecorator;
 /**
  * Property decorator that configures a children collection sub-projection from an event type.
  * @param eventType - The event constructor.

package/dist/projections/modelBound/childrenFrom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"childrenFrom.d.ts","sourceRoot":"","sources":["../../../projections/modelBound/childrenFrom.ts"],"names":[],"mappings":"AAGA,OAAO,kBAAkB,CAAC;AAG1B,OAAO,EAAE,0BAA0B,EAAuB,MAAM,0CAA0C,CAAC;AAE3G,8DAA8D;AAC9D,MAAM,WAAW,oBAAoB;IACjC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID;;;;;;;GAOG;AACH,wBAAgB,YAAY,CACxB,SAAS,EAAE,QAAQ,EACnB,GAAG,CAAC,EAAE,MAAM,GAAG,QAAQ,EACvB,YAAY,CAAC,EAAE,MAAM,EACrB,SAAS,CAAC,EAAE,MAAM,GACnB,0BAA0B,CAW5B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAEnG"}
+{"version":3,"file":"childrenFrom.d.ts","sourceRoot":"","sources":["../../../projections/modelBound/childrenFrom.ts"],"names":[],"mappings":"AAGA,OAAO,kBAAkB,CAAC;AAG1B,OAAO,EAAE,0BAA0B,EAAuB,MAAM,0CAA0C,CAAC;AAE3G,8DAA8D;AAC9D,MAAM,WAAW,oBAAoB;IACjC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAChC,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,mBAAmB,GAAG,0BAA0B,CAAC;AAC5G;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,QAAQ,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,0BAA0B,CAAC;AAkClJ;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAEnG"}

package/dist/projections/modelBound/childrenFrom.js

@@ -5,26 +5,27 @@ import { TypeIntrospector } from '../../types/index.js';
 import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
 import { getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 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, or the child constructor.
- * @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, key, identifiedBy, parentKey) {
+export function childrenFrom(eventType, keyOrOptions, identifiedBy, parentKey) {
+    const metadata = toMetadata(eventType, keyOrOptions, identifiedBy, parentKey);
     return decorateModelBoundProperty((target, propertyKey) => {
         const propKey = propertyKey.toString();
         TypeIntrospector.trackProperty(target.constructor, propKey);
         const existing = Reflect.getMetadata(METADATA_KEY, target, propKey) ?? [];
-        const metadata = {
-            eventType, key: typeof key === 'string' ? key : undefined,
-            childType: typeof key === 'function' ? key : undefined, identifiedBy, parentKey
-        };
         Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target, propKey);
     });
 }
+function toMetadata(eventType, keyOrOptions, identifiedBy, parentKey) {
+    if (typeof keyOrOptions === 'object' && keyOrOptions !== null) {
+        return {
+            eventType, childType: keyOrOptions.childType, key: keyOrOptions.key,
+            identifiedBy: keyOrOptions.identifiedBy, parentKey: keyOrOptions.parentKey
+        };
+    }
+    return {
+        eventType, key: typeof keyOrOptions === 'string' ? keyOrOptions : undefined,
+        childType: typeof keyOrOptions === 'function' ? keyOrOptions : undefined, identifiedBy, parentKey
+    };
+}
 /**
  * Retrieves all childrenFrom metadata stored on the given property.
  * @param target - The class prototype.

package/dist/projections/modelBound/childrenFrom.js.map

@@ -1 +1 @@
-{"version":3,"file":"childrenFrom.js","sourceRoot":"","sources":["../../../projections/modelBound/childrenFrom.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAC/E,OAAO,EAA8B,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAgB3G,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAEzD;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CACxB,SAAmB,EACnB,GAAuB,EACvB,YAAqB,EACrB,SAAkB;IAElB,OAAO,0BAA0B,CAAC,CAAC,MAAc,EAAE,WAA4B,EAAE,EAAE;QAC/E,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,EAAE,CAAC;QACvC,gBAAgB,CAAC,aAAa,CAAE,MAAoC,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAC3F,MAAM,QAAQ,GAA2B,OAAO,CAAC,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;QAClG,MAAM,QAAQ,GAAyB;YACnC,SAAS,EAAE,GAAG,EAAE,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS;YACzD,SAAS,EAAE,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS;SAClF,CAAC;QACF,OAAO,CAAC,cAAc,CAAC,YAAY,EAAE,CAAC,GAAG,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACnF,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc,EAAE,WAAmB;IACvE,OAAO,mBAAmB,CAAyB,YAAY,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;AAChG,CAAC"}
+{"version":3,"file":"childrenFrom.js","sourceRoot":"","sources":["../../../projections/modelBound/childrenFrom.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAC/E,OAAO,EAA8B,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AA4B3G,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAmBzD,MAAM,UAAU,YAAY,CACxB,SAAmB,EACnB,YAAsD,EACtD,YAAqB,EACrB,SAAkB;IAElB,MAAM,QAAQ,GAAG,UAAU,CAAC,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;IAC9E,OAAO,0BAA0B,CAAC,CAAC,MAAc,EAAE,WAA4B,EAAE,EAAE;QAC/E,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,EAAE,CAAC;QACvC,gBAAgB,CAAC,aAAa,CAAE,MAAoC,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAC3F,MAAM,QAAQ,GAA2B,OAAO,CAAC,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;QAClG,OAAO,CAAC,cAAc,CAAC,YAAY,EAAE,CAAC,GAAG,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACnF,CAAC,CAAC,CAAC;AACP,CAAC;AAED,SAAS,UAAU,CACf,SAAmB,EACnB,YAAiE,EACjE,YAAgC,EAChC,SAA6B;IAE7B,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC5D,OAAO;YACH,SAAS,EAAE,SAAS,EAAE,YAAY,CAAC,SAAS,EAAE,GAAG,EAAE,YAAY,CAAC,GAAG;YACnE,YAAY,EAAE,YAAY,CAAC,YAAY,EAAE,SAAS,EAAE,YAAY,CAAC,SAAS;SAC7E,CAAC;IACN,CAAC;IACD,OAAO;QACH,SAAS,EAAE,GAAG,EAAE,OAAO,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS;QAC3E,SAAS,EAAE,OAAO,YAAY,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS;KACpG,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc,EAAE,WAAmB;IACvE,OAAO,mBAAmB,CAAyB,YAAY,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;AAChG,CAAC"}

package/dist/projections/modelBound/index.d.ts

@@ -18,7 +18,7 @@ export type { DecrementMetadata } from './decrement.js';
 export { count, getCountMetadata } from './count.js';
 export type { CountMetadata } from './count.js';
 export { childrenFrom, getChildrenFromMetadata } from './childrenFrom.js';
-export type { ChildrenFromMetadata } from './childrenFrom.js';
+export type { ChildrenFromMetadata, ChildrenFromOptions } from './childrenFrom.js';
 export { nested, isNested } from './nested.js';
 export { clearWith, getClearWithClassMetadata, getClearWithPropertyMetadata } from './clearWith.js';
 export type { ClearWithMetadata } from './clearWith.js';

package/dist/projections/modelBound/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../projections/modelBound/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../projections/modelBound/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.27.0",
+    "version": "6.28.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/projections/Projections.childrenFromOptions.spec.ts

@@ -0,0 +1,118 @@
+// 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 { field } from '@cratis/fundamentals';
+import { chai, describe, it, vi } from 'vitest';
+import { IClientArtifactsProvider } from '../artifacts/index.js';
+import { ChronicleConnection } from '../connection/index.js';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { childrenFrom } from './modelBound/childrenFrom.js';
+import { fromEvent } from './modelBound/fromEvent.js';
+import { Projections } from './Projections.js';
+
+chai.should();
+
+class KeyedItemAdded {
+    itemId = '';
+    orderId = '';
+    name = '';
+}
+eventType()(KeyedItemAdded);
+
+class KeyedOrderCreated {}
+eventType()(KeyedOrderCreated);
+
+// No @field metadata on any collection: the child type comes only from the options.
+class KeyedItem {
+    id = '';
+    sku = '';
+    name = '';
+}
+
+class KeyedOrder {
+    byKey: KeyedItem[] = [];
+    byIdentifiedBy: KeyedItem[] = [];
+    byParentKey: KeyedItem[] = [];
+    byKeyAndIdentifiedBy: KeyedItem[] = [];
+    byKeyAndParentKey: KeyedItem[] = [];
+    byAll: KeyedItem[] = [];
+    byFieldMetadata: KeyedItem[] = [];
+}
+childrenFrom(KeyedItemAdded, { childType: KeyedItem, key: 'itemId' })(KeyedOrder.prototype, 'byKey');
+childrenFrom(KeyedItemAdded, { childType: KeyedItem, identifiedBy: 'sku' })(KeyedOrder.prototype, 'byIdentifiedBy');
+childrenFrom(KeyedItemAdded, { childType: KeyedItem, parentKey: 'orderId' })(KeyedOrder.prototype, 'byParentKey');
+childrenFrom(KeyedItemAdded, { childType: KeyedItem, key: 'itemId', identifiedBy: 'sku' })(KeyedOrder.prototype, 'byKeyAndIdentifiedBy');
+childrenFrom(KeyedItemAdded, { childType: KeyedItem, key: 'itemId', parentKey: 'orderId' })(KeyedOrder.prototype, 'byKeyAndParentKey');
+childrenFrom(KeyedItemAdded, { childType: KeyedItem, key: 'itemId', identifiedBy: 'sku', parentKey: 'orderId' })(KeyedOrder.prototype, 'byAll');
+childrenFrom(KeyedItemAdded, { key: 'itemId' })(KeyedOrder.prototype, 'byFieldMetadata');
+field(Array, { enumerable: true, genericArguments: [KeyedItem] })(KeyedOrder.prototype, 'byFieldMetadata');
+fromEvent(KeyedOrderCreated)(KeyedOrder);
+
+interface ChildrenDefinition {
+    IdentifiedBy: string;
+    From: Array<{ Key: { Id: string }; Value: { Key: string; ParentKey: string; Properties: Record<string, string> } }>;
+}
+
+async function registeredChildren(): Promise<Record<string, ChildrenDefinition>> {
+    const register = vi.fn().mockResolvedValue(undefined);
+    const connection = {
+        readModels: { registerMany: vi.fn().mockResolvedValue(undefined) },
+        projections: { register }
+    } as unknown as ChronicleConnection;
+    const artifacts = {
+        eventTypes: [], readModels: [KeyedOrder], reactors: [], reducers: [], seeders: [], constraints: [],
+        projections: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+    } as unknown as IClientArtifactsProvider;
+    await new Projections('test-store', 'test-namespace', connection, artifacts, 'test-sink').register();
+    return register.mock.calls[0][0].Projections[0].Children;
+}
+
+function creation(children: Record<string, ChildrenDefinition>, property: string) {
+    const child = children[property];
+    const entry = child.From.find(candidate => candidate.Key.Id === 'KeyedItemAdded')!;
+    return { identifiedBy: child.IdentifiedBy, key: entry.Value.Key, parentKey: entry.Value.ParentKey, properties: entry.Value.Properties };
+}
+
+describe('when registering childrenFrom with the options form', () => {
+    it('should key children by the event property and map the discovered identifier from it', async () => {
+        creation(await registeredChildren(), 'byKey').should.deep.equal({
+            identifiedBy: 'id', key: 'itemId', parentKey: '$eventSourceId', properties: { id: 'itemId' }
+        });
+    });
+
+    it('should use an explicit identifiedBy with the default event source key', async () => {
+        creation(await registeredChildren(), 'byIdentifiedBy').should.deep.equal({
+            identifiedBy: 'sku', key: '$eventSourceId', parentKey: '$eventSourceId', properties: { sku: '$eventContext(EventSourceId)' }
+        });
+    });
+
+    it('should use an explicit parent key with the default child key', async () => {
+        creation(await registeredChildren(), 'byParentKey').should.deep.equal({
+            identifiedBy: 'id', key: '$eventSourceId', parentKey: 'orderId', properties: { id: '$eventContext(EventSourceId)' }
+        });
+    });
+
+    it('should map an explicit identifiedBy from an explicit key', async () => {
+        creation(await registeredChildren(), 'byKeyAndIdentifiedBy').should.deep.equal({
+            identifiedBy: 'sku', key: 'itemId', parentKey: '$eventSourceId', properties: { sku: 'itemId' }
+        });
+    });
+
+    it('should combine an explicit key and parent key', async () => {
+        creation(await registeredChildren(), 'byKeyAndParentKey').should.deep.equal({
+            identifiedBy: 'id', key: 'itemId', parentKey: 'orderId', properties: { id: 'itemId' }
+        });
+    });
+
+    it('should combine key, identifiedBy and parent key', async () => {
+        creation(await registeredChildren(), 'byAll').should.deep.equal({
+            identifiedBy: 'sku', key: 'itemId', parentKey: 'orderId', properties: { sku: 'itemId' }
+        });
+    });
+
+    it('should emit the same definition when the child type comes from field metadata', async () => {
+        const children = await registeredChildren();
+        creation(children, 'byFieldMetadata').should.deep.equal(creation(children, 'byKey'));
+    });
+});

package/projections/modelBound/childrenFrom.ts

@@ -20,8 +20,28 @@ export interface ChildrenFromMetadata {
     readonly parentKey?: string;
 }
 
+/** Options for the options form of the childrenFrom property decorator. */
+export interface ChildrenFromOptions {
+    /** The child type, for TypeScript runtimes without emitted generic metadata. */
+    readonly childType?: 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.
+ * Use this form to name the child type and an explicit child key together.
+ * @param eventType - The event constructor.
+ * @param options - The child type, key, identifiedBy and parentKey.
+ * @returns A property decorator.
+ */
+export function childrenFrom(eventType: Function, options: ChildrenFromOptions): ChroniclePropertyDecorator;
 /**
  * Property decorator that configures a children collection sub-projection from an event type.
  * @param eventType - The event constructor.
@@ -30,24 +50,40 @@ const METADATA_KEY = 'chronicle:projection:childrenFrom';
  * @param parentKey - Optional event property name used as the parent key.
  * @returns A property decorator.
  */
+export function childrenFrom(eventType: Function, key?: string | Function, identifiedBy?: string, parentKey?: string): ChroniclePropertyDecorator;
 export function childrenFrom(
     eventType: Function,
-    key?: string | Function,
+    keyOrOptions?: string | Function | ChildrenFromOptions,
     identifiedBy?: string,
     parentKey?: string
 ): ChroniclePropertyDecorator {
+    const metadata = toMetadata(eventType, keyOrOptions, identifiedBy, parentKey);
     return decorateModelBoundProperty((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: typeof key === 'string' ? key : undefined,
-            childType: typeof key === 'function' ? key : undefined, identifiedBy, parentKey
-        };
         Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target, propKey);
     });
 }
 
+function toMetadata(
+    eventType: Function,
+    keyOrOptions: string | Function | ChildrenFromOptions | undefined,
+    identifiedBy: string | undefined,
+    parentKey: string | undefined
+): ChildrenFromMetadata {
+    if (typeof keyOrOptions === 'object' && keyOrOptions !== null) {
+        return {
+            eventType, childType: keyOrOptions.childType, key: keyOrOptions.key,
+            identifiedBy: keyOrOptions.identifiedBy, parentKey: keyOrOptions.parentKey
+        };
+    }
+    return {
+        eventType, key: typeof keyOrOptions === 'string' ? keyOrOptions : undefined,
+        childType: typeof keyOrOptions === 'function' ? keyOrOptions : undefined, identifiedBy, parentKey
+    };
+}
+
 /**
  * Retrieves all childrenFrom metadata stored on the given property.
  * @param target - The class prototype.

package/projections/modelBound/index.ts

@@ -21,7 +21,7 @@ export type { DecrementMetadata } from './decrement.js';
 export { count, getCountMetadata } from './count.js';
 export type { CountMetadata } from './count.js';
 export { childrenFrom, getChildrenFromMetadata } from './childrenFrom.js';
-export type { ChildrenFromMetadata } from './childrenFrom.js';
+export type { ChildrenFromMetadata, ChildrenFromOptions } from './childrenFrom.js';
 export { nested, isNested } from './nested.js';
 export { clearWith, getClearWithClassMetadata, getClearWithPropertyMetadata } from './clearWith.js';
 export type { ClearWithMetadata } from './clearWith.js';

package/testing/ReadModelScenario.childrenFrom.spec.ts

@@ -0,0 +1,35 @@
+// 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 { eventType } from '../events/eventTypeDecorator.js';
+import { childrenFrom } from '../projections/modelBound/childrenFrom.js';
+import { fromEvent } from '../projections/modelBound/fromEvent.js';
+import { ReadModelScenario, UnsupportedProjectionOperation } from './index.js';
+
+chai.should();
+
+class ScenarioItemAdded {
+    itemId = '';
+    name = '';
+}
+eventType('scenario-keyed-item-added')(ScenarioItemAdded);
+
+class ScenarioItem {
+    id = '';
+    name = '';
+}
+
+class ScenarioOrder {
+    items: ScenarioItem[] = [];
+}
+childrenFrom(ScenarioItemAdded, { childType: ScenarioItem, key: 'itemId' })(ScenarioOrder.prototype, 'items');
+fromEvent(ScenarioItemAdded)(ScenarioOrder);
+
+describe('when a read model scenario evaluates keyed children from the options form', () => {
+    it('should reject children projections explicitly when the scenario is created', () => {
+        (() => new ReadModelScenario(ScenarioOrder, { eventTypes: [ScenarioItemAdded], reducers: [], projections: [] }))
+            .should.throw(UnsupportedProjectionOperation)
+            .with.property('message').that.includes('Children.items (@childrenFrom)').and.includes('children projections');
+    });
+});