From 5f3a64a00b8fd606a706c3f40f7300701fc55d78 Mon Sep 17 00:00:00 2001 From: Strek Date: Thu, 20 Jan 2022 17:44:25 +0530 Subject: [PATCH] docs(readme): added types (#660) --- README.md | 213 +++++++++++++++++++++++++++++++++++------------ src/index.js | 2 + types/index.d.ts | 6 +- 3 files changed, 167 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index ac59fc1..0b97979 100644 --- a/README.md +++ b/README.md @@ -52,10 +52,8 @@ module.exports = { ## Options -| Name | Type | Description | -| :-------------------------: | :-----------------------: | :--------------------------------------- | -| **[`patterns`](#patterns)** | `{Array}` | Specify file related patterns for plugin | -| **[`options`](#options-1)** | `{Object}` | Specify options for plugin | +- **[`patterns`](#patterns)** +- **[`options`](#options-1)** The plugin's signature: @@ -79,26 +77,29 @@ module.exports = { }; ``` -### Patterns - -| Name | Type | Default | Description | -| :-------------------------------------: | :------------------: | :---------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`from`](#from) | `{String}` | `undefined` | Glob or path from where we copy files. | -| [`to`](#to) | `{String\|Function}` | `compiler.options.output` | Output path. | -| [`context`](#context) | `{String}` | `options.context \|\| compiler.options.context` | A path that determines how to interpret the `from` path. | -| [`globOptions`](#globoptions) | `{Object}` | `undefined` | [Options][glob-options] passed to the glob pattern matching library including `ignore` option. | -| [`filter`](#filter) | `{Function}` | `undefined` | Allows to filter copied assets. | -| [`toType`](#totype) | `{String}` | `undefined` | Determinate what is `to` option - directory, file or template. | -| [`force`](#force) | `{Boolean}` | `false` | Overwrites files already in `compilation.assets` (usually added by other plugins/loaders). | -| [`priority`](#priority) | `{Number}` | `0` | Allows you to specify the copy priority. | -| [`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. | -| [`transformAll`](#transformAll) | `{Function}` | `undefined` | Allows you to modify the contents of multiple files and save the result to one file. | -| [`noErrorOnMissing`](#noerroronmissing) | `{Boolean}` | `false` | Doesn't generate an error on missing file(s). | -| [`info`](#info) | `{Object\|Function}` | `undefined` | Allows to add assets info. | +### `Patterns` + +- [`from`](#from) +- [`to`](#to) +- [`context`](#context) +- [`globOptions`](#globoptions) +- [`filter`](#filter) +- [`toType`](#totype) +- [`force`](#force) +- [`priority`](#priority) +- [`transform`](#transform) +- [`transformAll`](#transformAll) +- [`noErrorOnMissing`](#noerroronmissing) +- [`info`](#info) #### `from` -Type: `String` +Type: + +```ts +type from = string; +``` + Default: `undefined` Glob or path from where we copy files. @@ -179,10 +180,17 @@ More [`examples`](#examples) #### `to` -Type: `String|Function` +Type: + +```ts +type to = + | string + | ((pathData: { context: string; absoluteFilename?: string }) => string); +``` + Default: `compiler.options.output` -##### String +##### `string` Output path. @@ -215,7 +223,7 @@ module.exports = { }; ``` -##### Function +##### `function` Allows to modify the writing path. @@ -263,7 +271,12 @@ module.exports = { #### `context` -Type: `String` +Type: + +```ts +type context = string; +``` + Default: `options.context|compiler.options.context` A path that determines how to interpret the `from` path. @@ -306,7 +319,12 @@ More [`examples`](#examples) #### `globOptions` -Type: `Object` +Type: + +```ts +type globOptions = import("globby").Options; +``` + Default: `undefined` 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 = { #### `filter` -Type: `Function` +Type: + +```ts +type filter = (filepath: string) => boolean; +``` + Default: `undefined` > ℹ️ To ignore files by path please use the [`globOptions.ignore`](#globoptions) option. @@ -370,7 +393,12 @@ module.exports = { #### `toType` -Type: `String` +Type: + +```ts +type toType = "dir" | "file" | "template"; +``` + Default: `undefined` Determinate what is `to` option - directory, file or template. @@ -378,11 +406,11 @@ Sometimes it is hard to say what is `to`, example `path/to/dir-with.ext`. If you want to copy files in directory you need use `dir` option. We try to automatically determine the `type` so you most likely do not need this option. -| Name | Type | Default | Description | -| :---------------------------: | :--------: | :---------: | :--------------------------------------------------------------------------------------------------- | -| **[`'dir'`](#dir)** | `{String}` | `undefined` | If `to` has no extension or ends on `'/'` | -| **[`'file'`](#file)** | `{String}` | `undefined` | If `to` is not a directory and is not a template | -| **[`'template'`](#template)** | `{String}` | `undefined` | If `to` contains [a template pattern](https://webpack.js.org/configuration/output/#template-strings) | +| Name | Type | Default | Description | +| :---------------------------: | :------: | :---------: | :--------------------------------------------------------------------------------------------------- | +| **[`'dir'`](#dir)** | `string` | `undefined` | If `to` has no extension or ends on `'/'` | +| **[`'file'`](#file)** | `string` | `undefined` | If `to` is not a directory and is not a template | +| **[`'template'`](#template)** | `string` | `undefined` | If `to` contains [a template pattern](https://webpack.js.org/configuration/output/#template-strings) | ##### `'dir'` @@ -446,7 +474,12 @@ module.exports = { #### `force` -Type: `Boolean` +Type: + +```ts +type force = boolean; +``` + Default: `false` Overwrites files already in `compilation.assets` (usually added by other plugins/loaders). @@ -471,7 +504,12 @@ module.exports = { #### `priority` -Type: `Number` +Type: + +```ts +type priority = number; +``` + Default: `0` Allows to specify the priority of copying files with the same destination name. @@ -506,12 +544,22 @@ module.exports = { #### `transform` -Type: `Function|Object` +Type: + +```ts +type transform = + | { + transformer: (input: string, absoluteFilename: string) => string; + cache?: boolean | TransformerCacheObject | undefined; + } + | ((input: string, absoluteFilename: string) => string); +``` + Default: `undefined` Allows to modify the file contents. -##### `Function` +##### `function` **webpack.config.js** @@ -535,16 +583,21 @@ module.exports = { }; ``` -##### `Object` +##### `object` -| Name | Type | Default | Description | -| :-------------------------------: | :-----------------: | :---------: | :--------------------------------------------------------------------------------------------------------------- | -| **[`transformer`](#transformer)** | `{Function}` | `undefined` | Allows to modify the file contents. | -| **[`cache`](#cache)** | `{Boolean\|Object}` | `false` | Enable `transform` caching. You can use `transform: { cache: { key: 'my-cache-key' } }` to invalidate the cache. | +| Name | Default | Description | +| :-------------------------------: | :---------: | :--------------------------------------------------------------------------------------------------------------- | +| **[`transformer`](#transformer)** | `undefined` | Allows to modify the file contents. | +| **[`cache`](#cache)** | `false` | Enable `transform` caching. You can use `transform: { cache: { key: 'my-cache-key' } }` to invalidate the cache. | ###### `transformer` -Type: `Function` +Type: + +```ts +type transformer = (input: string, absoluteFilename: string) => string; +``` + Default: `undefined` **webpack.config.js** @@ -595,7 +648,29 @@ module.exports = { ###### `cache` -Type: `Boolean|Object` +Type: + +```ts +type cache = + | boolean + | { + keys: { + [key: string]: any; + }; + } + | { + keys: ( + defaultCacheKeys: { + [key: string]: any; + }, + absoluteFilename: string + ) => Promise<{ + [key: string]: any; + }>; + } + | undefined; +``` + Default: `false` **webpack.config.js** @@ -603,7 +678,7 @@ Default: `false` Enable/disable and configure caching. Default path to cache directory: `node_modules/.cache/copy-webpack-plugin`. -###### `Boolean` +###### `boolean` Enables/Disable `transform` caching. @@ -630,7 +705,7 @@ module.exports = { }; ``` -##### `Object` +##### `object` Enables `transform` caching and setup cache directory and invalidation keys. @@ -738,7 +813,18 @@ module.exports = { #### `transformAll` -Type: `Function` +Type: + +```ts +type transformAll = ( + data: { + data: Buffer; + sourceFilename: string; + absoluteFilename: string; + }[] +) => any; +``` + Default: `undefined` Allows you to modify the contents of multiple files and save the result to one file. @@ -777,7 +863,12 @@ module.exports = { ### `noErrorOnMissing` -Type: `Boolean` +Type: + +```ts +type noErrorOnMissing = boolean; +``` + Default: `false` Doesn't generate an error on missing file(s). @@ -799,7 +890,19 @@ module.exports = { #### `info` -Type: `Object|Function` +Type: + +```ts +type info = + | Record + | ((item: { + absoluteFilename: string; + sourceFilename: string; + filename: string; + toType: ToType; + }) => Record); +``` + Default: `undefined` Allows to add assets info. @@ -844,12 +947,18 @@ module.exports = { ### Options -| Name | Type | Default | Description | -| :---------------------------: | :--------: | :-----: | :----------------------------------------------- | -| [`concurrency`](#concurrency) | `{Number}` | `100` | Limits the number of simultaneous requests to fs | +- [`concurrency`](#concurrency) #### `concurrency` +type: + +```ts +type concurrency = number; +``` + +default: `100` + limits the number of simultaneous requests to fs **webpack.config.js** diff --git a/src/index.js b/src/index.js index caada0e..a1ff362 100644 --- a/src/index.js +++ b/src/index.js @@ -93,11 +93,13 @@ const template = /\[\\*([\w:]+)\\*\]/i; /** * @callback Filter * @param {string} filepath + * @returns {boolean} */ /** * @callback TransformAllFunction * @param {{ data: Buffer, sourceFilename: string, absoluteFilename: string }[]} data + * @returns {string | Buffer} */ /** diff --git a/types/index.d.ts b/types/index.d.ts index 850db6f..51a1723 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -64,10 +64,12 @@ export = CopyPlugin; /** * @callback Filter * @param {string} filepath + * @returns {boolean} */ /** * @callback TransformAllFunction * @param {{ data: Buffer, sourceFilename: string, absoluteFilename: string }[]} data + * @returns {string | Buffer} */ /** * @typedef { { [key: string]: string } | ((item: { absoluteFilename: string, sourceFilename: string, filename: string, toType: ToType }) => { [key: string]: string }) } Info @@ -249,14 +251,14 @@ type TransformerObject = { cache?: boolean | TransformerCacheObject | undefined; }; type Transform = TransformerFunction | TransformerObject; -type Filter = (filepath: string) => any; +type Filter = (filepath: string) => boolean; type TransformAllFunction = ( data: { data: Buffer; sourceFilename: string; absoluteFilename: string; }[] -) => any; +) => string | Buffer; type Info = | { [key: string]: string;