introduce api-extractor for typings rollup

.eslintrc.json

@@ -19,7 +19,7 @@
     "no-process-exit": "error",
     "no-loop-func": "error",
     "no-console": "off",
-    "valid-jsdoc": "error",
+    "valid-jsdoc": "off",
     "no-var": "error",
     "prefer-const": "error",
     "prefer-arrow-callback": "error",

.gitignore

@@ -1,4 +1,5 @@
 .idea
 node_modules
 coverage
-/dist
+/dist
+/temp

etc/loader-utils.api.md

@@ -0,0 +1,29 @@
+## API Report File for "loader-utils"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+/// <reference types="node" />
+
+import type { LoaderContext } from 'webpack';
+
+// Warning: (ae-forgotten-export) The symbol "DigestType" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+export function getHashDigest(buffer: Buffer, algorithm: string | "xxhash64" | "md4" | "native-md4", digestType: DigestType | string, maxLength: number): any;
+
+// Warning: (ae-forgotten-export) The symbol "IInterpolateNameOptions" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function interpolateName(loaderContext: LoaderContext<object>, name: string | ((resourcePath: string, resourceQuery?: string) => string), options?: IInterpolateNameOptions): string;
+
+// @public
+export function isUrlRequest(url: string): boolean;
+
+// @public
+export function urlToRequest(url: string, root?: string | boolean): string;
+
+// (No @packageDocumentation comment for this package)
+
+```

lib/getHashDigest.ts

@@ -67,6 +67,14 @@ let createMd4: typeof import("./hash/md4").create;
 let BatchedHash: typeof import("./hash/BatchedHash").BatchedHash;
 let BulkUpdateDecorator: typeof import("./hash/BulkUpdateDecorator").BulkUpdateDecorator;
 
+/**
+ * @public
+ *
+ * @param buffer - This represents the content that should be hashed
+ * @param hashType - The algorithm to use to hash the content. Can be one of `xxhash64`, `md4`, `native-md4` or any other hash algorithm supported by node.js `crypto` module.
+ * @param digestType - The encoding to use for the hash. Can be one of `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62` or `base64`.
+ * @param maxLength - The maximum length of the resulting hash. Defaults to `9999`.
+ */
 export default function getHashDigest(
   buffer: Buffer,
   algorithm: string | "xxhash64" | "md4" | "native-md4",

lib/interpolateName.ts

@@ -8,6 +8,15 @@ interface IInterpolateNameOptions {
   regExp?: string;
 }
 
+/**
+ * Interpolates a filename template using multiple placeholders and/or regular expressions.
+ * The template and regular expression are set as query params called `name` and `regExp` on the current loader's context.
+ *
+ * @param loaderContext - The loader context from webpack which is provided via `this` inside of a loader.
+ * @param name - The name of the string to transform/interpolate on. This can be a string or a function (providing the loader contexts resourcePath and resourceQuery) that returns a string.
+ * @param options - An object containing the following properties: `context`, `content`, `regExp`.
+ * @public
+ */
 export default function interpolateName(
   loaderContext: LoaderContext<object>,
   name: string | ((resourcePath: string, resourceQuery?: string) => string),

lib/isUrlRequest.ts

@@ -5,6 +5,24 @@ const ABOSLUTE_URL_NON_WINDOWS_PATHLIKE_REGEXP = /^[a-z][a-z0-9+.-]*:/i;
 const POROTCOL_RELATIVE_REGEXP = /^\/\//i;
 const URL_FOR_TEMPLATE_REGEXP = /^#/i;
 
+/**
+ * Utility method for ensuring if a string is a requestable URL
+ * @remarks
+ * You typically want to call `isUrlRequest()` before using the `urlToRequest()` function
+ * @example
+ * ```js
+ * const url = "path/to/module.js"
+ * if (loaderUtils.isUrlRequest(url)) {
+ * // Logic for requestable url
+ * const request = loaderUtils.urlToRequest(url);
+ * } else {
+ * // Logic for non-requestable url
+ * }
+ * ```
+ *
+ * @param url - The url to check
+ * @public
+ */
 export default function isUrlRequest(url: string): boolean {
   // An URL is not an request if
 

lib/urlToRequest.ts

@@ -4,6 +4,49 @@ const MODULE_REQUEST_REGEXP = /^[^?]*~/;
 const ROOT_RELATIVE_URL_REGEXP = /^\//;
 const TILDE_ROOTS_MODULE_REQUEST_REGEXP = /([^~/])$/;
 
+/**
+ * Converts some resource URL into a webpack module request
+ *
+ * @example
+ * A simple example:
+ * ```js
+ * const url = "path/to/module.js"
+ * const request = loaderUtils.urlToRequest(url);
+ * // request === "./path/to/module.js"
+ * ```
+ *
+ * @remarks
+ * ### Module URLs
+ *
+ * @example
+ * Any URL containing a `~` will be interpreted as a module request. Anything after the `~` will be considered the request path:
+ * ```js
+ * const url = "~/path/to/module.js"
+ * const request = loaderUtils.urlToRequest(url);
+ * // request === "path/to/module.js"
+ * ```
+ *
+ * @remarks
+ * ### Root-relative URLs
+ *
+ * @example
+ * URLs that are root-relative (start with `/`) can be resolved relative to some arbitrary path by using the root parameter:
+ * ```js
+ * const url = "/path/to/module.js"
+ * const request = loaderUtils.urlToRequest(url, "./root");
+ * // request === "./root/path/to/module.js"
+ * ```
+ *
+ * @example
+ * To convert a root-relative URL into a module URL, specify a root value that starts with `~`:
+ * ```js
+ * const url = "/path/to/module.js"
+ * const request = loaderUtils.urlToRequest(url, "~");
+ * // request === "path/to/module.js"
+ * ```
+ *
+ * @public
+ */
 export default function urlToRequest(
   url: string,
   root?: string | boolean

package.json

@@ -7,7 +7,8 @@
   "scripts": {
     "lint": "prettier --list-different . && eslint ./lib",
     "pretty": "prettier --write .",
-    "build": "tsc",
+    "type-rollup": "api-extractor run --local",
+    "build": "tsc && yarn type-rollup",
     "pretest": "yarn lint",
     "test": "jest",
     "test:only": "jest --coverage",
@@ -23,6 +24,7 @@
     "node": ">= 12.13.0"
   },
   "devDependencies": {
+    "@microsoft/api-extractor": "^7.33.7",
     "@typescript-eslint/eslint-plugin": "^5.47.0",
     "@typescript-eslint/parser": "^5.47.0",
     "coveralls": "^3.1.1",

tsconfig.json

@@ -6,7 +6,9 @@
     "outDir": "dist",
     "strict": true,
     "types": ["node"],
-    "esModuleInterop": true
+    "esModuleInterop": true,
+    "declaration": true,
+    "declarationMap": true
   },
   "include": ["lib/**/*.ts"]
 }