basyx-typescript-sdk 2.2.5 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -32,6 +32,9 @@ Clients for the AAS API components:
32
32
  - AAS Discovery Service
33
33
  - AASX File Service
34
34
 
35
+ All clients support [conditional requests](#conditional-requests-etag) (`ETag`, `If-Match`, `If-None-Match`) for
36
+ optimistic concurrency.
37
+
35
38
  Utility functions for working with AAS data:
36
39
 
37
40
  - Utils for Descriptors
@@ -241,6 +244,57 @@ async function getAllShells() {
241
244
  `Configuration.accessToken` is applied automatically by the runtime. You only need middleware if you want custom auth
242
245
  logic beyond bearer token injection.
243
246
 
247
+ ### Conditional Requests (ETag)
248
+
249
+ Clients report the `ETag` of a response as `etag` and accept the conditional request headers of RFC 9110, so that
250
+ concurrent changes are detected instead of silently overwritten. The entity tag is opaque: pass it back unchanged.
251
+ Servers that send no `ETag` leave `etag` `undefined`.
252
+
253
+ | Option | Methods | Header |
254
+ | ------------- | ---------------------------------------------------------------------- | --------------- |
255
+ | `ifMatch` | `put*`, `patch*`, `delete*`, `post*` below a resource, operation calls | `If-Match` |
256
+ | `ifNoneMatch` | `put*` (use `*` to only create), `get*` of a resource or its parts | `If-None-Match` |
257
+
258
+ ```typescript
259
+ import { Configuration, SubmodelRepositoryClient } from 'basyx-typescript-sdk';
260
+
261
+ const client = new SubmodelRepositoryClient();
262
+ const configuration = new Configuration({ basePath: 'http://localhost:8082' });
263
+ const submodelIdentifier = 'https://example.com/ids/sm/1';
264
+
265
+ const read = await client.getSubmodelById({ configuration, submodelIdentifier });
266
+ if (read.success) {
267
+ const update = await client.patchSubmodelElementByPathValueOnly({
268
+ configuration,
269
+ submodelIdentifier,
270
+ idShortPath: 'Temperature',
271
+ submodelElementValue: '21.5',
272
+ ifMatch: read.etag,
273
+ });
274
+
275
+ if (!update.success && update.preconditionFailed) {
276
+ // 412: the Submodel was changed by someone else. Reload, merge and retry.
277
+ }
278
+ // update.etag is the new entity tag for the next conditional write
279
+ }
280
+
281
+ // Revalidate a cached representation
282
+ const revalidated = await client.getSubmodelById({ configuration, submodelIdentifier, ifNoneMatch: cachedEtag });
283
+ if (revalidated.success && revalidated.notModified) {
284
+ // 304: keep using the cached Submodel
285
+ }
286
+ ```
287
+
288
+ - Failed results have `preconditionFailed: true` for `412 Precondition Failed` and `preconditionRequired: true` for
289
+ `428 Precondition Required` (the server requires `If-Match`).
290
+ - A read returns `{ success: true, notModified: true, statusCode: 304 }` without `data` only if `ifNoneMatch` is passed;
291
+ the result type includes this case only then.
292
+ - `AasService` and `SubmodelService` return the `etag` of the shell or Submodel on reads and accept `ifMatch` for
293
+ `updateAas`, `deleteAas`, `updateSubmodel` and `deleteSubmodel`. The condition applies to the repository; with
294
+ `ifMatch`, deletes remove the repository resource before the registry descriptor and require the repository
295
+ configuration.
296
+ - Calls without these options behave as before.
297
+
244
298
  ### Using the AasService (High-level API)
245
299
 
246
300
  ```typescript