Add `isNullish`, `isNonNullish` and `isKeyOf` Utility Functions

[shtse8]

Summary

This pull request introduces two new utility functions, isNullish and isNonNullish, to the Radash library. These functions are intended to provide a more intuitive and expressive way to handle nullish values in JavaScript, complementing the existing utility functions in Radash.

Motivation

In JavaScript, handling nullish values (null and undefined) can often be verbose and error-prone, especially when dealing with deep object structures or complex logic. The isNullish function provides a clear, concise way to check for nullish values, while isNonNullish allows for the inverse, checking for values that are not nullish. These additions aim to improve developer experience and code readability, aligning with Radash's goal of offering practical and straightforward utility functions.

Details

• isNullish(value: any): boolean: Returns true if the value is null or undefined, otherwise returns false.
• isNonNullish(value: any): boolean: Returns true if the value is not null and not undefined, otherwise returns false.

Implementation

The implementation of these functions is straightforward, relying on strict equality checks to determine if a value is nullish or not. This approach ensures maximum performance and minimal overhead, in line with the efficiency goals of Radash.

Use Cases

These functions can be particularly useful in scenarios where distinguishing between "no value" and falsy values like 0, '', or false is important. For example, in configuration objects, function parameters, or API response parsing, where a nullish value might signify the absence of a meaningful value.

Tests

Comprehensive unit tests have been added to ensure the reliability and correctness of these functions under various scenarios.

Changes Made

1. Added the isNullish function along with its unit tests.
2. Added the isNonNullish function along with its unit tests.
3. Updated the documentation to include these new functions, providing examples of their use.

How to Test

1. Pull this branch locally.
2. Run npm install to install any new dependencies (if any).
3. Run npm run test to execute the unit tests for isNullish and isNonNullish. All tests should pass.
4. Optionally, integrate these functions into a sample project to see them in action.

Potential Impact

These changes are additive and fully backward compatible. They introduce no breaking changes to existing functionality in Radash.

I believe these additions will make working with nullish values in JavaScript more intuitive and expressive for Radash users. I look forward to your feedback and any suggestions for improvement!

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
radash-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 14, 2024 9:37am

[shtse8]

Summary

This pull request introduces a new utility function, isKeyOf, to the Radash library. This function enhances type safety and developer experience by providing a more robust way to check for the existence of keys in objects, especially useful in TypeScript for narrowing down types and ensuring compile-time safety.

Motivation

Current JavaScript operations like key in object or Reflect.has(object, key) merely return a boolean indicating whether a key exists in an object, without any type narrowing. This can be limiting in TypeScript, especially when working with enums and needing to ensure a string is a valid key of a specific object type. The isKeyOf function addresses this by not only checking for the existence of a key but also narrowing down the type, thereby enhancing type safety and providing more utility in scenarios involving enums and type-checking.

Implementation

• isKeyOf<T>(obj: T, key: PropertyKey): key is keyof T: The function takes an object obj of type T and a key, and returns true if the key exists in the object, with TypeScript being able to infer the narrowed type.

For example, using isKeyOf with an enum:

enum Values {
   A = 'a', 
   B = 'b',
}
const result = isKeyOf(Values, 'A'); // result is true, with 'A' being recognized as a valid key of `Values`.

Use Cases

isKeyOf is particularly useful for validating and narrowing types when dealing with enums or when keys of an object must be validated in a type-safe manner. It's an excellent tool for TypeScript developers looking to leverage the language's type system more effectively.

Tests

Comprehensive tests have been added to verify the functionality of isKeyOf across various scenarios, ensuring its reliability and type-safety in practical use cases.

Changes Made

1. Implemented the isKeyOf function, designed to check for key existence and narrow down the type in TypeScript.
2. Added unit tests for isKeyOf covering various use cases and ensuring its effectiveness with enums and object types.
3. Updated documentation to include isKeyOf, illustrating its benefits and how to integrate it into TypeScript projects.

How to Test

1. Fetch this branch and run npm install to ensure all dependencies are up to date.
2. Execute npm run test to run the suite of unit tests for the isKeyOf function. All tests should pass, demonstrating its reliability.
3. For a hands-on test, integrate isKeyOf into a TypeScript project and use it for type checking and narrowing with enums or object keys.

Potential Impact

This addition is non-breaking and complements the existing suite of utility functions in Radash. It introduces a type-safe way to check for the presence of keys in objects, specifically designed to leverage TypeScript's capabilities.

This function aligns with Radash's goal of providing practical, straightforward utilities that enhance developer productivity and code safety. I'm excited to see how isKeyOf can benefit TypeScript users in the Radash community and look forward to any feedback or suggestions for improvement!

[aleclarson]

Hey @shtse8, I appreciate your thoroughness here in explaining your PR! Would you be interested in joining us over at the Radashi fork, where we're bringing Radash to new heights? I see you now have your own utility library called XDash, but it'd be great to combine our skills. We already have a team of about 6 people, and it'd be great to have you with us. We've made a lot of improvements already. 😄

_{P.S. You can read my post to learn more about the differences between Radashi and its predecessor.}