@cratis/chronicle 6.52.0 → 6.53.0

package/reactors/startAtTail.spec.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import { isStartAtTail, startAtTail } from './startAtTail.js';
+
+@startAtTail()
+class MarkedReactor {}
+
+class OrdinaryReactor {}
+
+class InheritedReactor extends MarkedReactor {}
+
+describe('the start-at-tail decorator', () => {
+    it('marks the reactor class', () => {
+        expect(isStartAtTail(MarkedReactor)).toBe(true);
+    });
+
+    it('leaves an unmarked class alone', () => {
+        expect(isStartAtTail(OrdinaryReactor)).toBe(false);
+    });
+
+    it('is not inherited by a subclass', () => {
+        expect(isStartAtTail(InheritedReactor)).toBe(false);
+    });
+
+    it('refuses to decorate anything but a class', () => {
+        const decorate = startAtTail() as unknown as (target: object, context: { kind: string }) => void;
+        expect(() => decorate(() => {}, { kind: 'method' })).toThrow(TypeError);
+    });
+});

package/reactors/startAtTail.ts

@@ -0,0 +1,33 @@
+// 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:reactor:startAtTail';
+
+/**
+ * A new reactor normally catches up from the beginning of the event sequence, so one whose handlers have side
+ * effects acts on every historical event the moment it is deployed. `@onceOnly()` does not prevent that, because it
+ * only excludes replay.
+ *
+ * Marks a reactor class so that the first time Chronicle sees it, it begins at the tail of the event sequence and
+ * observes only what is appended from then on. A reactor that already has a position keeps it, so the marker is safe
+ * to leave in place. Renaming the reactor or moving it changes its default id and makes it a new reactor, which
+ * starts at the tail again, unless an explicit id is given to `@reactor()`. An explicit replay still replays from the
+ * beginning. Both the Chronicle server and the client must support it; a server that predates it ignores the request.
+ * The marker is not inherited by subclasses.
+ * @returns A class decorator for legacy and standard TypeScript decorators.
+ */
+export function startAtTail(): ClassDecorator & ((value: Function, context: ClassDecoratorContext) => void) {
+    return (target: object, context?: ClassDecoratorContext) => {
+        if (typeof context === 'object' && context.kind !== 'class') {
+            throw new TypeError('Start-at-tail can only decorate a reactor class.');
+        }
+        Reflect.defineMetadata(METADATA_KEY, true, target);
+    };
+}
+
+/** Whether this reactor class is marked to start at the tail (without inheriting the marker). */
+export function isStartAtTail(target: Function): boolean {
+    return Reflect.getOwnMetadata(METADATA_KEY, target) === true;
+}

package/readModels/for_ReadModels/given/Book.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 'reflect-metadata';
+import { field } from '@cratis/fundamentals';
+import { fromEvent } from '../../../projections/modelBound/fromEvent.js';
+import { setValue } from '../../../projections/modelBound/setValue.js';
+import { BookRegistered } from './BookRegistered.js';
+import { BookBorrowed } from './BookBorrowed.js';
+import { BookReturned } from './BookReturned.js';
+
+export class Book {
+    id = '';
+    title: string | null = null;
+    isbn: string | null = null;
+    borrowed = false;
+}
+field(String)(Book.prototype, 'id');
+field(String)(Book.prototype, 'title');
+field(String)(Book.prototype, 'isbn');
+field(Boolean)(Book.prototype, 'borrowed');
+fromEvent(BookRegistered)(Book);
+fromEvent(BookBorrowed)(Book);
+fromEvent(BookReturned)(Book);
+setValue(BookBorrowed, true)(Book.prototype, 'borrowed');
+setValue(BookReturned, false)(Book.prototype, 'borrowed');

package/readModels/for_ReadModels/given/BookBorrowed.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export class BookBorrowed {}

package/readModels/for_ReadModels/given/BookRegistered.ts

