node2nix

https://volkswagenfeature.github.io
Admin
node2nix is a tool that generates Nix expressions from NPM package specifications, enabling the...
Tokens:9,839
Snippets:85
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Package Constructor

Source: https://volkswagenfeature.github.io/Package.html

Initializes a new Package object with deployment configuration, lock file details, parent package reference, name, version specifier, base directory, production mode flag, and sources cache.

```APIDOC
## Package Constructor

### Description
Creates a new package object.

### Parameters
#### Path Parameters
- **deploymentConfig** (DeploymentConfig) - Required - An object capturing global deployment settings
- **lock** (Object) - Required - Contents of a package lock file (or undefined if no lock exists)
- **parent** (Package) - Required - Reference to the package that embeds the constructed package, or null if there is no parent
- **name** (String) - Required - Name of a Node.js package
- **versionSpec** (String) - Required - Version specifier of a Node.js package, such as an exact version number, version range, URL, or GitHub identifier
- **baseDir** (String) - Required - Directory in which the referrer's package.json configuration resides
- **production** (Boolean) - Required - Indicates whether we deploy in production mode or development mode. In development mode, also the development dependencies will be included.
- **sourcesCache** (SourcesCache) - Required - Cache that contains references to all sources that need to be obtained

### Source
* Package.js, line 8
```

--------------------------------

### Initialize DeploymentConfig

Source: https://volkswagenfeature.github.io/DeploymentConfig.js.html

Constructs a new DeploymentConfig instance. Use this to set global deployment configuration properties such as registries, production mode, dependency inclusion, output directory, and cache behavior.

```javascript
function DeploymentConfig(registries, production, includePeerDependencies, flatten, nodePackage, outputDir, bypassCache, stripOptionalDependencies) {
    this.registries = registries;
    this.production = production;
    this.includePeerDependencies = includePeerDependencies;
    this.flatten = flatten;
    this.nodePackage = nodePackage;
    this.outputDir = outputDir;
    this.bypassCache = bypassCache;
    this.stripOptionalDependencies = stripOptionalDependencies;
}

exports.DeploymentConfig = DeploymentConfig;
```

--------------------------------

### Package Constructor

Source: https://volkswagenfeature.github.io/Package.js.html

Initializes a new Package object with configuration, lock information, parent package reference, name, version specifier, base directory, production mode flag, and sources cache.

```APIDOC
## Package Constructor

### Description
Creates a new package object. A representation of an NPM package that is obtained from an external source, that may have dependencies on other packages, and may bundle packages in its node_modules/ sub folder.

### Parameters
#### Path Parameters
- **deploymentConfig** (DeploymentConfig) - An object capturing global deployment settings
- **lock** (Object) - Contents of a package lock file (or undefined if no lock exists)
- **parent** (Package) - Reference to the package that embeds the constructed package, or null if there is no parent
- **name** (String) - Name of a Node.js package
- **versionSpec** (String) - Version specifier of a Node.js package, such as an exact version number, version range, URL, or GitHub identifier
- **baseDir** (String) - Directory in which the referrer's package.json configuration resides
- **production** (Boolean) - Indicates whether we deploy in production mode or development mode. In development mode, also the development dependencies will be included.
- **sourcesCache** (SourcesCache) - Cache that contains references to all sources that need to be obtained

### Request Example
```javascript
// Example usage (conceptual, actual parameters depend on context)
const newPackage = new Package(deploymentConfig, lock, parent, 'my-package', '^1.0.0', '/path/to/base', true, sourcesCache);
```

### Response
#### Success Response (200)
- **Package** (Object) - A newly constructed Package instance.

#### Response Example
```json
{
  "message": "Package object created successfully"
}
```
```

--------------------------------

### Initialize SourcesCache

Source: https://volkswagenfeature.github.io/SourcesCache.js.html

Constructs a new SourcesCache instance. Initializes an empty object to store sources.

```javascript
function SourcesCache() {
    this.sources = {};
}
```

--------------------------------

### Initialize Package Object

Source: https://volkswagenfeature.github.io/Package.js.html

Constructs a new Package object, initializing properties like deployment configuration, parent package, and source information. It uses Source.constructSource to determine the package's origin.

```javascript
function Package(deploymentConfig, lock, parent, name, versionSpec, baseDir, production, sourcesCache) {
    this.deploymentConfig = deploymentConfig;
    this.lock = lock;
    this.parent = parent;
    this.production = production;
    this.sourcesCache = sourcesCache;
    this.source = Source.constructSource(deploymentConfig.registries, baseDir, deploymentConfig.outputDir, name, versionSpec, deploymentConfig.stripOptionalDependencies);
    this.requiredDependencies = {};
    this.providedDependencies = {};
}
```

--------------------------------

### Import Dependencies

Source: https://volkswagenfeature.github.io/SourcesCache.js.html

Imports necessary modules: 'nijs' for Nix AST manipulation and 'inherit' for inheritance.

