index.types.ts

import { ParsedPath } from 'path'
import { preset } from './preset-types'

export interface Options {
   /**
    * **REQUIRED** unless using the `createAutoImportTask` function (defaults to the `sourceFolder` setting).
    *
    * Determines where the output file is sent after processing.
    *
    * Should be identical to the setting used in `gulp.dest()`.
    *
    * It is always a relative path from `gulpfile.js`, not a relative path from the current file.
    *
    * @example 'path/to/destination'
    *
    * @abstract The `gulp.dest()` setting is unavailable at the time the plugin is called, thus the setting needs to be provided explicitly.
    */
   dest?: string

   /**
    * Use a set of predefined default settings rather than configuring all of the settings yourself.
    *
    * You can view the available presets and the settings that they provide in the presets folder.
    *
    * @variation es5 - Import a set of functions using `require()` and then call them on page load
    *
    * @variation es5_default_exports - `exports.$name = require('$path')`
    *
    * @variation es5_named_exports - `exports.$name = require('$path').$name`
    *
    * @variation es6 - Import a set of functions using ES6 `import` syntax and then call them on page load
    *
    * @variation es6_default_exports - `export { default as $name } from '$path'`
    *
    * @variation es6_named_exports - `export { $name } from '$path'`
    *
    * @variation ts - Import a set of functions using TypeScript `import` syntax and then call them on page load
    *
    * @variation ts_default_exports - `export { default as $name } from '$path'`
    *
    * @variation ts_named_exports - `export { $name } from '$path'`
    *
    * @variation jade - `include $path` (outputs a .jade file)
    *
    * @variation pug - `include $path` (outputs a .pug file)
    *
    * @variation sass - `@import $path` (outputs a .sass file)
    *
    * @variation scss - `@import '$path';` (outputs a .scss file)
    *
    * @variation stylus - `@import '$path'` (outputs a .styl file)
    */
   preset?: preset

   /**
	 * The format setting dictates the format of each import line in the generated file.
	 *
	 * Use the `$path` and `$name` placeholders inside the string to determine where the file path and name should go.
	 *
	 * @example "export { $name } from '$path'"
	 * @example {
		imports: `import $name from '$path'`,
		functions: '  $name()',
	},
	 * @requires template (only if an object is provided)
	 */
   format?:
      | string
      | {
           [formatName: string]: string
        }

   /**
	 * The template setting holds a string that dictates the overall structure of the generated file.
	 *
	 * Use `$format[formatName]` placeholders in the template string to dictate where each format should be used in the output file.
	 *
	 * If the format setting is provided as a string, the template setting is ignored.
	 *
	 * **Do not place format string indents in this setting**, place them in the `format` setting instead.
	 *
	 * @example `
		$format[imports]

		export default function () {
		$format[functions]
		}
	 * `
	 */
   template?: string

   /**
    * Define the file name for the output file.
    *
    * The file extension must be included.
    *
    * @example "custom-file-name.js"
    */
   fileName?: string

   /**
    * `false` by default.
    *
    * When `true`, it will never alter the order that `$path` imports are loaded in.
    *
    * This gives you the ability to manually edit the output file to achieve the desired import order.
    *
    * Make sure to save the output file into source control so that your teammates end up with a file that is in the same order as yours.
    *
    * **Note:** Only compatible with the `$path` placeholder. `$noExtPath` and `$dir` placeholders are not supported.
    */
   retainOrder?: boolean

   /**
    * A string of text that is added to the top of the output file when it is generated.
    *
    * @example "// Do not edit this file directly"
    */
   header?: string

   /**
    * A string of text that is added to the bottom of the output file when it is generated.
    *
    * This might be useful for calling a custom function at the bottom of the file after all the imports have been loaded.
    */
   footer?: string

   /** Return a replacement string for each file import statement that gets generated. */
   formatReplace?: (params: FormatReplaceParams) => string

   /** Return a replacement string for an overall template. */
   templateReplace?: (params: TemplateReplaceParams) => string
}

export interface PathObject extends ParsedPath {
   /** The file extension (if any) such as 'js', note that the dot is not included. */
   ext: string
   /** The full relative path including the directory, file name, and extension such as '../path/to/file.js'. */
   fullPath: string
}

export interface Format {
   [formatName: string]: string
}

export interface FormatReplaceParams {
   /** The current formatted import line that would normally get printed out to the file. */
   output: string
   /** The format string being used to format the output. */
   format: string | Format
   /** If using a template, this is the key used to identify the formatter. */
   formatKey?: string
   /** Information about the current import path. */
   path: PathObject
}

export interface TemplateReplaceParams {
   /** The current output that would normally get printed out to the file */
   output: string
   /** The formatting object used to format the template */
   formats: {
      [formatName: string]: string
   }
   /** The template being used to format the output file */
   template: string
   /** A list of all the relative paths being used to generate the file */
   paths: Array<PathObject>
}

export type AutoImports = (options: Options) => NodeJS.ReadWriteStream