@@ -0,0 +1,7 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export class BookRegistered {
+    title = '';
+    isbn = '';
+}

package/readModels/for_ReadModels/given/BookReturned.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export class BookReturned {}

package/readModels/for_ReadModels/when_reading_a_model_bound_projection/without_registration_fields.spec.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it, vi } from 'vitest';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import type { ChronicleConnection } from '../../../connection/index.js';
+import { ReadModels } from '../../ReadModels.js';
+import { Book } from '../given/Book.js';
+
+const should = chai.should();
+
+for (const borrowed of [true, false]) {
+    describe(`when reading a model-bound projection after a book is ${borrowed ? 'borrowed' : 'returned'} without registration fields`, () => {
+        let result: Book;
+
+        beforeEach(async () => {
+            const connection = {
+                readModels: { getInstanceByKey: vi.fn().mockResolvedValue({ ReadModel: JSON.stringify({ id: 'book', borrowed }) }) }
+            } as unknown as ChronicleConnection;
+            const artifacts = { readModels: [Book], projections: [], reducers: [] } as unknown as IClientArtifactsProvider;
+            const readModels = new ReadModels('store', 'tenant', connection, artifacts, 'sink');
+            result = await readModels.getInstanceById(Book, 'book');
+        });
+
+        it('should restore the model type', () => result.should.be.instanceOf(Book));
+        it('should keep the title null', () => should.equal(result.title, null));
+        it('should keep the isbn null', () => should.equal(result.isbn, null));
+        it('should restore the borrowed state', () => result.borrowed.should.equal(borrowed));
+    });
+}

package/readModels/for_deserializeReadModel/given/Address.ts

@@ -0,0 +1,12 @@
+// 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';
+
+export class Address {
+    street = 'Default street';
+    city: string | null = null;
+}
+field(String)(Address.prototype, 'street');
+field(String)(Address.prototype, 'city');

package/readModels/for_deserializeReadModel/given/IdentityDefaults.fixture.ts

@@ -0,0 +1,15 @@
+// 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';
+
+export class IdentityDefaults {
+    original = {};
+    mirror = this.original;
+    owner = this;
+    name = 'default';
+}
+field(Object)(IdentityDefaults.prototype, 'mirror');
+field(Object)(IdentityDefaults.prototype, 'owner');
+field(String)(IdentityDefaults.prototype, 'name');

package/readModels/for_deserializeReadModel/given/SetterDefaults.fixture.ts

@@ -0,0 +1,22 @@
+// 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';
+
+export class SetterDefaults {
+    sibling = 'default';
+    assignments = 0;
+    private _name = 'default';
+
+    get name(): string {
+        return this._name;
+    }
+
+    set name(value: string) {
+        this.assignments++;
+        this._name = `prefix:${value}`;
+    }
+}
+field(String)(SetterDefaults.prototype, 'name');
+field(String)(SetterDefaults.prototype, 'sibling');

package/readModels/for_deserializeReadModel/given/a_read_model_with_defaults.ts

@@ -0,0 +1,18 @@
+// 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 { Address } from './Address.js';
+
+export class Model {
+    title: string | null = null;
+    status = 'available';
+    address = new Address();
+    children = [new Address()];
+}
+field(String)(Model.prototype, 'title');
+field(String)(Model.prototype, 'status');
+field(Address)(Model.prototype, 'address');
+field(Array, { genericArguments: [Address] })(Model.prototype, 'children');

package/readModels/for_deserializeReadModel/when_restoring/with_a_non_idempotent_setter_and_an_absent_sibling.spec.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { deserializeReadModel } from '../../deserializeReadModel.js';
+import { SetterDefaults } from '../given/SetterDefaults.fixture.js';
+
+chai.should();
+
+describe('when restoring with a non-idempotent setter and an absent sibling', () => {
+    let result: SetterDefaults;
+
+    beforeEach(() => {
+        result = deserializeReadModel(SetterDefaults, '{"name":"stored"}');
+    });
+
+    it('should apply the setter transformation once', () => result.name.should.equal('prefix:stored'));
+    it('should invoke the setter once', () => result.assignments.should.equal(1));
+    it('should keep the absent sibling default', () => result.sibling.should.equal('default'));
+});

