@pixygon/savedata

Unified save data system for Pixygon apps. Server-synced persistence with ownership guard, conflict detection, and multi-provider support.

Install

npm install @pixygon/savedata

Setup

import { SaveProvider } from '@pixygon/savedata'

<SaveProvider config={{
  baseUrl: 'https://api.pixygon.com/v1',
  projectId: '69c3e752b9e4643b1ba67ff8', // MongoDB ObjectId
  getToken: () => accessToken,
  getUserId: () => userId,
  autoSaveInterval: 10_000,              // 10s (default)
}}>
  <App />
</SaveProvider>

Multiple providers can coexist (e.g., global + per-app):

<SaveProvider config={{ projectId: '65481fec93ee5f866ade917f' }}> {/* global */}
  <SaveProvider config={{ projectId: '69c3e752b9e4643b1ba67ff8' }}> {/* per-app */}
    <App />
  </SaveProvider>
</SaveProvider>

Hooks

useSavedata<T>(projectId?)

Full save state and actions.

const { data, isLoaded, syncStatus, revision, updateSection, mergeSection, forceSave, forceLoad } = useSavedata('69c3e752b9e4643b1ba67ff8')

updateSection('fog', { revealedPoints: [...], totalDistanceM: 1234 })

useSavedataSection<T>(key, defaultValue, projectId?)

Convenience hook for a single section.

const { data, update, merge } = useSavedataSection('skills', { skillXp: {}, totalXp: 0 })

update({ skillXp: { explorer: 100 }, totalXp: 100 })

Safety Features

• Ownership guard — blocks saves when userId changes during account switch
• Revision tracking — sends expectedRevision to server, handles 409 Conflict
• Dirty tracking — only saves sections that actually changed
• Merge-on-load — for same-user page reloads, merges local + server (takes max)
• Server-side — enforceOwnership middleware rejects cross-user writes, empty-data guard prevents zeroing