@trackunit/react-core-hooks 1.15.11 → 1.15.12

package/index.cjs.js

@@ -4,6 +4,7 @@ var reactCoreContextsApi = require('@trackunit/react-core-contexts-api');
 var react = require('react');
 var esToolkit = require('es-toolkit');
 var irisAppRuntimeCore = require('@trackunit/iris-app-runtime-core');
+var zod = require('zod');
 
 /**
  * Hook to get the analytics context.
@@ -1050,6 +1051,102 @@ const useUserPermission = (requiredPermission) => {
     }, [permissions, requiredPermission]);
 };
 
+/**
+ * Zod pipeline that parses a non-empty JSON string into an unknown value.
+ * Handles double-encoded JSON by attempting a second parse when the first
+ * result is still a string. Returns a Zod issue (rather than throwing)
+ * when the input is not valid JSON.
+ */
+const jsonParsePipeline = zod.z
+    .string()
+    .min(1)
+    .transform((str, ctx) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(str);
+    }
+    catch {
+        ctx.addIssue({
+            code: zod.z.ZodIssueCode.custom,
+            message: "Invalid JSON string",
+        });
+        return zod.z.NEVER;
+    }
+    if (typeof parsed === "string") {
+        try {
+            parsed = JSON.parse(parsed);
+        }
+        catch {
+            // Not double-encoded, keep the first-level parse
+        }
+    }
+    return parsed;
+});
+/**
+ * Zod pipeline that validates a non-null value and converts it to a JSON string.
+ * Strings are returned as-is; all other values go through `JSON.stringify`.
+ * Non-serialisable values (e.g. circular references) produce a Zod issue
+ * instead of throwing.
+ */
+const stringifySchema = zod.z
+    .unknown()
+    .refine((val) => val !== null && val !== undefined)
+    .transform((val, ctx) => {
+    if (typeof val === "string") {
+        return val;
+    }
+    try {
+        return JSON.stringify(val);
+    }
+    catch {
+        ctx.addIssue({
+            code: zod.z.ZodIssueCode.custom,
+            message: "Value is not serializable to JSON",
+        });
+        return zod.z.NEVER;
+    }
+})
+    .pipe(zod.z.string());
+/**
+ * Hook providing safe JSON parsing and stringification utilities with Zod validation.
+ *
+ * Returns stable callbacks for:
+ * - `safeParse` - Parse JSON and validate against a schema
+ * - `isJSON` - Check if a string is valid JSON
+ * - `safeStringify` - Convert a value to JSON string
+ *
+ * @example
+ * ```ts
+ * const { safeParse, safeStringify, isJSON } = useSettingsUtils();
+ *
+ * const data = safeParse(rawJson, mySchema);
+ * const json = safeStringify(myObject);
+ * const valid = isJSON(someString);
+ * ```
+ */
+const useSettingsUtils = () => {
+    const safeParse = react.useCallback((jsonString, schema) => {
+        if (!jsonString) {
+            return null;
+        }
+        const jsonResult = jsonParsePipeline.pipe(schema).safeParse(jsonString);
+        if (jsonResult.success) {
+            return jsonResult.data;
+        }
+        const rawResult = schema.safeParse(jsonString);
+        return rawResult.success ? rawResult.data : null;
+    }, []);
+    const isJSON = react.useCallback((jsonString) => {
+        const result = jsonParsePipeline.safeParse(jsonString);
+        return result.success && result.data !== null;
+    }, []);
+    const safeStringify = react.useCallback((value) => {
+        const result = stringifySchema.safeParse(value);
+        return result.success ? result.data : null;
+    }, []);
+    return react.useMemo(() => ({ safeParse, isJSON, safeStringify }), [safeParse, isJSON, safeStringify]);
+};
+
 /**
  * This is a hook to use the WidgetConfigProvider.
  *
@@ -1205,6 +1302,7 @@ exports.useIrisAppName = useIrisAppName;
 exports.useModalDialogContext = useModalDialogContext;
 exports.useNavigateInHost = useNavigateInHost;
 exports.useOemBrandingContext = useOemBrandingContext;
+exports.useSettingsUtils = useSettingsUtils;
 exports.useSiteRuntime = useSiteRuntime;
 exports.useTimeRange = useTimeRange;
 exports.useToast = useToast;

package/index.esm.js

@@ -2,6 +2,7 @@ import { AnalyticsContext, AssetSortingContext, ConfirmationDialogContext, Envir
 import { useContext, useMemo, useState, useCallback, useEffect, useReducer, useRef } from 'react';
 import { isEqual } from 'es-toolkit';
 import { AssetRuntime, CustomerRuntime, EventRuntime, ParamsRuntime, SiteRuntime, WidgetConfigRuntime } from '@trackunit/iris-app-runtime-core';
+import { z } from 'zod';
 
 /**
  * Hook to get the analytics context.
@@ -1048,6 +1049,102 @@ const useUserPermission = (requiredPermission) => {
     }, [permissions, requiredPermission]);
 };
 
+/**
+ * Zod pipeline that parses a non-empty JSON string into an unknown value.
+ * Handles double-encoded JSON by attempting a second parse when the first
+ * result is still a string. Returns a Zod issue (rather than throwing)
+ * when the input is not valid JSON.
+ */
+const jsonParsePipeline = z
+    .string()
+    .min(1)
+    .transform((str, ctx) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(str);
+    }
+    catch {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Invalid JSON string",
+        });
+        return z.NEVER;
+    }
+    if (typeof parsed === "string") {
+        try {
+            parsed = JSON.parse(parsed);
+        }
+        catch {
+            // Not double-encoded, keep the first-level parse
+        }
+    }
+    return parsed;
+});
+/**
+ * Zod pipeline that validates a non-null value and converts it to a JSON string.
+ * Strings are returned as-is; all other values go through `JSON.stringify`.
+ * Non-serialisable values (e.g. circular references) produce a Zod issue
+ * instead of throwing.
+ */
+const stringifySchema = z
+    .unknown()
+    .refine((val) => val !== null && val !== undefined)
+    .transform((val, ctx) => {
+    if (typeof val === "string") {
+        return val;
+    }
+    try {
+        return JSON.stringify(val);
+    }
+    catch {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Value is not serializable to JSON",
+        });
+        return z.NEVER;
+    }
+})
+    .pipe(z.string());
+/**
+ * Hook providing safe JSON parsing and stringification utilities with Zod validation.
+ *
+ * Returns stable callbacks for:
+ * - `safeParse` - Parse JSON and validate against a schema
+ * - `isJSON` - Check if a string is valid JSON
+ * - `safeStringify` - Convert a value to JSON string
+ *
+ * @example
+ * ```ts
+ * const { safeParse, safeStringify, isJSON } = useSettingsUtils();
+ *
+ * const data = safeParse(rawJson, mySchema);
+ * const json = safeStringify(myObject);
+ * const valid = isJSON(someString);
+ * ```
+ */
+const useSettingsUtils = () => {
+    const safeParse = useCallback((jsonString, schema) => {
+        if (!jsonString) {
+            return null;
+        }
+        const jsonResult = jsonParsePipeline.pipe(schema).safeParse(jsonString);
+        if (jsonResult.success) {
+            return jsonResult.data;
+        }
+        const rawResult = schema.safeParse(jsonString);
+        return rawResult.success ? rawResult.data : null;
+    }, []);
+    const isJSON = useCallback((jsonString) => {
+        const result = jsonParsePipeline.safeParse(jsonString);
+        return result.success && result.data !== null;
+    }, []);
+    const safeStringify = useCallback((value) => {
+        const result = stringifySchema.safeParse(value);
+        return result.success ? result.data : null;
+    }, []);
+    return useMemo(() => ({ safeParse, isJSON, safeStringify }), [safeParse, isJSON, safeStringify]);
+};
+
 /**
  * This is a hook to use the WidgetConfigProvider.
  *
@@ -1174,4 +1271,4 @@ const useWidgetConfig = () => {
     return result;
 };
 
-export { fetchAssetBlobUrl, useAnalytics, useAssetRuntime, useAssetSorting, useConfirmationDialog, useCurrentUser, useCurrentUserFavoriteAdvancedSensors, useCurrentUserFavoriteInsights, useCurrentUserLanguage, useCurrentUserSystemOfMeasurement, useCurrentUserTimeZonePreference, useCustomerRuntime, useEnvironment, useErrorHandler, useErrorHandlerOrNull, useEventRuntime, useExportDataContext, useFeatureBranchQueryString, useFeatureFlags, useFilterBarContext, useGeolocation, useHasAccessTo, useImageUploader, useIrisAppId, useIrisAppImage, useIrisAppName, useModalDialogContext, useNavigateInHost, useOemBrandingContext, useSiteRuntime, useTimeRange, useToast, useToken, useUserPermission, useUserSubscription, useWidgetConfig, useWidgetConfigAsync };
+export { fetchAssetBlobUrl, useAnalytics, useAssetRuntime, useAssetSorting, useConfirmationDialog, useCurrentUser, useCurrentUserFavoriteAdvancedSensors, useCurrentUserFavoriteInsights, useCurrentUserLanguage, useCurrentUserSystemOfMeasurement, useCurrentUserTimeZonePreference, useCustomerRuntime, useEnvironment, useErrorHandler, useErrorHandlerOrNull, useEventRuntime, useExportDataContext, useFeatureBranchQueryString, useFeatureFlags, useFilterBarContext, useGeolocation, useHasAccessTo, useImageUploader, useIrisAppId, useIrisAppImage, useIrisAppName, useModalDialogContext, useNavigateInHost, useOemBrandingContext, useSettingsUtils, useSiteRuntime, useTimeRange, useToast, useToken, useUserPermission, useUserSubscription, useWidgetConfig, useWidgetConfigAsync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-core-hooks",
-  "version": "1.15.11",
+  "version": "1.15.12",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -8,9 +8,10 @@
   },
   "dependencies": {
     "es-toolkit": "^1.39.10",
-    "@trackunit/iris-app-runtime-core": "1.15.10",
-    "@trackunit/iris-app-runtime-core-api": "1.14.10",
-    "@trackunit/react-core-contexts-api": "1.15.10"
+    "@trackunit/iris-app-runtime-core": "1.15.11",
+    "@trackunit/iris-app-runtime-core-api": "1.14.11",
+    "@trackunit/react-core-contexts-api": "1.15.11",
+    "zod": "^3.25.76"
   },
   "peerDependencies": {
     "react": "^19.0.0"

package/src/index.d.ts

@@ -27,4 +27,5 @@ export * from "./useFeatureBranchQueryString";
 export * from "./user/useCurrentUser";
 export * from "./user/useCurrentUserPreference";
 export * from "./user/useUserPermission";
+export * from "./utilities/useSettingsUtils";
 export * from "./widgetConfig/useWidgetConfig";

package/src/utilities/useSettingsUtils.d.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+export interface SettingsUtils {
+    /**
+     * Safely parses a JSON string and validates the result against a Zod schema.
+     * Returns the validated value when parsing and validation succeed, otherwise `null`.
+     * The return type is inferred from the schema — no type assertions needed.
+     *
+     * @param jsonString - The JSON string to parse, or `null`.
+     * @param schema - A Zod schema that describes the expected shape of the parsed value.
+     * @example
+     * ```ts
+     * const result = safeParse('{"name":"Ada"}', z.object({ name: z.string() }));
+     * // result: { name: "Ada" }
+     *
+     * const num = safeParse("42", z.number());
+     * // num: 42
+     *
+     * const miss = safeParse('{"a":1}', z.object({ b: z.string() }));
+     * // miss: null
+     * ```
+     */
+    safeParse: <TValue>(jsonString: string | null, schema: z.ZodType<TValue>) => TValue | null;
+    /**
+     * Checks whether a string is valid, non-null JSON.
+     *
+     * Returns `false` for the JSON literal `"null"` to match the legacy behaviour
+     * where `JSON.parse(str) !== null` was required.
+     *
+     * @param jsonString - The string to test.
+     * @returns `true` when the string can be parsed as non-null JSON.
+     */
+    isJSON: (jsonString: string) => boolean;
+    /**
+     * Safely converts a value to a JSON string using a Zod validation pipeline.
+     *
+     * - Returns the value unchanged if it is already a string.
+     * - Returns `null` for `null` / `undefined` or if serialisation fails
+     *   (e.g. circular references).
+     *
+     * @param value - The value to stringify.
+     * @returns The JSON string representation, or `null` on failure.
+     * @example
+     * ```ts
+     * safeStringify({ a: 1 })   // '{"a":1}'
+     * safeStringify("hello")    // "hello"
+     * safeStringify(null)       // null
+     * ```
+     */
+    safeStringify: (value: unknown) => string | null;
+}
+/**
+ * Hook providing safe JSON parsing and stringification utilities with Zod validation.
+ *
+ * Returns stable callbacks for:
+ * - `safeParse` - Parse JSON and validate against a schema
+ * - `isJSON` - Check if a string is valid JSON
+ * - `safeStringify` - Convert a value to JSON string
+ *
+ * @example
+ * ```ts
+ * const { safeParse, safeStringify, isJSON } = useSettingsUtils();
+ *
+ * const data = safeParse(rawJson, mySchema);
+ * const json = safeStringify(myObject);
+ * const valid = isJSON(someString);
+ * ```
+ */
+export declare const useSettingsUtils: () => SettingsUtils;