@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:

"@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:

"@recordtimelabel/core": "0.1.2"

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 v2 Preparation

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:

• 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

These helpers do not import Firebase and do not perform network writes.

Test

npm test