feat: NodeJS exports submodules as subpaths (#1066)

## Added
* Explicitly export own first-level submodules via package manifest (via
[#1066])
When used with bundlers/packers downstream, this might enable better
tree shaking due to scoped imports.
## Refactor
  * Ease internal tree shaking (via [#1066])

[#1066]: #1066

---------

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

Author: jkowalleck

HISTORY.md

@@ -6,6 +6,14 @@ All notable changes to this project will be documented in this file.
 
 <!-- add unreleased items here -->
 
+* Added
+  * Explicitly export own first-level submodules via package manifest (via [#1066])  
+    When used with bundlers/packers downstream, this might enable better tree shaking due to scoped imports.
+* Refactor
+  * Ease internal tree shaking (via [#1066])
+
+[#1066]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/1066
+
 ## 6.7.2 -- 2024-05-07
 
 * Changed

package.json

@@ -106,9 +106,52 @@
   "types": "./dist.d/index.node.d.ts",
   "main": "./dist.node/index.node.js",
   "exports": {
-    "types": "./dist.d/index.node.d.ts",
-    "browser": "./dist.web/lib.js",
-    "default": "./dist.node/index.node.js"
+    ".": {
+      "types": "./dist.d/index.node.d.ts",
+      "browser": "./dist.web/lib.js",
+      "default": "./dist.node/index.node.js"
+    },
+    "./package.json": "./package.json",
+    "./Builders": {
+      "types": "./dist.d/builders/index.node.d.ts",
+      "default": "./dist.node/builders/index.node.js"
+    },
+    "./Enums": {
+      "types": "./dist.d/enums/index.d.ts",
+      "default": "./dist.node/enums/index.js"
+    },
+    "./Factories": {
+      "types": "./dist.d/factories/index.node.d.ts",
+      "default": "./dist.node/factories/index.node.js"
+    },
+    "./Models": {
+      "types": "./dist.d/models/index.d.ts",
+      "default": "./dist.node/models/index.js"
+    },
+    "./Serialize": {
+      "types": "./dist.d/serialize/index.node.d.ts",
+      "default": "./dist.node/serialize/index.node.js"
+    },
+    "./Spec": {
+      "types": "./dist.d/spec/index.d.ts",
+      "default": "./dist.node/spec/index.js"
+    },
+    "./Types": {
+      "types": "./dist.d/types/index.d.ts",
+      "default": "./dist.node/types/index.js"
+    },
+    "./Utils": {
+      "types": "./dist.d/utils/index.d.ts",
+      "default": "./dist.node/utils/index.js"
+    },
+    "./Validation": {
+      "types": "./dist.d/validation/index.node.d.ts",
+      "default": "./dist.node/validation/index.node.js"
+    },
+    "./SPDX": {
+      "types": "./dist.d/spdx.d.ts",
+      "default": "./dist.node/spdx.js"
+    }
   },
   "directories": {
     "doc": "./docs",

src/builders/fromNodePackageJson.node.ts

@@ -28,9 +28,12 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 
 import type { PackageJson } from '../_helpers/packageJson'
 import { splitNameGroup } from '../_helpers/packageJson'
-import * as Enums from '../enums'
+import { ComponentType } from '../enums/componentType'
 import type * as Factories from '../factories/index.node'
-import * as Models from '../models'
+import { Component } from '../models/component'
+import { ExternalReferenceRepository } from '../models/externalReference'
+import { LicenseRepository } from '../models/license'
+import { Tool } from '../models/tool'
 
 /**
  * Node-specific ToolBuilder.
@@ -48,18 +51,18 @@ export class ToolBuilder {
 
   // Current implementation does not return `undefined` yet, but it is an option for future implementation.
   // To prevent future breaking changes, it is declared to return `undefined`.
-  makeTool (data: PackageJson): Models.Tool | undefined {
+  makeTool (data: PackageJson): Tool | undefined {
     const [name, vendor] = typeof data.name === 'string'
       ? splitNameGroup(data.name)
       : []
 
-    return new Models.Tool({
+    return new Tool({
       vendor,
       name,
       version: (typeof data.version === 'string')
         ? data.version
         : undefined,
-      externalReferences: new Models.ExternalReferenceRepository(this.#extRefFactory.makeExternalReferences(data))
+      externalReferences: new ExternalReferenceRepository(this.#extRefFactory.makeExternalReferences(data))
     })
   }
 }
@@ -87,7 +90,7 @@ export class ComponentBuilder {
     return this.#licenseFactory
   }
 
-  makeComponent (data: PackageJson, type: Enums.ComponentType = Enums.ComponentType.Library): Models.Component | undefined {
+  makeComponent (data: PackageJson, type: ComponentType = ComponentType.Library): Component | undefined {
     if (typeof data.name !== 'string') {
       return undefined
     }
@@ -116,7 +119,7 @@ export class ComponentBuilder {
 
     const externalReferences = this.#extRefFactory.makeExternalReferences(data)
 
-    const licenses = new Models.LicenseRepository()
+    const licenses = new LicenseRepository()
     if (typeof data.license === 'string') {
       /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#license */
       licenses.add(this.#licenseFactory.makeFromString(data.license))
@@ -134,10 +137,10 @@ export class ComponentBuilder {
       }
     }
 
-    return new Models.Component(type, name, {
+    return new Component(type, name, {
       author,
       description,
-      externalReferences: new Models.ExternalReferenceRepository(externalReferences),
+      externalReferences: new ExternalReferenceRepository(externalReferences),
       group,
       licenses,
       version

src/factories/fromNodePackageJson.node.ts

@@ -31,16 +31,17 @@ import type { PackageURL } from 'packageurl-js'
 import { isNotUndefined } from '../_helpers/notUndefined'
 import type { PackageJson } from '../_helpers/packageJson'
 import { PackageUrlQualifierNames } from '../_helpers/packageUrl'
-import * as Enums from '../enums'
-import * as Models from '../models'
+import { ExternalReferenceType } from '../enums/externalReferenceType'
+import type { Component } from '../models/component'
+import { ExternalReference } from '../models/externalReference'
 import { PackageUrlFactory as PlainPackageUrlFactory } from './packageUrl'
 
 /**
  * Node-specific ExternalReferenceFactory.
  */
 export class ExternalReferenceFactory {
-  makeExternalReferences (data: PackageJson): Models.ExternalReference[] {
-    const refs: Array<Models.ExternalReference | undefined> = []
+  makeExternalReferences (data: PackageJson): ExternalReference[] {
+    const refs: Array<ExternalReference | undefined> = []
 
     try { refs.push(this.makeVcs(data)) } catch { /* pass */ }
     try { refs.push(this.makeHomepage(data)) } catch { /* pass */ }
@@ -49,7 +50,7 @@ export class ExternalReferenceFactory {
     return refs.filter(isNotUndefined)
   }
 
-  makeVcs (data: PackageJson): Models.ExternalReference | undefined {
+  makeVcs (data: PackageJson): ExternalReference | undefined {
     /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#repositoryc */
     const repository = data.repository
     let url
@@ -67,21 +68,21 @@ export class ExternalReferenceFactory {
       comment = 'as detected from PackageJson property "repository"'
     }
     return typeof url === 'string' && url.length > 0
-      ? new Models.ExternalReference(url, Enums.ExternalReferenceType.VCS, { comment })
+      ? new ExternalReference(url, ExternalReferenceType.VCS, { comment })
       : undefined
   }
 
-  makeHomepage (data: PackageJson): Models.ExternalReference | undefined {
+  makeHomepage (data: PackageJson): ExternalReference | undefined {
     /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#homepage */
     const url = data.homepage
     return typeof url === 'string' && url.length > 0
-      ? new Models.ExternalReference(
-        url, Enums.ExternalReferenceType.Website,
+      ? new ExternalReference(
+        url, ExternalReferenceType.Website,
         { comment: 'as detected from PackageJson property "homepage"' })
       : undefined
   }
 
-  makeIssueTracker (data: PackageJson): Models.ExternalReference | undefined {
+  makeIssueTracker (data: PackageJson): ExternalReference | undefined {
     /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#bugs */
     const bugs = data.bugs
     let url
@@ -94,7 +95,7 @@ export class ExternalReferenceFactory {
       comment = 'as detected from PackageJson property "bugs"'
     }
     return typeof url === 'string' && url.length > 0
-      ? new Models.ExternalReference(url, Enums.ExternalReferenceType.IssueTracker, { comment })
+      ? new ExternalReference(url, ExternalReferenceType.IssueTracker, { comment })
       : undefined
   }
 }
@@ -105,7 +106,7 @@ const npmDefaultRegistryMatcher = /^https?:\/\/registry\.npmjs\.org/
  * Node-specific PackageUrlFactory.
  */
 export class PackageUrlFactory extends PlainPackageUrlFactory {
-  override makeFromComponent (component: Models.Component, sort: boolean = false): PackageURL | undefined {
+  override makeFromComponent (component: Component, sort: boolean = false): PackageURL | undefined {
     const purl = super.makeFromComponent(component, sort)
     return purl === undefined
       ? undefined

src/factories/license.ts

@@ -17,8 +17,8 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
-import type { DisjunctiveLicense, License } from '../models'
-import { LicenseExpression, NamedLicense, SpdxLicense } from '../models'
+import type { DisjunctiveLicense, License } from '../models/license'
+import { LicenseExpression, NamedLicense, SpdxLicense } from '../models/license'
 import { fixupSpdxId, isValidSpdxLicenseExpression } from '../spdx'
 
 export class LicenseFactory {

src/factories/packageUrl.ts

@@ -20,8 +20,8 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 import { PackageURL } from 'packageurl-js'
 
 import { PackageUrlQualifierNames } from '../_helpers/packageUrl'
-import { ExternalReferenceType } from '../enums'
-import type { Component } from '../models'
+import { ExternalReferenceType } from '../enums/externalReferenceType'
+import type { Component } from '../models/component'
 
 export class PackageUrlFactory {
   readonly #type: PackageURL['type']

src/index.node.ts

@@ -17,6 +17,10 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
+/* REMEMBER:
+ALL non-internal exports in here have to be set as `exports` in `package.json`
+*/
+
 export * from './index.common'
 
 // region node-specifics

src/models/attachment.ts

@@ -18,7 +18,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
 import type { Stringable } from '../_helpers/stringable'
-import type { AttachmentEncoding } from '../enums'
+import type { AttachmentEncoding } from '../enums/attachmentEncoding'
 
 export interface OptionalAttachmentProperties {
   contentType?: Attachment['contentType']

src/models/bom.ts

@@ -17,11 +17,11 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
-import type { PositiveInteger } from '../types'
-import { isPositiveInteger } from '../types'
+import type { PositiveInteger } from '../types/integer'
+import { isPositiveInteger } from '../types/integer'
 import { ComponentRepository } from './component'
 import { Metadata } from './metadata'
-import { VulnerabilityRepository } from './vulnerability'
+import { VulnerabilityRepository } from './vulnerability/vulnerability'
 
 export interface OptionalBomProperties {
   metadata?: Bom['metadata']

src/models/component.ts

@@ -24,8 +24,8 @@ import { SortableComparables, SortableStringables } from '../_helpers/sortable'
 import type { Stringable } from '../_helpers/stringable'
 import { treeIteratorSymbol } from '../_helpers/tree'
 import type { ComponentScope, ComponentType } from '../enums'
-import type { CPE } from '../types'
-import { isCPE } from '../types'
+import type { CPE } from '../types/cpe'
+import { isCPE } from '../types/cpe'
 import { BomRef, BomRefRepository } from './bomRef'
 import { ExternalReferenceRepository } from './externalReference'
 import { HashDictionary } from './hash'

src/models/externalReference.ts

@@ -19,7 +19,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 
 import type { Comparable } from '../_helpers/sortable'
 import { SortableComparables } from '../_helpers/sortable'
-import type { ExternalReferenceType } from '../enums'
+import type { ExternalReferenceType } from '../enums/externalReferenceType'
 import type { BomLink } from './bomLink'
 import { HashDictionary } from './hash'
 

src/models/hash.ts

@@ -18,7 +18,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
 import type { Sortable } from '../_helpers/sortable'
-import type { HashAlgorithm } from '../enums'
+import type { HashAlgorithm } from '../enums/hashAlogorithm'
 
 // no regex for the HashContent in here. It applies at runtime of a normalization/serialization process.
 export type HashContent = string

src/models/license.ts

@@ -18,7 +18,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
 import type { Sortable } from '../_helpers/sortable'
-import type { LicenseAcknowledgement } from '../enums'
+import type { LicenseAcknowledgement } from '../enums/licenseAcknowledgement'
 import type { SpdxId } from '../spdx'
 import type { Attachment } from './attachment'
 

src/models/lifecycle.ts

@@ -18,7 +18,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
 import type { Comparable, Sortable } from '../_helpers/sortable'
-import type { LifecyclePhase } from '../enums'
+import type { LifecyclePhase } from '../enums/lifecyclePhase'
 
 export interface OptionalNamedLifecycleProperties {
   description?: NamedLifecycle['description']

src/models/swid.ts

@@ -17,8 +17,8 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
-import type { NonNegativeInteger } from '../types'
-import { isNonNegativeInteger } from '../types'
+import type { NonNegativeInteger } from '../types/integer'
+import { isNonNegativeInteger } from '../types/integer'
 import type { Attachment } from './attachment'
 
 export interface OptionalSWIDProperties {

src/models/vulnerability/analysis.ts

@@ -18,7 +18,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
 import type { AnalysisJustification, AnalysisState } from '../../enums/vulnerability'
-import { AnalysisResponseRepository } from '../../enums/vulnerability'
+import { AnalysisResponseRepository } from '../../enums/vulnerability/analysisResponse'
 
 export interface OptionalAnalysisProperties {
   state?: Analysis['state']

src/models/vulnerability/vulnerability.ts

@@ -19,7 +19,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 
 import type { Comparable } from '../../_helpers/sortable'
 import { SortableComparables } from '../../_helpers/sortable'
-import { CweRepository } from '../../types'
+import { CweRepository } from '../../types/cwe'
 import { BomRef } from '../bomRef'
 import { PropertyRepository } from '../property'
 import { ToolRepository } from '../tool'