basyx-typescript-sdk 2.3.0 → 2.4.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.
Files changed (62) hide show
  1. package/README.md +68 -1
  2. package/bundle/index.cjs +1421 -91
  3. package/bundle/index.cjs.map +1 -1
  4. package/bundle/index.mjs +1353 -92
  5. package/bundle/index.mjs.map +1 -1
  6. package/dist/clients/AasRegistryClient.d.ts +20 -0
  7. package/dist/clients/AasRegistryClient.js +40 -0
  8. package/dist/clients/AasRepositoryClient.d.ts +20 -0
  9. package/dist/clients/AasRepositoryClient.js +40 -0
  10. package/dist/clients/ConceptDescriptionRepositoryClient.d.ts +20 -0
  11. package/dist/clients/ConceptDescriptionRepositoryClient.js +40 -0
  12. package/dist/clients/SubmodelRegistryClient.d.ts +20 -0
  13. package/dist/clients/SubmodelRegistryClient.js +40 -0
  14. package/dist/clients/SubmodelRepositoryClient.d.ts +20 -0
  15. package/dist/clients/SubmodelRepositoryClient.js +40 -0
  16. package/dist/generated/AasRegistryService/apis/AssetAdministrationShellRegistryAPIApi.d.ts +14 -1
  17. package/dist/generated/AasRegistryService/apis/AssetAdministrationShellRegistryAPIApi.js +29 -0
  18. package/dist/generated/AasRegistryService/models/index.d.ts +374 -0
  19. package/dist/generated/AasRegistryService/models/index.js +6 -0
  20. package/dist/generated/AasRepositoryService/apis/AssetAdministrationShellRepositoryAPIApi.d.ts +14 -1
  21. package/dist/generated/AasRepositoryService/apis/AssetAdministrationShellRepositoryAPIApi.js +29 -0
  22. package/dist/generated/AasRepositoryService/models/index.d.ts +381 -0
  23. package/dist/generated/AasRepositoryService/models/index.js +7 -0
  24. package/dist/generated/ConceptDescriptionRepositoryService/apis/ConceptDescriptionRepositoryAPIApi.d.ts +14 -1
  25. package/dist/generated/ConceptDescriptionRepositoryService/apis/ConceptDescriptionRepositoryAPIApi.js +29 -0
  26. package/dist/generated/ConceptDescriptionRepositoryService/models/index.d.ts +381 -0
  27. package/dist/generated/ConceptDescriptionRepositoryService/models/index.js +7 -0
  28. package/dist/generated/SubmodelRegistryService/apis/SubmodelRegistryAPIApi.d.ts +14 -1
  29. package/dist/generated/SubmodelRegistryService/apis/SubmodelRegistryAPIApi.js +29 -0
  30. package/dist/generated/SubmodelRegistryService/models/index.d.ts +381 -0
  31. package/dist/generated/SubmodelRegistryService/models/index.js +7 -0
  32. package/dist/generated/SubmodelRepositoryService/apis/SubmodelRepositoryAPIApi.d.ts +14 -1
  33. package/dist/generated/SubmodelRepositoryService/apis/SubmodelRepositoryAPIApi.js +29 -0
  34. package/dist/generated/SubmodelRepositoryService/models/index.d.ts +381 -0
  35. package/dist/generated/SubmodelRepositoryService/models/index.js +7 -0
  36. package/dist/lib/endpointConfiguration.d.ts +71 -0
  37. package/dist/lib/endpointConfiguration.js +101 -0
  38. package/dist/lib/errorHandler.js +9 -4
  39. package/dist/lib/index.d.ts +1 -0
  40. package/dist/lib/index.js +2 -0
  41. package/dist/lib/queryJsonization.d.ts +17 -0
  42. package/dist/lib/queryJsonization.js +309 -0
  43. package/dist/lib/queryRequests.d.ts +24 -0
  44. package/dist/lib/queryRequests.js +44 -0
  45. package/dist/models/Query.d.ts +378 -0
  46. package/dist/models/Query.js +430 -0
  47. package/dist/models/QueryResult.d.ts +22 -0
  48. package/dist/models/QueryResult.js +1 -0
  49. package/dist/models/index.d.ts +2 -0
  50. package/dist/models/index.js +2 -0
  51. package/dist/services/AasService.d.ts +15 -4
  52. package/dist/services/AasService.js +38 -40
  53. package/dist/services/SubmodelService.d.ts +9 -8
  54. package/dist/services/SubmodelService.js +17 -34
  55. package/dist/services/index.d.ts +1 -0
  56. package/dist/utils/DescriptorUtils.d.ts +27 -1
  57. package/dist/utils/DescriptorUtils.js +65 -27
  58. package/dist/utils/ServiceDescriptionUtils.d.ts +30 -0
  59. package/dist/utils/ServiceDescriptionUtils.js +43 -0
  60. package/dist/utils/index.d.ts +2 -0
  61. package/dist/utils/index.js +2 -0
  62. package/package.json +1 -1
