@soleil-se/app-util 5.10.1 → 5.12.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.12.0] - 2025-10-09
+
+- Add `iteratorToArray`, `nodeIteratorToArray`, `listToArray` and `setToArray` utility functions to convert these data structures into arrays.
+
+## [5.11.0] - 2025-09-04
+
+- Add type-safe wrapper for `@sitevision/api/server/appData` and `@sitevision/api/server/globalAppData`.
+- Adjust types for `fetchJson` and `urlParams` to work better with TypeScript.
+
 ## [5.10.1] - 2025-06-26
 
 - Adjust types for rendering functions.

package/client/fetch-json/index.d.ts

@@ -4,20 +4,53 @@
  * `https://` will be left as is. Other URI:s willbe converted to match a route in the current app
  * with `getRouteUri`.
  *
+ * @template T
  * @param {string} uri - The URI to fetch JSON data from.
- * @param {object} options - The options for the fetch request, see <https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters>.
- * @param {string} options.method - The HTTP method to use in the request.
- * @param {object} options.params - The parameters to be included in the request URL.
- * @param {object} options.body - The body to include in the request.
- * @param {number} options.retries - The number of retries to attempt in case of a timeout error.
- * @param {object} options.headers - The headers to be included in the request.
- * @returns {Promise<object>} A promise that resolves to the JSON response.
- * @throws {Error} If the response is not successful or cannot be parsed as JSON.
+ * @param {Options} [options] - The options for the fetch request with some extensions.
+ * @returns {Promise<T>} A promise that resolves to the JSON response.
+ * @throws {FetchError} If the response is not successful or cannot be parsed as JSON.
  */
-export default function fetchJson(uri: string, options?: {
-    method: string;
-    params: object;
-    body: object;
-    retries: number;
-    headers: object;
-}): Promise<object>;
+export default function fetchJson<T>(uri: string, options?: Options): Promise<T>;
+/**
+ * @typedef {Object} ExtensionOptions
+ * @property {{ [key: string]: unknown }} [params] - The parameters to be included in the request
+ * URL.
+ * @property {number} [retries=0] - The number of retries to attempt in case of a timeout error.
+ *
+ * @typedef {RequestInit & ExtensionOptions} Options
+ */
+/**
+ * Custom error class for fetch-related errors with additional HTTP context.
+ */
+export class FetchError extends Error {
+    /**
+     * @param {string} message - The error message.
+     * @param {Object} [options] - Error options.
+     * @param {number} [options.status] - HTTP status code.
+     * @param {boolean} [options.aborted=false] - Whether the request was aborted.
+     * @param {Object.<string, unknown>} [options.additionalProps] - Additional properties.
+     */
+    constructor(message: string, { status, aborted, ...additionalProps }?: {
+        status?: number;
+        aborted?: boolean;
+        additionalProps?: {
+            [x: string]: unknown;
+        };
+    });
+    status: number;
+    aborted: boolean;
+}
+export type ExtensionOptions = {
+    /**
+     * - The parameters to be included in the request
+     * URL.
+     */
+    params?: {
+        [key: string]: unknown;
+    };
+    /**
+     * - The number of retries to attempt in case of a timeout error.
+     */
+    retries?: number;
+};
+export type Options = RequestInit & ExtensionOptions;

package/client/fetch-json/index.js

@@ -1,5 +1,46 @@
 import { getRouteUri, stringifyParams } from '../../common';
 
