vlt / docs

    • PricingBenchmarks (opens in new window)Community (opens in new window)Feedback
  • Overview
    • Overview
    • browser
    • index
    • Reference
  • Classes
  • Spec
  • Type Aliases
  • GitSelectorParsed
  • Scope
  • SpecLike<Type>
  • SpecLikeBase
  • SpecOptions
  • SpecOptionsFilled
  • SpecType
  • Functions
  • assertPathSafeName()
  • isPathSafeName()
  • References
  • currentDefaultRegistryName
  • defaultGitHostArchives
  • defaultGitHosts
  • defaultJsrRegistries
  • defaultRegistries
  • defaultRegistryName
  • defaultScopeRegistries
  • getNormalizeFile
  • getOptions
  • gitHostWebsites
  • isSpec
  • kCustomInspect
  • NodeJSDependenciesOptions
  1. Client
  2. /
  3. API Reference
  4. /
  5. @vltpkg/spec
  6. /
  7. index

index

Classes

Spec

Defined in: spec/src/index.ts:17

The base, isomorphic Spec implementation.

Extends

  • Spec

Implements

  • SpecLike<Spec>

Constructors

new Spec()
TypeScript
new Spec(
   name, 
   bareSpec, 
   options?): Spec

Defined in: spec/src/browser.ts:368

The initial value of Object.prototype.constructor is the standard built-in Object constructor.

Parameters
ParameterType
namestring
bareSpecstring
options?SpecOptions
Returns

Spec

Inherited from

Spec.constructor

new Spec()
TypeScript
new Spec(spec, options?): Spec

Defined in: spec/src/browser.ts:369

The initial value of Object.prototype.constructor is the standard built-in Object constructor.

Parameters
ParameterType
specstring
options?SpecOptions
Returns

Spec

Inherited from

Spec.constructor

new Spec()
TypeScript
new Spec(
   spec, 
   bareOrOptions?, 
   options?): Spec

Defined in: spec/src/browser.ts:370

The initial value of Object.prototype.constructor is the standard built-in Object constructor.

Parameters
ParameterType
specstring | Spec
bareOrOptions?string | SpecOptions
options?SpecOptions
Returns

Spec

Inherited from

Spec.constructor

Properties

