YAML Helpers

Based on the js-yaml package.

Idea

Adds support for additional data manipulation tags to the YAML parser.

Installation

yarn add @soloyal/yaml-helpers

Usage

Example Payload

export const payload = {
  firstName: 'John',
  lastName: 'Doe',
  birthDate: '6/19/2023, 4:15:36 PM',
  gender: 'male',
  age: 30,
  address: {
    street: '123 Main St',
    city: 'Springfield',
    zip: '12345'
  },
  markdown: '# markdown-it rulezz!',
}

Example Source configuration.yml

payload:
  file:
    # Load content from a file using the !file tag
    secret: !file secret.pem

  include:
    # Include content from another YAML file using the !include tag
    <<: !include path-to-without-yml-extension
    profile: !include profile

  env:
    # Load environment variables using the !env tag
    baseUrl: !env BASE_URL
    cdnBaseUrl: !env CDN_BASE_URL

  handlebars:
    # Use Handlebars.js templates for dynamic data with the !handlebars tag
    fullname: !handlebars "{{ firstName }} {{ lastName }}"
    baseUrl: !handlebars "{{env 'BASE_URL'}}"
    cdnBaseUrl: !handlebars "{{env 'CDN_BASE_URL'}}"
    helpers: !handlebars "{{#if firstName}}Hey {{ firstName }}.{{else}}Hey There!{{/if}}"

  payload:
    # Access payload data using the !payload tag
    all: !payload '*'
    first-name: !payload firstName

  builder:
    # Constructs a payload using a schema with the !builder tag
    partial: !builder
      .: !payload address
      fullAddress: !handlebars "{{ address.street }}, {{ address.city }} {{ address.zip }}"

  data:
    # Parse a date string using the !date tag
    birthDate: !date '6/19/2023, 4:15:36 PM'

  ms:
    # Use milliseconds and manipulate dates with the !ms tag
    5days-ms: !ms 5d
    date-plus-5days-date: !ms-date ['6/19/2023, 4:15:36 PM', '5d']
    date-plus-5days-day-of-the-week: !ms-date-day ['6/19/2023, 4:15:36 PM', '5d']
    date-plus-5days-day-of-the-month: !ms-date-date ['6/19/2023, 4:15:36 PM', '5d']
    date-plus-5days-month: !ms-date-month ['6/19/2023, 4:15:36 PM', '5d']
    date-plus-5days-year: !ms-date-year ['6/19/2023, 4:15:36 PM', '5d']

    current-date-plus-5days-date: !ms-current-date 5d
    current-date-plus-5days-day-of-the-week: !ms-current-date-day 5d
    current-date-plus-5days-day-of-the-month: !ms-current-date-date 5d
    current-date-plus-5days-month: !ms-current-date-month 5d
    current-date-plus-5days-year: !ms-current-date-year 5d

  markdown-it: !makrdown-it markdown

YAML Tags Description, Logic, and Examples

!file

Logic: The !file tag loads the content of a specified file into the YAML structure as a string. This is useful for including external data, such as keys or certificates, directly into the configuration.

Example 1: Load a Private Key

secrets:
  privateKey: !file secret.pem # Load the content of the secret.pem file as the privateKey value.

Example 2: Load Multiple Files

certificates:
  certificate: !file cert.pem # Load the content of the cert.pem file.
  key: !file key.pem # Load the content of the key.pem file.

!include

Logic: The !include tag allows you to include the content of another YAML file into the current file. This helps modularize configurations by splitting them into smaller, more manageable files.

Example 1: Include a Profile

profile: !include profile.yml # Load the content of profile.yml into the profile key.
profile-json: !include profile.json # Load the content of profile.json into the profile key.

Example 2: Include Nested Configuration

settings:
  main: !include config/main.yml # Include main settings from config/main.yml.
  advanced: !include config/advanced.yml # Include advanced settings from config/advanced.yml.

!env

Logic: The !env tag retrieves environment variables and injects them into the YAML structure. The tag looks for environment variables prefixed with CONFIGURATION_.

Example 1: Load Base URLs

api:
  baseUrl: !env BASE_URL # Retrieve and use the CONFIGURATION_BASE_URL environment variable.
  cdnUrl: !env CDN_BASE_URL # Retrieve and use the CONFIGURATION_CDN_BASE_URL environment variable.

