@cratis/chronicle 3.1.1 → 5.0.0

package/events/tagDecorator.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 { Tag } from './Tag';
+import { mergeTags } from './mergeTags';
+
+/** Metadata key used to store the tags labeling a class. */
+const TAGS_METADATA_KEY = 'chronicle:tags';
+
+/**
+ * TypeScript decorator that labels an event type, reactor, or reducer with one or more tags.
+ * This is the TypeScript equivalent of the C# `[Tag]` attribute.
+ *
+ * Applying the decorator more than once accumulates tags rather than replacing them, so
+ * `@tag('a')` followed by `@tag('b')` on the same class results in both `'a'` and `'b'`.
+ *
+ * @param values - The tags to apply.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```typescript
+ * @eventType()
+ * @tag('analytics', 'user-action')
+ * class UserLoggedIn {
+ *     constructor(readonly userId: string) {}
+ * }
+ * ```
+ */
+export function tag(...values: string[]): ClassDecorator {
+    return (target: object) => addTags(target, values);
+}
+
+/**
+ * TypeScript decorator that labels an event type, reactor, or reducer with one or more tags.
+ * This is the TypeScript equivalent of the C# `[Tags]` attribute, and behaves identically to
+ * {@link tag} - use whichever reads more naturally at the call site.
+ *
+ * @param values - The tags to apply.
+ * @returns A class decorator.
+ */
+export function tags(...values: string[]): ClassDecorator {
+    return (target: object) => addTags(target, values);
+}
+
+function addTags(target: object, values: string[]): void {
+    const existing = (Reflect.getMetadata(TAGS_METADATA_KEY, target) as Tag[] | undefined) ?? [];
+    const merged = mergeTags(existing, values).map(value => new Tag(value));
+    Reflect.defineMetadata(TAGS_METADATA_KEY, merged, target);
+}
+
+/**
+ * Gets all tags applied to a class via {@link tag} or {@link tags}.
+ * @param target - The class constructor to retrieve tags for.
+ * @returns The tags applied to the class, or an empty array if none are.
+ */
+export function getTagsFor(target: Function): Tag[] {
+    return (Reflect.getMetadata(TAGS_METADATA_KEY, target) as Tag[] | undefined) ?? [];
+}

package/jobs/Jobs.ts

@@ -4,7 +4,7 @@
 import type { JobSummaryResponse, JobStepSummaryResponse } from '@cratis/chronicle.contracts';
 import { Guid } from '@cratis/fundamentals';
 import { ChronicleConnection } from '../connection';
-import { ensureCommandSuccess, ensureQuerySuccess, firstQueryResult } from '../connection/callResults';
+import { ensureCommandSuccess, ensureQuerySuccess } from '../connection/callResults';
 import { fromContractsGuid, toContractsGuid } from '../connection/Guid';
 import { IJobs } from './IJobs';
 import { JobId } from './JobId';