PropertyTypeDefault valueDescriptionInherited from
bareSpecstringundefinedjust the part AFTER the name, so 1.x in foo@1.xSpecLike.bareSpec Spec.bareSpec
catalog?stringundefined-Spec.catalog
constructortypeof SpecundefinedThe initial value of Object.prototype.constructor is the standard built-in Object constructor.BrowserSpec.constructor
conventionalRegistryTarball?stringundefinedconventional location of the tarball on the registry, if it can be guessed. This is only attempted if the spec is a registry type, with a single version comparator. This can be used to elide resolved urls that are repetitive and predictable.SpecLike.conventionalRegistryTarball Spec.conventionalRegistryTarball
distTag?stringundefineda dist-tag like 'latest'SpecLike.distTag Spec.distTag
file?stringundefinedfile path for file:// url specsSpecLike.file Spec.file
gitCommittish?stringundefinedthe commit value we will check outSpecLike.gitCommittish Spec.gitCommittish
gitRemote?stringundefinedthe git remote to fetch fromSpecLike.gitRemote Spec.gitRemote
gitSelector?stringundefinedthe committish, semver range, and/or path portion of a git remoteSpecLike.gitSelector Spec.gitSelector
gitSelectorParsed?GitSelectorParsedundefinedthe parsed '::'-separated key/value pairs: semver:<range> and path:<subpath>SpecLike.gitSelectorParsed Spec.gitSelectorParsed
namestringundefinedthe name portion, so foo in foo@1.xSpecLike.name Spec.name
namedGitHost?stringundefinedgithub, gitlab, bitbucket, gist, etc.SpecLike.namedGitHost Spec.namedGitHost
namedGitHostPath?stringundefinedthe path that's parsed when we have a named git hostSpecLike.namedGitHostPath Spec.namedGitHostPath
namedJsrRegistry?stringundefined-Spec.namedJsrRegistry
namedRegistry?stringundefinedIn specs like foo@npm:bar@1, this is the 'npm' part. Other registries can be mapped using the registries option.SpecLike.namedRegistry Spec.namedRegistry
optionsSpecOptionsFilledundefinedoptions passed to the constructor, plus defaultsSpecLike.options Spec.options
overriddenbooleanfalseIs this a spec that overrides another spec?SpecLike.overridden Spec.overridden
range?Rangeundefinedparsed semver range specifierSpecLike.range Spec.range
registry?stringundefinedregistry to consult to resolve this specSpecLike.registry Spec.registry
registrySpec?stringundefinedsemver range or dist-tag for resolving against a packumentSpecLike.registrySpec Spec.registrySpec
remoteURL?stringundefinedURL to download a tarball from, if it can be determined. This is set for url specs of course, but also git remotes on known hosts that provide a gitHostArchive template.SpecLike.remoteURL Spec.remoteURL
scope?`@${string}`undefinedthe name's scope, so @acme in @acme/foo@1.xSpecLike.scope Spec.scope
scopeRegistry?stringundefinedif the name is scoped, and there's a registry associated with the scope, then this is that registrySpecLike.scopeRegistry Spec.scopeRegistry
semver?stringundefinedspec to resolve against available versionsSpecLike.semver Spec.semver
specstringundefinedthe full named specifier passed to the constructorSpecLike.spec Spec.spec
subspec?Specundefinedin bar@npm:foo@1.x, this is the spec for foo@1.xSpecLike.subspec Spec.subspec
typeSpecTypeundefinedthe type of spec that this is, ultimatelySpecLike.type Spec.type
workspace?stringundefinedthe package name or path of the workspace being referencedSpecLike.workspace Spec.workspace
workspaceSpec?stringundefinedthe specifier when using workspace: specs This can be either a semver range, *, ~, or ^, if the name is not modified. Or, it can include a workspace package name or path, like workspace:packages/foo@* or workspace:@scope/foo@*.SpecLike.workspaceSpec Spec.workspaceSpec
nodejsDependencies?NodeJSDependenciesOptionsundefined-Spec.nodejsDependencies

Accessors

final
Get Signature
TypeScript
get final(): Spec & object

Defined in: spec/src/browser.ts:337

Return the final entry in the chain of subspecs When deciding which thing to actually fetch, spec.final is the thing to look at.

Returns

Spec & object

Implementation of
TypeScript
SpecLike.final
Inherited from

Spec.final

Methods

[kCustomInspect]()
TypeScript
kCustomInspect: string

Defined in: spec/src/index.ts:18

Parameters
ParameterType
_depth?number
options?InspectOptions
Returns

string

Overrides

Spec.[kCustomInspect]

toString()
TypeScript
toString(): string

Defined in: spec/src/browser.ts:356

Normally, the string value of a Spec is just the string passed in to be parsed. However, in the case of a chain of subspecs, like foo@npm:bar@npm:baz@npm:quux@latest, this simplifies out the middle parts of the chain, returning just foo@npm:quux@latest

Returns

string

Implementation of
TypeScript
SpecLike.toString
Inherited from

Spec.toString

parse()
Call Signature
TypeScript
static parse(
   name, 
   bareSpec, 
   options?): Spec

Defined in: spec/src/browser.ts:246

Create a Spec object from a full spec, name+bareSpec, or Spec object

Note: If a Spec object is provided, it is returned as-is, without investigating whether the options match.

Parameters
ParameterType
namestring
bareSpecstring
options?SpecOptions
Returns

Spec

Inherited from

Spec.parse

Call Signature
TypeScript
static parse(spec, options?): Spec

Defined in: spec/src/browser.ts:251

Create a Spec object from a full spec, name+bareSpec, or Spec object

Note: If a Spec object is provided, it is returned as-is, without investigating whether the options match.