+/**
+ * @typedef {Object} ExtensionOptions
+ * @property {{ [key: string]: unknown }} [params] - The parameters to be included in the request
+ * URL.
+ * @property {number} [retries=0] - The number of retries to attempt in case of a timeout error.
+ *
+ * @typedef {RequestInit & ExtensionOptions} Options
+ */
+
+/**
+ * Custom error class for fetch-related errors with additional HTTP context.
+ */
+export class FetchError extends Error {
+  /**
+   * @param {string} message - The error message.
+   * @param {Object} [options] - Error options.
+   * @param {number} [options.status] - HTTP status code.
+   * @param {boolean} [options.aborted=false] - Whether the request was aborted.
+   * @param {Object.<string, unknown>} [options.additionalProps] - Additional properties.
+   */
+  constructor(message, { status, aborted = false, ...additionalProps } = {}) {
+    super(message);
+    this.name = 'FetchError';
+    this.status = status;
+    this.aborted = aborted;
+
+    // Add any additional properties from the error response
+    Object.entries(additionalProps).forEach(([key, value]) => {
+      if (key !== 'message' && key !== 'status' && key !== 'aborted') {
+        this[key] = value;
+      }
+    });
+  }
+}
+
+/**
+ * Builds the URL for the request, handling different URI formats.
+ * @param {string} uri - The URI to convert to a full URL.
+ * @param {{ [key: string]: unknown }} params - Query parameters to include in the URL.
+ * @returns {string} The complete URL for the request.
+ */
 function getUrl(uri, params) {
   if (uri.startsWith('/rest-api') || uri.startsWith('/appresource') || uri.startsWith('/edit-app-config') || !uri.startsWith('/')) {
     return uri + stringifyParams(params, { addQueryPrefix: true });
@@ -7,6 +48,11 @@ function getUrl(uri, params) {
   return getRouteUri(uri, params);
 }
 
+/**
+ * Attempts to parse response text as JSON.
+ * @param {Response} response - The fetch Response object.
+ * @returns {Promise<unknown | undefined>} The parsed JSON object or undefined if parsing fails.
+ */
 async function toJson(response) {
   const text = await response.text();
   try {
@@ -16,31 +62,51 @@ async function toJson(response) {
   }
 }
 
+/**
+ * Creates a FetchError object from a failed response, including JSON error details.
+ * @param {Response} response - The failed fetch Response object.
+ * @returns {Promise<FetchError>} A FetchError with additional properties from the response JSON.
+ */
 async function responseError(response) {
   const json = await toJson(response) || {};
-  const error = new Error(json?.message || response?.statusText);
-  Object.entries(json).forEach(([key, value]) => {
-    error[key] = value;
+  const message = json?.message || response?.statusText;
+  return new FetchError(message, {
+    status: response.status,
+    aborted: false,
+    ...json,
   });
-  error.status = response.status;
-  return error;
 }
 
+/**
+ * Handles the fetch response, throwing errors for non-OK responses and parsing JSON.
+ * @param {Response} response - The fetch Response object.
+ * @returns {Promise<unknown>} The parsed JSON response.
+ * @throws {FetchError} If the response is not OK or cannot be parsed as JSON.
+ */
 async function handleResponse(response) {
   if (!response.ok) {
     throw await responseError(response);
   }
   const json = await toJson(response);
   if (!json) {
-    throw new Error('Response could not be parsed as JSON.');
+    throw new FetchError('Response could not be parsed as JSON.');
   }
   return json;
 }
 
+/**
+ * Checks if the current context is a SiteVision widget/dashboard.
+ * @returns {boolean} True if running in a widget context.
+ */
 function isWidget() {
   return !!window?.sv?.PageContext?.dashboardId;
 }
 
+/**
+ * Modifies request options for widget context by adding required parameters and headers.
+ * @param {Options} options - The original request options.
+ * @returns {Options} Modified options with widget-specific parameters and headers.
+ */
 function getWidgetOptions(options) {
   return {
     ...options,
@@ -55,29 +121,17 @@ function getWidgetOptions(options) {
   };
 }
 
-/**
- * @typedef {Object} ExtensionOptions
- * @property {Object<string,any>} params - The parameters to be included in the request URL.
- * @property {number} retries - The number of retries to attempt in case of a timeout error.
- *
- * @typedef {RequestInit & ExtensionOptions} Options
- */
-
 /**
  * Fetches JSON data from a specified URI.
  * URI:s starting with `/rest-api`, `/appresource`, `/edit-app-config` or a protocol, for example
  * `https://` will be left as is. Other URI:s willbe converted to match a route in the current app
  * with `getRouteUri`.
  *
+ * @template T
  * @param {string} uri - The URI to fetch JSON data from.
- * @param {Options} options - The options for the fetch request with some extensions.
- * @param {string} options.method - The HTTP method to use in the request.
- * @param {object} options.params - The parameters to be included in the request URL.
- * @param {object} options.body - The body to include in the request.
- * @param {number} options.retries - The number of retries to attempt in case of a timeout error.
- * @param {object} options.headers - The headers to be included in the request.
- * @returns {Promise<Object>} A promise that resolves to the JSON response.
- * @throws {Error} If the response is not successful or cannot be parsed as JSON.
+ * @param {Options} [options] - The options for the fetch request with some extensions.
+ * @returns {Promise<T>} A promise that resolves to the JSON response.
+ * @throws {FetchError} If the response is not successful or cannot be parsed as JSON.
  */
 export default function fetchJson(uri, options = {}) {
   const { params = {}, retries = 0, ...rest } = isWidget() ? getWidgetOptions(options) : options;
@@ -89,8 +143,20 @@ export default function fetchJson(uri, options = {}) {
       if (isTimeout && retries > 0) {
         return fetchJson(uri, { ...rest, params, retries: retries - 1 });
       }
-      // eslint-disable-next-line no-param-reassign
-      error.aborted = error.name === 'AbortError';
-      return Promise.reject(error);
+
+      // Handle abort errors
+      if (error.name === 'AbortError') {
+        return Promise.reject(new FetchError(error.message, {
+          status: error.status,
+          aborted: true,
+        }));
+      }
+
+      // Re-throw FetchError as-is, convert other errors
+      if (error instanceof FetchError) {
+        return Promise.reject(error);
+      }
+
+      return Promise.reject(new FetchError(error.message, { status: error.status || 500 }));
     });
 }

package/client/index.d.ts

@@ -1,3 +1,3 @@
-export { default as fetchJson } from "./fetch-json";
 export { default as preventDefault } from "./prevent-default";
 export { getUrlParam, getUrlParams, setUrlParams, updateUrlParams, clearUrlParams } from "./url-params";
+export { default as fetchJson, FetchError } from "./fetch-json";

package/client/index.js

@@ -6,5 +6,5 @@ export {
   clearUrlParams,
 } from './url-params';
 
-export { default as fetchJson } from './fetch-json';
+export { default as fetchJson, FetchError } from './fetch-json';
 export { default as preventDefault } from './prevent-default';

package/client/url-params/index.d.ts

@@ -1,14 +1,15 @@
 /**
  * Set query parameters in the url-field.
- * @param {Object} obj - Values to be set.
- * @param {Object} [options] Optional options.
- * @param {Boolean} [options.scoped = false] If parameter keys should be scoped to current app.
+ * @param {{ [key: string]: unknown }} params - Values to be set.
  */
-export function setUrlParams(params: any): void;
+export function setUrlParams(params: {
+    [key: string]: unknown;
+}): void;
 /**
  * Get query parameter from the url-field.
+ * @param {string} key - The key of the parameter to get.
  */
-export function getUrlParam(key: any): any;
+export function getUrlParam(key: string): any;
 /**
  * Get query parameters from the url-field.
  */
@@ -19,9 +20,11 @@ export function getUrlParams(): {};
 export function clearUrlParams(): void;
 /**
  * Updates query parameters in the url-field.
- * @param {Object} params - Values to be updated.
+ * @param {{ [key: string]: unknown }} params - Values to be updated.
  */
-export function updateUrlParams(params: any): void;
+export function updateUrlParams(params: {
+    [key: string]: unknown;
+}): void;
 declare namespace _default {
     export { getUrlParam };
     export { setUrlParams };

package/client/url-params/index.js

@@ -4,9 +4,7 @@ const isEmpty = (obj) => Object.keys(obj).length === 0 && obj.constructor === Ob
 
 /**
  * Set query parameters in the url-field.
- * @param {Object} obj - Values to be set.
- * @param {Object} [options] Optional options.
- * @param {Boolean} [options.scoped = false] If parameter keys should be scoped to current app.
+ * @param {{ [key: string]: unknown }} params - Values to be set.
  */
 export function setUrlParams(params) {
   const path = (isEmpty(params) ? window.location.pathname : `?${stringifyParams(params)}`);
@@ -16,6 +14,7 @@ export function setUrlParams(params) {
 
 /**
  * Get query parameter from the url-field.
+ * @param {string} key - The key of the parameter to get.
  */
 export function getUrlParam(key) {
   const params = parseParams(window.location.search);
@@ -40,7 +39,7 @@ export function clearUrlParams() {
 
 /**
  * Updates query parameters in the url-field.
- * @param {Object} params - Values to be updated.
+ * @param {{ [key: string]: unknown }} params - Values to be updated.
  */
 export function updateUrlParams(params) {
   setUrlParams(Object.assign(getUrlParams(), params));

package/common/index.d.ts

@@ -1,81 +1,81 @@
-/**
- * Get a prefixed namespace unique for app.
- * @param {string} [prefix='app']
- * @return {string} - Prefixed namespace.
- */
-export function getNamespace(prefix?: string): string;
-/**
- * Generate a unique identifier with a random UUID without dashes.
- * @param {string} prefix Prefix for the identifier.
- * @returns {string} Unique identifier.
- */
-export function generateId(prefix?: string): string;
-/**
- * Stringify an object to a query string compatible with Sitevision.
- * @param {Object} params Object with parameters to stringify.
- * @param {Object} [options] Optional options.
- * @param {Boolean} [options.addQueryPrefix = false] If a leading ? should be added to the string.
- * @returns Stringified parameters.
- */
-export function stringifyParams(params?: any, { addQueryPrefix }?: {
-    addQueryPrefix?: boolean;
-}): string;
-/**
- * Parse an URL or URI to an object containing its query parameters.
- * @param {String} url URL or URI to be parsed, must start with or contain "?".
- * @returns Object with parsed parameters.
- */
-export function parseParams(url?: string): {};
-/**
- * Get URI for a route, same as `getStandaloneUrl` in Sitevision router.
- * @param {string} route A route.
- * @param {object} params Query parameters.
- * @returns {string} URI for route.
- */
-export function getRouteUri(route?: string, params?: object): string;
-/**
- * Get URI for a view, same as `getUrl` in Sitevision router.
- * @deprecated Not used in WebApps 2.
- * @param {string} route A route.
- * @returns {string} URI for view.
- */
-export function getViewUri(route?: string, params?: any): string;
-/**
- * Get URI for a resource.
- * @param {string} resource A resource.
- * @returns {string} URI for a resource.
- */
-export function getResourceUri(resource?: string): string;
-export function setAppProps(data: any): void;
-/**
- * Get appData value or object that is passed to app when rendering.
- * @export
- * @param {string} [key] - Key for value.
- * @return {*|object} - Value or object.
- */
-export function getAppProps(key?: string): any | object;
-/**
- * If the current code is running on the server.
- * @constant {boolean}
- */
-export const isServer: any;
-/**
- * If the current code is running in the browser.
- * @constant {boolean}
- */
-export const isBrowser: boolean;
-/**
- * DOM friendly unique identifier for the WebApp.
- * @constant {string}
- */
-export const appId: string;
-/**
- * If the WebApp is running in offline mode or not.
- * @constant {boolean}
- */
-export const isOffline: boolean;
-/**
- * If the WebApp is running in online mode or not.
- * @constant {boolean}
- */
-export const isOnline: boolean;
+/**
+ * Get a prefixed namespace unique for app.
+ * @param {string} [prefix='app']
+ * @return {string} - Prefixed namespace.
+ */
+export function getNamespace(prefix?: string): string;
+/**
+ * Generate a unique identifier with a random UUID without dashes.
+ * @param {string} prefix Prefix for the identifier.
+ * @returns {string} Unique identifier.
+ */
+export function generateId(prefix?: string): string;
+/**
+ * Stringify an object to a query string compatible with Sitevision.
+ * @param {Object} params Object with parameters to stringify.
+ * @param {Object} [options] Optional options.
+ * @param {Boolean} [options.addQueryPrefix = false] If a leading ? should be added to the string.
+ * @returns Stringified parameters.
+ */
+export function stringifyParams(params?: any, { addQueryPrefix }?: {
+    addQueryPrefix?: boolean;
+}): string;
+/**
+ * Parse an URL or URI to an object containing its query parameters.
+ * @param {String} url URL or URI to be parsed, must start with or contain "?".
+ * @returns Object with parsed parameters.
+ */
+export function parseParams(url?: string): {};
+/**
+ * Get URI for a route, same as `getStandaloneUrl` in Sitevision router.
+ * @param {string} route A route.
+ * @param {object} params Query parameters.
+ * @returns {string} URI for route.
+ */
+export function getRouteUri(route?: string, params?: object): string;
+/**
+ * Get URI for a view, same as `getUrl` in Sitevision router.
+ * @deprecated Not used in WebApps 2.
+ * @param {string} route A route.
+ * @returns {string} URI for view.
+ */
+export function getViewUri(route?: string, params?: any): string;
+/**
+ * Get URI for a resource.
+ * @param {string} resource A resource.
+ * @returns {string} URI for a resource.
+ */
+export function getResourceUri(resource?: string): string;
+export function setAppProps(data: any): void;
+/**
+ * Get appData value or object that is passed to app when rendering.
+ * @export
+ * @param {string} [key] - Key for value.
+ * @return {*|object} - Value or object.
+ */
+export function getAppProps(key?: string): any | object;
+/**
+ * If the current code is running on the server.
+ * @constant {boolean}
+ */
+export const isServer: any;
+/**
+ * If the current code is running in the browser.
+ * @constant {boolean}
+ */
+export const isBrowser: boolean;
+/**
+ * DOM friendly unique identifier for the WebApp.
+ * @constant {string}
+ */
+export const appId: string;
+/**
+ * If the WebApp is running in offline mode or not.
+ * @constant {boolean}
+ */
+export const isOffline: boolean;
+/**
+ * If the WebApp is running in online mode or not.
+ * @constant {boolean}
+ */
+export const isOnline: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soleil-se/app-util",
-  "version": "5.10.1",
+  "version": "5.12.0",
   "description": "Utility functions for WebApps, RESTApps and Widgets in Sitevision.",
   "main": "./common/index.js",
   "author": "Soleil AB",
@@ -23,7 +23,7 @@
     "@sitevision/api": "*"
   },
   "scripts": {
-    "create-type-definitions": "node ../../utils/createTypeDefinitions.js ./common/index.js;./ ./client/index.js ./client/svelte/index.js ./client/svelte/3/index.js ./client/svelte/4/index.js ./client/svelte/5/index.js ./server/index.js ./server/svelte/index.js ./server/svelte/3/index.js ./server/svelte/4/index.js ./server/svelte/5/index.js"
+    "create-type-definitions": "node ../../utils/createTypeDefinitions.js ./common/index.js ./client/index.js ./client/svelte/index.js ./client/svelte/3/index.js ./client/svelte/4/index.js ./client/svelte/5/index.js ./server/index.js ./server/svelte/index.js ./server/svelte/3/index.js ./server/svelte/4/index.js ./server/svelte/5/index.js ./server/app-data/index.js ./server/global-app-data/index.js"
   },
-  "gitHead": "b5a77ddf78f3a1d2204c44bdc4faef035e7961e9"
+  "gitHead": "b307141c40e0116c6f2f2c3354656904d9fedb79"
 }

package/server/app-data/index.d.ts

@@ -0,0 +1,84 @@
+export default appData;
+declare namespace appData {
+    /**
+     * 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.
+     */
+    function get(key: string, ...properties?: string[]): unknown;
+    /**
+     * 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.
+     */
+    function getArray(key: string): string[] | import("@sitevision/api/types/javax/jcr/Node").Node[];
+    /**
+     * 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.
+     */
+    function getString(key: string): string | undefined;
+    /**
+     * 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.
+     */
+    function getBoolean(key: string): boolean | undefined;
+    /**
+     * 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.
+     */
+    function getNumber(key: string): number | undefined;
+    /**
+     * 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.
+     */
+    function getNodes(key: string): import("@sitevision/api/types/javax/jcr/Node").Node[];
+    /**
+     * 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.
+     */
+    function getStrings(key: string): string[];
+    /**
+     * 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.
+     */
+    function getNode(key: string): import("@sitevision/api/types/javax/jcr/Node").Node;
+    /**
+     * 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.
+     */
+    function getStringProperty(key: string, property: string): string | undefined;
+    /**
+     * 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.
+     */
+    function getStringsProperty(key: string, property: string): string[];
+    /**
+     * 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.
+     */
+    function getBooleanProperty(key: string, property: string): boolean | undefined;
+    /**
+     * 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.
+     */
+    function getNumberProperty(key: string, property: string): number | undefined;
+}

package/server/app-data/index.js

@@ -0,0 +1,155 @@
+import appDataSv from '@sitevision/api/server/appData';
+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;
+  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 appData = {
+  /**
+   * 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 appData;

package/server/global-app-data/index.d.ts

@@ -0,0 +1,84 @@
+export default globalAppData;
+declare namespace 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.
+       */
+    function get(key: string, ...properties?: string[]): unknown;
+    /**
+     * 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.
+     */
+    function getArray(key: string): string[] | import("@sitevision/api/types/javax/jcr/Node").Node[];
+    /**
+     * 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.
+     */
+    function getString(key: string): string | undefined;
+    /**
+     * 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.
+     */
+    function getBoolean(key: string): boolean | undefined;
+    /**
+     * 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.
+     */
+    function getNumber(key: string): number | undefined;
+    /**
+     * 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.
+     */
+    function getNodes(key: string): import("@sitevision/api/types/javax/jcr/Node").Node[];
+    /**
+     * 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.
+     */
+    function getStrings(key: string): string[];
+    /**
+     * 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.
+     */
+    function getNode(key: string): import("@sitevision/api/types/javax/jcr/Node").Node;
+    /**
+     * 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.
+     */
+    function getStringProperty(key: string, property: string): string | undefined;
+    /**
+     * 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.
+     */
+    function getStringsProperty(key: string, property: string): string[];
+    /**
+     * 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.
+     */
+    function getBooleanProperty(key: string, property: string): boolean | undefined;
+    /**
+     * 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.
+     */
+    function getNumberProperty(key: string, property: string): number | undefined;
+}

package/server/global-app-data/index.js

@@ -0,0 +1,155 @@
+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;
+  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;

package/server/index.d.ts

@@ -1,6 +1,52 @@
-/**
- * Require a module natively.
- * @param {string} module
- * @returns any
- */
-export function nativeRequire(module: string): any;
+/**
+ * Require a module natively, bypassing Webpack bundling.
+ * This function behaves like CommonJS require() and is used to import
+ * system packages in the Rhino runtime environment where Webpack bundling interferes
+ * with native module resolution.
+ *
+ * @param {string} module - The module identifier
+ * @returns {any} The exported module
+ * @example
+ * // Import a Sitevision API package
+ * const PortletContextUtil = nativeRequire('PortletContextUtil');
+ */
+export function nativeRequire(module: string): any;
+/**
+ * @typedef {import('@sitevision/api/types/javax/jcr/Node').Node} Node
+ * @typedef {import('@sitevision/api/types/javax/jcr/NodeIterator').NodeIterator} NodeIterator
+ * @typedef {import('@sitevision/api/types/java/util/Iterator').Iterator} Iterator
+ * @typedef {import('@sitevision/api/types/java/util/List').List} List
+ * @typedef {import('@sitevision/api/types/java/util/Set').Set} Set
+ */
+/**
+ * Converts an Iterator to an array
+ * @template T
+ * @param {Iterator} iterator - The Iterator to convert
+ * @returns {T[]} Array containing all items from the iterator
+ */
+export function iteratorToArray<T>(iterator: Iterator): T[];
+/**
+ * Converts a NodeIterator to an array of Nodes
+ * @param {NodeIterator} nodeIterator - The NodeIterator to convert
+ * @returns {Node[]} Array containing all nodes from the iterator
+ */
+export function nodeIteratorToArray(nodeIterator: NodeIterator): Node[];
+/**
+ * Converts a List to an array
+ * @template T
+ * @param {List} list - The List to convert
+ * @returns {T[]} Array containing all items from the list
+ */
+export function listToArray<T>(list: List): T[];
+/**
+ * Converts a Set to an array
+ * @template T
+ * @param {Set} set - The Set to convert
+ * @returns {T[]} Array containing all items from the set
+ */
+export function setToArray<T>(set: Set): T[];
+export type Node = import('@sitevision/api/types/javax/jcr/Node').Node;
+export type NodeIterator = import('@sitevision/api/types/javax/jcr/NodeIterator').NodeIterator;
+export type Iterator = import('@sitevision/api/types/java/util/Iterator').Iterator;
+export type List = import('@sitevision/api/types/java/util/List').List;
+export type Set = import('@sitevision/api/types/java/util/Set').Set;

package/server/index.js

@@ -1,12 +1,71 @@
 /* Make native requires work with @sitevision/sitevision-scripts that uses Webpack */
 /* eslint-disable camelcase, no-undef, import/no-dynamic-require, global-require */
 /**
- * Require a module natively.
- * @param {string} module
- * @returns any
+ * Require a module natively, bypassing Webpack bundling.
+ * This function behaves like CommonJS require() and is used to import
+ * system packages in the Rhino runtime environment where Webpack bundling interferes
+ * with native module resolution.
+ *
+ * @param {string} module - The module identifier
+ * @returns {any} The exported module
+ * @example
+ * // Import a Sitevision API package
+ * const PortletContextUtil = nativeRequire('PortletContextUtil');
  */
 export function nativeRequire(module) {
   if (typeof __non_webpack_require__ !== 'undefined') return __non_webpack_require__(module);
   return require(module);
 }
 /* eslint-enable camelcase, no-undef, import/no-dynamic-require, global-require */
+
+/**
+ * @typedef {import('@sitevision/api/types/javax/jcr/Node').Node} Node
+ * @typedef {import('@sitevision/api/types/javax/jcr/NodeIterator').NodeIterator} NodeIterator
+ * @typedef {import('@sitevision/api/types/java/util/Iterator').Iterator} Iterator
+ * @typedef {import('@sitevision/api/types/java/util/List').List} List
+ * @typedef {import('@sitevision/api/types/java/util/Set').Set} Set
+ */
+
+/**
+ * Converts an Iterator to an array
+ * @template T
+ * @param {Iterator} iterator - The Iterator to convert
+ * @returns {T[]} Array containing all items from the iterator
+ */
+export function iteratorToArray(iterator) {
+  const array = [];
+  if (!iterator) return array;
+  while (iterator?.hasNext()) {
+    array.push(iterator?.next());
+  }
+  return array;
+}
+
+/**
+ * Converts a NodeIterator to an array of Nodes
+ * @param {NodeIterator} nodeIterator - The NodeIterator to convert
+ * @returns {Node[]} Array containing all nodes from the iterator
+ */
+export function nodeIteratorToArray(nodeIterator) {
+  return iteratorToArray(nodeIterator);
+}
+
+/**
+ * Converts a List to an array
+ * @template T
+ * @param {List} list - The List to convert
+ * @returns {T[]} Array containing all items from the list
+ */
+export function listToArray(list) {
+  return iteratorToArray(list?.iterator());
+}
+
+/**
+ * Converts a Set to an array
+ * @template T
+ * @param {Set} set - The Set to convert
+ * @returns {T[]} Array containing all items from the set
+ */
+export function setToArray(set) {
+  return iteratorToArray(set?.iterator());
+}