@leancodepl/utils 9.5.3 → 9.6.0

package/README.md

@@ -28,13 +28,13 @@ Asserts that a value is not undefined. Throws an error if the value is undefined
 import { assertDefined } from "@leancodepl/utils"
 
 interface User {
-    name: string
-    email: string
+  name: string
+  email: string
 }
 
 function processUserAssert(user?: User) {
-    assertDefined(user) // Throws if undefined, no return value
-    return user.name // TypeScript knows user is defined
+  assertDefined(user) // Throws if undefined, no return value
+  return user.name // TypeScript knows user is defined
 }
 ```
 
@@ -53,13 +53,13 @@ Asserts that a value is not null. Throws an error if the value is null.
 import { assertNotNull } from "@leancodepl/utils"
 
 interface User {
-    name: string
-    email: string
+  name: string
+  email: string
 }
 
 function processData(data: string | null) {
-    assertNotNull(data, "Data cannot be null")
-    return data.toUpperCase() // TypeScript knows data is string
+  assertNotNull(data, "Data cannot be null")
+  return data.toUpperCase() // TypeScript knows data is string
 }
 ```
 
@@ -78,13 +78,13 @@ Asserts that a value is not null or undefined. Throws an error if the value is n
 import { assertNotEmpty } from "@leancodepl/utils"
 
 interface User {
-    name: string
-    email: string
+  name: string
+  email: string
 }
 
 function processValue(value: string | null | undefined) {
-    assertNotEmpty(value, "Value is required")
-    return value.length // TypeScript knows value is string
+  assertNotEmpty(value, "Value is required")
+  return value.length // TypeScript knows value is string
 }
 ```
 
@@ -105,13 +105,13 @@ Ensures that a value is defined, returning it if defined or throwing an error if
 import { ensureDefined } from "@leancodepl/utils"
 
 interface User {
-    name: string
-    email: string
+  name: string
+  email: string
 }
 
 function processUser(user?: User) {
-    const definedUser = ensureDefined(user) // Returns User or throws
-    return definedUser.name
+  const definedUser = ensureDefined(user) // Returns User or throws
+  return definedUser.name
 }
 ```
 
@@ -132,13 +132,13 @@ Ensures that a value is not null, returning it if not null or throwing an error
 import { ensureNotNull } from "@leancodepl/utils"
 
 interface User {
-    name: string
-    email: string
+  name: string
+  email: string
 }
 
 function processData(data: string | null) {
-    const validData = ensureNotNull(data, "Data cannot be null")
-    return validData.toUpperCase()
+  const validData = ensureNotNull(data, "Data cannot be null")
+  return validData.toUpperCase()
 }
 ```
 
@@ -159,13 +159,13 @@ Ensures that a value is not null or undefined, returning it if valid or throwing
 import { ensureNotEmpty } from "@leancodepl/utils"
 
 interface User {
-    name: string
-    email: string
+  name: string
+  email: string
 }
 
 function processValue(value: string | null | undefined) {
-    const validValue = ensureNotEmpty(value, "Value is required")
-    return validValue.length
+  const validValue = ensureNotEmpty(value, "Value is required")
+  return validValue.length
 }
 ```
 