```javascript
var nijs = require('nijs');
var inherit = require('nijs/lib/ast/util/inherit.js').inherit;
```

--------------------------------

### SourcesCache Constructor

Source: https://volkswagenfeature.github.io/SourcesCache.html

Initializes a new instance of the SourcesCache.

```APIDOC
## SourcesCache()

### Description
A cache store that memorizes all packages to obtain from external sources.

### Constructor
#### new SourcesCache()
Construct a new source cache instance.

Source:
    
  * SourcesCache.js, line 4

### Extends
  * NixASTNode
```

--------------------------------

### toNixAST Method

Source: https://volkswagenfeature.github.io/SourcesCache.js.html

Converts the SourcesCache into a Nix Abstract Syntax Tree (AST) representation. It sorts sources by identifier before conversion.

```APIDOC
## GET /toNixAST

### Description
Converts the current cache of sources into a Nix AST format. The sources are sorted alphabetically by their identifiers before being converted.

### Method
GET

### Endpoint
/toNixAST

### Parameters
None

### Request Body
None

### Response
#### Success Response (200)
- **ast** (object) - A Nix AST object where keys are source identifiers and values are the Nix AST representation of each source.

### Response Example
```json
{
  "ast": {
    "npm:react@18.2.0": {
      "type": "source",
      "url": "https://registry.npmjs.org/react"
    }
  }
}
```
```

--------------------------------

### Convert Package to Nix AST

Source: https://volkswagenfeature.github.io/Package.js.html

Converts the package definition to a Nix Abstract Syntax Tree (AST). This method populates the AST with dependencies, build inputs, and metadata.

```javascript
Package.prototype.toNixAST = function() {
    var homepage;

    if(typeof this.source.config.homepage == "string" && this.source.config.homepage) {
        homepage = this.source.config.homepage;
    }

    var ast = this.source.toNixAST();
    ast.dependencies = this.generateDependencyAST();
    ast.buildInputs = new nijs.NixExpression("globalBuildInputs");
    ast.meta = {
        description: this.source.config.description,
        homepage: homepage,
        license: this.source.config.license
    };
    ast.production = this.production;
    ast.bypassCache = this.deploymentConfig.bypassCache;
    ast.reconstructLock = (this.lock === undefined);

    return ast;
};
```

--------------------------------

### toNixAST

Source: https://volkswagenfeature.github.io/Package.html

Converts the package's dependency structure into a Nix Abstract Syntax Tree (AST).

```APIDOC
## GET /toNixAST

### Description
Converts the package's dependency structure into a Nix Abstract Syntax Tree (AST).

### Method
GET

### Endpoint
/toNixAST

### See
* NixASTNode#toNixAST

### Source
* Package.js, line 319
```

--------------------------------

### SourcesCache Constructor

Source: https://volkswagenfeature.github.io/SourcesCache.js.html

Initializes a new SourcesCache instance with an empty sources object.

```APIDOC
## SourcesCache Constructor

### Description
Constructs a new SourcesCache instance. This cache stores packages obtained from external sources.

### Method
Constructor

### Endpoint
N/A

### Parameters
None

### Request Body
None

### Response
- **sources** (object) - An empty object to store sources.
```

--------------------------------

### DeploymentConfig Constructor

Source: https://volkswagenfeature.github.io/DeploymentConfig.js.html

The DeploymentConfig class constructor initializes deployment configuration properties. It accepts various parameters to define registries, production mode, dependency inclusion, flattening, package name, output directory, cache bypassing, and stripping of optional dependencies.

```APIDOC
## DeploymentConfig Constructor

### Description
Constructs a new deployment config instance. Stores all global deployment configuration properties.

### Method
Constructor

### Parameters
#### Constructor Parameters
- **registries** (Array<Registry>) - Required - An array of alternative registries for scoped packages.
- **production** (Boolean) - Required - Indicates whether we deploy in production mode or development mode. In development mode, also the development dependencies will be included.
- **includePeerDependencies** (Boolean) - Required - Indicates whether to include peer dependencies with the package.
- **flatten** (Boolean) - Required - Indicates whether to create a flat dependency structure in which dependencies are as high as possible in the graph.
- **nodePackage** (String) - Required - Name of the Node.js package to use from Nixpkgs.
- **outputDir** (String) - Required - Directory in which the nix expression will be written.
- **bypassCache** (Boolean) - Required - Indicates that the content addressable cache should be bypassed.
- **stripOptionalDependencies** (Boolean) - Required - When enabled, the optional dependencies are stripped from the regular dependencies in the NPM registry.

### Request Example
```javascript
const config = new DeploymentConfig(
  registries,
  production,
  includePeerDependencies,
  flatten,
  nodePackage,
  outputDir,
  bypassCache,
  stripOptionalDependencies
);
```

### Response
#### Success Response (200)
- **DeploymentConfig instance** - An instance of the DeploymentConfig class with the provided configuration properties.

#### Response Example
```javascript
// Example of a DeploymentConfig instance (internal representation)
{
  registries: [...],
  production: true,
  includePeerDependencies: false,
  flatten: true,
  nodePackage: "some-package",
  outputDir: "./dist",
  bypassCache: false,
  stripOptionalDependencies: true
}
```
```

