types: add jsdoc based typescript typings

.gitignore

@@ -63,3 +63,5 @@ typings/
 
 
 # End of https://www.gitignore.io/api/node
+
+*.d.ts

file-util-git-history.js

@@ -4,12 +4,19 @@ const { isAbsolute, parse, resolve, relative } = require("path");
 const { promisify } = require("util");
 const assert = require("assert");
 
+/**
+ * @typedef {import("nodegit").Revwalk.HistoryEntry} HistoryEntry
+ *
+ * @typedef {Object} Options
+ * @property {string} [gitPath]
+ */
+
 const accessAsync = promisify(access);
 
 /**
  * Find closest git parent of a file or folder
  * @param {string} path - path to file or folder
- * @returns {string} path to git parent folder
+ * @returns {Promise<string>} path to git parent folder
  */
 async function resolveGitFolder(path) {
   assert(isAbsolute(path), "git path must be absolute");
@@ -36,7 +43,7 @@ async function resolveGitFolder(path) {
  * Read this history of a file in source control
  * @param {string} filePath - path to file
  * @param {string} gitPath - path to git folder
- * @returns {Commit[]} list of NodeGit commit objects
+ * @returns {Promise<HistoryEntry[]>} list of NodeGit commit objects
  */
 async function readHistory(filePath, gitPath) {
   // ensure filepath and gitpath exist
@@ -62,12 +69,14 @@ async function readHistory(filePath, gitPath) {
 /**
  * Read this history of a file in source control
  * @param {string} filePath - path to file
- * @param {Object} [options] - optional predetermined gitPath
- * @returns {Commit[]} list of NodeGit commit objects
+ * @param {Options} [options] - optional predetermined gitPath
+ * @returns {Promise<HistoryEntry[]>} list of NodeGit commit objects
  */
 async function gitHistory(filePath, options = {}) {
   assert(isAbsolute(filePath), "file path must be absolute");
-  const gitPath = options.gitPath ? options.gitPath : await resolveGitFolder(filePath);
+  const gitPath = options.gitPath
+    ? options.gitPath
+    : await resolveGitFolder(filePath);
   return readHistory(filePath, gitPath);
 }
 

package.json

@@ -3,11 +3,14 @@
   "version": "3.0.1",
   "description": "Get a file's git history",
   "main": "file-util-git-history.js",
+  "types": "file-util-git-history.d.ts",
   "files": [
-    "file-util-git-history.js"
+    "file-util-git-history.js",
+    "file-util-git-history.d.ts"
   ],
   "scripts": {
-    "test": "eslint . && jest"
+    "build": "rimraf \"{lib/**,}*.d.ts\" && tsc && type-coverage",
+    "test": "npm run build && eslint . && jest"
   },
   "repository": {
     "type": "git",
@@ -33,13 +36,17 @@
   },
   "homepage": "https://github.com/ChristianMurphy/file-util-git-history#readme",
   "devDependencies": {
+    "@types/jest": "^26.0.23",
     "eslint": "^7.20.0",
     "eslint-plugin-jest": "^24.1.5",
     "eslint-plugin-node": "^11.0.0",
     "husky": "^6.0.0",
     "jest": "^27.0.0",
     "lint-staged": "^11.0.0",
-    "prettier": "^2.0.0"
+    "prettier": "^2.0.0",
+    "rimraf": "^3.0.2",
+    "type-coverage": "^2.17.5",
+    "typescript": "^4.3.4"
   },
   "eslintConfig": {
     "env": {
@@ -71,6 +78,7 @@
     "node": "^10.0.0 || ^12.0.0 || ^14.0.0"
   },
   "dependencies": {
+    "@types/nodegit": "^0.27.2",
     "nodegit": "^0.27.0"
   },
   "renovate": {
@@ -88,5 +96,11 @@
     "hooks": {
       "pre-commit": "lint-staged"
     }
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
   }
 }

tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "include": ["*.js", "lib/**/*.js"],
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "allowJs": true,
+    "checkJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true
+  }
+}