Merge pull request #1163 from zloirock/ts-definitions

package.json

@@ -30,8 +30,8 @@
     "compat-hermes": "zx tests/compat/hermes-adapter.mjs",
     "compat-node": "node tests/compat/node-runner",
     "compat-rhino": "zx tests/compat/rhino-adapter.mjs --version=1.7.14",
-    "lint": "run-s init test-eslint bundle test-publint",
-    "test": "run-s init test-eslint bundle test-publint test-unit test-promises test-observables test-entries test-compat-data test-compat-tools test-builder check",
+    "lint": "run-s init test-eslint test-type-definitions bundle test-publint",
+    "test": "run-s lint test-unit test-promises test-observables test-entries test-compat-data test-compat-tools test-builder check",
     "test-eslint": "npm run zxi tests/eslint/runner.mjs",
     "test-publint": "npm run zxi tests/publint/runner.mjs",
     "test-unit": "run-s test-unit-karma test-unit-node",
@@ -44,6 +44,7 @@
     "test-builder": "zx tests/builder/builder.mjs",
     "test-compat-data": "zx tests/compat-data/index.mjs",
     "test-compat-tools": "zx tests/compat-tools/index.mjs",
+    "test-type-definitions": "npm run zxi cd tests/type-definitions/runner.mjs",
     "test262": "npm run zxi cd tests/test262/runner.mjs",
     "refresh": "node scripts/clean-dependencies.mjs && npm install-test",
     "downloads": "zx scripts/downloads-by-versions.mjs",

packages/core-js-builder/README.md

@@ -32,3 +32,5 @@ const bundle = await builder({
   filename: PATH_TO_MY_COREJS_BUNDLE,
 });
 ```
+
+ℹ️ When using TypeScript, make sure to set `esModuleInterop` to `true`.

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

@@ -0,0 +1,71 @@
+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,
+};
+
+type Format = 'bundle' | 'esm' | 'cjs';
+
+type SummaryEntry = boolean | {
+  size?: boolean,
+  modules?: boolean,
+};
+
+type Summary = {
+  /** in the console, you could specify required parts or set `true` for enable all of them */
+  comment?: SummaryEntry,
+  /** in the comment, you could specify required parts or set `true` for enable all of them */
+  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,
+  /** 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,
+  /** optional target filename, if it's missed a file will not be created */
+  filename?: string,
+  /** shows summary for the bundle, disabled by default */
+  summary?: Summary,
+};
+
+declare function builder(options?: Options): Promise<string>;
+
+export = builder;

packages/core-js-builder/package.json

@@ -19,6 +19,7 @@
   },
   "sideEffects": false,
   "main": "index.js",
+  "types": "index.d.ts",
   "dependencies": {
     "core-js": "3.27.2",
     "core-js-compat": "3.27.2",

tests/type-definitions/builder.ts

@@ -0,0 +1,68 @@
+import builder from 'core-js-builder';
+
+const a: Promise<string> = builder({ targets: { node: 17 } });
+const b: string = await builder({ targets: { node: 17 } });
+
+await builder();
+await builder({});
+await builder({ modules: 'core-js/actual' });
+await builder({ modules: 'es.array.push' });
+await builder({ modules: /^es\.array\./ });
+await builder({ modules: ['core-js/actual', /^es\.array\./] });
+await builder({ exclude: 'core-js/actual' });
+await builder({ exclude: 'es.array.push' });
+await builder({ exclude: /^es\.array\./ });
+await builder({ exclude: ['core-js/actual', /^es\.array\./] });
+await builder({ modules: 'core-js/actual', exclude: /^es\.array\./ });
+await builder({ targets: '> 1%' });
+await builder({ targets: ['defaults', 'last 5 versions'] });
+await builder({ targets: { esmodules: true, node: 'current', browsers: ['> 1%'] } });
+await builder({ targets: { chrome: '26', firefox: 4 } });
+await builder({ targets: { browsers: { chrome: '26', firefox: 4 } } });
+await builder({ targets: { chrome: '26', firefox: 4, esmodules: true, node: 'current', browsers: ['> 1%'] } });
+await builder({ format: 'bundle' });
+await builder({ format: 'esm' });
+await builder({ format: 'cjs' });
+await builder({ filename: '/foo/bar/baz.js' });
+await builder({ summary: { comment: true } });
+await builder({ summary: { comment: { size: true } } });
+await builder({ summary: { comment: { size: false, modules: true } } });
+await builder({ summary: { console: true } });
+await builder({ summary: { console: { size: true } } });
+await builder({ summary: { console: { size: false, modules: true } } });
+await builder({ summary: { console: { size: false, modules: true }, comment: { size: false, modules: true } } });
+await builder({
+  modules: 'core-js/actual',
+  exclude: /^es\.array\./,
+  targets: {
+    android: 1,
+    bun: '1',
+    chrome: 1,
+    'chrome-android': '1',
+    deno: 1,
+    edge: '1',
+    electron: 1,
+    firefox: '1',
+    'firefox-android': 1,
+    hermes: '1',
+    ie: 1,
+    ios: '1',
+    opera: 1,
+    'opera-android': '1',
+    phantom: 1,
+    quest: '1',
+    'react-native': 1,
+    rhino: '1',
+    safari: 1,
+    samsung: '1',
+    node: 'current',
+    esmodules: true,
+    browsers: ['> 1%'],
+  },
+  format: 'bundle',
+  filename: '/foo/bar/baz.js',
+  summary: {
+    console: { size: false, modules: true },
+    comment: { size: false, modules: true },
+  },
+});

tests/type-definitions/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "tests/type-definitions",
+  "devDependencies": {
+    "typescript": "^4.9.4"
+  }
+}

tests/type-definitions/runner.mjs

@@ -0,0 +1 @@
+await $`tsc`;

tests/type-definitions/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "esnext",
+    "module": "esnext",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "noEmit": true
+  },
+  "include": [
+    "*.ts"
+  ]
+}