@trackunit/react-core-hooks 1.14.4 → 1.14.5-alpha-58b6b568fca.0

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.
@@ -1056,6 +1057,128 @@ 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;
+});
+/**
+ * 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
+ * ```
+ */
+const safeParse = (jsonString, schema) => {
+    if (!jsonString) {
+        return null;
+    }
+    const jsonResult = jsonParsePipeline.pipe(schema).safeParse(jsonString);
+    if (jsonResult.success) {
+        return jsonResult.data;
+    }
+    // Not valid JSON — try validating the raw string directly
+    const rawResult = schema.safeParse(jsonString);
+    return rawResult.success ? rawResult.data : null;
+};
+/**
+ * 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());
+/**
+ * Checks whether a string is valid, non-null JSON.
+ *
+ * Reuses the internal {@link jsonParsePipeline} so that the parsing logic
+ * stays in one place. 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 {boolean} `true` when the string can be parsed as non-null JSON.
+ */
+const isJSON = (jsonString) => {
+    const result = jsonParsePipeline.safeParse(jsonString);
+    return result.success && result.data !== null;
+};
+/**
+ * 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 {string | null} The JSON string representation, or `null` on failure.
+ * @example
+ * ```ts
+ * safeStringify({ a: 1 })   // '{"a":1}'
+ * safeStringify("hello")    // "hello"
+ * safeStringify(null)       // null
+ * ```
+ */
+const safeStringify = (value) => {
+    const result = stringifySchema.safeParse(value);
+    return result.success ? result.data : null;
+};
+
 /**
  * This is a hook to use the WidgetConfigProvider.
  *
@@ -1183,6 +1306,9 @@ const useWidgetConfig = () => {
 };
 
 exports.fetchAssetBlobUrl = fetchAssetBlobUrl;
+exports.isJSON = isJSON;
+exports.safeParse = safeParse;
+exports.safeStringify = safeStringify;
 exports.useAnalytics = useAnalytics;
 exports.useAssetRuntime = useAssetRuntime;
 exports.useAssetSorting = useAssetSorting;

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.
@@ -1054,6 +1055,128 @@ 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;
+});
+/**
+ * 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
+ * ```
+ */
+const safeParse = (jsonString, schema) => {
+    if (!jsonString) {
+        return null;
+    }
+    const jsonResult = jsonParsePipeline.pipe(schema).safeParse(jsonString);
+    if (jsonResult.success) {
+        return jsonResult.data;
+    }
+    // Not valid JSON — try validating the raw string directly
+    const rawResult = schema.safeParse(jsonString);
+    return rawResult.success ? rawResult.data : null;
+};
+/**
+ * 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());
+/**
+ * Checks whether a string is valid, non-null JSON.
+ *
+ * Reuses the internal {@link jsonParsePipeline} so that the parsing logic
+ * stays in one place. 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 {boolean} `true` when the string can be parsed as non-null JSON.
+ */
+const isJSON = (jsonString) => {
+    const result = jsonParsePipeline.safeParse(jsonString);
+    return result.success && result.data !== null;
+};
+/**
+ * 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 {string | null} The JSON string representation, or `null` on failure.
+ * @example
+ * ```ts
+ * safeStringify({ a: 1 })   // '{"a":1}'
+ * safeStringify("hello")    // "hello"
+ * safeStringify(null)       // null
+ * ```
+ */
+const safeStringify = (value) => {
+    const result = stringifySchema.safeParse(value);
+    return result.success ? result.data : null;
+};
+
 /**
  * This is a hook to use the WidgetConfigProvider.
  *
@@ -1180,4 +1303,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, isJSON, safeParse, safeStringify, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-core-hooks",
-  "version": "1.14.4",
+  "version": "1.14.5-alpha-58b6b568fca.0",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -8,9 +8,11 @@
   },
   "dependencies": {
     "es-toolkit": "^1.39.10",
-    "@trackunit/iris-app-runtime-core": "1.14.3",
-    "@trackunit/iris-app-runtime-core-api": "1.13.3",
-    "@trackunit/react-core-contexts-api": "1.14.3"
+    "@trackunit/iris-app-runtime-core": "1.14.4-alpha-58b6b568fca.0",
+    "@trackunit/iris-app-runtime-core-api": "1.13.4-alpha-58b6b568fca.0",
+    "@trackunit/react-core-contexts-api": "1.14.4-alpha-58b6b568fca.0",
+    "@trackunit/react-core-contexts-test": "1.14.5-alpha-58b6b568fca.0",
+    "zod": "^3.23.8"
   },
   "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/SettingsUtils";
 export * from "./widgetConfig/useWidgetConfig";

package/src/utilities/SettingsUtils.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+/**
+ * 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
+ * ```
+ */
+export declare const safeParse: <TValue>(jsonString: string | null, schema: z.ZodType<TValue>) => TValue | null;
+/**
+ * Checks whether a string is valid, non-null JSON.
+ *
+ * Reuses the internal {@link jsonParsePipeline} so that the parsing logic
+ * stays in one place. 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 {boolean} `true` when the string can be parsed as non-null JSON.
+ */
+export declare const 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 {string | null} The JSON string representation, or `null` on failure.
+ * @example
+ * ```ts
+ * safeStringify({ a: 1 })   // '{"a":1}'
+ * safeStringify("hello")    // "hello"
+ * safeStringify(null)       // null
+ * ```
+ */
+export declare const safeStringify: (value: unknown) => string | null;