Skip to main content

structUtils

Index

Functions

areDescriptorsEqual

areIdentsEqual

  • Returns true if the idents are equal


    Parameters

    Returns boolean

areLocatorsEqual

  • Returns true if the locators are equal


    Parameters

    Returns boolean

areVirtualPackagesEquivalent

  • 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

    Returns boolean

bindDescriptor

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

    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

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


    Parameters

    Returns Package

devirtualizeDescriptor

  • Returns a new devirtualized descriptor based on a virtualized descriptor


    Parameters

    Returns Descriptor

devirtualizeLocator

  • Returns a new devirtualized locator based on a virtualized locator


    Parameters

    Returns Locator

ensureDevirtualizedDescriptor

  • Returns a descriptor guaranteed to be devirtualized


    Parameters

    Returns Descriptor

ensureDevirtualizedLocator

  • Returns a locator guaranteed to be devirtualized


    Parameters

    Returns Locator

getIdentVendorPath

  • 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

    Returns PortablePath

isPackageCompatible

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


    Parameters

    Returns boolean

isVirtualDescriptor

  • isVirtualDescriptor(descriptor: Descriptor): boolean
  • Returns true if the descriptor is virtual.


    Parameters

    Returns boolean

isVirtualLocator

  • isVirtualLocator(locator: Locator): boolean
  • Returns true if the locator is virtual.


    Parameters

    Returns boolean

makeDescriptor

  • 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

  • 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 }

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

  • 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

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


    Parameters

    Returns string

prettyIdent

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


    Parameters

    Returns string

prettyLocator

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


    Parameters

    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

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


    Parameters

    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

  • 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

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


    Parameters

    Returns string

renamePackage

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


    Parameters

    Returns Package

slugifyIdent

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


    Parameters

    Returns string

slugifyLocator

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


    Parameters

    Returns Filename

sortDescriptors

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


    Parameters

    Returns Descriptor[]

stringifyDescriptor

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


    Parameters

    Returns string

stringifyIdent

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


    Parameters

    Returns string

stringifyLocator

  • stringifyLocator(locator: Locator): string
  • Returns a string from a descriptor (eg. @types/lodash@1.0.0).


    Parameters

    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

  • 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

  • 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