Enhance `Except` type by orimiles5 · Pull Request #560 · sindresorhus/type-fest

orimiles5 · 2023-02-28T19:15:09Z

Closes #556.

Hello There!

I would like to introduce a PR that enhances the Except type to be more strict. Although the updated type remains non-strict by default, users have the option to use the strict type by setting the strict option to true. The rationale for this change was in response to the feedback provided in issue #556, which requested a stricter version of the Except type.

Additionally, I can make further modifications to the types that use the Except type, if you would like.

To assist with the adoption of the updated type, I have included some examples in the JSDoc. If you have any questions or feedback about this change, please do not hesitate to let me know.

Thank you for your time and consideration.

orimiles5 · 2023-03-09T12:22:10Z

@sindresorhus I would appreciate your review.

sindresorhus · 2023-03-10T20:22:43Z

// @pheis @tommy-mitchell @rayrw Would any of you be willing to help review this?

sindresorhus · 2023-03-10T20:24:41Z

 ## License

-SPDX-License-Identifier: (MIT OR CC0-1.0)
+SPDX-License-Identifier: (MIT OR CC0-1.0)


Don't make unrelated changes.

I can't figure out what was the change, maybe it's a white space?

I believe the trailing new line was changed.

@orimiles5 This still needs to be fixed.

@sindresorhus Could you give me some advice on how to fix this?

sindresorhus · 2023-03-10T20:26:12Z

-import type {Except} from 'type-fest';
+import {Except} from 'type-fest';


Don't make unrelated changes.

sindresorhus · 2023-03-10T20:27:27Z

@orimiles5 Can you think of any reason to want the non-strict version? If not, we could plan to remove the option and default to strict in the next major version.

tommy-mitchell · 2023-03-11T00:51:15Z

@sindresorhus are you suggesting keeping the default as non-strict in this PR, with an option to be strict? Or that the this PR should have an option to be non-strict, and that the next version will remove that option?

tommy-mitchell · 2023-03-11T01:17:41Z

+type ExceptOptions = {
+	/**
+	@default false
+	*/
+	strict?: boolean;
+};


Could add a description to the option:

Suggested change

type ExceptOptions = {

/**

@default false

*/

strict?: boolean;

};

type ExceptOptions = {

/**

Disallow assigning non-specified properties.

Setting this to `false` is not recommended. Included for backwards-compatability.

@default false

*/

strict?: boolean;

};

tommy-mitchell · 2023-03-11T01:39:10Z

+@see {NonStrictExcept}
 */
-type Filter<KeyType, ExcludeType> = IsEqual<KeyType, ExcludeType> extends true ? never : (KeyType extends ExcludeType ? never : KeyType);
+type Filter<KeyType, ExcludeType> =
+IsEqual<KeyType, ExcludeType> extends true ? never :
+	KeyType extends ExcludeType ? never : KeyType;


Unrelated change.

Suggested change

@see {NonStrictExcept}

*/

type Filter<KeyType, ExcludeType> = IsEqual<KeyType, ExcludeType> extends true ? never : (KeyType extends ExcludeType ? never : KeyType);

type Filter<KeyType, ExcludeType> =

IsEqual<KeyType, ExcludeType> extends true ? never :

KeyType extends ExcludeType ? never : KeyType;

@see {Except}

*/

type Filter<KeyType, ExcludeType> = IsEqual<KeyType, ExcludeType> extends true ? never : (KeyType extends ExcludeType ? never : KeyType);

tommy-mitchell · 2023-03-11T01:48:05Z