Parameters
ParameterType
specstring
options?SpecOptions
Returns

Spec

Inherited from

Spec.parse

Call Signature
TypeScript
static parse(spec, options?): Spec

Defined in: spec/src/browser.ts:252

Create a Spec object from a full spec, name+bareSpec, or Spec object

Note: If a Spec object is provided, it is returned as-is, without investigating whether the options match.

Parameters
ParameterType
specSpec
options?SpecOptions
Returns

Spec

Inherited from

Spec.parse

parseArgs()
TypeScript
static parseArgs(specOrBareSpec, opts?): Spec

Defined in: spec/src/browser.ts:263

Parameters
ParameterType
specOrBareSpecstring
opts?SpecOptions
Returns

Spec

Inherited from

Spec.parseArgs

parseGitSelector()
TypeScript
static parseGitSelector(selector, spec?): [GitSelectorParsed, string, Range]

Defined in: spec/src/browser.ts:878

Should only ever be called with the bit that comes AFTER the # in the git remote url.

Parameters
ParameterType
selectorstring
spec?Spec
Returns

[GitSelectorParsed, string, Range]

Inherited from

Spec.parseGitSelector

Type Aliases

GitSelectorParsed

TypeScript
type GitSelectorParsed = object;

Defined in: spec/src/types.ts:48

Type declaration

NameType
path?string
semver?string

Scope

TypeScript
type Scope = `@${string}`;

Defined in: spec/src/types.ts:7

SpecLike<Type>

TypeScript
type SpecLike<Type> = SpecLikeBase & object;

Defined in: spec/src/types.ts:164

Type declaration

NameType
finalType
subspec?Type

Type Parameters

Type Parameter
Type extends SpecLikeBase

SpecLikeBase

TypeScript
type SpecLikeBase = object;

Defined in: spec/src/types.ts:56

Type declaration

NameTypeDescription
bareSpecstringjust the part AFTER the name, so 1.x in foo@1.x
conventionalRegistryTarball?stringconventional location of the tarball on the registry, if it can be guessed. This is only attempted if the spec is a registry type, with a single version comparator. This can be used to elide resolved urls that are repetitive and predictable.
distTag?stringa dist-tag like 'latest'
file?stringfile path for file:// url specs
finalSpecLikeBasegetter that retrieves the actual spec value to be used
gitCommittish?stringthe commit value we will check out
gitRemote?stringthe git remote to fetch from
gitSelector?stringthe committish, semver range, and/or path portion of a git remote
gitSelectorParsed?GitSelectorParsedthe parsed '::'-separated key/value pairs: semver:<range> and path:<subpath>
namestringthe name portion, so foo in foo@1.x
namedGitHost?stringgithub, gitlab, bitbucket, gist, etc.
namedGitHostPath?stringthe path that's parsed when we have a named git host
namedRegistry?stringIn specs like foo@npm:bar@1, this is the 'npm' part. Other registries can be mapped using the registries option.
optionsSpecOptionsFilledoptions passed to the constructor, plus defaults
overriddenbooleanIs this a spec that overrides another spec?
range?Rangeparsed semver range specifier
registry?stringregistry to consult to resolve this spec
registrySpec?stringsemver range or dist-tag for resolving against a packument
remoteURL?stringURL to download a tarball from, if it can be determined. This is set for url specs of course, but also git remotes on known hosts that provide a gitHostArchive template.
scope?Scopethe name's scope, so @acme in @acme/foo@1.x
scopeRegistry?stringif the name is scoped, and there's a registry associated with the scope, then this is that registry
semver?stringspec to resolve against available versions
specstringthe full named specifier passed to the constructor
subspec?SpecLikeBasein bar@npm:foo@1.x, this is the spec for foo@1.x
typeSpecTypethe type of spec that this is, ultimately
workspace?stringthe package name or path of the workspace being referenced
workspaceSpec?stringthe specifier when using workspace: specs This can be either a semver range, *, ~, or ^, if the name is not modified. Or, it can include a workspace package name or path, like workspace:packages/foo@* or workspace:@scope/foo@*.
toString()string-

