Skip to content

Commit 5f3a64a

Browse files
author
Strek
authored
docs(readme): added types (#660)
1 parent 9b5a314 commit 5f3a64a

File tree

3 files changed

+167
-54
lines changed

3 files changed

+167
-54
lines changed

‎README.md

Lines changed: 161 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -52,10 +52,8 @@ module.exports = {
5252
5353
## Options
5454

55-
| Name | Type | Description |
56-
| :-------------------------: | :-----------------------: | :--------------------------------------- |
57-
| **[`patterns`](#patterns)** | `{Array<String\|Object>}` | Specify file related patterns for plugin |
58-
| **[`options`](#options-1)** | `{Object}` | Specify options for plugin |
55+
- **[`patterns`](#patterns)**
56+
- **[`options`](#options-1)**
5957

6058
The plugin's signature:
6159

@@ -79,26 +77,29 @@ module.exports = {
7977
};
8078
```
8179

82-
### Patterns
83-
84-
| Name | Type | Default | Description |
85-
| :-------------------------------------: | :------------------: | :---------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
86-
| [`from`](#from) | `{String}` | `undefined` | Glob or path from where we copy files. |
87-
| [`to`](#to) | `{String\|Function}` | `compiler.options.output` | Output path. |
88-
| [`context`](#context) | `{String}` | `options.context \|\| compiler.options.context` | A path that determines how to interpret the `from` path. |
89-
| [`globOptions`](#globoptions) | `{Object}` | `undefined` | [Options][glob-options] passed to the glob pattern matching library including `ignore` option. |
90-
| [`filter`](#filter) | `{Function}` | `undefined` | Allows to filter copied assets. |
91-
| [`toType`](#totype) | `{String}` | `undefined` | Determinate what is `to` option - directory, file or template. |
92-
| [`force`](#force) | `{Boolean}` | `false` | Overwrites files already in `compilation.assets` (usually added by other plugins/loaders). |
93-
| [`priority`](#priority) | `{Number}` | `0` | Allows you to specify the copy priority. |
94-
| [`transform`](#transform) | `{Object}` | `undefined` | Allows to modify the file contents. Enable `transform` caching. You can use `{ transform: {cache: { key: 'my-cache-key' }} }` to invalidate the cache. |
95-
| [`transformAll`](#transformAll) | `{Function}` | `undefined` | Allows you to modify the contents of multiple files and save the result to one file. |
96-
| [`noErrorOnMissing`](#noerroronmissing) | `{Boolean}` | `false` | Doesn't generate an error on missing file(s). |
97-
| [`info`](#info) | `{Object\|Function}` | `undefined` | Allows to add assets info. |
80+
### `Patterns`
81+
82+
- [`from`](#from)
83+
- [`to`](#to)
84+
- [`context`](#context)
85+
- [`globOptions`](#globoptions)
86+
- [`filter`](#filter)
87+
- [`toType`](#totype)
88+
- [`force`](#force)
89+
- [`priority`](#priority)
90+
- [`transform`](#transform)
91+
- [`transformAll`](#transformAll)
92+
- [`noErrorOnMissing`](#noerroronmissing)
93+
- [`info`](#info)
9894

9995
#### `from`
10096

101-
Type: `String`
97+
Type:
98+
99+
```ts
100+
type from = string;
101+
```
102+
102103
Default: `undefined`
103104

104105
Glob or path from where we copy files.
@@ -179,10 +180,17 @@ More [`examples`](#examples)
179180

180181
#### `to`
181182

182-
Type: `String|Function`
183+
Type:
184+
185+
```ts
186+
type to =
187+
| string
188+
| ((pathData: { context: string; absoluteFilename?: string }) => string);
189+
```
190+
183191
Default: `compiler.options.output`
184192

185-
##### String
193+
##### `string`
186194

187195
Output path.
188196

@@ -215,7 +223,7 @@ module.exports = {
215223
};
216224
```
217225

218-
##### Function
226+
##### `function`
219227

220228
Allows to modify the writing path.
221229

@@ -263,7 +271,12 @@ module.exports = {
263271

264272
#### `context`
265273

266-
Type: `String`
274+
Type:
275+
276+
```ts
277+
type context = string;
278+
```
279+
267280
Default: `options.context|compiler.options.context`
268281

269282
A path that determines how to interpret the `from` path.
@@ -306,7 +319,12 @@ More [`examples`](#examples)
306319

307320
#### `globOptions`
308321

309-
Type: `Object`
322+
Type:
323+
324+
```ts
325+
type globOptions = import("globby").Options;
326+
```
327+
310328
Default: `undefined`
311329

312330
Allows to configure the glob pattern matching library used by the plugin. [See the list of supported options][glob-options]
@@ -335,7 +353,12 @@ module.exports = {
335353

336354
#### `filter`
337355

338-
Type: `Function`
356+
Type:
357+
358+
```ts
359+
type filter = (filepath: string) => boolean;
360+
```
361+
339362
Default: `undefined`
340363

341364
> ℹ️ To ignore files by path please use the [`globOptions.ignore`](#globoptions) option.
@@ -370,19 +393,24 @@ module.exports = {
370393

371394
#### `toType`
372395

373-
Type: `String`
396+
Type:
397+
398+
```ts
399+
type toType = "dir" | "file" | "template";
400+
```
401+
374402
Default: `undefined`
375403

376404
Determinate what is `to` option - directory, file or template.
377405
Sometimes it is hard to say what is `to`, example `path/to/dir-with.ext`.
378406
If you want to copy files in directory you need use `dir` option.
379407
We try to automatically determine the `type` so you most likely do not need this option.
380408

381-
| Name | Type | Default | Description |
382-
| :---------------------------: | :--------: | :---------: | :--------------------------------------------------------------------------------------------------- |
383-
| **[`'dir'`](#dir)** | `{String}` | `undefined` | If `to` has no extension or ends on `'/'` |
384-
| **[`'file'`](#file)** | `{String}` | `undefined` | If `to` is not a directory and is not a template |
385-
| **[`'template'`](#template)** | `{String}` | `undefined` | If `to` contains [a template pattern](https://webpack.js.org/configuration/output/#template-strings) |
409+
| Name | Type | Default | Description |
410+
| :---------------------------: | :------: | :---------: | :--------------------------------------------------------------------------------------------------- |
411+
| **[`'dir'`](#dir)** | `string` | `undefined` | If `to` has no extension or ends on `'/'` |
412+
| **[`'file'`](#file)** | `string` | `undefined` | If `to` is not a directory and is not a template |
413+
| **[`'template'`](#template)** | `string` | `undefined` | If `to` contains [a template pattern](https://webpack.js.org/configuration/output/#template-strings) |
386414

387415
##### `'dir'`
388416

@@ -446,7 +474,12 @@ module.exports = {
446474

447475
#### `force`
448476

449-
Type: `Boolean`
477+
Type:
478+
479+
```ts
480+
type force = boolean;
481+
```
482+
450483
Default: `false`
451484

452485
Overwrites files already in `compilation.assets` (usually added by other plugins/loaders).
@@ -471,7 +504,12 @@ module.exports = {
471504

472505
#### `priority`
473506

474-
Type: `Number`
507+
Type:
508+
509+
```ts
510+
type priority = number;
511+
```
512+
475513
Default: `0`
476514

477515
Allows to specify the priority of copying files with the same destination name.
@@ -506,12 +544,22 @@ module.exports = {
506544

507545
#### `transform`
508546

509-
Type: `Function|Object`
547+
Type:
548+
549+
```ts
550+
type transform =
551+
| {
552+
transformer: (input: string, absoluteFilename: string) => string;
553+
cache?: boolean | TransformerCacheObject | undefined;
554+
}
555+
| ((input: string, absoluteFilename: string) => string);
556+
```
557+
510558
Default: `undefined`
511559

512560
Allows to modify the file contents.
513561

514-
##### `Function`
562+
##### `function`
515563

516564
**webpack.config.js**
517565

@@ -535,16 +583,21 @@ module.exports = {
535583
};
536584
```
537585

538-
##### `Object`
586+
##### `object`
539587

540-
| Name | Type | Default | Description |
541-
| :-------------------------------: | :-----------------: | :---------: | :--------------------------------------------------------------------------------------------------------------- |
542-
| **[`transformer`](#transformer)** | `{Function}` | `undefined` | Allows to modify the file contents. |
543-
| **[`cache`](#cache)** | `{Boolean\|Object}` | `false` | Enable `transform` caching. You can use `transform: { cache: { key: 'my-cache-key' } }` to invalidate the cache. |
588+
| Name | Default | Description |
589+
| :-------------------------------: | :---------: | :--------------------------------------------------------------------------------------------------------------- |
590+
| **[`transformer`](#transformer)** | `undefined` | Allows to modify the file contents. |
591+
| **[`cache`](#cache)** | `false` | Enable `transform` caching. You can use `transform: { cache: { key: 'my-cache-key' } }` to invalidate the cache. |
544592

545593
###### `transformer`
546594

547-
Type: `Function`
595+
Type:
596+
597+
```ts
598+
type transformer = (input: string, absoluteFilename: string) => string;
599+
```
600+
548601
Default: `undefined`
549602

550603
**webpack.config.js**
@@ -595,15 +648,37 @@ module.exports = {
595648

596649
###### `cache`
597650

598-
Type: `Boolean|Object`
651+
Type:
652+
653+
```ts
654+
type cache =
655+
| boolean
656+
| {
657+
keys: {
658+
[key: string]: any;
659+
};
660+
}
661+
| {
662+
keys: (
663+
defaultCacheKeys: {
664+
[key: string]: any;
665+
},
666+
absoluteFilename: string
667+
) => Promise<{
668+
[key: string]: any;
669+
}>;
670+
}
671+
| undefined;
672+
```
673+
599674
Default: `false`
600675

601676
**webpack.config.js**
602677

603678
Enable/disable and configure caching.
604679
Default path to cache directory: `node_modules/.cache/copy-webpack-plugin`.
605680

606-
###### `Boolean`
681+
###### `boolean`
607682

608683
Enables/Disable `transform` caching.
609684

@@ -630,7 +705,7 @@ module.exports = {
630705
};
631706
```
632707

633-
##### `Object`
708+
##### `object`
634709

635710
Enables `transform` caching and setup cache directory and invalidation keys.
636711

@@ -738,7 +813,18 @@ module.exports = {
738813

739814
#### `transformAll`
740815

741-
Type: `Function`
816+
Type:
817+
818+
```ts
819+
type transformAll = (
820+
data: {
821+
data: Buffer;
822+
sourceFilename: string;
823+
absoluteFilename: string;
824+
}[]
825+
) => any;
826+
```
827+
742828
Default: `undefined`
743829

744830
Allows you to modify the contents of multiple files and save the result to one file.
@@ -777,7 +863,12 @@ module.exports = {
777863

778864
### `noErrorOnMissing`
779865

780-
Type: `Boolean`
866+
Type:
867+
868+
```ts
869+
type noErrorOnMissing = boolean;
870+
```
871+
781872
Default: `false`
782873

783874
Doesn't generate an error on missing file(s).
@@ -799,7 +890,19 @@ module.exports = {
799890

800891
#### `info`
801892

802-
Type: `Object|Function<Object>`
893+
Type:
894+
895+
```ts
896+
type info =
897+
| Record<string, string>
898+
| ((item: {
899+
absoluteFilename: string;
900+
sourceFilename: string;
901+
filename: string;
902+
toType: ToType;
903+
}) => Record<string, string>);
904+
```
905+
803906
Default: `undefined`
804907

805908
Allows to add assets info.
@@ -844,12 +947,18 @@ module.exports = {
844947

845948
### Options
846949

847-
| Name | Type | Default | Description |
848-
| :---------------------------: | :--------: | :-----: | :----------------------------------------------- |
849-
| [`concurrency`](#concurrency) | `{Number}` | `100` | Limits the number of simultaneous requests to fs |
950+
- [`concurrency`](#concurrency)
850951

851952
#### `concurrency`
852953

954+
type:
955+
956+
```ts
957+
type concurrency = number;
958+
```
959+
960+
default: `100`
961+
853962
limits the number of simultaneous requests to fs
854963

855964
**webpack.config.js**

‎src/index.js

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,11 +93,13 @@ const template = /\[\\*([\w:]+)\\*\]/i;
9393
/**
9494
* @callback Filter
9595
* @param {string} filepath
96+
* @returns {boolean}
9697
*/
9798

9899
/**
99100
* @callback TransformAllFunction
100101
* @param {{ data: Buffer, sourceFilename: string, absoluteFilename: string }[]} data
102+
* @returns {string | Buffer}
101103
*/
102104

103105
/**

0 commit comments

Comments
 (0)