docs

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

Author: jkowalleck

HISTORY.md

@@ -6,6 +6,11 @@ All notable changes to this project will be documented in this file.
 
 <!-- add unreleased items here -->
 
+* Added
+  * Public export `types.NodePackageJson`, which is the input type for various factories and builders (via [#1263])
+
+[#1263]: https://github.com/CycloneDX/cyclonedx-javascript-library/pull/1263
+
 ## 8.4.0 -- 2025-06-16
 
 * Fixed

src/builders/fromNodePackageJson.node.ts

@@ -33,7 +33,7 @@ import { Component } from '../models/component'
 import { ExternalReferenceRepository } from '../models/externalReference'
 import { LicenseRepository } from '../models/license'
 import { Tool } from '../models/tool'
-import type { PackageJson } from '../types/packageJson'
+import type { NodePackageJson } from '../types/nodePackageJson'
 
 /**
  * Node-specific ToolBuilder.
@@ -51,7 +51,7 @@ 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): Tool | undefined {
+  makeTool (data: NodePackageJson): Tool | undefined {
     const [name, vendor] = typeof data.name === 'string'
       ? splitNameGroup(data.name)
       : []
@@ -90,7 +90,7 @@ export class ComponentBuilder {
     return this.#licenseFactory
   }
 
-  makeComponent (data: PackageJson, type: ComponentType = ComponentType.Library): Component | undefined {
+  makeComponent (data: NodePackageJson, type: ComponentType = ComponentType.Library): Component | undefined {
     if (typeof data.name !== 'string') {
       return undefined
     }

src/factories/fromNodePackageJson.node.ts

@@ -36,15 +36,15 @@ import { HashAlgorithm } from "../enums/hashAlogorithm";
 import type { Component } from '../models/component'
 import { ExternalReference } from '../models/externalReference'
 import { HashDictionary } from '../models/hash'
-import type { PackageJson } from '../types/packageJson'
+import type { NodePackageJson } from '../types/nodePackageJson'
 import { defaultRegistryMatcher, parsePackageIntegrity } from '../utils/npmjsUtility.node'
 import { PackageUrlFactory as PlainPackageUrlFactory } from './packageUrl'
 
 /**
  * Node-specific ExternalReferenceFactory.
  */
 export class ExternalReferenceFactory {
-  makeExternalReferences (data: PackageJson): ExternalReference[] {
+  makeExternalReferences (data: NodePackageJson): ExternalReference[] {
     const refs: Array<ExternalReference | undefined> = []
 
     try { refs.push(this.makeVcs(data)) } catch { /* pass */ }
@@ -55,7 +55,7 @@ export class ExternalReferenceFactory {
     return refs.filter(isNotUndefined)
   }
 
-  makeVcs (data: PackageJson): ExternalReference | undefined {
+  makeVcs (data: NodePackageJson): ExternalReference | undefined {
     /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#repositoryc */
     const repository = data.repository
     let url = undefined
@@ -78,7 +78,7 @@ export class ExternalReferenceFactory {
       : new ExternalReference(url.toString(), ExternalReferenceType.VCS, { comment })
   }
 
-  makeHomepage (data: PackageJson): ExternalReference | undefined {
+  makeHomepage (data: NodePackageJson): 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
@@ -88,7 +88,7 @@ export class ExternalReferenceFactory {
       : undefined
   }
 
-  makeIssueTracker (data: PackageJson): ExternalReference | undefined {
+  makeIssueTracker (data: NodePackageJson): ExternalReference | undefined {
     /* see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#bugs */
     const bugs = data.bugs
     let url = undefined
@@ -105,7 +105,7 @@ export class ExternalReferenceFactory {
       : undefined
   }
 
-  makeDist(data: PackageJson): ExternalReference | undefined {
+  makeDist(data: NodePackageJson): ExternalReference | undefined {
     // "dist" might be used in bundled dependencies' manifests.
     // docs: https://blog.npmjs.org/post/172999548390/new-pgp-machinery
     /* eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- acknowledged */

src/types/packageJson.ts renamed to src/types/nodePackageJson.ts

@@ -25,7 +25,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
  * Normalization should be done downstream, for example
  * via [`normalize-package-data`](https://www.npmjs.com/package/normalize-package-data).
  */
-export interface PackageJson {
+export interface NodePackageJson {
   name?: string
   version?: string
   description?: string
@@ -53,7 +53,7 @@ export interface PackageJson {
 
 
 /* TODO: write type assertion
-export function isPackageJsonNode (value: any): value is PackageJsonNode {
-  return...
+export function isNodePackageJson (value: any): value is NodePackageJson {
+  ...
 }
 */