+The NonStrictExcept refers to the standard Except method that permits the assignment of an object with additional properties to an object of a different type.
+@see https://github.com/sindresorhus/type-fest/issues/556
+
+@category Object
+*/
+type NonStrictExcept<ObjectType, KeysType extends keyof ObjectType> = {
+	[KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType];
+};
+
+/**
+Create a type from an object type without certain keys - in stricter way.
+When the "strict" option in ExceptOptions is true, StrictExcept will be used.
+
+The StrictExcept method resolves the problem that arises when an object with additional properties is assigned to an object of a different type.
+@see https://github.com/sindresorhus/type-fest/issues/556
+
+@category Object
+*/
+type StrictExcept<ObjectType, KeysType extends keyof ObjectType> = NonStrictExcept<ObjectType, KeysType> & Partial<Record<KeysType, never>>;
+
+/**
+The Except type is the exported type, which determines the appropriate method to use (NonStrictExcept or StrictExcept) based on the options provided as the third argument (which is set to false by default).
+
 @example
 ```
-import type {Except} from 'type-fest';
+import {Except} from 'type-fest';

 type Foo = {
 	a: number;
 	b: string;
 	c: boolean;
 };

-type FooWithoutA = Except<Foo, 'a' | 'c'>;
-//=> {b: string};
+type FooWithoutA = Except<Foo, 'a', {strict: false}>; // False by default
+
+const foo: Foo = {
+	a: 1,
+	b: 'b',
+	c: true,
+};
+
+const fooWithoutA: FooWithoutA = foo; // No error
+//=> NonStrictExcept<Foo, 'a'>;
+
+@example
 ```
+import {Except} from 'type-fest';

-@category Object
-*/
-export type Except<ObjectType, KeysType extends keyof ObjectType> = {
-	[KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType];
+type Foo = {
+	a: number;
+	b: string;
+	c: boolean;
+};
+
+type FooWithoutA = Except<Foo, 'a', {strict: true}>;
+
+const foo: Foo = {
+	a: 1,
+	b: 'b',
+	c: true,
 };
+
+const fooWithoutA: FooWithoutA = foo; // Error
+//=> StrictExcept<Foo, 'a'>;
+*/
+export type Except<ObjectType, KeysType extends keyof ObjectType, Options extends ExceptOptions = {strict: false}> =
+Options['strict'] extends false ? NonStrictExcept<ObjectType, KeysType> : StrictExcept<ObjectType, KeysType>;


No need for extra types, we can just inline:

Suggested change

The NonStrictExcept refers to the standard Except method that permits the assignment of an object with additional properties to an object of a different type.

@see https://github.com/sindresorhus/type-fest/issues/556

@category Object

*/

type NonStrictExcept<ObjectType, KeysType extends keyof ObjectType> = {

[KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType];

};

/**

Create a type from an object type without certain keys - in stricter way.

When the "strict" option in ExceptOptions is true, StrictExcept will be used.

The StrictExcept method resolves the problem that arises when an object with additional properties is assigned to an object of a different type.

@see https://github.com/sindresorhus/type-fest/issues/556

@category Object

*/

type StrictExcept<ObjectType, KeysType extends keyof ObjectType> = NonStrictExcept<ObjectType, KeysType> & Partial<Record<KeysType, never>>;

/**

The Except type is the exported type, which determines the appropriate method to use (NonStrictExcept or StrictExcept) based on the options provided as the third argument (which is set to false by default).

@example

```

import type {Except} from 'type-fest';

import {Except} from 'type-fest';

type Foo = {

a: number;

b: string;

c: boolean;

};

type FooWithoutA = Except<Foo, 'a' | 'c'>;

//=> {b: string};

type FooWithoutA = Except<Foo, 'a', {strict: false}>; // False by default

const foo: Foo = {

a: 1,

b: 'b',

c: true,

};

const fooWithoutA: FooWithoutA = foo; // No error

//=> NonStrictExcept<Foo, 'a'>;

@example

```

import {Except} from 'type-fest';

@category Object

*/

export type Except<ObjectType, KeysType extends keyof ObjectType> = {

[KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType];

type Foo = {

a: number;

b: string;

c: boolean;

};

type FooWithoutA = Except<Foo, 'a', {strict: true}>;

const foo: Foo = {

a: 1,

b: 'b',

c: true,

};

const fooWithoutA: FooWithoutA = foo; // Error

//=> StrictExcept<Foo, 'a'>;

*/

export type Except<ObjectType, KeysType extends keyof ObjectType, Options extends ExceptOptions = {strict: false}> =

Options['strict'] extends false ? NonStrictExcept<ObjectType, KeysType> : StrictExcept<ObjectType, KeysType>;

@example

```

import type {Except} from 'type-fest';

type Foo = {

a: number;

b: string;

};

type FooWithoutA = Except<Foo, 'a'>;

//=> {b: string}

const fooWithoutA: FooWithoutA = {a: 1, b: '2'};

//=> errors: 'a' does not exist in type '{ b: string; }'

type FooWithoutB = Except<Foo, 'b', {strict: true}>;

//=> {a: number} & Partial<Record<"b", never>>

const fooWithoutB: FooWithoutB = {a: 1, b: '2'};

//=> errors at 'b': Type 'string' is not assignable to type 'undefined'.

```

@category Object

*/

export type Except<ObjectType, KeysType extends keyof ObjectType, Options extends ExceptOptions = {strict: false}> = {

[KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType];

} & (Options['strict'] extends true

? Partial<Record<KeysType, never>>

: {});

Wouldn't allow me to make a suggestion there, but in the Except doc comment:

/** Create a type from an object type without certain keys. + Use option `strict: true` to disallow assigning additional properties to this type. // ... */

tommy-mitchell · 2023-03-11T02:05:20Z

Additionally, I can make further modifications to the types that use the Except type, if you would like.

Which types use Except?

tommy-mitchell

I think this PR could be simpler.

sindresorhus · 2023-03-11T07:26:04Z

are you suggesting keeping the default as non-strict in this PR, with an option to be strict? Or that the this PR should have an option to be non-strict, and that the next version will remove that option?

Making it {strict: true} by default is a breaking change, so the option is required for now. I'm asking whether there are any good use-cases for having it as false. If not, we can consider switching it to true by default in the next major release and then removing the option.

rayrw

I personally think the definition of strictness in this type could be more than one depending on which criteria do we prioritize (check if assignable v.s. accessible).

Yes, using the current Except type cannot prevent us from assigning objects with excess properties because of TypeScript's design decision. However, the default behavior actually can check if we can access to that property.

Taking the same fooWithoutA variable in the original issue #556 as an example. When we try to access fooWithoutA.a, we get this error.

Property 'a' does not exist on type 'Except<Foo, "a">'.(2339)

With the strict option in this PR turned on, we cannot assign foo to fooWithoutA anymore. However, this comes with a trade off. We have to make a accessible. fooWithoutA.a is now valid and is shown in auto-complete.

So far I cannot find a perfect solution that can prevent both, but I wouldn't say either one is wrong. For now, maybe an explicit option like makeExceptPropertiesUndefined is more accurate? What do you think?

sindresorhus · 2023-03-14T11:23:50Z

With the strict option in this PR turned on, we cannot assign foo to fooWithoutA anymore. However, this comes with a trade off. We have to make an accessible. fooWithoutA.a is now valid and is shown in auto-complete.

The trade-off should be documented.

orimiles5 · 2023-03-14T16:17:50Z

@sindresorhus I think the option should have a specific name for what exactly it's enabling. strict is confusing as the type is already a strict version of Omit.

Changed the strict option to requireExactProperties to better reflect its behavior.
If you have a better name suggestion, please advise.

The trade-off should be documented.

Added documentation for the trade-off as well.

tommy-mitchell · 2023-03-14T19:57:52Z

 /**
 Create a type from an object type without certain keys.

+Use option `requireExactProps: true` to disallow assigning additional properties to this type. Notice that any omitted properties in the resulting type will be present as `undefined`.


Suggested change

Use option `requireExactProps: true` to disallow assigning additional properties to this type. Notice that any omitted properties in the resulting type will be present as `undefined`.

Use option `requireExactProps: true` to disallow assigning additional properties to this type. Note that any omitted properties in the resulting type will be present in suggestions as `undefined`.

We could also add a note like this to the readme:

Exact - Create a type that does not allow extra properties. Use option requireExactProps: true to disallow assigning additional properties to this type. (Note that that any omitted properties in the resulting type will be present in suggestions as undefined.)

Which means line 46 could probably just be appended to line 44:

/** Create a type from an object type without certain keys. Use option `requireExactProps: true` to disallow assigning additional properties to this type. Notice that any omitted properties in the resulting type will be present as `undefined`. This type is a stricter... ... */

sindresorhus · 2023-03-16T17:45:52Z

 - [`EmptyObject`](source/empty-object.d.ts) - Represents a strictly empty plain object, the `{}` value.
 - [`IsEmptyObject`](source/empty-object.d.ts) - Returns a `boolean` for whether the type is strictly equal to an empty plain object, the `{}` value.
- [`Except`](source/except.d.ts) - Create a type from an object type without certain keys. This is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys).
+- [`Except`](source/except.d.ts) - Create a type from an object type without certain keys. Use option `requireExactProps: true` to disallow assigning additional properties to this type. (Note that that any omitted properties in the resulting type will be present in suggestions as `undefined`.)


The description here should not be changed. The option is explained in the type docs. That's enough.

sindresorhus · 2023-03-16T17:47:37Z

+
 /**
-Create a type from an object type without certain keys.
+Create a type from an object type without certain keys. Use option `requireExactProps: true` to disallow assigning additional properties to this type. Note that any omitted properties in the resulting type will be present in suggestions as `undefined`.


This text should be in the docs for ExceptOptions instead. The only text we need here is just:

We recommend setting the requireExactProps option to true.

sindresorhus · 2023-03-16T17:48:21Z

 ## License

-SPDX-License-Identifier: (MIT OR CC0-1.0)
+SPDX-License-Identifier: (MIT OR CC0-1.0)


@orimiles5 This still needs to be fixed.

orimiles5 · 2023-03-22T17:57:00Z

Made the requested changes.
Let me know if further changes are required.

orimiles5 · 2023-03-23T12:59:12Z

Thank you!

orimiles5 added 6 commits February 26, 2023 20:14

add StrictExcept type

5b3138b

prettier

fd7733a

added example for StrictExcept

29ce64d

create Except type with optional strict

03efc42

change name to

a0636bb

change to single quotes

8bcc45c

orimiles5 closed this Feb 28, 2023

make StrictExcept false by default

3c5e005

orimiles5 changed the title ~~Improve Except type~~ Enhance Except type Mar 1, 2023

orimiles5 reopened this Mar 1, 2023

orimiles5 closed this Mar 1, 2023

orimiles5 reopened this Mar 1, 2023

remove test for strict-except

0b5573b

Update except.d.ts

3ef2af0

sindresorhus reviewed Mar 10, 2023

View reviewed changes

Update except.d.ts

f14a038

sindresorhus reviewed Mar 10, 2023

View reviewed changes

tommy-mitchell reviewed Mar 11, 2023

View reviewed changes

Comment thread test-d/except.ts

tommy-mitchell suggested changes Mar 11, 2023

View reviewed changes

rayrw reviewed Mar 11, 2023

View reviewed changes

Add IsLiteral types (sindresorhus#563)

d7a1d0f

sindresorhus and others added 3 commits March 14, 2023 18:24

Update except.d.ts

5de63de

Merge branch 'main' into dev

e2a2cc0

change strict option name to be more specific and document the trade-off

9d63b07

orimiles5 requested review from sindresorhus and tommy-mitchell and removed request for sindresorhus and tommy-mitchell March 14, 2023 17:08

tommy-mitchell reviewed Mar 14, 2023

View reviewed changes

orimiles5 added 2 commits March 14, 2023 22:59

Fix documentation

730d469

Update Except type documentation

6ffbed6

orimiles5 requested review from sindresorhus and tommy-mitchell and removed request for sindresorhus and tommy-mitchell March 14, 2023 22:08

tommy-mitchell mentioned this pull request Mar 14, 2023

Make tsd ignore unused locals by default tsdjs/tsd#185

Merged

sindresorhus requested changes Mar 16, 2023

View reviewed changes

orimiles5 added 3 commits March 22, 2023 08:32

Merge branch 'main' into 'dev'

880e7e4

Modify Except type docs

87fcc50

Modify ExceptOptions docs

af2e28b

orimiles5 requested a review from sindresorhus March 22, 2023 17:58

sindresorhus added 4 commits March 23, 2023 16:47

Update readme.md

f8e36b3

Update except.d.ts

f5d2a10

Update except.d.ts

0a15a94

Merge branch 'main' into dev

fa7c464

sindresorhus merged commit c5743c9 into sindresorhus:main Mar 23, 2023

dfernandez79 mentioned this pull request Apr 11, 2023

Changes in Except from v3.7.0 generates a huge declaration output truncated by TypeScript v4.9.5 #591

Open

		import type {Except} from 'type-fest';
		import {Except} from 'type-fest';

	Use option `requireExactProps: true` to disallow assigning additional properties to this type. Notice that any omitted properties in the resulting type will be present as `undefined`.
	Use option `requireExactProps: true` to disallow assigning additional properties to this type. Note that any omitted properties in the resulting type will be present in suggestions as `undefined`.

Uh oh!

Conversation

orimiles5 commented Feb 28, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

orimiles5 commented Mar 9, 2023

Uh oh!

sindresorhus commented Mar 10, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

orimiles5 Mar 22, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sindresorhus commented Mar 10, 2023

Uh oh!

tommy-mitchell commented Mar 11, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tommy-mitchell Mar 11, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tommy-mitchell commented Mar 11, 2023

Uh oh!

tommy-mitchell left a comment

Choose a reason for hiding this comment

Uh oh!

sindresorhus commented Mar 11, 2023

Uh oh!

rayrw left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sindresorhus commented Mar 14, 2023

Uh oh!

orimiles5 commented Mar 14, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

orimiles5 commented Mar 22, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

orimiles5 commented Mar 23, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

orimiles5 commented Feb 28, 2023 •

edited

Loading

orimiles5 Mar 22, 2023 •

edited

Loading

tommy-mitchell Mar 11, 2023 •

edited

Loading

rayrw left a comment •

edited

Loading

orimiles5 commented Mar 14, 2023 •

edited

Loading

orimiles5 commented Mar 22, 2023 •

edited

Loading