@@ -49,10 +49,10 @@ export class Jobs implements IJobs {
 
     /** @inheritdoc */
     async getJobs(): Promise<JobSummaryResponse[]> {
-        const response = await firstQueryResult('get jobs', this._connection.jobs.allJobs({
+        const response = await this._connection.jobs.allJobs({
             EventStore: this._eventStore,
             Namespace: this._namespace
-        }));
+        });
 
         return ensureQuerySuccess('get jobs', response);
     }

package/observation/ObserverRunningState.ts

@@ -8,27 +8,18 @@ export enum ObserverRunningState {
     /** The observer is in an unknown state. */
     Unknown = 'Unknown',
 
-    /** The observer is subscribing to the event sequence. */
-    Subscribing = 'Subscribing',
-
-    /** The observer is replaying events from the beginning. */
-    Replaying = 'Replaying',
-
-    /** The observer is resuming after a pause. */
-    Resuming = 'Resuming',
-
-    /** The observer is actively processing events. */
+    /** The observer is active and waiting for new events. */
     Active = 'Active',
 
-    /** The observer is paused and not processing events. */
-    Paused = 'Paused',
+    /** The observer is suspended. */
+    Suspended = 'Suspended',
 
-    /** The observer has stopped processing events. */
-    Stopped = 'Stopped',
+    /** The observer is replaying. */
+    Replaying = 'Replaying',
 
-    /** The observer is in a failed state. */
-    Failed = 'Failed',
+    /** The observer is disconnected. */
+    Disconnected = 'Disconnected',
 
-    /** The observer has been disconnected. */
-    Disconnected = 'Disconnected'
+    /** The observer is quarantined. */
+    Quarantined = 'Quarantined'
 }

package/observation/index.ts

@@ -7,5 +7,6 @@ export type { FailedPartition } from './FailedPartition';
 export type { FailedPartitionAttempt } from './FailedPartitionAttempt';
 export type { IFailedPartitions } from './IFailedPartitions';
 export { FailedPartitions } from './FailedPartitions';
+export { toObserverRunningState } from './toObserverRunningState';
 export type { ICanBeNotifiedWhenReplay } from './ICanBeNotifiedWhenReplay';
 export type { ICanBeNotifiedWhenPartitionReplayed } from './ICanBeNotifiedWhenPartitionReplayed';

package/observation/toObserverRunningState.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ObserverRunningState as ContractObserverRunningState } from '@cratis/chronicle.contracts';
+import { ObserverRunningState } from './ObserverRunningState';
+
+/**
+ * Converts a wire {@link ContractObserverRunningState} into the client {@link ObserverRunningState}.
+ * @param state - The wire running state to convert.
+ * @returns The converted client running state.
+ */
+export function toObserverRunningState(state: ContractObserverRunningState): ObserverRunningState {
+    switch (state) {
+        case ContractObserverRunningState.Active:
+            return ObserverRunningState.Active;
+        case ContractObserverRunningState.Suspended:
+            return ObserverRunningState.Suspended;
+        case ContractObserverRunningState.Replaying:
+            return ObserverRunningState.Replaying;
+        case ContractObserverRunningState.OBSERVER_RUNNING_STATE_Disconnected:
+            return ObserverRunningState.Disconnected;
+        case ContractObserverRunningState.Quarantined:
+            return ObserverRunningState.Quarantined;
+        default:
+            return ObserverRunningState.Unknown;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "3.1.1",
+    "version": "5.0.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",
@@ -159,20 +159,20 @@
         "test": "vitest run"
     },
     "dependencies": {
-        "@bufbuild/protobuf": "^2.12.0",
-        "@cratis/chronicle.contracts": "17.0.0",
+        "@bufbuild/protobuf": "^2.14.1",
+        "@cratis/chronicle.contracts": "17.0.4",
         "@grpc/grpc-js": "^1.14.4",
         "@opentelemetry/api": "^1.9.1",
-        "nice-grpc": "^2.1.16",
-        "nice-grpc-common": "^2.0.3",
+        "nice-grpc": "^2.1.17",
+        "nice-grpc-common": "^2.0.4",
         "reflect-metadata": "^0.2.2",
-        "undici": "^8.7.0"
+        "undici": "^8.10.2"
     },
     "devDependencies": {
-        "@cratis/fundamentals": "7.14.0",
-        "@types/node": "^25.9.1",
+        "@cratis/fundamentals": "7.18.3",
+        "@types/node": "^26.4.1",
         "typescript": "^6.0.3",
-        "vitest": "^4.1.10"
+        "vitest": "^5.0.0"
     },
     "peerDependencies": {
         "@cratis/fundamentals": "^7.14.0"

package/projections/IProjections.ts

@@ -1,8 +1,16 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { Constructor } from '@cratis/fundamentals';
+import { FailedPartition } from '../observation/FailedPartition';
+import { JobId } from '../jobs/JobId';
+import { ProjectionId } from './ProjectionId';
+import { ProjectionQueryResult } from './ProjectionQueryResult';
+import { ProjectionState } from './ProjectionState';
+
 /**
- * Defines a system to work with projections, including discovery and registration with the Kernel.
+ * Defines a system to work with projections, including discovery, registration and operating
+ * on projections that are known to the Chronicle Kernel.
  */
 export interface IProjections {
     /**
@@ -16,4 +24,76 @@ export interface IProjections {
      * @returns A promise that resolves when registration is complete.
      */
     register(): Promise<void>;
+
+    /**
+     * Check if there is a definition for a specific projection identifier.
+     * @param projectionId - Identifier of the projection.
+     * @returns True if it exists, false if not.
+     */
+    hasFor(projectionId: ProjectionId | string): boolean;
+
+    /**
+     * Check if there is a definition for the projection that maintains a specific read model.
+     * @param readModelType - Type of read model to check for.
+     * @returns True if it exists, false if not.
+     */
+    hasForModel(readModelType: Constructor): boolean;
+
+    /**
+     * Get the {@link ProjectionId} for the projection that maintains a specific read model.
+     * @param readModelType - Type of read model to get for.
+     * @returns The {@link ProjectionId} for the read model.
+     * @remarks A model-bound projection has no projection type of its own - its read model type is the
+     * only handle it has. A declarative projection is only resolvable here when it declares its
+     * read model type explicitly (the second argument to the `projection()` decorator); one whose read
+     * model is inferred at registration time cannot be resolved before `register()` has run.
+     */
+    getProjectionIdFor(readModelType: Constructor): ProjectionId;
+
+    /**
+     * Get the state of a specific projection.
+     * @param projectionId - Identifier of the projection to get the state for.
+     * @returns The {@link ProjectionState}.
+     */
+    getStateFor(projectionId: ProjectionId | string): Promise<ProjectionState>;
+
+    /**
+     * Get the state of the projection that maintains a specific read model.
+     * @param readModelType - Type of read model to get the state for.
+     * @returns The {@link ProjectionState}.
+     */
+    getStateForModel(readModelType: Constructor): Promise<ProjectionState>;
+
+    /**
+     * Get any failed partitions for the projection that maintains a specific read model.
+     * @param readModelType - Type of read model to get for.
+     * @returns Collection of {@link FailedPartition}, if any.
+     */
+    getFailedPartitionsForModel(readModelType: Constructor): Promise<FailedPartition[]>;
+
+    /**
+     * Replay a specific projection by its identifier.
+     * @param projectionId - Identifier of the projection to replay.
+     * @returns The {@link JobId} of the replay job that was started or resumed.
+     */
+    replay(projectionId: ProjectionId | string): Promise<JobId>;
+
+    /**
+     * Replay the projection that maintains a specific read model.
+     * @param readModelType - Type of read model to replay the projection for.
+     * @returns The {@link JobId} of the replay job that was started or resumed.
+     */
+    replayForModel(readModelType: Constructor): Promise<JobId>;
+
+    /**
+     * Query a projection declaration against the event log without registering it.
+     * @param declaration - The Projection Declaration Language string to query.
+     * @param eventSequenceId - Optional event sequence identifier to query. Defaults to `"event-log"`.
+     * @returns A {@link ProjectionQueryResult} containing the resulting read model entries.
+     * @remarks The declaration may omit the `=> ReadModelType` target - in that case the read model
+     * schema is inferred from the events used in the projection. An inferred read model can never be
+     * registered as a permanent projection; query-only declarations are exclusively for ad-hoc
+     * exploration.
+     */
+    query(declaration: string, eventSequenceId?: string): Promise<ProjectionQueryResult>;
 }

package/projections/ProjectionQueryResult.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents the result of querying a projection against the event log.
+ */
+export interface ProjectionQueryResult {
+    /** Collection of JSON representations of the resulting read model entries. */
+    readonly readModelEntries: ReadonlyArray<string>;
+}

package/projections/ProjectionState.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ObserverRunningState } from '../observation/ObserverRunningState';
+import { EventSequenceNumber } from '../eventSequences/EventSequenceNumber';
+
+/**
+ * Represents the state of a projection.
+ */
+export interface ProjectionState {
+    /** The current running state of the projection. */
+    readonly runningState: ObserverRunningState;
+
+    /** Indicates whether the projection is subscribed to its handler. */
+    readonly isSubscribed: boolean;
+
+    /** The next event sequence number the projection will process. */
+    readonly nextEventSequenceNumber: EventSequenceNumber;
+
+    /** The last event sequence number the projection handled. */
+    readonly lastHandledEventSequenceNumber: EventSequenceNumber;
+
+    /** The current tail event sequence number of the event sequence the projection observes. */
+    readonly tailEventSequenceNumber: EventSequenceNumber;
+}

package/projections/Projections.childrenAndNested.spec.ts

@@ -124,7 +124,7 @@ function createProjections(readModels: (new (...args: unknown[]) => unknown)[])
         eventTypeMigrations: []
     };
 
