@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
@@ -1,12 +1,14 @@
1
1
  import { Inject, Injectable, WritableSignal, inject, DestroyRef, computed } from '@angular/core';
2
2
  import { toObservable } from '@angular/core/rxjs-interop';
3
3
  import { Subject, Observable, merge, forkJoin, of, from, pipe } from 'rxjs';
4
- import { startWith, pairwise, publishLast, publish, publishReplay, refCount, tap, pluck, mergeMap, filter, takeUntil, skipUntil, buffer, skip, switchMap, map, take } from 'rxjs/operators';
4
+ import { startWith, pairwise, share, tap, pluck, mergeMap, filter, takeUntil, skipUntil, buffer, skip, switchMap, map, take } from 'rxjs/operators';
5
5
  import { setEntities, setEntity, removeEntities, SelectEntityId } from '@ngrx/signals/entities';
6
6
  import { EntityLoadQuery, EntityStreamQuery, entityInQueryResults } from '../store/app.store';
7
7
  import { QueryParams, QueryOptions, AnyEntity } from '../store/app.model';
8
8
  import { DocumentChange } from '@angular/fire/firestore';
9
9
  import { DATABASE_SERVICE, DatabaseService } from './database.service';
10
+ import { StreamMultiplexer } from './stream-multiplexer';
11
+ import { queryLog } from './query-logger';
10
12
 
11
13
  const selectId: SelectEntityId<AnyEntity> = (entity) => entity.__id;
12
14
 
@@ -15,6 +17,26 @@ export interface CachedConnection {
15
17
  registeredSet: Set<DestroyRef>;
16
18
  }
17
19
 
20
+
21
+ /**
22
+ * CachedListenersService manages database connections and their lifecycles to
23
+ * ensure optimal performance, prevent memory leaks, and solve the N+1 query problem.
24
+ *
25
+ * Responsibilities:
26
+ * 1. **Listener Pooling**: Deduplicates active Firestore snapshot listeners. If multiple
27
+ * components request a stream for the exact same query, only one actual database
28
+ * connection is opened.
29
+ * 2. **Reference Counting & Lifecycle Management**: Tracks which components are using
30
+ * which stream via their Angular `DestroyRef`. When a component is destroyed, its
31
+ * reference is removed.
32
+ * 3. **Graceful Teardown**: Implements a 5-second grace period before fully closing a
33
+ * database connection after its last reference drops. This prevents UI flicker and
34
+ * unnecessary DB reads if the user navigates away and immediately back.
35
+ * 4. **Load Time Tracking (One-shot Loads)**: Tracks `lastLoadTime` for general queries
36
+ * and precise `entityLoadTime` for optimized batch equality queries. This enables
37
+ * incremental (delta-only) fetching, drastically reducing bandwidth by only fetching
38
+ * entities modified since the last load.
39
+ */
18
40
  @Injectable({
19
41
  providedIn: 'root',
20
42
  })
