Skip to content

Commit b2affa0

Browse files
JounQinJounQin
authored
feat: add new globalShims option (#145)
1 parent 4053178 commit b2affa0

File tree

12 files changed

+484
-34
lines changed

12 files changed

+484
-34
lines changed

‎.changeset/funny-meals-speak.md

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
"synckit": patch
3+
---
4+
5+
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`.
6+
7+
You can also pass a custom `globalShims` option as `GlobalShim` `Array` to custom your own shims:
8+
9+
````ts
10+
export interface GlobalShim {
11+
moduleName: string
12+
/**
13+
* `undefined` means side effect only
14+
*/
15+
globalName?: string
16+
/**
17+
* 1. `undefined` or empty string means `default`, for example:
18+
* ```js
19+
* import globalName from 'module-name'
20+
* ```
21+
*
22+
* 2. `null` means namespaced, for example:
23+
* ```js
24+
* import * as globalName from 'module-name'
25+
* ```
26+
*
27+
*/
28+
named?: string | null
29+
/**
30+
* If not `false`, the shim will only be applied when the original `globalName` unavailable,
31+
* for example you may only want polyfill `globalThis.fetch` when it's unavailable natively:
32+
* ```js
33+
* import fetch from 'node-fetch'
34+
*
35+
* if (!globalThis.fetch) {
36+
* globalThis.fetch = fetch
37+
* }
38+
* ```
39+
*/
40+
conditional?: boolean
41+
}
42+
````
43+
44+
You can aslo reuse the exported `DEFAULT_GLOBAL_SHIMS_PRESET` for extanding:
45+
46+
```js
47+
import { DEFAULT_GLOBAL_SHIMS_PRESET, createSyncFn } from 'synckit'
48+
49+
const syncFn = createSyncFn(require.resolve('./worker'), {
50+
globalShims: [
51+
...DEFAULT_GLOBAL_SHIMS_PRESET,
52+
// your own shim here
53+
]
54+
})
55+
```

‎.github/workflows/ci.yml

+1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ jobs:
1212
node:
1313
- 16
1414
- 18
15+
- 18.18
1516
- 20
1617
os:
1718
- macos-latest

‎.github/workflows/pkg-size.yml

+1-3
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
name: Package Size Report
22

33
on:
4-
pull_request_target:
5-
branches:
6-
- main
4+
- pull_request
75

86
jobs:
97
pkg-size-report:

‎.nvmrc

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
18.18

‎README.md

+40
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ Perform async work synchronously in Node.js using `worker_threads` with first-cl
1818
- [Usage](#usage)
1919
- [Install](#install)
2020
- [API](#api)
21+
- [Types](#types)
2122
- [Options](#options)
2223
- [Envs](#envs)
2324
- [TypeScript](#typescript)
@@ -71,20 +72,59 @@ runAsWorker(async (...args) => {
7172

7273
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)
7374

75+
### Types
76+
77+
````ts
78+
export interface GlobalShim {
79+
moduleName: string
80+
/**
81+
* `undefined` means side effect only
82+
*/
83+
globalName?: string
84+
/**
85+
* 1. `undefined` or empty string means `default`, for example:
86+
* ```js
87+
* import globalName from 'module-name'
88+
* ```
89+
*
90+
* 2. `null` means namespaced, for example:
91+
* ```js
92+
* import * as globalName from 'module-name'
93+
* ```
94+
*
95+
*/
96+
named?: string | null
97+
/**
98+
* If not `false`, the shim will only be applied when the original `globalName` unavailable,
99+
* for example you may only want polyfill `globalThis.fetch` when it's unavailable natively:
100+
* ```js
101+
* import fetch from 'node-fetch'
102+
*
103+
* if (!globalThis.fetch) {
104+
* globalThis.fetch = fetch
105+
* }
106+
* ```
107+
*/
108+
conditional?: boolean
109+
}
110+
````
111+
74112
### Options
75113

76114
1. `bufferSize` same as env `SYNCKIT_BUFFER_SIZE`
77115
2. `timeout` same as env `SYNCKIT_TIMEOUT`
78116
3. `execArgv` same as env `SYNCKIT_EXEC_ARGV`
79117
4. `tsRunner` same as env `SYNCKIT_TS_RUNNER`
80118
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
119+
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
81120

82121
### Envs
83122

84123
1. `SYNCKIT_BUFFER_SIZE`: `bufferSize` to create `SharedArrayBuffer` for `worker_threads` (default as `1024`)
85124
2. `SYNCKIT_TIMEOUT`: `timeout` for performing the async job (no default)
86125
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)
87126
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
127+
5. `SYNCKIT_GLOBAL_SHIMS`: Whether to enable the default `DEFAULT_GLOBAL_SHIMS_PRESET` as `globalShims`
88128

89129
### TypeScript
90130

‎package.json

+3
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,9 @@
9090
"preset": "ts-jest",
9191
"testEnvironment": "node",
9292
"collectCoverage": true,
93+
"collectCoverageFrom": [
94+
"src/**"
95+
],
9396
"extensionsToTreatAsEsm": [
9497
".ts"
9598
],

0 commit comments

Comments
 (0)