@cratis/chronicle 3.0.0 → 3.1.1

package/observation/notifyReplayLifecycle.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReplayState } from '@cratis/chronicle.contracts';
+import { ICanBeNotifiedWhenPartitionReplayed } from './ICanBeNotifiedWhenPartitionReplayed';
+import { ICanBeNotifiedWhenReplay } from './ICanBeNotifiedWhenReplay';
+
+function hasReplayLifecycleHooks(instance: unknown): instance is ICanBeNotifiedWhenReplay {
+    if (typeof instance !== 'object' || instance === null) {
+        return false;
+    }
+
+    const candidate = instance as Record<string, unknown>;
+    return typeof candidate.beginReplay === 'function' && typeof candidate.endReplay === 'function';
+}
+
+function hasPartitionReplayLifecycleHooks(instance: unknown): instance is ICanBeNotifiedWhenPartitionReplayed {
+    if (typeof instance !== 'object' || instance === null) {
+        return false;
+    }
+
+    const candidate = instance as Record<string, unknown>;
+    return typeof candidate.beginReplayPartition === 'function' && typeof candidate.endReplayPartition === 'function';
+}
+
+/**
+ * Notifies a reactor/reducer instance of a replay-state transition signaled by the Chronicle Kernel,
+ * when the instance optionally implements {@link ICanBeNotifiedWhenReplay} and/or
+ * {@link ICanBeNotifiedWhenPartitionReplayed}. A no-op for {@link ReplayState.REPLAY_STATE_None} or
+ * when the instance implements neither contract.
+ * @param instance - The reactor/reducer instance to notify.
+ * @param replayState - The replay-state transition signaled for the current batch.
+ * @param partition - The partition the transition applies to, for the partition-scoped states.
+ * @returns A promise that resolves when the relevant callback (if any) has completed.
+ */
+export async function notifyReplayLifecycle(instance: unknown, replayState: ReplayState, partition: string): Promise<void> {
+    switch (replayState) {
+        case ReplayState.BeginReplay:
+            if (hasReplayLifecycleHooks(instance)) {
+                await instance.beginReplay();
+            }
+            break;
+        case ReplayState.EndReplay:
+            if (hasReplayLifecycleHooks(instance)) {
+                await instance.endReplay();
+            }
+            break;
+        case ReplayState.BeginReplayPartition:
+            if (hasPartitionReplayLifecycleHooks(instance)) {
+                await instance.beginReplayPartition(partition);
+            }
+            break;
+        case ReplayState.EndReplayPartition:
+            if (hasPartitionReplayLifecycleHooks(instance)) {
+                await instance.endReplayPartition(partition);
+            }
+            break;
+        default:
+            break;
+    }
+}

package/observation/toClientFailedPartition.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { FailedPartition as ContractsFailedPartition } from '@cratis/chronicle.contracts';
+import { fromContractsGuid } from '../connection/Guid';
+import { EventSequenceNumber } from '../eventSequences/EventSequenceNumber';
+import { FailedPartition } from './FailedPartition';
+
+/**
+ * Converts a wire {@link ContractsFailedPartition} into the client {@link FailedPartition} shape.
+ * @param failedPartition - The wire failed partition to convert.
+ * @returns The converted client failed partition.
+ */
+export function toClientFailedPartition(failedPartition: ContractsFailedPartition): FailedPartition {
+    return {
+        id: fromContractsGuid(failedPartition.Id).toString(),
+        observerId: failedPartition.ObserverId,
+        partition: failedPartition.Partition,
+        attempts: (failedPartition.Attempts ?? []).map(attempt => ({
+            occurred: new Date(attempt.Occurred?.Value ?? ''),
+            sequenceNumber: new EventSequenceNumber(attempt.SequenceNumber ?? 0n),
+            messages: attempt.Messages ?? [],
+            stackTrace: attempt.StackTrace ?? ''
+        }))
+    };
+}

package/package.json