--------------------------------

### Bundle Multiple Dependencies

Source: https://volkswagenfeature.github.io/Package.js.html

Bundles a collection of dependencies, resolving and fetching them if necessary. It handles both direct and flattened bundling strategies.

```javascript
Package.prototype.bundleDependencies = function(resolvedDependencies, dependencies, callback) {
    if(dependencies === undefined) {
        callback();
    } else {
        var self = this;

        slasp.fromEach(function(callback) {
            callback(null, dependencies);
        }, function(dependencyName, callback) {
            var versionSpec = dependencies[dependencyName];
            var parentDependency = self.findMatchingProvidedDependencyByParent(dependencyName, versionSpec);

            if(self.isBundledDependency(dependencyName)) {
                self.requiredDependencies[dependencyName] = null;
                callback();
            } else if(parentDependency === null) {
                var pkg = new Package(self.deploymentConfig, self.lock, self, dependencyName, versionSpec, self.source.baseDir, true /* Never include development dependencies of transitive dependencies */, self.sourcesCache);

                slasp.sequence([
                    function(callback) {
                        pkg.source.fetch(callback);
                    },

                    function(callback) {
                        self.sourcesCache.addSource(pkg.source);
                        self.bundleDependency(dependencyName, pkg);
                        resolvedDependencies[dependencyName] = pkg;
                        callback();
                    }
                ], callback);
            } else {
                self.requiredDependencies[dependencyName] = parentDependency; // If there is a parent package that provides the requested dependency -> use it
                callback();
            }

        }, callback);
    }
};
```

--------------------------------

### copyNodeEnvExpr

Source: https://volkswagenfeature.github.io/module-node2nix.html

Writes a copy of the node-env.nix file to a specified path. This is useful for setting up the environment for NPM package builds.

```APIDOC
## copyNodeEnvExpr

### Description
Writes a copy of node-env.nix to a specified path.

### Method
(static) copyNodeEnvExpr

### Parameters
#### Path Parameters
- **nodeEnvNix** (String) - Required - Path to which the NPM package build expression is written
- **callback** (function) - Required - Callback function that gets invoked if the operation is done. If an error has occured, the error parameter is set to the error message.

### Request Example
```json
{
  "nodeEnvNix": "/path/to/write/node-env.nix",
  "callback": "function(error) { ... }"
}
```

### Response
#### Success Response (200)
- **N/A** - This function does not return a value on success, but invokes the callback.

#### Response Example
```json
// Callback is invoked with no arguments on success
```
```

--------------------------------

### Generate Nix Dependency AST

Source: https://volkswagenfeature.github.io/Package.js.html

Generates an Abstract Syntax Tree (AST) for package dependencies. Returns undefined if no dependencies are required.

```javascript
Package.prototype.generateDependencyAST = function() {
    var dependencies = [];
    var dependencyExpr;
    this.dependencies.forEach(function(dependency) {
        dependencyExpr = dependency.toNixAST();
        if (dependencyExpr.dependencies) {
            dependencies.push(dependencyExpr);
            dependencies = dependencies.concat(dependencyExpr.dependencies);
        } else {
            dependencies.push(dependencyExpr);
        }
    });

    if(dependencies.length == 0) {
        return undefined; // If no dependencies are required, simply compose no parameter. Though not mandatory, it improves readability of the generated expression
    } else {
        return dependencies;
    }
};
```

--------------------------------

### SourcesCache.toNixAST

Source: https://volkswagenfeature.github.io/SourcesCache.html

Converts the SourcesCache to a Nix AST representation.

```APIDOC
## toNixAST()

### Description
Converts the current SourcesCache instance into a Nix Abstract Syntax Tree (AST) representation.

### Method
GET

### Endpoint
/sources/toNixAST

### Parameters
None

### Response
#### Success Response (200)
- **nixAST** (object) - The Nix AST representation of the cache.

#### Response Example
```json
{
  "nixAST": {
    "type": "call",
    "function": {
      "type": "identifier",
      "name": "import"
    },
    "args": [
      {
        "type": "string",
        "value": "<path_to_generated_nix_file>"
      }
    ]
  }
}
```

See:
    
  * NixASTNode#toNixAST
```

--------------------------------

### Package.prototype.resolveDependenciesAndSources

Source: https://volkswagenfeature.github.io/Package.js.html

Resolves and bundles both regular and development dependencies, considering the production flag and peer dependency inclusion.

```APIDOC
## Package.prototype.resolveDependenciesAndSources

### Description
Resolves dependencies and their sources. It first bundles regular dependencies, then development dependencies if not in production mode, and finally considers including peer dependencies based on configuration.

### Method
Package.prototype.resolveDependenciesAndSources

### Parameters
#### Path Parameters
- **callback** (function) - Callback function to be invoked upon completion.
```

