Add TypeScript definition (#111)

index.d.ts

@@ -0,0 +1,123 @@
+import {IOptions as NodeGlobOptions} from 'glob';
+import {Options as FastGlobOptions} from 'fast-glob';
+
+export type ExpandDirectoriesOption =
+	| boolean
+	| ReadonlyArray<string>
+	| {files: ReadonlyArray<string>; extensions: ReadonlyArray<string>};
+
+export interface GlobbyOptions extends FastGlobOptions {
+	/**
+	 * If set to `true`, `globby` will automatically glob directories for you. If you define an `Array` it will only glob files that matches the patterns inside the `Array`. You can also define an `Object` with `files` and `extensions` like in the example below.
+	 *
+	 * Note that if you set this option to `false`, you won't get back matched directories unless you set `onlyFiles: false`.
+	 *
+	 * @default true
+	 *
+	 * @example
+	 *
+	 * import globby from 'globby';
+	 *
+	 * (async () => {
+	 * 	const paths = await globby('images', {
+	 * 		expandDirectories: {
+	 * 			files: ['cat', 'unicorn', '*.jpg'],
+	 * 			extensions: ['png']
+	 * 		}
+	 * 	});
+	 * 	console.log(paths);
+	 * 	//=> ['cat.png', 'unicorn.png', 'cow.jpg', 'rainbow.jpg']
+	 * })();
+	 */
+	readonly expandDirectories?: ExpandDirectoriesOption;
+
+	/**
+	 * Respect ignore patterns in `.gitignore` files that apply to the globbed files.
+	 *
+	 * @default false
+	 */
+	readonly gitignore?: boolean;
+}
+
+/**
+ * @param patterns - See supported `minimatch` [patterns](https://github.com/isaacs/minimatch#usage).
+ * @param options - See the [`fast-glob` options](https://github.com/mrmlnc/fast-glob#options-1) in addition to the ones in this package.
+ * @returns A `Promise<Array>` of matching paths.
+ */
+export default function globby(
+	patterns: string | ReadonlyArray<string>,
+	options?: GlobbyOptions
+): Promise<string[]>;
+
+/**
+ * @param patterns - See supported `minimatch` [patterns](https://github.com/isaacs/minimatch#usage).
+ * @param options - See the [`fast-glob` options](https://github.com/mrmlnc/fast-glob#options-1) in addition to the ones in this package.
+ * @returns An `Array` of matching paths.
+ */
+export function sync(
+	patterns: string | ReadonlyArray<string>,
+	options?: GlobbyOptions
+): string[];
+
+export interface GlobTask {
+	readonly pattern: string;
+	readonly options: GlobbyOptions;
+}
+
+/**
+ * Note that you should avoid running the same tasks multiple times as they contain a file system cache. Instead, run this method each time to ensure file system changes are taken into consideration.
+ *
+ * @param patterns - See supported `minimatch` [patterns](https://github.com/isaacs/minimatch#usage).
+ * @param options - See the [`fast-glob` options](https://github.com/mrmlnc/fast-glob#options-1) in addition to the ones in this package.
+ * @returns An `Array<Object>` in the format `{ pattern: string, options: Object }`, which can be passed as arguments to [`fast-glob`](https://github.com/mrmlnc/fast-glob). This is useful for other globbing-related packages.
+ */
+export function generateGlobTasks(
+	patterns: string | ReadonlyArray<string>,
+	options?: GlobbyOptions
+): GlobTask[];
+
+/**
+ * Note that the options affect the results. If `noext: true` is set, then `+(a|b)` will not be considered a magic pattern. If the pattern has a brace expansion, like `a/{b/c,x/y}`, then that is considered magical, unless `nobrace: true` is set.
+ *
+ * This function is backed by [`node-glob`](https://github.com/isaacs/node-glob#globhasmagicpattern-options).
+ *
+ * @param patterns - See supported `minimatch` [patterns](https://github.com/isaacs/minimatch#usage).
+ * @param options - See the [`node-glob` options](https://github.com/isaacs/node-glob#globhasmagicpattern-options).
+ * @returns A boolean of whether there are any special glob characters in the `patterns`.
+ */
+export function hasMagic(
+	patterns: string | ReadonlyArray<string>,
+	options?: NodeGlobOptions
+): boolean;
+
+export interface GitignoreOptions {
+	readonly cwd?: string;
+	readonly ignore?: ReadonlyArray<string>;
+}
+
+export type FilterFunction = (path: string) => boolean;
+
+export interface Gitignore {
+	(options?: GitignoreOptions): Promise<FilterFunction>;
+
+	/**
+	 * @returns A filter function indicating whether a given path is ignored via a `.gitignore` file.
+	 */
+	sync(options?: GitignoreOptions): FilterFunction;
+}
+
+/**
+ * `.gitignore` files matched by the ignore config are not used for the resulting filter function.
+ *
+ * @returns A `Promise` for a filter function indicating whether a given path is ignored via a `.gitignore` file.
+ *
+ * @example
+ *
+ * import {gitignore} from 'globby';
+ *
+ * (async () => {
+ * 	const isIgnored = await gitignore();
+ * 	console.log(isIgnored('some/file'));
+ * })();
+ */
+export const gitignore: Gitignore;

index.js

@@ -75,7 +75,7 @@ const globToTask = task => glob => {
 	};
 };
 
