BC: Properly exclude external packages when preparing this library for web browsers

.eslintignore

@@ -1,11 +1,12 @@
 **/node_modules/**
 
-
 # generated files: dist and docs
+/reports/**
 /dist/**
 /dist.*/**
 /docs/api/**
-/examples/node-typescript/dist/**
+/examples/**/dist/**
+
 
 !/src/**
 !/libs/**

.github/workflows/nodejs.yml

@@ -263,7 +263,7 @@ jobs:
         run: node -- 'example.${{ matrix.js-type }}'
         working-directory: ${{ env.EXAMPLE_DIR }}
 
-  example-typescript:
+  example-TS:
     needs: [ 'build' ]
     name: example TS${{ matrix.typescript-version }} ${{ matrix.js-type }}
     runs-on: ubuntu-latest
@@ -326,6 +326,42 @@ jobs:
         run: npm run example
         working-directory: ${{ env.EXAMPLE_DIR }}
 
+  examples-Web:
+    needs: [ 'build' ]
+    name: example Web ${{ matrix.packer }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        packer:
+          - parcel
+          - webpack
+    env:
+      EXAMPLE_DIR: examples/web/${{ matrix.packer }}
+    steps:
+      - name: Checkout
+        # see https://github.com/actions/checkout
+        uses: actions/checkout@v3
+      - name: Setup Node.js ${{ env.NODE_ACTIVE_LTS }}
+        # see https://github.com/actions/setup-node
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ env.NODE_ACTIVE_LTS }}
+      - name: fetch build artifact 'node'
+        # see https://github.com/actions/download-artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: dist.web
+          path: dist.web
+      - name: setup library
+        run: npm ci --ignore-scripts --omit=dev --include=optional --loglevel=silly
+      - name: setup example project
+        run: npm i --no-save --loglevel=silly
+        working-directory: ${{ env.EXAMPLE_DIR }}
+      - name: build example
+        run: npm run build
+        working-directory: ${{ env.EXAMPLE_DIR }}
+
   api-doc:
     name: api-doc ${{ matrix.target }}
     runs-on: "ubuntu-latest"

HISTORY.md

@@ -4,12 +4,26 @@ All notable changes to this project will be documented in this file.
 
 ## unreleased
 
+* BREAKING
+  * Usage this library in web browsers might no longer work out of the box (via [#880])  
+    It might require a bundler/packer for web; see the `examples/web-*`.  
+    This is only a breaking change if you used this library in a web browser.
+* Fixed
+  * Properly exclude external packages when preparing this library for web browsers ([#883] via [#880])
+* Examples
+  * Adjusted and extended examples for usage in web browsers ([#883] via [#880])  
+    Removed `examples/web`, added `examples/web-parcel` & `examples/web-webpack`.
+  * Added examples for usage of `CDX.Factories.PackageUrlFactory` (via [#882])
 * Build
   * Use _TypeScript_ `v5.1.6` now, was `v5.1.5` (via [#866])
   * Use _Webpack_ `v5.88.1` now, was `v5.88.0` (via [#870])
+  * Apply wider rules for `externals` for in _Webpack_ build ([#883] via [#880])
 
 [#866]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/866
 [#870]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/870
+[#880]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/880
+[#882]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/882
+[#883]: https://github.com/CycloneDX/cyclonedx-javascript-library/issues/883
 
 ## 3.0.0 -- 2023-06-28
 

examples/README.md

@@ -8,8 +8,12 @@
 * `node-typescript` showcases the usage in Node.js TypeScript
   * [`example.cjs`](node-typescript/example.cjs) targets JavaScript, "commonjs" style - from TypeScript `^3.8 || ^4 || ^5`.
   * [`example.mjs`](node-typescript/example.mjs) targets JavaScript, "module"   style - from TypeScript `^4 || ^5`.
-* `web` showcases the usage in web browser JavaScript
-  * [`example.html`](web/example.html) targets any web-browser.
+* `web/parcel` showcases the usage in web browser when compiled by [_Parcel_](https://parceljs.org/):
+  * [`src/index.html`](web/parcel/src/index.html) will be compiled to  
+    [`dist/index.html`](web/parcel/dist/index.html) and runs in any web browser.
+* `web/webpack` showcases the usage in web browser when compiled by [_Webpack_](https://webpack.js.org/):
+  * [`src/index.js`](web/webpack/src/index.js) will be compiled, so that it can be embedded by  
+    [`dist/index.html`](web/webpack/dist/index.html) and runs in any web browser.
 
 ## Data models
 

examples/web/parcel/.gitignore

@@ -0,0 +1,5 @@
+*
+!/.gitignore
+!/package.json
+!/src/
+!/src/**

examples/web/parcel/package.json

@@ -0,0 +1,16 @@
+{
+  "private": true,
+  "name": "example",
+  "license": "Apache-2.0",
+  "source": "src/index.html",
+  "dependencies": {
+    "@cyclonedx/cyclonedx-library": "file:../../.."
+  },
+  "devDependencies": {
+    "parcel": "^2"
+  },
+  "scripts": {
+    "build": "parcel build --detailed-report",
+    "example": "parcel"
+  }
+}

examples/web/parcel/src/app.js

@@ -0,0 +1,59 @@
+/*!
+This file is part of CycloneDX JavaScript Library.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) OWASP Foundation. All Rights Reserved.
+*/
+
+/** Example how to serialize a Bom to JSON / XML. */
+
+const CDX = require('@cyclonedx/cyclonedx-library')
+// full Library is available as `CDX`, now
+
+const lFac = new CDX.Factories.LicenseFactory()
+const purlFac = new CDX.Factories.PackageUrlFactory('npm')
+
+const bom = new CDX.Models.Bom()
+bom.metadata.component = new CDX.Models.Component(
+  CDX.Enums.ComponentType.Application,
+  'MyProject'
+)
+bom.metadata.component.licenses.add(lFac.makeFromString('MIT OR Apache-2.0'))
+
+const componentA = new CDX.Models.Component(
+  CDX.Enums.ComponentType.Library,
+  'myComponentA',
+  {
+    group: 'acme',
+    version: '1.33.7'
+  }
+)
+componentA.licenses.add(lFac.makeFromString('Apache-2.0'))
+componentA.purl = purlFac.makeFromComponent(componentA)
+
+bom.components.add(componentA)
+bom.metadata.component.dependencies.add(componentA.bomRef)
+
+const serializeSpec = CDX.Spec.Spec1dot5
+
+const jsonSerializer = new CDX.Serialize.JsonSerializer(
+  new CDX.Serialize.JSON.Normalize.Factory(serializeSpec))
+const serializedJson = jsonSerializer.serialize(bom)
+console.log(serializedJson)
+
+const xmlSerializer = new CDX.Serialize.XmlSerializer(
+  new CDX.Serialize.XML.Normalize.Factory(serializeSpec))
+const serializedXML = xmlSerializer.serialize(bom)
+console.log(serializedXML)

