@cratis/chronicle 6.14.0 → 6.14.2

package/for_ChronicleClient/when_registering_artifacts/with_standard_property_mappings.standard.spec.ts

@@ -0,0 +1,138 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { field } from '@cratis/fundamentals';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ChronicleClient } from '../../ChronicleClient.js';
+import { ChronicleOptions } from '../../ChronicleOptions.js';
+import type { EventStore } from '../../EventStore.js';
+import { childrenFrom } from '../../projections/modelBound/childrenFrom.js';
+import { fromEvent } from '../../projections/modelBound/fromEvent.js';
+import { setFrom } from '../../projections/modelBound/setFrom.js';
+import { DecoratorType } from '../../types/DecoratorType.js';
+import { TypeDiscoverer } from '../../types/TypeDiscoverer.js';
+
+class Changed {}
+
+function createClient() {
+    const client = new ChronicleClient(ChronicleOptions.fromConnectionString('chronicle://localhost:35000', { discoveryPatterns: [] }));
+    const warn = vi.spyOn(client['_logger'], 'warn');
+    const registerArtifacts = vi.fn().mockResolvedValue(undefined);
+    const store = { name: { value: 'store' }, namespace: { value: 'Default' }, registerArtifacts } as unknown as EventStore;
+    return { client, warn, store, registerArtifacts };
+}
+
+afterEach(() => {
+    TypeDiscoverer.default.clear();
+});
+
+describe('when registering artifacts with standard property mappings', () => {
+    it('should warn once about orphan mappings with their property and event type', async () => {
+        const discoverer = new TypeDiscoverer(async () => ['model.ts'], async () => {
+            class Orphan {
+                @setFrom(Changed) value = '';
+                @setFrom(Changed) name = '';
+            }
+            class OtherOrphan { @setFrom(Changed) value = ''; }
+            void Orphan;
+            void OtherOrphan;
+            return {};
+        });
+        await discoverer.discover('model.ts');
+        const { client, warn, store, registerArtifacts } = createClient();
+        try {
+            await client['registerArtifactsForStore'](store, 'new-store');
+            await client['registerArtifactsForStore'](store, 'new-store');
+            expect(warn).toHaveBeenCalledTimes(1);
+            expect(warn.mock.calls[0][0]).toContain('{value <- Changed, name <- Changed}, {value <- Changed}');
+            expect(warn.mock.calls[0][0]).toContain('@fromEvent(...)');
+            expect(warn.mock.calls[0][0]).toContain('discoveryPatterns');
+            expect(warn.mock.calls[0][0]).toContain('register the class explicitly');
+            expect(registerArtifacts).toHaveBeenCalledTimes(2);
+        } finally {
+            client.dispose();
+        }
+    });
+
+    it('should not warn after the first instance registers the model before store creation', async () => {
+        class Constructed { @setFrom(Changed) value = ''; }
+        new Constructed();
+        const { client, warn, store } = createClient();
+        try {
+            await client['registerArtifactsForStore'](store, 'new-store');
+            expect(warn).not.toHaveBeenCalled();
+        } finally {
+            client.dispose();
+        }
+    });
+
+    it('should not warn for a discovered export', async () => {
+        class Discovered { @setFrom(Changed) value = ''; }
+        const discoverer = new TypeDiscoverer(async () => ['model.ts'], async () => ({ Discovered }));
+        await discoverer.discover('model.ts');
+        const { client, warn, store } = createClient();
+        try {
+            await client['registerArtifactsForStore'](store, 'new-store');
+            expect(warn).not.toHaveBeenCalled();
+        } finally {
+            client.dispose();
+        }
+    });
+
+    it('should not warn for an unexported base class of a discovered model', async () => {
+        class Base { @setFrom(Changed) value = ''; }
+        class Derived extends Base {}
+        const discoverer = new TypeDiscoverer(async () => ['model.ts'], async () => ({ Derived }));
+        await discoverer.discover('model.ts');
+        const { client, warn, store } = createClient();
+        try {
+            await client['registerArtifactsForStore'](store, 'new-store');
+            expect(warn).not.toHaveBeenCalled();
+        } finally {
+            client.dispose();
+        }
+    });
+
+    it('should not warn for an unexported child of a discovered model', async () => {
+        class Line { @setFrom(Changed) value = ''; }
+        class Cart {
+            @childrenFrom(Changed)
+            @field(Array, { genericArguments: [Line] })
+            lines: Line[] = [];
+        }
+        const discoverer = new TypeDiscoverer(async () => ['model.ts'], async () => ({ Cart }));
+        await discoverer.discover('model.ts');
+        const { client, warn, store } = createClient();
+        try {
+            await client['registerArtifactsForStore'](store, 'new-store');
+            expect(warn).not.toHaveBeenCalled();
+        } finally {
+            client.dispose();
+        }
+    });
+
+    it('should not warn for an explicitly registered class', async () => {
+        class Explicit { @setFrom(Changed) value = ''; }
+        TypeDiscoverer.default.register(DecoratorType.ReadModel, Explicit);
+        const { client, warn, store } = createClient();
+        try {
+            await client['registerArtifactsForStore'](store, 'new-store');
+            expect(warn).not.toHaveBeenCalled();
+        } finally {
+            client.dispose();
+        }
+    });
+
+    it('should not warn for a class-level model mapping', async () => {
+        @fromEvent(Changed)
+        class ClassMapped { @setFrom(Changed) value = ''; }
+        const { client, warn, store } = createClient();
+        try {
+            await client['registerArtifactsForStore'](store, 'new-store');
+            expect(warn).not.toHaveBeenCalled();
+            void ClassMapped;
+        } finally {
+            client.dispose();
+        }
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.14.0",
+    "version": "6.14.2",
     "description": "Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle, the open-source event-sourcing database",
     "author": "Cratis",
     "license": "MIT",
@@ -167,7 +167,7 @@
         "build": "tsc -b",
         "clean": "rm -rf dist",
         "test": "vitest run",
-        "test:standard-types": "tsc --ignoreConfig --noEmit --target es2022 --module es2022 --moduleResolution bundler --lib es2022,esnext.decorators --types node --skipLibCheck --strict schemas/decorators.standard.spec.ts projections/modelBound/decorators.standard.spec.ts events/classDecorators.standard.spec.ts reactors/decorators.standard.spec.ts readModels/standardFallbacks.standard.spec.ts artifacts/validateArtifactSchemas.spec.ts",
+        "test:standard-types": "tsc --ignoreConfig --noEmit --target es2022 --module es2022 --moduleResolution bundler --lib es2022,esnext.decorators --types node --skipLibCheck --strict schemas/decorators.standard.spec.ts projections/modelBound/decorators.standard.spec.ts events/classDecorators.standard.spec.ts reactors/decorators.standard.spec.ts readModels/standardFallbacks.standard.spec.ts readModels/registration.standard.spec.ts for_ChronicleClient/when_registering_artifacts/with_standard_property_mappings.standard.spec.ts artifacts/validateArtifactSchemas.spec.ts",
         "test:native": "node ./scripts/check-native-esm.mjs"
     },
     "dependencies": {

package/projections/CompiledProjectionDefinitions.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ProjectionDefinition } from '@cratis/chronicle.contracts';
+import type { buildReadModelDefinition } from '../readModels/buildReadModelDefinition.js';
+
+/** Connection-independent contracts produced for projection registration. */
+export interface CompiledProjectionDefinitions {
+    /** The final wire definitions, including variant cross-wiring and LastUpdated hashes. */
+    readonly definitions: ProjectionDefinition[];
+    /** Read models registered before the projections. */
+    readonly readModels: ReturnType<typeof buildReadModelDefinition>[];
+}

package/projections/ProjectionDefinitionCompiler.registration.spec.ts

@@ -0,0 +1,279 @@
+// 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 { readFileSync } from 'node:fs';
+import { field, Constructor } from '@cratis/fundamentals';
+import { chai, describe, it, vi } from 'vitest';
+import type { IClientArtifactsProvider } from '../artifacts/index.js';
+import type { ChronicleConnection } from '../connection/index.js';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { IProjectionBuilderFor } from './declarative/IProjectionBuilderFor.js';
+import { IProjectionFor } from './declarative/IProjectionFor.js';
+import { projection } from './declarative/projection.js';
+import { addFrom } from './modelBound/addFrom.js';
+import { childrenFrom } from './modelBound/childrenFrom.js';
+import { clearWith } from './modelBound/clearWith.js';
+import { count } from './modelBound/count.js';
+import { decrement } from './modelBound/decrement.js';
+import { entersOn } from './modelBound/entersOn.js';
+import { eventSequence } from './modelBound/eventSequence.js';
+import { fromAll } from './modelBound/fromAll.js';
+import { fromEvent } from './modelBound/fromEvent.js';
+import { fromEvery } from './modelBound/fromEvery.js';
+import { globalFor } from './modelBound/globalFor.js';
+import { increment } from './modelBound/increment.js';
+import { isModelBoundProjection } from './modelBound/isModelBoundProjection.js';
+import { join } from './modelBound/join.js';
+import { nested } from './modelBound/nested.js';
+import { noAutoMap } from './modelBound/noAutoMap.js';
+import { notRewindable } from './modelBound/notRewindable.js';
+import { passive } from './modelBound/passive.js';
+import { removedWith } from './modelBound/removedWith.js';
+import { removedWithJoin } from './modelBound/removedWithJoin.js';
+import { setFrom } from './modelBound/setFrom.js';
+import { setFromContext } from './modelBound/setFromContext.js';
+import { setValue } from './modelBound/setValue.js';
+import { subtractFrom } from './modelBound/subtractFrom.js';
+import { variantOf } from './modelBound/variantOf.js';
+import { ProjectionDefinitionCompiler } from './ProjectionDefinitionCompiler.js';
+import { Projections } from './Projections.js';
+
+class ItemCreated { name!: string; quantity!: number; }
+eventType()(ItemCreated);
+class ItemUpdated { name!: string; quantity!: number; }
+eventType()(ItemUpdated);
+class ItemRemoved {}
+eventType()(ItemRemoved);
+class DescriptionCleared {}
+eventType()(DescriptionCleared);
+class LineAdded { productId!: string; }
+eventType()(LineAdded);
+class Joined { name!: string; }
+eventType()(Joined);
+class Opened { title!: string; }
+eventType()(Opened);
+class Published { url!: string; }
+eventType()(Published);
+class TitleChanged { title!: string; }
+eventType()(TitleChanged);
+
+class Flat { id!: string; name!: string; }
+setFrom(ItemCreated, 'name')(Flat.prototype, 'name');
+fromEvent(ItemCreated)(Flat);
+class AutoMapped { id!: string; name!: string; quantity!: number; }
+noAutoMap(AutoMapped.prototype, 'quantity');
+fromEvent(ItemCreated)(AutoMapped);
+class Totals { id!: string; quantity!: number; removed!: number; count!: number; }
+addFrom(ItemCreated, 'quantity')(Totals.prototype, 'quantity');
+subtractFrom(ItemUpdated, 'quantity')(Totals.prototype, 'removed');
+count(ItemCreated)(Totals.prototype, 'count');
+fromEvent(ItemCreated)(Totals);
+class Removable { id!: string; name!: string; }
+fromEvent(ItemCreated)(Removable);
+removedWith(ItemRemoved)(Removable);
+class Line { productId!: string; }
+class WithChildren { id!: string; lines!: Line[]; }
+childrenFrom(LineAdded, undefined, 'productId')(WithChildren.prototype, 'lines');
+field(Array, { enumerable: true, genericArguments: [Line] })(WithChildren.prototype, 'lines');
+fromEvent(ItemCreated)(WithChildren);
+class WithJoin { id!: string; name!: string; }
+join(Joined, 'name')(WithJoin.prototype, 'name');
+fromEvent(ItemCreated)(WithJoin);
+class Every { id!: string; name!: string; }
+fromEvery('name')(Every.prototype, 'name');
+fromEvent(ItemCreated)(Every);
+
+class PassiveModel { id!: string; name!: string; }
+field(String)(PassiveModel.prototype, 'name');
+setFrom(ItemCreated, 'name')(PassiveModel.prototype, 'name');
+fromEvent(ItemCreated)(PassiveModel);
+passive(PassiveModel);
+
+class Detail { description!: string; }
+setFrom(ItemCreated, 'name')(Detail.prototype, 'description');
+clearWith(DescriptionCleared)(Detail.prototype, 'description');
+fromEvent(ItemCreated)(Detail);
+clearWith(ItemRemoved)(Detail);
+class WithNested { id!: string; detail!: Detail; title!: string; }
+field(Detail)(WithNested.prototype, 'detail');
+nested(WithNested.prototype, 'detail');
+clearWith(ItemUpdated)(WithNested.prototype, 'detail');
+clearWith(ItemRemoved)(WithNested.prototype, 'title');
+fromEvent(ItemCreated)(WithNested);
+
+class WithRemovedJoin { id!: string; name!: string; }
+removedWithJoin(ItemRemoved, 'productId')(WithRemovedJoin);
+removedWithJoin(TitleChanged, 'title')(WithRemovedJoin.prototype, 'name');
+fromEvent(ItemCreated)(WithRemovedJoin);
+
+class CustomKeys { id!: string; }
+fromEvent(ItemCreated, { key: 'productId', parentKey: 'ownerId' })(CustomKeys);
+class ConstantKeys { id!: string; }
+fromEvent(ItemCreated, { constantKey: 'one', parentKey: 'ownerId' })(ConstantKeys);
+
+class NoMapping { id!: string; name!: string; }
+noAutoMap(NoMapping);
+fromEvent(ItemCreated)(NoMapping);
+class NoRewind { id!: string; }
+notRewindable(NoRewind);
+fromEvent(ItemCreated)(NoRewind);
+class OtherSequence { id!: string; }
+eventSequence('custom-sequence')(OtherSequence);
+fromEvent(ItemCreated)(OtherSequence);
+
+class MappingOptions { id!: string; context!: string; state!: string; increments!: number; decrements!: number; all!: string; }
+field(String)(MappingOptions.prototype, 'context');
+field(Number)(MappingOptions.prototype, 'increments');
+setFromContext(ItemCreated, 'eventSourceId')(MappingOptions.prototype, 'context');
+setValue(ItemUpdated, 'ready')(MappingOptions.prototype, 'state');
+increment(ItemCreated)(MappingOptions.prototype, 'increments');
+decrement(ItemUpdated)(MappingOptions.prototype, 'decrements');
+fromAll('name')(MappingOptions.prototype, 'all');
+fromEvent(ItemCreated)(MappingOptions);
+
+class Identity {}
+class Draft { id!: string; title!: string; }
+setFrom(Opened, 'title')(Draft.prototype, 'title');
+variantOf(Identity, 'id')(Draft);
+entersOn(Opened)(Draft);
+fromEvent(Opened)(Draft);
+class Public { id!: string; url!: string; title!: string; }
+setFrom(Published, 'url')(Public.prototype, 'url');
+setFrom(TitleChanged, 'title')(Public.prototype, 'title');
+variantOf(Identity, 'id')(Public);
+entersOn(Published)(Public);
+fromEvent(Published)(Public);
+fromEvent(TitleChanged)(Public);
+class KeyedVariant { id!: string; title!: string; }
+variantOf(Identity, 'id')(KeyedVariant);
+entersOn(Opened, 'productId')(KeyedVariant);
+fromEvent(Opened)(KeyedVariant);
+class SharedTitle { title!: string; }
+setFrom(TitleChanged, 'title')(SharedTitle.prototype, 'title');
+globalFor(Identity)(SharedTitle);
+
+class Declarative { id!: string; name!: string; quantity!: number; lines!: Line[]; }
+class DeclarativeProjection implements IProjectionFor<Declarative> {
+    define(builder: IProjectionBuilderFor<Declarative>): void {
+        builder.from(ItemCreated, from => from.set(model => model.name).to(event => event.name))
+            .join(Joined, joined => joined.on(model => model.name).set(model => model.name).to(event => event.name))
+            .fromEvery(every => every.set(model => model.name).toEventContextProperty('eventType'))
+            .removedWith(ItemRemoved)
+            .children<Line>(model => model.lines, children => children.from(LineAdded))
+            .autoMap();
+    }
+}
+projection('Declarative', Declarative)(DeclarativeProjection);
+class AnotherDeclarativeProjection implements IProjectionFor<Declarative> {
+    define(builder: IProjectionBuilderFor<Declarative>): void {
+        builder.from(ItemUpdated);
+    }
+}
+projection('AnotherDeclarative', Declarative)(AnotherDeclarativeProjection);
+
+class DeclarativeDraft { id!: string; title!: string; }
+class DeclarativeDraftProjection implements IProjectionFor<DeclarativeDraft> {
+    define(builder: IProjectionBuilderFor<DeclarativeDraft>): void {
+        builder.variantOf(Identity, model => model.id).entersOn(Opened).from(Opened);
+    }
+}
+projection('DeclarativeDraft', DeclarativeDraft)(DeclarativeDraftProjection);
+class DeclarativePublic { id!: string; url!: string; }
+class DeclarativePublicProjection implements IProjectionFor<DeclarativePublic> {
+    define(builder: IProjectionBuilderFor<DeclarativePublic>): void {
+        builder.variantOf(Identity, model => model.id).entersOn(Published).from(Published).from(TitleChanged);
+    }
+}
+projection('DeclarativePublic', DeclarativePublic)(DeclarativePublicProjection);
+
+class Inferred { uniqueTitle!: string; }
+field(String)(Inferred.prototype, 'uniqueTitle');
+class InferredProjection implements IProjectionFor<Inferred> {
+    define(builder: IProjectionBuilderFor<Inferred>): void {
+        builder.from(Opened, from => from.set(model => model.uniqueTitle).to(event => event.title));
+    }
+}
+projection()(InferredProjection);
+
+const cases = [
+    { name: 'flat', readModels: [Flat], projections: [], globalForHandlers: [] },
+    { name: 'passive-with-fields', readModels: [PassiveModel], projections: [], globalForHandlers: [] },
+    { name: 'nested-and-clear', readModels: [WithNested], projections: [], globalForHandlers: [] },
+    { name: 'removed-with-join', readModels: [WithRemovedJoin], projections: [], globalForHandlers: [] },
+    { name: 'custom-keys', readModels: [CustomKeys, ConstantKeys], projections: [], globalForHandlers: [] },
+    { name: 'no-auto-map', readModels: [NoMapping], projections: [], globalForHandlers: [] },
+    { name: 'not-rewindable', readModels: [NoRewind], projections: [], globalForHandlers: [] },
+    { name: 'event-sequence', readModels: [OtherSequence], projections: [], globalForHandlers: [] },
+    { name: 'mapping-options-with-fields', readModels: [MappingOptions], projections: [], globalForHandlers: [] },
+    { name: 'enters-on-key', readModels: [KeyedVariant], projections: [], globalForHandlers: [] },
+    { name: 'declarative-inferred-with-fields', readModels: [Inferred], projections: [InferredProjection], globalForHandlers: [] },
+    { name: 'automap-exclusion', readModels: [AutoMapped], projections: [], globalForHandlers: [] },
+    { name: 'arithmetic', readModels: [Totals], projections: [], globalForHandlers: [] },
+    { name: 'removed-with', readModels: [Removable], projections: [], globalForHandlers: [] },
+    { name: 'children', readModels: [WithChildren], projections: [], globalForHandlers: [] },
+    { name: 'join', readModels: [WithJoin], projections: [], globalForHandlers: [] },
+    { name: 'from-every', readModels: [Every], projections: [], globalForHandlers: [] },
+    { name: 'model-bound-variants', readModels: [Draft, Public], projections: [], globalForHandlers: [SharedTitle] },
+    { name: 'declarative', readModels: [Declarative], projections: [DeclarativeProjection], globalForHandlers: [] },
+    { name: 'declarative-variants', readModels: [DeclarativeDraft, DeclarativePublic], projections: [DeclarativeDraftProjection, DeclarativePublicProjection], globalForHandlers: [] }
+];
+
+function artifactsFor(testCase: typeof cases[number]): IClientArtifactsProvider {
+    return {
+        projections: testCase.projections as Constructor[],
+        readModels: testCase.readModels as Constructor[],
+        globalForHandlers: testCase.globalForHandlers as Constructor[],
+        eventTypes: [ItemCreated, ItemUpdated, ItemRemoved, LineAdded, Joined, Opened, Published, TitleChanged],
+        reactors: [], reducers: [], seeders: [], constraints: [], webhooks: [], eventTypeMigrations: []
+    };
+}
+
+function serializeContract(value: unknown): string {
+    return JSON.stringify(value, (_key, member: unknown) => typeof member === 'bigint' ? member.toString() : member);
+}
+
+async function captureRegistration(artifacts: IClientArtifactsProvider): Promise<string> {
+    const registerMock = vi.fn().mockResolvedValue(undefined);
+    const registerManyMock = vi.fn().mockResolvedValue(undefined);
+    const connection = {
+        projections: { register: registerMock },
+        readModels: { registerMany: registerManyMock }
+    } as unknown as ChronicleConnection;
+    await new Projections('test-store', 'test-namespace', connection, artifacts, 'test-sink').register();
+    return serializeContract({
+        readModels: registerManyMock.mock.calls.map(call => call[0].ReadModels).flat(),
+        projections: registerMock.mock.calls.map(call => call[0].Projections).flat()
+    });
+}
+
+chai.should();
+
+const goldenUrl = new URL('./ProjectionDefinitionCompiler.registration.golden.json', import.meta.url);
+
+describe('projection registration payload', () => {
+    for (const testCase of cases) {
+        it(`should match the registration golden for ${testCase.name}`, async () => {
+            const actual = await captureRegistration(artifactsFor(testCase));
+            const goldens = JSON.parse(readFileSync(goldenUrl, 'utf8')) as Array<{ name: string; payload: string }>;
+            actual.should.equal(goldens.find(candidate => candidate.name === testCase.name)?.payload);
+        });
+
+        it(`should send the compiler's definitions and read-model schemas for ${testCase.name}`, async () => {
+            const artifacts = artifactsFor(testCase);
+            const compiled = new ProjectionDefinitionCompiler(artifacts, 'test-sink').compile(
+                artifacts.projections,
+                artifacts.readModels.filter(isModelBoundProjection)
+            );
+            const compiledPayload = serializeContract({ readModels: compiled.readModels, projections: compiled.definitions });
+            compiledPayload.should.equal(await captureRegistration(artifacts));
+        });
+    }
+
+    it('should reject multiple projections for one read model', () => {
+        const artifacts = artifactsFor(cases.find(testCase => testCase.name === 'declarative')!);
+        (() => new ProjectionDefinitionCompiler(artifacts, 'test-sink').compile(
+            [DeclarativeProjection, AnotherDeclarativeProjection], []
+        )).should.throw("Read model id 'Declarative' has multiple projections.");
+    });
+});