@@ -22,12 +44,27 @@ export class CachedListenersService {
22
44
  /** Cached connections by loadKey. */
23
45
  private connectionByQueryKey: Record<string, CachedConnection> = {};
24
46
 
47
+ /** Active multiplexers by collection.field */
48
+ private streamMultiplexers = new Map<string, StreamMultiplexer>();
49
+
25
50
  /** Close connection events. */
26
51
  private closeConnection$: Subject<string> = new Subject<string>();
27
52
 
53
+
28
54
  /** Load state across the app by queryKey. Stores last load time in milliseconds. */
29
55
  private lastLoadTime: Record<string, number> = {};
30
56
 
57
+ /** Per-entity load times for optimized equality queries. Key: "collection.field:value" */
58
+ private entityLoadTime: Record<string, number> = {};
59
+
60
+ getEntityLoadTime(collection: string, field: string, value: string): number {
61
+ return this.entityLoadTime[`${collection}.${field}:${value}`] || -1;
62
+ }
63
+
64
+ setEntityLoadTime(collection: string, field: string, value: string, time: number): void {
65
+ this.entityLoadTime[`${collection}.${field}:${value}`] = time;
66
+ }
67
+
31
68
  /** Define a unique key for each connection. */
32
69
  private getQueryKey(collection: string, queryParams: QueryParams, queryOptions: QueryOptions): string {
33
70
  let queryOptionsString = '';
@@ -54,12 +91,43 @@ export class CachedListenersService {
54
91
  return `${collection}.${queryParams.sort()}.${queryOptionsString}`;
55
92
  }
56
93
 
94
+ /**
95
+ * Clear cached connection states and last load times.
96
+ * NOTE: This is strictly intended for resetting state between test cases
97
+ * in unit/integration tests and should not be used in dev/production environments
98
+ * to avoid unexpected stream disconnections.
99
+ */
100
+ clearCache(): void {
101
+ for (const key of Object.keys(this.connectionByQueryKey)) {
102
+ const connection = this.connectionByQueryKey[key];
103
+ if (connection) {
104
+ this.closeConnection$.next(key);
105
+ connection.registeredSet.clear();
106
+ }
107
+ }
108
+ this.connectionByQueryKey = {};
109
+
110
+ for (const multiplexer of this.streamMultiplexers.values()) {
111
+ multiplexer.teardownAll();
112
+ }
113
+ this.streamMultiplexers.clear();
114
+ this.lastLoadTime = {};
115
+ this.entityLoadTime = {};
116
+ }
117
+
57
118
  /** Return whether a stream exists for this query. */
58
119
  isStreamForQuery(collection: string, queryParams: QueryParams, queryOptions: QueryOptions): boolean {
59
120
  const queryKey = this.getQueryKey(collection, queryParams, queryOptions);
60
121
  return !!this.connectionByQueryKey[queryKey];
61
122
  }
62
123
 
124
+ /** Return whether a specific ID is currently being streamed by a multiplexer. */
125
+ isIdStreamed(collection: string, field: string, id: string): boolean {
126
+ const multiplexerKey = `${collection}.${field}`;
127
+ const multiplexer = this.streamMultiplexers.get(multiplexerKey);
128
+ return multiplexer ? multiplexer.isIdActive(id) : false;
129
+ }
130
+
63
131
  /** Get the last load time for a particular query. */
64
132
  getLastLoadTime(collection: string, queryParams: QueryParams, queryOptions: QueryOptions): number {
65
133
  // If there are queryOptions, we don't support saving load times
@@ -98,6 +166,7 @@ export class CachedListenersService {
98
166
  loading?: WritableSignal<boolean>,
99
167
  },
100
168
  ): Promise<CachedConnection> {
169
+ queryLog(`[CachedListenersService] processStreamQuery called for collection: '${collection}', query:`, JSON.stringify(queryParams));
101
170
  // console.log("PROCESS QUERY: " + this.getQueryKey(collection, queryParams, queryOptions));
102
171
 
103
172
  // Get destroyRef for the component that called processStreamQuery
@@ -128,10 +197,22 @@ export class CachedListenersService {
128
197
  // Add a 5-second delay so we don't have to reconnect multiple times
129
198
  // if the next view happens to use the same stream
130
199
  setTimeout(() => {
200
+ // If the destroyRef is not in the set, it means this connection was already
201
+ // cleared/cleaned up (e.g., via clearCache() in tests), so we bail out.
202
+ if (!connection.registeredSet.has(destroyRef)) {
203
+ return;
204
+ }
205
+
131
206
  connection.registeredSet.delete(destroyRef);
132
207
  if (connection.registeredSet.size === 0) {
133
- this.closeConnection$.next(connection.queryKey);
134
- this.connectionByQueryKey[connection.queryKey] = undefined;
208
+ // Verify that this connection is still the active connection in the cache map.
209
+ // This is essential to prevent stale callbacks (e.g. from a previous test case
210
+ // that was cleared via clearCache()) from overwriting a new active connection
211
+ // in the cache or triggering premature disconnections.
212
+ if (this.connectionByQueryKey[connection.queryKey] === connection) {
213
+ this.closeConnection$.next(connection.queryKey);
214
+ this.connectionByQueryKey[connection.queryKey] = undefined;
215
+ }
135
216
  }
136
217
  }, 5000);
137
218
  });
@@ -166,19 +247,19 @@ export class CachedListenersService {
166
247
  const changedEntities = [];
167
248
  for (const key in currEntities) {
168
249
  if (!(key in prevEntities)) {
169
- // the entity was added
250
+ // the entity was added
170
251
  changedEntities.push({
171
252
  type: 'added',
172
253
  doc: currEntities[key],
173
254
  });
174
255
  } else if (currEntities[key]['_deleted']) {
175
- // the entity was removed
256
+ // the entity was removed
176
257
  changedEntities.push({
177
258
  type: 'removed',
178
259
  doc: currEntities[key],
179
260
  });
180
261
  } else if (currEntities[key]['_updatedAt'] !== prevEntities[key]['_updatedAt']) {
181
- // the entity was modified
262
+ // the entity was modified
182
263
  changedEntities.push({
183
264
  type: 'modified',
184
265
  doc: currEntities[key],
@@ -206,9 +287,21 @@ export class CachedListenersService {
206
287
 
207
288
  // Process queries concurrently using Promise.all
208
289
  await Promise.all(optimizedQueries.filter((q) => !!q).map(async (query) => {
209
- await this.processStreamQuery(query.collection, query.store, query.queryParams, query.queryOptions, injector, query.streamQueries, {
210
- loading: options?.loading,
211
- });
290
+ const isSimpleChild = (!query.queryOptions || Object.keys(query.queryOptions).length === 0) &&
291
+ query.queryParams.length === 1 &&
292
+ (query.queryParams[0][1] === '==' || query.queryParams[0][1] === 'in');
293
+
294
+ if (isSimpleChild) {
295
+ const childField = query.queryParams[0][0];
296
+ const childOp = query.queryParams[0][1];
297
+ const childVal = query.queryParams[0][2];
298
+ const childIds = childOp === 'in' ? childVal : [childVal];
299
+ queryLog(`[CachedListenersService] Nested query optimized to simple stream query: ${childField} in [${childIds}]`);
300
+ await this.processSimpleStreamQuery(query.collection, childField, childIds, query.store, injector, query.streamQueries, { loading: options?.loading });
301
+ } else {
302
+ queryLog(`[CachedListenersService] Nested query falling back to standard stream query:`, JSON.stringify(query.queryParams));
303
+ await this.processStreamQuery(query.collection, query.store, query.queryParams, query.queryOptions, injector, query.streamQueries, { loading: options?.loading });
304
+ }
212
305
  }));
213
306
  }));
214
307
  });
@@ -222,7 +315,116 @@ export class CachedListenersService {
222
315
  return connection;
223
316
  }
224
317
 
225
- private createConnection<T>(collection: string, store, queryParams: QueryParams, queryOptions: QueryOptions, destroyRef: DestroyRef): CachedConnection {
318
+ /**
319
+ * Optimized fast-path for simple streaming queries (e.g., `id in [1, 2, 3]`).
320
+ * Instead of managing distinct complex RxJS subscription chains for every component, this delegates
321
+ * ID registration to a centralized `StreamMultiplexer` (per collection/field).
322
+ *
323
+ * It also handles nested `streamQueries` (e.g. streaming a post's author) by listening to changes
324
+ * to the parent entities, diffing them (`pairwise`), and setting up streams for the new children.
325
+ */
326
+ public async processSimpleStreamQuery<T extends AnyEntity>(
327
+ collection: string,
328
+ field: string,
329
+ ids: string[],
330
+ store: any,
331
+ injector: any,
332
+ streamQueries?: (entity: T) => EntityStreamQuery<AnyEntity>[],
333
+ options?: { loading?: WritableSignal<boolean> },
334
+ ): Promise<void> {
335
+ queryLog(`[CachedListenersService] processSimpleStreamQuery called for collection: '${collection}', field: '${field}', ids: [${ids}]`);
336
+
337
+ if (!ids || ids.length === 0) {
338
+ options?.loading?.set(false);
339
+ return;
340
+ }
341
+
342
+ const destroyRef = injector.get(DestroyRef);
343
+ const multiplexerKey = `${collection}.${field}`;
344
+
345
+ let multiplexer = this.streamMultiplexers.get(multiplexerKey);
346
+ if (!multiplexer) {
347
+ multiplexer = new StreamMultiplexer(collection, field, this.db, store);
348
+ this.streamMultiplexers.set(multiplexerKey, multiplexer);
349
+ }
350
+ multiplexer.registerIds(ids, destroyRef);
351
+
352
+ if (streamQueries) {
353
+ // 1. We select the entities from the store.
354
+ // Because `app.store.ts` caches identical array references, `filteredSignal` will NOT trigger
355
+ // spurious emissions if the underlying data has not actually changed.
356
+ const filteredSignal = computed(() => {
357
+ return store.selectEntities([[field, 'in', ids]], {});
358
+ });
359
+
360
+ // 2. We convert the signal to an observable to perform pairwise diffing.
361
+ // This is necessary because if a parent entity is added or modified, we need to re-evaluate
362
+ // its nested `streamQueries` (e.g., if a post's authorId changes, we must query the new author).
363
+ toObservable(filteredSignal, { injector }).pipe(
364
+ map((entities) => {
365
+ const entityMap = {};
366
+ for (const entity of entities) {
367
+ entityMap[entity.__id] = entity;
368
+ }
369
+ return entityMap;
370
+ }),
371
+ startWith({}),
372
+ pairwise(),
373
+ map(([prevEntities, currEntities]) => {
374
+ // 3. Diff the current entities against the previous entities to determine exactly
375
+ // what was added, removed, or modified. We rely on the `_deleted` flag and `_updatedAt`.
376
+ const changedEntities = [];
377
+ for (const key in currEntities) {
378
+ if (!(key in prevEntities)) {
379
+ changedEntities.push({ type: 'added', doc: currEntities[key] });
380
+ } else if (currEntities[key]['_deleted']) {
381
+ changedEntities.push({ type: 'removed', doc: currEntities[key] });
382
+ } else if (currEntities[key]['_updatedAt'] !== prevEntities[key]['_updatedAt']) {
383
+ changedEntities.push({ type: 'modified', doc: currEntities[key] });
384
+ }
385
+ }
386
+ return changedEntities;
387
+ }),
388
+ map((changes) => changes.filter((c) => c.type !== 'removed')),
389
+ filter((changes) => changes.length > 0),
390
+ ).subscribe(async (changes) => {
391
+ // 4. For every changed entity, evaluate its nested stream queries.
392
+ const queriesByEntity = changes.map((change) => streamQueries(change.doc));
393
+ if (queriesByEntity.length === 0 || queriesByEntity[0].length === 0) return;
394
+
395
+ // 5. Transpose the matrix so each row corresponds to all queries of the same query type.
396
+ // This allows us to group and optimize queries (e.g., combining 5 single equality queries into 1 'in' query).
397
+ const queriesByQueryType = queriesByEntity[0].map((_, colIndex) => queriesByEntity.map((row) => row[colIndex]));
398
+
399
+ await Promise.all(queriesByQueryType.map(async (queriesForOneType) => {
400
+ const optimizedQueries = EntityStreamQuery.optimize(queriesForOneType);
401
+ await Promise.all(optimizedQueries.filter((q) => !!q).map(async (query) => {
402
+ const isSimpleChild = (!query.queryOptions || Object.keys(query.queryOptions).length === 0) &&
403
+ query.queryParams.length === 1 &&
404
+ (query.queryParams[0][1] === '==' || query.queryParams[0][1] === 'in');
405
+
406
+ if (isSimpleChild) {
407
+ const childField = query.queryParams[0][0];
408
+ const childOp = query.queryParams[0][1];
409
+ const childVal = query.queryParams[0][2];
410
+ const childIds = childOp === 'in' ? childVal : [childVal];
411
+ queryLog(`[CachedListenersService] Nested query optimized to simple stream query: ${childField} in [${childIds}]`);
412
+ await this.processSimpleStreamQuery(query.collection, childField, childIds, query.store, injector, query.streamQueries, { loading: options?.loading });
413
+ } else {
414
+ queryLog(`[CachedListenersService] Nested query falling back to standard stream query:`, JSON.stringify(query.queryParams));
415
+ await this.processStreamQuery(query.collection, query.store, query.queryParams, query.queryOptions, injector, query.streamQueries, { loading: options?.loading });
416
+ }
417
+ }));
418
+ }));
419
+ });
420
+ }
421
+
422
+ // We'll turn off the loading indicator right away since we don't have a good way
423
+ // to know when all individual streams are initialized yet.
424
+ options?.loading?.set(false);
425
+ }
426
+
427
+ private createConnection<T>(collection: string, store: any, queryParams: QueryParams, queryOptions: QueryOptions, destroyRef: DestroyRef): CachedConnection {
226
428
  // console.log("CONNECT " + this.getQueryKey(collection, queryParams, queryOptions));
227
429
 
228
430
  // ------------ DEFINE OBSERVABLES FOR DISCONNECTING ------------------------------
@@ -232,8 +434,7 @@ export class CachedListenersService {
232
434
  filter((qk) => qk === queryKey),
233
435
  take(1),
234
436
  // tap(a => { console.log("DISCONNECT: " + queryKey) }),
235
- publish(),
236
- refCount(),
437
+ share(),
237
438
  );
238
439
 
239
440
  // ------------ HANDLE PATCHING TO STORE ------------------------------------------
@@ -257,11 +458,25 @@ export class CachedListenersService {
257
458
  .filter((dc) => dc.type === 'modified' && dc.docData['_deleted'])
258
459
  .map((dc) => dc.docData['__id']);
259
460
 
461
+ // Handle changes of the 'removed' type. In general, firebase 'removed'
462
+ // could be due to no longer matching the stream query rather than being
463
+ // deleted from the DB. this is why we use soft deletes (set _deleted to true).
464
+ // We could still get 'removed' entries if there are manual deletions in the
465
+ // database or when firestore is syncing updates after temporarily using
466
+ // entities cached to IndexedDB.
467
+ const entitiesToModify2 = fbPayload
468
+ .filter((dc) => dc.type === 'removed' && !entityInQueryResults(dc.docData, queryParams, queryOptions))
469
+ .map((dc) => dc.docData);
470
+
471
+ const entitiesToRemove2 = fbPayload
472
+ .filter((dc) => dc.type === 'removed' && entityInQueryResults(dc.docData, queryParams, queryOptions))
473
+ .map((dc) => dc.docData['__id']);
474
+
260
475
  // Patch all the changes to the store
261
476
  store.handleStreamChanges(
262
477
  entitiesToAdd,
263
- entitiesToModify,
264
- entitiesToRemove,
478
+ [...entitiesToModify, ...entitiesToModify2],
479
+ [...entitiesToRemove, ...entitiesToRemove2],
265
480
  );
266
481
  });
267
482
 
@@ -6,7 +6,7 @@ import { WriteBatchI } from '../store/batch-write.service';
6
6
 
7
7
  export interface DatabaseService {
8
8
  createId(): string;
9
- afUser(): Observable<{ uid: string, email: string, displayName: string, photoURL: string }>;
9
+ afUser(): Observable<{ uid: string, email: string, displayName: string, photoURL: string } | null>;
10
10
  login(providerId: string, scope?: string): any;
11
11
  loginLink(error): void;
12
12
  logout(): any;
@@ -1,11 +1,11 @@
1
- import { Injectable, inject, Injector, computed } from '@angular/core';
1
+ import { Injectable, inject, Injector, computed, Provider } from '@angular/core';
2
2
  import { toObservable } from '@angular/core/rxjs-interop';
3
3
  import { Observable, combineLatest, merge, of, from, pipe, BehaviorSubject } from 'rxjs';
4
4
  import { tap, pluck, mergeMap, pairwise, delay, startWith, filter, takeUntil, skip, switchMap, map, take } from 'rxjs/operators';
5
5
  import { environment } from '../../../environments/environment';
6
6
  import { DocumentSnapshot, serverTimestamp, Timestamp, getDoc, getDocs, doc, setDoc, updateDoc, deleteDoc, docData, collection, collectionData, collectionChanges, query, where, orderBy, OrderByDirection, limit, startAt, startAfter, endAt, endBefore, DocumentChange, increment, AggregateQuerySnapshot, AggregateField, AggregateSpec, getAggregateFromServer, getCountFromServer } from '@angular/fire/firestore';
7
7
  import { AnyEntity, QueryParams, QueryOptions } from '../store/app.model';
8
- import { DatabaseService } from './database.service';
8
+ import { DatabaseService, DATABASE_SERVICE } from './database.service';
9
9
  import { SelectEntityId } from '@ngrx/signals/entities';
10
10
  import { AuthMockDB } from '../store/auth/auth.mock';
11
11
 
@@ -24,7 +24,7 @@ export class FirebaseMockService implements DatabaseService {
24
24
  'users': inject(UserMockDB),
25
25
  'userContexts': inject(UserContextMockDB),
26
26
  };
27
- private user$ = new BehaviorSubject(this.authDB.user());
27
+ private user$ = new BehaviorSubject(this.authDB.afUser());
28
28
 
29
29
  // Constant for simulating delay (e.g. to see loading icon in action)
30
30
  GET_LATENCY_SIMULATION_DELAY = 100;
@@ -52,13 +52,13 @@ export class FirebaseMockService implements DatabaseService {
52
52
  return autoId;
53
53
  }
54
54
 
55
- afUser(): Observable<{ uid: string, email: string, displayName: string, photoURL: string }> {
55
+ afUser(): Observable<{ uid: string, email: string, displayName: string, photoURL: string } | null> {
56
56
  return this.user$;
57
57
  }
58
58
 
59
59
  async login(providerId, scope?: string): Promise<any> {
60
60
  this.authDB.login();
61
- this.user$.next(this.authDB.user());
61
+ this.user$.next(this.authDB.afUser());
62
62
  return {
63
63
  user: {
64
64
  uid: USER_DB[0].__id,
@@ -73,7 +73,7 @@ export class FirebaseMockService implements DatabaseService {
73
73
 
74
74
  logout() {
75
75
  this.authDB.logout();
76
- this.user$.next(this.authDB.user());
76
+ this.user$.next(this.authDB.afUser());
77
77
  }
78
78
 
79
79
  streamEntity<T>(collectionName: string, id: string) {
@@ -219,7 +219,7 @@ export class FirebaseMockService implements DatabaseService {
219
219
 
220
220
  if (batch) {
221
221
  const docRef = {
222
- path: `${collectionName}/${entity.__id}`
222
+ path: `${collectionName}/${entity.__id}`,
223
223
  };
224
224
  return batch.set(docRef, entityFinal);
225
225
  } else {
@@ -236,7 +236,7 @@ export class FirebaseMockService implements DatabaseService {
236
236
 
237
237
  if (batch) {
238
238
  const docRef = {
239
- path: `${collectionName}/${id}`
239
+ path: `${collectionName}/${id}`,
240
240
  };
241
241
  return batch.update(docRef, changesFinal);
242
242
  } else {
@@ -254,7 +254,7 @@ export class FirebaseMockService implements DatabaseService {
254
254
 
255
255
  if (batch) {
256
256
  const docRef = {
257
- path: `${collectionName}/${id}`
257
+ path: `${collectionName}/${id}`,
258
258
  };
259
259
  return batch.update(docRef, changes);
260
260
  } else {
@@ -275,3 +275,28 @@ export class FirebaseMockService implements DatabaseService {
275
275
  return await store.update(id, changes);
276
276
  }
277
277
  }
278
+
279
+ /**
280
+ * Creates provider configuration for FirebaseMockService with custom DB collection seeding.
281
+ */
282
+ export function provideFirebaseMock({
283
+ users,
284
+ userContexts,
285
+ }: {
286
+ users?: any[];
287
+ userContexts?: any[];
288
+ } = {}): Provider[] {
289
+ return [
290
+ {
291
+ provide: FirebaseMockService,
292
+ useFactory: (injector: Injector) => {
293
+ const service = new FirebaseMockService(injector);
294
+ if (users) service.DB['users'].init(users);
295
+ if (userContexts) service.DB['userContexts'].init(userContexts);
296
+ return service;
297
+ },
298
+ deps: [Injector],
299
+ },
300
+ { provide: DATABASE_SERVICE, useExisting: FirebaseMockService },
301
+ ];
302
+ }
@@ -32,9 +32,9 @@ export class FirebaseService implements DatabaseService {
32
32
  return autoId;
33
33
  }
34
34
 
35
- afUser(): Observable<User> {
35
+ afUser(): Observable<User | null> {
36
36
  return from(this.afAuth.authStateReady()).pipe(
37
- switchMap(() => this.user$)
37
+ switchMap(() => this.user$),
38
38
  );
39
39
  }
40
40
 
@@ -85,8 +85,8 @@ export class FirebaseService implements DatabaseService {
85
85
  });
86
86
  }
87
87
 
88
- logout() {
89
- return signOut(this.afAuth);
88
+ async logout() {
89
+ await signOut(this.afAuth);
90
90
  }
91
91
 
92
92
  streamEntity<T>(collectionName: string, id: string) {
@@ -0,0 +1,11 @@
1
+ import { isDevMode } from '@angular/core';
2
+
3
+ // Flip this to `true` when you want to trace query execution!
4
+ // This will output rich logs for stream multiplexing and load bucketing.
5
+ export const DEBUG_QUERY_SYSTEM = false;
6
+
7
+ export function queryLog(...args: unknown[]) {
8
+ if (isDevMode() && DEBUG_QUERY_SYSTEM) {
9
+ console.log(...args);
10
+ }
11
+ }
@@ -0,0 +1,104 @@
1
+ import { TestBed } from '@angular/core/testing';
2
+ import { signalStore, withState } from '@ngrx/signals';
3
+ import { withEntitiesAndSelectMethods, withEntitiesAndDBMethods } from '../store/app.store';
4
+ import { DATABASE_SERVICE } from './database.service';
5
+ import { provideFirebaseMock } from './firebase.mock.service';
6
+ import { MOCK_SIMULATION_USERS } from './simulation.mock';
7
+ import * as queryLogger from './query-logger';
8
+ import { Timestamp } from '@angular/fire/firestore';
9
+
10
+ export const UserStore = signalStore(
11
+ { providedIn: 'root' },
12
+ withState({}),
13
+ withEntitiesAndDBMethods<any>('users'),
14
+ );
15
+
16
+ describe('Simulation for Load Bucketing Strategy', () => {
17
+ let currentTime = 0;
18
+ let timestampSpy: jest.SpyInstance;
19
+
20
+ beforeEach(() => {
21
+ // Spy on Firestore Timestamp.now() to control the time without breaking JS setTimeouts
22
+ timestampSpy = jest.spyOn(Timestamp, 'now').mockImplementation(() => {
23
+ return Timestamp.fromMillis(currentTime);
24
+ });
25
+ });
26
+
27
+ afterEach(() => {
28
+ timestampSpy.mockRestore();
29
+ });
30
+
31
+ it('runs the load time bucketing simulation', async () => {
32
+ TestBed.configureTestingModule({
33
+ providers: [
34
+ UserStore,
35
+ provideFirebaseMock({ users: MOCK_SIMULATION_USERS }),
36
+ ],
37
+ });
38
+
39
+ const userStore = TestBed.inject(UserStore) as any;
40
+ const db = TestBed.inject(DATABASE_SERVICE) as any;
41
+
42
+ const logSpy = jest.spyOn(queryLogger, 'queryLog').mockImplementation(() => {});
43
+ const getEntitiesSpy = jest.spyOn(db, 'getEntities');
44
+ const getEntitySpy = jest.spyOn(db, 'getEntity');
45
+
46
+ currentTime = 300000; // start exactly at T = 5 minutes (Bucket index 1)
47
+
48
+ console.log('\n---> Action: Initial Load of id1, id2 at T=5m');
49
+ await userStore.load([['__id', 'in', ['id1', 'id2']]], {});
50
+
51
+ // Expect 2 queries (one for _deleted: false, one for _deleted: true)
52
+ expect(getEntitiesSpy).toHaveBeenCalledTimes(2);
53
+ let callArgs = getEntitiesSpy.mock.calls[0];
54
+ expect(callArgs[1]).toContainEqual(['_deleted', '==', false]);
55
+
56
+ currentTime += 2 * 60 * 1000; // T = 7m (Still in the 5m-10m bucket index 1)
57
+ console.log('\n---> Action: Initial Load of id3, id4 at T=7m');
58
+ getEntitiesSpy.mockClear();
59
+ await userStore.load([['__id', 'in', ['id3', 'id4']]], {});
60
+ expect(getEntitiesSpy).toHaveBeenCalledTimes(2);
61
+
62
+ // Now id1 and id2 have lastLoadTime = 5m
63
+ // id3 and id4 have lastLoadTime = 7m
64
+ // Both belong to the [5m, 10m) bucket (index 1).
65
+
66
+ currentTime += 2 * 60 * 1000; // T = 9m
67
+ console.log('\n---> Action: Load id1, id2, id3, id4 together at T=9m');
68
+ getEntitiesSpy.mockClear();
69
+ await userStore.load([['__id', 'in', ['id1', 'id2', 'id3', 'id4']]], {});
70
+
71
+ // Should be batched into exactly ONE group! So 2 queries total.
72
+ expect(getEntitiesSpy).toHaveBeenCalledTimes(2);
73
+ callArgs = getEntitiesSpy.mock.calls[0];
74
+ // We expect the min time among the bucket items to be used (5m)
75
+ const timestampCondition = (callArgs[1] as any[]).find((param: any) => param[0] === '_updatedAt');
76
+ expect(timestampCondition).toBeDefined();
77
+ expect(timestampCondition![2].toMillis()).toEqual(300000); // exactly 5m
78
+
79
+ // Now ALL of id1, id2, id3, id4 have lastLoadTime = 9m (which is in the 5m-10m bucket)
80
+
81
+ currentTime += 3 * 60 * 1000; // T = 12m (Next bucket index 2)
82
+ console.log('\n---> Action: Initial Load of id5 at T=12m');
83
+ getEntitiesSpy.mockClear();
84
+ getEntitySpy.mockClear();
85
+ await userStore.load([['__id', 'in', ['id5']]], {});
86
+ expect(getEntitiesSpy).toHaveBeenCalledTimes(0);
87
+ expect(getEntitySpy).toHaveBeenCalledTimes(1);
88
+
89
+ // Now we load id1, id2, id3, id4 (lastLoadTime=9m, bucket index 1)
90
+ // AND id5 (lastLoadTime=12m, bucket index 2)
91
+ currentTime += 1 * 60 * 1000; // T = 13m
92
+ console.log('\n---> Action: Load all id1..id5 together at T=13m');
93
+ getEntitiesSpy.mockClear();
94
+ await userStore.load([['__id', 'in', ['id1', 'id2', 'id3', 'id4', 'id5']]], {});
95
+
96
+ // Check if the spy caught the actual internal library logs properly!
97
+ // The previous test tried to assert against the internal console logs of the test file.
98
+ // Instead, assert on the actual bucketing logs from app.store.ts
99
+ const allLogs = logSpy.mock.calls.map((args) => args.join(' '));
100
+ expect(allLogs.some((log) => log.includes('[Store] Grouped 5 IDs into 2 time bucket(s).'))).toBe(true);
101
+
102
+ console.log('\n=== FULL LOAD BUCKETING SIMULATION COMPLETE ===');
103
+ });
104
+ });