fix: include type definitions (#186)

* fix: include type definitions

* chore: turn off no-unused-vars for the sink base class

We want them for JSDoc

.editorconfig

@@ -0,0 +1,11 @@
+; http://editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/workflows/publish.yml

@@ -3,7 +3,7 @@ name: Release and Publish
 on:
   push:
     branches:
-      - master
+      - main
       - alpha
       - beta
       - next
@@ -26,6 +26,9 @@ jobs:
       - name: Lint files
         run: npm run lint
 
+      - name: Generate type definitions
+        run: npm run types
+
       - name: Run tests
         run: npm run test
 

.github/workflows/test.yml

@@ -3,7 +3,7 @@ name: Run Lint and Tests
 on:
   push:
     branches-ignore:
-      - master
+      - main
       - alpha
       - beta
       - next
@@ -28,4 +28,6 @@ jobs:
 
       - run: npm run lint
 
+      - run: npm run types
+
       - run: npm test

.gitignore

@@ -13,4 +13,5 @@ tmp/**/*
 coverage
 .vscode
 .nyc_output/
-.tap/
+.tap/
+types/

.npmrc

@@ -1 +1,2 @@
 package-lock=false
+save-exact=true

.prettierrc → .prettierrc.json

@@ -4,7 +4,7 @@
   "tabWidth": 4,
   "overrides": [
     {
-      "files": [".prettierrc", "*.json", "*.yml", ".travis.yml", ".eslintrc"],
+      "files": ["*.json", "*.yml"],
       "options": {
         "tabWidth": 2
       }

eslint.config.js

@@ -0,0 +1,22 @@
+import prettierConfig from 'eslint-config-prettier';
+import prettierPlugin from 'eslint-plugin-prettier/recommended';
+import globals from 'globals';
+import js from '@eslint/js';
+
+export default [
+    js.configs.recommended,
+    prettierConfig,
+    prettierPlugin,
+    {
+        languageOptions: {
+            globals: {
+                ...globals.node,
+                ...globals.browser,
+                global: true,
+            },
+        },
+    },
+    {
+        ignores: ['coverage/*', 'dist/*'],
+    },
+];

lib/main.js

@@ -1,38 +1,75 @@
-const Sink = class Sink {
-    write() {
+/* eslint-disable no-unused-vars */
+export default class Sink {
+    /**
+     * @template [T=unknown]
+     * @param {string} filePath Path to the file to be stored.
+     * @param {string} contentType The content type of the file (ex `application/javascript`).
+     * @returns {T | Promise<T>}
+     */
+    write(filePath, contentType) {
         throw new Error('.write method is not implemented');
     }
 
-    read() {
+    /**
+     * @template [T=unknown]
+     * @param {string} filePath
+     * @returns {T | Promise<T>}
+     */
+    read(filePath) {
         throw new Error('.read method is not implemented');
     }
 
-    delete() {
+    /**
+     * @template [T=unknown]
+     * @param {string} filePath
+     * @returns {T | Promise<T>}
+     */
+    delete(filePath) {
         throw new Error('.delete method is not implemented');
     }
 
-    exist() {
+    /**
+     * @template [T=unknown]
+     * @param {string} filePath
+     * @returns {T | Promise<T>}
+     */
+    exist(filePath) {
         throw new Error('.exist method is not implemented');
     }
 
     get metrics() {
         throw new Error('.metrics getter is not implemented');
     }
 
+    /**
+     * Validates {@link filePath} and returns it.
+     * @param {string} filePath
+     * @throws {TypeError} if validation fails
+     * @returns {string}
+     */
     static validateFilePath(filePath) {
-        if (typeof filePath !== 'string') throw new TypeError('Argument must be a String');
-        if (filePath === '') throw new TypeError('Argument can not be an empty String');
+        if (typeof filePath !== 'string')
+            throw new TypeError('Argument must be a String');
+        if (filePath === '')
+            throw new TypeError('Argument can not be an empty String');
         return filePath;
     }
 
+    /**
+     * Validates {@link contentType} and returns it.
+     * @param {string} contentType
+     * @throws {TypeError} if validation fails
+     * @returns {string}
+     */
     static validateContentType(contentType) {
-        if (typeof contentType !== 'string') throw new TypeError('Argument must be a String');
-        if (contentType === '') throw new TypeError('Argument can not be an empty String');
+        if (typeof contentType !== 'string')
+            throw new TypeError('Argument must be a String');
+        if (contentType === '')
+            throw new TypeError('Argument can not be an empty String');
         return contentType;
     }
 
     get [Symbol.toStringTag]() {
         return 'Sink';
     }
-};
-export default Sink;
+}

package.json

@@ -3,17 +3,22 @@
   "version": "1.2.1",
   "description": "A Sink interface",
   "main": "lib/main.js",
+  "types": "types/main.d.ts",
   "type": "module",
   "files": [
     "CHANGELOG.md",
     "package.json",
     "README.md",
-    "lib"
+    "lib",
+    "types"
   ],
   "scripts": {
-    "test": "tap --disable-coverage --allow-empty-coverage test/**/*.js",
+    "lint": "eslint .",
     "lint:fix": "eslint --fix .",
-    "lint": "eslint ."
+    "test": "run-s test:*",
+    "test:unit": "tap --disable-coverage --allow-empty-coverage tests/**/*.js",
+    "test:types": "tsc --project tsconfig.test.json",
+    "types": "tsc --declaration --emitDeclarationOnly"
   },
   "repository": {
     "type": "git",
@@ -29,13 +34,14 @@
     "@babel/eslint-parser": "7.24.7",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/git": "10.0.1",
-    "eslint": "8.57.0",
-    "eslint-config-airbnb-base": "15.0.0",
+    "eslint": "9.1.1",
     "eslint-config-prettier": "9.1.0",
-    "eslint-plugin-import": "2.29.1",
     "eslint-plugin-prettier": "5.1.3",
+    "globals": "15.0.0",
+    "npm-run-all": "4.1.5",
     "prettier": "3.3.2",
     "semantic-release": "24.0.0",
-    "tap": "18.8.0"
+    "tap": "18.8.0",
+    "typescript": "5.5.4"
   }
 }

release.config.cjs

@@ -1,15 +1,21 @@
 module.exports = {
-    "plugins": [
-      "@semantic-release/commit-analyzer",
-      "@semantic-release/release-notes-generator",
-      "@semantic-release/changelog",
-      ["@semantic-release/npm", {
-        "tarballDir": "release"
-      }],
-      ["@semantic-release/github", {
-        "assets": "release/*.tgz"
-      }],
-      "@semantic-release/git"
+    plugins: [
+        '@semantic-release/commit-analyzer',
+        '@semantic-release/release-notes-generator',
+        '@semantic-release/changelog',
+        [
+            '@semantic-release/npm',
+            {
+                tarballDir: 'release',
+            },
+        ],
+        [
+            '@semantic-release/github',
+            {
+                assets: 'release/*.tgz',
+            },
+        ],
+        '@semantic-release/git',
     ],
-    "preset": "angular"
-}
+    preset: 'angular',
+};