--------------------------------

### Convert SourcesCache to Nix AST

Source: https://volkswagenfeature.github.io/SourcesCache.js.html

Converts the sources cache into a Nix AST representation. It sorts the sources by identifier before conversion.

```javascript
SourcesCache.prototype.toNixAST = function() {
    var self = this;
    var ast = {};

    Object.keys(self.sources).sort().forEach(function(identifier) {
        var source = self.sources[identifier];
        ast[identifier] = source.toNixAST();
    });

    return ast;
};
```

--------------------------------

### Generate Nix Composition Expression

Source: https://volkswagenfeature.github.io/node2nix.js.html

Generates and writes a Nix composition expression to the specified output file. This step involves creating a CompositionExpression object and writing its Nix representation.

```javascript
expr = new CompositionExpression(compositionNix, nodePackage, nodeEnvNix, outputNix, supplementNix, (supplementJSON !== undefined), useFetchGitPrivate);
fs.writeFile(compositionNix, disclaimer + nijs.jsToNix(expr, true) + "\n", callback);
```

--------------------------------

### Package.prototype.bundleDependencies

Source: https://volkswagenfeature.github.io/Package.js.html

Bundles a collection of dependencies, resolving and fetching their metadata. Supports flattening mode and callback invocation upon completion.

```APIDOC
## Package.prototype.bundleDependencies

### Description
Bundles a collection of dependencies with this package (or when flattening mode has been enabled) any parent package that does not conflict and automatically fetches its metadata by downloading it.

### Method
Package.prototype.bundleDependencies

### Parameters
#### Path Parameters
- **resolvedDependencies** (Object) - Memorizes the dependencies that have been resolved so that we can resolve their transitive dependencies later.
- **dependencies** (Array<Package>) - Dependencies to bundle with the package
- **callback** (function(Object)) - Callback that gets invoked then the work is done. The first parameter is set to an error object if the operation fails.
```

--------------------------------

### Display Warnings for Common Mistakes

Source: https://volkswagenfeature.github.io/node2nix.js.html

Displays warnings to the user about common mistakes in the Nix generation process, such as an unused lock file or the presence of a node_modules folder in the project root.

```javascript
console.log("\nWARNING: A lock file exists in the repository, yet it is not used in the generation process!");
console.log("As a result, the deployment of the project may fail.");
console.log("You probably want to run node2nix with the -l option to use the lock file!");
```

```javascript
console.log("\nWARNING: There is a node_modules/ folder in the root directory of the project!");
console.log("These packages will be included in the Nix build and influence the outcome.");
console.log("If you don't want this to happen, then you should remove it before running any");
console.log("of the Nix commands!");
```

--------------------------------

### Resolve Dependencies and Sources

Source: https://volkswagenfeature.github.io/Package.js.html

Initiates the process of resolving and bundling dependencies, including regular and development dependencies, and potentially peer dependencies based on configuration.

```javascript
Package.prototype.resolveDependenciesAndSources = function(callback) {
    var self = this;
    var resolvedDependencies = {};

    slasp.sequence([
        function(callback) {
            self.bundleDependencies(resolvedDependencies, self.source.config.dependencies, callback);
        },

        function(callback) {
            /* Bundle the development dependencies, if applicable */
            if(self.production) {
                callback();
            } else {
                self.bundleDependencies(resolvedDependencies, self.source.config.devDependencies, callback);
            }
        },

        function(callback) {
            if(self.deploymentConfig.includePeerDependencies) {

```

--------------------------------

### Generate Dependency AST

Source: https://volkswagenfeature.github.io/Package.js.html

Composes an abstract syntax tree for the provided NPM dependencies of a package. It creates Nix attribute references for each dependency.

```javascript
var dependencies = [];

Object.keys(self.providedDependencies).sort().forEach(function(dependencyName) {
    var dependency = self.providedDependencies[dependencyName];

    // For each dependency, refer to the source attribute set that defines it
    var ref = new nijs.NixAttrReference({
        attrSetExpr: new nijs.NixExpression("sources"),
        refExpr: dependency.source.identifier
    });

    var transitiveDependencies = dependency.generateDependencyAST();
    var dependencyExpr;

    if(transitiveDependencies === undefined) {
        dependencyExpr = ref; // If a dependency has no dependencies of its own, we just refer to the attribute in the source set
    } else {
        // If a dependency has dependencies, we augment the reference with the set of dependencies that it needs
        dependencyExpr = new nijs.NixMergeAttrs({
            left: ref,
            right: {

```

--------------------------------

### Find Matching Provided Dependency by Parent

Source: https://volkswagenfeature.github.io/Package.js.html

Recursively searches parent packages for a dependency that matches the specified name and version range. Returns the nearest matching parent package or null if no match is found or a conflict is detected.