-    const projections = new Projections('test-store', connection, clientArtifacts, 'test-sink');
+    const projections = new Projections('test-store', 'test-namespace', connection, clientArtifacts, 'test-sink');
     return { projections, registerMock };
 }
 

package/projections/Projections.modelBoundCompleteness.spec.ts

@@ -0,0 +1,224 @@
+// 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 { AutoMap } from '@cratis/chronicle.contracts';
+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 { clearWith } from './modelBound/clearWith';
+import { eventLog, eventSequence } from './modelBound/eventSequence';
+import { fromAll } from './modelBound/fromAll';
+import { fromEvent } from './modelBound/fromEvent';
+import { noAutoMap } from './modelBound/noAutoMap';
+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 MbWorkArrangementSet {
+    location!: string;
+    workMode!: number;
+}
+eventType()(MbWorkArrangementSet);
+
+class MbCandidateSubmitted {
+    name!: string;
+    location!: string;
+}
+eventType()(MbCandidateSubmitted);
+
+class MbAssignmentSummary {
+    id!: string;
+    location!: string;
+    candidateName!: string;
+}
+setFrom(MbWorkArrangementSet, 'location')(MbAssignmentSummary.prototype, 'location');
+noAutoMap(MbAssignmentSummary.prototype, 'location');
+setFrom(MbCandidateSubmitted, 'name')(MbAssignmentSummary.prototype, 'candidateName');
+fromEvent(MbWorkArrangementSet)(MbAssignmentSummary);
+readModel()(MbAssignmentSummary);
+
+class MbFullyExcluded {
+    id!: string;
+    location!: string;
+}
+setFrom(MbWorkArrangementSet, 'location')(MbFullyExcluded.prototype, 'location');
+fromEvent(MbWorkArrangementSet)(MbFullyExcluded);
+noAutoMap(MbFullyExcluded);
+readModel()(MbFullyExcluded);
+
+class MbProductRenamed {
+    name!: string;
+    version!: number;
+}
+eventType()(MbProductRenamed);
+
+class MbProductPriceChanged {
+    price!: number;
+    version!: number;
+}
+eventType()(MbProductPriceChanged);
+
+class MbProductVersion {
+    id!: string;
+    name!: string;
+    price!: number;
+    version!: number;
+}
+fromAll('version')(MbProductVersion.prototype, 'version');
+fromEvent(MbProductRenamed)(MbProductVersion);
+fromEvent(MbProductPriceChanged)(MbProductVersion);
+readModel()(MbProductVersion);
+
+class MbOrderPlaced {
+    amount!: number;
+}
+eventType()(MbOrderPlaced);
+
+class MbOrderSummaryWithCustomSequence {
+    id!: string;
+    totalAmount!: number;
+}
+setFrom(MbOrderPlaced, 'amount')(MbOrderSummaryWithCustomSequence.prototype, 'totalAmount');
+fromEvent(MbOrderPlaced)(MbOrderSummaryWithCustomSequence);
+eventSequence('custom-sequence')(MbOrderSummaryWithCustomSequence);
+readModel()(MbOrderSummaryWithCustomSequence);
+
+class MbLocalEvent {
+    data!: string;
+}
+eventType()(MbLocalEvent);
+
+class MbLocalSnapshot {
+    id!: string;
+    data!: string;
+}
+setFrom(MbLocalEvent, 'data')(MbLocalSnapshot.prototype, 'data');
+fromEvent(MbLocalEvent)(MbLocalSnapshot);
+eventLog(MbLocalSnapshot);
+readModel()(MbLocalSnapshot);
+
+class MbProjectNoted {
+    note!: string;
+}
+eventType()(MbProjectNoted);
+
+class MbProjectNoteCleared {}
+eventType()(MbProjectNoteCleared);
+
+class MbProjectNotes {
+    id!: string;
+    note!: string | undefined;
+}
+setFrom(MbProjectNoted, 'note')(MbProjectNotes.prototype, 'note');
+clearWith(MbProjectNoteCleared)(MbProjectNotes.prototype, 'note');
+fromEvent(MbProjectNoted)(MbProjectNotes);
+readModel()(MbProjectNotes);
+
+interface BuiltFromEntry {
+    Key: { Id: string };
+    Value: { Properties: Record<string, string>; Key: string; ParentKey: string };
+}
+
+interface BuiltDefinition {
+    EventSequenceId: string;
+    AutoMap: AutoMap;
+    NoAutoMapProperties: string[];
+    All: { Properties: Record<string, string> };
+    From: BuiltFromEntry[];
+}
+
+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', 'test-namespace', connection, clientArtifacts, 'test-sink');
+    return { projections, registerMock };
+}
+
+async function registerAndGetDefinition(readModelType: new (...args: unknown[]) => unknown): Promise<BuiltDefinition> {
+    const { projections, registerMock } = createProjections([readModelType]);
+    await projections.register();
+    return registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition;
+}
+
+function findFromEntry(definition: BuiltDefinition, eventTypeId: string): BuiltFromEntry {
+    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 model-bound completeness', () => {
+    describe('when a property is excluded from AutoMap with noAutoMap', () => {
+        it('should keep AutoMap enabled at the root and list only the excluded property', async () => {
+            const definition = await registerAndGetDefinition(MbAssignmentSummary);
+
+            expect(definition.AutoMap).toBe(AutoMap.Enabled);
+            expect(definition.NoAutoMapProperties).toEqual(['location']);
+
+            const workArrangementSet = findFromEntry(definition, 'MbWorkArrangementSet');
+            expect(workArrangementSet.Value.Properties.location).toBe('location');
+
+            const candidateSubmitted = findFromEntry(definition, 'MbCandidateSubmitted');
+            expect(candidateSubmitted.Value.Properties.candidateName).toBe('name');
+        });
+    });
+
+    describe('when a whole model-bound projection is excluded from AutoMap with class-level noAutoMap', () => {
+        it('should disable AutoMap for the whole definition', async () => {
+            const definition = await registerAndGetDefinition(MbFullyExcluded);
+            expect(definition.AutoMap).toBe(AutoMap.Disabled);
+        });
+    });
+
+    describe('when a property uses fromAll to read from every event type', () => {
+        it('should include it in the All properties map', async () => {
+            const definition = await registerAndGetDefinition(MbProductVersion);
+            expect(definition.All.Properties.version).toBe('version');
+        });
+    });
+
+    describe('when a model-bound projection declares a custom event sequence', () => {
+        it('should use the declared event sequence instead of the event log', async () => {
+            const definition = await registerAndGetDefinition(MbOrderSummaryWithCustomSequence);
+            expect(definition.EventSequenceId).toBe('custom-sequence');
+        });
+    });
+
+    describe('when a model-bound projection is explicitly pinned to the event log', () => {
+        it('should use the event log sequence', async () => {
+            const definition = await registerAndGetDefinition(MbLocalSnapshot);
+            expect(definition.EventSequenceId).toBe('event-log');
+        });
+    });
+
+    describe('when a root scalar property is cleared with an event', () => {
+        it('should add a $null mapping for that property on the clearing event', async () => {
+            const definition = await registerAndGetDefinition(MbProjectNotes);
+            const clearedBy = findFromEntry(definition, 'MbProjectNoteCleared');
+            expect(clearedBy.Value.Properties.note).toBe('$null');
+        });
+    });
+});