@lookwe/omit-undefined 1.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @lookwe/omit-undefined
+
+A small utility package for TypeScript and JavaScript projects to create a new object with all `undefined` properties removed. It also provides a TypeScript helper type to accurately represent objects without `undefined` properties.
+
+## Installation
+
+You can install `@lookwe/omit-undefined` using npm or yarn:
+
+```bash
+npm install @lookwe/omit-undefined
+# or
+yarn add @lookwe/omit-undefined
+```
+
+## Usage
+
+```js
+import { omitUndefined, OmitUndefined } from '@lookwe/omit-undefined';
+
+const cleanedObject = omitUndefined({
+	id: undefined,
+	name: 'Example',
+	isActive: true,
+});
+
+console.log(cleanedObject);
+// {
+//   name: 'Example',
+//   description: true,
+// }
+```
+
+### `OmitUndefined<T>` Type
+
+This utility type helps you define the shape of an object where properties that could potentially be `undefined` in the original type `T` are now optional and guaranteed to not be `undefined`.
+
+```ts
+import { OmitUndefined } from '@lookwe/omit-undefined';
+
+type User = {
+	id: number | undefined;
+	username: string;
+	email?: string | undefined;
+	roles: string[] | undefined;
+};
+
+type DefinedUser = OmitUndefined<User>;
+// DefinedUser will be:
+// {
+//   id?: number;
+//   username: string;
+//   email?: string;
+//   roles?: string[];
+// }
+
+const validUser: DefinedUser = {
+	username: 'testuser',
+};
+
+const anotherValidUser: DefinedUser = {
+	id: 123,
+	username: 'anotheruser',
+	email: '[email address removed]',
+	roles: ['admin', 'editor'],
+};
+
+// The following would have a type error because 'username' is required in DefinedUser
+// const invalidUser: DefinedUser = {};
+```
+
+## Usefulness with `exactOptionalPropertyTypes`
+
+With the introduction of the `exactOptionalPropertyTypes` flag in TypeScript 4.4, a stricter distinction is made between an optional property being absent and being explicitly set to `undefined`. However, many existing utility types and even some libraries don't fully account for this nuanced behavior. They often treat optional properties (`propertyName?: Type`) as being equivalent to properties that can explicitly be `undefined` (`propertyName: Type | undefined`).
+
+This can lead to situations where, with `exactOptionalPropertyTypes` enabled, you might expect an optional property with an `undefined` value to be treated as truly absent by utility functions or type definitions, but instead, it's still considered present (albeit with an `undefined` value).
+
+`@lookwe/omit-undefined` and its `OmitUndefined` type are designed to be mindful of this distinction. The `omitUndefined` function explicitly removes properties whose value is `undefined`, ensuring that the resulting object truly reflects the absence of those properties. Similarly, the `OmitUndefined` type accurately represents an object where properties that _could_ have been `undefined` in the original type are now optional in the resulting type, but their possible values no longer include `undefined`.
+
+This makes `@lookwe/omit-undefined` a valuable tool, especially when working with TypeScript projects that leverage the benefits of `exactOptionalPropertyTypes` for more precise type checking and a clearer understanding of optional properties. It helps bridge the gap where other libraries might fall short in fully supporting this stricter interpretation of optionality.

package/omit-undefined.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Defines a type `OmitUndefinedProps` that creates a new type by making properties of `T` optional if their type
+ * extends `undefined`, and keeping other properties required.
+ */
+export type OmitUndefined<T> = {
+    [K in keyof T as undefined extends T[K] ? K : never]?: Exclude<T[K], undefined>;
+} & {
+    [K in keyof T as undefined extends T[K] ? never : K]: T[K];
+};
+/**
+ * Creates a new object containing only the properties of the input object that are not `undefined`.
+ *
+ * @param {T} obj  - The object to process.
+ * @returns {OmitUndefined<T>} A new object with properties that were not `undefined` in the original object.
+ * @template T  - An object type.
+ */
+export declare function omitUndefined<const T extends object>(obj: T): OmitUndefined<T>;

package/omit-undefined.js

@@ -0,0 +1,18 @@
+/**
+ * Creates a new object containing only the properties of the input object that are not `undefined`.
+ *
+ * @param {T} obj  - The object to process.
+ * @returns {OmitUndefined<T>} A new object with properties that were not `undefined` in the original object.
+ * @template T  - An object type.
+ */
+function omitUndefined(obj) {
+    const cleanedObj = { ...obj };
+    for (const key in cleanedObj) {
+        if (cleanedObj[key] === undefined) {
+            delete cleanedObj[key];
+        }
+    }
+    return cleanedObj;
+}
+
+export { omitUndefined };

package/package.json

@@ -0,0 +1,66 @@
+{
+	"name": "@lookwe/omit-undefined",
+	"description": "A small utility package for TypeScript and JavaScript projects to create a new object with all `undefined` properties removed, with strong support for TypeScript's `exactOptionalPropertyTypes`.",
+	"homepage": "https://github.com/Lookwe69/omit-undefined",
+	"bugs": {
+		"url": "https://github.com/Lookwe69/omit-undefined/issues"
+	},
+	"keywords": [
+		"omit",
+		"undefined",
+		"utility",
+		"typescript",
+		"javascript",
+		"exactOptionalPropertyTypes"
+	],
+	"author": "Lookwe",
+	"version": "1.1.0",
+	"type": "module",
+	"scripts": {
+		"build": "rollup --config rollup-dist.config.js",
+		"build:watch": "npm run build -- --watch",
+		"build:prepack": "rollup --config rollup-prepack.config.js",
+		"clean": "rm -rf dist && rm -rf coverage && rm -rf internal",
+		"lint": "npm run lint:eslint && npm run lint:ts",
+		"lint:eslint": "eslint 'src/**/*.ts'",
+		"lint:ts": "tsc --noEmit",
+		"format": "prettier --check --ignore-path .gitignore .",
+		"format:fix": "npm run format -- --write && npm run format -- --write --plugin=@homer0/prettier-plugin-jsdoc",
+		"test": "npm run build && node --test",
+		"prepare-pack": "npm run clean && npm run build:prepack",
+		"prepack": "npm run prepare-pack",
+		"semantic-release": "semantic-release"
+	},
+	"files": [
+		"omit-undefined.js",
+		"omit-undefined.d.ts"
+	],
+	"main": "omit-undefined.js",
+	"module": "omit-undefined.js",
+	"types": "omit-undefined.d.ts",
+	"exports": {
+		".": "./omit-undefined.js"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"devDependencies": {
+		"@homer0/prettier-plugin-jsdoc": "^10.0.0",
+		"@ianvs/prettier-plugin-sort-imports": "^4.4.1",
+		"@rollup/plugin-node-resolve": "^16.0.1",
+		"@rollup/plugin-replace": "^6.0.2",
+		"@rollup/plugin-typescript": "^12.1.2",
+		"@tsconfig/strictest": "^2.0.5",
+		"@types/node": "^22.15.2",
+		"eslint": "^9.25.1",
+		"expect-type": "^1.2.1",
+		"globals": "^16.0.0",
+		"prettier": "^3.5.3",
+		"rollup": "^4.40.0",
+		"rollup-plugin-multi-input": "^1.5.0",
+		"semantic-release": "^24.2.3",
+		"tslib": "^2.8.1",
+		"typescript": "^5.8.3",
+		"typescript-eslint": "^8.31.0"
+	}
+}