Skip to content

Commit 9a9cf1e

Browse files
BendingBendersindresorhus
BendingBender
authored and
sindresorhus
committed
Add TypeScript definition (#111)
1 parent eb26c7e commit 9a9cf1e

File tree

4 files changed

+227
-3
lines changed

4 files changed

+227
-3
lines changed

‎index.d.ts

+123
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
import {IOptions as NodeGlobOptions} from 'glob';
2+
import {Options as FastGlobOptions} from 'fast-glob';
3+
4+
export type ExpandDirectoriesOption =
5+
| boolean
6+
| ReadonlyArray<string>
7+
| {files: ReadonlyArray<string>; extensions: ReadonlyArray<string>};
8+
9+
export interface GlobbyOptions extends FastGlobOptions {
10+
/**
11+
* 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.
12+
*
13+
* Note that if you set this option to `false`, you won't get back matched directories unless you set `onlyFiles: false`.
14+
*
15+
* @default true
16+
*
17+
* @example
18+
*
19+
* import globby from 'globby';
20+
*
21+
* (async () => {
22+
* const paths = await globby('images', {
23+
* expandDirectories: {
24+
* files: ['cat', 'unicorn', '*.jpg'],
25+
* extensions: ['png']
26+
* }
27+
* });
28+
* console.log(paths);
29+
* //=> ['cat.png', 'unicorn.png', 'cow.jpg', 'rainbow.jpg']
30+
* })();
31+
*/
32+
readonly expandDirectories?: ExpandDirectoriesOption;
33+
34+
/**
35+
* Respect ignore patterns in `.gitignore` files that apply to the globbed files.
36+
*
37+
* @default false
38+
*/
39+
readonly gitignore?: boolean;
40+
}
41+
42+
/**
43+
* @param patterns - See supported `minimatch` [patterns](https://github.com/isaacs/minimatch#usage).
44+
* @param options - See the [`fast-glob` options](https://github.com/mrmlnc/fast-glob#options-1) in addition to the ones in this package.
45+
* @returns A `Promise<Array>` of matching paths.
46+
*/
47+
export default function globby(
48+
patterns: string | ReadonlyArray<string>,
49+
options?: GlobbyOptions
50+
): Promise<string[]>;
51+
52+
/**
53+
* @param patterns - See supported `minimatch` [patterns](https://github.com/isaacs/minimatch#usage).
54+
* @param options - See the [`fast-glob` options](https://github.com/mrmlnc/fast-glob#options-1) in addition to the ones in this package.
55+
* @returns An `Array` of matching paths.
56+
*/
57+
export function sync(
58+
patterns: string | ReadonlyArray<string>,
59+
options?: GlobbyOptions
60+
): string[];
61+
62+
export interface GlobTask {
63+
readonly pattern: string;
64+
readonly options: GlobbyOptions;
65+
}
66+
67+
/**
68+
* 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.
69+
*
70+
* @param patterns - See supported `minimatch` [patterns](https://github.com/isaacs/minimatch#usage).
71+
* @param options - See the [`fast-glob` options](https://github.com/mrmlnc/fast-glob#options-1) in addition to the ones in this package.
72+
* @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.
73+
*/
74+
export function generateGlobTasks(
75+
patterns: string | ReadonlyArray<string>,
76+
options?: GlobbyOptions
77+
): GlobTask[];
78+
79+
/**
80+
* 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.
81+
*
82+
* This function is backed by [`node-glob`](https://github.com/isaacs/node-glob#globhasmagicpattern-options).
83+
*
84+
* @param patterns - See supported `minimatch` [patterns](https://github.com/isaacs/minimatch#usage).
85+
* @param options - See the [`node-glob` options](https://github.com/isaacs/node-glob#globhasmagicpattern-options).
86+
* @returns A boolean of whether there are any special glob characters in the `patterns`.
87+
*/
88+
export function hasMagic(
89+
patterns: string | ReadonlyArray<string>,
90+
options?: NodeGlobOptions
91+
): boolean;
92+
93+
export interface GitignoreOptions {
94+
readonly cwd?: string;
95+
readonly ignore?: ReadonlyArray<string>;
96+
}
97+
98+
export type FilterFunction = (path: string) => boolean;
99+
100+
export interface Gitignore {
101+
(options?: GitignoreOptions): Promise<FilterFunction>;
102+
103+
/**
104+
* @returns A filter function indicating whether a given path is ignored via a `.gitignore` file.
105+
*/
106+
sync(options?: GitignoreOptions): FilterFunction;
107+
}
108+
109+
/**
110+
* `.gitignore` files matched by the ignore config are not used for the resulting filter function.
111+
*
112+
* @returns A `Promise` for a filter function indicating whether a given path is ignored via a `.gitignore` file.
113+
*
114+
* @example
115+
*
116+
* import {gitignore} from 'globby';
117+
*
118+
* (async () => {
119+
* const isIgnored = await gitignore();
120+
* console.log(isIgnored('some/file'));
121+
* })();
122+
*/
123+
export const gitignore: Gitignore;

‎index.js

+4-1
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ const globToTask = task => glob => {
7575
};
7676
};
7777

