@geolonia/geonicdb-sdk 0.2.1 → 0.4.0

package/README.md

@@ -153,7 +153,8 @@ const result = await db.request('GET', '/ngsi-ld/v1/subscriptions');
 db.subscribe({ entityTypes: ['Room'] });
 
 db.on('entityUpdated', (event) => {
-  console.log(`${event.entityId} updated:`, event.data);
+  // event.entity contains the complete NGSI-LD entity ({ id, type, ...attributes })
+  console.log(`${event.entityId} updated:`, event.entity);
 });
 
 db.on('error', (err) => console.error(err));
@@ -175,6 +176,57 @@ await db.connect();
 | `reconnecting` | `{ attempt, delay }` | Auto-reconnect starting |
 | `error` | `Error` | Error occurred |
 | `tokenRefresh` | `RefreshedCredentials` | Bearer token was refreshed |
+| `cacheHit` | `CacheEvent` | Request served from in-memory cache (304 received) |
+| `cacheMiss` | `CacheEvent` | Cache miss — fresh response fetched from origin |
+| `cacheInvalidated` | `CacheEvent` | Cache entry dropped (e.g. after a WebSocket entity event) |
+
+## Client-side Cache & Polling
+
+The SDK includes an in-memory cache that handles `ETag` / `If-None-Match`
+negotiation transparently. Subsequent reads of an unchanged resource are
+served as `304 Not Modified` — the SDK presents them to your code as a normal
+`200` response with the cached body.
+
+```typescript
+// First call: fresh fetch, ETag stored
+const rooms1 = await db.getEntities({ type: 'Room' });
+
+// Second call: server returns 304, SDK returns the cached body
+const rooms2 = await db.getEntities({ type: 'Room' });
+
+// Concurrent calls to the same path are deduplicated:
+const [a, b, c] = await Promise.all([
+  db.getEntities({ type: 'Room' }),
+  db.getEntities({ type: 'Room' }),
+  db.getEntities({ type: 'Room' }),
+]);  // → only one HTTP request hits the network
+```
+
+Cache is enabled by default; pass `cache: false` to opt out.
+
+### Polling
+
+`db.poll(params, options)` repeats `getEntities()` at an interval and reports
+back whether the data actually changed. Internally it leverages the cache's
+ETag negotiation, so unchanged ticks transfer almost no bytes.
+
+```typescript
+const handle = db.poll({ type: 'Room' }, {
+  interval: 5000,
+  onData: (rooms) => render(rooms),
+  onNoChange: () => {},  // server returned 304
+  onError: (err) => console.error(err),
+});
+
+// Stop later
+handle.stop();
+```
+
+### WebSocket-driven cache invalidation
+
+When the SDK receives `entityCreated` / `entityUpdated` / `entityDeleted`
+WebSocket events, it drops affected cache entries automatically. The next
+read re-validates with the server.
 
 ## API Reference
 
@@ -192,6 +244,9 @@ await db.connect();
 | `tenant` | `string` | No | Tenant name (or use `data-tenant` attribute on script tag) |
 | `baseUrl` | `string` | No | API base URL (auto-detected from script `src` if omitted) |
 | `wsEndpoint` | `string` | No | WebSocket endpoint URL (auto-detected from `baseUrl` if omitted) |
+| `debug` | `boolean` | No | Enable debug logging to console (default: `false`) |
+| `cache` | `boolean` | No | Enable in-memory cache with ETag/304 + request dedup (default: `true`) |
+| `cacheMaxEntries` | `number` | No | LRU cache capacity when `cache` is enabled (default: `1000`) |
 
 ### Authentication
 
@@ -276,6 +331,35 @@ await db.connect();
 | `request(method, path, body?)` | `string, string, unknown` | `Promise<unknown>` | Authenticated request with automatic JSON parsing |
 | `requestRaw(method, path, body?)` | `string, string, unknown` | `Promise<Response>` | Authenticated request returning raw `Response` (for accessing headers) |
 
+### Cache & Polling
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `poll(params, options)` | `GetEntitiesParams \| undefined, PollOptions<T>` | `PollHandle` | ETag-based polling — fires `onData` only when the data actually changes. `options` is **required** (`onData` must be specified to receive data) |
+| `clearCache()` | — | `void` | Drop all cached responses |
+
+#### `PollOptions<T>`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `interval` | `number` | Polling interval in milliseconds (default: `5000`) |
+| `onData` | `(data: T) => void` | Called whenever the server returns fresh data (200) |
+| `onNoChange` | `() => void` | Called when the server returns 304 Not Modified |
+| `onError` | `(err: Error) => void` | Called on any fetch/parse failure |
+
+#### `PollHandle`
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `stop()` | — | `void` | Stop the polling timer |
+
+#### `CacheEvent`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `key` | `string` | Cache key (`METHOD:path`) |
+| `path` | `string` | Request path |
+
 ### WebSocket
 
 | Method | Parameters | Returns | Description |
@@ -300,6 +384,39 @@ await db.connect();
 | `on(event, listener)` | `string, Function` | `this` | Register an event listener |
 | `off(event, listener)` | `string, Function` | `this` | Remove an event listener |
 
+## Error Handling
+
+All async methods throw typed errors extending `GeonicDBError`. Use `instanceof` to distinguish error types.
+
+```typescript
+import { GeonicDBError, AuthenticationError, NotFoundError } from '@geolonia/geonicdb-sdk';
+
+try {
+  await db.getEntity('urn:ngsi-ld:Room:404');
+} catch (err) {
+  if (err instanceof AuthenticationError) {
+    // 401 — re-login needed
+  } else if (err instanceof NotFoundError) {
+    // 404 — entity not found
+  } else if (err instanceof GeonicDBError) {
+    console.error(err.message, err.statusCode);
+  } else {
+    console.error(err);
+  }
+}
+```
+
+| Class | Status | Description |
+|-------|--------|-------------|
+| `GeonicDBError` | — | Base class (`statusCode` property) |
+| `AuthenticationError` | 401 | Invalid credentials or expired token |
+| `AuthorizationError` | 403 | Insufficient permissions |
+| `NotFoundError` | 404 | Resource not found |
+| `ConflictError` | 409 | Entity already exists |
+| `ValidationError` | 422 | Bad request payload |
+| `RateLimitError` | 429 | Rate limited (`retryAfter` property) |
+| `NetworkError` | — | Fetch failure, DNS error, timeout |
+
 ## License
 
 MIT