@cratis/chronicle 6.66.0 → 6.67.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 (85) hide show
  1. package/ArtifactRegistrationResult.ts +31 -0
  2. package/ChronicleClient.ts +2 -2
  3. package/ChronicleOptions.ts +12 -2
  4. package/EventStore.ts +31 -6
  5. package/IEventStore.ts +7 -0
  6. package/artifacts/ArtifactRegistrationAttempt.ts +50 -0
  7. package/dist/ArtifactRegistrationResult.d.ts +35 -0
  8. package/dist/ArtifactRegistrationResult.d.ts.map +1 -0
  9. package/dist/ArtifactRegistrationResult.js +4 -0
  10. package/dist/ArtifactRegistrationResult.js.map +1 -0
  11. package/dist/ChronicleClient.js +2 -2
  12. package/dist/ChronicleClient.js.map +1 -1
  13. package/dist/ChronicleOptions.d.ts +4 -0
  14. package/dist/ChronicleOptions.d.ts.map +1 -1
  15. package/dist/ChronicleOptions.js +8 -2
  16. package/dist/ChronicleOptions.js.map +1 -1
  17. package/dist/EventStore.d.ts +11 -2
  18. package/dist/EventStore.d.ts.map +1 -1
  19. package/dist/EventStore.js +29 -6
  20. package/dist/EventStore.js.map +1 -1
  21. package/dist/IEventStore.d.ts +6 -0
  22. package/dist/IEventStore.d.ts.map +1 -1
  23. package/dist/artifacts/ArtifactRegistrationAttempt.d.ts +20 -0
  24. package/dist/artifacts/ArtifactRegistrationAttempt.d.ts.map +1 -0
  25. package/dist/artifacts/ArtifactRegistrationAttempt.js +47 -0
  26. package/dist/artifacts/ArtifactRegistrationAttempt.js.map +1 -0
  27. package/dist/eventSequences/EventEnrichmentContext.d.ts +15 -0
  28. package/dist/eventSequences/EventEnrichmentContext.d.ts.map +1 -0
  29. package/dist/eventSequences/EventEnrichmentContext.js +4 -0
  30. package/dist/eventSequences/EventEnrichmentContext.js.map +1 -0
  31. package/dist/eventSequences/EventEnrichmentProvider.d.ts +10 -0
  32. package/dist/eventSequences/EventEnrichmentProvider.d.ts.map +1 -0
  33. package/dist/eventSequences/EventEnrichmentProvider.js +4 -0
  34. package/dist/eventSequences/EventEnrichmentProvider.js.map +1 -0
  35. package/dist/eventSequences/EventLog.d.ts +2 -1
  36. package/dist/eventSequences/EventLog.d.ts.map +1 -1
  37. package/dist/eventSequences/EventLog.js +2 -2
  38. package/dist/eventSequences/EventLog.js.map +1 -1
  39. package/dist/eventSequences/EventSequence.d.ts +4 -1
  40. package/dist/eventSequences/EventSequence.d.ts.map +1 -1
  41. package/dist/eventSequences/EventSequence.js +28 -8
  42. package/dist/eventSequences/EventSequence.js.map +1 -1
  43. package/dist/eventSequences/enrichEventContent.d.ts +5 -0
  44. package/dist/eventSequences/enrichEventContent.d.ts.map +1 -0
  45. package/dist/eventSequences/enrichEventContent.js +16 -0
  46. package/dist/eventSequences/enrichEventContent.js.map +1 -0
  47. package/dist/eventSequences/index.d.ts +2 -0
  48. package/dist/eventSequences/index.d.ts.map +1 -1
  49. package/dist/eventSequences/index.js.map +1 -1
  50. package/dist/for_EventStore/when_inspecting_registration/given/an_event_store.d.ts +13 -0
  51. package/dist/for_EventStore/when_inspecting_registration/given/an_event_store.d.ts.map +1 -0
  52. package/dist/for_EventStore/when_inspecting_registration/given/an_event_store.js +79 -0
  53. package/dist/for_EventStore/when_inspecting_registration/given/an_event_store.js.map +1 -0
  54. package/dist/index.d.ts +1 -0
  55. package/dist/index.d.ts.map +1 -1
  56. package/dist/index.js.map +1 -1
  57. package/dist/projections/Projections.d.ts +2 -1
  58. package/dist/projections/Projections.d.ts.map +1 -1
  59. package/dist/projections/Projections.js +7 -4
  60. package/dist/projections/Projections.js.map +1 -1
  61. package/dist/projections/registerProjectionWithRetry.d.ts +4 -2
  62. package/dist/projections/registerProjectionWithRetry.d.ts.map +1 -1
  63. package/dist/projections/registerProjectionWithRetry.js +8 -4
  64. package/dist/projections/registerProjectionWithRetry.js.map +1 -1
  65. package/dist/tsconfig.tsbuildinfo +1 -1
  66. package/eventSequences/EventEnrichmentContext.ts +18 -0
  67. package/eventSequences/EventEnrichmentProvider.ts +16 -0
  68. package/eventSequences/EventLog.ts +4 -2
  69. package/eventSequences/EventSequence.ts +33 -10
  70. package/eventSequences/enrichEventContent.ts +22 -0
  71. package/eventSequences/for_EventSequence/when_enriching_appends/from_client_options.spec.ts +64 -0
  72. package/eventSequences/for_EventSequence/when_enriching_appends/given.fixture.ts +53 -0
  73. package/eventSequences/for_EventSequence/when_enriching_appends/with_a_failing_provider.spec.ts +57 -0
  74. package/eventSequences/for_EventSequence/when_enriching_appends/with_a_pending_provider.spec.ts +58 -0
  75. package/eventSequences/for_EventSequence/when_enriching_appends/with_providers.spec.ts +66 -0
  76. package/eventSequences/for_EventSequence/when_enriching_appends/without_providers.spec.ts +25 -0
  77. package/eventSequences/index.ts +2 -0
  78. package/for_EventStore/when_inspecting_registration/given/an_event_store.ts +59 -0
  79. package/for_EventStore/when_inspecting_registration/with_new_attempts.spec.ts +104 -0
  80. package/for_EventStore/when_inspecting_registration/with_projection_outcomes.spec.ts +80 -0
  81. package/index.ts +1 -0
  82. package/package.json +1 -1
  83. package/projections/Projections.ts +10 -4
  84. package/projections/for_registerProjectionWithRetry/when_reporting_outcomes.spec.ts +71 -0
  85. package/projections/registerProjectionWithRetry.ts +11 -5
