feat: add `hasProp`, `hasPropSatisfying`, and `isEqual` #515

airjp73 · 2024-02-15T04:56:55Z

Resolves #461

Summary

Adds three new helpers:

isEqual does a shallow, Object.is equality comparison and acts as a type guard
hasProp checks if a given object has a property and that it's defined
hasPropSatisfying checks if a given object has property, that it's defined, and that the provided predicate/type guard returns true.

Design considerations

`isEqual`

I originally thought to just do an === comparison, but I thought Object.is made more sense since it's more robust to values like NaN.

`hasProp`

My original plan was to only check for the presence of a property and allow checks like hasProp({ a: undefined }, 'a') to return true.

However, Typescript removes undefined from the possible values when removing the optionality of the prop (related github issue). The linked thread has some workarounds, but I wasn't able to get any of them to work in a general enough way for this helper.

This means that the narrowed type resulting from the type guard couldn't be accurate if we returned true for present keys with undefined as the value.

I think returning false when the value is undefined is a reasonable trade-off to make to keep the types completely accurate.

`hasPropSatisifying`

Same considerations as hasProp, but the type accuracy issue also extends to the type of the argument passed to the predicate.

Potential future improvements

Lodash and Ramda both have the ability to check for properties at a given path.

Lodash's has supports it directly
Ramda has a separate hasPath helper

As a future improvement, we could conceivably add a couple hasPropAtPath and hasPropAtPathSatisfying helpers.

Make sure that you:

Typedoc added for new methods and updated for changed
Tests added for new methods and updated for changed
New methods added to src/index.ts
New methods added to mapping.md

We use semantic PR titles to automate the release process!

https://conventionalcommits.org

PRs should be titled following using the format: < TYPE >(< scope >)?: description

Available Types:

feat: new functions, and changes to a function's type that would impact users.
fix: changes to the runtime behavior of an existing function, or refinements to it's type that shouldn't impact most users.
perf: changes to function implementations that improve a functions runtime performance.
refactor: changes to function implementations that are neither fix nor perf
test: tests-only changes (transparent to users of the function).
docs: changes to the documentation of a function or the documentation site.
build, ci, style, chore, and revert: are only relevant for the internals of the library.

For scope put the name of the function you are working on (either new or
existing).

codesandbox-ci · 2024-02-15T04:57:16Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit e4023c9:

Sandbox	Source
remeda-example-vanilla	Configuration

codecov · 2024-02-15T04:58:18Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.54%. Comparing base (96a4e82) to head (e4023c9).
Report is 50 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #515      +/-   ##
==========================================
+ Coverage   98.41%   98.54%   +0.12%     
==========================================
  Files         127      138      +11     
  Lines        7954     9271    +1317     
  Branches      724      782      +58     
==========================================
+ Hits         7828     9136    +1308     
- Misses        123      132       +9     
  Partials        3        3

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

eranhirsch

I think it's unlikely that people would consider an array as having a prop at an index. We already offer hasAtLeast to narrow arrays so that accessing a specific prop would result in a non-undefined value. Handling arrays in these functions complicates their type considerably and might introduce edge-cases and bugs that would be hard to find and fix. Let's keep hasProp and hasPropSatisfying for proper objects just as pick, omit, and prop are.
Handling unions specifically is also beyond what the utility functions should handle. We don't handle these issues with prop, pick, or omit either. If this is to handle discriminated unions, it's usually recommended to have a pivot prop that would allow typescript to align the types. I personally encountered issues in the past with trying to rely on prop existence in order to discriminate a union. Let's keep this simple for now, and we can always go back to this and expand it if we see that the simple solution isn't working for people.

mapping.md

src/_objectProps.ts

eranhirsch · 2024-02-15T14:45:11Z

src/_objectProps.ts

