@tech4good/angular-schematics 20.3.1 → 21.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 (144) hide show
  1. package/.agents/skills/publish-npm/SKILL.md +1 -1
  2. package/.agents/skills/publish-npm/eval.yaml +15 -0
  3. package/.agents/skills/publish-npm/fixtures/package-v21.json.template +8 -0
  4. package/.t4g/agent-memory.db +0 -0
  5. package/CHANGELOG.md +62 -0
  6. package/contributing-docs/commit-message.md +3 -6
  7. package/package.json +5 -5
  8. package/src/collection.json +8 -0
  9. package/src/component/files/__name@dasherize__/__name@dasherize__.component.ts.template +1 -3
  10. package/src/component/index_spec.js +57 -4
  11. package/src/component/index_spec.js.map +1 -1
  12. package/src/entity/index.js +7 -1
  13. package/src/entity/index.js.map +1 -1
  14. package/src/entity/index_spec.js +108 -4
  15. package/src/entity/index_spec.js.map +1 -1
  16. package/src/guard/files/__name@dasherize__.guard.spec.ts.template +45 -0
  17. package/src/guard/files/__name@dasherize__.guard.ts.template +32 -0
  18. package/src/guard/index.d.ts +2 -0
  19. package/src/guard/index.js +38 -0
  20. package/src/guard/index.js.map +1 -0
  21. package/src/guard/index_spec.d.ts +1 -0
  22. package/src/guard/index_spec.js +64 -0
  23. package/src/guard/index_spec.js.map +1 -0
  24. package/src/guard/schema.json +46 -0
  25. package/src/ng-add/files/.firebaserc.template +3 -2
  26. package/src/ng-add/files/.github/workflows/angular-github-ci.yml.template +105 -39
  27. package/src/ng-add/files/.gitignore.template +1 -2
  28. package/src/ng-add/files/angular.json.template +1 -5
  29. package/src/ng-add/files/docs-infra/infrastructure-guide.md.template +390 -0
  30. package/src/ng-add/files/docs-infra/load-system-architecture.md.template +166 -0
  31. package/src/ng-add/files/docs-infra/querying-strategy.md.template +157 -0
  32. package/src/ng-add/files/docs-infra/stream-system-architecture.md.template +283 -0
  33. package/src/ng-add/files/eslint.config.js.template +4 -1
  34. package/src/ng-add/files/firebase.json.template +37 -0
  35. package/src/ng-add/files/firestore.rules.spec.ts.template +221 -0
  36. package/src/ng-add/files/firestore.rules.template +67 -0
  37. package/src/ng-add/files/jest.config.ts.template +6 -1
  38. package/src/ng-add/files/package.json.template +41 -31
  39. package/src/ng-add/files/setup-jest.ts.template +13 -5
  40. package/src/ng-add/files/src/app/admin/admin-panel/admin-panel.component.spec.ts.template +76 -12
  41. package/src/ng-add/files/src/app/admin/admin-panel/admin-panel.component.ts.template +1 -3
  42. package/src/ng-add/files/src/app/admin/admin-panel/admin-settings/admin-settings.component.spec.ts.template +90 -0
  43. package/src/ng-add/files/src/app/admin/admin-panel/admin-settings/admin-settings.component.ts.template +1 -1
  44. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-counts/admin-count-pill/admin-count-pill.component.spec.ts.template +12 -17
  45. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-counts/admin-count-pill/admin-count-pill.component.ts.template +2 -4
  46. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-counts/admin-user-counts.component.spec.ts.template +40 -19
  47. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-counts/admin-user-counts.component.ts.template +3 -5
  48. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-list.component.html.template +2 -2
  49. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-list.component.spec.ts.template +108 -0
  50. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-list.component.ts.template +11 -11
  51. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-table/admin-user-table.component.html.template +6 -2
  52. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-table/admin-user-table.component.spec.ts.template +136 -19
  53. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-table/admin-user-table.component.ts.template +8 -5
  54. package/src/ng-add/files/src/app/app.component.html.template +1 -1
  55. package/src/ng-add/files/src/app/app.component.scss.template +10 -0
  56. package/src/ng-add/files/src/app/app.component.ts.template +1 -1
  57. package/src/ng-add/files/src/app/app.config.ts.template +11 -11
  58. package/src/ng-add/files/src/app/auth-routing.spec.ts.template +101 -0
  59. package/src/ng-add/files/src/app/core/analytics/log.service.ts.template +5 -8
  60. package/src/ng-add/files/src/app/core/analytics/time-analytics.service.spec.ts.template +140 -0
  61. package/src/ng-add/files/src/app/core/analytics/time-analytics.service.ts.template +25 -7
  62. package/src/ng-add/files/src/app/core/auth/guards/redirect-if-authenticated.guard.ts.template +1 -1
  63. package/src/ng-add/files/src/app/core/auth/guards/require-admin.guard.ts.template +1 -1
  64. package/src/ng-add/files/src/app/core/auth/guards/require-auth-and-consent.guard.ts.template +1 -1
  65. package/src/ng-add/files/src/app/core/auth/guards/require-auth.guard.ts.template +1 -1
  66. package/src/ng-add/files/src/app/core/firebase/cached-listeners.service.ts.template +229 -14
  67. package/src/ng-add/files/src/app/core/firebase/database.service.ts.template +1 -1
  68. package/src/ng-add/files/src/app/core/firebase/firebase.mock.service.ts.template +34 -9
  69. package/src/ng-add/files/src/app/core/firebase/firebase.service.ts.template +4 -4
  70. package/src/ng-add/files/src/app/core/firebase/query-logger.ts.template +11 -0
  71. package/src/ng-add/files/src/app/core/firebase/simulate-load.spec.ts.template +104 -0
  72. package/src/ng-add/files/src/app/core/firebase/simulate-stream.spec.ts.template +127 -0
  73. package/src/ng-add/files/src/app/core/firebase/simulation.mock.ts.template +38 -0
  74. package/src/ng-add/files/src/app/core/firebase/stream-multiplexer.ts.template +443 -0
  75. package/src/ng-add/files/src/app/core/store/app.store.spec.ts.template +920 -0
  76. package/src/ng-add/files/src/app/core/store/app.store.ts.template +303 -137
  77. package/src/ng-add/files/src/app/core/store/auth/auth.mock.ts.template +65 -23
  78. package/src/ng-add/files/src/app/core/store/auth/auth.store.ts.template +68 -67
  79. package/src/ng-add/files/src/app/core/store/user/user.mock.ts.template +46 -0
  80. package/src/ng-add/files/src/app/core/store/user-context/user-context.mock.ts.template +17 -0
  81. package/src/ng-add/files/src/app/core/testing/test-utils.ts.template +26 -0
  82. package/src/ng-add/files/src/app/first-time/consent/consent.component.html.template +3 -3
  83. package/src/ng-add/files/src/app/first-time/consent/consent.component.spec.ts.template +89 -13
  84. package/src/ng-add/files/src/app/first-time/consent/consent.component.ts.template +46 -17
  85. package/src/ng-add/files/src/app/first-time/consent/consent.guard.ts.template +1 -1
  86. package/src/ng-add/files/src/app/first-time/early-access/early-access.component.html.template +5 -63
  87. package/src/ng-add/files/src/app/first-time/early-access/early-access.component.scss.template +1 -94
  88. package/src/ng-add/files/src/app/first-time/early-access/early-access.component.spec.ts.template +150 -14
  89. package/src/ng-add/files/src/app/first-time/early-access/early-access.component.ts.template +15 -42
  90. package/src/ng-add/files/src/app/first-time/early-access/early-access.guard.ts.template +2 -2
  91. package/src/ng-add/files/src/app/first-time/early-access/early-access.model.ts.template +5 -0
  92. package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.html.template +42 -0
  93. package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.scss.template +96 -0
  94. package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.spec.ts.template +37 -0
  95. package/src/ng-add/files/src/app/first-time/early-access/survey-form/survey-form.component.ts.template +63 -0
  96. package/src/ng-add/files/src/app/first-time/early-access/waitlist-view/waitlist-view.component.html.template +16 -0
  97. package/src/ng-add/files/src/app/first-time/early-access/waitlist-view/waitlist-view.component.scss.template +7 -0
  98. package/src/ng-add/files/src/app/first-time/early-access/waitlist-view/waitlist-view.component.spec.ts.template +41 -0
  99. package/src/ng-add/files/src/app/first-time/early-access/waitlist-view/waitlist-view.component.ts.template +26 -0
  100. package/src/ng-add/files/src/app/first-time/first-time-routing.spec.ts.template +123 -0
  101. package/src/ng-add/files/src/app/first-time/landing/hero/hero.component.html.template +11 -4
  102. package/src/ng-add/files/src/app/first-time/landing/hero/hero.component.scss.template +17 -4
  103. package/src/ng-add/files/src/app/first-time/landing/hero/hero.component.ts.template +5 -5
  104. package/src/ng-add/files/src/app/first-time/landing/landing.component.html.template +1 -1
  105. package/src/ng-add/files/src/app/first-time/landing/landing.component.scss.template +0 -1
  106. package/src/ng-add/files/src/app/first-time/landing/landing.component.spec.ts.template +25 -17
  107. package/src/ng-add/files/src/app/first-time/landing/landing.component.ts.template +4 -12
  108. package/src/ng-add/files/src/app/first-time/landing/rotating-quotes/rotating-quotes.component.ts.template +1 -1
  109. package/src/ng-add/files/src/app/first-time/login/login.component.spec.ts.template +36 -16
  110. package/src/ng-add/files/src/app/first-time/login/login.component.ts.template +1 -1
  111. package/src/ng-add/files/src/app/first-time/onboarding/onboarding.component.spec.ts.template +11 -15
  112. package/src/ng-add/files/src/app/first-time/onboarding/onboarding.component.ts.template +1 -3
  113. package/src/ng-add/files/src/app/main/home/home.component.ts.template +1 -3
  114. package/src/ng-add/files/src/app/shared/dev-status-bar/dev-status-bar.component.spec.ts.template +98 -0
  115. package/src/ng-add/files/src/app/shared/dev-status-bar/dev-status-bar.component.ts.template +9 -3
  116. package/src/ng-add/files/src/app/shared/hint-visibility/hint-visibility.directive.spec.ts.template +164 -0
  117. package/src/ng-add/files/src/app/shared/hint-visibility/hint-visibility.directive.ts.template +20 -18
  118. package/src/ng-add/files/src/app/shared/navbar/navbar.component.spec.ts.template +38 -17
  119. package/src/ng-add/files/src/app/shared/navbar/navbar.component.ts.template +1 -1
  120. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.html.template +1 -1
  121. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.spec.ts.template +49 -10
  122. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.component.ts.template +5 -5
  123. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.service.spec.ts.template +86 -0
  124. package/src/ng-add/files/src/app/shared/redeployment-warning/redeployment-warning.service.ts.template +11 -9
  125. package/src/ng-add/files/src/environments/environment.prod.ts.template +1 -0
  126. package/src/ng-add/files/src/environments/environment.test.ts.template +1 -0
  127. package/src/ng-add/files/src/environments/environment.ts.template +2 -8
  128. package/src/ng-add/files/src/styles.scss.template +29 -1
  129. package/src/ng-add/files/tsconfig.app.json.template +6 -6
  130. package/src/ng-add/files/tsconfig.json.template +13 -8
  131. package/src/ng-add/files/tsconfig.spec.json.template +6 -5
  132. package/src/ng-add/index.js +19 -1
  133. package/src/ng-add/index.js.map +1 -1
  134. package/src/component/files/__name@dasherize__/__name@dasherize__.animations.ts.template +0 -4
  135. package/src/ng-add/files/src/app/admin/admin-panel/admin-panel.animations.ts.template +0 -4
  136. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-counts/admin-count-pill/admin-count-pill.animations.ts.template +0 -4
  137. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-counts/admin-user-counts.animations.ts.template +0 -4
  138. package/src/ng-add/files/src/app/admin/admin-panel/admin-user-list/admin-user-table/admin-user-table.animations.ts.template +0 -4
  139. package/src/ng-add/files/src/app/first-time/consent/consent.animations.ts.template +0 -4
  140. package/src/ng-add/files/src/app/first-time/early-access/early-access.animations.ts.template +0 -10
  141. package/src/ng-add/files/src/app/first-time/landing/hero/hero.animations.ts.template +0 -15
  142. package/src/ng-add/files/src/app/first-time/landing/landing.animations.ts.template +0 -4
  143. package/src/ng-add/files/src/app/first-time/onboarding/onboarding.animations.ts.template +0 -4
  144. package/src/ng-add/files/src/app/main/home/home.animations.ts.template +0 -4