Example 2: Load Database Configuration

database:
  host: !env DB_HOST # Load the CONFIGURATION_DB_HOST environment variable.
  port: !env DB_PORT # Load the CONFIGURATION_DB_PORT environment variable.

!handlebars

Logic: The !handlebars tag uses Handlebars.js to perform templating operations within YAML files. It allows you to create dynamic content based on the provided payload or environment variables.

Example 1: Generate a Full Name

user:
  fullName: !handlebars "{{ firstName }} {{ lastName }}" # Combines firstName and lastName from the payload to form fullName.

Example 2: Conditional Greeting

greeting:
  message: !handlebars "{{#if firstName}}Hello, {{ firstName }}!{{else}}Hello, Guest!{{/if}}" # Greet by name if firstName exists, otherwise greet as Guest.

Example 3: Generate a URL with Environment Variables

urls:
  apiUrl: !handlebars "{{env 'BASE_URL'}}/api" # Combines the BASE_URL environment variable with "/api".

!payload

Logic: The !payload tag accesses and injects data from the provided payload into the YAML structure. It can return the entire payload or a specific path within it.

Example 1: Access Full Payload

userData:
  all: !payload '*' # Injects the entire payload under userData.all.

Example 2: Access Specific Field

userData:
  firstName: !payload firstName # Injects only the firstName from the payload.
  city: !payload address.city # Injects the city field from the nested address object.

!markdown-it

Logic: The !markdown-it tag accesses and injects data from the provided payload into the YAML structure. It can return the HTML version of the markdown path payload property.

Example 1: Access Full Payload

userData:
  html: !markdown-it 'payload.markdown.property' # Injects the HTML version of the markdown path into userData.html.

!builder

Logic: The !builder tag constructs a new structure within the YAML based on a provided schema, merging it into the existing data. It's used for creating complex objects dynamically.

Example 1: Build a Full Address

address:
  full: !builder
    street: !payload address.street
    fullAddress: !handlebars "{{ address.street }}, {{ address.city }} {{ address.zip }}" # Constructs fullAddress from street, city, and zip.

Example 2: Build a User Profile

profile:
  userData: !builder
    name: !payload firstName
    fullName: !handlebars "{{ firstName }} {{ lastName }}" # Combines firstName and lastName to create fullName.
    age: !payload age

!date

Logic: The !date tag parses a date string and returns a Date object. This is useful for date manipulations or storing date objects within the YAML configuration.

Example 1: Parse a Birth Date

dates:
  birthDate: !date '6/19/2023, 4:15:36 PM' # Parses the provided date string into a Date object.

Example 2: Current Date

dates:
  currentDate: !date # Parses the current date and time.

!ms

Logic: The !ms tag converts human-readable time durations (e.g., 5d, 10h) into milliseconds. This is useful for time-based configurations like cache expiration or delay intervals.

Example 1: Convert Days to Milliseconds

cache:
  expiration: !ms 5d # Converts 5 days into milliseconds.

Example 2: Convert Hours to Milliseconds

delay:
  retry: !ms 2h # Converts 2 hours into milliseconds for a retry delay.

!ms-date

Logic: The !ms-date tag adds a duration to a given date and returns a new Date object. This allows for date manipulations, like scheduling events a certain number of days after a given date.

Example 1: Add 5 Days to a Specific Date