```javascript
Package.prototype.findMatchingProvidedDependencyByParent = function(name, versionSpec) {
    if(this.parent === null) { // If there is no parent, then we can also not provide a dependency
        return null;
    } else {
        var dependency = this.parent.providedDependencies[name];
  
        if(dependency === undefined) {
            return this.parent.findMatchingProvidedDependencyByParent(name, versionSpec); // If the parent does not provide the dependency, try the parent's parent
        } else if(dependency === null) {
             return null; // If we have encountered a bundled dependency with the same name, consider it a conflict (is not a perfect resolution, but does not result in an error)
        } else {
            if(semver.satisfies(dependency.source.config.version, versionSpec, true)) { // If we found a dependency with the same name, see if the version fits
                return dependency;
            } else {
                return null; // If there is a version mismatch, then a conflicting version has been encountered
            }
        }
    }
};
```

--------------------------------

### Copy Node Environment Nix Expression

Source: https://volkswagenfeature.github.io/node2nix.js.html

Copies the 'node-env.nix' file to a specified path. This is useful for setting up the build environment for Node.js projects within Nix.

```javascript
function copyNodeEnvExpr(nodeEnvNix, callback) {
    /* Compose a read stream that reads the build expression */
    var rs = fs.createReadStream(path.join(path.dirname(module.filename), "..", "nix", "node-env.nix"));
    rs.on("error", function(err) {
        callback(err);
    });
  
    /* Compose a write stream that writes the build expression */
    var ws = fs.createWriteStream(nodeEnvNix);
    ws.on("error", function(err) {
        callback(err);
    });
    ws.on("close", function() {
        callback(null);
    });
  
    /* Pipe the data to actually copy stuff */
    rs.pipe(ws);
}
```

--------------------------------

### findMatchingProvidedDependencyByParent

Source: https://volkswagenfeature.github.io/Package.js.html

Recursively checks enclosing parent packages to find a dependency that matches the required version range.

```APIDOC
## GET /findMatchingProvidedDependencyByParent

### Description
Recursively checks the enclosing parent packages to see whether a dependency exists that fits within the required version range.

### Method
GET

### Endpoint
`/findMatchingProvidedDependencyByParent`

### Parameters
#### Query Parameters
- **name** (String) - Required - Name of a Node.js package
- **versionSpec** (String) - Required - Version specifier of a Node.js package, such as an exact version number, version range, URL, or GitHub identifier

### Response
#### Success Response (200)
- **Package** (Object) - The nearest parent package matching the version specifier or null if no such package exists.

#### Response Example
```json
{
  "dependency": {
    "name": "example-package",
    "version": "1.2.3"
  }
}
```
```

--------------------------------

### npmToNix

Source: https://volkswagenfeature.github.io/module-node2nix.html

Generates a Nix expression from a JSON file representing a Node.js package configuration or an array of NPM dependencies. It can output registry, composition, and supplement expressions.

```APIDOC
## npmToNix

### Description
Generates a Nix expression from a JSON file representing a Node.js package configuration or an array of NPM dependencies.

### Method
(static) npmToNix

### Parameters
#### Path Parameters
- **inputJSON** (String) - Required - Path to a package.json or arbitrary JSON file
- **outputNix** (String) - Required - Path to which the generated registry expression is written
- **compositionNix** (String) - Required - Path to which the generated composition expression is written
- **nodeEnvNix** (String) - Required - Path to which the NPM package build expression is written
- **supplementJSON** (String) - Optional - Path to a supplement JSON file
- **supplementNix** (String) - Optional - Path to which the generated supplement expression is written
- **production** (Boolean) - Optional - Indicates whether to deploy the package in production mode
- **includePeerDependencies** (Boolean) - Optional - Indicates whether to include peer dependencies with the package
- **flatten** (Boolean) - Optional - Indicates whether to create a flat dependency structure in which dependencies are as high as possible in the graph
- **nodePackage** (String) - Optional - Name of the Node.js package to use from Nixpkgs
- **registries** (Array.<Registry>) - Optional - URL and AuthToken for registries
- **noCopyNodeEnv** (Boolean) - Optional - Indicates that no copy of the NPM package build expression should be made
- **bypassCache** (Boolean) - Optional - Indicates that the content addressable cache should be bypassed
- **useFetchGitPrivate** (Boolean) - Optional - Indicates that the fetchgitPrivate function should be used instead of fetchgit
- **stripOptionalDependencies** (Boolean) - Optional - When enabled, the optional dependencies are stripped from the regular dependencies in the NPM registry
- **callback** (function) - Required - Callback function that gets invoked when the work is done. If an error occurs, the error parameter is set to contain the error. If the operation succeeds, it returns a string containing the registry expression containing the packages and all its dependencies.

### Request Example
```json
{
  "inputJSON": "package.json",
  "outputNix": "registry.nix",
  "compositionNix": "composition.nix",
  "nodeEnvNix": "node-env.nix",
  "production": true,
  "callback": "function(error, registryExpression) { ... }"
}
```

### Response
#### Success Response (200)
- **registryExpression** (String) - A string containing the Nix registry expression with packages and dependencies.

#### Response Example
```json
// Callback is invoked with the registry expression string on success
```
```