@@ -0,0 +1,127 @@
1
+ import { TestBed } from '@angular/core/testing';
2
+ import { DestroyRef, EnvironmentInjector } from '@angular/core';
3
+ import { Subject } from 'rxjs';
4
+ import { StreamMultiplexer } from './stream-multiplexer';
5
+ import { DatabaseService, DATABASE_SERVICE } from './database.service';
6
+ import { signalStore, withState } from '@ngrx/signals';
7
+ import { withEntitiesAndSelectMethods, withEntitiesAndDBMethods } from '../store/app.store';
8
+
9
+ import { provideFirebaseMock } from './firebase.mock.service';
10
+ import { MOCK_SIMULATION_USERS, MOCK_SIMULATION_USER_CONTEXTS } from './simulation.mock';
11
+ import * as queryLogger from './query-logger';
12
+
13
+ // Define realistic Stores
14
+ export const UserStore = signalStore(
15
+ { providedIn: 'root' },
16
+ withState({}),
17
+ withEntitiesAndDBMethods<any>('users'),
18
+ );
19
+
20
+ export const UserContextStore = signalStore(
21
+ { providedIn: 'root' },
22
+ withState({}),
23
+ withEntitiesAndDBMethods<any>('userContexts'),
24
+ );
25
+
26
+ describe('Simulation with Actual Store Syntax', () => {
27
+ it('runs the full stream multiplexer simulation and logs the output', async () => {
28
+ TestBed.configureTestingModule({
29
+ providers: [
30
+ ...provideFirebaseMock({
31
+ users: MOCK_SIMULATION_USERS,
32
+ userContexts: MOCK_SIMULATION_USER_CONTEXTS,
33
+ }),
34
+ UserStore,
35
+ UserContextStore,
36
+ ],
37
+ });
38
+
39
+ const userStore = TestBed.inject(UserStore) as any;
40
+ const userContextStore = TestBed.inject(UserContextStore) as any;
41
+ const injector = TestBed.inject(EnvironmentInjector);
42
+
43
+ const logSpy = jest.spyOn(queryLogger, 'queryLog').mockImplementation(() => {});
44
+ console.log('=== STARTING REALISTIC STORE SIMULATION ===\n');
45
+
46
+ // Create mock injectors and destroy refs for separate components
47
+ const componentA = { onDestroyFns: [] as any[] };
48
+ const mockInjectorA = { get: (token: any, notFound?: any, flags?: any) => token === DestroyRef ? { onDestroy: (cb: any) => componentA.onDestroyFns.push(cb) } : injector.get(token, notFound, flags) };
49
+
50
+ const componentB = { onDestroyFns: [] as any[] };
51
+ const mockInjectorB = { get: (token: any, notFound?: any, flags?: any) => token === DestroyRef ? { onDestroy: (cb: any) => componentB.onDestroyFns.push(cb) } : injector.get(token, notFound, flags) };
52
+
53
+ const componentC = { onDestroyFns: [] as any[] };
54
+ const mockInjectorC = { get: (token: any, notFound?: any, flags?: any) => token === DestroyRef ? { onDestroy: (cb: any) => componentC.onDestroyFns.push(cb) } : injector.get(token, notFound, flags) };
55
+
56
+ // 1. Initial load, component A asks for 5 IDs using the actual stream API
57
+ userStore.stream([['__id', 'in', ['id1', 'id2', 'id3', 'id4', 'id5']]], {}, mockInjectorA);
58
+ await new Promise((r) => setTimeout(r, 50));
59
+
60
+ // 2. Component B asks for 3 completely different IDs
61
+ userStore.stream([['__id', 'in', ['id6', 'id7', 'id8']]], {}, mockInjectorB);
62
+ await new Promise((r) => setTimeout(r, 50));
63
+
64
+ // 3. Component C asks for 3 IDs (2 overlap with A, 1 new) and has a NESTED stream query
65
+ // Streaming the user's UserContext
66
+ userStore.stream(
67
+ [['__id', 'in', ['id1', 'id2', 'id9']]],
68
+ {},
69
+ mockInjectorC,
70
+ (user: any) => {
71
+ const contextId = `${user.__id}_context`;
72
+ return [{
73
+ collection: 'userContexts',
74
+ store: userContextStore,
75
+ queryParams: [['__id', '==', contextId]],
76
+ queryOptions: {},
77
+ }];
78
+ },
79
+ );
80
+ await new Promise((r) => setTimeout(r, 50));
81
+
82
+ // 4. Component A destroys (orphans 3 IDs: id3, id4, id5. id1, id2 stay active for C)
83
+ console.log('\n---> Action: Component A destroys (tears down stream for id1, id2, id3, id4, id5)');
84
+ componentA.onDestroyFns.forEach((fn) => fn());
85
+ await new Promise((r) => setTimeout(r, 5100));
86
+
87
+ // 5. Fire off a bunch of singleton queries to hit the bloat threshold (trigger repacking)
88
+ const singletons = ['id10', 'id11', 'id12', 'id13', 'id14', 'id15', 'id16', 'id17'];
89
+ for (const id of singletons) {
90
+ userStore.stream([['__id', 'in', [id]]], {}, mockInjectorC);
91
+ }
92
+ await new Promise((r) => setTimeout(r, 50));
93
+
94
+ // 6. Request a MASSIVE array that has to be chunked (e.g. 35 IDs)
95
+ const hugeArray = Array.from({ length: 35 }, (_, i) => `huge_${i}`);
96
+ userStore.stream([['__id', 'in', hugeArray]], {}, mockInjectorB);
97
+ await new Promise((r) => setTimeout(r, 50));
98
+
99
+ // 8. Test quick recreation (Component E requests id100, dies, Component F requests id100 immediately)
100
+ const componentE = { onDestroyFns: [] as any[] };
101
+ const mockInjectorE = { get: (token: any, notFound?: any, flags?: any) => token === DestroyRef ? { onDestroy: (cb: any) => componentE.onDestroyFns.push(cb) } : injector.get(token, notFound, flags) };
102
+
103
+ console.log('\n---> Action: Component E mounts, requests id100');
104
+ userStore.stream([['__id', 'in', ['id100']]], {}, mockInjectorE);
105
+ await new Promise((r) => setTimeout(r, 50));
106
+
107
+ console.log('\n---> Action: Component E destroys itself');
108
+ componentE.onDestroyFns.forEach((fn) => fn());
109
+ await new Promise((r) => setTimeout(r, 1000)); // wait 1s (less than 5s)
110
+
111
+ const componentF = { onDestroyFns: [] as any[] };
112
+ const mockInjectorF = { get: (token: any, notFound?: any, flags?: any) => token === DestroyRef ? { onDestroy: (cb: any) => componentF.onDestroyFns.push(cb) } : injector.get(token, notFound, flags) };
113
+
114
+ console.log('\n---> Action: Component F mounts and requests id100 BEFORE the 5s timeout finishes');
115
+ userStore.stream([['__id', 'in', ['id100']]], {}, mockInjectorF);
116
+
117
+ await new Promise((r) => setTimeout(r, 4500)); // Wait out the rest of Component E's 5s timeout
118
+
119
+ // Verify key behaviors through logs
120
+ expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('[StreamMultiplexer] Opening 1 new websocket stream(s) for chunks:'));
121
+ expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('[StreamMultiplexer] Tearing down 9 old websocket stream(s).'));
122
+ expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('[StreamMultiplexer] Smart Repack Triggered!'));
123
+ expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('[StreamMultiplexer] Component destroyed 5 seconds ago! Releasing its holds on IDs: [id100]'));
124
+
125
+ console.log('\n=== FULL STREAMING SIMULATION COMPLETE ===');
126
+ }, 15000);
127
+ });
@@ -0,0 +1,38 @@
1
+ export const MOCK_SIMULATION_USERS = [];
2
+ export const MOCK_SIMULATION_USER_CONTEXTS = [];
3
+
4
+ // Seed 1-20
5
+ for (let i = 1; i <= 20; i++) {
6
+ MOCK_SIMULATION_USERS.push({
7
+ __id: `id${i}`,
8
+ name: `User id${i}`,
9
+ });
10
+ MOCK_SIMULATION_USER_CONTEXTS.push({
11
+ __id: `id${i}_context`,
12
+ userId: `id${i}`,
13
+ data: `Context for user id${i}`,
14
+ });
15
+ }
16
+
17
+ // Seed huge_0 to huge_50
18
+ for (let i = 0; i <= 50; i++) {
19
+ MOCK_SIMULATION_USERS.push({
20
+ __id: `huge_${i}`,
21
+ name: `User huge_${i}`,
22
+ });
23
+ MOCK_SIMULATION_USER_CONTEXTS.push({
24
+ __id: `huge_${i}_context`,
25
+ userId: `huge_${i}`,
26
+ data: `Context for user huge_${i}`,
27
+ });
28
+ }
29
+
30
+ MOCK_SIMULATION_USERS.push({
31
+ __id: `id99`,
32
+ name: `User id99`,
33
+ });
34
+
35
+ MOCK_SIMULATION_USERS.push({
36
+ __id: `id100`,
37
+ name: `User id100`,
38
+ });
@@ -0,0 +1,443 @@
1
+ import { DestroyRef } from '@angular/core';
2
+ import { DatabaseService } from './database.service';
3
+ import { entityInQueryResults } from '../store/app.store';
4
+ import { queryLog } from './query-logger';
5
+ import { QueryParams, AnyEntity } from '../store/app.model';
6
+
7
+ /**
8
+ * StreamMultiplexer optimizes Firestore realtime subscriptions by multiplexing multiple
9
+ * independent component requests into a minimal number of batched 'in' queries.
10
+ *
11
+ * It manages two pools of websockets:
12
+ * 1. `batchedListeners`: fully packed 'in' queries (chunks of 30 IDs).
13
+ * 2. `singleListeners`: sparse 'in' queries handling newly requested IDs.
14
+ *
15
+ * It balances stream connection limits with UI rendering performance by maintaining
16
+ * sparse streams until a threshold is reached, at which point it automatically triggers
17
+ * an `executeSmartRepack` to consolidate streams and free up websocket connections.
18
+ *
19
+ * It tracks component lifecycles using `DestroyRef` to gracefully tear down streams
20
+ * when components are destroyed and their requested IDs become "orphaned".
21
+ */
22
+ export class StreamMultiplexer<T extends AnyEntity = AnyEntity> {
23
+ // Maps a unique query value ID (e.g., a specific user ID) to the set of component DestroyRefs that requested it.
24
+ private destroyRefsById = new Map<string, Set<DestroyRef>>();
25
+
26
+ // Maps a component's DestroyRef to the set of IDs it requested. This allows us to safely clean up all of a component's
27
+ // requested IDs when it is destroyed, even if it called registerIds multiple times.
28
+ private idsByDestroyRef = new Map<DestroyRef, Set<string>>();
29
+
30
+ // Tracks optimized batches of up to 30 IDs
31
+ private batchedListeners: Array<{ ids: string[], unsubscribe: (() => void) | null }> = [];
32
+
33
+ // Tracks newly added small groups of IDs that haven't been repacked yet
34
+ private singleListeners: Array<{ ids: string[], unsubscribe: (() => void) | null }> = [];
35
+
36
+ // Threshold for determining when a batch is "sparse" enough to warrant evaluating a repack operation.
37
+ private readonly MAX_ORPHANED_IDS_PER_BATCH = 10;
38
+
39
+ // Threshold for determining when we have accumulated enough single listeners to warrant repacking them into a batch.
40
+ private readonly MAX_SINGLE_LISTENERS_BEFORE_REPACK = 10;
41
+
42
+ constructor(
43
+ private collection: string,
44
+ private field: string,
45
+ private db: DatabaseService,
46
+ private store: { handleStreamChanges(entitiesToAdd: T[], entitiesToModify: T[], entitiesToRemove: string[]): void }, // NgRx Signal Store with handleStreamChanges
47
+ ) {}
48
+
49
+ /**
50
+ * Checks if an ID is currently being actively streamed by any component.
51
+ */
52
+ isIdActive(id: string): boolean {
53
+ return this.destroyRefsById.has(id) && this.destroyRefsById.get(id)!.size > 0;
54
+ }
55
+
56
+ /**
57
+ * Registers a list of IDs to be streamed from Firestore.
58
+ * Duplicate requests for the same ID are deduplicated.
59
+ * Automatically handles teardown when the provided destroyRef fires.
60
+ */
61
+ registerIds(ids: string[], destroyRef: DestroyRef) {
62
+ queryLog(`[StreamMultiplexer] registerIds called with: [${Array.from(ids).join(', ')}]`);
63
+ const newIds: string[] = [];
64
+
65
+ // We maintain a reverse lookup from DestroyRef -> IDs to easily clean up when the component is destroyed.
66
+ let idsForDestroyRef = this.idsByDestroyRef.get(destroyRef);
67
+ const isFirstRegistrationForRef = !idsForDestroyRef;
68
+
69
+ // Initialize the set if this is the very first time this DestroyRef is calling registerIds()
70
+ if (!idsForDestroyRef) {
71
+ idsForDestroyRef = new Set();
72
+ this.idsByDestroyRef.set(destroyRef, idsForDestroyRef);
73
+ }
74
+
75
+ ids.forEach((id) => {
76
+ // Add the requested ID to the component's tracking set so it can be safely cleaned up later
77
+ idsForDestroyRef.add(id);
78
+
79
+ // Look up if this exact ID is already being actively streamed by anyone else in the application
80
+ let registeredSet = this.destroyRefsById.get(id);
81
+ if (!registeredSet) {
82
+ // First time this ID has been requested anywhere!
83
+ // We create a new Set to track all the specific DestroyRefs that have requested it.
84
+ registeredSet = new Set();
85
+ this.destroyRefsById.set(id, registeredSet);
86
+
87
+ // Track this as a new ID that needs to be streamed
88
+ newIds.push(id);
89
+ }
90
+ registeredSet.add(destroyRef);
91
+ });
92
+
93
+ // Handle teardown when the component is destroyed
94
+ if (isFirstRegistrationForRef) {
95
+ destroyRef.onDestroy(() => {
96
+ setTimeout(() => {
97
+ let triggeredRemove = false;
98
+
99
+ // Retrieve the dynamically accumulated set of IDs that were requested by this specific component's DestroyRef.
100
+ // By pulling from this Map instead of a closed-over lexical variable, we ensure we clean up ALL IDs
101
+ // requested across multiple calls to registerIds() by the same component.
102
+ const idsToClean = this.idsByDestroyRef.get(destroyRef);
103
+ if (idsToClean) {
104
+ queryLog(`[StreamMultiplexer] Component destroyed 5 seconds ago! Releasing its holds on IDs: [${Array.from(idsToClean).join(', ')}]`);
105
+ idsToClean.forEach((id) => {
106
+ const registeredSet = this.destroyRefsById.get(id);
107
+ if (registeredSet && registeredSet.has(destroyRef)) {
108
+ // Remove this component's claim to the ID
109
+ registeredSet.delete(destroyRef);
110
+
111
+ // If no other components are currently listening to this ID,
112
+ // completely remove it from the globally active set.
113
+ if (registeredSet.size === 0) {
114
+ this.destroyRefsById.delete(id);
115
+ triggeredRemove = true;
116
+ }
117
+ }
118
+ });
119
+
120
+ // Cleanup the tracking Map itself to prevent memory leaks
121
+ this.idsByDestroyRef.delete(destroyRef);
122
+ }
123
+
124
+ if (triggeredRemove) {
125
+ this.cleanupEmptyListeners();
126
+ if (this.hasBatchWithTooManyOrphans()) {
127
+ this.executeSmartRepack();
128
+ }
129
+ }
130
+ }, 5000); // 5-second graceful shutdown period
131
+ });
132
+ }
133
+
134
+ this.checkAndExecuteRepack(newIds);
135
+ }
136
+
137
+ /**
138
+ * Evaluates whether the multiplexer should execute a repack operation.
139
+ * A repack is executed if either:
140
+ * 1. A new ID request pushes the projected single listener count over the MAX_SINGLE_LISTENERS_BEFORE_REPACK threshold.
141
+ * 2. An orphaned batch cleanup check triggered this evaluation.
142
+ *
143
+ * If new IDs are requested but the threshold is not met, this method simply spins up
144
+ * a single sparse stream for those IDs to prioritize immediate UI rendering speed.
145
+ *
146
+ * @param newIds - Array of newly requested IDs that are not yet streamed.
147
+ */
148
+ private checkAndExecuteRepack(newIds: string[]) {
149
+ if (newIds.length > 0) {
150
+ const numNewBatches = Math.ceil(newIds.length / 30);
151
+ const projectedSingleListeners = this.singleListeners.length + numNewBatches;
152
+
153
+ // If adding these new IDs would push us over the threshold, just execute a repack directly.
154
+ // The repack logic will automatically pick up all unstreamed IDs.
155
+ if (projectedSingleListeners >= this.MAX_SINGLE_LISTENERS_BEFORE_REPACK) {
156
+ this.executeSmartRepack(newIds);
157
+ } else {
158
+ // Otherwise, spin up a new listener for the newly requested IDs
159
+ const newChunks = this.chunkArray(newIds, 30);
160
+ const newBatches = this.startNewBatches(newChunks, []);
161
+
162
+ // We separate full batches from sparse single listeners
163
+ newBatches.forEach((b) => {
164
+ if (b.ids.length === 30) {
165
+ this.batchedListeners.push(b);
166
+ } else {
167
+ this.singleListeners.push(b);
168
+ }
169
+ });
170
+ }
171
+ }
172
+ }
173
+
174
+ /**
175
+ * Completely tears down all active streams and resets the multiplexer state.
176
+ * Useful when the user logs out or the entire parent collection listener is destroyed.
177
+ */
178
+ teardownAll() {
179
+ this.batchedListeners.forEach((b) => {
180
+ if (b.unsubscribe) b.unsubscribe();
181
+ });
182
+ this.batchedListeners = [];
183
+
184
+ this.singleListeners.forEach((s) => {
185
+ if (s.unsubscribe) s.unsubscribe();
186
+ });
187
+ this.singleListeners = [];
188
+
189
+ this.destroyRefsById.clear();
190
+ this.idsByDestroyRef.clear();
191
+ }
192
+
193
+ /**
194
+ * Identifies any listeners (both single and batched) where EVERY SINGLE ID has 0 active holds.
195
+ * If an entire stream is completely abandoned, it is immediately unsubscribed and purged to prevent
196
+ * dead sockets from hanging around indefinitely.
197
+ */
198
+ private cleanupEmptyListeners() {
199
+ const activeIds = new Set(this.destroyRefsById.keys());
200
+
201
+ const emptyBatches = this.batchedListeners.filter((b) => b.ids.every((id) => !activeIds.has(id)));
202
+ if (emptyBatches.length > 0) {
203
+ queryLog(`[StreamMultiplexer] Purging ${emptyBatches.length} completely empty batched stream(s).`);
204
+ emptyBatches.forEach((b) => {
205
+ if (b.unsubscribe) {
206
+ b.unsubscribe();
207
+ b.unsubscribe = null;
208
+ }
209
+ });
210
+ this.batchedListeners = this.batchedListeners.filter((b) => !emptyBatches.includes(b));
211
+ }
212
+
213
+ const emptySingles = this.singleListeners.filter((s) => s.ids.every((id) => !activeIds.has(id)));
214
+ if (emptySingles.length > 0) {
215
+ queryLog(`[StreamMultiplexer] Purging ${emptySingles.length} completely empty single stream(s).`);
216
+ emptySingles.forEach((s) => {
217
+ if (s.unsubscribe) {
218
+ s.unsubscribe();
219
+ s.unsubscribe = null;
220
+ }
221
+ });
222
+ this.singleListeners = this.singleListeners.filter((s) => !emptySingles.includes(s));
223
+ }
224
+ }
225
+
226
+ /**
227
+ * Checks if any of the currently active websocket listeners has too many "orphaned" IDs
228
+ * (IDs that are being streamed from Firestore but are no longer requested by any component).
229
+ */
230
+ private hasBatchWithTooManyOrphans(): boolean {
231
+ return this.batchedListeners.some((batch) => {
232
+ const orphans = batch.ids.filter((id) => {
233
+ const refs = this.destroyRefsById.get(id);
234
+ return !refs || refs.size === 0;
235
+ }).length;
236
+ return orphans >= this.MAX_ORPHANED_IDS_PER_BATCH;
237
+ });
238
+ }
239
+
240
+ /**
241
+ * Consolidates sparse streams and tears down bloated batches.
242
+ *
243
+ * It uses a greedy mathematical algorithm to evaluate "candidate batches" (those with <= 25 active IDs)
244
+ * and determine if tearing them down and bundling their active IDs with the single listeners will
245
+ * result in a net reduction in the total number of websocket streams.
246
+ *
247
+ * Note: This method does not check threshold conditions before executing. Callers
248
+ * (e.g. checkAndExecuteRepack) must verify that a repack is strictly necessary
249
+ * before invoking this method.
250
+ *
251
+ * @param newIds - Array of newly requested IDs that need to be streamed.
252
+ */
253
+ private executeSmartRepack(newIds: string[] = []) {
254
+ queryLog(`[StreamMultiplexer] Smart Repack Triggered!`);
255
+
256
+ const activeIds = new Set(this.destroyRefsById.keys());
257
+
258
+ // 1. Gather all single listeners and new IDs into one pool
259
+ const singleIds: string[] = [];
260
+ this.singleListeners.forEach((s) => singleIds.push(...s.ids.filter((id) => activeIds.has(id))));
261
+ singleIds.push(...newIds);
262
+
263
+ const S = singleIds.length;
264
+
265
+ // 2. Identify sparse batches (<= 25 active IDs) as candidates for mathematical reduction
266
+ const candidateBatches = this.batchedListeners
267
+ .map((batch) => ({
268
+ batch,
269
+ activeCount: batch.ids.filter((id) => activeIds.has(id)).length,
270
+ }))
271
+ .filter((b) => b.activeCount <= 25);
272
+
273
+ // 3. Sort candidates ascending so we combine the sparsest batches first
274
+ candidateBatches.sort((a, b) => a.activeCount - b.activeCount);
275
+
276
+ // Baseline reduction: bundling all single listeners into tight chunks
277
+ let bestReduction = S > 0 ? S - Math.ceil(S / 30) : 0;
278
+ let bestT: Array<{ ids: string[], unsubscribe: (() => void) | null }> = [];
279
+
280
+ let currentA = 0;
281
+ const currentT: Array<{ ids: string[], unsubscribe: (() => void) | null }> = [];
282
+
283
+ // 4. Greedily evaluate absorbing sparse batches to maximize stream reduction
284
+ for (let i = 0; i < candidateBatches.length; i++) {
285
+ currentT.push(candidateBatches[i].batch);
286
+ currentA += candidateBatches[i].activeCount;
287
+
288
+ const newBatchesCount = Math.ceil((S + currentA) / 30);
289
+ const reduction = S + currentT.length - newBatchesCount;
290
+
291
+ if (reduction > bestReduction) {
292
+ bestReduction = reduction;
293
+ bestT = [...currentT];
294
+ }
295
+ }
296
+
297
+ // 5. Ensure we also forcibly tear down any bloated batches (>= 10 orphans)
298
+ // even if they didn't mathematically reduce the total stream count.
299
+ const bloatedBatches = this.batchedListeners.filter((batch) => {
300
+ const orphans = batch.ids.filter((id) => !activeIds.has(id)).length;
301
+ return orphans >= this.MAX_ORPHANED_IDS_PER_BATCH;
302
+ });
303
+
304
+ bloatedBatches.forEach((b) => {
305
+ if (!bestT.includes(b)) {
306
+ bestT.push(b);
307
+ }
308
+ });
309
+
310
+ const batchesToTeardown = bestT;
311
+ const singleListenersToTeardown = [...this.singleListeners];
312
+
313
+ // 6. Collect all the actively requested IDs from the streams we are about to tear down
314
+ const idsToChunk: string[] = [...singleIds];
315
+ batchesToTeardown.forEach((b) => {
316
+ idsToChunk.push(...b.ids.filter((id) => activeIds.has(id)));
317
+ });
318
+
319
+ // 7. If there's nothing left to stream, just clean up state and return
320
+ if (idsToChunk.length === 0) {
321
+ this.finalizeRepackState(batchesToTeardown, singleListenersToTeardown, []);
322
+ return;
323
+ }
324
+
325
+ // 8. Break the collected IDs into optimal chunks of 30 for Firestore 'in' queries
326
+ const newChunks = this.chunkArray(idsToChunk, 30);
327
+
328
+ // 9. Spin up the new websocket streams, passing the old ones to be torn down only AFTER the new ones emit data
329
+ const newBatches = this.startNewBatches(newChunks, [...batchesToTeardown, ...singleListenersToTeardown]);
330
+
331
+ // 10. Update our internal tracking arrays to reflect the new state
332
+ this.finalizeRepackState(batchesToTeardown, singleListenersToTeardown, newBatches);
333
+ }
334
+
335
+ /**
336
+ * Opens new Firestore snapshot streams for the given chunks of IDs.
337
+ *
338
+ * @param newChunks - The fully chunked arrays of IDs to stream (max 30 per chunk).
339
+ * @param oldBatchesToTeardown - The old websocket listeners that these new chunks are replacing.
340
+ * They are only torn down *after* the new stream emits its first
341
+ * payload, preventing UI flickering.
342
+ */
343
+ private startNewBatches(newChunks: string[][], oldBatchesToTeardown: Array<{ ids: string[], unsubscribe: (() => void) | null }>) {
344
+ if (newChunks.length > 0) {
345
+ queryLog(`[StreamMultiplexer] Opening ${newChunks.length} new websocket stream(s) for chunks:`);
346
+ newChunks.forEach((c) => queryLog(` - [${c.join(', ')}]`));
347
+ }
348
+ const newBatches: Array<{ ids: string[], unsubscribe: (() => void) | null }> = [];
349
+
350
+ newChunks.forEach((chunk) => {
351
+ let isFirstEmission = true;
352
+ const queryParams: QueryParams = chunk.length === 1 ?
353
+ [[this.field, '==', chunk[0]]] :
354
+ [[this.field, 'in', chunk]];
355
+ const unsubscribeBatch = this.db.streamEntitiesChanges<T>(this.collection, queryParams, {}).subscribe((changes) => {
356
+ this.patchToStore(changes, queryParams);
357
+ if (isFirstEmission) {
358
+ isFirstEmission = false;
359
+ // Trigger teardown of old sockets that this new socket replaces
360
+ this.teardownOldListeners(oldBatchesToTeardown);
361
+ }
362
+ });
363
+ newBatches.push({ ids: chunk, unsubscribe: () => unsubscribeBatch.unsubscribe() });
364
+ });
365
+ return newBatches;
366
+ }
367
+
368
+ /**
369
+ * Unsubscribes from the old listener sockets to clean up the network connections.
370
+ */
371
+ private teardownOldListeners(oldBatches: Array<{ ids: string[], unsubscribe: (() => void) | null }>) {
372
+ if (oldBatches.length > 0) {
373
+ queryLog(`[StreamMultiplexer] Tearing down ${oldBatches.length} old websocket stream(s).`);
374
+ oldBatches.forEach((b) => {
375
+ queryLog(` - [${b.ids.join(', ')}]`);
376
+ if (b.unsubscribe) {
377
+ b.unsubscribe();
378
+ b.unsubscribe = null;
379
+ }
380
+ });
381
+ }
382
+ }
383
+
384
+ /**
385
+ * Cleans up the multiplexer state arrays by removing the objects for the torn down streams
386
+ * and pushing the newly created streams into the correct `batchedListeners` or `singleListeners` array.
387
+ */
388
+ private finalizeRepackState(
389
+ oldBatchesToTeardown: Array<{ ids: string[], unsubscribe: (() => void) | null }>,
390
+ oldSingleListenersToTeardown: Array<{ ids: string[], unsubscribe: (() => void) | null }>,
391
+ newBatches: Array<{ ids: string[], unsubscribe: (() => void) | null }>,
392
+ ) {
393
+ this.batchedListeners = this.batchedListeners.filter((b) => !oldBatchesToTeardown.includes(b));
394
+ this.singleListeners = this.singleListeners.filter((s) => !oldSingleListenersToTeardown.includes(s));
395
+
396
+ newBatches.forEach((b) => {
397
+ if (b.ids.length === 30) {
398
+ this.batchedListeners.push(b);
399
+ } else {
400
+ this.singleListeners.push(b);
401
+ }
402
+ });
403
+ }
404
+
405
+ /**
406
+ * Utility to split an array of IDs into smaller chunks (max 30 for Firestore 'in' queries).
407
+ */
408
+ private chunkArray(array: string[], size: number): string[][] {
409
+ return Array.from({ length: Math.ceil(array.length / size) }, (v, i) => array.slice(i * size, i * size + size));
410
+ }
411
+
412
+ /**
413
+ * Takes the raw DocumentChange payload from Firestore and formats it into
414
+ * added/modified/removed arrays that the NgRx Signal Store can easily process.
415
+ */
416
+ private patchToStore(fbPayload: Array<{ type: string, docData: T }>, queryParams: QueryParams) {
417
+ const entitiesToAdd = fbPayload
418
+ .filter((dc) => dc.type === 'added' && !dc.docData['_deleted'])
419
+ .map((dc) => dc.docData);
420
+
421
+ const entitiesToModify = fbPayload
422
+ .filter((dc) => dc.type === 'modified' && !dc.docData['_deleted'])
423
+ .map((dc) => dc.docData);
424
+
425
+ const entitiesToRemove = fbPayload
426
+ .filter((dc) => dc.type === 'modified' && dc.docData['_deleted'])
427
+ .map((dc) => dc.docData['__id']);
428
+
429
+ const entitiesToModify2 = fbPayload
430
+ .filter((dc) => dc.type === 'removed' && !entityInQueryResults(dc.docData, queryParams, {}))
431
+ .map((dc) => dc.docData);
432
+
433
+ const entitiesToRemove2 = fbPayload
434
+ .filter((dc) => dc.type === 'removed' && entityInQueryResults(dc.docData, queryParams, {}))
435
+ .map((dc) => dc.docData['__id']);
436
+
437
+ this.store.handleStreamChanges(
438
+ entitiesToAdd,
439
+ [...entitiesToModify, ...entitiesToModify2],
440
+ [...entitiesToRemove, ...entitiesToRemove2],
441
+ );
442
+ }
443
+ }