@eryx/project Module

Project manifest and lockfile helpers.

As the project manifest is a TOML file, programmatic changes can cause a complete re-formatting of the file. As such, this library exposes a CST view for the manifest, and is it strongly recommended to make edits within the CST view. See the toml documentation for more details on this.

Summary

Functions

project.parse(source: string) → ManifestDocument
project.load(filePath: string?) → ManifestDocument
project.find(start: string?) → string?
project.loadNearest(start: string?) → ManifestDocument?
project.getTool(document: ManifestDocument, name: string) → any
project.encode(document: ManifestDocument) → string
project.save(document: ManifestDocument, filePath: string?) → ()
lock.parse(source: string) → LockDocument
lock.load(rootOrPath: string?) → LockDocument
lock.exists(root: string?) → boolean
lock.encode(document: LockDocument) → string
lock.save(document: LockDocument, filePath: string?) → ()

API Reference

Functions

project.parse

Parse an eryx.toml source string.

project.parse(source: string) → ManifestDocument

project.load

Load an eryx.toml file. Defaults to ./eryx.toml.

project.load(filePath: string?) → ManifestDocument

project.find

Find the nearest eryx.toml, searching upward from start or the current working directory. Returns nil when no project manifest is found.

project.find(start: string?) → string?

project.loadNearest

Load the nearest project manifest, searching upward from start or the current working directory.

project.loadNearest(start: string?) → ManifestDocument?

project.getTool

Return a third-party [tool.<name>] table from a parsed manifest document. The returned value is read from the CST-backed document so callers can inspect the exact currently loaded config without Eryx validating that tool's schema.

project.getTool(document: ManifestDocument, name: string) → any

project.encode

Encode a manifest document. Unchanged CST documents round-trip exactly; changed CST documents preserve as much source formatting as the TOML CST encoder can patch.

project.encode(document: ManifestDocument) → string

project.save

Write a manifest document to disk. Defaults to the path it was loaded from, or ./eryx.toml for documents created from a string.

project.save(document: ManifestDocument, filePath: string?) → ()

lock.parse

Parse an eryx.lock source string.

lock.parse(source: string) → LockDocument

lock.load

Load an eryx.lock file. If rootOrPath is a directory, eryx.lock inside that directory is loaded. If it is a file path, that file is loaded.

lock.load(rootOrPath: string?) → LockDocument

lock.exists

Return whether a lockfile exists for a project root.

lock.exists(root: string?) → boolean

lock.encode

Encode a lockfile document.

lock.encode(document: LockDocument) → string

lock.save

Write a lockfile document to disk. Defaults to the path it was loaded from, or ./eryx.lock for documents created from a string.

lock.save(document: LockDocument, filePath: string?) → ()

Types

Author
type Author = { name: string, email: string?, url: string? }
name: string
email: string?
url: string?

ProjectMetadata
type ProjectMetadata = { name: string, version: string, private: boolean?, description: string?, authors: { Author }?, license: string?, licenseFile: string?, keywords: { string }?, sourceRoot: string? }
name: string
version: string
private: boolean?
description: string?
authors: { Author }?
license: string?
licenseFile: string?
keywords: { string }?
sourceRoot: string?

Links
type Links = { [string]: string? }
homepage: string?
documentation: string?
source: string?
bugs: string?

GitDependency

Represents a dependency that is available on git

Exactly one of rev, tag or branch must be specified

type GitDependency = { git: string, rev: string, subdir: string? } | { git: string, tag: string, subdir: string? } | { git: string, branch: string, subdir: string? }

PathDependency

Represents a dependency that is on the local filesystem

This dependency will not be copied, and is only referenced as an alias. A child eryx.toml is ignored.

type PathDependency = { path: string }
path: string

LocalDependency

Represents a dependency that is on the local filesystem

The contents of this dependency will be copied to the local project, and any root eryx.toml will be used for child dependency resolution

type LocalDependency = { local: string }
local: string

UrlDependency

Represents a dependency that is a downloadable archive

The archive may optionally include an eryx.toml, which will be used for child depdendency resolution

type UrlDependency = { url: string, sha256: string? }
url: string
sha256: string?

RepositoryDependency

Represents a package available on a repository

type RepositoryDependency = { repo: string, version: semver.Range?, package: string? }
repo: string
version: semver.Range?
package: string?

Dependency
type Dependency = string | GitDependency | PathDependency | LocalDependency | UrlDependency | RepositoryDependency

Dependencies
type Dependencies = { [string]: Dependency }

Workspace
type Workspace = { [string]: string }

BuildTarget
type BuildTarget = { output: string, entrypoint: string, include: { string }?, exclude: { string }?, sourceExe: string? }
output: string
entrypoint: string
include: { string }?
exclude: { string }?
sourceExe: string?

TestConfig
type TestConfig = { include: { string }?, exclude: { string }? }
include: { string }?
exclude: { string }?

Manifest
type Manifest = { manifestVersion: number, project: ProjectMetadata, links: Links?, scripts: { [string]: string }?, repositories: { [string]: string }?, workspace: Workspace?, dependencies: Dependencies?, devDependencies: Dependencies?, build: { [string]: BuildTarget }?, test: TestConfig?, raw: { [any]: any } }
manifestVersion: number
project: ProjectMetadata
links: Links?
scripts: { [string]: string }?
repositories: { [string]: string }?
workspace: Workspace?
dependencies: Dependencies?
devDependencies: Dependencies?
build: { [string]: BuildTarget }?
test: TestConfig?
raw: { [any]: any }

ManifestDocument
type ManifestDocument = { path: string?, root: string?, cst: any, manifest: Manifest }
path: string?
root: string?
cst: any
manifest: Manifest

LockedDependency
type LockedDependency = { name: string, version: string?, source: string? }
name: string
version: string?
source: string?

LockedPackage
type LockedPackage = { name: string, version: string?, source: string?, checksum: string?, rev: string?, dependencies: { LockedDependency }?, raw: { [any]: any } }
name: string
version: string?
source: string?
checksum: string?
rev: string?
dependencies: { LockedDependency }?
raw: { [any]: any }

Lockfile
type Lockfile = { version: number, eryxVersion: string?, generatedAt: string?, packages: { LockedPackage }, raw: { [any]: any } }
version: number
eryxVersion: string?
generatedAt: string?
packages: { LockedPackage }
raw: { [any]: any }

LockDocument
type LockDocument = { path: string?, root: string?, cst: any, lockfile: Lockfile }
path: string?
root: string?
cst: any
lockfile: Lockfile