@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/README.md
ADDED
|
@@ -0,0 +1,536 @@
|
|
|
1
|
+
# @tech4good/platform-data
|
|
2
|
+
|
|
3
|
+
Shared data infrastructure for Tech4Good Angular applications. An app keeps its
|
|
4
|
+
own entities and domain stores; this package supplies the reusable store engine,
|
|
5
|
+
Firestore adapter, mock database, listener sharing, incremental loading, and batch
|
|
6
|
+
write orchestration.
|
|
7
|
+
|
|
8
|
+
Initial version: `0.1.0-alpha.0`, under development. This checkout does not publish
|
|
9
|
+
anything automatically. Targets Angular 21, NgRx Signals 21, RxJS 7.8, and Firebase
|
|
10
|
+
12. Use Node.js 22 or later for development.
|
|
11
|
+
|
|
12
|
+
## Documentation
|
|
13
|
+
|
|
14
|
+
- [Changes beyond extraction](EXTRACTION-CHANGES.md): original-code comparison,
|
|
15
|
+
fixes, changed contracts, final logout/reset policy and validation evidence.
|
|
16
|
+
- [Future work and watch points](FUTURE-WORK.md): decisions to preserve, retained
|
|
17
|
+
store risks to monitor, auth/consent package proposals and adoption checks.
|
|
18
|
+
- [Migration guide](MIGRATION.md): update an existing application.
|
|
19
|
+
- [Future backend notes](BACKENDS.md): timestamp and adapter considerations for
|
|
20
|
+
databases beyond Firestore.
|
|
21
|
+
|
|
22
|
+
These guides are included in the built npm package. The two handoff documents
|
|
23
|
+
describe the final initial-extraction decisions; earlier repository planning
|
|
24
|
+
notes also contain superseded designs.
|
|
25
|
+
|
|
26
|
+
## What belongs where
|
|
27
|
+
|
|
28
|
+
| Shared package | App-owned code |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| Structural identity/metadata, query types and selectors | Entity interfaces and relationships |
|
|
31
|
+
| NgRx entity store features and query descriptors | Collection names, domain methods, computed business state |
|
|
32
|
+
| Incremental loads, listener cache and multiplexer | Which data a page loads and when |
|
|
33
|
+
| Data-only Firestore adapter and batch services | Firebase projects, emulator/cache configuration, auth and provisioning |
|
|
34
|
+
| Mock collections, latency/error controls, optional persistence | Mock seeds, user personas and auth mocks |
|
|
35
|
+
| Listener/load-history cleanup and write-feedback integration | Auth-state cleanup, record retention, navigation, analytics, rules and indexes |
|
|
36
|
+
|
|
37
|
+
The package contains no app entity union, auth service, environment file, rules,
|
|
38
|
+
or Firebase initialization. Adding an entity does not require a package release.
|
|
39
|
+
The core and `/testing` have no Firebase dependency. Firebase is an optional peer
|
|
40
|
+
required only when using `/firestore`; Material is likewise optional for `/material`.
|
|
41
|
+
Runtime diagnostics use the separate `@tech4good/platform-logging` peer package,
|
|
42
|
+
which apps install and configure once. Data infrastructure uses its `data` namespace.
|
|
43
|
+
|
|
44
|
+
## Define an app entity and store
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
// In your app: problem.model.ts
|
|
48
|
+
import { DataEntity } from '@tech4good/platform-data';
|
|
49
|
+
|
|
50
|
+
export interface Problem extends DataEntity {
|
|
51
|
+
title: string;
|
|
52
|
+
__collectionId: string;
|
|
53
|
+
difficulty: number;
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
// In your app: problem.store.ts
|
|
59
|
+
import { signalStore, withComputed } from '@ngrx/signals';
|
|
60
|
+
import { computed } from '@angular/core';
|
|
61
|
+
import { withEntitiesAndDBMethods } from '@tech4good/platform-data';
|
|
62
|
+
import { Problem } from './problem.model';
|
|
63
|
+
|
|
64
|
+
export const ProblemStore = signalStore(
|
|
65
|
+
{ providedIn: 'root' },
|
|
66
|
+
withEntitiesAndDBMethods<Problem>('problems'),
|
|
67
|
+
withComputed(store => ({
|
|
68
|
+
difficultProblems: computed(() => store.entities().filter(p => p.difficulty > 3)),
|
|
69
|
+
})),
|
|
70
|
+
);
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`DataEntity` describes a stored record. All four infrastructure fields are required:
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
interface DataEntity {
|
|
77
|
+
__id: string;
|
|
78
|
+
_createdAt: DataTimestamp;
|
|
79
|
+
_updatedAt: DataTimestamp;
|
|
80
|
+
_deleted: boolean;
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`_deleted` supports active/soft-delete queries. `_updatedAt` drives incremental
|
|
85
|
+
loads and nested-stream change detection. `_createdAt` is the creation-time
|
|
86
|
+
convention and supports creation ordering. An app may retain its own `AnyEntity`
|
|
87
|
+
union, but imports shared types/functions directly from the package; local
|
|
88
|
+
`app.store`, listener/cache, and batch forwarding files are not generated.
|
|
89
|
+
|
|
90
|
+
Creation inputs are different from stored records:
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
import { NewDataEntity } from '@tech4good/platform-data';
|
|
94
|
+
|
|
95
|
+
const draft: NewDataEntity<Problem> = {
|
|
96
|
+
title: 'Addition', __collectionId: 'c1', difficulty: 1,
|
|
97
|
+
};
|
|
98
|
+
await problems.add(draft);
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Domain fields are still required. `store.add()` generates an omitted `__id`;
|
|
102
|
+
the adapters stamp metadata, while optimistic local records receive timestamps
|
|
103
|
+
immediately. Direct `data.addEntity()` calls must supply `__id`. An optional
|
|
104
|
+
creation timestamp can be retained when restoring a record; writes always refresh
|
|
105
|
+
`_updatedAt` and adds set `_deleted: false`. `store.init()`, raw mock-store inserts,
|
|
106
|
+
and mock seeds accept complete stored entities, not creation drafts.
|
|
107
|
+
|
|
108
|
+
Firestore uses server timestamps. Pending local snapshots expose estimated
|
|
109
|
+
`DataTimestamp` values until the server confirms them. This does not backfill old
|
|
110
|
+
records: custom writers, imports, Cloud Functions, and existing documents must
|
|
111
|
+
follow the metadata convention. The TypeScript type is not runtime schema validation.
|
|
112
|
+
|
|
113
|
+
## Shared timestamp values
|
|
114
|
+
|
|
115
|
+
Application records use `DataTimestamp`, a finite instant with safe integer epoch
|
|
116
|
+
seconds, integer nanoseconds in `[0, 1_000_000_000)`, and the explicit JSON-safe
|
|
117
|
+
marker `__type: 'DataTimestamp'`. Create values through the package helpers:
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
import {
|
|
121
|
+
DataTimestamp, dataTimestamp, dataTimestampNow, dataTimestampFromDate,
|
|
122
|
+
dataTimestampToDate, compareDataTimestamps, dataTimestampEquals,
|
|
123
|
+
} from '@tech4good/platform-data';
|
|
124
|
+
|
|
125
|
+
const precise: DataTimestamp = dataTimestamp(10, 123456789);
|
|
126
|
+
const estimate = dataTimestampNow();
|
|
127
|
+
const fromForm = dataTimestampFromDate(new Date('2026-09-10T12:00:00Z'));
|
|
128
|
+
const displayDate = dataTimestampToDate(precise);
|
|
129
|
+
const isEarlier = compareDataTimestamps(precise, estimate) < 0;
|
|
130
|
+
const sameInstant = dataTimestampEquals(precise, { ...precise });
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Factories return frozen plain objects. `isDataTimestamp()` validates the marker
|
|
134
|
+
and numeric fields. Nested-stream change detection compares timestamp values
|
|
135
|
+
and other entity fields, so updates sharing a clock tick are still detected.
|
|
136
|
+
The marker is reserved: ordinary `{ seconds, nanoseconds }`
|
|
137
|
+
objects and date-looking strings are not automatically treated as timestamps.
|
|
138
|
+
Negative instants use a negative whole second plus a nonnegative fractional part;
|
|
139
|
+
for example, half a millisecond before the epoch is `dataTimestamp(-1, 999500000)`.
|
|
140
|
+
|
|
141
|
+
`dataTimestampFromMillis()` and `dataTimestampToMillis()` are also available.
|
|
142
|
+
Numbers and `Date` can lose precision; use the seconds/nanoseconds value for exact
|
|
143
|
+
comparisons, query bounds and round-trips. `Date` conversion is for UI display or
|
|
144
|
+
inputs already limited to milliseconds. Date-only and local scheduled times are
|
|
145
|
+
separate domain concepts, not `DataTimestamp` values.
|
|
146
|
+
|
|
147
|
+
The Firestore adapter converts native SDK timestamps to shared values on every
|
|
148
|
+
read/stream and converts shared values back for writes, query operands, cursor
|
|
149
|
+
tuples and batches. Conversion includes nested maps and arrays, so domain fields
|
|
150
|
+
such as `joinedWaitlistAt` also use `DataTimestamp`. SDK references, GeoPoints,
|
|
151
|
+
bytes and write sentinels retain their native representation. When constructing
|
|
152
|
+
an opaque SDK operation such as `arrayUnion()`, convert timestamp operands with
|
|
153
|
+
`toFirestoreTimestamp()` **before** passing them to that SDK operation.
|
|
154
|
+
|
|
155
|
+
Direct SDK integration helpers are exported from `/firestore`:
|
|
156
|
+
`fromFirestoreTimestamp()`, `toFirestoreTimestamp()`, `encodeFirestoreData()` and
|
|
157
|
+
`decodeFirestoreData()`. Firestore keeps its native timestamp storage and server
|
|
158
|
+
metadata; this change does not require rewriting persisted documents. The SDK
|
|
159
|
+
validates its supported date range. Stored Firestore precision is microseconds,
|
|
160
|
+
so persisted reads can contain fewer fractional digits than an input value.
|
|
161
|
+
See [Firestore data types](https://firebase.google.com/docs/firestore/manage-data/data-types).
|
|
162
|
+
|
|
163
|
+
Mock persistence stores the tagged values as JSON and restores them without
|
|
164
|
+
Firebase. Its reader also accepts the previous `__type: 'Timestamp'` mock format.
|
|
165
|
+
Existing external mock seeds must be migrated to shared values.
|
|
166
|
+
|
|
167
|
+
This refactor changes representation, not synchronization guarantees. The current
|
|
168
|
+
client-clock load cutoff, soft-delete behavior and Firestore-oriented query/batch
|
|
169
|
+
semantics remain. Future database adapters and backend-owned synchronization
|
|
170
|
+
cursors are discussed in the repository's
|
|
171
|
+
[backend design notes](BACKENDS.md).
|
|
172
|
+
|
|
173
|
+
## Configure Firestore
|
|
174
|
+
|
|
175
|
+
The app creates its Firebase/AngularFire providers as usual and supplies the
|
|
176
|
+
chosen Firestore instance:
|
|
177
|
+
|
|
178
|
+
```ts
|
|
179
|
+
import { inject } from '@angular/core';
|
|
180
|
+
import { Firestore } from '@angular/fire/firestore';
|
|
181
|
+
import { providePlatformData } from '@tech4good/platform-data';
|
|
182
|
+
import { provideFirestoreData } from '@tech4good/platform-data/firestore';
|
|
183
|
+
import { provideMaterialDataFeedback } from '@tech4good/platform-data/material';
|
|
184
|
+
|
|
185
|
+
const dataProviders = [
|
|
186
|
+
providePlatformData(),
|
|
187
|
+
provideFirestoreData(() => inject(Firestore)),
|
|
188
|
+
provideMaterialDataFeedback(), // optional snackbar feedback and Undo
|
|
189
|
+
];
|
|
190
|
+
// Include dataProviders in appConfig.providers alongside your Firebase providers.
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
`DATA_ACCESS` is the data-only interface. Its legacy name `DATABASE_SERVICE`
|
|
194
|
+
references the exact same injection token. `FirestoreDataService` implements
|
|
195
|
+
reads, streams, count/aggregate, add/update, soft delete, and atomic increment.
|
|
196
|
+
The adapter uses the Firebase SDK with the supplied instance; it does not create
|
|
197
|
+
an auth session or select a Firebase project.
|
|
198
|
+
|
|
199
|
+
For an existing combined data/auth service, preserve an app-owned facade and
|
|
200
|
+
provide that facade under the token; see [migration](MIGRATION.md).
|
|
201
|
+
|
|
202
|
+
## Configure shared logging
|
|
203
|
+
|
|
204
|
+
```ts
|
|
205
|
+
import { providePlatformLogging } from '@tech4good/platform-logging';
|
|
206
|
+
|
|
207
|
+
// In appConfig.providers:
|
|
208
|
+
providePlatformLogging({ enabled: ['data'] });
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
Logging is disabled by default. The logging package owns namespace controls,
|
|
212
|
+
optional persistence/DevTools access and custom output sinks. There is no
|
|
213
|
+
`DataLogger`, `DATA_LOGGER`, or `logger` option on `providePlatformData`.
|
|
214
|
+
Other features use `injectLogger('auth')`, etc. from the same package. See the
|
|
215
|
+
logging package README (`packages/logging/README.md` in this repository) for
|
|
216
|
+
configuration and migration.
|
|
217
|
+
|
|
218
|
+
## Read and write data
|
|
219
|
+
|
|
220
|
+
```ts
|
|
221
|
+
await problems.load([['__collectionId', '==', collectionId]], {});
|
|
222
|
+
const selected = problems.selectEntities([['difficulty', '>=', 3]], {});
|
|
223
|
+
const one = problems.selectEntity(problemId); // Problem | null
|
|
224
|
+
|
|
225
|
+
await problems.add({ __id: db.createId(), title: 'Addition', __collectionId: collectionId, difficulty: 1 });
|
|
226
|
+
await problems.update(problemId, { difficulty: 2 });
|
|
227
|
+
await problems.remove(problemId); // soft delete
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
| API | Behavior |
|
|
231
|
+
| --- | --- |
|
|
232
|
+
| `load(params, options, nestedLoads?, { loading }?)` | Merge fetched entities into the local store; use delta loads when possible |
|
|
233
|
+
| `stream(params, options, injector, nestedStreams?, { loading }?)` | Register realtime updates for the supplied component lifetime |
|
|
234
|
+
| `selectEntity(id)` / `selectFirst(params, options)` | Return a matching active entity or null |
|
|
235
|
+
| `selectEntities(params, options)` | Select active local entities; memoize unchanged result arrays |
|
|
236
|
+
| `count(params, options)` / `aggregate(params, options, spec)` | Query the backend, excluding soft-deleted records |
|
|
237
|
+
| `add`, `update`, `remove`, `increment` | Support loading state and optimistic writes; add/update/remove support batch configuration and feedback |
|
|
238
|
+
| `init(entities)` / `reset()` | Replace initial local contents, or empty this collection’s records and load history |
|
|
239
|
+
|
|
240
|
+
`load()` initially filters `_deleted == false`. Later unconstrained loads can add
|
|
241
|
+
`_updatedAt > lastLoadTime`; it also queries soft-deleted records to remove local
|
|
242
|
+
copies. Single equality/membership queries share per-value timestamps, group by
|
|
243
|
+
five-minute buckets, and split Firestore `in` requests into chunks of 30. A
|
|
244
|
+
single `__id` uses a document read. Queries with ordering/limit/cursors use full
|
|
245
|
+
loads. Keep the corresponding initial and incremental indexes in the app;
|
|
246
|
+
platform-tooling checks those query shapes.
|
|
247
|
+
|
|
248
|
+
`stream()` resolves after registration. Its `loading` flag currently represents
|
|
249
|
+
registration/nested setup, not a guarantee that all first server snapshots have
|
|
250
|
+
arrived. Observe `CachedListenersService.errors$` for asynchronous stream errors
|
|
251
|
+
and offer a retry that calls `stream()` again. Failed listeners are retired so a
|
|
252
|
+
retry can reconnect. Listeners normally remain for a five-second navigation
|
|
253
|
+
grace period; `teardownAllStreams()` closes them immediately while retaining records
|
|
254
|
+
and load history.
|
|
255
|
+
|
|
256
|
+
`EntityLoadQuery` and `EntityStreamQuery` retain the existing descriptor API:
|
|
257
|
+
`new EntityLoadQuery(collection, store, params, options, nestedLoads?)`. Apps can
|
|
258
|
+
keep their named `LoadProblem`/`StreamProblem` subclasses. Conditional nested
|
|
259
|
+
query lists are supported. Equality descriptors combine only when collection,
|
|
260
|
+
store, field, options and downstream callback identity permit it.
|
|
261
|
+
|
|
262
|
+
Query options accept one or more ordering fields and scalar/tuple cursors:
|
|
263
|
+
`{ orderBy: [['difficulty', 'desc'], ['title', 'asc']], startAfter: [3, 'Addition'] }`.
|
|
264
|
+
Undefined filter operands are ignored for compatibility with optional nested
|
|
265
|
+
fields; explicitly check required IDs in app code. Empty `in` selects nothing
|
|
266
|
+
locally; Firestore rejects empty membership queries, so skip those backend calls.
|
|
267
|
+
|
|
268
|
+
Aggregate output names are independent of operators:
|
|
269
|
+
|
|
270
|
+
```ts
|
|
271
|
+
const stats = await problems.aggregate([], {}, {
|
|
272
|
+
total: ['count'],
|
|
273
|
+
difficultySum: ['sum', 'difficulty'],
|
|
274
|
+
difficultyMean: ['average', 'difficulty'],
|
|
275
|
+
});
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
Average can be `null` when there are no numeric values. Count and sum return
|
|
279
|
+
numbers; aggregate result types include null to represent average accurately.
|
|
280
|
+
|
|
281
|
+
## Logout cleanup and retained records
|
|
282
|
+
|
|
283
|
+
Provide one root store per collection. Components share that store's records;
|
|
284
|
+
navigating between pages does not empty it. Component destruction releases its
|
|
285
|
+
listener claims after the navigation grace period.
|
|
286
|
+
|
|
287
|
+
The app explicitly ends database subscriptions before signing out:
|
|
288
|
+
|
|
289
|
+
```ts
|
|
290
|
+
private readonly cachedListeners = inject(CachedListenersService);
|
|
291
|
+
|
|
292
|
+
// Before removing authentication:
|
|
293
|
+
this.cachedListeners.teardownAllStreams();
|
|
294
|
+
this.userStore.reset();
|
|
295
|
+
this.userContextStore.reset();
|
|
296
|
+
// Reset the app's auth/telemetry session state in its logout flow as well.
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
`teardownAllStreams()` closes all active/retiring listeners and nested observers.
|
|
300
|
+
It preserves records and both query/per-entity load timestamps for every collection,
|
|
301
|
+
so subsequent loads can continue incrementally. Streams can reconnect normally.
|
|
302
|
+
|
|
303
|
+
`store.reset()` clears that collection's records and both kinds of load history.
|
|
304
|
+
Its next load starts fresh; other stores keep their records and timestamps.
|
|
305
|
+
`CachedListenersService.clearLoadHistory(collection)` provides the history-only
|
|
306
|
+
operation used internally by `reset()`. `clearCache()` is the explicit global
|
|
307
|
+
operation: it closes all listeners and clears every collection's history while
|
|
308
|
+
retaining records. It is useful in tests, but is not the logout operation.
|
|
309
|
+
|
|
310
|
+
The generated `AuthStore.clearSessionState()` combines this teardown with explicit
|
|
311
|
+
`UserStore`, `UserContextStore`, and telemetry session-ID resets. After sign-out,
|
|
312
|
+
the auth flow sets `afUser` to null and navigates. Only the reset stores lose
|
|
313
|
+
their load history. Other entity records and timestamps remain available, including
|
|
314
|
+
data an app intentionally displays signed out.
|
|
315
|
+
The Firebase auth observer stays subscribed for subsequent auth changes.
|
|
316
|
+
|
|
317
|
+
A store's `reset()` does not delete backend data or stop listeners. Logout stops
|
|
318
|
+
listeners first, then resets auth-related stores. Keeping history cleanup with
|
|
319
|
+
record reset prevents an incremental query from assuming emptied records remain.
|
|
320
|
+
|
|
321
|
+
Ordinary reads and writes already in flight finish normally: they can update local
|
|
322
|
+
records and load timestamps after teardown. This preserves the existing apps'
|
|
323
|
+
behavior; logout is not a guarantee that no further local results can arrive.
|
|
324
|
+
Auth still coordinates its own pending profile provisioning before teardown.
|
|
325
|
+
There is no automatic reset-all registration or support for independent stores
|
|
326
|
+
of the same collection sharing one cache service. Generated entity definitions
|
|
327
|
+
and mock registration are separate from this logout policy.
|
|
328
|
+
|
|
329
|
+
## Mock data and testing
|
|
330
|
+
|
|
331
|
+
```ts
|
|
332
|
+
import { provideMockData } from '@tech4good/platform-data/testing';
|
|
333
|
+
import { dataTimestampNow } from '@tech4good/platform-data';
|
|
334
|
+
|
|
335
|
+
TestBed.configureTestingModule({
|
|
336
|
+
providers: [provideMockData({
|
|
337
|
+
collections: {
|
|
338
|
+
problems: [{ __id: 'p1', title: 'Addition', difficulty: 1, __collectionId: 'c1', _createdAt: dataTimestampNow(), _updatedAt: dataTimestampNow(), _deleted: false }],
|
|
339
|
+
},
|
|
340
|
+
disableLatency: true,
|
|
341
|
+
})],
|
|
342
|
+
});
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
Collection definitions and fixtures belong to the app, with registration generated
|
|
346
|
+
by `@tech4good/platform-tooling` alpha.2 or later. Declare identity in the model:
|
|
347
|
+
|
|
348
|
+
```ts
|
|
349
|
+
import { DataEntity, defineEntity } from '@tech4good/platform-data';
|
|
350
|
+
|
|
351
|
+
export interface Problem extends DataEntity { title: string; }
|
|
352
|
+
export const problemEntity = defineEntity<Problem>({ collection: 'problems' });
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
Use `problemEntity.collection` in `withEntitiesAndDBMethods<Problem>()` and
|
|
356
|
+
`withEntitiesForMockDB<Problem>()`. In `problem.mock.ts`, export the mock wiring:
|
|
357
|
+
|
|
358
|
+
```ts
|
|
359
|
+
import { defineEntityMock } from '@tech4good/platform-data/testing';
|
|
360
|
+
import { problemEntity } from './problem.model';
|
|
361
|
+
|
|
362
|
+
// ProblemMockDB and PROBLEM_DB are defined in this mock file.
|
|
363
|
+
export const problemMock = defineEntityMock(problemEntity, {
|
|
364
|
+
store: ProblemMockDB,
|
|
365
|
+
seeds: PROBLEM_DB, // Or a function returning fresh, typed fixtures.
|
|
366
|
+
});
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
`t4g-entities` generates `APP_ENTITIES`/`AppEntityMap` and `APP_ENTITY_MOCKS` under
|
|
370
|
+
`src/app/core/store`. Consume the latter in an injection context:
|
|
371
|
+
|
|
372
|
+
```ts
|
|
373
|
+
import { createMockRegistry, provideMockData } from '@tech4good/platform-data/testing';
|
|
374
|
+
import { APP_ENTITY_MOCKS } from './core/store/entity-mocks.generated';
|
|
375
|
+
|
|
376
|
+
provideMockData({ collections: () => createMockRegistry(APP_ENTITY_MOCKS) });
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
An app auth facade can instead set `override readonly DB =
|
|
380
|
+
createMockRegistry(APP_ENTITY_MOCKS)`. The registry injects the existing typed
|
|
381
|
+
mock stores, so tests and the database use the same backend instances. Pass
|
|
382
|
+
`MockSeedOverrides<typeof APP_ENTITY_MOCKS>` to `seedMockRegistry` for typed test
|
|
383
|
+
overrides; empty arrays intentionally clear a collection and bypass persisted
|
|
384
|
+
fixtures. Entities without custom mock declarations get empty memory collections.
|
|
385
|
+
|
|
386
|
+
Generated apps keep the manifests in source control, regenerate before
|
|
387
|
+
build/test/lint, and watch model/mock changes during `npm start`. Production uses
|
|
388
|
+
a separate provider module without fixture imports. Definitions require exported
|
|
389
|
+
`const` declarations and literal collection names; mock definitions import their
|
|
390
|
+
entity directly from its relative model file. They are statically discovered,
|
|
391
|
+
not executed by the generator.
|
|
392
|
+
|
|
393
|
+
No handwritten `AnyEntity` union is needed. The shared `DataEntity` contract
|
|
394
|
+
supports infrastructure; concrete stores still check domain fields. If an app
|
|
395
|
+
needs a full union, use `AppEntityMap[keyof AppEntityMap]`.
|
|
396
|
+
|
|
397
|
+
Manual `provideMockData({ collections: { problems: seedArray } })` remains useful
|
|
398
|
+
for small isolated tests. Mock collections simulate the backend; resetting
|
|
399
|
+
frontend stores does not erase their data. See [migration steps](MIGRATION.md).
|
|
400
|
+
|
|
401
|
+
`MockDataService` exposes `GET_LATENCY_SIMULATION_DELAY` (100 ms),
|
|
402
|
+
`PUT_LATENCY_SIMULATION_DELAY` (300 ms), `failCollections`, `stallCollections`, and
|
|
403
|
+
`failWriteCollections`. Read controls cover get, stream, count, and aggregate.
|
|
404
|
+
Change failure lists and issue a new request to test recovery. No mock operation
|
|
405
|
+
connects to Firebase.
|
|
406
|
+
|
|
407
|
+
Persistence is opt-in for `withEntitiesForMockDB` through `MOCK_PERSISTENCE` or
|
|
408
|
+
`provideMockData({ persistence: { enabled: true, keyPrefix: 'my-app-v1-' }, ... })`.
|
|
409
|
+
It is browser-safe, restores timestamps, reports invalid/inaccessible storage
|
|
410
|
+
through the logger, and removes storage listeners on destruction. Plain array
|
|
411
|
+
registrations use memory collections and do not persist.
|
|
412
|
+
|
|
413
|
+
Inject `BATCH_WRITE_SERVICE` and await store operations inside its callback:
|
|
414
|
+
|
|
415
|
+
```ts
|
|
416
|
+
await batches.batchWrite(async batchConfig => {
|
|
417
|
+
await problems.update('p1', { difficulty: 2 }, { batchConfig });
|
|
418
|
+
await problems.remove('p2', { batchConfig });
|
|
419
|
+
}, { optimistic: true });
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
Preparation and commit failures share a rollback boundary. Compensation runs in
|
|
423
|
+
reverse order. Mock batches stage and validate all operations before applying
|
|
424
|
+
changes and reject repeated commits. The mock is not an implementation of
|
|
425
|
+
Firestore transactions, security rules, or composite index planning.
|
|
426
|
+
|
|
427
|
+
## Package verification
|
|
428
|
+
|
|
429
|
+
`npm run test:data` builds the library and runs public API type checks, the shared
|
|
430
|
+
query suite, the load/stream simulations, and targeted regressions for reset, streaming, selectors, batching,
|
|
431
|
+
mock data, and Undo. Run these commands sequentially: the tests temporarily place
|
|
432
|
+
fixtures inside the built package to exercise its actual entry points.
|
|
433
|
+
|
|
434
|
+
`test/simulate-load.spec.ts` covers time-bucketed ID loads.
|
|
435
|
+
`test/simulate-stream.spec.ts` covers overlapping component subscriptions,
|
|
436
|
+
nested streams, repacking, chunking and delayed teardown. Both use the package's
|
|
437
|
+
mock adapter and local `test/simulation.mock.ts` fixtures. These are the package's
|
|
438
|
+
own tests: they stay in this repository, are not emitted into generated apps,
|
|
439
|
+
and are not part of the published `/testing` API. Apps keep their own provider,
|
|
440
|
+
entity, auth and security-rules integration tests.
|
|
441
|
+
|
|
442
|
+
With the Firebase CLI and Java installed, run the separate real-adapter suite:
|
|
443
|
+
|
|
444
|
+
```bash
|
|
445
|
+
firebase emulators:exec --only firestore --project demo-platform-data \
|
|
446
|
+
--config packages/data/test/emulator/firebase.json "npm run test:data:firestore"
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
This uses a local demo project on port 8385. It tests CRUD, server timestamps,
|
|
450
|
+
identity reconstruction, aliased aggregates, cursors, snapshots, and atomic
|
|
451
|
+
batch failure against the SDK and emulator. It refuses a non-local emulator
|
|
452
|
+
address. Its permissive test rules belong only to this test fixture; applications
|
|
453
|
+
continue to own and test their own rules.
|
|
454
|
+
|
|
455
|
+
The emulator does not enforce composite indexes. Run platform-tooling for static
|
|
456
|
+
coverage and validate required indexes against a dedicated development Firestore
|
|
457
|
+
project before rollout. See [Firebase emulator differences](https://firebase.google.com/docs/emulator-suite/connect_firestore#how_the_cloud_firestore_emulator_differs_from_production).
|
|
458
|
+
|
|
459
|
+
## Local development and release
|
|
460
|
+
|
|
461
|
+
From the angular-schematics repository root:
|
|
462
|
+
|
|
463
|
+
```bash
|
|
464
|
+
npm install
|
|
465
|
+
npm run test:data
|
|
466
|
+
npm run pack:logging
|
|
467
|
+
npm run pack:data
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
This builds Angular Package Format output in `packages/data/dist` and creates
|
|
471
|
+
`tech4good-platform-data-0.1.0-alpha.0.tgz` at the repository root. Install that
|
|
472
|
+
actual tarball alongside its logging peer in a disposable branch/copy of a consumer:
|
|
473
|
+
|
|
474
|
+
```bash
|
|
475
|
+
cd /path/to/math-pets
|
|
476
|
+
npm install --save-exact /path/to/angular-schematics/tech4good-platform-logging-0.1.0-alpha.0.tgz /path/to/angular-schematics/tech4good-platform-data-0.1.0-alpha.0.tgz
|
|
477
|
+
npm run lint
|
|
478
|
+
npm run build
|
|
479
|
+
npm test -- --runInBand
|
|
480
|
+
npm run test:rules
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
After a package edit, rebuild/repack and reinstall the new tarball. A tarball is
|
|
484
|
+
a snapshot, not a live link. Keep local tarball paths out of application release
|
|
485
|
+
commits. `npm link` is possible but can introduce duplicate Angular instances;
|
|
486
|
+
tarball testing matches what npm users receive.
|
|
487
|
+
|
|
488
|
+
For a release, choose an unused package version, update the generated dependency
|
|
489
|
+
in `src/ng-add/files/package.json.template`, and record the changes:
|
|
490
|
+
|
|
491
|
+
```bash
|
|
492
|
+
npm version 0.1.0-alpha.1 --workspace @tech4good/platform-data --no-git-tag-version --ignore-scripts
|
|
493
|
+
npm test
|
|
494
|
+
npm run build:data
|
|
495
|
+
npm pack ./packages/data/dist --dry-run
|
|
496
|
+
```
|
|
497
|
+
|
|
498
|
+
Review/commit the release changes. Then publish the **built directory**:
|
|
499
|
+
|
|
500
|
+
```bash
|
|
501
|
+
npm login
|
|
502
|
+
npm publish ./packages/data/dist --access public --tag alpha
|
|
503
|
+
npm view @tech4good/platform-data@0.1.0-alpha.1 version
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
Use `0.1.0-alpha.0` for the first publication; the bump above illustrates the next
|
|
507
|
+
iteration. Each publication needs an unused version. Publish the required
|
|
508
|
+
platform-logging version first, then data before any
|
|
509
|
+
schematics release that references it. Consumers can install the exact alpha
|
|
510
|
+
with `npm install --save-exact @tech4good/platform-logging@0.1.0-alpha.0 @tech4good/platform-data@0.1.0-alpha.0`.
|
|
511
|
+
|
|
512
|
+
The source workspace is not the publishable artifact. Unlike platform-tooling,
|
|
513
|
+
this Angular library must be built before publishing `packages/data/dist`.
|
|
514
|
+
A `prepublishOnly` guard rejects accidental publication of the source workspace.
|
|
515
|
+
|
|
516
|
+
## Constraints and review
|
|
517
|
+
|
|
518
|
+
- Local selectors cover the scalar, timestamp, array, dotted-field, ordering,
|
|
519
|
+
and cursor cases used by these apps. They do not reproduce Firestore's complete
|
|
520
|
+
heterogeneous type ordering or document-snapshot cursor semantics. Use the
|
|
521
|
+
emulator to verify backend behavior and rules; composite indexes require
|
|
522
|
+
separate static checks and a development Firestore project.
|
|
523
|
+
- Incremental loads rely on client-clock cutoffs and server `_updatedAt` values.
|
|
524
|
+
Clock skew, hard deletes, and records leaving a filtered range can leave stale
|
|
525
|
+
cached data until reset/full refresh. Realtime streams or explicit reset/full
|
|
526
|
+
loads are appropriate where strict freshness is required.
|
|
527
|
+
- Limited realtime query removals can mean leaving a result window, not deletion.
|
|
528
|
+
The shared store retains the existing change-classification convention; use
|
|
529
|
+
app query selectors instead of treating the entire entity cache as one page.
|
|
530
|
+
- Serialize optimistic mutations to the same entity when rollback/undo matters;
|
|
531
|
+
this initial API is not an optimistic transaction/conflict-resolution engine.
|
|
532
|
+
|
|
533
|
+
See [migration](MIGRATION.md) and the repository's
|
|
534
|
+
[review and extraction plan](../../docs-plans/platform-data-extraction.md) for the
|
|
535
|
+
boundary, defect review, and acceptance work. The library is not production
|
|
536
|
+
validated until the recorded consumer and emulator checks pass.
|