http-request-manager 22.0.13 → 22.0.14

package/README.md

@@ -262,6 +262,63 @@ Behavior notes:
 - Database disabled: tracker is bypassed; requests call the API directly each time.
 - `forceRefresh: true` always forces an API call.
 
+### Delta Sync (Incremental Fetch)
+
+When `deltaSync: true` is set on `DatabaseStorage`, `HTTPManagerStateService` sends an `X-Modified-Since: <epoch>` header on every fetch after the initial full load. The backend returns only records created or modified at or after the provided timestamp; the store merges them via upsert (IndexedDB `bulkPut` + `mergeDeltaData$` state updater).
+
+**Requirements:**
+
+- `DatabaseStorage` must be configured with a valid `table` name (database storage enabled).
+- `deltaSync: true` must be set on the `DatabaseStorage` config.
+- `expiresIn` controls the TTL for periodic full re-syncs. Set `expiresIn: '0'` to disable TTL expiry entirely — delta sync will run on every call without periodic full re-syncs. Use a non-zero value (e.g., `'1d'`) to periodically clear and re-fetch all data (corrects soft-delete drift).
+
+```typescript
+// Delta sync with no TTL expiry (delta on every call, no periodic full re-sync)
+const service = new HTTPManagerStateService(
+  ApiRequest.adapt({ server: 'https://api.example.com', path: ['api', 'items'] }),
+  DataType.ARRAY,
+  DatabaseStorage.adapt({ table: 'items', expiresIn: '0', deltaSync: true })
+);
+
+// Delta sync with daily full re-sync (delta between cycles, full fetch at TTL boundary)
+const service2 = new HTTPManagerStateService(
+  ApiRequest.adapt({ server: 'https://api.example.com', path: ['api', 'items'] }),
+  DataType.ARRAY,
+  DatabaseStorage.adapt({ table: 'items', expiresIn: '1d', deltaSync: true })
+);
+```
+
+**How it works:**
+
+1. **First call** (no `savedAt`): full fetch, DB populated, `savedAt` written to localStorage as `Date.now()`.
+2. **Subsequent calls** (within TTL): sends `X-Modified-Since: floor(savedAt / 1000)` header. Backend returns only changed/new records.
+   - **Records returned**: upserted to IndexedDB via `bulkPut`, merged into state via `mergeDeltaData$`, `savedAt` updated.
+   - **Empty response `[]`**: state/DB unchanged, `savedAt` updated to current time.
+   - **Error**: state/DB unchanged, `savedAt` NOT updated — next call retries from the same timestamp.
+3. **TTL expiry** (when `expiresIn` is non-zero): `clearTable` runs, full fetch replaces all data, `savedAt` reset.
+4. **`forceRefresh: true`**: full fetch bypasses delta path entirely.
+
+**localStorage updates on DB write:**
+
+When data is pushed to IndexedDB (both full fetch and delta fetch), the localStorage store for the table is updated with:
+- `expires`: refreshed to `utils.expires(expiresIn)` — resets the TTL clock so the next full re-sync is scheduled from the last DB write.
+- `requestCache.GET.savedAt`: set to `Date.now()` — the cursor for the next delta request's `X-Modified-Since` header.
+
+**`DatabaseStorage` properties:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `table` | `string` | `''` | IndexedDB table name (required for delta sync) |
+| `expiresIn` | `string` | `''` | TTL for full re-sync. Use `'0'` to disable (delta sync only, no periodic full re-sync). Examples: `'1m'`, `'1h'`, `'1d'` |
+| `deltaSync` | `boolean` | `false` | Enable incremental fetch with `X-Modified-Since` header |
+
+**Notes:**
+
+- `X-Modified-Since` is added to `volatileHeaders` so it's excluded from request signatures and cache metadata.
+- With `expiresIn: '0'`, TTL never expires — delta sync runs on every call. Use a non-zero value to periodically full re-sync and catch deleted records.
+- The `savedAt` timestamp (used as the `X-Modified-Since` value) is the last time data was successfully written to the DB — it represents the last DB sync time, not the last API call time.
+- Fully backwards compatible — existing consumers see no behavior change unless `deltaSync: true` is set.
+
 ## ⚙️ Configuration
 
 ### Module Initialization (`forRoot`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "http-request-manager",
-  "version": "22.0.13",
+  "version": "22.0.14",
   "homepage": "https://wavecoders.ca",
   "author": "Mike Bonifacio <wavecoders@gmail.com> (http://wavecoders@gmail.com/)",
   "description": "This is an Angular Module containing Components/Services using Material",