-module.exports = (patterns, options) => {
+const globby = (patterns, options) => {
 	let globTasks;
 
 	try {
@@ -106,6 +106,9 @@ module.exports = (patterns, options) => {
 		});
 };
 
+module.exports = globby;
+module.exports.default = globby;
+
 module.exports.sync = (patterns, options) => {
 	const globTasks = generateGlobTasks(patterns, options);
 

index.test-d.ts

@@ -0,0 +1,95 @@
+import {expectType} from 'tsd-check';
+import globby, {
+	GlobTask,
+	FilterFunction,
+	sync as globbySync,
+	generateGlobTasks,
+	hasMagic,
+	gitignore
+} from '.';
+
+// Globby
+expectType<Promise<string[]>>(globby('*.tmp'));
+expectType<Promise<string[]>>(globby(['a.tmp', '*.tmp', '!{c,d,e}.tmp']));
+
+expectType<Promise<string[]>>(globby('*.tmp', {expandDirectories: false}));
+expectType<Promise<string[]>>(
+	globby('*.tmp', {expandDirectories: ['a*', 'b*']})
+);
+expectType<Promise<string[]>>(
+	globby('*.tmp', {
+		expandDirectories: {
+			files: ['a', 'b'],
+			extensions: ['tmp']
+		}
+	})
+);
+expectType<Promise<string[]>>(globby('*.tmp', {gitignore: true}));
+expectType<Promise<string[]>>(globby('*.tmp', {ignore: ['**/b.tmp']}));
+
+// Globby (sync)
+expectType<string[]>(globbySync('*.tmp'));
+expectType<string[]>(globbySync(['a.tmp', '*.tmp', '!{c,d,e}.tmp']));
+
+expectType<string[]>(globbySync('*.tmp', {expandDirectories: false}));
+expectType<string[]>(globbySync('*.tmp', {expandDirectories: ['a*', 'b*']}));
+expectType<string[]>(
+	globbySync('*.tmp', {
+		expandDirectories: {
+			files: ['a', 'b'],
+			extensions: ['tmp']
+		}
+	})
+);
+expectType<string[]>(globbySync('*.tmp', {gitignore: true}));
+expectType<string[]>(globbySync('*.tmp', {ignore: ['**/b.tmp']}));
+
+// GenerateGlobTasks
+expectType<GlobTask[]>(generateGlobTasks('*.tmp'));
+expectType<GlobTask[]>(generateGlobTasks(['a.tmp', '*.tmp', '!{c,d,e}.tmp']));
+
+expectType<GlobTask[]>(generateGlobTasks('*.tmp', {expandDirectories: false}));
+expectType<GlobTask[]>(
+	generateGlobTasks('*.tmp', {expandDirectories: ['a*', 'b*']})
+);
+expectType<GlobTask[]>(
+	generateGlobTasks('*.tmp', {
+		expandDirectories: {
+			files: ['a', 'b'],
+			extensions: ['tmp']
+		}
+	})
+);
+expectType<GlobTask[]>(generateGlobTasks('*.tmp', {gitignore: true}));
+expectType<GlobTask[]>(generateGlobTasks('*.tmp', {ignore: ['**/b.tmp']}));
+
+// HasMagic
+expectType<boolean>(hasMagic('**'));
+expectType<boolean>(hasMagic(['**', 'path1', 'path2']));
+expectType<boolean>(hasMagic(['**', 'path1', 'path2'], {noext: true}));
+
+// Gitignore
+expectType<Promise<FilterFunction>>(gitignore());
+expectType<Promise<FilterFunction>>(
+	gitignore({
+		cwd: __dirname
+	})
+);
+expectType<Promise<FilterFunction>>(
+	gitignore({
+		ignore: ['**/b.tmp']
+	})
+);
+
+// Gitignore (sync)
+expectType<FilterFunction>(gitignore.sync());
+expectType<FilterFunction>(
+	gitignore.sync({
+		cwd: __dirname
+	})
+);
+expectType<FilterFunction>(
+	gitignore.sync({
+		ignore: ['**/b.tmp']
+	})
+);

package.json

@@ -14,11 +14,12 @@
 	},
 	"scripts": {
 		"bench": "npm update glob-stream fast-glob && matcha bench.js",
-		"test": "xo && ava"
+		"test": "xo && ava && tsd-check"
 	},
 	"files": [
 		"index.js",
-		"gitignore.js"
+		"gitignore.js",
+		"index.d.ts"
 	],
 	"keywords": [
 		"all",
@@ -55,6 +56,7 @@
 		"git"
 	],
 	"dependencies": {
+		"@types/glob": "^7.1.1",
 		"array-union": "^1.0.2",
 		"dir-glob": "^2.2.1",
 		"fast-glob": "^2.2.6",
@@ -69,6 +71,7 @@
 		"globby": "sindresorhus/globby#master",
 		"matcha": "^0.7.0",
 		"rimraf": "^2.6.3",
+		"tsd-check": "^0.3.0",
 		"xo": "^0.24.0"
 	},
 	"xo": {