Add TypeScript type definitions (#39)

index.d.ts

@@ -0,0 +1,47 @@
+export type Options = {
+	/**
+	Should be the same as your project name in `package.json`.
+	*/
+	readonly name: string;
+
+	/**
+	An array of files that will be searched for a common parent directory. This
+	common parent directory will be used in lieu of the `cwd` option below.
+	*/
+	readonly files?: string[] | string;
+
+	/**
+	Directory to start searching for a `package.json` from.
+
+	@default process.cwd()
+	*/
+	readonly cwd?: string;
+
+	/**
+	If `true`, the directory will be created synchronously before returning.
+
+	@default false
+	*/
+	readonly create?: boolean;
+
+	/**
+	If `true`, this modifies the return type to be a function that is a thunk for
+	`path.join(theFoundCacheDirectory)`.
+
+	@default false
+	*/
+	readonly thunk?: boolean;
+};
+
+/**
+Finds the cache directory using the supplied options. The algorithm checks for
+the `CACHE_DIR` environmental variable and uses it if it is not set to `true`,
+`false`, `1` or `0`. If one is not found, it tries to find a `package.json`
+file, searching every parent directory of the `cwd` specified (or implied from
+other options). It returns a `string` containing the absolute path to the cache
+directory, or `undefined` if `package.json` was never found or if the
+`node_modules` directory is unwritable.
+*/
+export default function findCacheDirectory(
+	options: Options,
+): string | undefined;

index.test-d.ts

@@ -0,0 +1,9 @@
+import {expectType} from 'tsd';
+import findCacheDirectory from './index.js';
+
+expectType<string | undefined>(findCacheDirectory({name: 'find-cache-dir'}));
+expectType<string | undefined>(findCacheDirectory({name: 'find-cache-dir', files: '/foo'}));
+expectType<string | undefined>(findCacheDirectory({name: 'find-cache-dir', files: ['/bar']}));
+expectType<string | undefined>(findCacheDirectory({name: 'find-cache-dir', cwd: '/fooz'}));
+expectType<string | undefined>(findCacheDirectory({name: 'find-cache-dir', create: true}));
+expectType<string | undefined>(findCacheDirectory({name: 'find-cache-dir', thunk: true}));

package.json

@@ -16,10 +16,11 @@
 		"node": ">=14.16"
 	},
 	"scripts": {
-		"test": "xo && ava"
+		"test": "xo && ava && tsd"
 	},
 	"files": [
-		"index.js"
+		"index.js",
+		"index.d.ts"
 	],
 	"keywords": [
 		"cache",
@@ -37,7 +38,8 @@
 		"ava": "^5.0.1",
 		"del": "^7.0.0",
 		"tempy": "^3.0.0",
-		"xo": "^0.52.4"
+		"tsd": "^0.28.0",
+		"xo": "^0.56.0"
 	},
 	"ava": {
 		"workerThreads": false