--------------------------------

### bundleDependencies

Source: https://volkswagenfeature.github.io/Package.html

Bundles a collection of dependencies with the current package or a parent package if flattening is enabled. It also fetches metadata for these dependencies.

```APIDOC
## POST /bundleDependencies

### Description
Bundles a collection of dependencies with this package (or when flattening mode has been enabled) any parent package that does not conflict and automatically fetches its metadata by downloading it.

### Method
POST

### Endpoint
/bundleDependencies

### Parameters
#### Request Body
- **resolvedDependencies** (Array<Package>) - Required - Memorizes the dependencies that have been resolved so that we can resolve their transitive dependencies later.
- **dependencies** (Array<Package>) - Required - Dependencies to bundle with the package
- **callback** (function) - Required - Callback that gets invoked then the work is done. The first parameter is set to an error object if the operation fails.

### Source
* Package.js, line 140
```

--------------------------------

### findMatchingProvidedDependencyByParent

Source: https://volkswagenfeature.github.io/Package.html

Recursively searches parent packages to find a dependency that matches the specified name and version.

```APIDOC
## GET /findMatchingProvidedDependencyByParent

### Description
Recursively checks the enclosing parent packages to see whether a dependency exists that fits within the required version range.

### Method
GET

### Endpoint
/findMatchingProvidedDependencyByParent

### Parameters
#### Query Parameters
- **name** (String) - Required - Name of a Node.js package
- **versionSpec** (String) - Required - Version specifier of a Node.js package, such as an exact version number, version range, URL, or GitHub identifier

### Returns
- **Package** - The nearest parent package matching the version specifier or null if no such package exists

### Source
* Package.js, line 56
```

--------------------------------

### addSource Method

Source: https://volkswagenfeature.github.io/SourcesCache.js.html

Adds a source to the cache if it does not already exist. The source is identified by its 'identifier' property.

```APIDOC
## POST /addSource

### Description
Adds a source to the cache. If a source with the same identifier already exists, it will not be added again.

### Method
POST

### Endpoint
/addSource

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **source** (Source) - Required - The source object to add to the cache. It must have an 'identifier' property.

### Request Example
```json
{
  "source": {
    "identifier": "npm:react@18.2.0",
    "url": "https://registry.npmjs.org/react"
  }
}
```

### Response
#### Success Response (200)
Indicates that the source was processed. No specific data is returned.

#### Response Example
(No response body)
```

--------------------------------

### Write Supplement Nix Expression

Source: https://volkswagenfeature.github.io/node2nix.js.html

Writes the supplement Nix expression to the specified output file. This is part of an asynchronous waterfall process.

```javascript
fs.writeFile(supplementNix, disclaimer + nijs.jsToNix(expr, true) + "\n", callback);
```

--------------------------------

### generateDependencyAST

Source: https://volkswagenfeature.github.io/Package.html

Generates an abstract syntax tree (AST) representing the NPM dependencies of this package.

```APIDOC
## GET /generateDependencyAST

### Description
Composes an abstract syntax tree for the provided NPM dependencies by this package.

### Method
GET

### Endpoint
/generateDependencyAST

### Returns
- **Array** - An array representing a list of NPM package dependencies

### Source
* Package.js, line 278
```

--------------------------------

### Convert NPM package.json to Nix Expression

Source: https://volkswagenfeature.github.io/node2nix.js.html

Converts an NPM package.json file into a Nix expression. It handles dependency resolution and can optionally incorporate lock files and supplement definitions.

```javascript
exports.copyNodeEnvExpr = copyNodeEnvExpr;
  
function npmToNix(inputJSON, outputNix, compositionNix, nodeEnvNix, lockJSON, supplementJSON, supplementNix, production, includePeerDependencies, flatten, nodePackage, registries, noCopyNodeEnv, bypassCache, useFetchGitPrivate, stripOptionalDependencies, callback) {
    var obj = JSON.parse(fs.readFileSync(inputJSON));
    var version = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"))).version;
    var disclaimer = "# This file has been generated by node2nix " + version + ". Do not edit!\n\n";
    var outputDir = path.dirname(outputNix);
    var baseDir = path.dirname(inputJSON);
  
    var lock;
  
    if(lockJSON !== undefined) {
        lock = JSON.parse(fs.readFileSync(lockJSON));
    }
  
    var deploymentConfig = new DeploymentConfig(registries, production, includePeerDependencies, flatten, nodePackage, outputDir, bypassCache, stripOptionalDependencies);
    var expr;
  
    var displayLockWarning = false;
  
    slasp.sequence([
        /* Generate a Nix expression */
        function(callback) {
            if(typeof obj == "object" && obj !== null) {
                if(Array.isArray(obj)) {
                    expr = new CollectionExpression(deploymentConfig, baseDir, obj);
                } else {
                    // Display error if mandatory package.json attributes are not set
                    if(!obj.name) {
                        return callback("Mandatory name attribute is missing in package.json");
                    }
  
                    // Parse package.json
                    expr = new PackageExpression(deploymentConfig, lock, baseDir, obj.name, baseDir);
  
                    // Display a warning if we expect a lock file to be used, but the user does not specify it
                    displayLockWarning = bypassCache && !lockJSON && fs.existsSync(path.join(path.dirname(inputJSON), path.basename(inputJSON, ".json"))) + "-lock.json");
                }
  
                expr.resolveDependencies(callback);
            } else {
                callback("The provided JSON file must consist of an object or an array");
            }
        },
  
        /* Write the output Nix expression to the specified output file */
        function(callback) {
            fs.writeFile(outputNix, disclaimer + nijs.jsToNix(expr, true) + "\n", callback);
        },
  
        function(callback) {
            /* Generate the supplement Nix expression, if specified */
            if(supplementJSON) {
                var obj = JSON.parse(fs.readFileSync(supplementJSON));
  
                if(Array.isArray(obj)) {
                    expr = new CollectionExpression(deploymentConfig, baseDir, obj);
                    expr.resolveDependencies(callback);
                } else {

```