package/readModels/for_deserializeReadModel/when_restoring/with_a_partial_nested_object.spec.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { deserializeReadModel } from '../../deserializeReadModel.js';
+import { Model } from '../given/a_read_model_with_defaults.js';
+import { Address } from '../given/Address.js';
+
+const should = chai.should();
+
+describe('when restoring with a partial nested object', () => {
+    let result: Model;
+
+    beforeEach(() => {
+        result = deserializeReadModel(Model, '{"address":{"city":"Oslo"}}');
+    });
+
+    it('should restore the nested type', () => result.address.should.be.instanceOf(Address));
+    it('should keep the absent nested field default', () => result.address.street.should.equal('Default street'));
+    it('should replace the present nested field default', () => result.address.city!.should.equal('Oslo'));
+});
+
+describe('when restoring with explicit null in a nested object', () => {
+    let result: Model;
+
+    beforeEach(() => {
+        result = deserializeReadModel(Model, '{"address":{"street":null}}');
+    });
+
+    it('should replace the non-null nested field default', () => should.equal(result.address.street, null));
+});

package/readModels/for_deserializeReadModel/when_restoring/with_absent_fields.spec.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { deserializeReadModel } from '../../deserializeReadModel.js';
+import { Model } from '../given/a_read_model_with_defaults.js';
+import { Address } from '../given/Address.js';
+
+const should = chai.should();
+
+describe('when restoring with absent fields', () => {
+    let result: Model;
+
+    beforeEach(() => {
+        result = deserializeReadModel(Model, '{}');
+    });
+
+    it('should keep the null default', () => should.equal(result.title, null));
+    it('should keep the non-null default', () => result.status.should.equal('available'));
+    it('should keep the nested object default', () => result.address.should.deep.equal(new Address()));
+    it('should deserialize an absent array to an empty array', () => result.children.should.deep.equal([]));
+});

package/readModels/for_deserializeReadModel/when_restoring/with_explicit_null.spec.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { deserializeReadModel } from '../../deserializeReadModel.js';
+import { Model } from '../given/a_read_model_with_defaults.js';
+
+const should = chai.should();
+
+describe('when restoring with explicit null', () => {
+    let result: Model;
+
+    beforeEach(() => {
+        result = deserializeReadModel(Model, '{"status":null,"address":null,"children":null}');
+    });
+
+    it('should replace the non-null scalar default', () => should.equal(result.status, null));
+    it('should replace the nested object default', () => should.equal(result.address, null));
+    it('should replace the array default', () => should.equal(result.children, null));
+});

package/readModels/for_deserializeReadModel/when_restoring/with_identity_dependent_defaults.spec.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { deserializeReadModel } from '../../deserializeReadModel.js';
+import { IdentityDefaults } from '../given/IdentityDefaults.fixture.js';
+
+chai.should();
+
+describe('when restoring with identity-dependent defaults', () => {
+    let result: IdentityDefaults;
+
+    beforeEach(() => {
+        result = deserializeReadModel(IdentityDefaults, '{"name":"stored"}');
+    });
+
+    it('should keep the default referencing another member identical to that member', () => result.mirror.should.equal(result.original));
+    it('should keep the default referencing its owner identical to the returned instance', () => result.owner.should.equal(result));
+    it('should still replace a present decorated field', () => result.name.should.equal('stored'));
+});