examples/web/parcel/src/index.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<!--
+This file is part of CycloneDX JavaScript Library.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) OWASP Foundation. All Rights Reserved.
+-->
+<html lang="en">
+<head>
+  <title>example</title>
+</head>
+<body>
+  <script type="module" src="app.js"></script>
+  <p>see JavaScript Console output for result.</p>
+</body>
+</html>

examples/web/webpack/.gitignore

@@ -0,0 +1,8 @@
+*
+!/.gitignore
+!/package.json
+!/webpack.json
+!/src/
+!/src/**
+!/dist/
+!/dist/index.html

examples/web/webpack/dist/index.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<!--
+This file is part of CycloneDX JavaScript Library.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+SPDX-License-Identifier: Apache-2.0
+Copyright (c) OWASP Foundation. All Rights Reserved.
+-->
+<html lang="en">
+<head>
+  <title>example</title>
+</head>
+<body>
+  <script src="./main.js"></script>
+  <p>see JavaScript Console output for result.</p>
+</body>
+</html>

examples/web/webpack/package.json

@@ -0,0 +1,16 @@
+{
+  "private": true,
+  "name": "example",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@cyclonedx/cyclonedx-library": "file:../../.."
+  },
+  "devDependencies": {
+    "webpack": "^5",
+    "webpack-cli": "^5"
+  },
+  "scripts": {
+    "build": "webpack build",
+    "example": "www-browser dist/index.html"
+  }
+}