@venizia/ignis-kernel 0.4.8 → 0.5.0-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 (60) hide show
  1. package/dist/esm/base/applications/rest.d.ts +2 -2
  2. package/dist/esm/base/applications/rest.js.map +1 -1
  3. package/dist/esm/base/auth/authenticate/common/keys.d.ts +21 -7
  4. package/dist/esm/base/auth/authenticate/common/keys.js +34 -7
  5. package/dist/esm/base/auth/authenticate/common/keys.js.map +1 -1
  6. package/dist/esm/base/auth/authenticate/common/types/jwt.d.ts +8 -17
  7. package/dist/esm/base/auth/authenticate/common/types/jwt.js.map +1 -1
  8. package/dist/esm/base/auth/authenticate/common/types/rest.d.ts +3 -1
  9. package/dist/esm/base/auth/authenticate/common/types/rest.js.map +1 -1
  10. package/dist/esm/base/auth/authenticate/common/types/service.d.ts +3 -3
  11. package/dist/esm/base/auth/authenticate/common/types/service.js.map +1 -1
  12. package/dist/esm/base/auth/authorize/common/constants/binding-keys.d.ts +6 -3
  13. package/dist/esm/base/auth/authorize/common/constants/binding-keys.js +8 -3
  14. package/dist/esm/base/auth/authorize/common/constants/binding-keys.js.map +1 -1
  15. package/dist/esm/base/auth/authorize/enforcers/enforcer-registry.js.map +1 -1
  16. package/dist/esm/base/auth/base/abstract-auth-registry.d.ts +2 -1
  17. package/dist/esm/base/auth/base/abstract-auth-registry.js +2 -2
  18. package/dist/esm/base/auth/base/abstract-auth-registry.js.map +1 -1
  19. package/dist/esm/base/components/base.d.ts +3 -3
  20. package/dist/esm/base/components/base.js +3 -3
  21. package/dist/esm/base/components/base.js.map +1 -1
  22. package/dist/esm/base/components/controller/rest/common/types.d.ts +2 -1
  23. package/dist/esm/base/components/controller/rest/common/types.js +3 -1
  24. package/dist/esm/base/components/controller/rest/common/types.js.map +1 -1
  25. package/dist/esm/base/components/controller/rest/rest.component.js.map +1 -1
  26. package/dist/esm/base/controllers/factory/controller.js +4 -1
  27. package/dist/esm/base/controllers/factory/controller.js.map +1 -1
  28. package/dist/esm/base/controllers/factory/definition.d.ts +48 -48
  29. package/dist/esm/base/events/common/types.d.ts +2 -1
  30. package/dist/esm/base/events/common/types.js.map +1 -1
  31. package/dist/esm/base/events/event-bus.js.map +1 -1
  32. package/dist/esm/base/metadata/artifact-keys.d.ts +2 -1
  33. package/dist/esm/base/metadata/artifact-keys.js.map +1 -1
  34. package/dist/esm/base/metadata/injectable.d.ts +2 -1
  35. package/dist/esm/base/metadata/injectable.js.map +1 -1
  36. package/dist/esm/base/metadata/persistents/repository/injection.js.map +1 -1
  37. package/dist/esm/base/middlewares/emoji-favicon/emoji-favicon.middleware.js +2 -1
  38. package/dist/esm/base/middlewares/emoji-favicon/emoji-favicon.middleware.js.map +1 -1
  39. package/dist/esm/base/models/common/schemas.d.ts +9 -9
  40. package/dist/esm/base/models/common/schemas.js +1 -1
  41. package/dist/esm/base/models/common/schemas.js.map +1 -1
  42. package/dist/esm/base/repositories/common/response-reader.d.ts +10 -1
  43. package/dist/esm/base/repositories/common/response-reader.js +17 -3
  44. package/dist/esm/base/repositories/common/response-reader.js.map +1 -1
  45. package/dist/esm/common/bindings.d.ts +7 -7
  46. package/dist/esm/common/bindings.js +21 -7
  47. package/dist/esm/common/bindings.js.map +1 -1
  48. package/dist/esm/helpers/inversion/common/types/artifact.d.ts +2 -2
  49. package/dist/esm/helpers/inversion/common/types/artifact.js.map +1 -1
  50. package/dist/esm/helpers/inversion/index.d.ts +1 -1
  51. package/dist/esm/helpers/inversion/index.js.map +1 -1
  52. package/dist/esm/helpers/inversion/mixins/artifact.mixin.d.ts +5 -5
  53. package/dist/esm/helpers/inversion/mixins/controllers/controller.d.ts +5 -5
  54. package/dist/esm/helpers/inversion/mixins/controllers/grpc.d.ts +5 -5
  55. package/dist/esm/helpers/inversion/mixins/controllers/rest.d.ts +5 -5
  56. package/dist/esm/helpers/inversion/mixins/datasource.mixin.d.ts +5 -5
  57. package/dist/esm/helpers/inversion/mixins/model.mixin.d.ts +5 -5
  58. package/dist/esm/helpers/inversion/mixins/repository.mixin.d.ts +5 -5
  59. package/dist/esm/helpers/inversion/registry.d.ts +35 -35
  60. package/package.json +5 -5