@@ -0,0 +1,71 @@
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 type { ProjectionDefinition } from '@cratis/chronicle.contracts';
5
+ import { afterEach, beforeEach, chai, describe, it, vi } from 'vitest';
6
+ import type { ProjectionRegistrationOutcome } from '../../ArtifactRegistrationResult.js';
7
+ import type { ChronicleConnection } from '../../connection/ChronicleConnection.js';
8
+ import { createLogger } from '../../logging/createLogger.js';
9
+ import { registerProjectionWithRetry } from '../registerProjectionWithRetry.js';
10
+
11
+ chai.should();
12
+
13
+ describe('when reporting projection registration outcomes', () => {
14
+ let register: ReturnType<typeof vi.fn>;
15
+ let record: ReturnType<typeof vi.fn<(outcome: ProjectionRegistrationOutcome) => void>>;
16
+ let connection: ChronicleConnection;
17
+ const projection = { Identifier: 'projection' } as ProjectionDefinition;
18
+ const logger = createLogger('registration-spec');
19
+ const run = (maxAttempts?: number) => registerProjectionWithRetry(connection, 'store', logger, projection, 'projection', maxAttempts, record);
20
+
21
+ beforeEach(() => {
22
+ vi.useFakeTimers();
23
+ register = vi.fn().mockResolvedValue({});
24
+ record = vi.fn();
25
+ connection = { projections: { register } } as unknown as ChronicleConnection;
26
+ });
27
+ afterEach(() => { vi.useRealTimers(); });
28
+
29
+ it('should retain the actual response only after a transient failure recovers', async () => {
30
+ const response = {};
31
+ register.mockRejectedValueOnce(new Error('UNAVAILABLE')).mockResolvedValueOnce(response);
32
+ const registration = run();
33
+ await vi.advanceTimersByTimeAsync(1999);
34
+ register.mock.calls.should.have.lengthOf(1);
35
+ record.mock.calls.should.have.lengthOf(0);
36
+ await vi.advanceTimersByTimeAsync(1);
37
+ (await registration)!.should.equal(response);
38
+ record.mock.calls.should.deep.equal([[{ identifier: 'projection', state: 'successful', response }]]);
39
+ });
40
+
41
+ it('should preserve all five attempts and the growing delays before reporting the underlying failure', async () => {
42
+ const failure = Object.assign(new Error('UNAVAILABLE'), { code: 14 });
43
+ register.mockRejectedValue(failure);
44
+ const registration = run().catch(error => error);
45
+ for (const delay of [2000, 4000, 8000, 15000]) {
46
+ await vi.advanceTimersByTimeAsync(delay - 1);
47
+ record.mock.calls.should.have.lengthOf(0);
48
+ await vi.advanceTimersByTimeAsync(1);
49
+ }
50
+ const thrown = await registration;
51
+ thrown.message.should.equal("Failed to register projection 'projection' after 5 attempt(s): Error: UNAVAILABLE");
52
+ register.mock.calls.should.have.lengthOf(5);
53
+ record.mock.calls.should.deep.equal([[{ identifier: 'projection', state: 'failed', error: failure }]]);
54
+ });
55
+
56
+ it('should preserve immediate non-transient rejection without retrying', async () => {
57
+ const failure = new Error('Invalid declaration');
58
+ register.mockRejectedValue(failure);
59
+ const thrown = await run().catch(error => error);
60
+ thrown.message.should.equal("Failed to register projection 'projection' after 1 attempt(s): Error: Invalid declaration");
61
+ register.mock.calls.should.have.lengthOf(1);
62
+ record.mock.calls.should.deep.equal([[{ identifier: 'projection', state: 'failed', error: failure }]]);
63
+ });
64
+
65
+ it('should retain the no-attempt behavior without inventing an acknowledgment', async () => {
66
+ const response = await run(0);
67
+ (response === undefined).should.be.true;
68
+ register.mock.calls.should.have.lengthOf(0);
69
+ record.mock.calls.should.have.lengthOf(0);
70
+ });
71
+ });
@@ -3,6 +3,7 @@
3
3
 
