feat: add new globalShims option (#145)

.changeset/funny-meals-speak.md

@@ -0,0 +1,55 @@
+---
+"synckit": patch
+---
+
+feat: add new `globalShims` option, what means you can env `SYNCKIT_GLOBAL_SHIMS=1` to enable auto polyfilling for some modules, for example: `fetch` from `node-fetch`, `performance` from `node:perf_hooks`.
+
+You can also pass a custom `globalShims` option as `GlobalShim` `Array` to custom your own shims:
+
+````ts
+export interface GlobalShim {
+  moduleName: string
+  /**
+   * `undefined` means side effect only
+   */
+  globalName?: string
+  /**
+   * 1. `undefined` or empty string means `default`, for example:
+   * ```js
+   * import globalName from 'module-name'
+   * ```
+   *
+   * 2. `null` means namespaced, for example:
+   * ```js
+   * import * as globalName from 'module-name'
+   * ```
+   *
+   */
+  named?: string | null
+  /**
+   * If not `false`, the shim will only be applied when the original `globalName` unavailable,
+   * for example you may only want polyfill `globalThis.fetch` when it's unavailable natively:
+   * ```js
+   * import fetch from 'node-fetch'
+   *
+   * if (!globalThis.fetch) {
+   *   globalThis.fetch = fetch
+   * }
+   * ```
+   */
+  conditional?: boolean
+}
+````
+
+You can aslo reuse the exported `DEFAULT_GLOBAL_SHIMS_PRESET` for extanding:
+
+```js
+import { DEFAULT_GLOBAL_SHIMS_PRESET, createSyncFn } from 'synckit'
+
+const syncFn = createSyncFn(require.resolve('./worker'), {
+  globalShims: [
+    ...DEFAULT_GLOBAL_SHIMS_PRESET,
+    // your own shim here
+  ]
+})
+```

.github/workflows/ci.yml

@@ -12,6 +12,7 @@ jobs:
         node:
           - 16
           - 18
+          - 18.18
           - 20
         os:
           - macos-latest

.github/workflows/pkg-size.yml

@@ -1,9 +1,7 @@
 name: Package Size Report
 
 on:
-  pull_request_target:
-    branches:
-      - main
+  - pull_request
 
 jobs:
   pkg-size-report:

.nvmrc

@@ -0,0 +1 @@
+18.18

README.md

@@ -18,6 +18,7 @@ Perform async work synchronously in Node.js using `worker_threads` with first-cl
 - [Usage](#usage)
   - [Install](#install)
   - [API](#api)
+  - [Types](#types)
   - [Options](#options)
   - [Envs](#envs)
   - [TypeScript](#typescript)
@@ -71,20 +72,59 @@ runAsWorker(async (...args) => {
 
 You must make sure, the `result` is serializable by [`Structured Clone Algorithm`](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)
 
+### Types
+
+````ts
+export interface GlobalShim {
+  moduleName: string
+  /**
+   * `undefined` means side effect only
+   */
+  globalName?: string
+  /**
+   * 1. `undefined` or empty string means `default`, for example:
+   * ```js
+   * import globalName from 'module-name'
+   * ```
+   *
+   * 2. `null` means namespaced, for example:
+   * ```js
+   * import * as globalName from 'module-name'
+   * ```
+   *
+   */
+  named?: string | null
+  /**
+   * If not `false`, the shim will only be applied when the original `globalName` unavailable,
+   * for example you may only want polyfill `globalThis.fetch` when it's unavailable natively:
+   * ```js
+   * import fetch from 'node-fetch'
+   *
+   * if (!globalThis.fetch) {
+   *   globalThis.fetch = fetch
+   * }
+   * ```
+   */
+  conditional?: boolean
+}
+````
+
 ### Options
 
 1. `bufferSize` same as env `SYNCKIT_BUFFER_SIZE`
 2. `timeout` same as env `SYNCKIT_TIMEOUT`
 3. `execArgv` same as env `SYNCKIT_EXEC_ARGV`
 4. `tsRunner` same as env `SYNCKIT_TS_RUNNER`
 5. `transferList`: Please refer Node.js [`worker_threads`](https://nodejs.org/api/worker_threads.html#:~:text=Default%3A%20true.-,transferList,-%3CObject%5B%5D%3E%20If) documentation
+6. `globalShims`: Similar like env `SYNCKIT_GLOBAL_SHIMS` but much more flexible which can be a `GlobalShim` `Array`, see `GlobalShim`'s [definition](#types) for more details
 
 ### Envs
 
 1. `SYNCKIT_BUFFER_SIZE`: `bufferSize` to create `SharedArrayBuffer` for `worker_threads` (default as `1024`)
 2. `SYNCKIT_TIMEOUT`: `timeout` for performing the async job (no default)
 3. `SYNCKIT_EXEC_ARGV`: List of node CLI options passed to the worker, split with comma `,`. (default as `[]`), see also [`node` docs](https://nodejs.org/api/worker_threads.html)
 4. `SYNCKIT_TS_RUNNER`: Which TypeScript runner to be used, it could be very useful for development, could be `'ts-node' | 'esbuild-register' | 'esbuild-runner' | 'swc' | 'tsx'`, `'ts-node'` is used by default, make sure you have installed them already
+5. `SYNCKIT_GLOBAL_SHIMS`: Whether to enable the default `DEFAULT_GLOBAL_SHIMS_PRESET` as `globalShims`
 
 ### TypeScript
 

package.json

@@ -90,6 +90,9 @@
     "preset": "ts-jest",
     "testEnvironment": "node",
     "collectCoverage": true,
+    "collectCoverageFrom": [
+      "src/**"
+    ],
     "extensionsToTreatAsEsm": [
       ".ts"
     ],