structUtils

Index

Functions

• allPeerRequests
• areDescriptorsEqual
• areIdentsEqual
• areLocatorsEqual
• areVirtualPackagesEquivalent
• bindDescriptor
• bindLocator
• convertDescriptorToLocator
• convertLocatorToDescriptor
• convertPackageToLocator
• convertToIdent
• convertToManifestRange
• copyPackage
• devirtualizeDescriptor
• devirtualizeLocator
• ensureDevirtualizedDescriptor
• ensureDevirtualizedLocator
• getIdentVendorPath
• isPackageCompatible
• isVirtualDescriptor
• isVirtualLocator
• makeDescriptor
• makeIdent
• makeLocator
• makeRange
• parseDescriptor
• parseFileStyleRange
• parseIdent
• parseLocator
• parseRange
• prettyDependent
• prettyDescriptor
• prettyIdent
• prettyLocator
• prettyLocatorNoColors
• prettyRange
• prettyReference
• prettyResolution
• prettyWorkspace
• renamePackage
• slugifyIdent
• slugifyLocator
• sortDescriptors
• stringifyDescriptor
• stringifyIdent
• stringifyLocator
• tryParseDescriptor
• tryParseIdent
• tryParseLocator
• tryParseRange
• virtualizeDescriptor
• virtualizePackage

Functions

allPeerRequests

• allPeerRequests(root: PeerRequirementNode | PeerRequestNode): Iterable<PeerRequestNode>

• Parameters

  • root: PeerRequirementNode | PeerRequestNode

  Returns Iterable<PeerRequestNode>

areDescriptorsEqual

• areDescriptorsEqual(a: Descriptor, b: Descriptor): boolean

• Returns true if the descriptors are equal

  ---

  Parameters

  • a: Descriptor

  • b: Descriptor

  Returns boolean

areIdentsEqual

• areIdentsEqual(a: Ident, b: Ident): boolean

• Returns true if the idents are equal

  ---

  Parameters

  • a: Ident

  • b: Ident

  Returns boolean

areLocatorsEqual

• areLocatorsEqual(a: Locator, b: Locator): boolean

• Returns true if the locators are equal

  ---

  Parameters

  • a: Locator

  • b: Locator

  Returns boolean

areVirtualPackagesEquivalent

• areVirtualPackagesEquivalent(a: Package, b: Package): boolean

• Virtual packages are considered equivalent when they belong to the same package identity and have the same dependencies. Note that equivalence is not the same as equality, as the references may be different.

  ---

  Parameters

  • a: Package

  • b: Package

  Returns boolean

bindDescriptor

• bindDescriptor(descriptor: Descriptor, params: {}): Descriptor

• Some descriptors only make sense when bound with some internal state. For instance that would be the case for the file: ranges, which require to be bound to their parent packages in order to resolve relative paths from the right location.

  This function will apply the specified parameters onto the requested descriptor, but only if it didn't get bound before (important to handle the case where we replace a descriptor by another, since when that happens the replacement has probably been already bound).

  ---

  Parameters

  • descriptor: Descriptor

    The original descriptor

  • params: {}

    The parameters to encode in the range

  Returns Descriptor

bindLocator

• bindLocator(locator: Locator, params: {}): Locator

• Some locators only make sense when bound with some internal state. For instance that would be the case for the file: references, which require to be bound to their parent packages in order to resolve relative paths from the right location.

  This function will apply the specified parameters onto the requested locator, but only if it didn't get bound before (important to handle the case where we replace a locator by another, since when that happens the replacement has probably been already bound).

  ---

  Parameters

  • locator: Locator

    The original locator

  • params: {}

    The parameters to encode in the reference

  Returns Locator

convertDescriptorToLocator

• convertDescriptorToLocator(descriptor: Descriptor): Locator

• Turns a descriptor into a locator.

  Note that this process may be unsafe, as descriptors may reference multiple packages, putting them at odd with locators' expected semantic. Only makes sense when used with single-resolution protocols, for instance file:.

  ---

  Parameters

  • descriptor: Descriptor

    The descriptor to convert into a locator.

  Returns Locator

convertLocatorToDescriptor

• convertLocatorToDescriptor(locator: Locator): Descriptor

• Turns a locator into a descriptor.

  This should be safe to do regardless of the locator, since all locator references are expected to be valid descriptor ranges.

  ---

  Parameters

  • locator: Locator

    The locator to convert into a descriptor.

  Returns Descriptor

convertPackageToLocator

• convertPackageToLocator(pkg: Package): Locator