@@ -463,3 +463,28 @@ function MyComponent() {
   );
 }
 ```
+
+### `useSyncState(state, onChange, compare)`
+
+Synchronizes external state changes with a callback function, calling the callback only when state actually changes.
+
+**Parameters:**
+
+- `state: T` - The current state value to monitor for changes
+- `onChange: (state: T) => void` - Callback function executed when state changes
+- `compare?: (a: T, b: T) => boolean` - Optional comparison function to determine if state has changed (defaults to
+  strict equality)
+
+**Usage:**
+
+```typescript
+import { useSyncState } from "@leancodepl/utils";
+
+function MyComponent({ externalValue }: { externalValue: string }) {
+  useSyncState(externalValue, (newValue) => {
+    console.log('Value changed to:', newValue);
+  });
+
+  return <div>{externalValue}</div>;
+}
+```

package/index.cjs.js

@@ -405,6 +405,33 @@ function useBoundRunInTask(block) {
     };
 }
 
+/**
+ * Synchronizes external state changes with a callback function, calling the callback only when state actually changes.
+ *
+ * @param state - The current state value to monitor for changes
+ * @param onChange - Callback function executed when state changes
+ * @param compare - Optional comparison function to determine if state has changed (defaults to strict equality)
+ * @example
+ * ```typescript
+ * import { useSyncState } from "@leancodepl/utils";
+ *
+ * function MyComponent({ externalValue }: { externalValue: string }) {
+ *   useSyncState(externalValue, (newValue) => {
+ *     console.log('Value changed to:', newValue);
+ *   });
+ *
+ *   return <div>{externalValue}</div>;
+ * }
+ * ```
+ */ function useSyncState(state, onChange, compare) {
+    const [prevState, setPrevState] = react.useState(state);
+    const hasChanged = compare ? !compare(state, prevState) : state !== prevState;
+    if (hasChanged) {
+        setPrevState(state);
+        onChange(state);
+    }
+}
+
 exports.addPrefix = addPrefix;
 exports.assertDefined = assertDefined;
 exports.assertNotEmpty = assertNotEmpty;
@@ -422,3 +449,4 @@ exports.useDialog = useDialog;
 exports.useKeyByRoute = useKeyByRoute;
 exports.useRunInTask = useRunInTask;
 exports.useSetUnset = useSetUnset;
+exports.useSyncState = useSyncState;

package/index.esm.js

@@ -403,4 +403,31 @@ function useBoundRunInTask(block) {
     };
 }
 
-export { addPrefix, assertDefined, assertNotEmpty, assertNotNull, capitalizeDeep, downloadFile, ensureDefined, ensureNotEmpty, ensureNotNull, toLowerFirst, toUpperFirst, uncapitalizeDeep, useBoundRunInTask, useDialog, useKeyByRoute, useRunInTask, useSetUnset };
+/**
+ * Synchronizes external state changes with a callback function, calling the callback only when state actually changes.
+ *
+ * @param state - The current state value to monitor for changes
+ * @param onChange - Callback function executed when state changes
+ * @param compare - Optional comparison function to determine if state has changed (defaults to strict equality)
+ * @example
+ * ```typescript
+ * import { useSyncState } from "@leancodepl/utils";
+ *
+ * function MyComponent({ externalValue }: { externalValue: string }) {
+ *   useSyncState(externalValue, (newValue) => {
+ *     console.log('Value changed to:', newValue);
+ *   });
+ *
+ *   return <div>{externalValue}</div>;
+ * }
+ * ```
+ */ function useSyncState(state, onChange, compare) {
+    const [prevState, setPrevState] = useState(state);
+    const hasChanged = compare ? !compare(state, prevState) : state !== prevState;
+    if (hasChanged) {
+        setPrevState(state);
+        onChange(state);
+    }
+}
+
+export { addPrefix, assertDefined, assertNotEmpty, assertNotNull, capitalizeDeep, downloadFile, ensureDefined, ensureNotEmpty, ensureNotNull, toLowerFirst, toUpperFirst, uncapitalizeDeep, useBoundRunInTask, useDialog, useKeyByRoute, useRunInTask, useSetUnset, useSyncState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leancodepl/utils",
-  "version": "9.5.3",
+  "version": "9.6.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public",
@@ -10,7 +10,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@leancodepl/api-date": "9.5.3",
+    "@leancodepl/api-date": "9.6.0",
     "tiny-invariant": ">=1.3.1"
   },
   "peerDependencies": {

package/src/index.d.ts

@@ -14,3 +14,4 @@ export * from "./lib/hooks/useBoundRunInTask";
 export * from "./lib/hooks/useKeyByRoute";
 export * from "./lib/hooks/useSetUnset";
 export * from "./lib/hooks/useDialog";
+export * from "./lib/hooks/useSyncState";

package/src/lib/hooks/useSyncState.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Synchronizes external state changes with a callback function, calling the callback only when state actually changes.
+ *
+ * @param state - The current state value to monitor for changes
+ * @param onChange - Callback function executed when state changes
+ * @param compare - Optional comparison function to determine if state has changed (defaults to strict equality)
+ * @example
+ * ```typescript
+ * import { useSyncState } from "@leancodepl/utils";
+ *
+ * function MyComponent({ externalValue }: { externalValue: string }) {
+ *   useSyncState(externalValue, (newValue) => {
+ *     console.log('Value changed to:', newValue);
+ *   });
+ *
+ *   return <div>{externalValue}</div>;
+ * }
+ * ```
+ */
+export declare function useSyncState<T>(state: T, onChange: (state: T) => void, compare?: (a: T, b: T) => boolean): void;