package/readModels/for_deserializeReadModel/when_restoring/with_partial_array_items.spec.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { deserializeReadModel } from '../../deserializeReadModel.js';
+import { Model } from '../given/a_read_model_with_defaults.js';
+import { Address } from '../given/Address.js';
+
+const should = chai.should();
+
+describe('when restoring with partial array items', () => {
+    let result: Model;
+
+    beforeEach(() => {
+        result = deserializeReadModel(Model, '{"children":[{}, {"street":"Stored street","city":null}]}');
+    });
+
+    it('should replace the array default', () => result.children.should.have.lengthOf(2));
+    it('should restore the child type', () => result.children[0].should.be.instanceOf(Address));
+    it('should keep the absent child field default', () => result.children[0].street.should.equal('Default street'));
+    it('should replace the present child field default', () => result.children[1].street.should.equal('Stored street'));
+    it('should preserve the null child field', () => should.equal(result.children[1].city, null));
+});

package/readModels/for_deserializeReadModel/when_restoring/with_present_fields.spec.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { deserializeReadModel } from '../../deserializeReadModel.js';
+import { Model } from '../given/a_read_model_with_defaults.js';
+
+chai.should();
+
+describe('when restoring with present fields', () => {
+    let result: Model;
+
+    beforeEach(() => {
+        result = deserializeReadModel(Model, '{"title":"Stored title","status":"borrowed"}');
+    });
+
+    it('should replace the null default', () => result.title!.should.equal('Stored title'));
+    it('should replace the non-null default', () => result.status.should.equal('borrowed'));
+});

package/testing/EventScenario.constraint-values.spec.ts

