Merge pull request #1500 from zloirock/v4-types

Author: zloirock

.github/workflows/ci.yml

@@ -21,6 +21,17 @@ jobs:
       - run: pip install codespell
       - run: npx run-s lint-raw codespell
 
+  type-definitions:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 25
+          cache: npm
+      - run: npm run prepare-monorepo
+      - run: npx run-s build-types test-type-definitions-ci
+
   karma:
     runs-on: windows-2022
     steps:

.gitignore

@@ -45,15 +45,19 @@ node_modules/
 /packages/core-js-pure/proposals/
 /packages/core-js-pure/stable/
 /packages/core-js-pure/stage/
-/packages/core-js-pure/index.js
 /packages/core-js-pure/configurator.js
+/packages/core-js-pure/index.js
 /packages/core-js-pure/package.json
 /packages/core-js-pure/LICENSE
+/packages/core-js-types/package.json
+/packages/core-js-types/ts*
+/packages/core-js-types/LICENSE
 /tests/**/bundles/
 /tests/compat/*.jar
 /tests/compat/compat-data.js
 /tests/unit-global/index.js
 /tests/unit-pure/index.js
+/tests/type-definitions/tmp/
 /website/templates/
 /website/dist/
 /website/src/public/

CONTRIBUTING.md

@@ -16,7 +16,7 @@ There is always some ["help wanted" issues](https://github.com/zloirock/core-js/
 - For export the polyfill, in all common cases use [`internals/export`](./packages/core-js/modules/export.js) helper. Use something else only if this helper is not applicable - for example, if you want to polyfill accessors.
 - If the code of the pure version implementation should significantly differ from the global version (*that's not a frequent situation, in most cases [`internals/is-pure`](./packages/core-js/modules/is-pure.js) constant is enough*), you can add it to [`packages/core-js-pure/override`](./packages/core-js-pure/override) directory. The rest parts of `@core-js/pure` will be copied from `core-js` package.
 - Add the feature detection of the polyfill to [`tests/compat/tests.js`](./tests/compat/tests.js), add the compatibility data to [`packages/core-js-compat/src/data.mjs`](./packages/core-js-compat/src/data.mjs), how to do it [see below](#how-to-update-core-js-compat-data).
-- Add it to entries definitions, see [`scripts/build-entries/entries-definitions.mjs`](./scripts/build-entries/entries-definitions.mjs).
+- Add it to entries definitions, see [`scripts/build-entries-and-types/entries-definitions.mjs`](scripts/build-entries-and-types/entries-definitions.mjs).
 - Add unit tests to [`tests/unit-global`](./tests/unit-global) and [`tests/unit-pure`](./tests/unit-pure).
 - Add tests of entry points to [`tests/entries/unit.mjs`](./tests/entries/unit.mjs).
 - Make sure that you are following [our coding style](#style-and-standards) and [all tests](#testing) are passed.
@@ -65,6 +65,33 @@ engine            | how to run tests | base data inherits from    | mandatory ch
 
 If you have no access to all required browsers / versions of browsers, use [Sauce Labs](https://saucelabs.com/), [BrowserStack](https://www.browserstack.com/) or [Cloud Browser](https://ieonchrome.com/).
 
+## TypeScript type definitions
+
+- TypeScript definitions should be added to the [`packages/core-js-types/src/base`](./packages/core-js-types/src/base) directory.
+- Our type definitions are built on top of ES6. If any related type is missing in ES6, it must be added to the [`packages/core-js-types/src/base/core-js-types`](./packages/core-js-types/src/base/core-js-types) directory and imported via triple-slash directives in your type definition file.
+- Place your type definition into the folder that matches its kind ([`packages/core-js-types/src/base/proposals`](./packages/core-js-types/src/base/proposals), [`packages/core-js-types/src/base/web`](./packages/core-js-types/src/base/web)).
+- Type definitions for the pure version are either generated from the global version types or created manually in the [`packages/core-js-types/src/base/pure`](./packages/core-js-types/src/base/pure) folder. Type build rules for the pure version can be modified using the `@type-options` directive:
+  - `no-extends` – do not extend the base type when adding a prefix to the type/interface
+  - `no-prefix` – do not add a prefix to the type/interface name
+  - `no-constructor` – use it when the type has no constructor (for example, `Math`)
+  - `export-base-constructor` – export the base type’s constructor instead of the prefixed one
+  - `no-export` – do not export this type
+  - `no-redefine` – do not redefine the type’s constructor
+  - `prefix-return-type` – add a prefix to the return type
+- All type definitions must be covered by TSC tests. Add them to the [`tests/type-definitions`](./tests/type-definitions) directory.
+- To build the types, run the command:
+  ```sh
+  npm run build-types
+  ```
+- To test the types, run the command:
+  ```sh
+  npm run test-type-definitions-all
+  ```
+- To run the fast subset of the types test, run the command:
+  ```sh
+  npm run test-type-definitions-smoke
+  ```
+
 ## Style and standards
 
 The coding style should follow our [`eslint.config.js`](./tests/eslint/eslint.config.js). You can test it by calling [`npm run lint`](#testing). Different places have different syntax and standard library limitations:

docs/web/docs/features/proposals/accessible-object-prototype-hasownproperty.md

@@ -13,3 +13,6 @@ class Object {
 ```plaintext
 core-js/proposals/accessible-object-hasownproperty
 ```
+
+## [TypeScript type definitions]({docs-version}/docs/typescript-type-definitions)
+[`@core-js/types/proposals/accessible-object-hasownproperty`](https://github.com/zloirock/core-js/blob/v4-types/packages/core-js-types/src/base/proposals/accessible-object-hasownproperty.d.ts)

docs/web/docs/features/proposals/array-deduplication.md

@@ -22,6 +22,9 @@ core-js(-pure)/full/array(/prototype)/unique-by
 core-js/full/typed-array/unique-by
 ```
 
+## [TypeScript type definitions]({docs-version}/docs/typescript-type-definitions)
+[`@core-js/types/proposals/array-unique`](https://github.com/zloirock/core-js/blob/v4-types/packages/core-js-types/src/base/proposals/array-unique.d.ts)
+
 ## Examples
 ```js
 [1, 2, 3, 2, 1].uniqueBy(); // [1, 2, 3]

docs/web/docs/features/proposals/array-filtering.md

@@ -23,6 +23,9 @@ core-js(-pure)/full/array(/prototype)/filter-reject
 core-js/full/typed-array/filter-reject
 ```
 
+## [TypeScript type definitions]({docs-version}/docs/typescript-type-definitions)
+[`@core-js/types/proposals/array-filtering`](https://github.com/zloirock/core-js/blob/v4-types/packages/core-js-types/src/base/proposals/array-filtering.d.ts)
+
 ## Examples
 ```js
 [1, 2, 3, 4, 5].filterReject(it => it % 2); // => [2, 4]

docs/web/docs/features/proposals/array-find-from-last.md

@@ -19,3 +19,6 @@ class %TypedArray% {
 ```plaintext
 core-js/proposals/array-find-from-last
 ```
+
+## [TypeScript type definitions]({docs-version}/docs/typescript-type-definitions)
+[`@core-js/types/proposals/array-find-from-last`](https://github.com/zloirock/core-js/blob/v4-types/packages/core-js-types/src/base/proposals/array-find-from-last.d.ts)

docs/web/docs/features/proposals/array-fromasync.md

@@ -13,3 +13,6 @@ class Array {
 ```plaintext
 core-js/proposals/array-from-async
 ```
+
+## [TypeScript type definitions]({docs-version}/docs/typescript-type-definitions)
+[`@core-js/types/proposals/array-from-async`](https://github.com/zloirock/core-js/blob/v4-types/packages/core-js-types/src/base/proposals/array-from-async.d.ts)

docs/web/docs/features/proposals/array-grouping.md

@@ -17,3 +17,6 @@ class Map {
 ```plaintext
 core-js/proposals/array-grouping-v2
 ```
+
+## [TypeScript type definitions]({docs-version}/docs/typescript-type-definitions)
+[`@core-js/types/proposals/array-grouping`](https://github.com/zloirock/core-js/blob/v4-types/packages/core-js-types/src/base/proposals/array-grouping.d.ts)

docs/web/docs/features/proposals/array-istemplateobject.md

@@ -18,6 +18,9 @@ core-js/proposals/array-is-template-object
 core-js(-pure)/full/array/is-template-object
 ```
 
+## [TypeScript type definitions]({docs-version}/docs/typescript-type-definitions)
+[`@core-js/types/proposals/array-is-template-object`](https://github.com/zloirock/core-js/blob/v4-types/packages/core-js-types/src/base/proposals/array-is-template-object.d.ts)
+
 ## Example
 ```js
 console.log(Array.isTemplateObject((it => it)`qwe${ 123 }asd`)); // => true