Skip to main content

utils/ast-path-operations

Interfaces​

PathOperationConfig​

Defined in: utils/ast-path-operations.ts:127

Configuration for a single path operation

PathOperationConfig

Example​

const config: PathOperationConfig = {
  path: 'on.workflow_call.inputs.version',
  operation: 'set',
  value: {
    description: 'The version to deploy',
    required: false,
    type: 'string'
  },
  required: true
}

Properties​

comment?​
optional comment: string;

Defined in: utils/ast-path-operations.ts:133

commentBefore?​
optional commentBefore: string;

Defined in: utils/ast-path-operations.ts:132

operation​
operation: PathOperation;

Defined in: utils/ast-path-operations.ts:129

Type of operation to perform

path​
path: string;

Defined in: utils/ast-path-operations.ts:128

Dot-notation path to target (e.g., 'jobs.changes.steps')

required?​
optional required: boolean;

Defined in: utils/ast-path-operations.ts:131

Whether the path must exist

spaceBefore?​
optional spaceBefore: boolean;

Defined in: utils/ast-path-operations.ts:134

spaceBeforeComment?​
optional spaceBeforeComment: boolean;

Defined in: utils/ast-path-operations.ts:135

tag?​
optional tag: string;

Defined in: utils/ast-path-operations.ts:136

value​
value: PathValue;

Defined in: utils/ast-path-operations.ts:130

Value to set/merge/overwrite

Type Aliases​

PathOperation​

type PathOperation = "set" | "merge" | "overwrite" | "preserve";

Defined in: utils/ast-path-operations.ts:93

Available operation types for path-based AST manipulation

PathValue​

type PathValue = Node | object | string | number | boolean | any[];

Defined in: utils/ast-path-operations.ts:102

Supported value types for path operations

Functions​

applyPathOperations()​

function applyPathOperations(
   doc, 
   operations, 
   document?): void;

Defined in: utils/ast-path-operations.ts:503

Apply multiple path operations to a document

This is the main entry point for applying multiple operations to a YAML document. It processes all operations in order and applies them to the document.

Parameters​

doc​

YAMLMap

The YAML document to modify

operations​

PathOperationConfig[]

Array of operations to apply

document?​

any

Returns​

void

Example​

const operations: PathOperationConfig[] = [
  {
    path: 'on.workflow_call.inputs.version',
    operation: 'set',
    value: { description: 'Version to deploy', required: false, type: 'string' }
  },
  {
    path: 'jobs.changes',
    operation: 'overwrite',
    value: createValueFromString(`
      runs-on: ubuntu-latest
      steps:
        - uses: ./actions/detect-changes
    `)
  }
]

applyPathOperations(doc, operations)

createValueFromArray()​

function createValueFromArray(arr): Node;

Defined in: utils/ast-path-operations.ts:645

Create a YAML node from a JavaScript array

Converts a JavaScript array to a YAML sequence node.

Parameters​

arr​

any[]

JavaScript array to convert

Returns​

Node

The converted YAML sequence node

Example​

const node = createValueFromArray(['develop', 'staging', 'main'])

createValueFromObject()​

function createValueFromObject(obj, doc?): Node;

Defined in: utils/ast-path-operations.ts:625

Create a YAML node from a JavaScript object

Converts a plain JavaScript object to a YAML map node.

Parameters​

obj​

object

JavaScript object to convert

doc?​

any

Returns​

Node

The converted YAML map node

Example​

const node = createValueFromObject({
  description: 'The version to deploy',
  required: false,
  type: 'string'
})

createValueFromString()​

function createValueFromString(
   yamlString, 
   context?, 
   document?): Node;

Defined in: utils/ast-path-operations.ts:541

Create a YAML node from a YAML string

Parses a YAML string and returns the root node. This is useful for complex multi-line YAML structures like job definitions.

Parameters​

yamlString​

string

YAML string to parse

context?​

any

document?​

any

Returns​

Node

The parsed YAML node

Example​

const node = createValueFromString(`
  runs-on: ubuntu-latest
  steps:
    - name: Checkout code
      uses: actions/checkout@v3
    - name: Run tests
      run: npm test
`)

ensurePathAndApply()​

function ensurePathAndApply(
   doc, 
   config, 
   document?): void;

Defined in: utils/ast-path-operations.ts:303

Ensure a path exists and apply the specified operation

This is the main orchestration function that handles all path operations. It checks if the path exists, applies the appropriate operation based on the configuration, and handles required vs optional paths.

Parameters​

doc​

YAMLMap

The YAML document to modify

config​

PathOperationConfig

Operation configuration

document?​

any

Returns​

void

Example​

const config: PathOperationConfig = {
  path: 'jobs.changes.runs-on',
  operation: 'set',
  value: 'ubuntu-latest',
  required: true
}

ensurePathAndApply(doc, config)

getPathValue()​

function getPathValue(doc, path): Node | null;

Defined in: utils/ast-path-operations.ts:265

Get a value at a specific path in the YAML AST

Navigates to the specified path and returns the node if found, null otherwise. This is useful for checking if a path exists before applying operations.

Parameters​

doc​

YAMLMap

The YAML document to read from

path​

string

Dot-notation path (e.g., 'jobs.changes.steps')

Returns​

Node | null

The node at the path, or null if not found

Example​

const doc = parseDocument('jobs: { changes: { runs-on: ubuntu-latest } }')
const value = getPathValue(doc.contents, 'jobs.changes.runs-on')
console.log(value) // Scalar('ubuntu-latest')

setPathValue()​

function setPathValue(
   doc, 
   path, 
   value, 
   document?, 
   commentBefore?, 
   spaceBeforeComment?): void;

Defined in: utils/ast-path-operations.ts:158

Set a value at a specific path in the YAML AST

Creates intermediate nodes as needed and sets the final value at the specified path. This is the core function for setting values in the YAML structure.

Parameters​

doc​

YAMLMap

The YAML document to modify

path​

string

Dot-notation path (e.g., 'jobs.changes.steps')

value​

PathValue

Value to set at the path

document?​

any

commentBefore?​

string

spaceBeforeComment?​

boolean

Returns​

void

Throws​

When path navigation fails or parent is not a map

Example​

const doc = parseDocument('name: Pipeline')
setPathValue(doc.contents, 'jobs.changes.runs-on', 'ubuntu-latest')
// Results in: jobs: { changes: { 'runs-on': 'ubuntu-latest' } }