feat: add JSDoc types and TypeScript declaration generation

.changeset/add-jsdoc-types.md

@@ -0,0 +1,5 @@
+---
+"stylus-loader": minor
+---
+
+Added JSDoc type annotations and TypeScript declaration file generation. The package now ships `types/index.d.ts` and exposes types via the package's `exports`/`types` fields.

.github/workflows/nodejs.yml

@@ -51,6 +51,12 @@ jobs:
       - name: Security audit
         run: npm run security
 
+      - name: Build types
+        run: npm run build:types
+
+      - name: Check types
+        run: if [ -n "$(git status types --porcelain)" ]; then echo "Missing types. Update types by running 'npm run build:types'"; exit 1; else echo "All types are valid"; fi
+
   test:
     name: Test - ${{ matrix.os }} - Node v${{ matrix.node-version }}, Webpack ${{ matrix.webpack-version }}
 

README.md

@@ -113,35 +113,32 @@ module.exports = {
             loader: "stylus-loader",
             options: {
               stylusOptions: {
+                // eslint-disable-next-line jsdoc/no-restricted-syntax
                 /**
                  * Specify Stylus plugins to use. Plugins may be passed as
                  * strings instead of importing them in your Webpack config.
-                 *
-                 * @type {(string|Function)[]}
+                 * @type {(string | (renderer: object) => void)[]}
                  * @default []
                  */
                 use: ["nib"],
 
                 /**
                  * Add path(s) to the import lookup paths.
-                 *
                  * @type {string[]}
                  * @default []
                  */
                 include: [path.join(__dirname, "src/styl/config")],
 
                 /**
                  * Import the specified Stylus files/paths.
-                 *
                  * @type {string[]}
                  * @default []
                  */
                 import: ["nib", path.join(__dirname, "src/styl/mixins")],
 
                 /**
                  * Define Stylus variables or functions.
-                 *
-                 * @type {Array|Object}
+                 * @type {[string, string | number | boolean, boolean?] | Record<string, string | number | boolean>}
                  * @default {}
                  */
                 // Array is the recommended syntax: [key, value, raw]
@@ -156,39 +153,32 @@ module.exports = {
                 // },
 
                 /**
-                 * Include regular CSS on @import.
-                 *
+                 * Include regular CSS on \@import.
                  * @type {boolean}
                  * @default false
                  */
                 includeCSS: false,
 
                 /**
                  * Resolve relative url()'s inside imported files.
-                 *
                  * @see https://stylus-lang.com/docs/js.html#stylusresolveroptions
-                 *
-                 * @type {boolean|Object}
+                 * @type {boolean | { nocheck?: boolean, paths?: string[] }}
                  * @default { nocheck: true }
                  */
                 resolveURL: true,
                 // resolveURL: { nocheck: true },
 
                 /**
                  * Emits comments in the generated CSS indicating the corresponding Stylus line.
-                 *
                  * @see https://stylus-lang.com/docs/executable.html
-                 *
                  * @type {boolean}
                  * @default false
                  */
                 lineNumbers: true,
 
                 /**
-                 * Move @import and @charset to the top.
-                 *
+                 * Move \@import and \@charset to the top.
                  * @see https://stylus-lang.com/docs/executable.html
-                 *
                  * @type {boolean}
                  * @default false
                  */
@@ -197,9 +187,7 @@ module.exports = {
                 /**
                  * Compress CSS output.
                  * In the "production" mode is `true` by default
-                 *
                  * @see https://stylus-lang.com/docs/executable.html
-                 *
                  * @type {boolean}
                  * @default false
                  */

bench/fixtures/imports/testLoader.js

@@ -1,3 +1,7 @@
+/**
+ * @param {string} content content
+ * @returns {string} test loader output
+ */
 function testLoader(content) {
   return `export default ${JSON.stringify(content)}`;
 }

bench/index.js

@@ -11,6 +11,10 @@ import importWebpackConfig from "./fixtures/imports/webpack.config.js";
 const __filename = url.fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+/**
+ * @param {(...args: unknown[]) => { on: (event: string, callback: () => void) => void }} fn function returning an emitter that emits "complete"
+ * @returns {(...args: unknown[]) => Promise<void>} a promise-returning function that resolves when "complete" fires
+ */
 function resolveOnComplete(fn) {
   return (...args) => {
     const _this = this;

package.json

@@ -19,6 +19,7 @@
   "type": "module",
   "exports": {
     ".": {
+      "types": "./types/index.d.ts",
       "import": "./dist/esm/index.js",
       "require": "./dist/cjs/index.js",
       "default": "./dist/esm/index.js"
@@ -27,19 +28,23 @@
   },
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
+  "types": "./types/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "types"
   ],
   "scripts": {
-    "clean": "del-cli dist",
+    "clean": "del-cli dist types",
     "prebuild": "npm run clean",
     "build:esm": "babel src -d dist/esm --env-name esm --copy-files --no-copy-ignored",
     "build:cjs": "babel src -d dist/cjs --env-name cjs --copy-files --no-copy-ignored && node -e \"const fs=require('fs');fs.writeFileSync('dist/cjs/package.json','{\\\"type\\\":\\\"commonjs\\\"}\\n');fs.appendFileSync('dist/cjs/index.js','module.exports = exports.default;\\nmodule.exports.default = exports.default;\\n')\"",
+    "build:types": "tsc && prettier \"types/**/*.ts\" --write",
     "build": "npm-run-all -p \"build:*\"",
     "security": "npm audit --production",
     "lint": "npm-run-all -l -p \"lint:**\" && npm run fmt:check",
     "lint:code": "eslint --cache .",
     "lint:spelling": "cspell --cache --no-must-find-files --quiet \"**/*.*\"",
+    "lint:types": "tsc --pretty --noEmit",
     "fmt": "npm run fmt:check -- --write",
     "fmt:check": "prettier --list-different --cache --ignore-unknown .",
     "fix": "npm run fix:code && npm run fmt",
@@ -53,6 +58,7 @@
     "release": "npm run build && changeset publish"
   },
   "dependencies": {
+    "@types/stylus": "^0.48.43",
     "normalize-path": "^3.0.0",
     "tinyglobby": "^0.2.12"
   },
@@ -62,6 +68,8 @@
     "@babel/preset-env": "^7.24.7",
     "@changesets/cli": "^2.30.0",
     "@changesets/get-github-info": "^0.8.0",
+    "@types/node": "^22.19.19",
+    "@types/normalize-path": "^3.0.2",
     "benchmark": "^2.1.4",
     "bootstrap-styl": "^5.0.9",
     "cspell": "^10.0.0",
@@ -79,6 +87,7 @@
     "raw-loader": "^4.0.2",
     "style-loader": "^4.0.0",
     "stylus": "^0.64.0",
+    "typescript": "^6.0.3",
     "webpack": "^5.101.0"
   },
   "peerDependencies": {