78-
module.exports = (patterns, options) => {
78+
const globby = (patterns, options) => {
7979
let globTasks;
8080

8181
try {
@@ -106,6 +106,9 @@ module.exports = (patterns, options) => {
106106
});
107107
};
108108

109+
module.exports = globby;
110+
module.exports.default = globby;
111+
109112
module.exports.sync = (patterns, options) => {
110113
const globTasks = generateGlobTasks(patterns, options);
111114

‎index.test-d.ts

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
import {expectType} from 'tsd-check';
2+
import globby, {
3+
GlobTask,
4+
FilterFunction,
5+
sync as globbySync,
6+
generateGlobTasks,
7+
hasMagic,
8+
gitignore
9+
} from '.';
10+
11+
// Globby
12+
expectType<Promise<string[]>>(globby('*.tmp'));
13+
expectType<Promise<string[]>>(globby(['a.tmp', '*.tmp', '!{c,d,e}.tmp']));
14+
15+
expectType<Promise<string[]>>(globby('*.tmp', {expandDirectories: false}));
16+
expectType<Promise<string[]>>(
17+
globby('*.tmp', {expandDirectories: ['a*', 'b*']})
18+
);
19+
expectType<Promise<string[]>>(
20+
globby('*.tmp', {
21+
expandDirectories: {
22+
files: ['a', 'b'],
23+
extensions: ['tmp']
24+
}
25+
})
26+
);
27+
expectType<Promise<string[]>>(globby('*.tmp', {gitignore: true}));
28+
expectType<Promise<string[]>>(globby('*.tmp', {ignore: ['**/b.tmp']}));
29+
30+
// Globby (sync)
31+
expectType<string[]>(globbySync('*.tmp'));
32+
expectType<string[]>(globbySync(['a.tmp', '*.tmp', '!{c,d,e}.tmp']));
33+
34+
expectType<string[]>(globbySync('*.tmp', {expandDirectories: false}));
35+
expectType<string[]>(globbySync('*.tmp', {expandDirectories: ['a*', 'b*']}));
36+
expectType<string[]>(
37+
globbySync('*.tmp', {
38+
expandDirectories: {
39+
files: ['a', 'b'],
40+
extensions: ['tmp']
41+
}
42+
})
43+
);
44+
expectType<string[]>(globbySync('*.tmp', {gitignore: true}));
45+
expectType<string[]>(globbySync('*.tmp', {ignore: ['**/b.tmp']}));
46+
47+
// GenerateGlobTasks
48+
expectType<GlobTask[]>(generateGlobTasks('*.tmp'));
49+
expectType<GlobTask[]>(generateGlobTasks(['a.tmp', '*.tmp', '!{c,d,e}.tmp']));
50+
51+
expectType<GlobTask[]>(generateGlobTasks('*.tmp', {expandDirectories: false}));
52+
expectType<GlobTask[]>(
53+
generateGlobTasks('*.tmp', {expandDirectories: ['a*', 'b*']})
54+
);
55+
expectType<GlobTask[]>(
56+
generateGlobTasks('*.tmp', {
57+
expandDirectories: {
58+
files: ['a', 'b'],
59+
extensions: ['tmp']
60+
}
61+
})
62+
);
63+
expectType<GlobTask[]>(generateGlobTasks('*.tmp', {gitignore: true}));
64+
expectType<GlobTask[]>(generateGlobTasks('*.tmp', {ignore: ['**/b.tmp']}));
65+
66+
// HasMagic
67+
expectType<boolean>(hasMagic('**'));
68+
expectType<boolean>(hasMagic(['**', 'path1', 'path2']));
69+
expectType<boolean>(hasMagic(['**', 'path1', 'path2'], {noext: true}));
70+
71+
// Gitignore
72+
expectType<Promise<FilterFunction>>(gitignore());
73+
expectType<Promise<FilterFunction>>(
74+
gitignore({
75+
cwd: __dirname
76+
})
77+
);
78+
expectType<Promise<FilterFunction>>(
79+
gitignore({
80+
ignore: ['**/b.tmp']
81+
})
82+
);
83+
84+
// Gitignore (sync)
85+
expectType<FilterFunction>(gitignore.sync());
86+
expectType<FilterFunction>(
87+
gitignore.sync({
88+
cwd: __dirname
89+
})
90+
);
91+
expectType<FilterFunction>(
92+
gitignore.sync({
93+
ignore: ['**/b.tmp']
94+
})
95+
);

‎package.json

+5-2
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,12 @@
1414
},
1515
"scripts": {
1616
"bench": "npm update glob-stream fast-glob && matcha bench.js",
17-
"test": "xo && ava"
17+
"test": "xo && ava && tsd-check"
1818
},
1919
"files": [
2020
"index.js",
21-
"gitignore.js"
21+
"gitignore.js",
22+
"index.d.ts"
2223
],
2324
"keywords": [
2425
"all",
@@ -55,6 +56,7 @@
5556
"git"
5657
],
5758
"dependencies": {
59+
"@types/glob": "^7.1.1",
5860
"array-union": "^1.0.2",
5961
"dir-glob": "^2.2.1",
6062
"fast-glob": "^2.2.6",
@@ -69,6 +71,7 @@
6971
"globby": "sindresorhus/globby#master",
7072
"matcha": "^0.7.0",
7173
"rimraf": "^2.6.3",
74+
"tsd-check": "^0.3.0",
7275
"xo": "^0.24.0"
7376
},
7477
"xo": {

0 commit comments

Comments
 (0)