@soleil-se/app-util 5.11.0 → 5.12.1

package/CHANGELOG.md

@@ -7,6 +7,14 @@ 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.1] - 2025-10-15
+
+- Return identifier for Node instances in `toString` function in `app-data` and `global-app-data`.
+
+## [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`.

package/client/index.d.ts

@@ -1,3 +1,3 @@
-export { default as preventDefault } from "./prevent-default";
-export { getUrlParam, getUrlParams, setUrlParams, updateUrlParams, clearUrlParams } from "./url-params";
-export { default as fetchJson, FetchError } 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soleil-se/app-util",
-  "version": "5.11.0",
+  "version": "5.12.1",
   "description": "Utility functions for WebApps, RESTApps and Widgets in Sitevision.",
   "main": "./common/index.js",
   "author": "Soleil AB",
@@ -25,5 +25,5 @@
   "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 ./server/app-data/index.js ./server/global-app-data/index.js"
   },
-  "gitHead": "972710bfa1a879efbd9ff95f6e2562eef4dd31d3"
+  "gitHead": "a0f04b22e5c5262f1c270f69485a22bbb6638d3e"
 }

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

@@ -1,84 +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;
-}
+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

@@ -9,6 +9,7 @@ import InstanceTypeUtil from '@sitevision/api/server/InstanceTypeUtil';
  */
 function toString(value) {
   if (value === null || value === undefined) return undefined;
+  if (InstanceTypeUtil.isNode(value)) return value.getIdentifier();
   return value.toString();
 }
 

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

@@ -1,84 +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;
-}
+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

@@ -9,6 +9,7 @@ import InstanceTypeUtil from '@sitevision/api/server/InstanceTypeUtil';
  */
 function toString(value) {
   if (value === null || value === undefined) return undefined;
+  if (InstanceTypeUtil.isNode(value)) return value.getIdentifier();
   return value.toString();
 }
 

package/server/index.d.ts

@@ -1,6 +1,52 @@
 /**
- * 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: 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());
+}