strip-undefined-values 1.0.0

package/README.md

@@ -0,0 +1,135 @@
+# strip-undefined-values
+
+Remove `undefined` values from an object before sending to APIs, databases, or serializers.
+
+Zero dependencies. Fully typed. Tiny. Shallow.
+
+```ts
+import { stripUndefined } from "strip-undefined-values"
+
+stripUndefined({ name: "Tomas", age: undefined, active: true })
+// => { name: "Tomas", active: true }
+```
+
+---
+
+## Installation
+
+```bash
+npm install strip-undefined-values
+```
+
+```bash
+pnpm add strip-undefined-values
+```
+
+```bash
+yarn add strip-undefined-values
+```
+
+---
+
+## API
+
+```ts
+function stripUndefined<T extends Record<string, any>>(obj: T): StripUndefined<T>
+```
+
+Removes own properties whose value is strictly `undefined`.
+Returns a **new object** — does **not** mutate the input.
+Nested objects are not traversed (shallow only).
+
+| Value       | Kept? |
+| ----------- | ----- |
+| `null`      | Yes   |
+| `false`     | Yes   |
+| `0`         | Yes   |
+| `""`        | Yes   |
+| `NaN`       | Yes   |
+| `undefined` | **No**|
+
+---
+
+## TypeScript
+
+The return type `StripUndefined<T>` automatically excludes keys whose type includes `undefined`:
+
+```ts
+type Input = { name: string; age: number | undefined; active: boolean }
+type Output = StripUndefined<Input>
+//   ^? { name: string; active: boolean }
+```
+
+This is intentionally conservative — the type is stricter than runtime so you can never accidentally access a possibly-undefined property on the result.
+
+You can also use `StripUndefined<T>` standalone as a utility type:
+
+```ts
+import type { StripUndefined } from "strip-undefined-values"
+```
+
+---
+
+## Common Use Cases
+
+### API payloads / PATCH requests
+
+```ts
+await fetch("/api/user", {
+  method: "PATCH",
+  body: JSON.stringify(stripUndefined({ name, email, age }))
+})
+```
+
+### Query parameters
+
+```ts
+const params = stripUndefined({ page, search, sort })
+const url = `/items?${new URLSearchParams(params)}`
+```
+
+### Prisma / database updates
+
+```ts
+await prisma.user.update({
+  where: { id },
+  data: stripUndefined({ name, email, bio })
+})
+```
+
+### GraphQL variables
+
+```ts
+const { data } = await client.query({
+  query: GET_USERS,
+  variables: stripUndefined({ first, after, filter })
+})
+```
+
+### Optional form fields
+
+```ts
+const formData = stripUndefined({
+  title: form.title,
+  description: form.description || undefined,
+  category: form.category || undefined,
+})
+```
+
+---
+
+## Comparison
+
+| Approach | Typed? | Deps | Deep? | Mutates? |
+| --- | --- | --- | --- | --- |
+| **`strip-undefined-values`** | **Yes** | **0** | No | No |
+| `lodash.omitBy` | Partial | 1 | No | No |
+| `Object.fromEntries(…filter…)` | No | 0 | No | No |
+| `remove-undefined-objects` | No | 1+ | Yes | No |
+| Manual `delete` | No | 0 | No | **Yes** |
+
+---
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripUndefined = stripUndefined;
+/**
+ * Remove own properties whose value is strictly `undefined` from an object.
+ *
+ * Returns a **new** plain object — the input is never mutated.
+ * Only top-level properties are checked (shallow). Nested objects are
+ * copied by reference and left untouched.
+ *
+ * Values like `null`, `false`, `0`, and `""` are kept.
+ *
+ * @typeParam T - The source object type
+ * @param obj - The object to strip `undefined` values from
+ * @returns A new object without any `undefined`-valued properties
+ *
+ * @example
+ * ```ts
+ * import { stripUndefined } from "strip-undefined-values"
+ *
+ * stripUndefined({ name: "Tomas", age: undefined, active: true })
+ * // => { name: "Tomas", active: true }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Safe for API payloads
+ * await fetch("/api/user", {
+ *   method: "PATCH",
+ *   body: JSON.stringify(stripUndefined({ name, email, age }))
+ * })
+ * ```
+ *
+ * @see {@link StripUndefined} for the companion utility type
+ * @since 1.0.0
+ */
+function stripUndefined(obj) {
+    const result = {};
+    for (const key in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            const value = obj[key];
+            if (value !== undefined) {
+                result[key] = value;
+            }
+        }
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Mapped type that removes keys whose value type includes `undefined`.
+ *
+ * @remarks
+ * This is intentionally conservative: if a key is typed as `T | undefined`,
+ * it is excluded from the result type entirely. At runtime the key is only
+ * removed when the value *actually is* `undefined`, so the type is stricter
+ * than the runtime behavior. This keeps downstream code safe — you will never
+ * accidentally access a possibly-undefined property on the result.
+ *
+ * @typeParam T - The source object type
+ *
+ * @example
+ * ```ts
+ * type Input = { name: string; age: number | undefined }
+ * type Output = StripUndefined<Input>
+ * //   ^? { name: string }
+ * ```
+ *
+ * @since 1.0.0
+ */
+export type StripUndefined<T extends Record<string, any>> = {
+    [K in keyof T as undefined extends T[K] ? never : K]: Exclude<T[K], undefined>;
+};
+/**
+ * Remove own properties whose value is strictly `undefined` from an object.
+ *
+ * Returns a **new** plain object — the input is never mutated.
+ * Only top-level properties are checked (shallow). Nested objects are
+ * copied by reference and left untouched.
+ *
+ * Values like `null`, `false`, `0`, and `""` are kept.
+ *
+ * @typeParam T - The source object type
+ * @param obj - The object to strip `undefined` values from
+ * @returns A new object without any `undefined`-valued properties
+ *
+ * @example
+ * ```ts
+ * import { stripUndefined } from "strip-undefined-values"
+ *
+ * stripUndefined({ name: "Tomas", age: undefined, active: true })
+ * // => { name: "Tomas", active: true }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Safe for API payloads
+ * await fetch("/api/user", {
+ *   method: "PATCH",
+ *   body: JSON.stringify(stripUndefined({ name, email, age }))
+ * })
+ * ```
+ *
+ * @see {@link StripUndefined} for the companion utility type
+ * @since 1.0.0
+ */
+export declare function stripUndefined<T extends Record<string, any>>(obj: T): StripUndefined<T>;

package/dist/index.js

@@ -0,0 +1,45 @@
+/**
+ * Remove own properties whose value is strictly `undefined` from an object.
+ *
+ * Returns a **new** plain object — the input is never mutated.
+ * Only top-level properties are checked (shallow). Nested objects are
+ * copied by reference and left untouched.
+ *
+ * Values like `null`, `false`, `0`, and `""` are kept.
+ *
+ * @typeParam T - The source object type
+ * @param obj - The object to strip `undefined` values from
+ * @returns A new object without any `undefined`-valued properties
+ *
+ * @example
+ * ```ts
+ * import { stripUndefined } from "strip-undefined-values"
+ *
+ * stripUndefined({ name: "Tomas", age: undefined, active: true })
+ * // => { name: "Tomas", active: true }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Safe for API payloads
+ * await fetch("/api/user", {
+ *   method: "PATCH",
+ *   body: JSON.stringify(stripUndefined({ name, email, age }))
+ * })
+ * ```
+ *
+ * @see {@link StripUndefined} for the companion utility type
+ * @since 1.0.0
+ */
+export function stripUndefined(obj) {
+    const result = {};
+    for (const key in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            const value = obj[key];
+            if (value !== undefined) {
+                result[key] = value;
+            }
+        }
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "strip-undefined-values",
+  "version": "1.0.0",
+  "description": "Remove undefined properties from an object. Fully typed. Zero dependencies.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "strip",
+    "undefined",
+    "remove undefined",
+    "omit undefined",
+    "clean object",
+    "filter undefined",
+    "sanitize object",
+    "api payload",
+    "typescript",
+    "utility",
+    "zero-dependency"
+  ],
+  "author": "Tomas",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tomahg/strip-undefined-values"
+  },
+  "homepage": "https://github.com/tomahg/strip-undefined-values#readme",
+  "bugs": {
+    "url": "https://github.com/tomahg/strip-undefined-values/issues"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "scripts": {
+    "build": "tsc && tsc --module commonjs --outDir dist/cjs --declaration false && node -e \"fs.renameSync('dist/cjs/index.js','dist/index.cjs')\" && node -e \"fs.rmSync('dist/cjs',{recursive:true})\"",
+    "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  }
+}