@@ -294,7 +294,7 @@ export declare class RouteConfigResolver {
294
294
  '4XX': {
295
295
  description: string;
296
296
  content: {
297
- 'application/json': {
297
+ "application/json": {
298
298
  schema: z.ZodObject<{
299
299
  statusCode: z.ZodOptional<z.ZodNumber>;
300
300
  message: z.ZodString;
@@ -314,7 +314,7 @@ export declare class RouteConfigResolver {
314
314
  '5XX': {
315
315
  description: string;
316
316
  content: {
317
- 'application/json': {
317
+ "application/json": {
318
318
  schema: z.ZodObject<{
319
319
  statusCode: z.ZodOptional<z.ZodNumber>;
320
320
  message: z.ZodString;
@@ -334,7 +334,7 @@ export declare class RouteConfigResolver {
334
334
  200: {
335
335
  description: string;
336
336
  content: {
337
- 'application/json': {
337
+ "application/json": {
338
338
  schema: z.ZodUnion<readonly [z.ZodObject<{
339
339
  count: z.ZodDefault<z.ZodNumber>;
340
340
  data: z.ZodArray<SelectSchema>;
@@ -346,7 +346,7 @@ export declare class RouteConfigResolver {
346
346
  headers: import("../index.js").TResponseHeaders;
347
347
  description: string;
348
348
  content: {
349
- 'application/json': {
349
+ "application/json": {
350
350
  schema: z.ZodUnion<readonly [z.ZodObject<{
351
351
  count: z.ZodDefault<z.ZodNumber>;
352
352
  data: z.ZodArray<SelectSchema>;
@@ -383,7 +383,7 @@ export declare class RouteConfigResolver {
383
383
  '4XX': {
384
384
  description: string;
385
385
  content: {
386
- 'application/json': {
386
+ "application/json": {
387
387
  schema: z.ZodObject<{
388
388
  statusCode: z.ZodOptional<z.ZodNumber>;
389
389
  message: z.ZodString;
@@ -403,7 +403,7 @@ export declare class RouteConfigResolver {
403
403
  '5XX': {
404
404
  description: string;
405
405
  content: {
406
- 'application/json': {
406
+ "application/json": {
407
407
  schema: z.ZodObject<{
408
408
  statusCode: z.ZodOptional<z.ZodNumber>;
409
409
  message: z.ZodString;
@@ -423,7 +423,7 @@ export declare class RouteConfigResolver {
423
423
  200: {
424
424
  description: string;
425
425
  content: {
426
- 'application/json': {
426
+ "application/json": {
427
427
  schema: z.ZodUnion<readonly [z.ZodObject<{
428
428
  count: z.ZodDefault<z.ZodNumber>;
429
429
  data: SelectSchema;
@@ -435,7 +435,7 @@ export declare class RouteConfigResolver {
435
435
  headers: import("../index.js").TResponseHeaders;
436
436
  description: string;
437
437
  content: {
438
- 'application/json': {
438
+ "application/json": {
439
439
  schema: z.ZodUnion<readonly [z.ZodObject<{
440
440
  count: z.ZodDefault<z.ZodNumber>;
441
441
  data: SelectSchema;
@@ -465,7 +465,7 @@ export declare class RouteConfigResolver {
465
465
  body?: {
466
466
  description: string;
467
467
  content: {
468
- 'application/json': {
468
+ "application/json": {
469
469
  schema: TAnyObjectSchema;
470
470
  };
471
471
  };
@@ -479,7 +479,7 @@ export declare class RouteConfigResolver {
479
479
  '4XX': {
480
480
  description: string;
481
481
  content: {
482
- 'application/json': {
482
+ "application/json": {
483
483
  schema: z.ZodObject<{
484
484
  statusCode: z.ZodOptional<z.ZodNumber>;
485
485
  message: z.ZodString;
@@ -499,7 +499,7 @@ export declare class RouteConfigResolver {
499
499
  '5XX': {
500
500
  description: string;
501
501
  content: {
502
- 'application/json': {
502
+ "application/json": {
503
503
  schema: z.ZodObject<{
504
504
  statusCode: z.ZodOptional<z.ZodNumber>;
505
505
  message: z.ZodString;
@@ -519,7 +519,7 @@ export declare class RouteConfigResolver {
519
519
  200: {
520
520
  description: string;
521
521
  content: {
522
- 'application/json': {
522
+ "application/json": {
523
523
  schema: z.ZodUnion<readonly [z.ZodObject<{
524
524
  count: z.ZodDefault<z.ZodNumber>;
525
525
  data: z.ZodArray<SelectSchema>;
@@ -531,7 +531,7 @@ export declare class RouteConfigResolver {
531
531
  headers: import("../index.js").TResponseHeaders;
532
532
  description: string;
533
533
  content: {
534
- 'application/json': {
534
+ "application/json": {
535
535
  schema: z.ZodUnion<readonly [z.ZodObject<{
536
536
  count: z.ZodDefault<z.ZodNumber>;
537
537
  data: z.ZodArray<SelectSchema>;
@@ -568,7 +568,7 @@ export declare class RouteConfigResolver {
568
568
  '4XX': {
569
569
  description: string;
570
570
  content: {
571
- 'application/json': {
571
+ "application/json": {
572
572
  schema: z.ZodObject<{
573
573
  statusCode: z.ZodOptional<z.ZodNumber>;
574
574
  message: z.ZodString;
@@ -588,7 +588,7 @@ export declare class RouteConfigResolver {
588
588
  '5XX': {
589
589
  description: string;
590
590
  content: {
591
- 'application/json': {
591
+ "application/json": {
592
592
  schema: z.ZodObject<{
593
593
  statusCode: z.ZodOptional<z.ZodNumber>;
594
594
  message: z.ZodString;
@@ -608,7 +608,7 @@ export declare class RouteConfigResolver {
608
608
  200: {
609
609
  description: string;
610
610
  content: {
611
- 'application/json': {
611
+ "application/json": {
612
612
  schema: z.ZodUnion<readonly [z.ZodObject<{
613
613
  count: z.ZodDefault<z.ZodNumber>;
614
614
  data: SelectSchema;
@@ -620,7 +620,7 @@ export declare class RouteConfigResolver {
620
620
  headers: import("../index.js").TResponseHeaders;
621
621
  description: string;
622
622
  content: {
623
- 'application/json': {
623
+ "application/json": {
624
624
  schema: z.ZodUnion<readonly [z.ZodObject<{
625
625
  count: z.ZodDefault<z.ZodNumber>;
626
626
  data: SelectSchema;
@@ -647,7 +647,7 @@ export declare class RouteConfigResolver {
647
647
  body: {
648
648
  description: string;
649
649
  content: {
650
- 'application/json': {
650
+ "application/json": {
651
651
  schema: TAnyObjectSchema;
652
652
  };
653
653
  };
@@ -664,7 +664,7 @@ export declare class RouteConfigResolver {
664
664
  '4XX': {
665
665
  description: string;
666
666
  content: {
667
- 'application/json': {
667
+ "application/json": {
668
668
  schema: z.ZodObject<{
669
669
  statusCode: z.ZodOptional<z.ZodNumber>;
670
670
  message: z.ZodString;
@@ -684,7 +684,7 @@ export declare class RouteConfigResolver {
684
684
  '5XX': {
685
685
  description: string;
686
686
  content: {
687
- 'application/json': {
687
+ "application/json": {
688
688
  schema: z.ZodObject<{
689
689
  statusCode: z.ZodOptional<z.ZodNumber>;
690
690
  message: z.ZodString;
@@ -704,7 +704,7 @@ export declare class RouteConfigResolver {
704
704
  200: {
705
705
  description: string;
706
706
  content: {
707
- 'application/json': {
707
+ "application/json": {
708
708
  schema: z.ZodUnion<readonly [z.ZodObject<{
709
709
  count: z.ZodDefault<z.ZodNumber>;
710
710
  data: z.ZodArray<SelectSchema>;
@@ -716,7 +716,7 @@ export declare class RouteConfigResolver {
716
716
  headers: import("../index.js").TResponseHeaders;
717
717
  description: string;
718
718
  content: {
719
- 'application/json': {
719
+ "application/json": {
720
720
  schema: z.ZodUnion<readonly [z.ZodObject<{
721
721
  count: z.ZodDefault<z.ZodNumber>;
722
722
  data: z.ZodArray<SelectSchema>;
@@ -745,7 +745,7 @@ export declare class RouteConfigResolver {
745
745
  body: {
746
746
  description: string;
747
747
  content: {
748
- 'application/json': {
748
+ "application/json": {
749
749
  schema: TAnyObjectSchema;
750
750
  };
751
751
  };
@@ -762,7 +762,7 @@ export declare class RouteConfigResolver {
762
762
  '4XX': {
763
763
  description: string;
764
764
  content: {
765
- 'application/json': {
765
+ "application/json": {
766
766
  schema: z.ZodObject<{
767
767
  statusCode: z.ZodOptional<z.ZodNumber>;
768
768
  message: z.ZodString;
@@ -782,7 +782,7 @@ export declare class RouteConfigResolver {
782
782
  '5XX': {
783
783
  description: string;
784
784
  content: {
785
- 'application/json': {
785
+ "application/json": {
786
786
  schema: z.ZodObject<{
787
787
  statusCode: z.ZodOptional<z.ZodNumber>;
788
788
  message: z.ZodString;
@@ -802,7 +802,7 @@ export declare class RouteConfigResolver {
802
802
  200: {
803
803
  description: string;
804
804
  content: {
805
- 'application/json': {
805
+ "application/json": {
806
806
  schema: z.ZodUnion<readonly [z.ZodObject<{
807
807
  count: z.ZodDefault<z.ZodNumber>;
808
808
  data: SelectSchema;
@@ -814,7 +814,7 @@ export declare class RouteConfigResolver {
814
814
  headers: import("../index.js").TResponseHeaders;
815
815
  description: string;
816
816
  content: {
817
- 'application/json': {
817
+ "application/json": {
818
818
  schema: z.ZodUnion<readonly [z.ZodObject<{
819
819
  count: z.ZodDefault<z.ZodNumber>;
820
820
  data: SelectSchema;
@@ -838,7 +838,7 @@ export declare class RouteConfigResolver {
838
838
  body: {
839
839
  description: string;
840
840
  content: {
841
- 'application/json': {
841
+ "application/json": {
842
842
  schema: TAnyObjectSchema;
843
843
  };
844
844
  };
@@ -855,7 +855,7 @@ export declare class RouteConfigResolver {
855
855
  '4XX': {
856
856
  description: string;
857
857
  content: {
858
- 'application/json': {
858
+ "application/json": {
859
859
  schema: z.ZodObject<{
860
860
  statusCode: z.ZodOptional<z.ZodNumber>;
861
861
  message: z.ZodString;
@@ -875,7 +875,7 @@ export declare class RouteConfigResolver {
875
875
  '5XX': {
876
876
  description: string;
877
877
  content: {
878
- 'application/json': {
878
+ "application/json": {
879
879
  schema: z.ZodObject<{
880
880
  statusCode: z.ZodOptional<z.ZodNumber>;
881
881
  message: z.ZodString;
@@ -895,7 +895,7 @@ export declare class RouteConfigResolver {
895
895
  200: {
896
896
  description: string;
897
897
  content: {
898
- 'application/json': {
898
+ "application/json": {
899
899
  schema: z.ZodUnion<readonly [z.ZodObject<{
900
900
  count: z.ZodDefault<z.ZodNumber>;
901
901
  data: SelectSchema;
@@ -907,7 +907,7 @@ export declare class RouteConfigResolver {
907
907
  headers: import("../index.js").TResponseHeaders;
908
908
  description: string;
909
909
  content: {
910
- 'application/json': {
910
+ "application/json": {
911
911
  schema: z.ZodUnion<readonly [z.ZodObject<{
912
912
  count: z.ZodDefault<z.ZodNumber>;
913
913
  data: SelectSchema;
@@ -964,7 +964,7 @@ export declare class RouteConfigResolver {
964
964
  '4XX': {
965
965
  description: string;
966
966
  content: {
967
- 'application/json': {
967
+ "application/json": {
968
968
  schema: z.ZodObject<{
969
969
  statusCode: z.ZodOptional<z.ZodNumber>;
970
970
  message: z.ZodString;
@@ -984,7 +984,7 @@ export declare class RouteConfigResolver {
984
984
  '5XX': {
985
985
  description: string;
986
986
  content: {
987
- 'application/json': {
987
+ "application/json": {
988
988
  schema: z.ZodObject<{
989
989
  statusCode: z.ZodOptional<z.ZodNumber>;
990
990
  message: z.ZodString;
@@ -1004,7 +1004,7 @@ export declare class RouteConfigResolver {
1004
1004
  200: {
1005
1005
  description: string;
1006
1006
  content: {
1007
- 'application/json': {
1007
+ "application/json": {
1008
1008
  schema: z.ZodUnion<readonly [z.ZodObject<{
1009
1009
  count: z.ZodDefault<z.ZodNumber>;
1010
1010
  data: SelectSchema;
@@ -1016,7 +1016,7 @@ export declare class RouteConfigResolver {
1016
1016
  headers: import("../index.js").TResponseHeaders;
1017
1017
  description: string;
1018
1018
  content: {
1019
- 'application/json': {
1019
+ "application/json": {
1020
1020
  schema: z.ZodUnion<readonly [z.ZodObject<{
1021
1021
  count: z.ZodDefault<z.ZodNumber>;
1022
1022
  data: SelectSchema;
@@ -1078,7 +1078,7 @@ export declare class RouteConfigResolver {
1078
1078
  '4XX': {
1079
1079
  description: string;
1080
1080
  content: {
1081
- 'application/json': {
1081
+ "application/json": {
1082
1082
  schema: z.ZodObject<{
1083
1083
  statusCode: z.ZodOptional<z.ZodNumber>;
1084
1084
  message: z.ZodString;
@@ -1098,7 +1098,7 @@ export declare class RouteConfigResolver {
1098
1098
  '5XX': {
1099
1099
  description: string;
1100
1100
  content: {
1101
- 'application/json': {
1101
+ "application/json": {
1102
1102
  schema: z.ZodObject<{
1103
1103
  statusCode: z.ZodOptional<z.ZodNumber>;
1104
1104
  message: z.ZodString;
@@ -1118,7 +1118,7 @@ export declare class RouteConfigResolver {
1118
1118
  200: {
1119
1119
  description: string;
1120
1120
  content: {
1121
- 'application/json': {
1121
+ "application/json": {
1122
1122
  schema: z.ZodUnion<readonly [z.ZodObject<{
1123
1123
  count: z.ZodDefault<z.ZodNumber>;
1124
1124
  data: SelectSchema;
@@ -1130,7 +1130,7 @@ export declare class RouteConfigResolver {
1130
1130
  headers: import("../index.js").TResponseHeaders;
1131
1131
  description: string;
1132
1132
  content: {
1133
- 'application/json': {
1133
+ "application/json": {
1134
1134
  schema: z.ZodUnion<readonly [z.ZodObject<{
1135
1135
  count: z.ZodDefault<z.ZodNumber>;
1136
1136
  data: SelectSchema;
@@ -1187,7 +1187,7 @@ export declare class RouteConfigResolver {
1187
1187
  '4XX': {
1188
1188
  description: string;
1189
1189
  content: {
1190
- 'application/json': {
1190
+ "application/json": {
1191
1191
  schema: z.ZodObject<{
1192
1192
  statusCode: z.ZodOptional<z.ZodNumber>;
1193
1193
  message: z.ZodString;
@@ -1207,7 +1207,7 @@ export declare class RouteConfigResolver {
1207
1207
  '5XX': {
1208
1208
  description: string;
1209
1209
  content: {
1210
- 'application/json': {
1210
+ "application/json": {
1211
1211
  schema: z.ZodObject<{
1212
1212
  statusCode: z.ZodOptional<z.ZodNumber>;
1213
1213
  message: z.ZodString;
@@ -1227,7 +1227,7 @@ export declare class RouteConfigResolver {
1227
1227
  200: {
1228
1228
  description: string;
1229
1229
  content: {
1230
- 'application/json': {
1230
+ "application/json": {
1231
1231
  schema: z.ZodUnion<readonly [z.ZodObject<{
1232
1232
  count: z.ZodDefault<z.ZodNumber>;
1233
1233
  data: z.ZodArray<SelectSchema>;
@@ -1239,7 +1239,7 @@ export declare class RouteConfigResolver {
1239
1239
  headers: import("../index.js").TResponseHeaders;
1240
1240
  description: string;
1241
1241
  content: {
1242
- 'application/json': {
1242
+ "application/json": {
1243
1243
  schema: z.ZodUnion<readonly [z.ZodObject<{
1244
1244
  count: z.ZodDefault<z.ZodNumber>;
1245
1245
  data: z.ZodArray<SelectSchema>;
@@ -1273,7 +1273,7 @@ export declare class RouteConfigResolver {
1273
1273
  '4XX': {
1274
1274
  description: string;
1275
1275
  content: {
1276
- 'application/json': {
1276
+ "application/json": {
1277
1277
  schema: z.ZodObject<{
1278
1278
  statusCode: z.ZodOptional<z.ZodNumber>;
1279
1279
  message: z.ZodString;
@@ -1293,7 +1293,7 @@ export declare class RouteConfigResolver {
1293
1293
  '5XX': {
1294
1294
  description: string;
1295
1295
  content: {
1296
- 'application/json': {
1296
+ "application/json": {
1297
1297
  schema: z.ZodObject<{
1298
1298
  statusCode: z.ZodOptional<z.ZodNumber>;
1299
1299
  message: z.ZodString;
@@ -1313,7 +1313,7 @@ export declare class RouteConfigResolver {
1313
1313
  200: {
1314
1314
  description: string;
1315
1315
  content: {
1316
- 'application/json': {
1316
+ "application/json": {
1317
1317
  schema: z.ZodObject<{
1318
1318
  count: z.ZodDefault<z.ZodNumber>;
1319
1319
  }, z.core.$strip>;
@@ -1324,7 +1324,7 @@ export declare class RouteConfigResolver {
1324
1324
  headers: import("../index.js").TResponseHeaders;
1325
1325
  description: string;
1326
1326
  content: {
1327
- 'application/json': {
1327
+ "application/json": {
1328
1328
  schema: z.ZodObject<{
1329
1329
  count: z.ZodDefault<z.ZodNumber>;
1330
1330
  }, z.core.$strip>;
@@ -1,3 +1,4 @@
1
+ import type { TBindingKey } from '../../../helpers/inversion/index.js';
1
2
  import type { ValueOrPromise } from '@venizia/ignis-helpers/common';
2
3
  import { type EventHandlerTypes } from './constants.js';
3
4
  /** One occurrence of a named domain event, decoupled from whatever publishes or handles it. */
@@ -33,7 +34,7 @@ export type TEventHandlerFunction<TPayload = unknown> = (opts: {
33
34
  /** `register`'s binding-key handler shape: resolved from the container by `key` on every retry attempt. */
34
35
  export interface IEventHandlerBindingKeyReference {
35
36
  type: typeof EventHandlerTypes.BINDING_KEY;
36
- key: string;
37
+ key: TBindingKey<IEventHandler>;
37
38
  }
38
39
  /** `register`'s function handler shape: `fn` is invoked directly, captured as a closure - see `TEventHandlerReference`. */
39
40
  export interface IEventHandlerFunctionReference<TPayload = unknown> {
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/base/events/common/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { ValueOrPromise } from '@venizia/ignis-helpers/common';\nimport { type EventHandlerTypes } from './constants';\n\n/** One occurrence of a named domain event, decoupled from whatever publishes or handles it. */\nexport interface IDomainEvent<TPayload = unknown> {\n name: string;\n payload: TPayload;\n occurredAt: string;\n traceId?: string;\n}\n\n/**\n * Per-registration retry override for `EventBus.register`. Both fields must be positive integers,\n * and are bounded by `EventDispatchRetry.MAX_ATTEMPTS_CEILING` / `MAX_TOTAL_WINDOW_MS` - a value\n * outside either throws at `register()`, never clamps.\n */\nexport interface IEventHandlerRetryOptions {\n /**\n * Attempts per dispatch.\n *\n * @default 3\n */\n maxAttempts?: number;\n\n /**\n * First backoff delay in ms; exponential growth is computed from it.\n *\n * @default 100\n */\n baseDelayMs?: number;\n}\n\n/** A handler callback - synchronous or asynchronous, `EventBus` awaits either the same way. */\nexport type TEventHandlerFunction<TPayload = unknown> = (opts: {\n event: IDomainEvent<TPayload>;\n}) => ValueOrPromise<void>;\n\n/** `register`'s binding-key handler shape: resolved from the container by `key` on every retry attempt. */\nexport interface IEventHandlerBindingKeyReference {\n type: typeof EventHandlerTypes.BINDING_KEY;\n key: string;\n}\n\n/** `register`'s function handler shape: `fn` is invoked directly, captured as a closure - see `TEventHandlerReference`. */\nexport interface IEventHandlerFunctionReference<TPayload = unknown> {\n type: typeof EventHandlerTypes.FUNCTION;\n fn: TEventHandlerFunction<TPayload>;\n}\n\n/**\n * The two shapes `EventBus.register`'s `handler` accepts, tagged by `type` so the caller states\n * which rather than the bus inferring it from whichever field is present. Only `BINDING_KEY` shares\n * `IEventHandler`'s rebind property; see its doc.\n */\nexport type TEventHandlerReference<TPayload = unknown> =\n | IEventHandlerBindingKeyReference\n | IEventHandlerFunctionReference<TPayload>;\n\n/**\n * Handles one `IDomainEvent`. Implemented by whatever is bound into the container under\n * `register`'s `{ type: EventHandlerTypes.BINDING_KEY, key }` form - see `TEventHandlerReference`\n * for the `FUNCTION` form, which does not implement this interface and does not share its rebind\n * property.\n *\n * MUST be idempotent. The bus retries a failed handler, so delivery is at-least-once: one that\n * half-succeeds then throws runs again from the top, re-applying whatever already landed. Three\n * shapes break, and only the first looks dangerous: a cumulative write (`count = count + 1`, or a\n * rolling average, which drifts toward the resampled value); several writes batched under one\n * `Promise.all`, where any failure re-runs the ones that succeeded; and a bare INSERT of a log or\n * audit row, which simply gains a duplicate - corrupting the record used to diagnose the retry.\n *\n * Resolved from the container by binding key at dispatch time, never captured as a direct reference,\n * so rebinding the key takes effect on the next attempt - including one already in flight. A\n * `FUNCTION`-form handler does NOT have this property: `fn` is a captured closure, so every attempt\n * in a long retry window calls the exact function registered at startup.\n */\nexport interface IEventHandler<TEvent extends IDomainEvent = IDomainEvent> {\n handle(opts: { event: TEvent }): ValueOrPromise<void>;\n}\n"]}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/base/events/common/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { TBindingKey } from '@/helpers/inversion';\nimport type { ValueOrPromise } from '@venizia/ignis-helpers/common';\nimport { type EventHandlerTypes } from './constants';\n\n/** One occurrence of a named domain event, decoupled from whatever publishes or handles it. */\nexport interface IDomainEvent<TPayload = unknown> {\n name: string;\n payload: TPayload;\n occurredAt: string;\n traceId?: string;\n}\n\n/**\n * Per-registration retry override for `EventBus.register`. Both fields must be positive integers,\n * and are bounded by `EventDispatchRetry.MAX_ATTEMPTS_CEILING` / `MAX_TOTAL_WINDOW_MS` - a value\n * outside either throws at `register()`, never clamps.\n */\nexport interface IEventHandlerRetryOptions {\n /**\n * Attempts per dispatch.\n *\n * @default 3\n */\n maxAttempts?: number;\n\n /**\n * First backoff delay in ms; exponential growth is computed from it.\n *\n * @default 100\n */\n baseDelayMs?: number;\n}\n\n/** A handler callback - synchronous or asynchronous, `EventBus` awaits either the same way. */\nexport type TEventHandlerFunction<TPayload = unknown> = (opts: {\n event: IDomainEvent<TPayload>;\n}) => ValueOrPromise<void>;\n\n/** `register`'s binding-key handler shape: resolved from the container by `key` on every retry attempt. */\nexport interface IEventHandlerBindingKeyReference {\n type: typeof EventHandlerTypes.BINDING_KEY;\n key: TBindingKey<IEventHandler>;\n}\n\n/** `register`'s function handler shape: `fn` is invoked directly, captured as a closure - see `TEventHandlerReference`. */\nexport interface IEventHandlerFunctionReference<TPayload = unknown> {\n type: typeof EventHandlerTypes.FUNCTION;\n fn: TEventHandlerFunction<TPayload>;\n}\n\n/**\n * The two shapes `EventBus.register`'s `handler` accepts, tagged by `type` so the caller states\n * which rather than the bus inferring it from whichever field is present. Only `BINDING_KEY` shares\n * `IEventHandler`'s rebind property; see its doc.\n */\nexport type TEventHandlerReference<TPayload = unknown> =\n | IEventHandlerBindingKeyReference\n | IEventHandlerFunctionReference<TPayload>;\n\n/**\n * Handles one `IDomainEvent`. Implemented by whatever is bound into the container under\n * `register`'s `{ type: EventHandlerTypes.BINDING_KEY, key }` form - see `TEventHandlerReference`\n * for the `FUNCTION` form, which does not implement this interface and does not share its rebind\n * property.\n *\n * MUST be idempotent. The bus retries a failed handler, so delivery is at-least-once: one that\n * half-succeeds then throws runs again from the top, re-applying whatever already landed. Three\n * shapes break, and only the first looks dangerous: a cumulative write (`count = count + 1`, or a\n * rolling average, which drifts toward the resampled value); several writes batched under one\n * `Promise.all`, where any failure re-runs the ones that succeeded; and a bare INSERT of a log or\n * audit row, which simply gains a duplicate - corrupting the record used to diagnose the retry.\n *\n * Resolved from the container by binding key at dispatch time, never captured as a direct reference,\n * so rebinding the key takes effect on the next attempt - including one already in flight. A\n * `FUNCTION`-form handler does NOT have this property: `fn` is a captured closure, so every attempt\n * in a long retry window calls the exact function registered at startup.\n */\nexport interface IEventHandler<TEvent extends IDomainEvent = IDomainEvent> {\n handle(opts: { event: TEvent }): ValueOrPromise<void>;\n}\n"]}
@@ -1 +1 @@
1
- {"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../../../src/base/events/event-bus.ts"],"names":[],"mappings":"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","sourcesContent":["import { ObjectUtility } from '@venizia/ignis-helpers/common';\nimport type { Container } from '@/helpers/inversion/container';\nimport type { ValueOrPromise } from '@venizia/ignis-helpers/common';\nimport {\n BaseHelper,\n getError,\n RetryBackoffStrategies,\n RetryHelper,\n RetryJitterModes,\n} from '@venizia/ignis-helpers/core';\nimport { EventDispatchRetry, EventHandlerTypes } from './common/constants';\nimport type {\n IDomainEvent,\n IEventHandler,\n IEventHandlerRetryOptions,\n TEventHandlerReference,\n} from './common/types';\n\n/** One `register`ed handler, resolved to concrete retry numbers and a ready-to-call invoker -\n * `EventDispatchRetry`'s defaults already applied and `handler`'s shape already resolved, so\n * `dispatch` never has to branch on either. */\ninterface IResolvedEventRegistration {\n // A method signature on purpose: its parameter is bivariant, so a registration holds the invoker of any payload type, which the registry cannot tell apart.\n invokeHandler(opts: { event: IDomainEvent<unknown> }): ValueOrPromise<void>;\n /** For the exhaustion log line only - a binding key or `<function fn.name>`. */\n description: string;\n maxAttempts: number;\n baseDelayMs: number;\n}\n\n/** In-process, fire-and-forget domain event bus. `TPayloadMap` keys the event names, so a wrong name\n * or payload shape is a compile error. Delivery is always async. Retry timing is a property of the\n * handler's own failure mode, not of the event, so `register` may tune it per registration. But\n * nobody awaits a fire-and-forget dispatch, so an unbounded window would let one event hold a\n * handler - and whatever it holds open, e.g. a database connection - for an unbounded time with no\n * one to report it. What the bus guarantees instead: a bounded MAXIMUM time a single dispatch can\n * occupy, enforced as a hard ceiling at `register()` - see `EventDispatchRetry`. Retry makes\n * delivery at-least-once: handlers must be idempotent, see `IEventHandler`. */\nexport class EventBus<TPayloadMap extends object> extends BaseHelper {\n private readonly container: Container;\n\n /** `register` appends, never replaces - two handlers may share an event name, and replacing would\n * drop the first with no way for the caller to notice. */\n private readonly registrationsByName: Map<string, IResolvedEventRegistration[]>;\n\n constructor(opts: { scope?: string; container: Container }) {\n super({ scope: opts.scope ?? EventBus.name });\n this.container = opts.container;\n this.registrationsByName = new Map();\n }\n\n /** The pre-jitter total of every inter-attempt delay `maxAttempts`/`baseDelayMs` would produce -\n * jitter (always on, see `dispatch`) only ever shrinks a delay, so this is a true upper bound. */\n private static computeTotalWindowMs(opts: { maxAttempts: number; baseDelayMs: number }): number {\n const { maxAttempts, baseDelayMs } = opts;\n let totalWindowMs = 0;\n\n for (let attempt = 1; attempt < maxAttempts; attempt++) {\n totalWindowMs += RetryHelper.computeBackoffDelayMs({\n attempt,\n backoff: {\n strategy: RetryBackoffStrategies.EXPONENTIAL,\n initialDelayMs: baseDelayMs,\n jitter: RetryJitterModes.NONE,\n },\n });\n }\n\n return totalWindowMs;\n }\n\n /** Loud rejection, never a silent clamp: a caller who believes a number the bus does not honour is\n * worse off than one who sees the ceiling at boot. */\n private static assertValidRetry(opts: {\n name: string;\n maxAttempts: number;\n baseDelayMs: number;\n }): void {\n const { name, maxAttempts, baseDelayMs } = opts;\n\n if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {\n throw getError({\n message: `[EventBus][register] retry.maxAttempts must be a positive integer | name: ${name} | Got: ${maxAttempts}`,\n });\n }\n\n if (!Number.isInteger(baseDelayMs) || baseDelayMs < 1) {\n throw getError({\n message: `[EventBus][register] retry.baseDelayMs must be a positive integer | name: ${name} | Got: ${baseDelayMs}`,\n });\n }\n\n if (maxAttempts > EventDispatchRetry.MAX_ATTEMPTS_CEILING) {\n throw getError({\n message: `[EventBus][register] retry.maxAttempts exceeds the ceiling | name: ${name} | Got: ${maxAttempts} | Ceiling: ${EventDispatchRetry.MAX_ATTEMPTS_CEILING} | Lower retry.maxAttempts`,\n });\n }\n\n const totalWindowMs = EventBus.computeTotalWindowMs({ maxAttempts, baseDelayMs });\n\n if (totalWindowMs > EventDispatchRetry.MAX_TOTAL_WINDOW_MS) {\n throw getError({\n message: `[EventBus][register] retry window exceeds the ceiling | name: ${name} | Got: ${totalWindowMs}ms | Ceiling: ${EventDispatchRetry.MAX_TOTAL_WINDOW_MS}ms | Lower retry.maxAttempts or retry.baseDelayMs`,\n });\n }\n }\n\n /**\n * Turns `handler` into a uniform invoker plus a description for the exhaustion log line.\n * `BINDING_KEY` resolves through the container INSIDE the returned closure, so every call re-reads\n * the current binding; `FUNCTION` calls `fn` directly, so the closure IS the resolution - there is\n * nothing left to re-read on a later attempt. The tag (`handler.type`) is what this switches on,\n * not which field happens to be present - see `EventHandlerTypes`' doc.\n */\n private static buildHandlerInvoker<TPayload>(opts: {\n container: Container;\n handler: TEventHandlerReference<TPayload>;\n name: string;\n }): {\n invokeHandler: (opts: { event: IDomainEvent<TPayload> }) => ValueOrPromise<void>;\n description: string;\n } {\n const { container, handler, name } = opts;\n\n if (ObjectUtility.isEmpty({ value: handler })) {\n throw getError({\n message: `[EventBus][register] Invalid handler | name: ${name} | Got: ${handler}`,\n });\n }\n\n switch (handler.type) {\n case EventHandlerTypes.BINDING_KEY: {\n const { key } = handler;\n\n if (ObjectUtility.isEmpty({ value: key })) {\n throw getError({\n message: `[EventBus][register] Invalid handler.key | name: ${name} | Got: ${key}`,\n });\n }\n\n return {\n invokeHandler: ({ event }) => container.get<IEventHandler>({ key }).handle({ event }),\n description: `binding-key:${key}`,\n };\n }\n\n case EventHandlerTypes.FUNCTION: {\n const { fn } = handler;\n\n if (typeof fn !== 'function') {\n throw getError({\n message: `[EventBus][register] Invalid handler.fn | name: ${name} | Expected a function | Got: ${typeof fn}`,\n });\n }\n\n return {\n invokeHandler: ({ event }) => fn({ event }),\n description: `function:${fn.name || 'anonymous'}`,\n };\n }\n\n default: {\n throw getError({\n message: `[EventBus][register] Unknown handler.type | name: ${name} | Expected one of: ${[...EventHandlerTypes.SCHEME_SET].join(', ')} | Got: ${(handler as { type?: unknown }).type}`,\n });\n }\n }\n }\n\n /**\n * `retry` is optional and per REGISTRATION, not per publish: the right window belongs to the\n * handler's own failure mode, and two handlers on the same event name may each pick their own.\n * Omitting it reproduces today's `EventDispatchRetry` defaults exactly. Both `maxAttempts` and the\n * total backoff window it implies are bounded - see `EventDispatchRetry` - and exceeding either\n * throws here, at boot where a human sees it, rather than being silently clamped at dispatch time.\n */\n register<K extends keyof TPayloadMap & string>(opts: {\n name: K;\n /** A `BINDING_KEY` reference re-resolves through the container on every retry attempt, so a\n * rebind reaches a dispatch already in flight. A `FUNCTION` reference is captured as-is: a\n * rebind has nothing to reach, and every attempt in a long retry window calls the exact `fn`\n * registered here. */\n handler: TEventHandlerReference<TPayloadMap[K]>;\n retry?: IEventHandlerRetryOptions;\n }): void {\n const { name, handler, retry } = opts;\n\n if (ObjectUtility.isEmpty({ value: name })) {\n throw getError({\n message: `[EventBus][register] Invalid registration | name: ${String(name)}`,\n });\n }\n\n const maxAttempts = retry?.maxAttempts ?? EventDispatchRetry.MAX_ATTEMPTS;\n const baseDelayMs = retry?.baseDelayMs ?? EventDispatchRetry.BASE_DELAY_MS;\n EventBus.assertValidRetry({ name, maxAttempts, baseDelayMs });\n\n const { invokeHandler, description } = EventBus.buildHandlerInvoker({\n container: this.container,\n handler,\n name,\n });\n\n const registration: IResolvedEventRegistration = {\n invokeHandler,\n description,\n maxAttempts,\n baseDelayMs,\n };\n\n const existing = this.registrationsByName.get(name);\n\n if (existing) {\n existing.push(registration);\n\n return;\n }\n\n this.registrationsByName.set(name, [registration]);\n }\n\n /**\n * Never blocks and never throws back to the caller: dispatch runs outside this call's flow via\n * `queueMicrotask`, and a handler failure is caught and logged where it happens (`dispatch`),\n * never here.\n */\n publish<K extends keyof TPayloadMap & string>(opts: {\n name: K;\n payload: TPayloadMap[K];\n traceId?: string;\n }): void {\n const { name, payload, traceId } = opts;\n\n const event: IDomainEvent<TPayloadMap[K]> = {\n name,\n payload,\n occurredAt: new Date().toISOString(),\n traceId,\n };\n\n const registrations = this.registrationsByName.get(name);\n\n if (!registrations?.length) {\n // A typo is already a compile error, so at runtime this only means nobody is listening yet -\n // a legitimate state on a fire-and-forget bus, not an incident.\n this.logger.debug('[publish] No handler registered | name: %s | traceId: %s', name, traceId);\n\n return;\n }\n\n for (const registration of registrations) {\n queueMicrotask(() => {\n // `dispatch` catches every failure path itself and never rejects - this `.catch` is an\n // unreachable backstop, kept (and logged) rather than left floating, for the day it isn't.\n this.dispatch({ event, registration }).catch((error: unknown) => {\n this.logger.error(\n '[publish] Unexpected dispatch failure | name: %s | Error: %s',\n event.name,\n error,\n );\n });\n });\n }\n }\n\n /**\n * Attempts/backoff come from the registration (`EventDispatchRetry`'s defaults when omitted),\n * always with full jitter - `RetryJitterModes.FULL` decorrelates a shared-resource pile-up hardest,\n * so many handlers retrying the same lock do not collide on the same instant a second and third\n * time. `invokeHandler` already encodes whether that re-resolves (`BINDING_KEY`) or was captured\n * once (`FUNCTION`) - see `buildHandlerInvoker` - so this method calls it uniformly. A handler that\n * throws synchronously is caught exactly like one that returns a rejected promise: `execution`\n * here is itself `async`, and JS converts a synchronous throw inside an async function body into a\n * rejection of that function's own promise - `RetryHelper.executeWithRetry`'s attempt loop never\n * sees the difference.\n *\n * `RetryHelper.executeWithRetry` is used without its own `logger` - its internal per-attempt/exhaustion\n * logging knows nothing about the event name or `traceId`, so it cannot be the trace anyone\n * relies on. The one line below, logged only on final failure, is.\n */\n private async dispatch(opts: {\n event: IDomainEvent<unknown>;\n registration: IResolvedEventRegistration;\n }): Promise<void> {\n const { event, registration } = opts;\n const { invokeHandler, description, maxAttempts, baseDelayMs } = registration;\n let lastAttempt = 0;\n\n try {\n await RetryHelper.executeWithRetry({\n operation: `EventBus.dispatch:${event.name}`,\n maxAttempts,\n backoff: {\n strategy: RetryBackoffStrategies.EXPONENTIAL,\n initialDelayMs: baseDelayMs,\n jitter: RetryJitterModes.FULL,\n },\n execution: async ({ attempt }) => {\n lastAttempt = attempt;\n await invokeHandler({ event });\n },\n });\n } catch (error) {\n // The only trace this failure leaves: it is caught here and never reaches the publisher, so\n // the event name, traceId and attempt count all have to be on this one line.\n this.logger.error(\n '[dispatch] Handler exhausted retries | name: %s | traceId: %s | attempts: %d | handler: %s | Error: %s',\n event.name,\n event.traceId,\n lastAttempt,\n description,\n error,\n );\n }\n }\n}\n"]}
1
+ {"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../../../src/base/events/event-bus.ts"],"names":[],"mappings":"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","sourcesContent":["import { ObjectUtility } from '@venizia/ignis-helpers/common';\nimport type { Container } from '@/helpers/inversion/container';\nimport type { ValueOrPromise } from '@venizia/ignis-helpers/common';\nimport {\n BaseHelper,\n getError,\n RetryBackoffStrategies,\n RetryHelper,\n RetryJitterModes,\n} from '@venizia/ignis-helpers/core';\nimport { EventDispatchRetry, EventHandlerTypes } from './common/constants';\nimport type {\n IDomainEvent,\n IEventHandlerRetryOptions,\n TEventHandlerReference,\n} from './common/types';\n\n/** One `register`ed handler, resolved to concrete retry numbers and a ready-to-call invoker -\n * `EventDispatchRetry`'s defaults already applied and `handler`'s shape already resolved, so\n * `dispatch` never has to branch on either. */\ninterface IResolvedEventRegistration {\n // A method signature on purpose: its parameter is bivariant, so a registration holds the invoker of any payload type, which the registry cannot tell apart.\n invokeHandler(opts: { event: IDomainEvent<unknown> }): ValueOrPromise<void>;\n /** For the exhaustion log line only - a binding key or `<function fn.name>`. */\n description: string;\n maxAttempts: number;\n baseDelayMs: number;\n}\n\n/** In-process, fire-and-forget domain event bus. `TPayloadMap` keys the event names, so a wrong name\n * or payload shape is a compile error. Delivery is always async. Retry timing is a property of the\n * handler's own failure mode, not of the event, so `register` may tune it per registration. But\n * nobody awaits a fire-and-forget dispatch, so an unbounded window would let one event hold a\n * handler - and whatever it holds open, e.g. a database connection - for an unbounded time with no\n * one to report it. What the bus guarantees instead: a bounded MAXIMUM time a single dispatch can\n * occupy, enforced as a hard ceiling at `register()` - see `EventDispatchRetry`. Retry makes\n * delivery at-least-once: handlers must be idempotent, see `IEventHandler`. */\nexport class EventBus<TPayloadMap extends object> extends BaseHelper {\n private readonly container: Container;\n\n /** `register` appends, never replaces - two handlers may share an event name, and replacing would\n * drop the first with no way for the caller to notice. */\n private readonly registrationsByName: Map<string, IResolvedEventRegistration[]>;\n\n constructor(opts: { scope?: string; container: Container }) {\n super({ scope: opts.scope ?? EventBus.name });\n this.container = opts.container;\n this.registrationsByName = new Map();\n }\n\n /** The pre-jitter total of every inter-attempt delay `maxAttempts`/`baseDelayMs` would produce -\n * jitter (always on, see `dispatch`) only ever shrinks a delay, so this is a true upper bound. */\n private static computeTotalWindowMs(opts: { maxAttempts: number; baseDelayMs: number }): number {\n const { maxAttempts, baseDelayMs } = opts;\n let totalWindowMs = 0;\n\n for (let attempt = 1; attempt < maxAttempts; attempt++) {\n totalWindowMs += RetryHelper.computeBackoffDelayMs({\n attempt,\n backoff: {\n strategy: RetryBackoffStrategies.EXPONENTIAL,\n initialDelayMs: baseDelayMs,\n jitter: RetryJitterModes.NONE,\n },\n });\n }\n\n return totalWindowMs;\n }\n\n /** Loud rejection, never a silent clamp: a caller who believes a number the bus does not honour is\n * worse off than one who sees the ceiling at boot. */\n private static assertValidRetry(opts: {\n name: string;\n maxAttempts: number;\n baseDelayMs: number;\n }): void {\n const { name, maxAttempts, baseDelayMs } = opts;\n\n if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {\n throw getError({\n message: `[EventBus][register] retry.maxAttempts must be a positive integer | name: ${name} | Got: ${maxAttempts}`,\n });\n }\n\n if (!Number.isInteger(baseDelayMs) || baseDelayMs < 1) {\n throw getError({\n message: `[EventBus][register] retry.baseDelayMs must be a positive integer | name: ${name} | Got: ${baseDelayMs}`,\n });\n }\n\n if (maxAttempts > EventDispatchRetry.MAX_ATTEMPTS_CEILING) {\n throw getError({\n message: `[EventBus][register] retry.maxAttempts exceeds the ceiling | name: ${name} | Got: ${maxAttempts} | Ceiling: ${EventDispatchRetry.MAX_ATTEMPTS_CEILING} | Lower retry.maxAttempts`,\n });\n }\n\n const totalWindowMs = EventBus.computeTotalWindowMs({ maxAttempts, baseDelayMs });\n\n if (totalWindowMs > EventDispatchRetry.MAX_TOTAL_WINDOW_MS) {\n throw getError({\n message: `[EventBus][register] retry window exceeds the ceiling | name: ${name} | Got: ${totalWindowMs}ms | Ceiling: ${EventDispatchRetry.MAX_TOTAL_WINDOW_MS}ms | Lower retry.maxAttempts or retry.baseDelayMs`,\n });\n }\n }\n\n /**\n * Turns `handler` into a uniform invoker plus a description for the exhaustion log line.\n * `BINDING_KEY` resolves through the container INSIDE the returned closure, so every call re-reads\n * the current binding; `FUNCTION` calls `fn` directly, so the closure IS the resolution - there is\n * nothing left to re-read on a later attempt. The tag (`handler.type`) is what this switches on,\n * not which field happens to be present - see `EventHandlerTypes`' doc.\n */\n private static buildHandlerInvoker<TPayload>(opts: {\n container: Container;\n handler: TEventHandlerReference<TPayload>;\n name: string;\n }): {\n invokeHandler: (opts: { event: IDomainEvent<TPayload> }) => ValueOrPromise<void>;\n description: string;\n } {\n const { container, handler, name } = opts;\n\n if (ObjectUtility.isEmpty({ value: handler })) {\n throw getError({\n message: `[EventBus][register] Invalid handler | name: ${name} | Got: ${handler}`,\n });\n }\n\n switch (handler.type) {\n case EventHandlerTypes.BINDING_KEY: {\n const { key } = handler;\n\n if (ObjectUtility.isEmpty({ value: key })) {\n throw getError({\n message: `[EventBus][register] Invalid handler.key | name: ${name} | Got: ${key}`,\n });\n }\n\n return {\n invokeHandler: ({ event }) => container.get({ key }).handle({ event }),\n description: `binding-key:${key}`,\n };\n }\n\n case EventHandlerTypes.FUNCTION: {\n const { fn } = handler;\n\n if (typeof fn !== 'function') {\n throw getError({\n message: `[EventBus][register] Invalid handler.fn | name: ${name} | Expected a function | Got: ${typeof fn}`,\n });\n }\n\n return {\n invokeHandler: ({ event }) => fn({ event }),\n description: `function:${fn.name || 'anonymous'}`,\n };\n }\n\n default: {\n throw getError({\n message: `[EventBus][register] Unknown handler.type | name: ${name} | Expected one of: ${[...EventHandlerTypes.SCHEME_SET].join(', ')} | Got: ${(handler as { type?: unknown }).type}`,\n });\n }\n }\n }\n\n /**\n * `retry` is optional and per REGISTRATION, not per publish: the right window belongs to the\n * handler's own failure mode, and two handlers on the same event name may each pick their own.\n * Omitting it reproduces today's `EventDispatchRetry` defaults exactly. Both `maxAttempts` and the\n * total backoff window it implies are bounded - see `EventDispatchRetry` - and exceeding either\n * throws here, at boot where a human sees it, rather than being silently clamped at dispatch time.\n */\n register<K extends keyof TPayloadMap & string>(opts: {\n name: K;\n /** A `BINDING_KEY` reference re-resolves through the container on every retry attempt, so a\n * rebind reaches a dispatch already in flight. A `FUNCTION` reference is captured as-is: a\n * rebind has nothing to reach, and every attempt in a long retry window calls the exact `fn`\n * registered here. */\n handler: TEventHandlerReference<TPayloadMap[K]>;\n retry?: IEventHandlerRetryOptions;\n }): void {\n const { name, handler, retry } = opts;\n\n if (ObjectUtility.isEmpty({ value: name })) {\n throw getError({\n message: `[EventBus][register] Invalid registration | name: ${String(name)}`,\n });\n }\n\n const maxAttempts = retry?.maxAttempts ?? EventDispatchRetry.MAX_ATTEMPTS;\n const baseDelayMs = retry?.baseDelayMs ?? EventDispatchRetry.BASE_DELAY_MS;\n EventBus.assertValidRetry({ name, maxAttempts, baseDelayMs });\n\n const { invokeHandler, description } = EventBus.buildHandlerInvoker({\n container: this.container,\n handler,\n name,\n });\n\n const registration: IResolvedEventRegistration = {\n invokeHandler,\n description,\n maxAttempts,\n baseDelayMs,\n };\n\n const existing = this.registrationsByName.get(name);\n\n if (existing) {\n existing.push(registration);\n\n return;\n }\n\n this.registrationsByName.set(name, [registration]);\n }\n\n /**\n * Never blocks and never throws back to the caller: dispatch runs outside this call's flow via\n * `queueMicrotask`, and a handler failure is caught and logged where it happens (`dispatch`),\n * never here.\n */\n publish<K extends keyof TPayloadMap & string>(opts: {\n name: K;\n payload: TPayloadMap[K];\n traceId?: string;\n }): void {\n const { name, payload, traceId } = opts;\n\n const event: IDomainEvent<TPayloadMap[K]> = {\n name,\n payload,\n occurredAt: new Date().toISOString(),\n traceId,\n };\n\n const registrations = this.registrationsByName.get(name);\n\n if (!registrations?.length) {\n // A typo is already a compile error, so at runtime this only means nobody is listening yet -\n // a legitimate state on a fire-and-forget bus, not an incident.\n this.logger.debug('[publish] No handler registered | name: %s | traceId: %s', name, traceId);\n\n return;\n }\n\n for (const registration of registrations) {\n queueMicrotask(() => {\n // `dispatch` catches every failure path itself and never rejects - this `.catch` is an\n // unreachable backstop, kept (and logged) rather than left floating, for the day it isn't.\n this.dispatch({ event, registration }).catch((error: unknown) => {\n this.logger.error(\n '[publish] Unexpected dispatch failure | name: %s | Error: %s',\n event.name,\n error,\n );\n });\n });\n }\n }\n\n /**\n * Attempts/backoff come from the registration (`EventDispatchRetry`'s defaults when omitted),\n * always with full jitter - `RetryJitterModes.FULL` decorrelates a shared-resource pile-up hardest,\n * so many handlers retrying the same lock do not collide on the same instant a second and third\n * time. `invokeHandler` already encodes whether that re-resolves (`BINDING_KEY`) or was captured\n * once (`FUNCTION`) - see `buildHandlerInvoker` - so this method calls it uniformly. A handler that\n * throws synchronously is caught exactly like one that returns a rejected promise: `execution`\n * here is itself `async`, and JS converts a synchronous throw inside an async function body into a\n * rejection of that function's own promise - `RetryHelper.executeWithRetry`'s attempt loop never\n * sees the difference.\n *\n * `RetryHelper.executeWithRetry` is used without its own `logger` - its internal per-attempt/exhaustion\n * logging knows nothing about the event name or `traceId`, so it cannot be the trace anyone\n * relies on. The one line below, logged only on final failure, is.\n */\n private async dispatch(opts: {\n event: IDomainEvent<unknown>;\n registration: IResolvedEventRegistration;\n }): Promise<void> {\n const { event, registration } = opts;\n const { invokeHandler, description, maxAttempts, baseDelayMs } = registration;\n let lastAttempt = 0;\n\n try {\n await RetryHelper.executeWithRetry({\n operation: `EventBus.dispatch:${event.name}`,\n maxAttempts,\n backoff: {\n strategy: RetryBackoffStrategies.EXPONENTIAL,\n initialDelayMs: baseDelayMs,\n jitter: RetryJitterModes.FULL,\n },\n execution: async ({ attempt }) => {\n lastAttempt = attempt;\n await invokeHandler({ event });\n },\n });\n } catch (error) {\n // The only trace this failure leaves: it is caught here and never reaches the publisher, so\n // the event name, traceId and attempt count all have to be on this one line.\n this.logger.error(\n '[dispatch] Handler exhausted retries | name: %s | traceId: %s | attempts: %d | handler: %s | Error: %s',\n event.name,\n event.traceId,\n lastAttempt,\n description,\n error,\n );\n }\n }\n}\n"]}
@@ -1,3 +1,4 @@
1
+ import { type TBindingKey } from '../../helpers/inversion/index.js';
1
2
  /**
2
3
  * The one place a binding key is derived for an artifact class - shared by the decorators, the
3
4
  * registration path and any framework that registers artifacts itself, so no copy drifts.
@@ -15,7 +16,7 @@ export declare class ArtifactBindingKeys {
15
16
  key: string;
16
17
  };
17
18
  }): {
18
- key: string;
19
+ key: TBindingKey;
19
20
  isDerived: boolean;
20
21
  };
21
22
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"artifact-keys.js","sourceRoot":"","sources":["../../../../src/base/metadata/artifact-keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAEvD;;;GAGG;AACH,MAAM,OAAO,mBAAmB;IAC9B;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,IAId;QACC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;QAE5C,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAC/D,CAAC;QAED,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACtF,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,IAM5B;QACC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;QAC3C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QAErC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,mBAAmB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAE9D,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,SAAS;YACX,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9B,MAAM,UAAU,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC,SAAS,YAAY,KAAK,CAAC;YAElF,IAAI,KAAK,IAAI,KAAK,KAAK,KAAK,CAAC,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;gBACnD,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACtB,CAAC;YAED,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC;QAED,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC;IACzB,CAAC;IAED,mGAAmG;IACnG,MAAM,CAAC,wBAAwB,CAAC,IAO/B;QACC,MAAM,CAAC,GAAG,CAAC,GAAG,mBAAmB,CAAC,qBAAqB,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAEnF,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,CAAC;YACb,OAAO,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;SAC7E,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,iBAAiB,CAAC,IAAqC;QAC5D,OAAO,IAAI,IAAI,CAAC,MAAM,yCAAyC,IAAI,CAAC,GAAG,kTAAkT,CAAC;IAC5X,CAAC;CACF","sourcesContent":["import { BindingKeys } from '@/helpers/inversion';\nimport { getError } from '@venizia/ignis-helpers/core';\n\n/**\n * The one place a binding key is derived for an artifact class - shared by the decorators, the\n * registration path and any framework that registers artifacts itself, so no copy drifts.\n */\nexport class ArtifactBindingKeys {\n /**\n * The key a class registers under: the `binding` it pins, or `<namespace>.<ClassName>`. Only the\n * second is `isDerived` - it follows the class name, which a minified build renames.\n */\n static resolve(opts: {\n target: Function;\n namespace: string;\n binding?: { namespace: string; key: string };\n }): { key: string; isDerived: boolean } {\n const { target, namespace, binding } = opts;\n\n if (binding) {\n return { key: BindingKeys.build(binding), isDerived: false };\n }\n\n return { key: BindingKeys.build({ namespace, key: target.name }), isDerived: true };\n }\n\n /**\n * The keys two DIFFERENT classes derive alike in one registration. A minified build gives classes\n * in different chunks the same short name; a module evaluated twice (hot reload) does too. A pinned\n * `binding` is a deliberate choice and is never counted, nor is a subclass registered after its\n * parent under the parent's name - the override pattern, where the subclass is meant to win.\n */\n static findDerivedCollisions(opts: {\n entries: Array<{\n target: Function;\n namespace: string;\n binding?: { namespace: string; key: string };\n }>;\n }): Array<string> {\n const owners = new Map<string, Function>();\n const collisions = new Set<string>();\n\n for (const entry of opts.entries) {\n const { key, isDerived } = ArtifactBindingKeys.resolve(entry);\n\n if (!isDerived) {\n continue;\n }\n\n const owner = owners.get(key);\n const isOverride = owner !== undefined && entry.target.prototype instanceof owner;\n\n if (owner && owner !== entry.target && !isOverride) {\n collisions.add(key);\n }\n\n owners.set(key, entry.target);\n }\n\n return [...collisions];\n }\n\n /** Throws on the first derived collision - the second binding would silently replace the first. */\n static assertNoDerivedCollision(opts: {\n entries: Array<{\n target: Function;\n namespace: string;\n binding?: { namespace: string; key: string };\n }>;\n caller: string;\n }): void {\n const [key] = ArtifactBindingKeys.findDerivedCollisions({ entries: opts.entries });\n\n if (key === undefined) {\n return;\n }\n\n throw getError({\n message: ArtifactBindingKeys.describeCollision({ key, caller: opts.caller }),\n });\n }\n\n static describeCollision(opts: { key: string; caller: string }): string {\n return `[${opts.caller}] Two classes derive the binding key '${opts.key}' from their class name, and the second would silently replace the first | A minified build renames classes - pin 'binding: { namespace, key }' or build with names kept (keepNames). A module evaluated twice by hot reload does the same - set 'bootChecks.allowDerivedKeyCollision' in that development setup`;\n }\n}\n"]}
1
+ {"version":3,"file":"artifact-keys.js","sourceRoot":"","sources":["../../../../src/base/metadata/artifact-keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAoB,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAEvD;;;GAGG;AACH,MAAM,OAAO,mBAAmB;IAC9B;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,IAId;QACC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;QAE5C,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,KAAK,CAAU,OAAO,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QACxE,CAAC;QAED,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,KAAK,CAAU,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC/F,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,IAM5B;QACC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;QAC3C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QAErC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,mBAAmB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAE9D,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,SAAS;YACX,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9B,MAAM,UAAU,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC,SAAS,YAAY,KAAK,CAAC;YAElF,IAAI,KAAK,IAAI,KAAK,KAAK,KAAK,CAAC,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;gBACnD,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACtB,CAAC;YAED,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC;QAED,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC;IACzB,CAAC;IAED,mGAAmG;IACnG,MAAM,CAAC,wBAAwB,CAAC,IAO/B;QACC,MAAM,CAAC,GAAG,CAAC,GAAG,mBAAmB,CAAC,qBAAqB,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAEnF,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,CAAC;YACb,OAAO,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;SAC7E,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,iBAAiB,CAAC,IAAqC;QAC5D,OAAO,IAAI,IAAI,CAAC,MAAM,yCAAyC,IAAI,CAAC,GAAG,kTAAkT,CAAC;IAC5X,CAAC;CACF","sourcesContent":["import { BindingKeys, type TBindingKey } from '@/helpers/inversion';\nimport { getError } from '@venizia/ignis-helpers/core';\n\n/**\n * The one place a binding key is derived for an artifact class - shared by the decorators, the\n * registration path and any framework that registers artifacts itself, so no copy drifts.\n */\nexport class ArtifactBindingKeys {\n /**\n * The key a class registers under: the `binding` it pins, or `<namespace>.<ClassName>`. Only the\n * second is `isDerived` - it follows the class name, which a minified build renames.\n */\n static resolve(opts: {\n target: Function;\n namespace: string;\n binding?: { namespace: string; key: string };\n }): { key: TBindingKey; isDerived: boolean } {\n const { target, namespace, binding } = opts;\n\n if (binding) {\n return { key: BindingKeys.build<unknown>(binding), isDerived: false };\n }\n\n return { key: BindingKeys.build<unknown>({ namespace, key: target.name }), isDerived: true };\n }\n\n /**\n * The keys two DIFFERENT classes derive alike in one registration. A minified build gives classes\n * in different chunks the same short name; a module evaluated twice (hot reload) does too. A pinned\n * `binding` is a deliberate choice and is never counted, nor is a subclass registered after its\n * parent under the parent's name - the override pattern, where the subclass is meant to win.\n */\n static findDerivedCollisions(opts: {\n entries: Array<{\n target: Function;\n namespace: string;\n binding?: { namespace: string; key: string };\n }>;\n }): Array<string> {\n const owners = new Map<string, Function>();\n const collisions = new Set<string>();\n\n for (const entry of opts.entries) {\n const { key, isDerived } = ArtifactBindingKeys.resolve(entry);\n\n if (!isDerived) {\n continue;\n }\n\n const owner = owners.get(key);\n const isOverride = owner !== undefined && entry.target.prototype instanceof owner;\n\n if (owner && owner !== entry.target && !isOverride) {\n collisions.add(key);\n }\n\n owners.set(key, entry.target);\n }\n\n return [...collisions];\n }\n\n /** Throws on the first derived collision - the second binding would silently replace the first. */\n static assertNoDerivedCollision(opts: {\n entries: Array<{\n target: Function;\n namespace: string;\n binding?: { namespace: string; key: string };\n }>;\n caller: string;\n }): void {\n const [key] = ArtifactBindingKeys.findDerivedCollisions({ entries: opts.entries });\n\n if (key === undefined) {\n return;\n }\n\n throw getError({\n message: ArtifactBindingKeys.describeCollision({ key, caller: opts.caller }),\n });\n }\n\n static describeCollision(opts: { key: string; caller: string }): string {\n return `[${opts.caller}] Two classes derive the binding key '${opts.key}' from their class name, and the second would silently replace the first | A minified build renames classes - pin 'binding: { namespace, key }' or build with names kept (keepNames). A module evaluated twice by hot reload does the same - set 'bootChecks.allowDerivedKeyCollision' in that development setup`;\n }\n}\n"]}
@@ -1,4 +1,5 @@
1
1
  import type { IArtifactMetadata, IArtifactRegistrationOptions, TBindingScope } from '../../helpers/inversion/index.js';
2
+ import { type TBindingKey } from '../../helpers/inversion/index.js';
2
3
  /** The root stereotype: marks a class as an artifact the application registers, with its registration defaults. Every other stereotype calls it. */
3
4
  export declare const injectable: <ApplicationType = unknown>(opts: IArtifactMetadata<ApplicationType>) => ClassDecorator;
4
5
  /**
@@ -52,7 +53,7 @@ export declare const component: <ApplicationType = unknown>(opts?: IArtifactRegi
52
53
  export declare const configuration: <ApplicationType = unknown>(opts?: IArtifactRegistrationOptions<ApplicationType>) => ClassDecorator;
53
54
  /** Marks a component method as the provider of `key`. `registerArtifacts` binds the key to a lazy provider that resolves the component and calls the method; SINGLETON unless `scope` says otherwise. */
54
55
  export declare const provide: (opts: {
55
- key: string;
56
+ key: TBindingKey;
56
57
  scope?: TBindingScope;
57
58
  }) => MethodDecorator;
58
59
  /** Helpers of the stereotype decorators; the decorators themselves stay functions. */