feat: add nullsToUndefined utility function to convert null values to undefined

Author: piotrkulpinski

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@primoui/utils",
   "description": "A lightweight set of utilities",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "license": "MIT",
   "type": "module",
   "author": {

src/helpers/helpers.test.ts

@@ -8,6 +8,7 @@ import {
   isCuid,
   isTruthy,
   joinAsSentence,
+  nullsToUndefined,
   range,
   slugify,
   splitArrayIntoChunks,
@@ -193,3 +194,175 @@ describe("tryCatch", () => {
     expect(result.error).toEqual(error)
   })
 })
+
+describe("nullsToUndefined", () => {
+  it("should convert null to undefined", () => {
+    expect(nullsToUndefined(null)).toEqual(undefined)
+  })
+
+  it("should preserve undefined values", () => {
+    expect(nullsToUndefined(undefined)).toEqual(undefined)
+  })
+
+  it("should preserve primitive values", () => {
+    expect(nullsToUndefined("hello")).toEqual("hello")
+    expect(nullsToUndefined(42)).toEqual(42)
+    expect(nullsToUndefined(true)).toEqual(true)
+    expect(nullsToUndefined(false)).toEqual(false)
+    expect(nullsToUndefined(0)).toEqual(0)
+  })
+
+  it("should convert null properties in objects to undefined", () => {
+    const input = {
+      name: "John",
+      age: null,
+      active: true,
+      description: null,
+    }
+
+    const result = nullsToUndefined(input)
+
+    expect(result).toEqual({
+      name: "John",
+      age: undefined,
+      active: true,
+      description: undefined,
+    })
+  })
+
+  it("should recursively convert null values in nested objects", () => {
+    const input = {
+      user: {
+        name: "John",
+        profile: {
+          bio: null,
+          avatar: "avatar.jpg",
+          settings: {
+            theme: null,
+            notifications: true,
+          },
+        },
+      },
+      data: null,
+    }
+
+    const result = nullsToUndefined(input)
+
+    expect(result).toEqual({
+      user: {
+        name: "John",
+        profile: {
+          bio: undefined,
+          avatar: "avatar.jpg",
+          settings: {
+            theme: undefined,
+            notifications: true,
+          },
+        },
+      },
+      data: undefined,
+    })
+  })
+
+  it("should handle empty objects", () => {
+    const input = {}
+    const result = nullsToUndefined(input)
+    expect(result).toEqual({})
+  })
+
+  it("should handle objects with only null values", () => {
+    const input = {
+      a: null,
+      b: null,
+      c: null,
+    }
+
+    const result = nullsToUndefined(input)
+
+    expect(result).toEqual({
+      a: undefined,
+      b: undefined,
+      c: undefined,
+    })
+  })
+
+  it("should mutate the original object", () => {
+    const input = {
+      name: "John",
+      age: null,
+    }
+
+    const result = nullsToUndefined(input)
+
+    // Should return the same reference
+    expect(result).toBe(input)
+    // Original object should be mutated
+    expect(input.age).toEqual(undefined)
+  })
+
+  it("should handle arrays (current behavior: not processed recursively)", () => {
+    const input = [null, "hello", null, 42]
+    const result = nullsToUndefined(input)
+
+    // Arrays are not plain objects (constructor.name !== "Object"), so they're returned as-is
+    expect(result).toEqual([null, "hello", null, 42])
+    expect(result).toBe(input)
+  })
+
+  it("should handle Date objects (current behavior: processed as objects)", () => {
+    const date = new Date("2023-01-01")
+    const result = nullsToUndefined(date)
+
+    // Date objects have constructor.name !== "Object", so they're returned as-is
+    expect(result).toEqual(date)
+    expect(result).toBe(date)
+  })
+
+  it("should handle objects containing arrays", () => {
+    const input = {
+      list: [null, "item", null],
+      name: null,
+    }
+
+    const result = nullsToUndefined(input)
+
+    expect(result).toEqual({
+      list: [null, "item", null], // Array is not processed
+      name: undefined, // Object property is processed
+    })
+  })
+
+  it("should handle complex mixed data structures", () => {
+    const input = {
+      id: 1,
+      name: null,
+      metadata: {
+        created: "2023-01-01",
+        updated: null,
+        tags: ["tag1", null, "tag2"],
+        config: {
+          enabled: null,
+          value: 42,
+        },
+      },
+      stats: null,
+    }
+
+    const result = nullsToUndefined(input)
+
+    expect(result).toEqual({
+      id: 1,
+      name: undefined,
+      metadata: {
+        created: "2023-01-01",
+        updated: undefined,
+        tags: ["tag1", null, "tag2"], // Arrays not processed
+        config: {
+          enabled: undefined,
+          value: 42,
+        },
+      },
+      stats: undefined,
+    })
+  })
+})

src/helpers/helpers.ts

@@ -1,4 +1,5 @@
 import slugifyString from "@sindresorhus/slugify"
+import { ReplaceNullWithUndefined } from ".."
 
 /**
  * A collection of helper functions used throughout the application.
@@ -232,3 +233,23 @@ export const tryCatch = async <T, E = Error>(promise: Promise<T>): Promise<Resul
     return { data: null, error: error as E }
   }
 }
+
+/**
+ * Converts all null values in an object to undefined.
+ * @param obj - The object to convert.
+ * @returns The converted object.
+ */
+export function nullsToUndefined<T>(obj: T): ReplaceNullWithUndefined<T> {
+  if (obj === null) {
+    return undefined as any
+  }
+
+  // object check based on: https://stackoverflow.com/a/51458052/6489012
+  if (obj?.constructor.name === "Object") {
+    for (const key in obj) {
+      obj[key] = nullsToUndefined(obj[key]) as any
+    }
+  }
+
+  return obj as any
+}

src/index.ts

@@ -44,3 +44,13 @@ export type NestedPartial<T> = {
 export type NestedRequired<T> = {
   [K in keyof T]-?: T[K] extends object ? NestedRequired<T[K]> : T[K]
 }
+
+export type ReplaceNullWithUndefined<T> = T extends null
+  ? undefined
+  : T extends Date
+    ? T
+    : {
+        [K in keyof T]: T[K] extends (infer U)[]
+          ? ReplaceNullWithUndefined<U>[]
+          : ReplaceNullWithUndefined<T[K]>
+      }