+
+export type AllUnionKeys<Union> = Union extends Union ? keyof Union : never;
+
+type MakeKeyRequired<Obj, Prop extends keyof Obj> = Obj & {


To prevent order from being an issue here you'd need to remove the props from Obj first.

Suggested change

type MakeKeyRequired<Obj, Prop extends keyof Obj> = Obj & {

type MakeKeyRequired<Obj, Prop extends keyof Obj> = Omit<Obj, Prop> & {

This was my original approach but ran into issues with the guard types. Typescript was thinking that this type was no longer assignable to the original.

Spent a little time trying to add this in and ran into the same issue. I'd need to do some more research to figure out exactly why, but TS gives this error in the hasProp implementation file:

A type predicate's type must be assignable to its parameter's type.

src/isEqual.ts

src/isEqual.test.ts

airjp73 · 2024-02-15T15:55:49Z

I think it's unlikely that people would consider an array as having a prop at an index. We already offer hasAtLeast to narrow arrays so that accessing a specific prop would result in a non-undefined value. Handling arrays in these functions complicates their type considerably and might introduce edge-cases and bugs that would be hard to find and fix. Let's keep hasProp and hasPropSatisfying for proper objects just as pick, omit, and prop are.

Good callout. I didn't realize that was there! I only added the type handling because it the implementation technically supports it without extra effort.

Handling unions specifically is also beyond what the utility functions should handle. We don't handle these issues with prop, pick, or omit either. If this is to handle discriminated unions, it's usually recommended to have a pivot prop that would allow typescript to align the types. I personally encountered issues in the past with trying to rely on prop existence in order to discriminate a union. Let's keep this simple for now, and we can always go back to this and expand it if we see that the simple solution isn't working for people.

I'm not sure I understand the perspective that this is beyond the scope of these helpers. I usually agree with implementing less complete feature sets and filling it out over time, but since we already have a more complete feature set it doesn't make sense to me to pare it down now.

I agree that prop, pick, and omit shouldn't have this handling. For the same reason that writing obj.someKey will error if a key might not exist, prop should too.

But since these helpers are type guards, the whole point is to take a wider type and narrow it.

eranhirsch · 2024-02-15T20:10:35Z

Those are good points about it being a type-guard requiring extra care about the types. I think the best thing would be to ensure that there are tests covering these concerns so that we can't accidentally break the code for these cases without even knowing.

None of the tests break at the moment when I remove the Narrow utility from the types in isEqual, for example.

src/hasPropSatisfying.test.ts

airjp73 · 2024-02-18T05:30:01Z

In the issue, there was some discussion about the behavior of the isEqual function. I kept moving forward with the referential equality implementation and the isEqual name for now, since it seemed like shallow and deep equals would have more specific names. Happy to change it you want though.

src/_objectProps.ts

eranhirsch

undefined is not special when it comes to prop values, it should be treated as a valid value and that should be represented both in the types and the runtime behaviour of hasProp.

See my comment inline in the test file.

src/_objectProps.ts

eranhirsch · 2024-03-10T13:57:59Z

src/_objectProps.ts

+export type AllUnionKeys<Union> = Union extends Union ? keyof Union : never;
+
+// Used to ensure the type asserted by a type guard is recognized as a subtype of the original type.
+export type EnsureExtends<T, U> = U extends T ? U : Simplify<T & U>;


Do we need to simplify here? Obviously, all types would benefit from being simplified, but I'm not sure when it's actually useful. Although this doesn't affect runtime performance, Typescript itself can become sluggish when too much recursive and iterative inference is expected from it.

eranhirsch · 2024-03-10T14:00:42Z

src/_objectProps.ts

+type MakeKeyRequired<Obj, Prop extends keyof Obj> = Omit<Obj, Prop> & {
+  // We need to both remove the optional modifier and exclude undefined.
+  // This is because the `-?` modifier will only exclude undefined from the type if the property is optional,
+  // which makes the behavior of the type inconsistent.
+  // More info about this can be found here: https://github.com/microsoft/TypeScript/issues/31025
+  // So excluding `undefined` explicitly also does this for required properties that include undefined.
+  [key in Prop]-?: Exclude<Obj[key], undefined>;
+};
+
+type UnionMembersWithProp<Obj, Prop extends keyof Obj> = Extract<
+  Obj,
+  { [key in Prop]?: unknown }
+>;
+
+export type WithRequiredProp<Obj, Prop extends AllUnionKeys<Obj>> = Simplify<
+  MakeKeyRequired<UnionMembersWithProp<Obj, Prop>, Prop>
+>;


Let's pull this out into the type-fest folder and copy:

https://github.com/sindresorhus/type-fest/blob/main/source/set-required.d.ts

eranhirsch · 2024-03-10T14:19:25Z

src/hasProp.test.ts

+  it("should return false when a prop is present on the object but is undefined", () => {
+    const obj = { b: undefined };
+    expect(hasProp(obj, "b")).toBe(false);
+  });


This is incorrect and relies on a more permissive type definition. When the typescript project uses exactOptionalPropertyTypes an undefined value is strictly different than an optional prop not being present. This is also how it works during runtime.

console.log('a' in { a: undefined }); // "true" console.log('a' in {}); // "false"

This behavior was an intentional trade-off. I can play around a bit more since it's been awhile, but I remember something at the type level couldn't reliably distinguish between the two.

Check out type-fest types for some of your utility types under _objectProps, they most likely can solve most of those issues.

hasProp should work as closely as possible to "prop" in <obj> otherwise some users would either misunderstand it's semantics and run into problems in runtime, or need to build their own function for the behaviour they need.

hasPropSatisfying(obj, prop, isDefined.strict) can provide the functionality you define for hashProp here, but the opposite is not possible.

I'll check it out and see what I can do. This is the issue I reference elsewhere in the PR that lead me to this decision. microsoft/TypeScript#31025

feat: add hasProp, hasPropSatisfying, and isEqual

19ec8d4

airjp73 force-pushed the master branch from 4988d5e to 19ec8d4 Compare February 15, 2024 05:01

eranhirsch requested changes Feb 15, 2024

View reviewed changes

airjp73 added 9 commits February 17, 2024 22:32

refactor: remove explicit array support

e4160ba

docs: remove helpers from mapping file that have no mapping

9a2bf88

test: rewrite isEqual tests

68e85ff

test: rewrite hasProp tests

292a54d

fix: update prop utility types to pass tests

eda7ee8

test: rewrite hasPropSatisfying tests

dc52970

fix: update hasPropSatisfying implementation to fix tests

b212179

refactor: clean up implementation and make object exclusive

108318d

docs: remove unnecessary wording from jsdoc

76851b1

airjp73 commented Feb 18, 2024

View reviewed changes

src/hasPropSatisfying.test.ts Outdated Show resolved Hide resolved

airjp73 and others added 3 commits February 18, 2024 08:29

fix: make the narrowed types more accurate

60bfcb7

Merge branch 'master' into master

759142b

Merge branch 'master' into master

9a50857

cjquines reviewed Feb 22, 2024

View reviewed changes

src/_objectProps.ts Outdated Show resolved Hide resolved

src/_objectProps.ts Outdated Show resolved Hide resolved

src/_objectProps.ts Outdated Show resolved Hide resolved

airjp73 and others added 7 commits February 22, 2024 16:05

fix: cleanup minor type issues and typos

00621a5

Merge branch 'master' into master

067eac9

Merge branch 'master' into master

76afdbc

prettier

77f3a13

lint autofixers

0accbff

manual fixs

491063d

no abbrevs

e4023c9

eranhirsch requested changes Mar 10, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add `hasProp`, `hasPropSatisfying`, and `isEqual` #515

feat: add `hasProp`, `hasPropSatisfying`, and `isEqual` #515

airjp73 commented Feb 15, 2024 •

edited

codesandbox-ci bot commented Feb 15, 2024 •

edited

codecov bot commented Feb 15, 2024 •

edited

eranhirsch left a comment

eranhirsch Feb 15, 2024

airjp73 Feb 15, 2024

airjp73 Feb 18, 2024

airjp73 commented Feb 15, 2024 •

edited

eranhirsch commented Feb 15, 2024

airjp73 commented Feb 18, 2024

eranhirsch left a comment

eranhirsch Mar 10, 2024

eranhirsch Mar 10, 2024

eranhirsch Mar 10, 2024

airjp73 Mar 10, 2024

eranhirsch Mar 10, 2024

airjp73 Mar 10, 2024


		export type AllUnionKeys<Union> = Union extends Union ? keyof Union : never;

		type MakeKeyRequired<Obj, Prop extends keyof Obj> = Obj & {

feat: add hasProp, hasPropSatisfying, and isEqual #515

Are you sure you want to change the base?

feat: add hasProp, hasPropSatisfying, and isEqual #515

Conversation

airjp73 commented Feb 15, 2024 • edited

Summary

Design considerations

isEqual

hasProp

hasPropSatisifying

Potential future improvements

Available Types:

codesandbox-ci bot commented Feb 15, 2024 • edited

codecov bot commented Feb 15, 2024 • edited

Codecov Report

eranhirsch left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

airjp73 commented Feb 15, 2024 • edited

eranhirsch commented Feb 15, 2024

airjp73 commented Feb 18, 2024

eranhirsch left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

feat: add `hasProp`, `hasPropSatisfying`, and `isEqual` #515

feat: add `hasProp`, `hasPropSatisfying`, and `isEqual` #515

airjp73 commented Feb 15, 2024 •

edited

`isEqual`

`hasProp`

`hasPropSatisifying`

codesandbox-ci bot commented Feb 15, 2024 •

edited

codecov bot commented Feb 15, 2024 •

edited

airjp73 commented Feb 15, 2024 •

edited