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