Enhance `Except` type #560

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

readme.md

@@ -902,4 +902,4 @@ You can find some examples in the [TypeScript docs](https://www.typescriptlang.o

 ## 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

source/except.d.ts

-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

source/except.d.ts

+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

source/except.d.ts

+@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

source/except.d.ts

+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. // ... */

test-d/except.ts

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

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. 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

readme.md

@@ -129,7 +129,8 @@ Click the type names for complete docs.

 - [`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

source/except.d.ts

 /**
-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

readme.md

@@ -902,4 +902,4 @@ You can find some examples in the [TypeScript docs](https://www.typescriptlang.o

 ## 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

test-d/except.ts Show resolved Hide resolved

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 tommy-mitchell and sindresorhus 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 tommy-mitchell and sindresorhus 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
7 checks passed

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enhance `Except` type #560

Enhance `Except` type #560

orimiles5 commented Feb 28, 2023 •

edited

orimiles5 commented Mar 9, 2023

sindresorhus commented Mar 10, 2023

sindresorhus Mar 10, 2023

orimiles5 Mar 11, 2023

tommy-mitchell Mar 12, 2023

sindresorhus Mar 16, 2023

orimiles5 Mar 22, 2023 •

edited

sindresorhus Mar 10, 2023

orimiles5 Mar 11, 2023

sindresorhus commented Mar 10, 2023

tommy-mitchell commented Mar 11, 2023

tommy-mitchell Mar 11, 2023

tommy-mitchell Mar 11, 2023

tommy-mitchell Mar 11, 2023 •

edited

tommy-mitchell Mar 11, 2023

tommy-mitchell commented Mar 11, 2023

tommy-mitchell left a comment

sindresorhus commented Mar 11, 2023

rayrw left a comment •

edited

sindresorhus commented Mar 14, 2023

orimiles5 commented Mar 14, 2023 •

edited

tommy-mitchell Mar 14, 2023

tommy-mitchell Mar 14, 2023

orimiles5 Mar 14, 2023

sindresorhus Mar 16, 2023

sindresorhus Mar 16, 2023

sindresorhus Mar 16, 2023

orimiles5 commented Mar 22, 2023 •

edited

orimiles5 commented Mar 23, 2023

		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`.

Enhance Except type #560

Enhance Except type #560

Conversation

orimiles5 commented Feb 28, 2023 • edited

orimiles5 commented Mar 9, 2023

sindresorhus commented Mar 10, 2023

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

orimiles5 Mar 22, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sindresorhus commented Mar 10, 2023

tommy-mitchell commented Mar 11, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tommy-mitchell Mar 11, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tommy-mitchell commented Mar 11, 2023

tommy-mitchell left a comment

Choose a reason for hiding this comment

sindresorhus commented Mar 11, 2023

rayrw left a comment • edited

Choose a reason for hiding this comment

sindresorhus commented Mar 14, 2023

orimiles5 commented Mar 14, 2023 • edited

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

orimiles5 commented Mar 22, 2023 • edited

orimiles5 commented Mar 23, 2023

Enhance `Except` type #560

Enhance `Except` type #560

orimiles5 commented Feb 28, 2023 •

edited

orimiles5 Mar 22, 2023 •

edited

tommy-mitchell Mar 11, 2023 •

edited

rayrw left a comment •

edited

orimiles5 commented Mar 14, 2023 •

edited

orimiles5 commented Mar 22, 2023 •

edited