forked from Rowland/EG
144 lines
2.8 KiB
TypeScript
144 lines
2.8 KiB
TypeScript
import File = require('vinyl');
|
|
|
|
export type Options = {
|
|
/**
|
|
Whether the plugin can handle directories.
|
|
|
|
@default false
|
|
*/
|
|
readonly supportsDirectories?: boolean;
|
|
|
|
/**
|
|
Whether the plugin can handle any Vinyl file type.
|
|
|
|
Useful for custom type filtering.
|
|
|
|
Supersedes `supportsDirectories`.
|
|
|
|
@default false
|
|
*/
|
|
readonly supportsAnyType?: boolean;
|
|
|
|
/**
|
|
An async generator function executed for finalization after all files have been processed.
|
|
|
|
You can yield more files from it if needed.
|
|
|
|
@example
|
|
```
|
|
import {gulpPlugin} from 'gulp-plugin-extras';
|
|
|
|
export default function gulpFoo() {
|
|
return gulpPlugin(
|
|
'gulp-foo',
|
|
async file => { … },
|
|
{
|
|
async * onFinish() {
|
|
yield someVinylFile;
|
|
yield someVinylFile2;
|
|
}
|
|
}
|
|
);
|
|
}
|
|
```
|
|
*/
|
|
readonly onFinish?: (stream: NodeJS.ReadableStream) => AsyncGenerator<File, never, void>;
|
|
};
|
|
|
|
/**
|
|
Create a Gulp plugin.
|
|
|
|
@param name - The plugin name.
|
|
@param onFile - The function called for each vinyl file in the stream. Must return a modified or new vinyl file. May be async.
|
|
|
|
If you throw an error with a `.isPresentable = true` property, it will not display the error stack.
|
|
|
|
_This does not support streaming unless you enable the `supportsAnyType` option._
|
|
|
|
@example
|
|
```
|
|
import {gulpPlugin} from 'gulp-plugin-extras';
|
|
|
|
export default function gulpFoo() {
|
|
return gulpPlugin('gulp-foo', async file => {
|
|
file.contents = await someKindOfTransformation(file.contents);
|
|
return file;
|
|
});
|
|
}
|
|
```
|
|
*/
|
|
export function gulpPlugin(
|
|
name: string,
|
|
onFile: (file: File) => File | Promise<File>,
|
|
options?: Options
|
|
): NodeJS.ReadableStream;
|
|
|
|
export type PluginErrorOptions = Error & {
|
|
/**
|
|
The plugin name.
|
|
*/
|
|
plugin: string;
|
|
|
|
/**
|
|
Error cause indicating the reason why the current error is thrown.
|
|
*/
|
|
cause?: string;
|
|
|
|
/**
|
|
The error currently being thrown.
|
|
*/
|
|
error?: Error;
|
|
|
|
/**
|
|
The path to the file that raised the error.
|
|
*/
|
|
fileName?: string;
|
|
|
|
/**
|
|
The line number where the error occurred.
|
|
*/
|
|
lineNumber?: number;
|
|
|
|
/**
|
|
Whether to show relevant properties in the error message details.
|
|
|
|
@default true
|
|
*/
|
|
showProperties?: boolean;
|
|
|
|
/**
|
|
Whether to show the error stack trace.
|
|
|
|
@default false
|
|
*/
|
|
showStack?: boolean;
|
|
};
|
|
|
|
/**
|
|
A plugin error.
|
|
|
|
@example
|
|
```
|
|
import {PluginError} from 'gulp-plugin-extras';
|
|
|
|
throw new PluginError('gulpFoo', 'Some error message');
|
|
```
|
|
*/
|
|
export class PluginError implements PluginErrorOptions {
|
|
plugin: string;
|
|
message: string;
|
|
name: string;
|
|
options_: PluginErrorOptions;
|
|
cause?: string;
|
|
error?: Error;
|
|
fileName?: string;
|
|
lineNumber?: number;
|
|
showProperties?: boolean;
|
|
showStack?: boolean;
|
|
stack?: string;
|
|
|
|
constructor(options?: PluginErrorOptions);
|
|
constructor(plugin: string, options?: PluginErrorOptions);
|
|
constructor(plugin: string, message: Error | string, options?: PluginErrorOptions);
|
|
}
|