@cratis/chronicle 6.71.2 → 6.72.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/dist/reactors/AsyncQueue.d.ts +10 -0
  2. package/dist/reactors/AsyncQueue.d.ts.map +1 -0
  3. package/dist/reactors/AsyncQueue.js +42 -0
  4. package/dist/reactors/AsyncQueue.js.map +1 -0
  5. package/dist/reactors/IReactorBuilder.d.ts +12 -0
  6. package/dist/reactors/IReactorBuilder.d.ts.map +1 -0
  7. package/dist/reactors/IReactorBuilder.js +4 -0
  8. package/dist/reactors/IReactorBuilder.js.map +1 -0
  9. package/dist/reactors/IReactorDefinition.d.ts +14 -0
  10. package/dist/reactors/IReactorDefinition.d.ts.map +1 -0
  11. package/dist/reactors/IReactorDefinition.js +4 -0
  12. package/dist/reactors/IReactorDefinition.js.map +1 -0
  13. package/dist/reactors/IReactorDefinitionBuilder.d.ts +9 -0
  14. package/dist/reactors/IReactorDefinitionBuilder.d.ts.map +1 -0
  15. package/dist/reactors/IReactorDefinitionBuilder.js +4 -0
  16. package/dist/reactors/IReactorDefinitionBuilder.js.map +1 -0
  17. package/dist/reactors/IReactors.d.ts +21 -10
  18. package/dist/reactors/IReactors.d.ts.map +1 -1
  19. package/dist/reactors/ReactorBuilder.d.ts +32 -0
  20. package/dist/reactors/ReactorBuilder.d.ts.map +1 -0
  21. package/dist/reactors/ReactorBuilder.js +91 -0
  22. package/dist/reactors/ReactorBuilder.js.map +1 -0
  23. package/dist/reactors/ReactorCallback.d.ts +4 -0
  24. package/dist/reactors/ReactorCallback.d.ts.map +1 -0
  25. package/dist/reactors/ReactorCallback.js +4 -0
  26. package/dist/reactors/ReactorCallback.js.map +1 -0
  27. package/dist/reactors/ReactorEvent.d.ts +7 -0
  28. package/dist/reactors/ReactorEvent.d.ts.map +1 -0
  29. package/dist/reactors/ReactorEvent.js +4 -0
  30. package/dist/reactors/ReactorEvent.js.map +1 -0
  31. package/dist/reactors/ReactorObservation.d.ts +21 -0
  32. package/dist/reactors/ReactorObservation.d.ts.map +1 -0
  33. package/dist/reactors/ReactorObservation.js +43 -0
  34. package/dist/reactors/ReactorObservation.js.map +1 -0
  35. package/dist/reactors/ReactorObservationTarget.d.ts +4 -1
  36. package/dist/reactors/ReactorObservationTarget.d.ts.map +1 -1
  37. package/dist/reactors/ReactorPageDispatcher.d.ts +6 -0
  38. package/dist/reactors/ReactorPageDispatcher.d.ts.map +1 -1
  39. package/dist/reactors/ReactorPageDispatcher.js +96 -51
  40. package/dist/reactors/ReactorPageDispatcher.js.map +1 -1
  41. package/dist/reactors/ReactorRegistration.d.ts +14 -0
  42. package/dist/reactors/ReactorRegistration.d.ts.map +1 -0
  43. package/dist/reactors/ReactorRegistration.js +4 -0
  44. package/dist/reactors/ReactorRegistration.js.map +1 -0
  45. package/dist/reactors/ReactorRegistrationKind.d.ts +7 -0
  46. package/dist/reactors/ReactorRegistrationKind.d.ts.map +1 -0
  47. package/dist/reactors/ReactorRegistrationKind.js +10 -0
  48. package/dist/reactors/ReactorRegistrationKind.js.map +1 -0
  49. package/dist/reactors/ReactorRegistrations.d.ts +17 -0
  50. package/dist/reactors/ReactorRegistrations.d.ts.map +1 -0
  51. package/dist/reactors/ReactorRegistrations.js +42 -0
  52. package/dist/reactors/ReactorRegistrations.js.map +1 -0
  53. package/dist/reactors/ReactorSubscription.d.ts +4 -0
  54. package/dist/reactors/ReactorSubscription.d.ts.map +1 -0
  55. package/dist/reactors/ReactorSubscription.js +4 -0
  56. package/dist/reactors/ReactorSubscription.js.map +1 -0
  57. package/dist/reactors/Reactors.d.ts +31 -38
  58. package/dist/reactors/Reactors.d.ts.map +1 -1
  59. package/dist/reactors/Reactors.js +143 -274
  60. package/dist/reactors/Reactors.js.map +1 -1
  61. package/dist/reactors/WaitTillSubscribedOptions.d.ts +7 -0
  62. package/dist/reactors/WaitTillSubscribedOptions.d.ts.map +1 -0
  63. package/dist/reactors/WaitTillSubscribedOptions.js +4 -0
  64. package/dist/reactors/WaitTillSubscribedOptions.js.map +1 -0
  65. package/dist/reactors/index.d.ts +5 -0
  66. package/dist/reactors/index.d.ts.map +1 -1
  67. package/dist/reactors/index.js.map +1 -1
  68. package/dist/reactors/prepareReactor.d.ts +34 -0
  69. package/dist/reactors/prepareReactor.d.ts.map +1 -0
  70. package/dist/reactors/prepareReactor.js +75 -0
  71. package/dist/reactors/prepareReactor.js.map +1 -0
  72. package/dist/reactors/waitTillSubscribed.d.ts +5 -0
  73. package/dist/reactors/waitTillSubscribed.d.ts.map +1 -0
  74. package/dist/reactors/waitTillSubscribed.js +29 -0
  75. package/dist/reactors/waitTillSubscribed.js.map +1 -0
  76. package/dist/tsconfig.tsbuildinfo +1 -1
  77. package/package.json +1 -1
  78. package/reactors/AsyncQueue.ts +41 -0
  79. package/reactors/IReactorBuilder.ts +15 -0
  80. package/reactors/IReactorDefinition.ts +17 -0
  81. package/reactors/IReactorDefinitionBuilder.ts +12 -0
  82. package/reactors/IReactors.ts +25 -10
  83. package/reactors/ReactorBuilder.ts +98 -0
  84. package/reactors/ReactorCallback.ts +7 -0
  85. package/reactors/ReactorEvent.ts +10 -0
  86. package/reactors/ReactorObservation.ts +45 -0
  87. package/reactors/ReactorObservationTarget.ts +4 -1
  88. package/reactors/ReactorPageDispatcher.ts +98 -54
  89. package/reactors/ReactorRegistration.ts +11 -0
  90. package/reactors/ReactorRegistrationKind.ts +9 -0
  91. package/reactors/ReactorRegistrations.ts +45 -0
  92. package/reactors/ReactorSubscription.ts +7 -0
  93. package/reactors/Reactors.ts +156 -310
  94. package/reactors/WaitTillSubscribedOptions.ts +9 -0
  95. package/reactors/for_Reactors/given/runtime_reactors.fixture.ts +50 -0
  96. package/reactors/for_Reactors/when_a_class_reactor_fails_to_restart.spec.ts +67 -0
  97. package/reactors/for_Reactors/when_a_class_reactor_fails_to_start.spec.ts +80 -0
  98. package/reactors/for_Reactors/when_class_delivery_is_unregistered.spec.ts +62 -0
  99. package/reactors/for_Reactors/when_defining_runtime_reactors.spec.ts +77 -0
  100. package/reactors/for_Reactors/when_dispatching_runtime_reactors.spec.ts +94 -0
  101. package/reactors/for_Reactors/when_registering_runtime_reactors.spec.ts +102 -0
  102. package/reactors/for_Reactors/when_stopping_runtime_reactors.spec.ts +160 -0
  103. package/reactors/for_Reactors/when_using_the_default_artifacts_provider.spec.ts +80 -0
  104. package/reactors/for_Reactors/when_waiting_till_subscribed.spec.ts +65 -0
  105. package/reactors/index.ts +5 -0
  106. package/reactors/prepareReactor.ts +79 -0
  107. package/reactors/waitTillSubscribed.ts +29 -0
