feat: copyDir supports more complex scenarios

API.md

@@ -39,15 +39,15 @@ public readonly buildOptions: BuildOptions;
 
 Build options passed on to esbuild. Please refer to the esbuild Build API docs for details.
 
-`buildOptions.outdir: string`
+* `buildOptions.outdir: string`
 The actual path for the output directory is defined by CDK. However setting this option allows to write files into a subdirectory. \
 For example `{ outdir: 'js' }` will create an asset with a single directory called `js`, which contains all built files. This approach can be useful for static website deployments, where JavaScript code should be placed into a subdirectory. \
 *Cannot be used together with `outfile`*.
-- `buildOptions.outfile: string`
+* `buildOptions.outfile: string`
 Relative path to a file inside the CDK asset output directory.
 For example `{ outfile: 'js/index.js' }` will create an asset with a single directory called `js`, which contains a single file `index.js`. This can be useful to rename the entry point. \
 *Cannot be used with multiple entryPoints or together with `outdir`.*
-- `buildOptions.absWorkingDir: string`
+* `buildOptions.absWorkingDir: string`
 Absolute path to the [esbuild working directory](https://esbuild.github.io/api/#working-directory) and defaults to the [current working directory](https://en.wikipedia.org/wiki/Working_directory). \
 If paths cannot be found, a good starting point is to look at the concatenation of `absWorkingDir + entryPoint`. It must always be a valid absolute path pointing to the entry point. When needed, the probably easiest way to set absWorkingDir is to use a combination of `resolve` and `__dirname` (see "Library authors" section in the documentation).
 
@@ -58,14 +58,27 @@ If paths cannot be found, a good starting point is to look at the concatenation
 ##### `copyDir`<sup>Optional</sup> <a name="@mrgrain/cdk-esbuild.AssetProps.property.copyDir"></a>
 
 ```typescript
-public readonly copyDir: string;
+public readonly copyDir: string | string[] | {[ key: string ]: string | string[]};
 ```
 
-- *Type:* `string`
+- *Type:* `string` | `string`[] | {[ key: string ]: `string` | `string`[]}
+
+Copy additional files to the code [asset staging directory](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.AssetStaging.html#absolutestagedpath), before the build runs. Files copied like this will be overwritten by esbuild if they share the same name as any of the outputs.
 
-Copy additional files to the output directory, before the build runs.
+* When provided with a `string` or `array`, all files are copied to the root of asset staging directory.
+* When given a `map`, the key indicates the destination relative to the asset staging directory and the value is a list of all sources to be copied.
 
-Files copied like this will be overwritten by esbuild if they share the same name as any of the outputs.
+Therefore the following values for `copyDir` are all equivalent:
+```ts
+{ copyDir: "path/to/source" }
+{ copyDir: ["path/to/source"] }
+{ copyDir: { ".": "path/to/source" } }
+{ copyDir: { ".": ["path/to/source"] } }
+```
+The destination cannot be outside of the asset staging directory.
+If you are receiving the error "Cannot copy files to outside of the asset staging directory."
+you are likely using `..` or an absolute path as key on the `copyDir` map.
+Instead use only relative paths and avoid `..`.
 
 ---
 
@@ -805,15 +818,15 @@ public readonly buildOptions: BuildOptions;
 
 Build options passed on to esbuild. Please refer to the esbuild Build API docs for details.
 
-`buildOptions.outdir: string`
+* `buildOptions.outdir: string`
 The actual path for the output directory is defined by CDK. However setting this option allows to write files into a subdirectory. \
 For example `{ outdir: 'js' }` will create an asset with a single directory called `js`, which contains all built files. This approach can be useful for static website deployments, where JavaScript code should be placed into a subdirectory. \
 *Cannot be used together with `outfile`*.
-- `buildOptions.outfile: string`
+* `buildOptions.outfile: string`
 Relative path to a file inside the CDK asset output directory.
 For example `{ outfile: 'js/index.js' }` will create an asset with a single directory called `js`, which contains a single file `index.js`. This can be useful to rename the entry point. \
 *Cannot be used with multiple entryPoints or together with `outdir`.*
-- `buildOptions.absWorkingDir: string`
+* `buildOptions.absWorkingDir: string`
 Absolute path to the [esbuild working directory](https://esbuild.github.io/api/#working-directory) and defaults to the [current working directory](https://en.wikipedia.org/wiki/Working_directory). \
 If paths cannot be found, a good starting point is to look at the concatenation of `absWorkingDir + entryPoint`. It must always be a valid absolute path pointing to the entry point. When needed, the probably easiest way to set absWorkingDir is to use a combination of `resolve` and `__dirname` (see "Library authors" section in the documentation).
 
@@ -824,14 +837,27 @@ If paths cannot be found, a good starting point is to look at the concatenation
 ##### `copyDir`<sup>Optional</sup> <a name="@mrgrain/cdk-esbuild.BundlerProps.property.copyDir"></a>
 
 ```typescript
-public readonly copyDir: string;
+public readonly copyDir: string | string[] | {[ key: string ]: string | string[]};
 ```
 
-- *Type:* `string`
+- *Type:* `string` | `string`[] | {[ key: string ]: `string` | `string`[]}
 
-Copy additional files to the output directory, before the build runs.
+Copy additional files to the code [asset staging directory](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.AssetStaging.html#absolutestagedpath), before the build runs. Files copied like this will be overwritten by esbuild if they share the same name as any of the outputs.
 
-Files copied like this will be overwritten by esbuild if they share the same name as any of the outputs.
+* When provided with a `string` or `array`, all files are copied to the root of asset staging directory.
+* When given a `map`, the key indicates the destination relative to the asset staging directory and the value is a list of all sources to be copied.
+
+Therefore the following values for `copyDir` are all equivalent:
+```ts
+{ copyDir: "path/to/source" }
+{ copyDir: ["path/to/source"] }
+{ copyDir: { ".": "path/to/source" } }
+{ copyDir: { ".": ["path/to/source"] } }
+```
+The destination cannot be outside of the asset staging directory.
+If you are receiving the error "Cannot copy files to outside of the asset staging directory."
+you are likely using `..` or an absolute path as key on the `copyDir` map.
+Instead use only relative paths and avoid `..`.
 
 ---
 
@@ -893,15 +919,15 @@ public readonly buildOptions: BuildOptions;
 
 Build options passed on to esbuild. Please refer to the esbuild Build API docs for details.
 
-`buildOptions.outdir: string`
+* `buildOptions.outdir: string`
 The actual path for the output directory is defined by CDK. However setting this option allows to write files into a subdirectory. \
 For example `{ outdir: 'js' }` will create an asset with a single directory called `js`, which contains all built files. This approach can be useful for static website deployments, where JavaScript code should be placed into a subdirectory. \
 *Cannot be used together with `outfile`*.
-- `buildOptions.outfile: string`
+* `buildOptions.outfile: string`
 Relative path to a file inside the CDK asset output directory.
 For example `{ outfile: 'js/index.js' }` will create an asset with a single directory called `js`, which contains a single file `index.js`. This can be useful to rename the entry point. \
 *Cannot be used with multiple entryPoints or together with `outdir`.*
-- `buildOptions.absWorkingDir: string`
+* `buildOptions.absWorkingDir: string`
 Absolute path to the [esbuild working directory](https://esbuild.github.io/api/#working-directory) and defaults to the [current working directory](https://en.wikipedia.org/wiki/Working_directory). \
 If paths cannot be found, a good starting point is to look at the concatenation of `absWorkingDir + entryPoint`. It must always be a valid absolute path pointing to the entry point. When needed, the probably easiest way to set absWorkingDir is to use a combination of `resolve` and `__dirname` (see "Library authors" section in the documentation).
 
@@ -912,14 +938,27 @@ If paths cannot be found, a good starting point is to look at the concatenation
 ##### `copyDir`<sup>Optional</sup> <a name="@mrgrain/cdk-esbuild.JavaScriptCodeProps.property.copyDir"></a>
 
 ```typescript
-public readonly copyDir: string;
+public readonly copyDir: string | string[] | {[ key: string ]: string | string[]};
 ```
 
-- *Type:* `string`
+- *Type:* `string` | `string`[] | {[ key: string ]: `string` | `string`[]}
 
-Copy additional files to the output directory, before the build runs.
+Copy additional files to the code [asset staging directory](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.AssetStaging.html#absolutestagedpath), before the build runs. Files copied like this will be overwritten by esbuild if they share the same name as any of the outputs.
 
-Files copied like this will be overwritten by esbuild if they share the same name as any of the outputs.
+* When provided with a `string` or `array`, all files are copied to the root of asset staging directory.
+* When given a `map`, the key indicates the destination relative to the asset staging directory and the value is a list of all sources to be copied.
+
+Therefore the following values for `copyDir` are all equivalent:
+```ts
+{ copyDir: "path/to/source" }
+{ copyDir: ["path/to/source"] }
+{ copyDir: { ".": "path/to/source" } }
+{ copyDir: { ".": ["path/to/source"] } }
+```
+The destination cannot be outside of the asset staging directory.
+If you are receiving the error "Cannot copy files to outside of the asset staging directory."
+you are likely using `..` or an absolute path as key on the `copyDir` map.
+Instead use only relative paths and avoid `..`.
 
 ---
 
@@ -975,15 +1014,15 @@ public readonly buildOptions: BuildOptions;
 
 Build options passed on to esbuild. Please refer to the esbuild Build API docs for details.
 
-`buildOptions.outdir: string`
+* `buildOptions.outdir: string`
 The actual path for the output directory is defined by CDK. However setting this option allows to write files into a subdirectory. \
 For example `{ outdir: 'js' }` will create an asset with a single directory called `js`, which contains all built files. This approach can be useful for static website deployments, where JavaScript code should be placed into a subdirectory. \
 *Cannot be used together with `outfile`*.
-- `buildOptions.outfile: string`
+* `buildOptions.outfile: string`
 Relative path to a file inside the CDK asset output directory.
 For example `{ outfile: 'js/index.js' }` will create an asset with a single directory called `js`, which contains a single file `index.js`. This can be useful to rename the entry point. \
 *Cannot be used with multiple entryPoints or together with `outdir`.*
-- `buildOptions.absWorkingDir: string`
+* `buildOptions.absWorkingDir: string`
 Absolute path to the [esbuild working directory](https://esbuild.github.io/api/#working-directory) and defaults to the [current working directory](https://en.wikipedia.org/wiki/Working_directory). \
 If paths cannot be found, a good starting point is to look at the concatenation of `absWorkingDir + entryPoint`. It must always be a valid absolute path pointing to the entry point. When needed, the probably easiest way to set absWorkingDir is to use a combination of `resolve` and `__dirname` (see "Library authors" section in the documentation).
 
@@ -994,14 +1033,27 @@ If paths cannot be found, a good starting point is to look at the concatenation
 ##### `copyDir`<sup>Optional</sup> <a name="@mrgrain/cdk-esbuild.JavaScriptSourceProps.property.copyDir"></a>
 
 ```typescript
-public readonly copyDir: string;
+public readonly copyDir: string | string[] | {[ key: string ]: string | string[]};
 ```
 
-- *Type:* `string`
+- *Type:* `string` | `string`[] | {[ key: string ]: `string` | `string`[]}
+
+Copy additional files to the code [asset staging directory](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.AssetStaging.html#absolutestagedpath), before the build runs. Files copied like this will be overwritten by esbuild if they share the same name as any of the outputs.
 
-Copy additional files to the output directory, before the build runs.
+* When provided with a `string` or `array`, all files are copied to the root of asset staging directory.
+* When given a `map`, the key indicates the destination relative to the asset staging directory and the value is a list of all sources to be copied.
 
-Files copied like this will be overwritten by esbuild if they share the same name as any of the outputs.
+Therefore the following values for `copyDir` are all equivalent:
+```ts
+{ copyDir: "path/to/source" }
+{ copyDir: ["path/to/source"] }
+{ copyDir: { ".": "path/to/source" } }
+{ copyDir: { ".": ["path/to/source"] } }
+```
+The destination cannot be outside of the asset staging directory.
+If you are receiving the error "Cannot copy files to outside of the asset staging directory."
+you are likely using `..` or an absolute path as key on the `copyDir` map.
+Instead use only relative paths and avoid `..`.
 
 ---
 
@@ -1495,15 +1547,15 @@ public readonly buildOptions: BuildOptions;
 
 Build options passed on to esbuild. Please refer to the esbuild Build API docs for details.
 
-`buildOptions.outdir: string`
+* `buildOptions.outdir: string`
 The actual path for the output directory is defined by CDK. However setting this option allows to write files into a subdirectory. \
 For example `{ outdir: 'js' }` will create an asset with a single directory called `js`, which contains all built files. This approach can be useful for static website deployments, where JavaScript code should be placed into a subdirectory. \
 *Cannot be used together with `outfile`*.
-- `buildOptions.outfile: string`
+* `buildOptions.outfile: string`
 Relative path to a file inside the CDK asset output directory.
 For example `{ outfile: 'js/index.js' }` will create an asset with a single directory called `js`, which contains a single file `index.js`. This can be useful to rename the entry point. \
 *Cannot be used with multiple entryPoints or together with `outdir`.*
-- `buildOptions.absWorkingDir: string`
+* `buildOptions.absWorkingDir: string`
 Absolute path to the [esbuild working directory](https://esbuild.github.io/api/#working-directory) and defaults to the [current working directory](https://en.wikipedia.org/wiki/Working_directory). \
 If paths cannot be found, a good starting point is to look at the concatenation of `absWorkingDir + entryPoint`. It must always be a valid absolute path pointing to the entry point. When needed, the probably easiest way to set absWorkingDir is to use a combination of `resolve` and `__dirname` (see "Library authors" section in the documentation).
 
@@ -1514,14 +1566,27 @@ If paths cannot be found, a good starting point is to look at the concatenation
 ##### `copyDir`<sup>Optional</sup> <a name="@mrgrain/cdk-esbuild.TypeScriptCodeProps.property.copyDir"></a>
 
 ```typescript
-public readonly copyDir: string;
+public readonly copyDir: string | string[] | {[ key: string ]: string | string[]};
 ```
 
-- *Type:* `string`
+- *Type:* `string` | `string`[] | {[ key: string ]: `string` | `string`[]}
 
-Copy additional files to the output directory, before the build runs.
+Copy additional files to the code [asset staging directory](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.AssetStaging.html#absolutestagedpath), before the build runs. Files copied like this will be overwritten by esbuild if they share the same name as any of the outputs.
 
-Files copied like this will be overwritten by esbuild if they share the same name as any of the outputs.
+* When provided with a `string` or `array`, all files are copied to the root of asset staging directory.
+* When given a `map`, the key indicates the destination relative to the asset staging directory and the value is a list of all sources to be copied.
+
+Therefore the following values for `copyDir` are all equivalent:
+```ts
+{ copyDir: "path/to/source" }
+{ copyDir: ["path/to/source"] }
+{ copyDir: { ".": "path/to/source" } }
+{ copyDir: { ".": ["path/to/source"] } }
+```
+The destination cannot be outside of the asset staging directory.
+If you are receiving the error "Cannot copy files to outside of the asset staging directory."
+you are likely using `..` or an absolute path as key on the `copyDir` map.
+Instead use only relative paths and avoid `..`.
 
 ---
 
@@ -1577,15 +1642,15 @@ public readonly buildOptions: BuildOptions;
 
 Build options passed on to esbuild. Please refer to the esbuild Build API docs for details.
 
-`buildOptions.outdir: string`
+* `buildOptions.outdir: string`
 The actual path for the output directory is defined by CDK. However setting this option allows to write files into a subdirectory. \
 For example `{ outdir: 'js' }` will create an asset with a single directory called `js`, which contains all built files. This approach can be useful for static website deployments, where JavaScript code should be placed into a subdirectory. \
 *Cannot be used together with `outfile`*.
-- `buildOptions.outfile: string`
+* `buildOptions.outfile: string`
 Relative path to a file inside the CDK asset output directory.
 For example `{ outfile: 'js/index.js' }` will create an asset with a single directory called `js`, which contains a single file `index.js`. This can be useful to rename the entry point. \
 *Cannot be used with multiple entryPoints or together with `outdir`.*
-- `buildOptions.absWorkingDir: string`
+* `buildOptions.absWorkingDir: string`
 Absolute path to the [esbuild working directory](https://esbuild.github.io/api/#working-directory) and defaults to the [current working directory](https://en.wikipedia.org/wiki/Working_directory). \
 If paths cannot be found, a good starting point is to look at the concatenation of `absWorkingDir + entryPoint`. It must always be a valid absolute path pointing to the entry point. When needed, the probably easiest way to set absWorkingDir is to use a combination of `resolve` and `__dirname` (see "Library authors" section in the documentation).
 
@@ -1596,14 +1661,27 @@ If paths cannot be found, a good starting point is to look at the concatenation
 ##### `copyDir`<sup>Optional</sup> <a name="@mrgrain/cdk-esbuild.TypeScriptSourceProps.property.copyDir"></a>
 
 ```typescript
-public readonly copyDir: string;
+public readonly copyDir: string | string[] | {[ key: string ]: string | string[]};
 ```
 
-- *Type:* `string`
+- *Type:* `string` | `string`[] | {[ key: string ]: `string` | `string`[]}
 
-Copy additional files to the output directory, before the build runs.
+Copy additional files to the code [asset staging directory](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.AssetStaging.html#absolutestagedpath), before the build runs. Files copied like this will be overwritten by esbuild if they share the same name as any of the outputs.
 
-Files copied like this will be overwritten by esbuild if they share the same name as any of the outputs.
+* When provided with a `string` or `array`, all files are copied to the root of asset staging directory.
+* When given a `map`, the key indicates the destination relative to the asset staging directory and the value is a list of all sources to be copied.
+
+Therefore the following values for `copyDir` are all equivalent:
+```ts
+{ copyDir: "path/to/source" }
+{ copyDir: ["path/to/source"] }
+{ copyDir: { ".": "path/to/source" } }
+{ copyDir: { ".": ["path/to/source"] } }
+```
+The destination cannot be outside of the asset staging directory.
+If you are receiving the error "Cannot copy files to outside of the asset staging directory."
+you are likely using `..` or an absolute path as key on the `copyDir` map.
+Instead use only relative paths and avoid `..`.
 
 ---