add documentation and example regarding dependency tree modelling (#250)

added Documentation and example regarding dependency tree modelling were added in multiple places

Signed-off-by: Jan Kowalleck <[email protected]>

Author: jkowalleck

HISTORY.md

@@ -8,6 +8,8 @@ All notable changes to this project will be documented in this file.
   * Removed synthetic default imports. (via [#243])  
     The resulting _JavaScript_ did not change in functionality, but in size.  
     Downstream users of the _TypeScript_ sources might consider this a bugfix, others a feature, others a style-change. 
+* Added
+  * Documentation and example regarding dependency tree modelling were added in multiple places. (via [#])  
 * Build
   * No longer enable _TypeScript_ config `esModuleInterop` & `allowSyntheticDefaultImports`, 
     which causes smaller build results and less unnecessary generated code.

README.md

@@ -100,12 +100,16 @@ See extended [examples].
 const cdx = require('@cyclonedx/cyclonedx-library')
 
 const bom = new cdx.Models.Bom()
-bom.components.add(
-  new cdx.Models.Component(
-    cdx.Enums.ComponentType.Library,
-    'myComponent'
-  )
+bom.metadata.component = new cdx.Models.Component(
+  cdx.Enums.ComponentType.Application,
+  'MyProject'
 )
+const componentA = new cdx.Models.Component(
+  cdx.Enums.ComponentType.Library,
+  'myComponentA',
+)
+bom.components.add(componentA)
+bom.metadata.component.dependencies.add(componentA.bomRef)
 ```
 
 ### In _WebBrowsers_
@@ -118,12 +122,16 @@ bom.components.add(
     const cdx = CycloneDX_library
 
     let bom = new cdx.Models.Bom()
-    bom.components.add(
-            new cdx.Models.Component(
-                    cdx.Enums.ComponentType.Library,
-                    'myComponent'
-            )
+    bom.metadata.component = new cdx.Models.Component(
+        cdx.Enums.ComponentType.Application,
+        'MyProject'
+    )
+    const componentA = new cdx.Models.Component(
+        cdx.Enums.ComponentType.Library,
+        'myComponentA',
     )
+    bom.components.add(componentA)
+    bom.metadata.component.dependencies.add(componentA.bomRef)
 </script>
 ```
 
@@ -141,7 +149,7 @@ See the [LICENSE][license_file] file for the full license.
 
 [license_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/LICENSE
 [contributing_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/CONTRIBUTING.md
-[examples]: https://github.com/CycloneDX/cyclonedx-javascript-library/tree/main/examples
+[examples]: https://github.com/CycloneDX/cyclonedx-javascript-library/tree/main/examples/README.md
 
 [shield_gh-workflow-test]: https://img.shields.io/github/workflow/status/CycloneDX/cyclonedx-javascript-library/Node%20CI/main?logo=GitHub&logoColor=white "tests"
 [shield_npm-version]: https://img.shields.io/npm/v/%40cyclonedx/cyclonedx-library?logo=npm&logoColor=white "npm"

examples/README.md

@@ -1,5 +1,12 @@
 # Examples
 
+## Usage
+
 * [`example.cjs`](node/example.cjs) showcases the usage in node, commonjs style.
 * [`example.mjs`](node/example.mjs) showcases the usage in node, module style.
 * [`web-browser.html`](web-browser.html) showcases the usage in a web-browser.
+
+## Data models
+
+The ["models" test data](../tests/_data/models.js) holds also examples for complete structures
+with all possible use cases, all nesting, and advanced complexity.

examples/node/example.cjs

@@ -24,12 +24,16 @@ const cdx = require('@cyclonedx/cyclonedx-library')
 // full Library is available as `cdx`, now
 
 const bom = new cdx.Models.Bom()
-bom.components.add(
-  new cdx.Models.Component(
-    cdx.Enums.ComponentType.Library,
-    'myComponent'
-  )
+bom.metadata.component = new cdx.Models.Component(
+  cdx.Enums.ComponentType.Application,
+  'MyProject'
 )
+const componentA = new cdx.Models.Component(
+  cdx.Enums.ComponentType.Library,
+  'myComponentA',
+)
+bom.components.add(componentA)
+bom.metadata.component.dependencies.add(componentA.bomRef)
 
 const jsonSerializer = new cdx.Serialize.JsonSerializer(
   new cdx.Serialize.JSON.Normalize.Factory(

examples/node/example.mjs

@@ -24,12 +24,16 @@ import * as cdx from '@cyclonedx/cyclonedx-library'
 // full Library is available as `cdx`, now
 
 const bom = new cdx.Models.Bom()
-bom.components.add(
-  new cdx.Models.Component(
-    cdx.Enums.ComponentType.Library,
-    'myComponent'
-  )
+bom.metadata.component = new cdx.Models.Component(
+  cdx.Enums.ComponentType.Application,
+  'MyProject'
 )
+const componentA = new cdx.Models.Component(
+  cdx.Enums.ComponentType.Library,
+  'myComponentA',
+)
+bom.components.add(componentA)
+bom.metadata.component.dependencies.add(componentA.bomRef)
 
 const jsonSerializer = new cdx.Serialize.JsonSerializer(
   new cdx.Serialize.JSON.Normalize.Factory(

examples/web-browser.html

@@ -32,12 +32,16 @@
     // full Library is available as `cdx`, now
 
     const bom = new cdx.Models.Bom()
-    bom.components.add(
-      new cdx.Models.Component(
-        cdx.Enums.ComponentType.Library,
-        'myComponent'
-      )
+    bom.metadata.component = new cdx.Models.Component(
+      cdx.Enums.ComponentType.Application,
+      'MyProject'
     )
+    const componentA = new cdx.Models.Component(
+      cdx.Enums.ComponentType.Library,
+      'myComponentA',
+    )
+    bom.components.add(componentA)
+    bom.metadata.component.dependencies.add(componentA.bomRef)
 
     const jsonSerializer = new cdx.Serialize.JsonSerializer(
       new cdx.Serialize.JSON.Normalize.Factory(