feat: parse boolean utility function

Author: lewis-wow

packages/utilities/src/index.ts

@@ -10,3 +10,4 @@ export * from './url_params_utils';
 export * from './code_hash_manager';
 export * from './hmac';
 export * from './storages';
+export * from './parse_boolean';

packages/utilities/src/parse_boolean.ts

@@ -0,0 +1,22 @@
+/**
+ * Strictly parses a value to a boolean, returning `null` if the value is invalid.
+ * - Returns `true` for: `true`, `1`, `'1'`, `'true'` (case-insensitive).
+ * - Returns `false` for: `false`, `0`, `'0'`, `'false'` (case-insensitive).
+ * - Returns `null` for any other value.
+ *
+ * @param value - The value to parse (unknown type).
+ * @returns {boolean | null} The parsed boolean or null if the input is invalid.
+ */
+export const parseBooleanOrNull = (value: unknown): boolean | null => {
+    if (value === true || value === 1) return true;
+    if (value === false || value === 0) return false;
+
+    if (typeof value === 'string') {
+        const lowerValue = value.trim().toLowerCase();
+        if (lowerValue === 'true' || lowerValue === '1') return true;
+        if (lowerValue === 'false' || lowerValue === '0') return false;
+    }
+
+    // Return null for invalid/ambiguous input
+    return null;
+};

test/utilities.test.ts

@@ -416,3 +416,17 @@ describe('createInjectableRegExp()', () => {
         expect(utils.createInjectableRegExp(/[\w._~]+/)).toStrictEqual(/[\w._~]+/);
     });
 });
+
+describe('parseBooleanOrNull', () => {
+    it.each([true, 'true', 'TRUE', 'TrUe', 1, '1'])('Return true for %s value', (value) => {
+        expect(utils.parseBooleanOrNull(value)).toBe(true);
+    });
+
+    it.each([false, 'false', 'FALSE', 'FaLsE', 0, '0'])('Return false for %s value', (value) => {
+        expect(utils.parseBooleanOrNull(value)).toBe(false);
+    });
+
+    it.each([undefined, null, 'null', {}, [], -1])('Return null for %s value', (value) => {
+        expect(utils.parseBooleanOrNull(value)).toBe(null);
+    });
+});