Merge pull request #1235 from susnux/typescript

CHANGELOG.md

@@ -26,6 +26,7 @@
     - `Symbol.isWellKnown` -> `Symbol.isWellKnownSymbol` method
 - Fixed some cases of increasing buffer size in `ArrayBuffer.prototype.{ transfer, transferToFixedLength }` polyfills
 - Fixed awaiting async `AsyncDisposableStack.prototype.adopt` callback, [#1258](https://github.com/zloirock/core-js/issues/1258)
+- Added TypeScript definitions to `core-js-compat`
 - Compat data improvements:
   - [`Set.prototype.difference`](https://github.com/tc39/proposal-set-methods) that was missed in Bun because of [a bug](https://github.com/oven-sh/bun/issues/2309) added in 0.6.0
   - `Array.prototype.{ group, groupToMap }` marked as no longer supported in WebKit runtimes because of the mentioned above web compat issue. For example, it's disabled from Bun 0.6.2

packages/core-js-builder/index.d.ts

@@ -1,40 +1,4 @@
-type StringOrRegExp = string | RegExp;
-
-type Modules = StringOrRegExp | readonly StringOrRegExp[];
-
-type Target =
-  | 'android'
-  | 'bun'
-  | 'chrome'
-  | 'chrome-android'
-  | 'deno'
-  | 'edge'
-  | 'electron'
-  | 'firefox'
-  | 'firefox-android'
-  | 'hermes'
-  | 'ie'
-  | 'ios'
-  | 'node'
-  | 'opera'
-  | 'opera-android'
-  | 'phantom'
-  | 'quest'
-  | 'react-native'
-  | 'rhino'
-  | 'safari'
-  | 'samsung';
-
-type BrowserslistQuery = string | ReadonlyArray<string>;
-
-type Environments = {
-  [target in Target]?: string | number;
-};
-
-type Targets = Environments & {
-  browsers?: Environments | BrowserslistQuery,
-  esmodules?: boolean,
-};
+import type compat from "core-js-compat";
 
 type Format = 'bundle' | 'esm' | 'cjs';
 
@@ -50,13 +14,9 @@ type Summary = {
   console?: SummaryEntry,
 };
 
-type Options = {
-  /** entry / module / namespace / an array of them, by default - all `core-js` modules */
-  modules?: Modules,
-  /** a blacklist, entry / module / namespace / an array of them, by default - empty list */
-  exclude?: Modules,
-  /** optional browserslist or core-js-compat format query */
-  targets?: Targets | BrowserslistQuery,
+type CompatOptions = Exclude<Parameters<typeof compat.compat>[0], undefined>;
+
+type Options = Pick<CompatOptions, "exclude" | "modules" | "targets"> & {
   /** output format, 'bundle' by default, can be 'cjs' or 'esm', and in this case
    *  the result will not be bundled and will contain imports of required modules */
   format?: Format,

packages/core-js-compat/compat.d.ts

@@ -0,0 +1,48 @@
+import type { ModuleName, Target, TargetVersion } from "./shared";
+
+type StringOrRegExp = string | RegExp;
+
+type Modules = StringOrRegExp | readonly StringOrRegExp[];
+
+type BrowserslistQuery = string | ReadonlyArray<string>;
+
+type Environments = {
+  [target in Target]?: string | number;
+};
+
+type Targets = Environments & {
+  browsers?: Environments | BrowserslistQuery,
+  esmodules?: boolean,
+};
+
+type CompatOptions = {
+  /** entry / module / namespace / an array of them, by default - all `core-js` modules */
+  modules?: Modules,
+  /** a blacklist, entry / module / namespace / an array of them, by default - empty list */
+  exclude?: Modules,
+  /** optional browserslist or core-js-compat format query */
+  targets?: Targets | BrowserslistQuery,
+  /** used `core-js` version, by default the latest */
+  version?: string,
+  /** inverse of the result, shows modules that are NOT required for the target environment */
+  inverse?: boolean,
+  /**
+   * @deprecated use `modules` instead
+   */
+  filter?: Modules
+};
+
+type CompatOutput = {
+  /** array of required modules */
+  list: ModuleName[],
+  /** object with targets for each module */
+  targets: {
+    [module: ModuleName]: {
+      [target in Target]?: TargetVersion
+    }
+  }
+}
+
+declare function compat(options?: CompatOptions): CompatOutput;
+
+export = compat;

packages/core-js-compat/get-modules-list-for-target-version.d.ts

@@ -0,0 +1,5 @@
+import type { ModuleName, TargetVersion } from "./shared";
+
+declare function getModulesListForTargetVersion(version: TargetVersion): readonly ModuleName[];
+
+export = getModulesListForTargetVersion;

packages/core-js-compat/index.d.ts

@@ -0,0 +1,27 @@
+import type compat from './compat'
+import type getModulesListForTargetVersion from './get-modules-list-for-target-version';
+import type { ModuleName, Target, TargetVersion } from './shared'
+
+type CompatData = {
+  [module: ModuleName]: {
+    [target in Target]?: TargetVersion
+  }
+};
+
+declare const ExportedCompatObject: typeof compat & {
+  compat: typeof compat,
+
+  /** The subset of modules which available in the passed `core-js` version */
+  getModulesListForTargetVersion: typeof getModulesListForTargetVersion,
+
+  /** Full list compatibility data */
+  data: CompatData,
+
+  /** map of modules by `core-js` entry points */
+  entries: {[entry_point: string]: readonly ModuleName[]},
+
+  /** Full list of modules */
+  modules: readonly ModuleName[]
+}
+
+export = ExportedCompatObject

packages/core-js-compat/package.json

@@ -19,6 +19,7 @@
   },
   "sideEffects": false,
   "main": "index.js",
+  "types": "index.d.ts",
   "dependencies": {
     "browserslist": "^4.21.5"
   }

packages/core-js-compat/shared.d.ts

@@ -0,0 +1,32 @@
+export type ModuleName = string;
+
+export type Target =
+  | 'android'
+  | 'bun'
+  | 'chrome'
+  | 'chrome-android'
+  | 'deno'
+  | 'edge'
+  | 'electron'
+  | 'firefox'
+  | 'firefox-android'
+  | 'hermes'
+  | 'ie'
+  | 'ios'
+  | 'node'
+  | 'opera'
+  | 'opera-android'
+  | 'phantom'
+  | 'quest'
+  | 'react-native'
+  | 'rhino'
+  | 'safari'
+  | 'samsung'
+  /** `quest` alias */
+  | 'oculus'
+  /** `react-native` alias */
+  | 'react'
+  /** @deprecated use `opera-android` instead */
+  | 'opera_mobile';
+
+export type TargetVersion = string;

tests/type-definitions/compat.ts

@@ -0,0 +1,77 @@
+import compat from 'core-js-compat';
+import compat2 from 'core-js-compat/compat';
+import getModulesListForTargetVersion from 'core-js-compat/get-modules-list-for-target-version';
+
+getModulesListForTargetVersion('3.0');
+compat.getModulesListForTargetVersion('3.0');
+
+compat.data['es.array.push'].android
+compat.data['es.array.push'].firefox
+
+if (typeof compat.modules[0] !== 'string') {
+  console.error('Invalid');
+}
+
+if (!compat.entries['core-js'].includes('es.array.from')) {
+  console.error('Invalid')
+}
+
+compat();
+compat({});
+compat({ modules: 'core-js/actual' });
+compat({ modules: 'es.array.push' });
+compat({ modules: /^es\.array\./ });
+compat({ modules: ['core-js/actual', /^es\.array\./] });
+compat({ exclude: 'core-js/actual' });
+compat({ exclude: 'es.array.push' });
+compat({ exclude: /^es\.array\./ });
+compat({ exclude: ['core-js/actual', /^es\.array\./] });
+compat({ modules: 'core-js/actual', exclude: /^es\.array\./ });
+compat({ targets: '> 1%' });
+compat({ targets: ['defaults', 'last 5 versions'] });
+compat({ targets: { esmodules: true, node: 'current', browsers: ['> 1%'] } });
+compat({ targets: { chrome: '26', firefox: 4 } });
+compat({ targets: { browsers: { chrome: '26', firefox: 4 } } });
+compat({ targets: { chrome: '26', firefox: 4, esmodules: true, node: 'current', browsers: ['> 1%'] } });
+compat({ version: '3.0' });
+compat({ inverse: true });
+
+compat.compat();
+compat.compat({});
+compat.compat({ modules: 'core-js/actual' });
+compat.compat({ modules: 'es.array.push' });
+compat.compat({ modules: /^es\.array\./ });
+compat.compat({ modules: ['core-js/actual', /^es\.array\./] });
+compat.compat({ exclude: 'core-js/actual' });
+compat.compat({ exclude: 'es.array.push' });
+compat.compat({ exclude: /^es\.array\./ });
+compat.compat({ exclude: ['core-js/actual', /^es\.array\./] });
+compat.compat({ modules: 'core-js/actual', exclude: /^es\.array\./ });
+compat.compat({ targets: '> 1%' });
+compat.compat({ targets: ['defaults', 'last 5 versions'] });
+compat.compat({ targets: { esmodules: true, node: 'current', browsers: ['> 1%'] } });
+compat.compat({ targets: { chrome: '26', firefox: 4 } });
+compat.compat({ targets: { browsers: { chrome: '26', firefox: 4 } } });
+compat.compat({ targets: { chrome: '26', firefox: 4, esmodules: true, node: 'current', browsers: ['> 1%'] } });
+compat.compat({ version: '3.0' });
+compat.compat({ inverse: true });
+
+compat2();
+compat2({});
+compat2({ modules: 'core-js/actual' });
+compat2({ modules: 'es.array.push' });
+compat2({ modules: /^es\.array\./ });
+compat2({ modules: ['core-js/actual', /^es\.array\./] });
+compat2({ exclude: 'core-js/actual' });
+compat2({ exclude: 'es.array.push' });
+compat2({ exclude: /^es\.array\./ });
+compat2({ exclude: ['core-js/actual', /^es\.array\./] });
+compat2({ modules: 'core-js/actual', exclude: /^es\.array\./ });
+compat2({ targets: '> 1%' });
+compat2({ targets: ['defaults', 'last 5 versions'] });
+compat2({ targets: { esmodules: true, node: 'current', browsers: ['> 1%'] } });
+compat2({ targets: { chrome: '26', firefox: 4 } });
+compat2({ targets: { browsers: { chrome: '26', firefox: 4 } } });
+compat2({ targets: { chrome: '26', firefox: 4, esmodules: true, node: 'current', browsers: ['> 1%'] } });
+compat2({ version: '3.0' });
+compat2({ inverse: true });