@@ -1,9 +1,24 @@
 {
     "name": "@cratis/chronicle",
-    "version": "3.0.0",
-    "description": "TypeScript idiomatic client for Cratis Chronicle",
+    "version": "3.1.1",
+    "description": "Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle, the open-source event-sourcing database",
     "author": "Cratis",
     "license": "MIT",
+    "homepage": "https://www.cratis.io/chronicle/",
+    "keywords": [
+        "event-sourcing",
+        "eventsourcing",
+        "event-store",
+        "eventstore",
+        "cqrs",
+        "ddd",
+        "projections",
+        "grpc",
+        "typescript",
+        "nodejs",
+        "chronicle",
+        "cratis"
+    ],
     "repository": {
         "type": "git",
         "url": "git+https://github.com/Cratis/Chronicle.TypeScript.git"
@@ -81,6 +96,16 @@
             "import": "./dist/webhooks/index.js",
             "default": "./dist/webhooks/index.js"
         },
+        "./externalServices": {
+            "types": "./dist/externalServices/index.d.ts",
+            "import": "./dist/externalServices/index.js",
+            "default": "./dist/externalServices/index.js"
+        },
+        "./identities": {
+            "types": "./dist/identities/index.d.ts",
+            "import": "./dist/identities/index.js",
+            "default": "./dist/identities/index.js"
+        },
         "./observation": {
             "types": "./dist/observation/index.d.ts",
             "import": "./dist/observation/index.js",
@@ -135,7 +160,7 @@
     },
     "dependencies": {
         "@bufbuild/protobuf": "^2.12.0",
-        "@cratis/chronicle.contracts": "16.4.0",
+        "@cratis/chronicle.contracts": "17.0.0",
         "@grpc/grpc-js": "^1.14.4",
         "@opentelemetry/api": "^1.9.1",
         "nice-grpc": "^2.1.16",

package/projections/Projections.childrenAndNested.spec.ts

@@ -0,0 +1,188 @@
+// 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 { describe, expect, it, vi } from 'vitest';
+import { IClientArtifactsProvider } from '../artifacts';
+import { ChronicleConnection } from '../connection';
+import { eventType } from '../events/eventTypeDecorator';
+import { readModel } from '../readModels/readModel';
+import { childrenFrom } from './modelBound/childrenFrom';
+import { clearWith } from './modelBound/clearWith';
+import { fromEvent } from './modelBound/fromEvent';
+import { nested } from './modelBound/nested';
+import { setFrom } from './modelBound/setFrom';
+import { Projections } from './Projections';
+
+// Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
+// fixtures don't depend on the test runner's decorator-syntax support.
+
+class LineAdded {
+    productId!: string;
+    quantity!: number;
+}
+eventType()(LineAdded);
+
+class LineQuantityChanged {
+    quantity!: number;
+}
+eventType()(LineQuantityChanged);
+
+class SummaryUpdated {
+    total!: number;
+}
+eventType()(SummaryUpdated);
+
+class SummaryCleared {}
+eventType()(SummaryCleared);
+
+class NoteAdded {
+    text!: string;
+}
+eventType()(NoteAdded);
+
+class NoteCleared {}
+eventType()(NoteCleared);
+
+class TagAdded {
+    name!: string;
+}
+eventType()(TagAdded);
+
+class OrderCreated {}
+eventType()(OrderCreated);
+
+class OrderLine {
+    productId!: string;
+    quantity!: number;
+}
+setFrom(LineQuantityChanged)(OrderLine.prototype, 'quantity');
+
+class OrderSummary {
+    total!: number;
+}
+setFrom(SummaryUpdated)(OrderSummary.prototype, 'total');
+clearWith(SummaryCleared)(OrderSummary);
+
+class OrderNote {
+    text!: string;
+}
+setFrom(NoteAdded)(OrderNote.prototype, 'text');
+
+class Order {
+    id!: string;
+    lines!: OrderLine[];
+    summary!: OrderSummary | undefined;
+    note!: OrderNote | undefined;
+    tags!: string[];
+}
+childrenFrom(LineAdded, undefined, 'productId', undefined)(Order.prototype, 'lines');
+field(Array, { enumerable: true, genericArguments: [OrderLine] })(Order.prototype, 'lines');
+nested(Order.prototype, 'summary');
+field(OrderSummary)(Order.prototype, 'summary');
+nested(Order.prototype, 'note');
+field(OrderNote)(Order.prototype, 'note');
+clearWith(NoteCleared)(Order.prototype, 'note');
+childrenFrom(TagAdded)(Order.prototype, 'tags');
+fromEvent(OrderCreated)(Order);
+readModel()(Order);
+
+interface FromRecord {
+    Key: { Id: string };
+    Value: { Properties: Record<string, string>; Key: string; ParentKey: string };
+}
+
+interface ChildrenDefinition {
+    IdentifiedBy: string;
+    From: FromRecord[];
+    RemovedWith: Array<{ Key: { Id: string } }>;
+}
+
+interface BuiltDefinition {
+    Children: Record<string, ChildrenDefinition>;
+    Nested: Record<string, ChildrenDefinition>;
+}
+
+function createProjections(readModels: (new (...args: unknown[]) => unknown)[]) {
+    const registerMock = vi.fn().mockResolvedValue(undefined);
+    const registerManyMock = vi.fn().mockResolvedValue(undefined);
+    const connection = {
+        readModels: { registerMany: registerManyMock },
+        projections: { register: registerMock }
+    } as unknown as ChronicleConnection;
+
+    const clientArtifacts: IClientArtifactsProvider = {
+        eventTypes: [],
+        readModels: readModels as unknown as IClientArtifactsProvider['readModels'],
+        reactors: [],
+        reducers: [],
+        seeders: [],
+        constraints: [],
+        projections: [],
+        webhooks: [],
+        eventTypeMigrations: []
+    };
+
+    const projections = new Projections('test-store', connection, clientArtifacts, 'test-sink');
+    return { projections, registerMock };
+}
+
+describe('Projections with childrenFrom, nested and clearWith', () => {
+    describe('when registering a model-bound projection using them', () => {
+        it('should not throw', async () => {
+            const { projections } = createProjections([Order]);
+            await expect(projections.register()).resolves.not.toThrow();
+        });
+
+        it('should build a children definition with the resolved child type wired up', async () => {
+            const { projections, registerMock } = createProjections([Order]);
+            await projections.register();
+
+            const definition = registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition;
+            const lines = definition.Children.lines;
+
+            expect(lines.IdentifiedBy).toBe('productId');
+            const creationEntry = lines.From.find(candidate => candidate.Key.Id === 'LineAdded')!;
+            expect(creationEntry.Value.Key).toBe('$eventSourceId');
+            expect(creationEntry.Value.ParentKey).toBe('$eventSourceId');
+
+            const updateEntry = lines.From.find(candidate => candidate.Key.Id === 'LineQuantityChanged')!;
+            expect(updateEntry.Value.Properties.quantity).toBe('quantity');
+        });
+
+        it('should build a children definition even when the child element type cannot be resolved', async () => {
+            const { projections, registerMock } = createProjections([Order]);
+            await projections.register();
+
+            const definition = registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition;
+            const tags = definition.Children.tags;
+
+            expect(tags.From.some(candidate => candidate.Key.Id === 'TagAdded')).toBe(true);
+        });
+
+        it('should build a nested definition honoring a class-level clearWith on the nested type', async () => {
+            const { projections, registerMock } = createProjections([Order]);
+            await projections.register();
+
+            const definition = registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition;
+            const summary = definition.Nested.summary;
+
+            const updateEntry = summary.From.find(candidate => candidate.Key.Id === 'SummaryUpdated')!;
+            expect(updateEntry.Value.Properties.total).toBe('total');
+            expect(summary.RemovedWith.some(candidate => candidate.Key.Id === 'SummaryCleared')).toBe(true);
+        });
+
+        it('should build a nested definition honoring a property-level clearWith', async () => {
+            const { projections, registerMock } = createProjections([Order]);
+            await projections.register();
+
+            const definition = registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition;
+            const note = definition.Nested.note;
+
+            const updateEntry = note.From.find(candidate => candidate.Key.Id === 'NoteAdded')!;
+            expect(updateEntry.Value.Properties.text).toBe('text');
+            expect(note.RemovedWith.some(candidate => candidate.Key.Id === 'NoteCleared')).toBe(true);
+        });
+    });
+});

package/projections/Projections.spec.ts

@@ -0,0 +1,131 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { describe, expect, it, vi } from 'vitest';
+import { IClientArtifactsProvider } from '../artifacts';
+import { ChronicleConnection } from '../connection';
+import { eventType } from '../events/eventTypeDecorator';
+import { readModel } from '../readModels/readModel';
+import { addFrom } from './modelBound/addFrom';
+import { count } from './modelBound/count';
+import { decrement } from './modelBound/decrement';
+import { fromEvent } from './modelBound/fromEvent';
+import { increment } from './modelBound/increment';
+import { subtractFrom } from './modelBound/subtractFrom';
+import { Projections } from './Projections';
+
+// Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
+// fixtures don't depend on the test runner's decorator-syntax support - they exercise exactly
+// the same decorator functions and metadata storage that `@decorator` syntax would invoke.
+
+class ItemAdded {
+    quantity!: number;
+}
+eventType()(ItemAdded);
+
+class ItemRemoved {
+    amount!: number;
+}
+eventType()(ItemRemoved);
+
+class CounterIncremented {}
+eventType()(CounterIncremented);
+
+class CounterDecremented {}
+eventType()(CounterDecremented);
+
+class ThingHappened {}
+eventType()(ThingHappened);
+
+class KeyedThingHappened {}
+eventType()(KeyedThingHappened);
+
+class Inventory {
+    id!: string;
+    total!: number;
+    totalFromNamedProperty!: number;
+    removedTotal!: number;
+    incrementedCount!: number;
+    decrementedCount!: number;
+    thingsHappenedCount!: number;
+    constantKeyedCount!: number;
+}
+addFrom(ItemAdded)(Inventory.prototype, 'total');
+addFrom(ItemAdded, 'quantity')(Inventory.prototype, 'totalFromNamedProperty');
+subtractFrom(ItemRemoved, 'amount')(Inventory.prototype, 'removedTotal');
+increment(CounterIncremented)(Inventory.prototype, 'incrementedCount');
+decrement(CounterDecremented)(Inventory.prototype, 'decrementedCount');
+count(ThingHappened)(Inventory.prototype, 'thingsHappenedCount');
+count(KeyedThingHappened, 'all-things')(Inventory.prototype, 'constantKeyedCount');
+fromEvent(ItemAdded)(Inventory);
+readModel()(Inventory);
+
+/**
+ * Builds a {@link Projections} instance wired to capture the registration payload sent
+ * to the kernel, without requiring a real gRPC connection.
+ */
+function createProjections(readModels: (new (...args: unknown[]) => unknown)[]) {
+    const registerMock = vi.fn().mockResolvedValue(undefined);
+    const registerManyMock = vi.fn().mockResolvedValue(undefined);
+    const connection = {
+        readModels: { registerMany: registerManyMock },
+        projections: { register: registerMock }
+    } as unknown as ChronicleConnection;
+
+    const clientArtifacts: IClientArtifactsProvider = {
+        eventTypes: [],
+        readModels: readModels as unknown as IClientArtifactsProvider['readModels'],
+        reactors: [],
+        reducers: [],
+        seeders: [],
+        constraints: [],
+        projections: [],
+        webhooks: [],
+        eventTypeMigrations: []
+    };
+
+    const projections = new Projections('test-store', connection, clientArtifacts, 'test-sink');
+    return { projections, registerMock };
+}
+
+function findFromEntry(definition: { From: Array<{ Key: { Id: string }; Value: { Properties: Record<string, string>; Key: string } }> }, eventTypeId: string) {
+    const entry = definition.From.find(candidate => candidate.Key.Id === eventTypeId);
+    if (!entry) {
+        throw new Error(`No From entry found for event type '${eventTypeId}'.`);
+    }
+    return entry;
+}
+
+describe('Projections', () => {
+    describe('when registering a model-bound projection with arithmetic decorators', () => {
+        it('should not throw and should produce the correct wire expressions', async () => {
+            const { projections, registerMock } = createProjections([Inventory]);
+
+            await expect(projections.register()).resolves.not.toThrow();
+
+            const request = registerMock.mock.calls[0][0] as { Projections: unknown[] };
+            const definition = request.Projections[0] as { From: Array<{ Key: { Id: string }; Value: { Properties: Record<string, string>; Key: string } }> };
+
+            const itemAdded = findFromEntry(definition, 'ItemAdded');
+            expect(itemAdded.Value.Properties.total).toBe('$add(total)');
+            expect(itemAdded.Value.Properties.totalFromNamedProperty).toBe('$add(quantity)');
+
+            const itemRemoved = findFromEntry(definition, 'ItemRemoved');
+            expect(itemRemoved.Value.Properties.removedTotal).toBe('$subtract(amount)');
+
+            const counterIncremented = findFromEntry(definition, 'CounterIncremented');
+            expect(counterIncremented.Value.Properties.incrementedCount).toBe('$increment');
+
+            const counterDecremented = findFromEntry(definition, 'CounterDecremented');
+            expect(counterDecremented.Value.Properties.decrementedCount).toBe('$decrement');
+
+            const thingHappened = findFromEntry(definition, 'ThingHappened');
+            expect(thingHappened.Value.Properties.thingsHappenedCount).toBe('$count');
+
+            const keyedThingHappened = findFromEntry(definition, 'KeyedThingHappened');
+            expect(keyedThingHappened.Value.Properties.constantKeyedCount).toBe('$count');
+            expect(keyedThingHappened.Value.Key).toBe('$value(all-things)');
+        });
+    });
+});