@tech4good/platform-data 0.1.0-alpha.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.
- package/BACKENDS.md +161 -0
- package/EXTRACTION-CHANGES.md +1011 -0
- package/FUTURE-WORK.md +328 -0
- package/MIGRATION.md +227 -0
- package/README.md +536 -0
- package/fesm2022/tech4good-platform-data-firestore.mjs +281 -0
- package/fesm2022/tech4good-platform-data-firestore.mjs.map +1 -0
- package/fesm2022/tech4good-platform-data-material.mjs +15 -0
- package/fesm2022/tech4good-platform-data-material.mjs.map +1 -0
- package/fesm2022/tech4good-platform-data-testing.mjs +479 -0
- package/fesm2022/tech4good-platform-data-testing.mjs.map +1 -0
- package/fesm2022/tech4good-platform-data.mjs +2190 -0
- package/fesm2022/tech4good-platform-data.mjs.map +1 -0
- package/package.json +51 -0
- package/types/tech4good-platform-data-firestore.d.ts +83 -0
- package/types/tech4good-platform-data-firestore.d.ts.map +1 -0
- package/types/tech4good-platform-data-material.d.ts +7 -0
- package/types/tech4good-platform-data-material.d.ts.map +1 -0
- package/types/tech4good-platform-data-testing.d.ts +236 -0
- package/types/tech4good-platform-data-testing.d.ts.map +1 -0
- package/types/tech4good-platform-data.d.ts +686 -0
- package/types/tech4good-platform-data.d.ts.map +1 -0
package/FUTURE-WORK.md
ADDED
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
# Platform-data: decisions, watch points and future work
|
|
2
|
+
|
|
3
|
+
Maintainer handoff: September 10, 2026. This records the accepted design and
|
|
4
|
+
proposals for later work. It does not authorize implementing every proposal or
|
|
5
|
+
claim that every risk below is an observed defect.
|
|
6
|
+
|
|
7
|
+
Read [EXTRACTION-CHANGES.md](EXTRACTION-CHANGES.md) for the implementation history,
|
|
8
|
+
[MIGRATION.md](MIGRATION.md) before adopting it, and [BACKENDS.md](BACKENDS.md)
|
|
9
|
+
before introducing another backend. Source paths in this guide refer to the
|
|
10
|
+
repository checkout, not files included in the npm tarball.
|
|
11
|
+
|
|
12
|
+
## Decisions to preserve
|
|
13
|
+
|
|
14
|
+
1. There is one shared root entity store per collection. Components select from
|
|
15
|
+
that common state and share matching listeners. Independent instances of the
|
|
16
|
+
same collection store are not the intended model.
|
|
17
|
+
2. Global stream teardown stops listeners and nested observers. It preserves
|
|
18
|
+
records and load history. An explicit `store.reset()` clears that store's
|
|
19
|
+
records and only its collection's history. `clearCache()` is an explicit
|
|
20
|
+
global listener/history invalidation, not the normal logout operation.
|
|
21
|
+
3. The app chooses auth/profile/session state to reset. Generated auth resets
|
|
22
|
+
UserStore, available UserContextStore and the telemetry session identifier.
|
|
23
|
+
Other domain stores retain records/history. Entity discovery must not acquire
|
|
24
|
+
an implicit reset-all policy.
|
|
25
|
+
4. Ordinary pending reads and writes may finish after teardown/reset. General
|
|
26
|
+
session epochs and automatic store resets were deliberately removed. Keep
|
|
27
|
+
listener-specific teardown guards; they solve a different problem.
|
|
28
|
+
5. Stored records require identity, shared timestamps and soft-delete metadata.
|
|
29
|
+
Core and `/testing` remain Firebase-free. Firestore owns SDK conversion.
|
|
30
|
+
6. Runtime logging is shared through platform-logging. Auth flows, navigation,
|
|
31
|
+
domain policies, rules and deletion graphs remain app-owned today.
|
|
32
|
+
|
|
33
|
+
These are product/architecture choices made during review, not accidental
|
|
34
|
+
omissions to silently "fix" in the next refactor. Revisit them with a concrete
|
|
35
|
+
use case or reproducible failure.
|
|
36
|
+
|
|
37
|
+
## 1. Monitor the chosen session cleanup policy
|
|
38
|
+
|
|
39
|
+
### Why we chose it
|
|
40
|
+
|
|
41
|
+
Mentor's July 28 `5b132ce` commit documents stopping old credential-bound
|
|
42
|
+
listeners to prevent denied reads after sign-out/deletion. Its reset list did
|
|
43
|
+
cover all stores then present; later chat entities simply were not added. The
|
|
44
|
+
history did not establish a separate incident requiring all local records to be
|
|
45
|
+
cleared. The user chose explicit auth-state reset and retained domain data, as
|
|
46
|
+
with ordinary navigation, while retaining **global** listener teardown.
|
|
47
|
+
|
|
48
|
+
Retained load history is paired with retained records. Clearing only the history
|
|
49
|
+
of reset stores avoids forcing full reloads in otherwise retained stores. This
|
|
50
|
+
assumes those records and cutoffs are still appropriate for the next use of the
|
|
51
|
+
query. A selector chooses from local data; it is not an authentication filter.
|
|
52
|
+
|
|
53
|
+
### Concrete watch points
|
|
54
|
+
|
|
55
|
+
| Situation | Current behavior / uncertainty | What to check before changing policy |
|
|
56
|
+
| --- | --- | --- |
|
|
57
|
+
| Account A signs out, then B signs in without a page reload | Domain records remain in memory. There is no claim that every selector in every app excludes A's retained records. | Exercise real app screens and root-level components; inspect records rendered before and after B's load. Check account/workspace predicates and auth-gated display. Capture an actual incorrect result before choosing a targeted reset or different cache scope. |
|
|
58
|
+
| A signed-out/public screen needs cached data | Retention intentionally permits this. Clearing every store would change that behavior. | Include public/offline-oriented flows in adoption tests so an auth change does not erase deliberately reusable state. |
|
|
59
|
+
| An ordinary read or optimistic write finishes after logout | It can apply records/history or rollback local state; it is not just a possible console error. | Delay the operation, sign out, then observe the next screen and next account. If results are wrong, determine which auth-sensitive operation needs guarding instead of reintroducing a blanket cancellation system. |
|
|
60
|
+
| The effective dataset changes while the collection/query key stays the same | Retained incremental cutoffs can be inappropriate after an app changes account/workspace scope or query meaning. | Reproduce with the app's actual filters and authorization model. Decide whether that transition should reset a particular store, explicitly clear history, or use a distinct query. Rules should not be assumed to filter a broad query for the caller. |
|
|
61
|
+
| Another tab signs out, or auth identity changes externally | Generated cleanup is called by explicit logout/guest-deletion flows. The auth observer is not yet a general cleanup coordinator for every external transition. | Test externally observed sign-out and direct UID switches, including active profile provisioning and root listeners. This is a requirement for a future auth package. |
|
|
62
|
+
| `store.reset()` is called while its listeners remain active | Reset does not unsubscribe. Records may return on updates, and a matching cached connection may not resend an initial snapshot merely because local records were emptied. | Normal auth flow tears down first. If another feature needs a standalone reset-and-reload operation, define and test that lifecycle explicitly. |
|
|
63
|
+
| `store.init()` replaces an already-used store | It replaces records without resetting history. It is not a complete cache-invalidation API. | Check any use outside initial setup/tests. If replacement must invalidate cutoffs, do so explicitly or design a dedicated operation. |
|
|
64
|
+
|
|
65
|
+
No verified cross-account UI incident was found in the review that led to this
|
|
66
|
+
decision. That is a validation limit, not proof that all app selectors are safe.
|
|
67
|
+
Firebase SDK persistence, mock persistence and backend records have separate
|
|
68
|
+
lifetimes; clearing an NgRx store does not clear them.
|
|
69
|
+
|
|
70
|
+
### Adoption scenarios to retain as regression coverage
|
|
71
|
+
|
|
72
|
+
- Normal logout and guest deletion: all active and retiring listeners close;
|
|
73
|
+
user/profile/session state resets; intended domain records and both kinds of
|
|
74
|
+
domain load history survive.
|
|
75
|
+
- Reset one collection, then load it and an untouched collection: the reset
|
|
76
|
+
collection loads fully; the untouched collection continues incrementally.
|
|
77
|
+
- A root-provided store used by two components shares data/listeners. Leaving
|
|
78
|
+
one component does not interrupt the other; returning during the grace period
|
|
79
|
+
reuses the connection.
|
|
80
|
+
- Delayed reads and profile provisioning around sign-out, a second sign-in,
|
|
81
|
+
logout without routing, and any public page that can remain mounted.
|
|
82
|
+
- External auth changes and browser restoration, with the app's actual cache
|
|
83
|
+
configuration and selector predicates.
|
|
84
|
+
|
|
85
|
+
The package and generated-app tests cover the first behaviors, including an
|
|
86
|
+
ordinary late read. Actual MathPets/Mentor account-switch screens and external
|
|
87
|
+
auth transitions still need application-level validation.
|
|
88
|
+
|
|
89
|
+
## 2. Remaining data-engine questions
|
|
90
|
+
|
|
91
|
+
These are boundaries to investigate when an application needs them, not a
|
|
92
|
+
commitment to redesign the entire synchronization system now.
|
|
93
|
+
|
|
94
|
+
### Keep later refactors separate from extraction
|
|
95
|
+
|
|
96
|
+
The first-extraction review restored the original selector ID branches, separate
|
|
97
|
+
batch modes, explicit Firestore option/write branches, mock snapshot/pairwise
|
|
98
|
+
stream flow, and direct ordinary mock writes. See the review table in
|
|
99
|
+
[EXTRACTION-CHANGES.md](EXTRACTION-CHANGES.md#extraction-review-preserve-the-original-flow)
|
|
100
|
+
for the original-to-package mapping and reasons for the differences retained.
|
|
101
|
+
|
|
102
|
+
Do not consolidate these branches or replace them with a new pipeline merely
|
|
103
|
+
while moving files or adopting the package. A later refactor can be worthwhile,
|
|
104
|
+
but give it its own commit, explain its benefit, and compare behavior and work
|
|
105
|
+
performed on large stores. In particular, keep ID lookup from enumerating the
|
|
106
|
+
whole store, and avoid whole-collection batch staging for ordinary mock writes.
|
|
107
|
+
|
|
108
|
+
Preserve the original comments' explanations, examples and tradeoffs as well as
|
|
109
|
+
the code's flow. For example, the optional __hashtagId query explains why an
|
|
110
|
+
undefined filter is ignored; replacing it with "ignore optional operands" loses
|
|
111
|
+
the reason and the concrete use case. When moving code, move that context with it.
|
|
112
|
+
If behavior changed, update the specific claim while retaining the useful example
|
|
113
|
+
and explaining the new behavior. Do not copy obsolete limitations as current facts.
|
|
114
|
+
|
|
115
|
+
### Optional filters and empty `in` lists
|
|
116
|
+
|
|
117
|
+
Decision from the selector/load review: **keep the existing nested-load rule**
|
|
118
|
+
in `processLoadQueries`. If any filter in a nested query contains `in []`, do
|
|
119
|
+
not call `store.load()` for that query. Other nested queries still run. This
|
|
120
|
+
avoids sending the empty `in` request to Firestore. The guard remains in
|
|
121
|
+
`packages/data/src/query-descriptors.ts`; it was present before extraction.
|
|
122
|
+
|
|
123
|
+
Keep these three behaviors distinct:
|
|
124
|
+
|
|
125
|
+
- An undefined filter value is intentionally ignored for optional relationships.
|
|
126
|
+
The other filters still apply. If none remain, selection includes all active
|
|
127
|
+
records already in the store.
|
|
128
|
+
- An empty `in` list makes the nested-load helper skip the **entire query**.
|
|
129
|
+
It does not clear existing records or establish that the store has no matches.
|
|
130
|
+
- The current local selector treats `in []` as matching no records. The original
|
|
131
|
+
selector discarded that filter instead. The ID lookup fix did not change this
|
|
132
|
+
separate selection policy; any further change needs an explicit decision.
|
|
133
|
+
|
|
134
|
+
Watch for a page assuming a skipped load clears old related data, or treating
|
|
135
|
+
"nothing was loaded" as proof that no related records exist. Also check callers
|
|
136
|
+
that build ID lists from optional relationships: ignoring one filter and
|
|
137
|
+
skipping an entire query have different effects when other filters are present.
|
|
138
|
+
Reproduce with already-cached records and multiple nested queries before changing
|
|
139
|
+
these rules. Existing coverage now checks that an empty-list query is skipped
|
|
140
|
+
while a separate valid query still runs. Do not remove the load guard merely to
|
|
141
|
+
make these different operations behave alike.
|
|
142
|
+
|
|
143
|
+
### Incremental loading and query membership
|
|
144
|
+
|
|
145
|
+
The existing algorithm uses timestamp cutoffs and soft-deleted records. Review
|
|
146
|
+
client/server clock differences, timestamp precision, writes at a cutoff and
|
|
147
|
+
concurrent changes when diagnosing missed updates. Hard deletion leaves no
|
|
148
|
+
tombstone for a later delta load. A record can also leave a filtered/limited
|
|
149
|
+
query without being globally deleted. Query membership and global entity
|
|
150
|
+
existence are different concepts; any new limited-query or backend behavior
|
|
151
|
+
needs tests for that distinction.
|
|
152
|
+
|
|
153
|
+
Do not equate an `await store.stream(...)` registration or its loading flag
|
|
154
|
+
with a guarantee that all initial backend snapshots and nested streams have
|
|
155
|
+
arrived. If a feature needs explicit readiness, define that contract and error
|
|
156
|
+
state before using it in guards or navigation. Nested failures are available
|
|
157
|
+
through `CachedListenersService.errors$`; apps may need a visible retry/error
|
|
158
|
+
experience. Automatic reconnection/backoff is not currently supplied by that API.
|
|
159
|
+
|
|
160
|
+
### Writes, rollback and Undo
|
|
161
|
+
|
|
162
|
+
Reverse-order compensation fixes ordering within a write operation. It does
|
|
163
|
+
not resolve overlapping optimistic operations on the same entity or conflicts
|
|
164
|
+
with another client's newer changes. Undo is a new write and can fail. Revisit
|
|
165
|
+
version checks, conflict behavior or operation serialization only with a concrete
|
|
166
|
+
consumer and tests for dependent/overlapping writes.
|
|
167
|
+
|
|
168
|
+
A post-commit feedback/local-patch error can reject after persistence succeeded.
|
|
169
|
+
The coordinator avoids rolling back committed optimistic data, but the caller
|
|
170
|
+
may still interpret rejection as "nothing saved" and retry. If observed, separate
|
|
171
|
+
persisted-write success from local/feedback failure in the public result contract.
|
|
172
|
+
Do not implement blind write retries without considering duplicate operations.
|
|
173
|
+
|
|
174
|
+
### Mock and adapter parity
|
|
175
|
+
|
|
176
|
+
Mocks cover the supported query/write behavior, not all Firestore semantics.
|
|
177
|
+
When adding operators, dotted-field updates, transforms, cursor types or complex
|
|
178
|
+
SDK values, compare local selectors, mock reads/writes and the real adapter.
|
|
179
|
+
Use focused emulator cases for adapter behavior and real index validation where
|
|
180
|
+
needed; passing mock tests alone is insufficient.
|
|
181
|
+
|
|
182
|
+
Persistence may eventually need an explicit seed/schema version and migration
|
|
183
|
+
policy. Review cross-tab changes and storage clearing as well as malformed data;
|
|
184
|
+
the current fallback is not a general migration system. Keep browser-storage
|
|
185
|
+
ownership/lifetime explicit and keep production fixtures out of bundles.
|
|
186
|
+
|
|
187
|
+
### Contracts and external writers
|
|
188
|
+
|
|
189
|
+
Required TypeScript metadata does not validate existing documents, Cloud
|
|
190
|
+
Functions, imports or administrative writes. Check that they preserve `_createdAt`,
|
|
191
|
+
advance `_updatedAt` and use `_deleted` consistently. Add a validation/migration
|
|
192
|
+
tool if real data warrants it, rather than silently inventing missing history.
|
|
193
|
+
|
|
194
|
+
Some inherited adapter/query internals still use `any`. Tighten those contracts
|
|
195
|
+
incrementally with public consumer type tests; avoid imposing an exhaustive
|
|
196
|
+
application entity union on the library again. Keep the no-Firebase core tests
|
|
197
|
+
and timestamp round-trip tests whenever dependencies or public values change.
|
|
198
|
+
|
|
199
|
+
## 3. Future auth/profile package
|
|
200
|
+
|
|
201
|
+
This is proposed work, **not an implemented package/API**. The detailed research
|
|
202
|
+
is in `docs-plans/platform-auth-and-onboarding-extraction.md` in the repository.
|
|
203
|
+
The working package name is `@tech4good/platform-auth`; proposed `/profiles`,
|
|
204
|
+
`/firebase` and `/testing` paths would be secondary entry points released with it.
|
|
205
|
+
|
|
206
|
+
The user wants profile assurance to be standard: an authenticated session should
|
|
207
|
+
resolve its profile, creating one if necessary. New profiles should default to
|
|
208
|
+
non-admin status while allowing app-specific fields/defaults. Existing profiles
|
|
209
|
+
must not have roles, consent or access state overwritten by new-user defaults.
|
|
210
|
+
|
|
211
|
+
Recommended responsibilities:
|
|
212
|
+
|
|
213
|
+
| Shared | App-owned |
|
|
214
|
+
| --- | --- |
|
|
215
|
+
| Session model, auth adapter contract, restoration and sign-in/link/sign-out operations | Which sign-in choices appear on each entry screen |
|
|
216
|
+
| Profile assurance, configurable new-profile factory and reconciliation policies | Domain profile fields, intentional role transitions and authorization |
|
|
217
|
+
| Coordination of auth notifications, provisioning, readiness, errors/retry and teardown | Guards, routes, return destinations and ordering of onboarding steps |
|
|
218
|
+
| Firebase adapter and auth simulator using the same lifecycle | Firebase project configuration and test personas |
|
|
219
|
+
| Data-integration cleanup hook plus explicit auth/profile reset | Extra session/analytics state and any evidence-based domain invalidation |
|
|
220
|
+
| An injectable account-deletion operation | Server-side deletion graph and guest save/delete prompts |
|
|
221
|
+
|
|
222
|
+
The current local Firebase and mock facades remain because they still implement
|
|
223
|
+
these app policies. Eventually consumers should use separate data and auth
|
|
224
|
+
contracts; data must not depend back on auth. A combined database facade can
|
|
225
|
+
delegate temporarily during migration.
|
|
226
|
+
|
|
227
|
+
Important design requirements:
|
|
228
|
+
|
|
229
|
+
- Share the profile algorithm across real and mock persistence. Custom factories
|
|
230
|
+
should not require reimplementing ordinary profile assurance.
|
|
231
|
+
- Use an atomic ensure/create-if-missing persistence contract. Current `DataAccess`
|
|
232
|
+
does not expose that capability; a read followed by an add is not sufficient
|
|
233
|
+
for concurrent tabs. Keep retryable factories free of external side effects.
|
|
234
|
+
- Distinguish authentication success from profile readiness/failure. A failed
|
|
235
|
+
profile write should leave a retryable state, not a guard waiting forever or
|
|
236
|
+
an unnecessary attempt to recreate an authenticated account.
|
|
237
|
+
- Coordinate explicit and observed sign-out, UID changes, restored sessions and
|
|
238
|
+
delayed profile operations. Target stale **auth/profile** work without turning
|
|
239
|
+
every domain store read into a session-cancelled operation.
|
|
240
|
+
- Preserve Google/anonymous sign-in, email-link sign-in, account linking and
|
|
241
|
+
their distinct outcomes. Configure callback URLs and storage namespaces;
|
|
242
|
+
return credential conflicts for the app to resolve rather than merging accounts.
|
|
243
|
+
- Keep teardown separate from domain retention. Test preserved domain records
|
|
244
|
+
and history, not a removed automatic store registry/reset-all assumption.
|
|
245
|
+
|
|
246
|
+
Start with configurable profile assurance, then auth lifecycle/adapters, then
|
|
247
|
+
update generated app composition. Test standard lab defaults and Mentor's role
|
|
248
|
+
behavior, repeated/concurrent provisioning, missing related records, offline or
|
|
249
|
+
denied writes, email callbacks, linking conflicts and external auth transitions.
|
|
250
|
+
|
|
251
|
+
## 4. Shared consent and other UI flows
|
|
252
|
+
|
|
253
|
+
Proposed `@tech4good/platform-onboarding` can distribute actual standalone Angular
|
|
254
|
+
components, templates and styles, with `/material` for the default UI. An app
|
|
255
|
+
imports them and receives package-owned fixes on dependency upgrade/rebuild.
|
|
256
|
+
Schematics should generate host/configuration code, not another copied consent
|
|
257
|
+
implementation.
|
|
258
|
+
|
|
259
|
+
Begin with consent rather than a universal configurable onboarding wizard:
|
|
260
|
+
|
|
261
|
+
- Share checkbox validation, pending state, duplicate-submit prevention,
|
|
262
|
+
already-accepted state and error/retry behavior. Offer a controller for apps
|
|
263
|
+
needing a different layout and a Material component for the common case.
|
|
264
|
+
- Customize text/options through typed inputs, richer sections through content
|
|
265
|
+
slots/templates, and appearance through supported theme tokens. App-replaced
|
|
266
|
+
templates stay app-owned and do not automatically receive package fixes.
|
|
267
|
+
- Await a save callback/service and report completion only after it succeeds.
|
|
268
|
+
Keep navigation separate so a routing failure is not reported as failed
|
|
269
|
+
persistence. Do not assume emitting an output awaits the parent's async save.
|
|
270
|
+
- Leave access-state transitions to configuration: MathPets/schematics currently
|
|
271
|
+
advance to `DONE`, while Mentor advances only from `CONSENT`.
|
|
272
|
+
- Keep consent document identity/version and acceptance policy separate from
|
|
273
|
+
npm version. A UI bug fix should not silently require everyone to consent again.
|
|
274
|
+
|
|
275
|
+
Try a built tarball in disposable MathPets and Mentor apps to demonstrate both
|
|
276
|
+
shared fixes and preserved local policy. Consent is a useful independent UI
|
|
277
|
+
pilot and need not wait for a complete auth migration.
|
|
278
|
+
|
|
279
|
+
## 5. Future databases
|
|
280
|
+
|
|
281
|
+
The shared timestamp value removes a core dependency on Firebase; it does not
|
|
282
|
+
by itself make the query, write and realtime contracts database-independent.
|
|
283
|
+
No Supabase or PostgreSQL adapter has been implemented.
|
|
284
|
+
|
|
285
|
+
[BACKENDS.md](BACKENDS.md) records the deferred design: timestamp mapping and
|
|
286
|
+
precision, server-authored metadata, query capabilities, change cursors,
|
|
287
|
+
realtime initial snapshots plus changes, writes/Undo, and app-owned schema/auth.
|
|
288
|
+
Use it as the starting point. Validate a small real consumer before broadening
|
|
289
|
+
`DataAccess` or promising that another database behaves exactly like Firestore.
|
|
290
|
+
|
|
291
|
+
## 6. Next adoption and release work
|
|
292
|
+
|
|
293
|
+
1. Rebuild the exact candidate and install its tarball in a disposable app first.
|
|
294
|
+
Install a matching platform-logging version too. Core, Firestore, testing and
|
|
295
|
+
Material entry points are one data release; logging is a separate package.
|
|
296
|
+
2. Follow the migration guide on a MathPets or Mentor branch. Earlier disposable
|
|
297
|
+
trials predate some final changes; they are not proof the current real apps
|
|
298
|
+
have adopted platform-data. Check timestamps, complete metadata/fixtures,
|
|
299
|
+
direct imports, providers, entity generation and app-specific auth cleanup.
|
|
300
|
+
3. Run package tests and the application's lint/build/tests/rules/index and
|
|
301
|
+
entity-registry checks. Exercise the session scenarios above in the actual
|
|
302
|
+
application. Firebase emulator success does not prove production composite
|
|
303
|
+
indexes exist.
|
|
304
|
+
4. Inspect the production bundle for mock seeds and check the installed package
|
|
305
|
+
exports/peer dependencies. Test a real tarball rather than relying solely on
|
|
306
|
+
workspace or npm-link resolution.
|
|
307
|
+
5. Follow the README's release instructions. Publish logging before a data
|
|
308
|
+
version that requires it, use the intended alpha tag, and publish the built
|
|
309
|
+
data `dist` directory. Inspect current manifests rather than assuming the
|
|
310
|
+
version in this dated note is still current.
|
|
311
|
+
|
|
312
|
+
There is no automatic commit, publish, deployment or real-app migration implied
|
|
313
|
+
by this handoff. Add release notes for actual changes after this initial record.
|
|
314
|
+
|
|
315
|
+
## For the next agent
|
|
316
|
+
|
|
317
|
+
Start with the README, these two handoff documents and MIGRATION.md. Inspect
|
|
318
|
+
current source and git status, including untracked package files: the initial
|
|
319
|
+
extraction was documented before its commit. Use baseline `fda18e3` for the
|
|
320
|
+
original copied templates and the named Mentor commits for the teardown history.
|
|
321
|
+
|
|
322
|
+
The repository's chronological extraction plan contains superseded experiments
|
|
323
|
+
and multiple validation milestones. Prefer the final decisions here when they
|
|
324
|
+
conflict with an earlier paragraph. Do not treat disposable test artifacts under
|
|
325
|
+
`/private/tmp` as durable evidence or assume older passing counts validate a new
|
|
326
|
+
artifact. Record new reproduction cases, decisions and validation with the change
|
|
327
|
+
that needs them. In particular, do not silently restore reset-all registration,
|
|
328
|
+
multi-instance store ownership or general pending-read/write cancellation.
|
package/MIGRATION.md
ADDED
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
# Migrating an existing lab application
|
|
2
|
+
|
|
3
|
+
Use a branch or disposable copy and an installed package tarball first. Do not
|
|
4
|
+
rerun `ng-add` over an existing application: authentication policy, profiles,
|
|
5
|
+
entity registrations, routes and configuration differ between the apps.
|
|
6
|
+
|
|
7
|
+
Before migrating, read [changes beyond extraction](EXTRACTION-CHANGES.md) for
|
|
8
|
+
behavior changes and [future work/watch points](FUTURE-WORK.md) for the accepted
|
|
9
|
+
store-retention policy and application scenarios that still need validation.
|
|
10
|
+
|
|
11
|
+
## 1. Preserve app entities and domain code
|
|
12
|
+
|
|
13
|
+
Keep app entity interfaces, mock seeds, `LoadX`/`StreamX` classes, and domain stores.
|
|
14
|
+
Change their shared imports to the package directly:
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
import {
|
|
18
|
+
withEntitiesAndDBMethods, withEntitiesAndSelectMethods,
|
|
19
|
+
selectEntities, entityInQueryResults, processLoadQueries,
|
|
20
|
+
EntityLoadQuery, EntityStreamQuery, QueryParams, QueryOptions,
|
|
21
|
+
CachedListenersService, StreamMultiplexer, BATCH_WRITE_SERVICE,
|
|
22
|
+
} from '@tech4good/platform-data';
|
|
23
|
+
import { withEntitiesForMockDB, BatchWriteMockService } from '@tech4good/platform-data/testing';
|
|
24
|
+
import { FirestoreBatchWriteService } from '@tech4good/platform-data/firestore';
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Update components, auth stores, app configuration, tests and any custom generators
|
|
28
|
+
as well. Delete the old `core/store/app.store.ts`, listener/cache and batch-service
|
|
29
|
+
forwarding files after updating their consumers. Do not introduce reexports at
|
|
30
|
+
those paths. Replace infrastructure uses of the app's `AnyEntity` with `DataEntity`,
|
|
31
|
+
then remove `app.model.ts` if it only held that union. Import shared query types
|
|
32
|
+
directly. An app-specific exhaustive union, if needed, can derive from the
|
|
33
|
+
generated `AppEntityMap[keyof AppEntityMap]` instead of a handwritten list.
|
|
34
|
+
|
|
35
|
+
The shared `simulate-load.spec.ts`, `simulate-stream.spec.ts` and
|
|
36
|
+
`simulation.mock.ts` now live in the data package's repository test suite. Remove
|
|
37
|
+
their copied versions from `core/firebase` after checking for any app-specific
|
|
38
|
+
cases you added. Keep those cases, along with tests of your providers, entity
|
|
39
|
+
relationships, auth flows and security rules, in the app.
|
|
40
|
+
|
|
41
|
+
Make each stored model extend `DataEntity` and remove its optional declarations
|
|
42
|
+
of `__id`, `_createdAt`, `_updatedAt`, `_deleted`. The inherited fields are required.
|
|
43
|
+
Use `NewDataEntity<MyEntity>` for creation inputs that have not received metadata;
|
|
44
|
+
`store.add()` supplies it. Direct adapter adds still require an ID. Seed factories,
|
|
45
|
+
raw mock-store inserts and `store.init()` must return complete stored records.
|
|
46
|
+
Update fixtures to use `createMockX()` or supply both timestamps and `_deleted`.
|
|
47
|
+
|
|
48
|
+
Check existing persisted data and every external writer for missing metadata.
|
|
49
|
+
Required TypeScript fields do not repair old documents. Missing `_deleted` can
|
|
50
|
+
exclude a record from active queries; missing `_updatedAt` prevents reliable
|
|
51
|
+
incremental loading and nested-stream update detection. `_createdAt` is the
|
|
52
|
+
creation-time convention, though the incremental algorithm does not filter on it.
|
|
53
|
+
|
|
54
|
+
### Replace Firebase timestamp values in application records
|
|
55
|
+
|
|
56
|
+
Import `DataTimestamp` and its helpers from `@tech4good/platform-data`:
|
|
57
|
+
|
|
58
|
+
| Old application usage | Shared value usage |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| `Timestamp` field type | `DataTimestamp` |
|
|
61
|
+
| `Timestamp.now()` | `dataTimestampNow()` |
|
|
62
|
+
| `Timestamp.fromMillis(ms)` | `dataTimestampFromMillis(ms)` |
|
|
63
|
+
| `Timestamp.fromDate(date)` | `dataTimestampFromDate(date)` |
|
|
64
|
+
| `timestamp.toMillis()` | `dataTimestampToMillis(timestamp)` (potentially lossy) |
|
|
65
|
+
| `timestamp.toDate()` | `dataTimestampToDate(timestamp)` (display conversion) |
|
|
66
|
+
| `a.isEqual(b)` or object identity checks | `dataTimestampEquals(a, b)` |
|
|
67
|
+
| Chronological comparison | `compareDataTimestamps(a, b)` |
|
|
68
|
+
|
|
69
|
+
Update metadata seeds and domain timestamp fields (for example,
|
|
70
|
+
`User.joinedWaitlistAt`), their factories, UI formatters and assertions.
|
|
71
|
+
Use `isDataTimestamp(value)` instead of `instanceof Timestamp`. Clock-controlled
|
|
72
|
+
store tests can spy on `Date.now()`; query cutoff operands are shared values.
|
|
73
|
+
|
|
74
|
+
The adapter decodes **all native timestamp values** in document maps/arrays,
|
|
75
|
+
not just metadata. It encodes tagged shared values on all write and query paths.
|
|
76
|
+
Ordinary strings/maps are preserved; `__type: 'DataTimestamp'` is a reserved tag.
|
|
77
|
+
Native SDK operations outside this adapter use `fromFirestoreTimestamp()` and
|
|
78
|
+
`toFirestoreTimestamp()` from `/firestore` at their boundaries. If a timestamp is
|
|
79
|
+
inside an SDK sentinel such as `arrayUnion`, convert it before making the sentinel.
|
|
80
|
+
|
|
81
|
+
Keep database/server timestamp generation in Firestore. Existing persisted
|
|
82
|
+
Firestore documents, Cloud Functions, security rules and indexes retain their
|
|
83
|
+
native representation. Mock persistence can read the previous tagged Timestamp
|
|
84
|
+
format without importing Firebase. The core/testing can now run without Firebase
|
|
85
|
+
installed; applications using `/firestore` still need the Firebase peer.
|
|
86
|
+
|
|
87
|
+
## 2. Split shared data from app auth policy
|
|
88
|
+
|
|
89
|
+
Keep `AuthSession` and the app's authentication/profile interface locally. Extend
|
|
90
|
+
the package `DataAccess` interface, and alias its token:
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
import { InjectionToken } from '@angular/core';
|
|
94
|
+
import { DATA_ACCESS, DataAccess } from '@tech4good/platform-data';
|
|
95
|
+
|
|
96
|
+
export interface DatabaseService extends DataAccess {
|
|
97
|
+
// Keep your app's existing auth/profile methods here.
|
|
98
|
+
}
|
|
99
|
+
export const DATABASE_SERVICE = DATA_ACCESS as InjectionToken<DatabaseService>;
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Extend `FirestoreDataService` from `/firestore` in the app's `FirebaseService`.
|
|
103
|
+
Remove only its duplicated data methods: createId, streamEntity, streamEntities,
|
|
104
|
+
streamEntitiesChanges, query-constraint construction, getEntity, getEntities,
|
|
105
|
+
count, aggregate, addEntity, updateEntity, removeEntity, incrementEntityField.
|
|
106
|
+
Keep auth mapping, login/linking, email-link context, profile provisioning,
|
|
107
|
+
account deletion and logout unchanged. Call `super()` in its constructor.
|
|
108
|
+
The base uses `dataFirestore`, so an app-specific `firestore` member can remain
|
|
109
|
+
where provisioning requires it.
|
|
110
|
+
|
|
111
|
+
Provide `PLATFORM_FIRESTORE` with the instance the app already configures. Supply
|
|
112
|
+
the combined app facade under `DATABASE_SERVICE`; do not also create a different
|
|
113
|
+
auth/data token. If using `provideFirestoreData()`, put the app facade override
|
|
114
|
+
after that provider. `useExisting` avoids creating a second instance when the
|
|
115
|
+
facade is also injected by class.
|
|
116
|
+
|
|
117
|
+
## 3. Preserve mock profiles and seeds
|
|
118
|
+
|
|
119
|
+
Extend `MockDataService` from `/testing` in the local `FirebaseMockService`.
|
|
120
|
+
Keep the app's `AuthMockDB` and auth/profile methods. Replace its handwritten
|
|
121
|
+
collection map and seed initialization with entity-local definitions:
|
|
122
|
+
|
|
123
|
+
1. Export `problemEntity = defineEntity<Problem>({ collection: 'problems' })`
|
|
124
|
+
beside the interface in `problem.model.ts`. Preserve existing collection names.
|
|
125
|
+
2. Use `problemEntity.collection` in the entity store, mock store, and load/stream
|
|
126
|
+
descriptors instead of repeating the string.
|
|
127
|
+
3. In `problem.mock.ts`, directly import the definition from `./problem.model`
|
|
128
|
+
and export `problemMock = defineEntityMock(problemEntity, { store: ProblemMockDB,
|
|
129
|
+
seeds: PROBLEM_DB })`. The mock store uses `withEntitiesForMockDB<Problem>`.
|
|
130
|
+
4. Install platform-tooling alpha.2 or later and run `t4g-entities`. It writes
|
|
131
|
+
`entities.generated.ts` and `entity-mocks.generated.ts` inside the application.
|
|
132
|
+
5. In the facade, import `APP_ENTITY_MOCKS` from the generated mock file and use
|
|
133
|
+
`override readonly DB = createMockRegistry(APP_ENTITY_MOCKS)`. Call
|
|
134
|
+
`super(injector)` in the constructor. Remove per-entity imports, manual seed
|
|
135
|
+
initialization, and duplicated data methods/latency controls.
|
|
136
|
+
6. Change test seed options to `collections: { users: [...], problems: [...] }`.
|
|
137
|
+
Type these with `MockSeedOverrides<typeof APP_ENTITY_MOCKS>` and apply them
|
|
138
|
+
through `seedMockRegistry<typeof APP_ENTITY_MOCKS>(service.DB, collections)`.
|
|
139
|
+
Explicit overrides replace persisted fixtures, including empty arrays.
|
|
140
|
+
7. Wrap development commands with `t4g-entities --watch -- ng serve` (or the
|
|
141
|
+
existing watch command). Prefix one-off builds/tests/lint with `t4g-entities &&`.
|
|
142
|
+
Add `generate:entities` and `check:entities` scripts; keep generated files in git.
|
|
143
|
+
8. Move mock provider imports into a development provider module. Configure the
|
|
144
|
+
production Angular build to replace it with a real-only provider module;
|
|
145
|
+
an environment check alone does not guarantee fixture imports are absent.
|
|
146
|
+
|
|
147
|
+
`createMockRegistry`, `seedMockRegistry`, and `defineEntityMock` come from
|
|
148
|
+
`@tech4good/platform-data/testing`. Apps without an auth facade may use
|
|
149
|
+
`provideMockData({ collections: () => createMockRegistry(APP_ENTITY_MOCKS) })`.
|
|
150
|
+
The generated registry retains each concrete mock-store type; tests that inject
|
|
151
|
+
`ProblemMockDB` still see the same backend instance. Domain models remain local.
|
|
152
|
+
|
|
153
|
+
Generation does not migrate existing data, rewrite security rules, or change
|
|
154
|
+
application auth policy. A missing custom mock declaration produces an empty
|
|
155
|
+
in-memory collection; add the declaration to preserve existing seeded/persisted
|
|
156
|
+
mock behavior. No manual `AnyEntity` or per-entity facade edits are needed after
|
|
157
|
+
this one-time migration.
|
|
158
|
+
|
|
159
|
+
Import `BatchWriteMockService` and `WriteBatchMock` directly from `/testing`, and
|
|
160
|
+
`FirestoreBatchWriteService` from `/firestore`. The mock batch provider uses the mock
|
|
161
|
+
adapter configured under `DATA_ACCESS`, including an app facade subclass.
|
|
162
|
+
|
|
163
|
+
## 4. Configure optional integrations and logout cleanup
|
|
164
|
+
|
|
165
|
+
Add `provideMaterialDataFeedback()` to preserve existing snackbar/undo options.
|
|
166
|
+
Install `@tech4good/platform-logging` alongside the data package and configure
|
|
167
|
+
`providePlatformLogging(...)` once in the app. Data diagnostics use its `data`
|
|
168
|
+
namespace; remove `DATA_LOGGER` providers and the `logger` option previously
|
|
169
|
+
accepted by `providePlatformData`. Import `Logger`, `injectLogger` and
|
|
170
|
+
`LoggingService` directly from the logging package. Replace module-level
|
|
171
|
+
`getLogger(...)` calls with `injectLogger(...)` in an injection context, or pass
|
|
172
|
+
a logger to non-injectable helpers. Delete the copied local logging service
|
|
173
|
+
after migrating its consumers; no compatibility reexports are needed.
|
|
174
|
+
|
|
175
|
+
Tests can capture `{ namespace, level, values }` through the logging provider's
|
|
176
|
+
`sink` option. Saved `query` filters should change to `data`. Generated apps only
|
|
177
|
+
enable optional persistence/DevTools access in development; logging output itself
|
|
178
|
+
defaults to disabled. The logging package README includes a migration checklist.
|
|
179
|
+
Configure
|
|
180
|
+
`MOCK_PERSISTENCE` using the app's existing cache setting if persistence is wanted.
|
|
181
|
+
The package itself imports no environment file or Material service in its root.
|
|
182
|
+
|
|
183
|
+
Keep global `CachedListenersService.teardownAllStreams()` before removing
|
|
184
|
+
credentials: it closes listeners/nested observers while preserving records and
|
|
185
|
+
load history in every entity store. Keep the app's explicit auth-related resets, session-ID
|
|
186
|
+
cleanup, and provisioning coordination. Generated apps call this composition
|
|
187
|
+
`AuthStore.clearSessionState()` and reset `UserStore` and `UserContextStore`,
|
|
188
|
+
including each collection's query and per-entity load history.
|
|
189
|
+
|
|
190
|
+
Remove blanket domain-store resets from logout when adopting this policy. Domain
|
|
191
|
+
records remain available across navigation and logout; the app's selectors decide
|
|
192
|
+
what to display. Ordinary pending reads/writes still complete and can update local
|
|
193
|
+
state afterward. `store.reset()` clears its own collection's local records and
|
|
194
|
+
load history, so its next load starts fresh. Other stores keep both and can load
|
|
195
|
+
deltas. `clearCache()` remains an explicit global listener/history cleanup for
|
|
196
|
+
tests or deliberate invalidation; do not use it for normal logout.
|
|
197
|
+
|
|
198
|
+
Use one root store per collection. The package does not register stores for automatic
|
|
199
|
+
reset or isolate multiple store instances for the same collection. Entity/model and
|
|
200
|
+
mock registries do not impose a session cleanup policy.
|
|
201
|
+
|
|
202
|
+
## 5. Validate behavior and release adoption
|
|
203
|
+
|
|
204
|
+
Run lint, an Angular production build, data/auth/mock tests, and emulator rule
|
|
205
|
+
tests. Test an account switch while a data read is pending. Exercise initial and
|
|
206
|
+
incremental reads, nested queries, listener navigation/retry, optimistic writes,
|
|
207
|
+
failed batches and Undo. Run platform-tooling against unchanged indexes.
|
|
208
|
+
|
|
209
|
+
Check these intentional behavior corrections while reviewing test expectations:
|
|
210
|
+
|
|
211
|
+
- Missing IDs and empty membership queries no longer select unrelated entities.
|
|
212
|
+
- Aggregation aliases work; empty numeric averages return null.
|
|
213
|
+
- Mock raw data reads can return soft-deleted records for incremental removal.
|
|
214
|
+
- Ordered null values remain queryable; descending and tuple cursors use their
|
|
215
|
+
declared direction. Unknown local operators fail explicitly.
|
|
216
|
+
- Queries are keyed by collection and query without mutating input arrays.
|
|
217
|
+
Components share the same root entity store and matching listeners.
|
|
218
|
+
- Global listener teardown retains records and load history; each store reset
|
|
219
|
+
clears only its collection’s records and timestamps. Pending reads
|
|
220
|
+
and local write compensation retain the existing apps’ completion behavior.
|
|
221
|
+
- Mock batch update of a missing document rejects atomically, like Firestore.
|
|
222
|
+
|
|
223
|
+
Once the alpha is published, replace the local tarball dependency with that
|
|
224
|
+
exact npm version and commit the application's manifest/lockfile plus its
|
|
225
|
+
composition changes. Upgrading platform-data later should normally require only
|
|
226
|
+
a version/lockfile change and validation, unless release notes identify an API
|
|
227
|
+
migration.
|