Provide type definitions

Author: axelrindle

index.d.ts

@@ -0,0 +1,97 @@
+/// <reference types="node/http" />
+
+import { IncomingMessage } from "http"
+
+interface CheckOptions {
+	/**
+	 * A personal access token used for private repositories or to increase
+	 * the rate limit.
+	 */
+	token?: string
+
+	/**
+	 * The name of the Github repository to check.
+	 */
+	repo: string
+
+	/**
+	 * The owner of the repository.
+	 */
+	owner: string
+
+	/**
+	 * The current version of the application.
+	 */
+	currentVersion: string
+
+	/**
+	 * @deprecated
+	 */
+	reduceTraffic?: boolean
+
+	/**
+	 * Whether to fetch the repositories' git tags instead of the GitHub releases.
+	 * Useful when no releases are created, but only tags.
+	 */
+	fetchTags?: boolean
+
+	/**
+	 * Setting this to true will fetch the latest release only.
+	 */
+	latestOnly?: boolean
+
+	/**
+	 * Excludes pre-releases from checks.
+	 * Currently only works when no token is specified.
+	 */
+	excludePrereleases?: boolean
+}
+
+/**
+ * Describes the structure of returned tag data.
+ */
+interface TagDescriptor {
+	/**
+	 * The name of the tag.
+	 * 
+	 * @example v1.2.3
+	 */
+	name: string
+}
+
+/**
+ * Describes the structure of returned release data.
+ */
+interface ReleaseDescriptor {
+	/**
+	 * The name of this release.
+	 */
+	name: string
+
+	/**
+	 * The tag associated with this release.
+	 */
+	tag: TagDescriptor
+
+	/**
+	 * Whether this release is a pre-release.
+	 */
+	isPrerelease: boolean
+
+	/**
+	 * A datetime string indicating the time this release was published.
+	 */
+	publishedAt: string
+
+	/**
+	 * A url where details about this release can be viewed.
+	 */
+	url: string
+}
+
+type CallbackFunction = (error?: Error, update?: ReleaseDescriptor | TagDescriptor) => void
+
+type RestHandlerFunction = (res: IncomingMessage) => void
+
+export default function check(options: CheckOptions, callback: CallbackFunction): null | Promise<ReleaseDescriptor|TagDescriptor>
+export = check

jsconfig.json

@@ -0,0 +1,14 @@
+{
+	"compilerOptions": {
+		"module": "CommonJS",
+		"target": "ES6",
+		"moduleResolution": "Node",
+		"resolveJsonModule": true,
+		"allowJs": true,
+		"checkJs": true,
+	},
+	"include": [
+		"index.js",
+		"lib/**/*.js"
+	]
+}

lib/check.js

@@ -12,8 +12,8 @@ const pkg = require('../package.json');
  * When the fetched version is greater than the given one, the newer version
  * is returned.
  *
- * @param options {object} The options for the version check.
- * @param callback {function|undefined} The callback function.
+ * @param {CheckOptions} options The options for the version check.
+ * @param {CallbackFunction} callback The callback function.
  */
 const graphql = (options, callback) => {
 	// build the query
@@ -46,10 +46,11 @@ const graphql = (options, callback) => {
  * When the fetched version is greater than the given one, the newer version
  * is returned.
  *
- * @param options {object} The options for the version check.
- * @param callback {function|undefined} The callback function.
+ * @param {CheckOptions} options The options for the version check.
+ * @param {CallbackFunction} callback The callback function.
 */
 const rest = (options, callback) => {
+	/** @type {RestHandlerFunction} */
 	const handler = res => {
 		const chunks = [];
 		res.on('data', chunk => {
@@ -115,6 +116,7 @@ const rest = (options, callback) => {
 	}
 
 	// define request options
+	/** @type {https.RequestOptions} */
 	const opts = {
 		hostname: 'api.github.com',
 		path: apiUrl,
@@ -137,8 +139,8 @@ const rest = (options, callback) => {
  * Github GraphQL API (v4) will be used. Otherwise we rely on the Github Rest API (v3), which
  * does not require authentication.
  *
- * @param options {object} The options for the version check.
- * @param callback {function|undefined} The callback function.
+ * @param {CheckOptions} options The options for the version check.
+ * @param {CallbackFunction} callback The callback function.
  */
 module.exports = (options, callback) => {
 	if (options === null || options === undefined) {

lib/main.js

@@ -4,8 +4,8 @@ const check = require('./check');
 /**
  * The exported checking function.
  *
- * @param options {object} The options for the version check.
- * @param callback {function|undefined} An optional callback to pass the result to.
+ * @param {CheckOptions} options The options for the version check.
+ * @param {CallbackFunction} callback An optional callback to pass the result to.
  *                                      Can be omitted to return a Promise.
  * @return null or a Promise.
  */

lib/query.js

@@ -1,8 +1,8 @@
 /**
  * Query for fetching the latest github release.
  *
- * @param repo {string} The repository name.
- * @param owner {string} The owner of the repository.
+ * @param {string} repo The repository name.
+ * @param {string} owner The owner of the repository.
  */
 module.exports.releases = (repo, owner) => {
 	return `
@@ -27,8 +27,8 @@ module.exports.releases = (repo, owner) => {
 /**
  * Query for fetching the latest git tag.
  *
- * @param repo {string} The repository name.
- * @param owner {string} The owner of the repository.
+ * @param {string} repo The repository name.
+ * @param {string} owner The owner of the repository.
  */
 module.exports.tags = (repo, owner) => {
 	return `

lib/scheme-mapper.js

@@ -1,6 +1,8 @@
 /**
  * Maps a response object into the form described here:
  * https://github.com/axelrindle/github-version-checker/wiki/API#releases
+ * 
+ * @returns {ReleaseDescriptor}
  */
 module.exports.release = obj => {
 	return {
@@ -17,6 +19,8 @@ module.exports.release = obj => {
 /**
  * Maps a response object into the form described here:
  * https://github.com/axelrindle/github-version-checker/wiki/API#tags
+ * 
+ * @returns {TagDescriptor}
  */
 module.exports.tag = obj => {
 	return {

package-lock.json

@@ -3,6 +3,7 @@
   "version": "2.2.0",
   "description": "Version checker working with GitHub releases.",
   "main": "index.js",
+  "types": "index.d.ts",
   "keywords": [
     "version-checker",
     "github-api"
@@ -14,6 +15,7 @@
     "semver": "^5.5.1"
   },
   "devDependencies": {
+    "@types/node": "^14.18.12",
     "ava": "^3.15.0",
     "eslint": "^7.16.0",
     "nyc": "^15.1.0"