SpecOptions

TypeScript
type SpecOptions = { [k in keyof SpecOptionsFilled]?: SpecOptionsFilled[k] };

Defined in: spec/src/types.ts:3

SpecOptionsFilled

TypeScript
type SpecOptionsFilled = object;

Defined in: spec/src/types.ts:9

Type declaration

NameTypeDescription
catalogRecord<string, string>-
catalogs?Record<string, Record<string, string>>-
default-registry-aliasstringThe name of the registry alias (a key in registries) that bare specs (e.g. foo@latest) and transitive deps without an explicit registry protocol resolve through, when no registry or scoped-registries entry applies. Defaults to 'npm'. The npm alias itself has no built-in URL -- it must be configured (e.g. via vlt setup), otherwise bare specs resolve with spec.registry === undefined.
git-host-archivesRecord<string, string>tarball hosting services for hosts listed in git-hosts
git-hostsRecord<string, string>shorthand prefix names for known git hosts
jsr-registriesRecord<string, string>registries that work like https://npm.jsr.io
registriesRecord<string, string>shorthand prefix names for known registries
registry?stringThe registry where a spec should be resolved against. There is no default. If no registry is configured, registry-type specs parsed without one will have spec.registry === undefined, and anything that needs to build a registry URL will fail. Named registry aliases (gh:, jsr:) and scoped-registries are unaffected. For bare specs, this takes precedence over the default-registry-alias lookup but not over a matching scoped-registries entry.
scoped-registriesRecord<Scope, string>registries mapped to a @scope

SpecType

TypeScript
type SpecType = "file" | "git" | "registry" | "remote" | "workspace" | "catalog";

Defined in: spec/src/types.ts:53

Functions

assertPathSafeName()

TypeScript
function assertPathSafeName(name, from?): void

Defined in: spec/src/valid-name.ts:26

Throw unless name is usable as a filesystem path segment. from is the actionable origin of the name: a tarball URL, git spec, or manifest path.

Parameters

ParameterType
nameunknown
from?string

Returns

void

isPathSafeName()

TypeScript
function isPathSafeName(name): boolean

Defined in: spec/src/valid-name.ts:18

Is a given value usable as a filesystem path segment?

Parameters

ParameterType
nameunknown

Returns

boolean

References

currentDefaultRegistryName

Re-exports currentDefaultRegistryName

defaultGitHostArchives

Re-exports defaultGitHostArchives

defaultGitHosts

Re-exports defaultGitHosts

defaultJsrRegistries

Re-exports defaultJsrRegistries

defaultRegistries

Re-exports defaultRegistries

defaultRegistryName

Re-exports defaultRegistryName

defaultScopeRegistries

Re-exports defaultScopeRegistries

getNormalizeFile

Re-exports getNormalizeFile

getOptions

Re-exports getOptions

gitHostWebsites

Re-exports gitHostWebsites

isSpec

Re-exports isSpec

kCustomInspect

Re-exports kCustomInspect

NodeJSDependenciesOptions

Re-exports NodeJSDependenciesOptions

PreviousbrowserNextReference

On this page

  • Classes
  • Spec
  • Type Aliases
  • GitSelectorParsed
  • Scope
  • SpecLike<Type>
  • SpecLikeBase
  • SpecOptions
  • SpecOptionsFilled
  • SpecType
  • Functions
  • assertPathSafeName()
  • isPathSafeName()
  • References
  • currentDefaultRegistryName
  • defaultGitHostArchives
  • defaultGitHosts
  • defaultJsrRegistries
  • defaultRegistries
  • defaultRegistryName
  • defaultScopeRegistries
  • getNormalizeFile
  • getOptions
  • gitHostWebsites
  • isSpec
  • kCustomInspect
  • NodeJSDependenciesOptions

Deploy your package on vlt.io

Publish scoped and private packages, manage organizations and access, and give every developer and CI environment a consistent source for public and private JavaScript dependencies.

Publish now