A Node.js CommonJS/ES6 module with the Liquid substitutions code used by xpm & relatives

This project provides a TypeScript Node.js CommonJS/ES6 module with the code used to perform the Liquid substitutions when parsing the xpm package.json file.

Note: Compatibility with legacy CommonJS is required until VS Code extensions will be updated to import ES6 modules.

The project is open-source and hosted on GitHub as xpack/xpm-liquid-ts.

Maintainer & developer info

This page documents how to use this module in an user application. For maintainer information, see the separate README-MAINTAINER page.

Prerequisites

A recent Node.js (>=16.0.0), since the TypeScript code is compiled into ECMAScript 2020 code, and the tests use ES6 modules.

Install

The module is available as @xpack/xpm-liquid-ts from the public npmjs repository; it can be added as a dependency to any TypeScript or JavaScript project with npm install:

npm install --save @xpack/xpm-liquid-ts@latest
Copy

The module does not provide any executables, and generally there are no reasons to install it globally.

User info

This section is intended for those who want to use this module in their own projects.

The @xpack/xpm-liquid module can be imported into both TypeScript and JavaScript Node.js code.

In TypeScript and ECMAScript modules, use import:

import { XpmLiquid } from '@xpack/xpm-liquid'
Copy

In JavaScript with CommonJS, use require():

const { XpmLiquid } = require('@xpack/xpm-liquid')
Copy

To use the XpmLiquid class, create an instance of the engine, provide the package.json object, possibly the name of the configuration, and call performSubstitutions():

const xpmLiquid = new XpmLiquid(log)
const xpmLiquidMap = xpmLiquid.prepareMap(packageJson, 'Debug')

const str = await xpmLiquid.performSubstitutions(
      '{{ "build" | path_join: configuration.name | to_filename }}',
      xpmLiquidMap)
Copy

Available variables

The entire project package.json is available as the package variable:

• package

All user defined properties (project and configuration) are grouped below the properties variable:

• properties

If the substitution refers to a certain build configuration, the configuration name and the entire configuration content are available separately below the configuration variable. Configuration properties are added to the properties variables, possibly overriding project properties.

• configuration.name
• configuration.*

Variables based on the Node.js process environment:

• env

Variables based on the Node.js os definitions:

• os.EOL
• os.arch (like 'arm', 'arm64', 'ia32', 'x64')
• os.constants
• os.cpus
• os.endianness
• os.homedir
• os.hostname
• os.platform (like 'darwin', 'linux', 'win32')
• os.release
• os.tmpdir
• os.type
• os.version (available since Node 12)

Variables based on the Node.js path definitions:

• path.delimiter (; for Windows, : for POSIX)
• path.sep (\ on Windows, / on POSIX)
• path.win32.delimiter (;)
• path.win32.sep (``)
• path.posix.delimiter (:)
• path.posix.sep (/)

Examples:

• "buildFolderRelativePath": "build{{ path.sep }}{{ configuration.name | to_filename }}"

Custom filters

Filters based on Node.js path functions:

• path_basename
• path_dirname
• path_normalize
• path_join
• path_relative
• path_posix_basename
• path_posix_dirname
• path_posix_normalize
• path_posix_join
• path_posix_relative
• path_win32_basename
• path_win32_dirname
• path_win32_normalize
• path_win32_join
• path_win32_relative

Filters based on Node.js utils functions:

• util_format

Custom filter to convert generic names to names accepted as file names (letters, digits, dash):

• to_filename
• to_posix_filename
• to_win32_filename

Examples:

• "buildFolderRelativePath": "{{ "build" | path_join: configuration.name | to_filename | downcase }"

Lenient if's

The undefined variables in tests do not trigger undefined variable messages and allow to use defaults, like:

{{ env.OPTIMIZATION | default: '-O2' }}
Copy

Reference

For more details on the available class definitions, including all methods, accessors, properties, etc, please see the TypeDoc reference pages.

Known problems

• none

Status

The @xpack/xpm-liquid-ts module is fully functional and stable.

The main clients for this module is the xpm CLI application and the VS Code xPack C/C++ Managed Build extension.

Tests

The module is tested with 100% coverage and CI tested on every push via GitHub Actions.

Compatibility notices

According to semver rules:

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.

v2.0.0

The project was updated to dual ESM & CJS.

License

The original content is released under the MIT License, with all rights reserved to Liviu Ionescu.