@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/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.