@@ -168,11 +168,11 @@ describe('fixture-backed unique scalar values', () => {
         const results = scenario.results;
         const unprovenKeys = ['!', '#', '%', '&', "'", '(', ')', '*', '+', ',', '/', ';', '<', '=', '>', '?', '[', ']', '^', '`', '~'];
         const invalidContent: unknown[] = [1, 0, 1.5, undefined, [], {}, new Date(), 'É', 'e\u0301', '"', '\\', '\n'];
-        // The production serializer throws on null before checkedContent can run.
+        // Fundamentals preserves null in JSON, so checkedContent rejects it as unsupported string content.
         for (const [value, operation] of [
             ...unprovenKeys.map(value => [value, 'artifacts.constraints']),
             ...invalidContent.map(value => [value, 'append.content']),
-            [null, 'append.serialization']
+            [null, 'append.content']
         ] as Array<[unknown, string]>) {
             const bad = new OracleDomainText('valid');
             Object.assign(bad, { key: value });

package/testing/for_ReadModelScenario/when_evaluating_arithmetic/with_legacy_decorators.legacy.spec.ts

@@ -83,7 +83,7 @@ describe('when evaluating arithmetic with legacy model-bound decorators', () =>
     it('should suppress aggregate-only AutoMap and restore it for mixed mappings', async () => {
         const scenario = new ReadModelScenario(Totals, artifacts);
         scenario.given.forEventSource('A').events(new Added(2));
-        ((await scenario.instance)!.title === undefined).should.be.true;
+        (await scenario.instance)!.title.should.equal('');
         scenario.given.forEventSource('A').events(new Renamed());
         const result = (await scenario.instance)!;
         [result.total, result.title, result.label].should.deep.equal([3, 'automapped', 'explicit']);

package/testing/for_ReadModelScenario/when_evaluating_arithmetic/with_standard_decorators.standard.spec.ts

@@ -84,7 +84,7 @@ describe('when evaluating arithmetic with standard model-bound decorators', () =
     it('should suppress aggregate-only AutoMap and restore it for mixed mappings', async () => {
         const scenario = new ReadModelScenario(Totals, artifacts);
         scenario.given.forEventSource('A').events(new Added(2));
-        should((await scenario.instance)!.title === undefined).be.true;
+        should((await scenario.instance)!.title).equal('');
         scenario.given.forEventSource('A').events(new Renamed());
         const result = (await scenario.instance)!;
         should([result.total, result.title, result.label]).deep.equal([3, 'automapped', 'explicit']);

package/testing/for_ReadModelScenario/when_evaluating_joins/with_a_fluent_projection.spec.ts

@@ -61,7 +61,7 @@ describe('when evaluating a fluent root join', () => {
         scenario.given.forEventSource('customer').events(new CustomerNamed('name'));
         (await scenario.instanceForEventSourceId('A'))!.customerName.should.equal('name');
         (await scenario.instanceForEventSourceId('B'))!.customerName.should.equal('name');
-        ((await scenario.instanceForEventSourceId('C'))!.customerName === undefined).should.be.true;
+        (await scenario.instanceForEventSourceId('C'))!.customerName.should.equal('');
     });
 
     it('should retain joined history across removal without resurrecting the removed root', async () => {
@@ -95,7 +95,7 @@ describe('when evaluating a fluent root join', () => {
         (await first.instance)!.customerName.should.equal('second');
         const second = new ReadModelScenario(Order, artifacts);
         second.given.forEventSource('A').events(new OrderPlaced('customer'));
-        ((await second.instance)!.customerName === undefined).should.be.true;
+        (await second.instance)!.customerName.should.equal('');
     });
 
     it('should update the root keys when observing a committed event sequence', async () => {

package/testing/for_ReadModelScenario/when_evaluating_joins/with_legacy_decorators.legacy.spec.ts

@@ -47,8 +47,8 @@ describe('when evaluating joins with legacy model-bound decorators', () => {
         const result = (await scenario.instance)!;
         result.customerName.should.equal('before');
         result.city.should.equal('Oslo');
-        (result.name === undefined).should.be.true;
-        (result.ignored === undefined).should.be.true;
+        result.name.should.equal('');
+        result.ignored.should.equal('');
     });
 
     it('should update existing roots and recreate a removed root from the latest joined history', async () => {

package/testing/for_ReadModelScenario/when_evaluating_joins/with_standard_decorators.standard.spec.ts

@@ -44,8 +44,8 @@ describe('when evaluating joins with standard model-bound decorators', () => {
         const result = (await scenario.instance)!;
         result.customerName.should.equal('before');
         result.city.should.equal('Oslo');
-        (result.name === undefined).should.be.true;
-        (result.ignored === undefined).should.be.true;
+        result.name.should.equal('');
+        result.ignored.should.equal('');
     });
 
     it('should fan out subsequent join events to all matching roots', async () => {

package/webhooks/WebhookDefinitionBuilder.ts

@@ -1,12 +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 {
-    BasicAuthorization,
-    BearerTokenAuthorization,
-    OAuthAuthorization,
-    OneOfBasicAuthorizationBearerTokenAuthorizationOAuthAuthorization,
-    WebhookDefinition
+import {
+    EventGenerationDelivery,
+    type BasicAuthorization,
+    type BearerTokenAuthorization,
+    type OAuthAuthorization,
+    type OneOfBasicAuthorizationBearerTokenAuthorizationOAuthAuthorization,
+    type WebhookDefinition
 } from '@cratis/chronicle.contracts';
 import { Constructor } from '@cratis/fundamentals';
 import { IEventTypes } from '../events/IEventTypes.js';
@@ -140,7 +141,8 @@ export class WebhookDefinitionBuilder implements IWebhookDefinitionBuilder {
             IsReplayable: this._isReplayable,
             IsActive: this._isActive,
             IsNotReplayable: !this._isReplayable,
-            IsInactive: !this._isActive
+            IsInactive: !this._isActive,
+            GenerationDelivery: EventGenerationDelivery.Compatibility
         };
     }
 }

package/webhooks/Webhooks.ts

@@ -104,7 +104,8 @@ export class Webhooks implements IWebhooks {
             IsReplayable: webhook.IsReplayable,
             IsActive: webhook.IsActive,
             IsNotReplayable: !webhook.IsReplayable,
-            IsInactive: !webhook.IsActive
+            IsInactive: !webhook.IsActive,
+            GenerationDelivery: webhook.GenerationDelivery
         }));
     }