@soleil-se/app-util/server/global-app-data/index.js

Utility functions for WebApps, RESTApps and Widgets in Sitevision.

import appDataSv from '@sitevision/api/server/globalAppData';
import InstanceTypeUtil from '@sitevision/api/server/InstanceTypeUtil';

/**
 * Converts the value returned by appData.get to a string representation.
 * @param {any} value - The value to convert.
 * @returns {string | undefined} - The string representation of the value or undefined if not a
 * string.
 */
function toString(value) {
  if (value === null || value === undefined) return undefined;
  if (InstanceTypeUtil.isNode(value)) return value.getIdentifier();
  return value.toString();
}

/**
 * Converts the value returned by appData.get to a boolean representation.
 * @param {any} value - The value to convert.
 * @returns {boolean | undefined} - The boolean representation of the value or undefined if not a
 * boolean.
 */
function toBoolean(value) {
  if (value === undefined || value === null) return undefined;
  return !!value;
}

/**
 * Converts the value returned by appData.get to a number representation.
 * @param {any} value - The value to convert.
 * @returns {number | undefined} - The number representation of the value or undefined if not a
 * number.
 */
function toNumber(value) {
  if (value === undefined || value === null) return undefined;
  const num = +value;
  return Number.isNaN(num) ? undefined : num;
}

const globalAppData = {
/**
   * Get a value from app data, same as get in \@sitevision/api/server/appData.
   * @param {string} key - The key of app data to retrieve.
   * @param {...string} [properties] - The keys of the properties to retrieve from a JCR Node.
   * @returns {unknown} The value of the app data or a properties of a JCR Node.
   */
  get(key, ...properties) {
    return appDataSv.get(key, ...properties);
  },
  /**
   * Get a value from app data as an array, same as getArray in \@sitevision/api/server/appData.
   * @param {string} key - The key of app data to retrieve.
   * @returns {import('@sitevision/api/types/javax/jcr/Node').Node[] | string[]} An array of JCR
   * Nodes for list components or value wrapped in an array for single type components.
   */
  getArray(key) {
    return appDataSv.getArray(key);
  },
  /**
   * Get a string value from app data.
   * @param {string} key - The key of app data to retrieve.
   * @returns {string | undefined} The string value or undefined if not set.
   */
  getString(key) {
    return toString(appDataSv.get(key));
  },
  /**
   * Get a boolean value from app data.
   * @param {string} key - The key of app data to retrieve.
   * @returns {boolean | undefined} The boolean value or undefined if not set.
   */
  getBoolean(key) {
    return toBoolean(appDataSv.get(key));
  },
  /**
   * Get a number value from app data.
   * @param {string} key - The key of app data to retrieve.
   * @returns {number | undefined} The number value, undefined if not set or not a number.
   */
  getNumber(key) {
    return toNumber(appDataSv.get(key));
  },
  /**
   * Get an array of nodes from app data.
   * @param {string} key - The key of app data to retrieve.
   * @returns {import('@sitevision/api/types/javax/jcr/Node').Node[]} The array of nodes or an
   * empty array if not set.
   */
  getNodes(key) {
    return appDataSv.getArray(key)?.filter((v) => InstanceTypeUtil.isNode(v)) || [];
  },
  /**
   * Get an array of strings from app data.
   * @param {string} key - The key of app data to retrieve.
   * @returns {string[]} The array of strings or an empty array if not set.
   */
  getStrings(key) {
    return appDataSv.getArray(key)
      ?.map((v) => toString(v))
      ?.filter((v) => v !== undefined) || [];
  },
  /**
   * Get a JCR Node from app data.
   * @param {string} key - The key of the property to retrieve.
   * @returns {import('@sitevision/api/types/javax/jcr/Node').Node | undefined} The JCR Node or
   * undefined if not set.
   */
  getNode(key) {
    return appDataSv.getNode(key) ?? undefined;
  },
  /**
   * Get a string property from a JCR Node referenced in app data.
   * @param {string} key - The key of the app data value.
   * @param {string} property - The property to retrieve from the node.
   * @returns {string | undefined} The string property value or undefined if not set.
   */
  getStringProperty(key, property) {
    return toString(appDataSv.get(key, property));
  },
  /**
   * Get a string array property or a single string wrapped in an array from a JCR Node referenced
   * in app data.
   * @param {string} key - The key of app data to retrieve.
   * @param {string} property - The property to retrieve from the node.
   * @returns {string[]} The array of strings or an empty array if not set.
   */
  getStringsProperty(key, property) {
    let value = appDataSv.get(key, property);
    if (Array.isArray(value)) {
      return value
        ?.map((v) => toString(v))
        ?.filter((v) => v !== undefined) || [];
    }
    value = toString(value);
    return value ? [value] : [];
  },
  /**
   * Get a boolean property from a JCR Node referenced in app data.
   * @param {string} key - The key of the app data value.
   * @param {string} property - The property to retrieve from the node.
   * @returns {boolean | undefined} The boolean property value or undefined if not set.
   */
  getBooleanProperty(key, property) {
    return toBoolean(appDataSv.get(key, property));
  },
  /**
   * Get a number property from a JCR Node referenced in app data.
   * @param {string} key - The key of the app data value.
   * @param {string} property - The property to retrieve from the node.
   * @returns {number | undefined} The number property value, undefined if not set or not a number.
   */
  getNumberProperty(key, property) {
    return toNumber(appDataSv.get(key, property));
  },
};

export default globalAppData;