@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 ADDED
@@ -0,0 +1,161 @@
1
+ # Future database adapters
2
+
3
+ Status: design notes, September 2026. PostgreSQL/Supabase adapters and new
4
+ synchronization protocols are **not implemented**. The current release removes
5
+ Firebase imports from the core and mock entry points, and supplies Firestore
6
+ conversions for the shared timestamp value. Firestore-oriented query semantics,
7
+ batch behavior and the existing client-clock incremental-loading algorithm remain.
8
+
9
+ ## Keep application values separate from database storage
10
+
11
+ `DataTimestamp` represents a finite instant using safe integer Unix epoch seconds,
12
+ nanoseconds from zero through 999,999,999, and the JSON-safe discriminator
13
+ `__type: 'DataTimestamp'`. Factories return frozen plain objects. The marker lets
14
+ adapters distinguish timestamps from ordinary maps without guessing from field
15
+ names, date-like strings, or coincidental seconds/nanoseconds properties.
16
+
17
+ The application shape does not prescribe the database schema. Each adapter
18
+ converts at reads, streams, writes, query operands, cursor values and batch
19
+ boundaries. Native database timestamp columns retain indexing and native
20
+ comparison. Conversion must also cover domain timestamp fields in maps/arrays;
21
+ SQL adapters may need explicit field/schema mappings for those fields.
22
+
23
+ Seconds/nanoseconds preserve milliseconds, microseconds and nanoseconds without
24
+ requiring a single epoch-nanosecond JavaScript number, which cannot precisely
25
+ represent modern instants. The type has no timezone, calendar scheduling,
26
+ duration, date-only or infinity semantics. Those belong in separate domain
27
+ types. Adapter-supported ranges and precision can be narrower than the shared
28
+ value's range and must be validated at the boundary.
29
+
30
+ The explicit marker is a deliberate refinement of a bare seconds/nanoseconds
31
+ interface: JSON persistence and nested domain conversion need a reliable runtime
32
+ distinction. SDK objects, such as Firestore references and sentinels, remain
33
+ adapter-specific. An SDK sentinel's inputs must be converted before constructing
34
+ that opaque object.
35
+
36
+ ## PostgreSQL mapping
37
+
38
+ For creation/update metadata, use `timestamptz`, PostgreSQL's abbreviation for
39
+ `timestamp with time zone`. It represents an instant normalized to UTC; it does
40
+ not retain the original timezone name. Plain `timestamp` means `timestamp without
41
+ time zone` and does not by itself identify a global instant. PostgreSQL supports
42
+ microsecond resolution and precision up to six fractional digits.
43
+ [PostgreSQL date/time types](https://www.postgresql.org/docs/current/datatype-datetime.html)
44
+
45
+ An illustrative schema fragment is:
46
+
47
+ ```sql
48
+ created_at timestamptz(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
49
+ updated_at timestamptz(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
50
+ deleted boolean NOT NULL DEFAULT false
51
+ ```
52
+
53
+ A default handles insertion; an update trigger or controlled backend write path
54
+ must refresh `updated_at` for every mutation, including soft deletion. Preserve
55
+ `created_at` on normal updates. The adapter can map these snake_case columns to
56
+ `_createdAt`, `_updatedAt`, and `_deleted`, and a primary key to `__id`.
57
+
58
+ For example, an API value `1970-01-01T00:00:10.123456Z` maps exactly to
59
+ `dataTimestamp(10, 123456000)`. A typed timestamp filter is encoded as a timestamp
60
+ parameter, for example `WHERE updated_at > $1::timestamptz`; the database performs
61
+ the comparison. Require an explicit timezone/offset in textual interchange and
62
+ normalize it during parsing. Exact PostgreSQL text parsing/formatting is future
63
+ adapter work; the current package does not supply a PostgreSQL codec.
64
+
65
+ Do not pass a microsecond timestamp through JavaScript `Date` before conversion.
66
+ node-postgres normally parses timestamps into `Date`, losing submillisecond
67
+ precision; use a custom type parser or a precision-preserving textual API path.
68
+ [node-postgres type handling](https://node-postgres.com/features/types)
69
+
70
+ ## Precision and authoritative metadata
71
+
72
+ Preserve all precision supplied by a backend on reads. Never infer precision
73
+ from the number of fields in `DataTimestamp`: a millisecond backend produces
74
+ nanoseconds divisible by 1,000,000; a microsecond backend produces values divisible
75
+ by 1,000. Firestore's SDK exposes nanoseconds, but persisted values are rounded
76
+ down to microseconds. Its current adapter returns the actual persisted value on
77
+ subsequent reads. Other adapters should document an explicit rejection or
78
+ normalization policy for writes finer than their native precision.
79
+ [Firestore data types](https://firebase.google.com/docs/firestore/manage-data/data-types)
80
+
81
+ Exact equality/ordering uses the two integer components. Conversions to `Date`
82
+ or floating-point milliseconds are useful for UI display and existing local
83
+ clock calculations, not precision-preserving persistence. Define backend rules
84
+ for timestamp query bounds as well as writes; silently rounding a bound can
85
+ change which records match.
86
+
87
+ Keep timestamp generation distinct from representation. The database should
88
+ generate authoritative metadata, while an optimistic local record can use an
89
+ estimate until the backend acknowledges the write. Future adapters should
90
+ return/stream confirmed values consistently. Timestamp equality alone is not a
91
+ universal record-version test: multiple writes can share a time. An explicit
92
+ revision or change event may be needed where every distinct update matters.
93
+
94
+ ## Incremental synchronization needs its own contract
95
+
96
+ The current store creates a last-load cutoff from the client clock and queries
97
+ `_updatedAt > cutoff`. Replacing the timestamp class does not repair clock skew,
98
+ late commits, equal timestamps, hard deletes, or records leaving a filter.
99
+
100
+ PostgreSQL illustrates the issue: `CURRENT_TIMESTAMP`/`now()` use the transaction
101
+ start time. A transaction can start at 12:00, remain invisible to a reader at
102
+ 12:01, and commit at 12:02. A subsequent cutoff of 12:01 misses that row stamped
103
+ 12:00. `clock_timestamp()` supplies wall time at the call, but is still not a
104
+ commit-order guarantee. This example follows PostgreSQL's documented time and
105
+ transaction-visibility behavior.
106
+ [Time functions](https://www.postgresql.org/docs/current/functions-datetime.html),
107
+ [transaction isolation](https://www.postgresql.org/docs/current/transaction-iso.html)
108
+
109
+ A future adapter contract should let the backend return an opaque synchronization
110
+ cursor alongside changes. The store passes the cursor back without interpreting
111
+ it as time. The backend owns ordering, retention, resumption, tombstones, query
112
+ scope and invalidation. A cursor must correspond to a consistent initial snapshot
113
+ and subsequent committed changes. An arbitrary sequence/auto-increment column
114
+ is not automatically commit ordered; a timestamp-plus-ID pagination tie-breaker
115
+ does not solve late commits either.
116
+
117
+ Investigate a durable change log or change-data-capture mechanism where strong
118
+ incremental guarantees are needed. Where a backend cannot provide those
119
+ guarantees, define an explicit full-reload/reconciliation fallback rather than
120
+ silently treating client time as a safe cursor. Do not invent this protocol until
121
+ there is a concrete second-backend pilot and its consistency requirements.
122
+
123
+ ## Other adapter work beyond timestamps
124
+
125
+ - **Query contract:** map identity, ordering, null/missing semantics, array
126
+ operators, aggregates and pagination. Replace hardcoded 30-ID batch sizing
127
+ with adapter capabilities or move batching into adapters. Unsupported
128
+ operations should fail clearly instead of silently changing meaning.
129
+ - **Realtime query results:** the core expects an initial result and changes to
130
+ result membership. Supabase Postgres Changes emits row INSERT/UPDATE/DELETE
131
+ events. A pilot must establish snapshot/subscription coordination, reconnection,
132
+ deletion handling, and correct filtered/limited query results; refetching may
133
+ be appropriate. [Supabase realtime](https://supabase.com/docs/guides/realtime/postgres-changes)
134
+ - **Atomic writes and Undo:** define backend-neutral operations and transaction
135
+ guarantees. Supabase JavaScript calls cannot simply be grouped into one
136
+ transaction; multi-statement work can use a database function through RPC.
137
+ Undo is a later compensating write, not reversal of a committed transaction.
138
+ [Supabase transaction guidance](https://supabase.com/docs/reference/javascript/using-modifiers-rollback)
139
+ - **App integration:** database schema, data migration, authorization policies,
140
+ auth/account flows and server functions are separate adoption work. A data
141
+ adapter does not migrate a Firebase application by itself.
142
+
143
+ ## Suggested pilot and evidence
144
+
145
+ When a second backend is needed, choose one ordinary entity with creation,
146
+ updates, soft deletion, a timestamp domain field, one filtered live query and
147
+ a batch operation. Keep its Angular domain store unchanged where possible.
148
+ Specify supported behavior before extending `DataAccess`; add only capabilities
149
+ the pilot demonstrates are necessary.
150
+
151
+ Use a shared adapter test suite plus real backend integration tests. Cover
152
+ negative/pre-epoch values, timezone offsets, precision/range limits, fractional
153
+ round-trips through the actual driver/API, server-generated metadata, query
154
+ bounds, updates sharing timestamps, transaction commit races, deletions,
155
+ reconnection, limited-query membership and atomic batch failures. Verify a
156
+ consumer can install/build/use each adapter without unrelated database SDKs.
157
+
158
+ The present implementation stops at the shared value, Firestore conversion,
159
+ mock persistence and Firebase-free core/testing boundaries. No PostgreSQL or
160
+ Supabase packages, database connections, schemas or synchronization cursors are
161
+ introduced by this change.