{"id":26180301,"url":"https://github.com/eclipse-basyx/basyx-typescript-sdk","last_synced_at":"2026-04-09T22:24:00.096Z","repository":{"id":272947707,"uuid":"917563943","full_name":"eclipse-basyx/basyx-typescript-sdk","owner":"eclipse-basyx","description":"BaSyx TypeScript SDK for developing applications and components for the Asset Administration Shell (AAS)","archived":false,"fork":false,"pushed_at":"2026-02-18T10:34:01.000Z","size":2475,"stargazers_count":7,"open_issues_count":1,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-02-18T15:29:24.143Z","etag":null,"topics":["aas","assetadministrationshell","basyx","client","utils"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eclipse-basyx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-16T08:22:58.000Z","updated_at":"2026-02-18T10:33:19.000Z","dependencies_parsed_at":"2026-01-05T04:00:31.946Z","dependency_job_id":null,"html_url":"https://github.com/eclipse-basyx/basyx-typescript-sdk","commit_stats":null,"previous_names":["eclipse-basyx/basyx-typescript-sdk"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/eclipse-basyx/basyx-typescript-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-basyx%2Fbasyx-typescript-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-basyx%2Fbasyx-typescript-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-basyx%2Fbasyx-typescript-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-basyx%2Fbasyx-typescript-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eclipse-basyx","download_url":"https://codeload.github.com/eclipse-basyx/basyx-typescript-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-basyx%2Fbasyx-typescript-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30154269,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T22:39:40.138Z","status":"ssl_error","status_checked_at":"2026-03-05T22:39:24.771Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aas","assetadministrationshell","basyx","client","utils"],"created_at":"2025-03-11T21:55:18.099Z","updated_at":"2026-04-09T22:24:00.078Z","avatar_url":"https://github.com/eclipse-basyx.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/eclipse-basyx/basyx-typescript-sdk/build-sdk.yml)\n![NPM Downloads](https://img.shields.io/npm/dw/basyx-typescript-sdk)\n[![NPM Version](https://img.shields.io/npm/v/basyx-typescript-sdk)](https://www.npmjs.com/package/basyx-typescript-sdk)\n![GitHub License](https://img.shields.io/github/license/eclipse-basyx/basyx-typescript-sdk)\n\n# basyx-typescript-sdk\n\nBaSyx TypeScript SDK for developing applications and components for the Asset Administration Shell (AAS)\n\n## Features\n\nHigh-level orchestration services:\n\n- **AasService**: Unified API for AAS operations across registry and repository\n  - Create, read, update, delete AAS with automatic registry synchronization\n  - Fetch AAS with their submodels in a single call\n  - Automatic endpoint resolution and fallback handling\n- **SubmodelService**: Unified API for Submodel operations across registry and repository\n  - Create, read, update, delete Submodels with automatic registry synchronization\n  - Flexible endpoint-based retrieval\n  - Automatic fallback to repository when registry unavailable\n\nClients for the AAS API components:\n\n- AAS Repository\n- Submodel Repository\n- Concept Description Repository\n- AAS Registry\n- Submodel Registry\n- AAS Discovery Service\n- AASX File Service\n\nUtility functions for working with AAS data:\n\n- Utils for Descriptors\n- Utils for KeyTypes\n- Utils for MultiLanguageProperties\n- Utils for Referables\n- Utils for References\n- Utils for SemanticIds\n\n## Installation\n\n```bash\nnpm install basyx-typescript-sdk\n# or\npnpm add basyx-typescript-sdk\n```\n\n\u003e See https://www.npmjs.com/package/basyx-typescript-sdk\n\n---\n\n\u003e [!IMPORTANT] Make sure to also install `@aas-core-works/aas-core3.1-typescript` in your project:\n\n```bash\nnpm install @aas-core-works/aas-core3.1-typescript\n# or\npnpm add @aas-core-works/aas-core3.1-typescript\n```\n\n## Development\n\n```bash\npnpm install\npnpm format:check\npnpm lint:check\npnpm type-check\npnpm build\npnpm bundle\npnpm test\npnpm verify:compat\n```\n\nUse `.nvmrc` to align local Node.js with CI:\n\n```bash\nnvm use\n```\n\n## Import Styles\n\nThe SDK supports multiple import styles for flexibility:\n\n### Direct Imports (Recommended for most use cases)\n\n```typescript\n// Import clients directly\nimport { AasRepositoryClient, AasRegistryClient, Configuration } from 'basyx-typescript-sdk';\n\n// Import services directly\nimport { AasService } from 'basyx-typescript-sdk';\n\n// Import utility functions directly\nimport { extractEndpointHref, getSubmodelElementByIdShort } from 'basyx-typescript-sdk';\n\n// Import library functions directly\nimport { base64Encode, base64Decode } from 'basyx-typescript-sdk';\n```\n\n### Namespaced Imports (For organized code)\n\n```typescript\n// Import utilities as namespace\nimport { Utils, Lib } from 'basyx-typescript-sdk';\n\n// Use with namespace\nconst endpoint = Utils.extractEndpointHref(descriptor, 'AAS-3.0');\nconst encoded = Lib.base64Encode('my-id');\n```\n\n### Mixed Style\n\n```typescript\n// Combine direct and namespaced imports\nimport { AasService, Configuration, Utils, base64Encode } from 'basyx-typescript-sdk';\n\n// Use directly imported functions\nconst id = base64Encode('my-id');\n\n// Use namespaced utilities\nconst element = Utils.getSubmodelElementByIdShort(submodel, 'myElement');\n```\n\n## Usage Examples\n\n### Basic Client Usage\n\n```typescript\nimport { AasRepositoryClient, Configuration } from 'basyx-typescript-sdk';\n\nasync function getAllShells() {\n  const client = new AasRepositoryClient();\n  const configuration = new Configuration({\n    basePath: 'http://localhost:8081',\n  });\n\n  const response = await client.getAllAssetAdministrationShells({ configuration });\n\n  if (response.success) {\n    console.log('Shells:', response.data.result);\n  } else {\n    console.error('Error:', response.error);\n  }\n}\n```\n\n### Using the AasService (High-level API)\n\n```typescript\nimport { AasService, Configuration } from 'basyx-typescript-sdk';\nimport { AssetAdministrationShell, AssetInformation, AssetKind } from '@aas-core-works/aas-core3.1-typescript/types';\n\n// Initialize service with both registry and repository\nconst service = new AasService({\n  registryConfig: new Configuration({ basePath: 'http://localhost:8084' }),\n  repositoryConfig: new Configuration({ basePath: 'http://localhost:8081' }),\n  // Optional: Separate configs for submodel services (used when includeSubmodels is enabled)\n  // If not provided, falls back to using registryConfig/repositoryConfig for submodels\n  // In typical BaSyx deployments, submodel services run on different ports:\n  submodelRegistryConfig: new Configuration({ basePath: 'http://localhost:8083' }),\n  submodelRepositoryConfig: new Configuration({ basePath: 'http://localhost:8081' }),\n  // Optional: Discovery service config (used for asset ID lookups)\n  discoveryConfig: new Configuration({ basePath: 'http://localhost:8086' }),\n});\n\n// Create a new AAS (automatically registers in registry)\nconst shell = new AssetAdministrationShell(\n  'https://example.com/ids/aas/my-aas',\n  new AssetInformation(AssetKind.Instance)\n);\n\nconst createResult = await service.createAas({ shell });\nif (createResult.success) {\n  console.log('Created AAS:', createResult.data.shell);\n}\n\n// Get AAS list from registry with automatic endpoint resolution\nconst listResult = await service.getAasList();\nif (listResult.success) {\n  console.log('All shells:', listResult.data.shells);\n}\n\n// Get AAS by ID (uses registry endpoint if available)\nconst getResult = await service.getAasById({\n  aasIdentifier: 'https://example.com/ids/aas/my-aas',\n});\n\n// Get AAS with its submodels in a single call\nconst withSubmodels = await service.getAasById({\n  aasIdentifier: 'https://example.com/ids/aas/my-aas',\n  includeSubmodels: true,\n});\nif (withSubmodels.success) {\n  console.log('Shell:', withSubmodels.data.shell);\n  console.log('Submodels:', withSubmodels.data.submodels); // Array of submodels\n}\n\n// Get all AAS with their submodels\nconst allWithSubmodels = await service.getAasList({ includeSubmodels: true });\nif (allWithSubmodels.success) {\n  allWithSubmodels.data.shells.forEach((shell, index) =\u003e {\n    console.log(`Shell ${index}:`, shell.id);\n    console.log(`Submodels:`, allWithSubmodels.data.submodels?.[shell.id]);\n  });\n}\n\n// Update AAS (updates both repository and registry)\nshell.idShort = 'UpdatedName';\nconst updateResult = await service.updateAas({ shell });\n\n// Get endpoint for an AAS\nconst endpointResult = await service.getAasEndpointById({\n  aasIdentifier: 'https://example.com/ids/aas/my-aas',\n});\n\n// Get AAS directly by endpoint URL\nconst byEndpointResult = await service.getAasByEndpoint({\n  endpoint: 'http://localhost:8081/shells/encoded-id',\n});\n\n// Delete AAS (removes from both registry and repository)\nawait service.deleteAas({\n  aasIdentifier: 'https://example.com/ids/aas/my-aas',\n});\n\n// Find AAS by asset IDs using discovery service\nconst assetIds = [\n  { name: 'serialNumber', value: '12345' },\n  { name: 'deviceId', value: 'device-001' },\n];\n\nconst byAssetIdResult = await service.getAasByAssetId({\n  assetIds,\n  includeSubmodels: true, // Optionally include submodels\n});\nif (byAssetIdResult.success) {\n  console.log('Found AAS IDs:', byAssetIdResult.data.aasIds);\n  console.log('Found shells:', byAssetIdResult.data.shells);\n  // If multiple AAS match the asset IDs, all are returned\n}\n\n// Fetch AAS with submodels and their concept descriptions\nconst serviceWithCD = new AasService({\n  registryConfig: new Configuration({ basePath: 'http://localhost:8084' }),\n  repositoryConfig: new Configuration({ basePath: 'http://localhost:8081' }),\n  submodelRegistryConfig: new Configuration({ basePath: 'http://localhost:8085' }),\n  submodelRepositoryConfig: new Configuration({ basePath: 'http://localhost:8082' }),\n  conceptDescriptionRepositoryConfig: new Configuration({ basePath: 'http://localhost:8083' }),\n});\n\nconst withConceptDescriptions = await serviceWithCD.getAasById({\n  aasIdentifier: 'https://example.com/ids/aas/my-aas',\n  includeSubmodels: true,\n  includeConceptDescriptions: true,\n});\nif (withConceptDescriptions.success) {\n  console.log('Shell:', withConceptDescriptions.data.shell);\n  console.log('Submodels with CDs:', withConceptDescriptions.data.submodels);\n  // Concept descriptions are fetched for all semantic IDs in submodels and their elements\n}\n\n// Resolve a Reference to get endpoints for AAS, Submodel, or SubmodelElement\nimport { Reference, Key, KeyTypes, ReferenceTypes } from '@aas-core-works/aas-core3.1-typescript/types';\n\n// Example 1: Reference to AAS and Submodel\nconst reference1 = new Reference(ReferenceTypes.ModelReference, [\n  new Key(KeyTypes.AssetAdministrationShell, 'https://example.com/ids/aas/my-aas'),\n  new Key(KeyTypes.Submodel, 'https://example.com/ids/sm/my-submodel'),\n]);\n\nconst resolved1 = await service.resolveReference({ reference: reference1 });\nif (resolved1.success) {\n  console.log('AAS Endpoint:', resolved1.data.aasEndpoint);\n  // e.g., 'http://localhost:8081/shells/encoded-aas-id'\n  console.log('Submodel Endpoint:', resolved1.data.submodelEndpoint);\n  // e.g., 'http://localhost:8082/submodels/encoded-sm-id'\n}\n\n// Example 2: Reference to a specific SubmodelElement\nconst reference2 = new Reference(ReferenceTypes.ModelReference, [\n  new Key(KeyTypes.AssetAdministrationShell, 'https://example.com/ids/aas/my-aas'),\n  new Key(KeyTypes.Submodel, 'https://example.com/ids/sm/my-submodel'),\n  new Key(KeyTypes.Property, 'MyProperty'),\n]);\n\nconst resolved2 = await service.resolveReference({ reference: reference2 });\nif (resolved2.success) {\n  console.log('SubmodelElement Path:', resolved2.data.submodelElementPath);\n  // e.g., 'http://localhost:8082/submodels/encoded-sm-id/submodel-elements/MyProperty'\n}\n\n// Example 3: Reference to nested SubmodelElements\nconst reference3 = new Reference(ReferenceTypes.ModelReference, [\n  new Key(KeyTypes.Submodel, 'https://example.com/ids/sm/my-submodel'),\n  new Key(KeyTypes.SubmodelElementCollection, 'MyCollection'),\n  new Key(KeyTypes.Property, 'NestedProperty'),\n]);\n\nconst resolved3 = await service.resolveReference({ reference: reference3 });\nif (resolved3.success) {\n  console.log('SubmodelElement Path:', resolved3.data.submodelElementPath);\n  // e.g., 'http://localhost:8082/submodels/encoded-sm-id/submodel-elements/MyCollection.NestedProperty'\n}\n\n// Fetch all AAS with submodels and concept descriptions\nconst allWithCD = await serviceWithCD.getAasList({\n  includeSubmodels: true,\n  includeConceptDescriptions: true,\n});\nif (allWithCD.success) {\n  allWithCD.data.shells.forEach((shell) =\u003e {\n    console.log('Shell:', shell.id);\n    console.log('Submodels:', allWithCD.data.submodels?.[shell.id]);\n    // Concept descriptions are available through the submodel service\n  });\n}\n```\n\n### Using the SubmodelService (High-level API)\n\n```typescript\nimport { SubmodelService, Configuration } from 'basyx-typescript-sdk';\nimport { Submodel, ModellingKind } from '@aas-core-works/aas-core3.1-typescript/types';\n\n// Initialize service with both registry and repository\nconst service = new SubmodelService({\n  registryConfig: new Configuration({ basePath: 'http://localhost:8085' }),\n  repositoryConfig: new Configuration({ basePath: 'http://localhost:8082' }),\n});\n\n// Create a new Submodel (automatically registers in registry)\nconst submodel = new Submodel(\n  'https://example.com/ids/sm/my-submodel',\n  null, // extensions\n  null, // category\n  'MySubmodel', // idShort\n  null, // displayName\n  null, // description\n  null, // administration\n  ModellingKind.Instance\n);\n\nconst createResult = await service.createSubmodel({ submodel });\nif (createResult.success) {\n  console.log('Created Submodel:', createResult.data.submodel);\n  console.log('Registry Descriptor:', createResult.data.descriptor);\n}\n\n// Get Submodel list from registry with automatic endpoint resolution\nconst listResult = await service.getSubmodelList({ preferRegistry: true });\nif (listResult.success) {\n  console.log('All submodels:', listResult.data.submodels);\n  console.log('Fetched from:', listResult.data.source); // 'registry' or 'repository'\n}\n\n// Get Submodel by ID (uses registry endpoint if available)\nconst getResult = await service.getSubmodelById({\n  submodelIdentifier: 'https://example.com/ids/sm/my-submodel',\n  useRegistryEndpoint: true,\n});\nif (getResult.success) {\n  console.log('Submodel:', getResult.data.submodel);\n  console.log('Descriptor:', getResult.data.descriptor);\n}\n\n// Update Submodel (updates both repository and registry)\nsubmodel.idShort = 'UpdatedSubmodel';\nconst updateResult = await service.updateSubmodel({ submodel });\n\n// Get endpoint for a Submodel\nconst endpointResult = await service.getSubmodelEndpointById({\n  submodelIdentifier: 'https://example.com/ids/sm/my-submodel',\n});\nif (endpointResult.success) {\n  console.log('Endpoint:', endpointResult.data);\n}\n\n// Get Submodel directly by endpoint URL\nconst byEndpointResult = await service.getSubmodelByEndpoint({\n  endpoint: 'http://localhost:8082/submodels/encoded-id',\n});\n\n// Delete Submodel (removes from both registry and repository)\nawait service.deleteSubmodel({\n  submodelIdentifier: 'https://example.com/ids/sm/my-submodel',\n});\n\n// Service works with only repository (no registry)\nconst repoOnlyService = new SubmodelService({\n  repositoryConfig: new Configuration({ basePath: 'http://localhost:8082' }),\n});\n\nconst repoList = await repoOnlyService.getSubmodelList();\n// Automatically falls back to repository when registry unavailable\n\n// Fetch submodels with concept descriptions\nconst serviceWithCD = new SubmodelService({\n  registryConfig: new Configuration({ basePath: 'http://localhost:8085' }),\n  repositoryConfig: new Configuration({ basePath: 'http://localhost:8082' }),\n  conceptDescriptionRepositoryConfig: new Configuration({ basePath: 'http://localhost:8083' }),\n});\n\n// Get submodel with its concept descriptions\nconst withCD = await serviceWithCD.getSubmodelById({\n  submodelIdentifier: 'https://example.com/ids/sm/my-submodel',\n  includeConceptDescriptions: true,\n});\nif (withCD.success) {\n  console.log('Submodel:', withCD.data.submodel);\n  console.log('Concept Descriptions:', withCD.data.conceptDescriptions);\n  // conceptDescriptions array contains all unique CDs referenced by:\n  // - The submodel's semanticId\n  // - All submodel elements' semanticId properties (recursively through collections, lists, entities)\n}\n\n// Get all submodels with concept descriptions\nconst listWithCD = await serviceWithCD.getSubmodelList({\n  preferRegistry: false,\n  includeConceptDescriptions: true,\n});\nif (listWithCD.success) {\n  console.log('Submodels:', listWithCD.data.submodels);\n  console.log('All Concept Descriptions:', listWithCD.data.conceptDescriptions);\n  // Concept descriptions are deduplicated across all submodels\n}\n\n// Get submodel by endpoint with concept descriptions\nconst byEndpointWithCD = await serviceWithCD.getSubmodelByEndpoint({\n  endpoint: 'http://localhost:8082/submodels/encoded-id',\n  includeConceptDescriptions: true,\n});\n```\n\n### Using Utility Functions\n\n```typescript\nimport { getSubmodelElementByIdShort, extractEndpointHref, base64Encode } from 'basyx-typescript-sdk';\nimport { Submodel } from '@aas-core-works/aas-core3.1-typescript/types';\n\n// Get a submodel element by its idShort\nconst element = getSubmodelElementByIdShort(submodel, 'MyProperty');\n\n// Extract endpoint from descriptor\nconst endpoint = extractEndpointHref(descriptor, 'AAS-3.0');\n\n// Encode/decode IDs from Identifiables\nconst encoded = base64Encode('https://example.com/ids/aas/my-aas');\n// Use in URL: http://localhost:8081/shells/{encoded}\n```\n\n### XML Serialization and Deserialization\n\n```typescript\nimport { serializeXml, deserializeXml } from 'basyx-typescript-sdk';\nimport { BaSyxEnvironment } from 'basyx-typescript-sdk';\nimport {\n  AssetAdministrationShell,\n  AssetInformation,\n  AssetKind,\n  Submodel,\n  ModellingKind,\n} from '@aas-core-works/aas-core3.1-typescript/types';\n\n// Create an environment with AAS and Submodels\nconst environment = new BaSyxEnvironment(\n  [new AssetAdministrationShell('https://example.com/ids/aas/my-aas', new AssetInformation(AssetKind.Instance))],\n  [\n    new Submodel(\n      'https://example.com/ids/sm/my-submodel',\n      null,\n      null,\n      'MySubmodel',\n      null,\n      null,\n      null,\n      ModellingKind.Instance\n    ),\n  ],\n  [] // conceptDescriptions\n);\n\n// Serialize to XML string\nconst xmlString = serializeXml(environment);\nconsole.log(xmlString);\n// Output:\n// \u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n// \u003caas:environment xmlns:aas=\"https://admin-shell.io/aas/3/1\"\n//   xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n//   xsi:schemaLocation=\"https://admin-shell.io/aas/3/1 AAS.xsd\"\u003e\n//   ...\n// \u003c/aas:environment\u003e\n\n// Customize namespace prefix (default is 'aas')\nconst xmlWithCustomPrefix = serializeXml(environment, 'custom');\n\n// Deserialize XML back to BaSyxEnvironment\nconst deserializedEnv = deserializeXml(xmlString);\nconsole.log('AAS:', deserializedEnv.assetAdministrationShells);\nconsole.log('Submodels:', deserializedEnv.submodels);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-basyx%2Fbasyx-typescript-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feclipse-basyx%2Fbasyx-typescript-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-basyx%2Fbasyx-typescript-sdk/lists"}