xpm-lib package

A Node.js TypeScript module with the core code for xpm and xpm enabled projects.

Remarks

This library groups together various classes and functions used in common by xpm and the Visual Studio Code extension.

The main functionality is to manage actions and build configurations, especially those defined using Liquid templates.

The Lazy Evaluation Mechanism

Actions (Actions) and build configurations (BuildConfigurations) implement a two-step lazy evaluation process to avoid unnecessary operations:

1. Name Expansion: During collection initialisation, only the matrix of options is evaluated for each template, expanding template names into concrete action or configuration names without processing their content.
2. Content Evaluation: Later, when an action or build configuration is actually accessed and initialised (via Action.initialise() or BuildConfiguration.initialise()), the template is fully evaluated and Liquid substitutions are performed.

This approach ensures that only items that are actually used incur the cost of template evaluation and variable substitution, significantly improving performance for projects with many actions or configurations.

Classes

Class	Description
Action	An individual xpm action containing commands to be executed.
Actions	A collection of xpm actions for a build configuration or the entire package.
BuildConfiguration	An individual xpm build configuration.
BuildConfigurations	A collection of xpm build configurations.
CombinationsGenerator	Generates all possible combinations from a matrix of parameters.
ConfigurationError	Error indicating a configuration issue.
DataModel	Represents a lazy-loading data model for an xpm package.
InputError	Error indicating that user input is invalid.
JsonSyntaxError	Error indicating a syntax error in configuration or template files.
LiquidEngine	Liquid engine configured for xpm templates.
LiquidMatrixDrop	Liquid drop that resolves matrix parameter values for templates.
LiquidPropertiesDrop	Liquid drop that resolves property values for template substitutions.
OutputError	Error indicating a failure during output generation.
Package	Provides access to package metadata and xpm-specific validation.
PlatformDetector	Platform detection service for runtime environment identification.
Policies	Computes feature policy flags based on a minimum xpm version.
PrerequisitesError	Error indicating that required prerequisites are not met.
TemplateError	Error indicating a template evaluation failure.
TemplateExpander	A generic template expansion engine for matrix-based template processing.

Abstract Classes

Abstract Class	Description
InitTemplateBase	Base class for xpm init templates.

Functions

Function	Description
chmodRecursively({ inputPath, readOnly, log, depth, maxDepth, }, input)	Recursively changes file permissions within a folder tree.
filterPath(input, platformDetector)	Replaces non-alphanumeric characters with dashes to make paths comply with file system names.
filterPosixPath(input)	Replaces non-alphanumeric characters with dashes to make paths comply with POSIX file system names.
filterWin32Path(input)	Replaces non-alphanumeric characters with dashes to make paths comply with Windows file system names.
getErrorMessage(error)	Extracts an error message string from an unknown error value.
getPlatformKey({ doForce32bit, platformDetector, }, input)	Builds a unique key using the current platform and architecture.
hasLiquidSyntax(value)	Checks whether a string contains Liquid template syntax.
isBoolean(value)	Determines whether a value is a boolean.
isJsonArray(value)	Determines whether a value is a JSON array.
isJsonObject(value)	Determines whether a value is a JSON object.
isNonEmptyJsonObject(value)	Determines whether a value is a non-empty JSON object.
isNumber(value)	Determines whether a value is a finite number.
isObject(value)	Determines whether a value is a non-array object.
isPrimitive(value)	Determines whether a value is a JavaScript primitive.
isString(value)	Determines whether a value is a string.
performSubstitutions({ engine, input, substitutionsVariables, log, maxIterations, maxOutputSize, }, input)	Performs substitutions on an input string using Liquid.
processMatrixForExpansion({ matrix, templateName, templateType, engine, substitutionsVariables, log, }, input)	Validates and processes a matrix object for template expansion.

Interfaces

