Skip to content

can't use internals for public API #1192

@jkowalleck

Description

@jkowalleck

some properties and constructor parameters use internal types, like SortableStringables.

this is an issue, as these internals are not exported. they can not be used downstream.
It prevents usage like follows:

component.evidence = new CDX.Models.ComponentEvidence({
        licenses: new CDX.Models.LicenseRepository(this.getLicenseEvidence(dirname(pkg.path), logger)),
        copyright: new SortableStringables(copyrights)
      })

context

some symbols are mark as internals, they are not exported, and they are not public API.
see https://cyclonedx-javascript-library.readthedocs.io/en/latest/typedoc/node/modules/_internal_.html

but yet, some internals are used in public API, as properties or parameters.

requirements / goals

  • no internals are used in public API, as properties or parameters.
    They miught be used for inheritance, still.

solution

have dedicated classes, that are properly exported and public API.
for example

// pseudo-code 
export CDX.Models.CopyrightRepository extends SortableStringables{}

just like we did before:

export class AnalysisResponseRepository extends SortableStringables<AnalysisResponse> {}

considerations

since this would change types of public API, we would introduce it in a two-staged manner:

  1. non-breaking:
    • allo the new class -- since the new classes inherit from the old one, all is good
      ComponentEvidence(..., copyright: CopyrightRepository|SortableStringables)
    • dont change the typeof the property -- since the new classes inherit from the old one, all is good
      copyright: SortableStringables
  2. breaking: remove any usage of non-public classes in public API.
    prepare a breaking change, but dont mere it yet; have it added to the next major milestone.
    see must not use internals for public API #1193

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions