Local-First Sync Engine

A lightweight, modular JavaScript (ES6+) library for building offline-first applications. Data is persisted locally using IndexedDB and synchronized with a remote server when connectivity is available. Designed for easy integration into web apps and PWAs.

Key Features

• Local persistence via IndexedDB.
• Two-way sync: push (local → server) and pull (server → local).
• Simple conflict resolution: last-write-wins (customizable).
• Full CRUD while offline.
• Modular codebase (store, sync, utils).
• No external dependencies.

Project Layout

• src/index.js — Public API entry.
• src/store.js — IndexedDB store abstraction (CRUD, unsynced tracking).
• src/sync.js — Synchronization (push/pull) logic.
• src/utils.js — Helpers (ID generator, conflict resolver, etc.).
• test/test.js — Simple local test script.
• package.json — Package metadata.

Installation

Install from npm (when published):

npm install local-first-sync-engine

For local development:

git clone <repo-url>
cd local-first-sync-engine
npm install

Quick Start

Example (Node/bundler environment):

const { createStore, syncWithServer } = require('local-first-sync-engine');

(async () => {
  const store = createStore('my-store');

  // Create
  const item = await store.addItem({ title: 'Note 1', body: 'Content' });

  // Update
  await store.updateItem(item.id, { title: 'Note 1 (edited)' });

  // Read
  const all = await store.getItems();
  console.log(all);

  // Sync with server
  await syncWithServer(store, 'https://api.example.com');
})();

Note: In-browser usage requires indexedDB and fetch.

API Reference

• createStore(name)
  Create a LocalStore instance. Returns a store object.

LocalStore instance methods:

• addItem(item) → Promise<{ id, data, lastModified, synced }>
• updateItem(id, updates) → Promise
• deleteItem(id) → Promise
• getItems() → Promise
• getUnsyncedItems() → Promise
• markSynced(id) → Promise

Sync helper:

• syncWithServer(store, serverUrl) → Promise
  Performs push of unsynced local items, then pulls updates from the server.

Server Contract (Example)

Expected endpoints:

• POST {serverUrl}/sync/push
  Body: array of local items to push. Return 200 OK on success.

• GET {serverUrl}/sync/pull
  Response: array of items in server format compatible with local items.

Customize authentication, data mapping, and responses per your server design.

Conflict Resolution

Default strategy: last-write-wins using lastModified timestamps. For complex merging, replace or extend resolveConflict in src/utils.js.

Browser Support & Notes

• Requires modern browser with IndexedDB and Fetch API.
• navigator.onLine used as a connectivity heuristic — consider active ping for reliability.
• For production, consider:
  • Retry/backoff and exponential backoff on failures.
  • Persistent operation queue.
  • Authentication and encryption for data in transit and at rest.

Testing

Run the provided basic test:

npm test

This executes test/test.js to simulate local operations.

Publishing to npm (Quick)

1. Verify package.json (name, version, main, license).
2. Login:

npm login

3. Publish:

npm publish

If the package name is taken, update the name field in package.json.

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit and push changes
4. Open a pull request with a clear description

Please run tests and follow code style conventions.

License

MIT — see LICENSE file.

Support

Open an issue in the repository for bugs, questions, or feature requests.

# Local-First Sync Engine

A lightweight, modular JavaScript (ES6+) library for building offline-first applications. Data is persisted locally using IndexedDB and synchronized with a remote server when connectivity is available. Designed for easy integration into web apps and PWAs.

---

## Key Features
- Local persistence via IndexedDB.
- Two-way sync: push (local → server) and pull (server → local).
- Simple conflict resolution: last-write-wins (customizable).
- Full CRUD while offline.
- Modular codebase (store, sync, utils).
- No external dependencies.

---

## Project Layout
- `src/index.js` — Public API entry.
- `src/store.js` — IndexedDB store abstraction (CRUD, unsynced tracking).
- `src/sync.js` — Synchronization (push/pull) logic.
- `src/utils.js` — Helpers (ID generator, conflict resolver, etc.).
- `test/test.js` — Simple local test script.
- `package.json` — Package metadata.

---

## Installation

Install from npm (when published):
```bash
npm install local-first-sync-engine

For local development:

git clone <repo-url>
cd local-first-sync-engine
npm install

Quick Start

Example (Node/bundler environment):

const { createStore, syncWithServer } = require('local-first-sync-engine');

(async () => {
  const store = createStore('my-store');

  // Create
  const item = await store.addItem({ title: 'Note 1', body: 'Content' });

  // Update
  await store.updateItem(item.id, { title: 'Note 1 (edited)' });

  // Read
  const all = await store.getItems();
  console.log(all);

  // Sync with server
  await syncWithServer(store, 'https://api.example.com');
})();

Note: In-browser usage requires indexedDB and fetch.

API Reference

• createStore(name)
  Create a LocalStore instance. Returns a store object.

LocalStore instance methods:

• addItem(item) → Promise<{ id, data, lastModified, synced }>
• updateItem(id, updates) → Promise
• deleteItem(id) → Promise
• getItems() → Promise
• getUnsyncedItems() → Promise
• markSynced(id) → Promise

Sync helper:

• syncWithServer(store, serverUrl) → Promise
  Performs push of unsynced local items, then pulls updates from the server.

Server Contract (Example)

Expected endpoints:

• POST {serverUrl}/sync/push
  Body: array of local items to push. Return 200 OK on success.

• GET {serverUrl}/sync/pull
  Response: array of items in server format compatible with local items.

Customize authentication, data mapping, and responses per your server design.

Conflict Resolution

Default strategy: last-write-wins using lastModified timestamps. For complex merging, replace or extend resolveConflict in src/utils.js.

Browser Support & Notes

• Requires modern browser with IndexedDB and Fetch API.
• navigator.onLine used as a connectivity heuristic — consider active ping for reliability.
• For production, consider:
  • Retry/backoff and exponential backoff on failures.
  • Persistent operation queue.
  • Authentication and encryption for data in transit and at rest.

Testing

Run the provided basic test:

npm test

This executes test/test.js to simulate local operations.

Publishing to npm (Quick)

1. Verify package.json (name, version, main, license).
2. Login:

npm login

3. Publish:

npm publish

If the package name is taken, update the name field in package.json.

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit and push changes
4. Open a pull request with a clear description

Please run tests and follow code style conventions.

License

MIT — see LICENSE file.

Support

Open an issue in the repository for bugs, questions, or feature requests.