• Turns a package structure into a simple locator. You won't often need to call this function since packages are already valid locators by virtue of structural inheritance.

  This function is only useful if you absolutely need to remove the non-locator fields from a structure before storing it somewhere.

  ---

  Parameters

  • pkg: Package

    The package to convert into a locator.

  Returns Locator

convertToIdent

• convertToIdent(source: Descriptor | Package | Locator): Ident

• Turns a compatible source to an ident. You won't really have to use this function since by virtue of structural inheritance all descriptors and locators are already valid idents.

  This function is only useful if you absolutely need to remove the non-ident fields from a structure before storing it somewhere.

  ---

  Parameters

  • source: Descriptor | Package | Locator

    The data structure to convert into an ident.

  Returns Ident

convertToManifestRange

• convertToManifestRange(range: string): string

• Some bindings are internal-only and not meant to be displayed anywhere (for instance that's the case with the parent locator bound to the file: ranges).

  this function strips them from a range.

  ---

  Parameters

  • range: string

  Returns string

copyPackage

• copyPackage(pkg: Package): Package

• Deep copies a package. The copy will share the same locator as the original.

  ---

  Parameters

  • pkg: Package

    The source package

  Returns Package

devirtualizeDescriptor

• devirtualizeDescriptor(descriptor: Descriptor): Descriptor

• Returns a new devirtualized descriptor based on a virtualized descriptor

  ---

  Parameters

  • descriptor: Descriptor

  Returns Descriptor

devirtualizeLocator

• devirtualizeLocator(locator: Locator): Locator

• Returns a new devirtualized locator based on a virtualized locator

  ---

  Parameters

  • locator: Locator

    the locator

  Returns Locator

ensureDevirtualizedDescriptor

• ensureDevirtualizedDescriptor(descriptor: Descriptor): Descriptor

• Returns a descriptor guaranteed to be devirtualized

  ---

  Parameters

  • descriptor: Descriptor

  Returns Descriptor

ensureDevirtualizedLocator

• ensureDevirtualizedLocator(locator: Locator): Locator

• Returns a locator guaranteed to be devirtualized

  ---

  Parameters

  • locator: Locator

    the locator

  Returns Locator

getIdentVendorPath

• getIdentVendorPath(ident: Ident): PortablePath

• The presence of a node_modules directory in the path is extremely common in the JavaScript ecosystem to denote whether a path belongs to a vendor or not. I considered using a more generic path for packages that aren't always JS-only (such as when using the Git fetcher), but that unfortunately caused various JS apps to start showing errors when working with git repos.

  As a result, all packages from all languages will follow this convention. At least it'll be consistent, and linkers will always have the ability to remap them to a different location if that's a critical requirement.

  ---

  Parameters

  • ident: Ident

  Returns PortablePath

isPackageCompatible

• isPackageCompatible(pkg: Package, architectures: ArchitectureSet): boolean

• Returns whether the given package is compatible with the specified environment.

  ---

  Parameters

  • pkg: Package

  • architectures: ArchitectureSet

  Returns boolean

isVirtualDescriptor

• isVirtualDescriptor(descriptor: Descriptor): boolean

• Returns true if the descriptor is virtual.

  ---

  Parameters

  • descriptor: Descriptor

  Returns boolean

isVirtualLocator

• isVirtualLocator(locator: Locator): boolean

• Returns true if the locator is virtual.

  ---

  Parameters

  • locator: Locator

  Returns boolean

makeDescriptor

• makeDescriptor(ident: Ident, range: string): Descriptor

• Creates a package descriptor.

  ---

  Parameters

  • ident: Ident

    The base ident (see makeIdent)

  • range: string

    The range to attach (eg. ^1.0.0)

  Returns Descriptor

makeIdent

• makeIdent(scope: null | string, name: string): Ident

• Creates a package ident.

  ---

  Parameters

  • scope: null | string

    The package scope without the @ prefix (eg. types)

  • name: string

    The name of the package

  Returns Ident

makeLocator

• makeLocator(ident: Ident, reference: string): Locator

• Creates a package locator.

  ---

  Parameters

  • ident: Ident

    The base ident (see makeIdent)

  • reference: string

    The reference to attach (eg. 1.0.0)

  Returns Locator

makeRange

• makeRange(__namedParameters: { params: null | ParsedUrlQuery; protocol: null | string; selector: string; source: null | string }): string

• Turn the components returned by parseRange back into a string. Check parseRange for more details.

  ---

  Parameters

  • __namedParameters: { params: null | ParsedUrlQuery; protocol: null | string; selector: string; source: null | string }

  Returns string

parseDescriptor

• parseDescriptor(string: string, strict?: boolean): Descriptor

• Parses a string into a descriptor

  Throws an error if the descriptor cannot be parsed.

  ---

  Parameters

  • string: string

    The descriptor string (eg. lodash@^1.0.0)

  • strict: boolean = false

    If false, the range is optional (unknown will be used as fallback)

  Returns Descriptor

parseFileStyleRange

• parseFileStyleRange(range: string, __namedParameters: { protocol: string }): { parentLocator: Locator; path: PortablePath }

• File-style ranges are bound to a parent locators that we need in order to resolve relative paths to the location of their parent packages. This function wraps parseRange to automatically extract the parent locator from the bindings and return it along with the selector.

  ---

  Parameters

  • range: string

  • __namedParameters: { protocol: string }

  Returns { parentLocator: Locator; path: PortablePath }

  • parentLocator: Locator

  • path: PortablePath

parseIdent

• parseIdent(string: string): Ident

• Parses a string into an ident.

  Throws an error if the ident cannot be parsed.

  ---

  Parameters

  • string: string

    The ident string (eg. @types/lodash)

  Returns Ident

parseLocator

• parseLocator(string: string, strict?: boolean): Locator

• Parses a string into a locator

  Throws an error if the locator cannot be parsed.

  ---

  Parameters

  • string: string

    The locator string (eg. lodash@1.0.0)

  • strict: boolean = false

    If false, the reference is optional (unknown will be used as fallback)

  Returns Locator

parseRange

• parseRange<Opts>(range: string, opts?: Opts): ParseRangeReturnType<Opts>

• Parses a range into its constituents. Ranges typically follow these forms, with both protocol and bindings being optionals:

  <protocol>:<selector>::<bindings>
  <protocol>:<source>#<selector>::<bindings>

  The selector is intended to "refine" the source, and is required. The source itself is optional (for instance we don't need it for npm packages, but we do for git dependencies).

  ---

  Type parameters

  • Opts: ParseRangeOptions

  Parameters

  • range: string

  • optionalopts: Opts

  Returns ParseRangeReturnType<Opts>

prettyDependent

• prettyDependent(configuration: Configuration, locator: Locator, descriptor: null | Descriptor): string

• Returns a string that is suitable to be printed to stdout. Based on the configuration it may include color sequences.

  ---

  Parameters

  • configuration: Configuration

    Reference configuration

  • locator: Locator

    The locator to pretty print

  • descriptor: null | Descriptor

    The descriptor that depends on it

  Returns string

prettyDescriptor

• prettyDescriptor(configuration: Configuration, descriptor: Descriptor): string

• Returns a string that is suitable to be printed to stdout. Based on the configuration it may include color sequences.

  ---

  Parameters

  • configuration: Configuration

    Reference configuration

  • descriptor: Descriptor

    The descriptor to pretty print

  Returns string

prettyIdent

• prettyIdent(configuration: Configuration, ident: Ident): string

• Returns a string that is suitable to be printed to stdout. Based on the configuration it may include color sequences.

  ---

  Parameters

  • configuration: Configuration

    Reference configuration

  • ident: Ident

    The ident to pretty print

  Returns string

prettyLocator

• prettyLocator(configuration: Configuration, locator: Locator): string

• Returns a string that is suitable to be printed to stdout. Based on the configuration it may include color sequences.

  ---

  Parameters

  • configuration: Configuration

    Reference configuration

  • locator: Locator

    The locator to pretty print

  Returns string

prettyLocatorNoColors

• prettyLocatorNoColors(locator: Locator): string

• Returns a string that is suitable to be printed to stdout. It will never be colored.

  ---

  Parameters

  • locator: Locator

    The locator to pretty print

  Returns string

prettyRange

• prettyRange(configuration: Configuration, range: string): string

• Returns a string that is suitable to be printed to stdout. Based on the configuration it may include color sequences.

  ---

  Parameters

  • configuration: Configuration

    Reference configuration

  • range: string

  Returns string

prettyReference

• prettyReference(configuration: Configuration, reference: string): string

• Returns a string that is suitable to be printed to stdout. Based on the configuration it may include color sequences.

  ---

  Parameters

  • configuration: Configuration

    Reference configuration

  • reference: string

    The reference to pretty print

  Returns string

prettyResolution

• prettyResolution(configuration: Configuration, descriptor: Descriptor, locator: null | Locator): string

• Returns a string that is suitable to be printed to stdout. Based on the configuration it may include color sequences.

  ---

  Parameters

  • configuration: Configuration

    Reference configuration

  • descriptor: Descriptor

    The descriptor to pretty print

  • locator: null | Locator

    The locator is resolves to

  Returns string

prettyWorkspace

• prettyWorkspace(configuration: Configuration, workspace: Workspace): string

• Returns a string that is suitable to be printed to stdout. Based on the configuration it may include color sequences.

  ---

  Parameters

  • configuration: Configuration

    Reference configuration

  • workspace: Workspace

    The workspace to pretty print

  Returns string

renamePackage

• renamePackage(pkg: Package, locator: Locator): Package

• Deep copies a package then change its locator to something else.

  ---

  Parameters

  • pkg: Package

    The source package

  • locator: Locator

    Its new new locator

  Returns Package

slugifyIdent

• slugifyIdent(ident: Ident): string

• Returns a string from an ident, formatted as a slug (eg. @types-lodash).

  ---

  Parameters

  • ident: Ident

  Returns string

slugifyLocator

• slugifyLocator(locator: Locator): Filename

• Returns a string from a locator, formatted as a slug (eg. @types-lodash-npm-1.0.0-abcdef1234).

  ---

  Parameters

  • locator: Locator

  Returns Filename

sortDescriptors

• sortDescriptors(descriptors: Iterable<Descriptor>): Descriptor[]

• Sorts a list of descriptors, first by their idents then by their ranges.

  ---

  Parameters

  • descriptors: Iterable<Descriptor>

  Returns Descriptor[]

stringifyDescriptor

• stringifyDescriptor(descriptor: Descriptor): string

• Returns a string from a descriptor (eg. @types/lodash@^1.0.0).

  ---

  Parameters

  • descriptor: Descriptor

  Returns string

stringifyIdent

• stringifyIdent(ident: Ident): string

• Returns a string from an ident (eg. @types/lodash).

  ---

  Parameters

  • ident: Ident

  Returns string

stringifyLocator

• stringifyLocator(locator: Locator): string

• Returns a string from a descriptor (eg. @types/lodash@1.0.0).

  ---

  Parameters

  • locator: Locator

  Returns string

tryParseDescriptor

• tryParseDescriptor(string: string, strict?: boolean): Descriptor | null

• Parses a string into a descriptor

  Returns null if the descriptor cannot be parsed.

  ---

  Parameters

  • string: string

    The descriptor string (eg. lodash@^1.0.0)

  • strict: boolean = false

    If false, the range is optional (unknown will be used as fallback)

  Returns Descriptor | null

tryParseIdent

• tryParseIdent(string: string): Ident | null

• Parses a string into an ident.

  Returns null if the ident cannot be parsed.

  ---

  Parameters

  • string: string

    The ident string (eg. @types/lodash)

  Returns Ident | null

tryParseLocator

• tryParseLocator(string: string, strict?: boolean): Locator | null

• Parses a string into a locator

  Returns null if the locator cannot be parsed.

  ---

  Parameters

  • string: string

    The locator string (eg. lodash@1.0.0)

  • strict: boolean = false

    If false, the reference is optional (unknown will be used as fallback)

  Returns Locator | null

tryParseRange

• tryParseRange<Opts>(range: string, opts?: Opts): ParseRangeReturnType<Opts> | null

• Parses a range into its constituents. Ranges typically follow these forms, with both protocol and bindings being optionals:

  <protocol>:<selector>::<bindings>
  <protocol>:<source>#<selector>::<bindings>

  The selector is intended to "refine" the source, and is required. The source itself is optional (for instance we don't need it for npm packages, but we do for git dependencies).

  ---

  Type parameters

  • Opts: ParseRangeOptions

  Parameters

  • range: string

  • optionalopts: Opts

  Returns ParseRangeReturnType<Opts> | null

virtualizeDescriptor

• virtualizeDescriptor(descriptor: Descriptor, entropy: string): Descriptor

• Creates a new virtual descriptor from a non virtual one.

  ---

  Parameters

  • descriptor: Descriptor

    The descriptor to virtualize

  • entropy: string

    A hash that provides uniqueness to this virtualized descriptor (normally a locator hash)

  Returns Descriptor

virtualizePackage

• virtualizePackage(pkg: Package, entropy: string): Package

• Creates a new virtual package from a non virtual one.

  ---

  Parameters

  • pkg: Package

    The package to virtualize

  • entropy: string

    A hash that provides uniqueness to this virtualized package (normally a locator hash)

  Returns Package