--------------------------------

### Bundle a Single Dependency

Source: https://volkswagenfeature.github.io/Package.js.html

Bundles a dependency into the package's node_modules directory. If flattening is enabled, it attempts to bundle with the highest parent package that doesn't conflict.

```javascript
Package.prototype.bundleDependency = function(dependencyName, pkg) {
    this.requiredDependencies[dependencyName] = pkg;

    if(this.deploymentConfig.flatten) { // In flatten mode, bundle dependency with the highest parent where it is not conflicting
        if(this.parent !== null && this.parent.providedDependencies[dependencyName] === undefined && this.parent.requiredDependencies[dependencyName] === undefined) {
            this.parent.bundleDependency(dependencyName, pkg);
        } else {
            pkg.parent = this;
            this.providedDependencies[dependencyName] = pkg;
        }
    } else {
        this.providedDependencies[dependencyName] = pkg; // Bundle the dependency with the package
    }
};
```

--------------------------------

### SourcesCache.addSource

Source: https://volkswagenfeature.github.io/SourcesCache.html

Adds a source to the cache if it doesn't already exist.

```APIDOC
## addSource(source)

### Description
Checks whether a given source exists and if not, adds it to the cache.

### Method
POST

### Endpoint
/sources

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **source** (Source) - Required - Any source object

### Request Example
```json
{
  "source": "<source_object>"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the source was added or already exists.

#### Response Example
```json
{
  "message": "Source added successfully."
}
```
```

--------------------------------

### resolveDependencies

Source: https://volkswagenfeature.github.io/Package.html

Resolves all direct and transitive dependencies for this package.

```APIDOC
## POST /resolveDependencies

### Description
Resolves all dependencies and transitive dependencies of this package.

### Method
POST

### Endpoint
/resolveDependencies

### Parameters
#### Request Body
- **callback** (function) - Required - Callback that gets invoked then the work is done. The first parameter is set to an error object if the operation fails.

### Source
* Package.js, line 263
```

--------------------------------

### Resolve Package Dependencies

Source: https://volkswagenfeature.github.io/Package.js.html

Resolves all dependencies and transitive dependencies of a package. It either fetches all dependencies if no lock file is present or uses the lock file to generate Nix expressions.

```javascript
if(this.lock === undefined) { // If no lock file is present, let the tool fetch all dependencies and metadata
    this.resolveDependenciesAndSources(callback);
} else { // If we have a lock file, use that to generate Nix expressions
    this.resolveDependenciesFromLockedDependencies(this.lock, callback);
}
```

--------------------------------

### bundleDependency

Source: https://volkswagenfeature.github.io/Package.html

Bundles a specific dependency into the package's node_modules folder or a parent package if flattening is enabled.

```APIDOC
## POST /bundleDependency

### Description
Bundles a dependency (that is fetched from an external location) to the package (or a parent package if flattening has been enabled). A bundled package will appear in the node_modules/ sub folder of the package.

### Method
POST

### Endpoint
/bundleDependency

### Parameters
#### Request Body
- **dependencyName** (String) - Required - Name of the dependency
- **pkg** (Package) - Required - Package to bundle in the node_modules/ sub folder

### Source
* Package.js, line 113
```

--------------------------------

### Package.prototype.bundleDependency

Source: https://volkswagenfeature.github.io/Package.js.html

Bundles a single dependency to the package or its parent if flattening is enabled. The bundled package appears in the node_modules/ subfolder.

```APIDOC
## Package.prototype.bundleDependency

### Description
Bundles a dependency (that is fetched from an external location) to the package (or a parent package if flattening has been enabled). A bundled package will appear in the node_modules/ sub folder of the package.

### Method
Package.prototype.bundleDependency

### Parameters
#### Path Parameters
- **dependencyName** (String) - Required - Name of the dependency
- **pkg** (Package) - Required - Package to bundle in the node_modules/ sub folder
```

--------------------------------

### Add Source to Cache

Source: https://volkswagenfeature.github.io/SourcesCache.js.html

Adds a source to the cache if it doesn't already exist. The source is identified by its 'identifier' property.

```javascript
SourcesCache.prototype.addSource = function(source) {
    if(this.sources[source.identifier] === undefined) {
        this.sources[source.identifier] = source;
    }
};
```

--------------------------------

### Export SourcesCache Class

Source: https://volkswagenfeature.github.io/SourcesCache.js.html

Exports the SourcesCache class for use in other modules.

```javascript
exports.SourcesCache = SourcesCache;
```

--------------------------------

### Copy Node Environment Expression

Source: https://volkswagenfeature.github.io/node2nix.js.html

Copies the node-env.nix expression. This function is called within an asynchronous waterfall, executing only if 'noCopyNodeEnv' is false.

```javascript
copyNodeEnvExpr(nodeEnvNix, callback);
```

--------------------------------

### Bundle Transitive Dependencies

Source: https://volkswagenfeature.github.io/Package.js.html

Bundles transitive dependencies for a package. It iterates through resolved dependencies and resolves their individual dependencies and sources.

```javascript
/* Bundle transitive dependencies */

slasp.fromEach(function(callback) {
    callback(null, resolvedDependencies);
}, function(dependencyName, callback) {
    var dependency = resolvedDependencies[dependencyName];
    dependency.resolveDependenciesAndSources(callback);
}, callback);
```

--------------------------------

### Bundle Peer Dependencies

Source: https://volkswagenfeature.github.io/Package.js.html

Bundles required peer dependencies for a package. This function is part of a larger dependency resolution process.

```javascript
/* Bundle the required peer dependencies, if applicable */
self.bundleDependencies(resolvedDependencies, self.source.config.peerDependencies, callback);
```

--------------------------------

### Resolve Dependencies from Locked Dependencies

Source: https://volkswagenfeature.github.io/Package.js.html

Resolves dependencies from a locked dependency object. It filters out bundled, optional, and development dependencies based on configuration and environment.

```javascript
if(dependencyObj.dependencies === undefined) {
    callback();
} else {
    slasp.fromEach(function(callback) {
        callback(null, dependencyObj.dependencies);
    }, function(dependencyName, callback) {
        var dependency = dependencyObj.dependencies[dependencyName];

        if(dependency.bundled) { // Bundled dependencies should not be included
            callback();
        } else if(self.deploymentConfig.stripOptionalDependencies && dependency.optional) { // When the stripping optional dependencies feature has been enabled, remove all optional dependencies
            callback();
        } else if(self.production && dependency.dev) { // Development dependencies should not be included in production mode
            callback();
        } else {
            var pkg = new Package(self.deploymentConfig, self.lock, self, dependencyName, dependency.version, self.source.baseDir, self.production, self.sourcesCache);
            self.providedDependencies[dependencyName] = pkg;

            slasp.sequence([
                function(callback) {
                    pkg.source.convertFromLockedDependency(dependency, callback);
                },

                function(callback) {
                    self.sourcesCache.addSource(pkg.source);
                    pkg.resolveDependenciesFromLockedDependencies(dependency, callback);
                }
            ], callback);
        }
    }, callback);
}
```

--------------------------------

### Check if Dependency is Bundled

Source: https://volkswagenfeature.github.io/Package.js.html

Checks if a given dependency name exists in the package's bundle dependencies configuration.

```javascript
if(dependencyName == this.source.config.bundleDependencies[i])
                    return true;
```

--------------------------------

### isBundledDependency

Source: https://volkswagenfeature.github.io/Package.html

Checks if a dependency with the given name is already bundled with this package.

```APIDOC
## GET /isBundledDependency

### Description
Checks whether a dependency with a given name is already bundled with this package.

### Method
GET

### Endpoint
/isBundledDependency

### Parameters
#### Query Parameters
- **dependencyName** (String) - Required - Name of the dependency

### Returns
- **Boolean** - true if the dependency is bundled, else false

### Source
* Package.js, line 84
```

--------------------------------

### Check if Dependency is Bundled

Source: https://volkswagenfeature.github.io/Package.js.html

Determines if a dependency with the given name is bundled with the current package by checking the 'bundledDependencies' and 'bundleDependencies' options in the package's source configuration.

```javascript
Package.prototype.isBundledDependency = function(dependencyName) {
    // Check the bundledDependencies option
    if(Array.isArray(this.source.config.bundledDependencies)) {
        for(var i = 0; i < this.source.config.bundledDependencies.length; i++) {
            if(dependencyName == this.source.config.bundledDependencies[i])
                return true;
        }
    }
  
    // Check the bundleDependencies option
    if(Array.isArray(this.source.config.bundleDependencies)) {
        for(var i = 0; i < this.source.config.bundleDependencies.length; i++) {

```
Tokens:
Raw