type-fest 2.11.2 → 2.12.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "2.11.2",
+	"version": "2.12.2",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",

package/readme.md

@@ -185,7 +185,7 @@ Click the type names for complete docs.
 
 ### Miscellaneous
 
-- [`PackageJson`](source/package-json.d.ts) - Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file).
+- [`PackageJson`](source/package-json.d.ts) - Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). It also includes support for [TypeScript Declaration Files](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) and [Yarn Workspaces](https://classic.yarnpkg.com/lang/en/docs/workspaces/).
 - [`TsConfigJson`](source/tsconfig-json.d.ts) - Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) (TypeScript 4.4).
 
 ## Declined types
@@ -199,6 +199,7 @@ Click the type names for complete docs.
 - [`Nullish`](https://github.com/sindresorhus/type-fest/pull/318) - The type only saves a couple of characters, not everyone knows what "nullish" means, and I'm also trying to [get away from `null`](https://github.com/sindresorhus/meta/discussions/7).
 - [`TitleCase`](https://github.com/sindresorhus/type-fest/pull/303) - It's not solving a common need and is a better fit for a separate package.
 - [`ExtendOr` and `ExtendAnd`](https://github.com/sindresorhus/type-fest/pull/247) - The benefits don't outweigh having to learn what they mean.
+- [`PackageJsonExtras`](https://github.com/sindresorhus/type-fest/issues/371) - There are too many possible configurations that can be put into `package.json`. If you would like to extend `PackageJson` to support an additional configuration in your project, please see the *Extending existing types* section below.
 
 ## Alternative type names
 
@@ -209,9 +210,28 @@ Click the type names for complete docs.
 
 ## Tips
 
+### Extending existing types
+
+- [`PackageJson`](source/package-json.d.ts) - There are a lot of tools that place extra configurations inside the `package.json` file. You can extend `PackageJson` to support these additional configurations.
+	<details>
+	<summary>
+			Example
+	</summary>
+
+	[Playground](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBDAnmApnA3gBQIYGMDW2A5igFIDOEAdnNuXAEJ0o4HFmVUC+cAZlBBBwA5ElQBaXinIxhAbgCwAKFCRYCZGnQAZYFRgooPfoJHSANntmKlysWlaESFanAC8jZo-YuaAMgwLKwBhal5gIgB+AC44XX1DADpQqnCiLhsgA)
+
+	```ts
+	import type {PackageJson as BasePackageJson} from 'type-fest';
+	import type {Linter} from 'eslint';
+
+	type PackageJson = BasePackageJson & {eslintConfig?: Linter.Config};
+	```
+	</details>
+
 ### Related
 
 - [typed-query-selector](https://github.com/g-plane/typed-query-selector) - Enhances `document.querySelector` and `document.querySelectorAll` with a template literal type that matches element types returned from an HTML element query selector.
+- [`Linter.Config`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/eslint/index.d.ts) - Definitions for the [ESLint configuration schema](https://eslint.org/docs/user-guide/configuring/language-options).
 
 ### Built-in types
 

package/source/get.d.ts

@@ -97,10 +97,15 @@ type WithStringsKeys = keyof WithStrings;
 //=> 'foo' | '0'
 ```
 */
-type WithStringKeys<BaseType extends Record<string | number, any>> = {
-	[Key in StringKeyOf<BaseType>]: BaseType[Key]
+type WithStringKeys<BaseType> = {
+	[Key in StringKeyOf<BaseType>]: UncheckedIndex<BaseType, Key>
 };
 
+/**
+Perform a `T[U]` operation if `T` supports indexing.
+*/
+type UncheckedIndex<T, U extends string | number> = [T] extends [Record<string | number, any>] ? T[U] : never;
+
 /**
 Get a property of an object or array. Works when indexing arrays using number-literal-strings, for example, `PropertyOf<number[], '0'> = number`, and when indexing objects with number keys.
 

package/source/jsonify.d.ts

@@ -3,6 +3,13 @@ import {JsonPrimitive, JsonValue} from './basic';
 // Note: The return value has to be `any` and not `unknown` so it can match `void`.
 type NotJsonable = ((...args: any[]) => any) | undefined;
 
+// Note: Handles special case where Arrays with `undefined` are transformed to `'null'` by `JSON.stringify()`
+// Only use with array members
+type JsonifyArrayMember<T> =
+	T extends undefined ?
+		null | Exclude<T, undefined> :
+		Jsonify<T>;
+
 /**
 Transform a type to one that is assignable to the `JsonValue` type.
 
@@ -64,7 +71,7 @@ type Jsonify<T> =
 		? T extends JsonPrimitive
 			? T // Primitive is acceptable
 			: T extends Array<infer U>
-				? Array<Jsonify<U>> // It's an array: recursive call for its children
+				? Array<JsonifyArrayMember<U>> // It's an array: recursive call for its children
 				: T extends object
 					? T extends {toJSON(): infer J}
 						? (() => J) extends (() => JsonValue) // Is J assignable to JsonValue?

package/source/package-json.d.ts

@@ -227,11 +227,19 @@ declare namespace PackageJson {
 	Entry points of a module, optionally with conditions and subpath exports.
 	*/
 	export type Exports =
+	| null
 	| string
 	| string[]
 	| {[key in ExportCondition]: Exports}
 	| {[key: string]: Exports}; // eslint-disable-line @typescript-eslint/consistent-indexed-object-style
 
+	/**
+	Import map entries of a module, optionally with conditions.
+	*/
+	export type Imports = { // eslint-disable-line @typescript-eslint/consistent-indexed-object-style
+		[key: string]: string | {[key in ExportCondition]: Exports};
+	};
+
 	export interface NonStandardEntryPoints {
 		/**
 		An ECMAScript module ID that is the primary entry point to the program.
@@ -416,12 +424,19 @@ declare namespace PackageJson {
 		main?: string;
 
 		/**
-		Standard entry points of the package, with enhanced support for ECMAScript Modules.
+		Subpath exports to define entry points of the package.
 
-		[Read more.](https://nodejs.org/api/esm.html#esm_package_entry_points)
+		[Read more.](https://nodejs.org/api/packages.html#subpath-exports)
 		*/
 		exports?: Exports;
 
+		/**
+		Subpath imports to define internal package import maps that only apply to import specifiers from within the package itself.
+
+		[Read more.](https://nodejs.org/api/packages.html#subpath-imports)
+		*/
+		imports?: Imports;
+
 		/**
 		The executable files that should be installed into the `PATH`.
 		*/

package/source/tsconfig-json.d.ts

@@ -598,6 +598,7 @@ declare namespace TsConfigJson {
 		Watch input files.
 
 		@default false
+		@deprecated Use watchOptions instead.
 		*/
 		watch?: boolean;
 
@@ -605,6 +606,8 @@ declare namespace TsConfigJson {
 		Specify the polling strategy to use when the system runs out of or doesn't support native file watchers.
 
 		Requires TypeScript version 3.8 or later.
+
+		@deprecated Use watchOptions.fallbackPolling instead.
 		*/
 		fallbackPolling?: CompilerOptions.FallbackPolling;
 
@@ -614,6 +617,7 @@ declare namespace TsConfigJson {
 		Requires TypeScript version 3.8 or later.
 
 		@default 'useFsEvents'
+		@deprecated Use watchOptions.watchDirectory instead.
 		*/
 		watchDirectory?: CompilerOptions.WatchDirectory;
 
@@ -623,6 +627,7 @@ declare namespace TsConfigJson {
 		Requires TypeScript version 3.8 or later.
 
 		@default 'useFsEvents'
+		@deprecated Use watchOptions.watchFile instead.
 		*/
 		watchFile?: CompilerOptions.WatchFile;
 
@@ -990,6 +995,71 @@ declare namespace TsConfigJson {
 		explainFiles?: boolean;
 	}
 
+	namespace WatchOptions {
+		export type WatchFileKind =
+			| 'FixedPollingInterval'
+			| 'PriorityPollingInterval'
+			| 'DynamicPriorityPolling'
+			| 'FixedChunkSizePolling'
+			| 'UseFsEvents'
+			| 'UseFsEventsOnParentDirectory';
+
+		export type WatchDirectoryKind =
+			| 'UseFsEvents'
+			| 'FixedPollingInterval'
+			| 'DynamicPriorityPolling'
+			| 'FixedChunkSizePolling';
+
+		export type PollingWatchKind =
+			| 'FixedInterval'
+			| 'PriorityInterval'
+			| 'DynamicPriority'
+			| 'FixedChunkSize';
+	}
+
+	export interface WatchOptions {
+
+		/**
+		Specify the strategy for watching individual files.
+
+		Requires TypeScript version 3.8 or later.
+
+		@default 'UseFsEvents'
+		*/
+		watchFile?: WatchOptions.WatchFileKind | Lowercase<WatchOptions.WatchFileKind>;
+
+		/**
+		Specify the strategy for watching directories under systems that lack recursive file-watching functionality.
+
+		Requires TypeScript version 3.8 or later.
+
+		@default 'UseFsEvents'
+		*/
+		watchDirectory?: WatchOptions.WatchDirectoryKind | Lowercase<WatchOptions.WatchDirectoryKind>;
+
+		/**
+		Specify the polling strategy to use when the system runs out of or doesn't support native file watchers.
+
+		Requires TypeScript version 3.8 or later.
+		*/
+		fallbackPolling?: WatchOptions.PollingWatchKind | Lowercase<WatchOptions.PollingWatchKind>;
+
+		/**
+		Enable synchronous updates on directory watchers for platforms that don't support recursive watching natively.
+		*/
+		synchronousWatchDirectory?: boolean;
+
+		/**
+		Specifies a list of directories to exclude from watch
+		*/
+		excludeDirectories?: string[];
+
+		/**
+		Specifies a list of files to exclude from watch
+		*/
+		excludeFiles?: string[];
+	}
+
 	/**
 	Auto type (.d.ts) acquisition options for this project.
 
@@ -1048,6 +1118,11 @@ export interface TsConfigJson {
 	*/
 	compilerOptions?: TsConfigJson.CompilerOptions;
 
+	/**
+	Instructs the TypeScript compiler how to watch files.
+	*/
+	watchOptions?: TsConfigJson.WatchOptions;
+
 	/**
 	Auto type (.d.ts) acquisition options for this project.