@@ -0,0 +1,80 @@
1
+ // Copyright (c) Cratis. All rights reserved.
2
+ // Licensed under the MIT license. See LICENSE file in the project root for full license information.
3
+
4
+ import { afterEach, beforeEach, chai, describe, it, vi } from 'vitest';
5
+ import { DefaultClientArtifactsProvider } from '../../artifacts/DefaultClientArtifactsProvider.js';
6
+ import { ChronicleClient } from '../../ChronicleClient.js';
7
+ import { ChronicleOptions } from '../../ChronicleOptions.js';
8
+ import type { ChronicleConnection } from '../../connection/ChronicleConnection.js';
9
+ import { EventStore } from '../../EventStore.js';
10
+ import { EventStoreName } from '../../EventStoreName.js';
11
+ import { EventStoreNamespaceName } from '../../EventStoreNamespaceName.js';
12
+ import { eventType } from '../../events/eventTypeDecorator.js';
13
+ import { TypeDiscoverer } from '../../types/TypeDiscoverer.js';
14
+ import { DecoratorType } from '../../types/DecoratorType.js';
15
+ import { reactor } from '../reactor.js';
16
+ import { runtime_reactors } from './given/runtime_reactors.fixture.js';
17
+
18
+ chai.should();
19
+
20
+ for (const scenario of ['discovery duplicate', 'runtime duplicate', 'runtime discovery collision', 'mixed reconnect', 'removal during reconnect'] as const) {
21
+ describe(`when using the default artifacts provider for ${scenario}`, () => {
22
+ let context: runtime_reactors;
23
+ let client: ChronicleClient;
24
+ let store: EventStore;
25
+ let failure: unknown;
26
+ beforeEach(async () => {
27
+ TypeDiscoverer.default.clear();
28
+ context = new runtime_reactors();
29
+ @eventType('real-added')
30
+ class Added {}
31
+ @reactor('real-discovered')
32
+ class Discovered { added() {} }
33
+ const register = vi.fn().mockResolvedValue({});
34
+ const connection = new Proxy({}, {
35
+ get: (_target, service) => {
36
+ if (service === 'logger') return undefined;
37
+ if (service === 'reactors') return { observe: context.observe };
38
+ return new Proxy({}, { get: () => register });
39
+ }
40
+ }) as ChronicleConnection;
41
+ client = new ChronicleClient(ChronicleOptions.fromConnectionString('chronicle://localhost:35000', { discoveryPatterns: [] }));
42
+ store = new EventStore(new EventStoreName('store'), EventStoreNamespaceName.default, connection, client['_lifecycle'], 'sink', DefaultClientArtifactsProvider.default);
43
+ client['_stores'].set('store', store);
44
+ const runtime = () => store.reactors.register('runtime', builder => builder.on(Added, () => {}));
45
+ try {
46
+ if (scenario === 'discovery duplicate') {
47
+ @reactor('real-discovered')
48
+ class Duplicate { added() {} }
49
+ TypeDiscoverer.default.register(DecoratorType.Reactor, Discovered, 'first-discovery-key');
50
+ TypeDiscoverer.default.register(DecoratorType.Reactor, Duplicate, 'second-discovery-key');
51
+ await store.reactors.register();
52
+ } else if (scenario === 'runtime duplicate') {
53
+ const first = runtime();
54
+ const second = runtime();
55
+ await first;
56
+ await second;
57
+ } else if (scenario === 'runtime discovery collision') {
58
+ await store.reactors.register('real-discovered', builder => builder.on(Added, () => {}));
59
+ } else {
60
+ await runtime();
61
+ await store.reactors.register();
62
+ if (scenario === 'removal during reconnect') await store.reactors.unregister('runtime');
63
+ await client['_lifecycle'].disconnected(error => { throw error; });
64
+ await client['_lifecycle'].connected(error => { throw error; });
65
+ await store.reactors.register();
66
+ }
67
+ } catch (error) { failure = error; }
68
+ });
69
+ afterEach(() => {
70
+ store.disposeObservations(); client.dispose(); context.reactors.dispose(); TypeDiscoverer.default.clear();
71
+ });
72
+ if (scenario.includes('duplicate') || scenario.includes('collision')) {
73
+ it('should reject rather than overwrite the identity', () => (failure as Error).message.should.match(/already registered/));
74
+ it('should open no streams for the invalid batch', () => context.observe.mock.calls.length.should.equal(scenario === 'runtime duplicate' ? 1 : 0));
75
+ } else {
76
+ it('should use cached EventStore lifecycle restoration exactly once', () => context.observe.mock.calls.length.should.equal(scenario === 'mixed reconnect' ? 4 : 3));
77
+ it('should cancel the previous observations', () => context.attempts[0].signal.aborted.should.be.true);
78
+ }
79
+ });
80
+ }
@@ -0,0 +1,65 @@
1
+ // Copyright (c) Cratis. All rights reserved.
2
+ // Licensed under the MIT license. See LICENSE file in the project root for full license information.
3
+
4
+ import { afterEach, beforeEach, chai, describe, it, vi } from 'vitest';
5
+ import { ObserverInformation } from '@cratis/chronicle.contracts';
6
+ import { Registered, runtime_reactors } from './given/runtime_reactors.fixture.js';
7
+
8
+ chai.should();
9
+
10
+ describe('when waiting for a reactor subscription', () => {
11
+ let context: runtime_reactors;
12
+ let completed: boolean;
13
+ beforeEach(async () => {
14
+ vi.useFakeTimers();
15
+ context = new runtime_reactors();
16
+ await context.reactors.register('runtime', builder => builder.on(Registered, () => {}).onEventSequence('custom'));
17
+ context.information.mockResolvedValueOnce(ObserverInformation.fromPartial({ IsSubscribed: false }))
18
+ .mockResolvedValue(ObserverInformation.fromPartial({ IsSubscribed: true }));
19
+ const pending = context.reactors.waitTillSubscribed('runtime', { timeout: 100 });
20
+ await vi.advanceTimersByTimeAsync(50);
21
+ await pending;
22
+ completed = true;
23
+ });
24
+ afterEach(() => { context.reactors.dispose(); vi.useRealTimers(); });
25
+ it('should poll until the observer reports subscribed', () => {
26
+ completed.should.be.true;
27
+ context.information.mock.calls.length.should.equal(2);
28
+ });
29
+ it('should scope readiness to the store namespace ID and sequence', () => {
30
+ const request = (context.information.mock.calls as unknown as [object][])[0][0];
31
+ request.should.deep.equal({ EventStore: 'store', Namespace: 'tenant', ObserverId: 'runtime', EventSequenceId: 'custom' });
32
+ });
33
+ });
34
+
35
+ for (const scenario of ['timeout', 'cancellation', 'disposal', 'query failure'] as const) {
36
+ describe(`when subscription readiness encounters ${scenario}`, () => {
37
+ let context: runtime_reactors;
38
+ let failure: unknown;
39
+ beforeEach(async () => {
40
+ vi.useFakeTimers();
41
+ context = new runtime_reactors();
42
+ const controller = new AbortController();
43
+ if (scenario === 'query failure') context.information.mockRejectedValue(new Error('query denied'));
44
+ const pending = context.reactors.waitTillSubscribed('runtime', { timeout: 100, signal: controller.signal }).catch(error => { failure = error; });
45
+ if (scenario === 'cancellation') controller.abort();
46
+ if (scenario === 'disposal') context.reactors.dispose();
47
+ await vi.advanceTimersByTimeAsync(100);
48
+ await pending;
49
+ });
50
+ afterEach(() => { context.reactors.dispose(); vi.useRealTimers(); });
51
+ it('should settle without claiming readiness', () => (failure instanceof Error).should.be.true);
52
+ it('should not register an observation as a side effect', () => context.observe.mock.calls.length.should.equal(0));
53
+ });
54
+ }
55
+
56
+ describe('when readiness observes an already subscribed observer', () => {
57
+ let context: runtime_reactors;
58
+ beforeEach(async () => {
59
+ context = new runtime_reactors();
60
+ context.information.mockResolvedValue(ObserverInformation.fromPartial({ IsSubscribed: true }));
61
+ await context.reactors.waitTillSubscribed('existing');
62
+ });
63
+ afterEach(() => context.reactors.dispose());
64
+ it('should allow readiness independently of a local registration acknowledgment', () => context.information.mock.calls.length.should.equal(1));
65
+ });
package/reactors/index.ts CHANGED
@@ -10,6 +10,11 @@ export { startAtTail } from './startAtTail.js';
10
10
  export { replay } from './replay.js';