package/README.md CHANGED
@@ -33,7 +33,8 @@ Clients for the AAS API components:
33
33
  - AASX File Service
34
34
 
35
35
  All clients support [conditional requests](#conditional-requests-etag) (`ETag`, `If-Match`, `If-None-Match`) for
36
- optimistic concurrency.
36
+ optimistic concurrency. The repository and registry clients support server-side search with the
37
+ [AAS Query Language](#querying-with-the-aas-query-language).
37
38
 
38
39
  Utility functions for working with AAS data:
39
40
 
@@ -43,6 +44,7 @@ Utility functions for working with AAS data:
43
44
  - Utils for Referables
44
45
  - Utils for References
45
46
  - Utils for SemanticIds
47
+ - Utils for ServiceDescriptions (query support)
46
48
 
47
49
  ## Installation
48
50
 
@@ -295,6 +297,71 @@ if (revalidated.success && revalidated.notModified) {
295
297
  configuration.
296
298
  - Calls without these options behave as before.
297
299
 
300
+ ### Querying with the AAS Query Language
301
+
302
+ The repository and registry clients search on the server with the AAS Query Language (IDTA-01002-3):
303
+
304
+ | Client | Method | Endpoint |
305
+ | ------------------------------------ | ------------------------------------------ | ---------------------------------- |
306
+ | `AasRepositoryClient` | `queryAssetAdministrationShells` | `POST /query/shells` |
307
+ | `SubmodelRepositoryClient` | `querySubmodels` | `POST /query/submodels` |
308
+ | `ConceptDescriptionRepositoryClient` | `queryConceptDescriptions` | `POST /query/concept-descriptions` |
309
+ | `AasRegistryClient` | `queryAssetAdministrationShellDescriptors` | `POST /query/shell-descriptors` |
310
+ | `SubmodelRegistryClient` | `querySubmodelDescriptors` | `POST /query/submodel-descriptors` |
311
+
312
+ Queries are built from the classes of the query model. Their names follow the V3.2 meta-model of
313
+ [aas-core-meta](https://github.com/aas-core-works/aas-core-meta), and the clients serialize them to the JSON of the
314
+ query language (e.g. `StringLiteral` becomes `{ "$strVal": ... }`).
315
+
316
+ ```typescript
317
+ import {
318
+ AasRepositoryClient,
319
+ Configuration,
320
+ ContainsComparison,
321
+ EqualComparison,
322
+ FieldOperand,
323
+ OrExpression,
324
+ Query,
325
+ StringLiteral,
326
+ } from 'basyx-typescript-sdk';
327
+
328
+ const client = new AasRepositoryClient();
329
+ const configuration = new Configuration({ basePath: 'http://localhost:8081' });
330
+
331
+ // $aas#idShort == "Robot" or $aas#id contains "robot"
332
+ const query = new Query(
333
+ new OrExpression([
334
+ new EqualComparison([new FieldOperand('$aas#idShort'), new StringLiteral('Robot')]),
335
+ new ContainsComparison([new FieldOperand('$aas#id'), new StringLiteral('robot')]),
336
+ ])
337
+ );
338
+
339
+ let cursor: string | undefined;
340
+ do {
341
+ const response = await client.queryAssetAdministrationShells({ configuration, query, limit: 50, cursor });
342
+ if (!response.success) {
343
+ // 400 for an invalid query, with the server's messages in response.error.messages
344
+ break;
345
+ }
346
+ if (response.data.resultType === 'AssetAdministrationShell') {
347
+ console.log(response.data.result.map((shell) => shell.idShort));
348
+ }
349
+ cursor = response.data.pagedResult?.cursor;
350
+ } while (cursor);
351
+ ```
352
+
353
+ - `data.resultType` is the type of the returned objects, e.g. `'AssetAdministrationShell'`, with `result` holding the
354
+ deserialized aas-core instances or descriptors. With `new Query(condition, QuerySelect.Id)` it is `'Identifier'` and
355
+ `result` holds the identifiers (`string[]`).
356
+ - `filters` (`$filters`) restrict fragments of the returned objects:
357
+ `new Query(condition, null, [new QueryFilter('$sm#supplementalSemanticIds[]', fragmentCondition)])`.
358
+ - `queryFromJsonable` parses query JSON (e.g. from a query editor) into the query model and reports the path to an
359
+ invalid value; `toJsonableQuery` serializes a query.
360
+ - `supportsQuery(serviceDescription, 'shells')` and `getQueryEndpoints(serviceDescription)` read the query profiles from
361
+ the result of `getSelfDescription`. Profiles are matched regardless of host and API version
362
+ (`https://admin-shell.io/aas/API/3/2/...`, `https://basyx.org/aas/API/3/2/...`). This is a hint only: a server can
363
+ serve query endpoints without advertising their profile.
364
+
298
365
  ### Using the AasService (High-level API)
299
366
 
300
367
  ```typescript