4
4
  import { ProjectionOwner, type ProjectionDefinition } from '@cratis/chronicle.contracts';
5
5
  import type { ChronicleConnection } from '../connection/index.js';
6
+ import type { ProjectionRegistrationOutcome, ProjectionRegistrationResponse } from '../ArtifactRegistrationResult.js';
6
7
  import type { createLogger } from '../logging/createLogger.js';
7
8
 
8
9
  /**
@@ -13,7 +14,8 @@ import type { createLogger } from '../logging/createLogger.js';
13
14
  * @param projection - The projection definition to register.
14
15
  * @param identifier - The identifier of the projection, for reporting.
15
16
  * @param maxAttempts - The number of attempts before giving up.
16
- * @returns A promise that resolves when the projection is registered.
17
+ * @param record - Receives the actual kernel response or final underlying failure.
18
+ * @returns The kernel acknowledgment, or undefined if no attempts were requested.
17
19
  */
18
20
  export async function registerProjectionWithRetry(
19
21
  connection: ChronicleConnection,
@@ -21,23 +23,26 @@ export async function registerProjectionWithRetry(
21
23
  logger: ReturnType<typeof createLogger>,
22
24
  projection: ProjectionDefinition,
23
25
  identifier: string,
24
- maxAttempts = 5
25
- ): Promise<void> {
26
+ maxAttempts = 5,
27
+ record: (outcome: ProjectionRegistrationOutcome) => void = () => {}
28
+ ): Promise<ProjectionRegistrationResponse | undefined> {
26
29
  let delay = 2000;
27
30
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
28
31
  try {
29
32
  logger.info('Registering projection', { identifier, readModel: projection.ReadModel, attempt });
30
- await connection.projections.register({
33
+ const response = await connection.projections.register({
31
34
  EventStore: eventStore,
32
35
  Owner: ProjectionOwner.PROJECTION_OWNER_Client,
33
36
  Projections: [projection]
34
37
  });
35
38
  logger.info('Projection registered successfully', { identifier });
36
- return;
39
+ record({ identifier, state: 'successful', response });
40
+ return response;
37
41
  } catch (error) {
38
42
  const msg = String(error);
39
43
  const isTransient = msg.includes('UNKNOWN') || msg.includes('UNAVAILABLE') || msg.includes('INTERNAL');
40
44
  if (!isTransient || attempt === maxAttempts) {
45
+ record({ identifier, state: 'failed', error });
41
46
  throw new Error(`Failed to register projection '${identifier}' after ${attempt} attempt(s): ${msg}`);
42
47
  }
43
48
  logger.warn('Projection registration failed with transient error, retrying', {
@@ -50,4 +55,5 @@ export async function registerProjectionWithRetry(
50
55
  delay = Math.min(delay * 2, 15000);
51
56
  }
52
57
  }
58
+ return undefined;
53
59
  }