dates:
  eventDate: !ms-date ['6/

19/2023, 4:15:36 PM', '5d'] # Adds 5 days to the provided date and returns the new Date object.

Example 2: Add Hours to a Specific Date

times:
  endTime: !ms-date ['6/19/2023, 4:15:36 PM', '3h'] # Adds 3 hours to the provided date and returns the new Date object.

!ms-date-day

Logic: The !ms-date-day tag returns the day of the week for a date after adding a duration. This is useful for determining which day of the week a future or past event falls on.

Example 1: Day of the Week After 5 Days

days:
  futureDay: !ms-date-day ['6/19/2023, 4:15:36 PM', '5d'] # Returns the day of the week (0-6, where 0 is Sunday) after adding 5 days.

Example 2: Day of the Week After Hours

days:
  meetingDay: !ms-date-day ['6/19/2023, 4:15:36 PM', '48h'] # Returns the day of the week after adding 48 hours.

!ms-date-date

Logic: The !ms-date-date tag returns the day of the month for a date after adding a duration. This is useful for scheduling events or tasks based on the day of the month.

Example 1: Day of the Month After 5 Days

dates:
  futureDate: !ms-date-date ['6/19/2023, 4:15:36 PM', '5d'] # Returns the day of the month (1-31) after adding 5 days.

Example 2: Day of the Month After Hours

dates:
  paymentDate: !ms-date-date ['6/19/2023, 4:15:36 PM', '72h'] # Returns the day of the month after adding 72 hours.

!ms-date-month

Logic: The !ms-date-month tag returns the month for a date after adding a duration. This is useful for determining the month in which a future event will occur.

Example 1: Month After 5 Days

months:
  futureMonth: !ms-date-month ['6/19/2023, 4:15:36 PM', '5d'] # Returns the month (0-11, where 0 is January) after adding 5 days.

Example 2: Month After Weeks

months:
  nextMonth: !ms-date-month ['6/19/2023, 4:15:36 PM', '2w'] # Returns the month after adding 2 weeks.

!ms-date-year

Logic: The !ms-date-year tag returns the year for a date after adding a duration. This is useful for scheduling events that span across years.

Example 1: Year After 5 Days

years:
  futureYear: !ms-date-year ['6/19/2023, 4:15:36 PM', '5d'] # Returns the year after adding 5 days.

Example 2: Year After Months

years:
  nextYear: !ms-date-year ['6/19/2023, 4:15:36 PM', '6mo'] # Returns the year after adding 6 months.

!ms-current-date

Logic: The !ms-current-date tag adds a duration to the current date and returns a new Date object. This is useful for scheduling future events relative to the current date.

Example 1: 5 Days From Now

dates:
  futureDate: !ms-current-date 5d # Adds 5 days to the current date and returns the new Date object.

Example 2: 3 Hours From Now

times:
  endTime: !ms-current-date 3h # Adds 3 hours to the current time and returns the new Date object.

!ms-current-date-day

Logic: The !ms-current-date-day tag returns the day of the week for the current date after adding a duration. This is useful for determining the day of the week a future event will occur.

Example 1: Day of the Week 5 Days From Now

days:
  futureDay: !ms-current-date-day 5d # Returns the day of the week (0-6) after adding 5 days to the current date.

Example 2: Day of the Week 12 Hours From Now

days:
  nextMeetingDay: !ms-current-date-day 12h # Returns the day of the week after adding 12 hours to the current time.

!ms-current-date-date

Logic: The !ms-current-date-date tag returns the day of the month for the current date after adding a duration. This is useful for scheduling tasks based on the current date.

Example 1: Day of the Month 5 Days From Now

dates:
  futureDate: !ms-current-date-date 5d # Returns the day of the month (1-31) after adding 5 days to the current date.

Example 2: Day of the Month 2 Weeks From Now

dates:
  billingDate: !ms-current-date-date 2w # Returns the day of the month after adding 2 weeks to the current date.

!ms-current-date-month

Logic: The !ms-current-date-month tag returns the month for the current date after adding a duration. This is useful for planning events based on the current month.

Example 1: Month 5 Days From Now

months:
  nextMonth: !ms-current-date-month 5d # Returns the month (0-11) after adding 5 days to the current date.

Example 2: Month 1 Week From Now

months:
  futureMonth: !ms-current-date-month 1w # Returns the month after adding 1 week to the current date.

!ms-current-date-year

Logic: The !ms-current-date-year tag returns the year for the current date after adding a duration. This is useful for scheduling future events that may span across years.

Example 1: Year 5 Days From Now

years:
  nextYear: !ms-current-date-year 5d # Returns the year after adding 5 days to the current date.

Example 2: Year 6 Months From Now

years:
  futureYear: !ms-current-date-year 6mo # Returns the year after adding 6 months to the current date.

Development

Clone the Repository

git clone <repository-url>

Development Build

yarn build -w

Production Build

yarn build

Links

• Handlebars
• Math Helpers (includes only math helper)
• ms

License

This code and all of its associated software is the property of SoLoyal Ltd. You may not reproduce or use any part of this code without the express written consent of SoLoyal Ltd.