Enhance Except type

package.json

@@ -49,5 +49,10 @@
  "@typescript-eslint/no-redeclare": "off",
  "@typescript-eslint/no-confusing-void-expression": "off"
  }
+ },
+ "tsd": {
+ "compilerOptions": {
+ "noUnusedLocals": false
+ }
  }
 }

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`.)
+This is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys).
 - [`Writable`](source/writable.d.ts) - Create a type that strips `readonly` from all or some of an object's keys. The inverse of `Readonly<T>`.
 - [`WritableDeep`](source/writable-deep.d.ts) - Create a deeply mutable version of an `object`/`ReadonlyMap`/`ReadonlySet`/`ReadonlyArray` type. The inverse of `ReadonlyDeep<T>`. Use `Writable<T>` if you only need one level deep.
 - [`Merge`](source/merge.d.ts) - Merge two types into a new type. Keys of the second type overrides keys of the first type.
@@ -910,4 +911,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)

source/except.d.ts

@@ -29,8 +29,19 @@ type Filtered = Filter<'bar', 'foo'>;
 */
 type Filter<KeyType, ExcludeType> = IsEqual<KeyType, ExcludeType> extends true ? never : (KeyType extends ExcludeType ? never : KeyType);
 
+type ExceptOptions = {
+ /**
+ Disallow assigning non-specified properties.
+
+ Setting this to `false` is not recommended. Included for backwards-compatability.
+
+ @default false
+ */
+ requireExactProps?: boolean;
+};
+
 /**
-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 type is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type). The `Omit` type does not restrict the omitted keys to be keys present on the given type, while `Except` does. The benefits of a stricter type are avoiding typos and allowing the compiler to pick up on rename refactors automatically.
 
@@ -43,15 +54,25 @@ import type {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'>;
+//=> {b: string}
+
+const fooWithoutA: FooWithoutA = {a: 1, b: '2'};
+//=> errors: 'a' does not exist in type '{ b: string; }'
+
+type FooWithoutB = Except<Foo, 'b', {requireExactProps: 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> = {
+export type Except<ObjectType, KeysType extends keyof ObjectType, Options extends ExceptOptions = {requireExactProps: false}> = {
  [KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType];
-};
+} & (Options['requireExactProps'] extends true
+ ? Partial<Record<KeysType, never>>
+ : {});

test-d/except.ts

@@ -1,8 +1,22 @@
-import {expectType} from 'tsd';
+import {expectType, expectError} from 'tsd';
 import type {Except} from '../index';
 
 declare const except: Except<{a: number; b: string}, 'b'>;
 expectType<{a: number}>(except);
+expectError(except.b);
+
+const nonStrict = {
+ a: 1,
+ b: '2',
+};
+
+const nonStrictAssignment: typeof except = nonStrict; // No error
+
+declare const strictExcept: Except<{a: number; b: string}, 'b', {requireExactProps: true}>;
+
+expectError(() => {
+ const strictAssignment: typeof strictExcept = nonStrict;
+});
 
 // Generic properties
 type Example = {
@@ -11,7 +25,7 @@ type Example = {
  bar: string;
 };
 
-const test: Except<Example, 'bar'> = {foo: 123, bar: 'asdf'};
+const test: Except<Example, 'bar', {requireExactProps: false}> = {foo: 123, bar: 'asdf'};
 expectType<number>(test.foo);
 // eslint-disable-next-line @typescript-eslint/dot-notation
 expectType<unknown>(test['bar']);