@recordtimelabel/core 0.1.0 → 0.1.2

package/README.md

@@ -1,55 +1,87 @@
-# @recordtimelabel/core
-
-Shared RecordTimeLabel data model, normalization, merge logic, operation reducer, and sync engine.
-
-## Scope
-
-This package is intentionally platform-neutral. It must not import React, Firebase, Chrome extension APIs, Electron APIs, or app-specific UI code.
-
-Current consumers:
-
-- `D:\Programming\RecordTimeLabel`
-- `D:\Programming\YouTwitchDownloader`
-
-During local development both apps consume it with:
+# @recordtimelabel/core
+
+Shared RecordTimeLabel data model, normalization, merge logic, operation reducer, and sync engine.
+
+## Scope
+
+This package is intentionally platform-neutral. It must not import React, Firebase, Chrome extension APIs, Electron APIs, or app-specific UI code.
+
+Current consumers:
+
+- `D:\Programming\RecordTimeLabel`
+- `D:\Programming\YouTwitchDownloader`
+
+During local development an app can consume a sibling checkout with:
+
+```json
+"@recordtimelabel/core": "file:../recordtimelabel-core"
+```
+
+For release builds, consume a fixed npm package, git tag, or private registry version so builds do not depend on a sibling folder path. The current release candidate is:
 
 ```json
-"@recordtimelabel/core": "file:../recordtimelabel-core"
+"@recordtimelabel/core": "0.1.2"
 ```
-
-For release builds, move this dependency to a git tag, npm package, or private registry version so builds do not depend on a sibling folder path.
-
-## Public API
-
-- `normalizeState(input)`
-- `normalizeRecords(records, options)`
+
+## Public API
+
+- `normalizeState(input)`
+- `normalizeRecords(records, options)`
 - `mergeLocalRemote({ localState, remoteState, pendingOps, clientId, now })`
 - `applyOperation(state, operation)`
+- `applyRecordTimeLabelOperation(state, operation)`
 - `createSyncEngine({ storageAdapter, cloudAdapter, clientId, clock, logger })`
+- `createRecordTimeLabelController({ storageAdapter, cloudAdapter, clientId, settingKeys, clock, logger })`
+- `buildRecordTimeLabelSyncPayload({ data, previousCloudData, pendingOps, syncMode, clientId, now })`
+- `buildSyncPayloadWithOperations({ data, previousCloudData, pendingOps, syncMode, clientId, now })`
+- `flushPendingOperations({ operations, storageAdapter, cloudAdapter, clientId, now })`
+- `mergeRemoteStateIntoLocal({ localData, remoteData, pendingOps, settingKeys, clientId, now })`
+- `buildLocalStateFromStorage(data, options)`
+- `buildStoragePatchFromState(state, options)`
+- `buildFirestoreV1UserPatch(state, options)`
+- `buildFirestoreV2LogicalPaths(userId)`
+- `buildFirestoreV2DocumentsFromState(state, options)`
+- `buildStateFromFirestoreV2Documents(documents, options)`
+- `hasMeaningfulRecordTimeLabelCloudState(data, options)`
+- `buildRecordTimeLabelContentFingerprint(data)`
+- `buildMigratedRecordTimeLabelV2State(legacyState, options)`
+- `RECORD_TIMELABEL_CLOUD_SCHEMAS`
+- `RECORD_TIMELABEL_SYNC_MODES`
 - `createOperation(type, payload, options)`
 - `OPERATION_TYPES`
+
+## Firestore v1 Compatibility
+
+Phase 1 keeps the existing `users/{uid}` document shape:
+
+- `folders`
+- `records`
+- `groupOrder`
+- `folderOrder`
+- `expandedGroups`
+- `settings`
+
+The core also normalizes and preserves these compatibility metadata fields:
+
+- `rtlSyncMeta`
+- `deletedRecordTombstones`
+- `deletedFolderTombstones`
+
+Deletion must be represented by tombstones or operations. Do not reintroduce the old heuristic that treats "local exists but cloud missing for more than five minutes" as deletion.
 
-## Firestore v1 Compatibility
-
-Phase 1 keeps the existing `users/{uid}` document shape:
-
-- `folders`
-- `records`
-- `groupOrder`
-- `folderOrder`
-- `expandedGroups`
-- `settings`
-
-The core also normalizes and preserves these compatibility metadata fields:
-
-- `rtlSyncMeta`
-- `deletedRecordTombstones`
-- `deletedFolderTombstones`
+## Firestore v2 Preparation
 
-Deletion must be represented by tombstones or operations. Do not reintroduce the old heuristic that treats "local exists but cloud missing for more than five minutes" as deletion.
+The package exposes platform-neutral v2 document helpers so app adapters can share the same record/folder/settings/ops shape before wiring Firebase SDK or REST calls:
 
-## Test
+- root document `users/{uid}/recordTimeLabel/main`: settings, order arrays, tombstones, and sync metadata
+- `users/{uid}/recordTimeLabel/main/records/{recordId}`: flattened per-record documents with `folderId`
+- `users/{uid}/recordTimeLabel/main/folders/{folderId}`: per-folder documents
+- `users/{uid}/recordTimeLabel/main/ops/{opId}`: pending operation documents
 
-```bash
-npm test
-```
+These helpers do not import Firebase and do not perform network writes.
+
+## Test
+
+```bash
+npm test
+```

package/package.json

@@ -1,20 +1,20 @@
-{
-  "name": "@recordtimelabel/core",
-  "version": "0.1.0",
-  "type": "module",
-  "description": "Shared RecordTimeLabel data model, merge logic, operations, and sync engine.",
-  "main": "./src/index.js",
-  "exports": {
-    ".": "./src/index.js"
-  },
-  "scripts": {
-    "test": "node --test tests/*.test.mjs"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "files": [
-    "src",
-    "README.md"
-  ]
-}
+{
+  "name": "@recordtimelabel/core",
+  "version": "0.1.2",
+  "type": "module",
+  "description": "Shared RecordTimeLabel data model, merge logic, operations, and sync engine.",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ]
+}