Interface	Description
ActionConstructorParameters	Configuration parameters for constructing an action instance.
ActionsConstructorParameters	Configuration parameters for constructing an actions collection instance.
BuildConfigurationConstructorParameters	Configuration parameters for constructing a build configuration instance.
BuildConfigurationsConstructorParameters	Configuration parameters for constructing a build configurations collection.
CombinationsGeneratorConstructorParameters	Configuration parameters for constructing a combinations generator instance.
Config	Defines the xpm configuration options.
Context	Provides the execution context for xpm operations.
DataModelConstructorParameters	Configuration parameters for constructing a data model instance.
InitTemplateConstructorParameters	Configuration parameters for constructing an xpm init template.
InitTemplateItemValue	Defines an xpm init template platform-specific item value.
InitTemplatePropertiesDefinition	Defines an xpm init single template property.
InitTemplateSubstitutionsVariables	Defines the substitution variables used by xpm init templates.
JsonActionTemplate	Represents a JSON template action with a matrix for expansion.
JsonBuildConfigurationContent	Represents a JSON build configuration definition.
JsonBuildConfigurationTemplate	Represents a JSON template build configuration with matrix expansion.
JsonDependencyExtended	Represents a JSON extended dependency definition.
JsonNpmPackage	Represents a JSON npm package.json structure.
JsonPackageSpecifier	Represents a JSON npm package specifier.
JsonXpack	Represents a JSON xpm-specific section in package.json.
JsonXpmBinaries	Represents a JSON binaries definition in package.
JsonXpmPackage	Represents a JSON xpm package.json structure.
JsonXpmPlatformFile	Represents a JSON platform-specific binary file definition.
LiquidMatrixDropConstructorParameters	Configuration parameters for constructing a matrix drop instance.
LiquidPropertiesDropConstructorParameters	Configuration parameters for constructing a properties drop instance.
LiquidSubstitutionsVariables	Defines the substitution variables available to Liquid templates.
PackageConstructorParameters	Configuration parameters for constructing a package instance.
PlatformInfo	Platform information structure for runtime environment detection.
PlatformInfoOptions	Options for platform information retrieval.
PoliciesConstructorParameters	Configuration parameters for constructing a policies instance.
ProcessedMatrix	Result of matrix validation and processing.
TemplateExpanderConstructorParameters	Configuration parameters for constructing a template expander instance.

Variables

Variable	Description
buildFolderRelativePathPropertyName	The property name used for the build folder relative path.
COMBINATIONS_GENERATOR_MAX_COMBINATIONS_LIMIT	The default maximum number of combinations that can be generated.
liquidSubstitutionsVariablesBase	The base substitution variables initialised from the current environment.

Type Aliases

Type Alias	Description
ActionCommands	Represents a list of action command strings.
InitTemplateItems	Represents the available items for a select type property in xpm init templates.
InitTemplatePlatform	Represents the supported platform identifiers for xpm init template items.
InitTemplatePropertiesDefinitions	Represents a map of xpm init template property definitions.
InitTemplateType	Represents the supported property types for xpm init template properties.
InstanceFactoryCallback	Callback function type for creating instances from template expansions.
JsonAction	Represents a JSON action definition or a template of one.
JsonActionContent	Represents a JSON action content as a string or string array.
JsonActions	Represents a JSON map of action definitions.
JsonBuildConfiguration	Represents a JSON build configuration definition or a template of one.
JsonBuildConfigurationInherits	Represents a JSON array of build configuration names to inherit from.
JsonBuildConfigurations	Represents a JSON map of build configuration definitions.
JsonDependencies	Represents a JSON map of dependencies.
JsonDependenciesContent	Represents a JSON dependency content as a string or extended definition.
JsonProperties	Represents a JSON map of properties.
JsonPropertyValue	Represents a JSON property value.
JsonScripts	Represents a JSON map of npm scripts.
JsonTemplateMatrix	Represents a matrix of parameters for template expansion.
JsonTemplateMatrixContent	Represents an array of string values for a single matrix parameter.
JsonXpmBinariesPlatforms	Represents a JSON map of binaries platforms.
LiquidSubstitutionsStrings	Represents a map of substitution values used by Liquid templates.
MatrixCombination	A matrix combination mapping parameter names to their values.

---

Generated via tsdoc2docusaurus 1.3.2 by API Extractor/Documenter 7.57.2.