11
11
  export type { ReactorMetadata } from './reactor.js';
12
12
  export type { IReactors } from './IReactors.js';
13
+ export type { IReactorBuilder } from './IReactorBuilder.js';
14
+ export type { IReactorDefinitionBuilder } from './IReactorDefinitionBuilder.js';
15
+ export type { IReactorDefinition } from './IReactorDefinition.js';
16
+ export type { ReactorEvent } from './ReactorEvent.js';
17
+ export type { WaitTillSubscribedOptions } from './WaitTillSubscribedOptions.js';
13
18
  export { Reactors } from './Reactors.js';
14
19
  export type { ReactorResultHandler } from './ReactorResultHandler.js';
15
20
  export type { ReactorServices } from './ReactorServices.js';
@@ -0,0 +1,79 @@
1
+ // Copyright (c) Cratis. All rights reserved.
2
+ // Licensed under the MIT license. See LICENSE file in the project root for full license information.
3
+
4
+ import { EventGenerationDelivery, type ReactorMessage } from '@cratis/chronicle.contracts';
5
+ import { createHandlerInstanceValidator } from '../observation/createHandlerInstanceValidator.js';
6
+ import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
7
+ import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
8
+ import { getTagsFor } from '../events/tagDecorator.js';
9
+ import { getFilterTagsFor } from '../events/filterEventsByTagDecorator.js';
10
+ import { getEventSourceTypeFor } from '../events/eventSourceTypeDecorator.js';
11
+ import { getEventStreamTypeFor } from '../events/eventStreamTypeDecorator.js';
12
+ import { toPageDelivery } from '../observation/batches/batchSize.js';
13
+ import type { IClientArtifactsProvider } from '../artifacts/IClientArtifactsProvider.js';
14
+ import type { ReactorSubscription } from './ReactorSubscription.js';
15
+ import type { ReactorRegistration } from './ReactorRegistration.js';
16
+ import { ReactorRegistrationKind } from './ReactorRegistrationKind.js';
17
+ import { getReactorMetadata } from './reactor.js';
18
+ import { isOnceOnly } from './onceOnly.js';
19
+ import { isStartAtTail } from './startAtTail.js';
20
+ import { getReactorBatchMethods, getReactorEventTypes } from './ReactorDispatcher.js';
21
+
22
+ /** Resolves handler validation before opening any stream in a registration batch. */
23
+ export function prepareReactor(registration: ReactorRegistration, artifacts: IClientArtifactsProvider) {
24
+ if (registration.kind !== ReactorRegistrationKind.Discovered) {
25
+ const definition = registration.definition;
26
+ if (!definition.id.value.trim()) throw new Error('Reactor id must not be empty.');
27
+ if (!definition.eventTypes.length) throw new Error('Reactor must subscribe to at least one event type.');
28
+ const known = artifacts.eventTypes.map(type => getEventTypeMetadata(type)?.eventType.id.value);
29
+ for (const type of definition.eventTypes) {
30
+ if (!known.includes(type.id.value)) throw new Error(`Reactor event type '${type.id.value}' has no registered event type.`);
31
+ }
32
+ return {
33
+ id: registration.id, reactorType: undefined, runtime: definition,
34
+ eventSequenceId: definition.eventSequenceId.value,
35
+ entries: definition.eventTypes.map(type => ({ id: type.id.value, generation: type.generation.value })),
36
+ batchMethods: [], validateInstance: (_instance: object) => {},
37
+ isReplayable: definition.isReplayable
38
+ };
39
+ }
40
+ const type = registration.type;
41
+ const entries = getReactorEventTypes(type, artifacts.eventTypes);
42
+ const batchMethods = getReactorBatchMethods(type, artifacts.eventTypes);
43
+ return {
44
+ id: registration.id, reactorType: type, runtime: undefined,
45
+ eventSequenceId: getReactorMetadata(type)!.eventSequenceId ?? EventSequenceId.eventLog.value,
46
+ entries, batchMethods,
47
+ validateInstance: createHandlerInstanceValidator(type, [
48
+ ...entries.flatMap(entry => [entry.methodName, entry.replayMethodName].filter((name): name is string => !!name)),
49
+ ...batchMethods.map(method => method.methodName)
50
+ ]),
51
+ isReplayable: !isOnceOnly(type)
52
+ };
53
+ }
54
+
55
+ /** Creates the protocol subscription, without implying remote acknowledgment. */
56
+ export function reactorSubscriptionMessage(subscription: ReactorSubscription, scope: {
57
+ connectionId: string; eventStore: string; namespace: string;
58
+ }): ReactorMessage {
59
+ const { reactorType: type } = subscription;
60
+ return { Content: { Value0: {
61
+ ConnectionId: scope.connectionId, EventStore: scope.eventStore, Namespace: scope.namespace,
62
+ Reactor: {
63
+ ReactorId: subscription.id, EventSequenceId: subscription.eventSequenceId,
64
+ EventTypes: [...subscription.entries, ...subscription.batchMethods.flatMap(method => [...method.eventTypes.values()])].map(entry => ({
65
+ EventType: { Id: entry.id, Generation: entry.generation, Tombstone: false }, Key: '$eventSourceId'
66
+ })),
67
+ IsReplayable: subscription.isReplayable, IsNotReplayable: !subscription.isReplayable,
68
+ StartAtTail: type ? isStartAtTail(type) : false,
69
+ GenerationDelivery: EventGenerationDelivery.Compatibility,
70
+ Tags: type ? getTagsFor(type).map(tag => tag.value) : [],
71
+ Filters: {
72
+ FilterTags: type ? getFilterTagsFor(type).map(tag => tag.value) : [],
73
+ EventSourceType: type ? getEventSourceTypeFor(type) : '',
74
+ EventStreamType: type ? getEventStreamTypeFor(type) : 'All'
75
+ }
76
+ },
77
+ PageDelivery: type ? toPageDelivery(type) : undefined
78
+ }, Value1: undefined } };
79
+ }
@@ -0,0 +1,29 @@
1
+ // Copyright (c) Cratis. All rights reserved.
2
+ // Licensed under the MIT license. See LICENSE file in the project root for full license information.
3
+
4
+ import { setTimeout as delay } from 'node:timers/promises';
5
+ import type { ChronicleConnection } from '../connection/ChronicleConnection.js';
6
+ import type { WaitTillSubscribedOptions } from './WaitTillSubscribedOptions.js';
7
+
8
+ /** Polls current observer readiness; a previous subscription can satisfy this check. */
9
+ export async function waitTillSubscribed(read: (signal: AbortSignal) => ReturnType<ChronicleConnection['observers']['getObserverInformation']>,
10
+ options: WaitTillSubscribedOptions, lifetime: AbortSignal): Promise<void> {
11
+ const timeout = options.timeout ?? 5000;
12
+ if (!Number.isFinite(timeout) || timeout < 0) throw new Error('Subscription timeout must be a finite non-negative number.');
13
+ const controller = new AbortController();
14
+ const timer = setTimeout(() => controller.abort(new Error('Timed out waiting for reactor subscription.')), timeout);
15
+ const signals = [controller.signal, lifetime];
16
+ if (options.signal) signals.push(options.signal);
17
+ const signal = AbortSignal.any(signals);
18
+ try {
19
+ for (;;) {
20
+ signal.throwIfAborted();
21
+ const information = await read(signal);
22
+ signal.throwIfAborted();
23
+ if (information.IsSubscribed) return;
24
+ await delay(50, undefined, { signal });
25
+ }
26
+ } finally {
27
+ clearTimeout(timer);
28
+ }
29
+ }