Move to TypeScript

.github/workflows/npm-publish.yml

@@ -27,6 +27,8 @@ jobs:
         run: rm -rf docs CHANGELOG.md
       - name: Install Dependencies
         run: yarn --immutable
+      - name: Build
+        run: yarn build
       - name: Publish
         run: yarn npm publish
         env:

.github/workflows/test.yml → .github/workflows/test-and-build.yml

@@ -1,7 +1,7 @@
 # This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
 # For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
 
-name: Run Tests
+name: Run Tests + Build
 
 on:
   push:
@@ -10,6 +10,17 @@ on:
     branches: ["main"]
 
 jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x" # needs to be the same version as when publishing
+          cache: "yarn"
+      - run: yarn
+      - run: yarn build
   test:
     strategy:
       matrix:
@@ -25,3 +36,4 @@ jobs:
           cache: "yarn"
       - run: yarn
       - run: yarn test
+

.gitignore

@@ -6,3 +6,4 @@ oldtest.mjs
 !.yarn/releases
 !.yarn/plugins
 .pnp.*
+dist

package.json

@@ -9,14 +9,11 @@
     "relative links"
   ],
   "homepage": "https://github.com/vernak2539/astro-rehype-relative-markdown-links",
-  "main": "./src/index.mjs",
   "type": "module",
-  "types": "./src/index.d.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "files": [
-    "src/index.mjs",
-    "src/utils.mjs",
-    "src/options.mjs",
-    "src/**/*.d.ts"
+    "dist"
   ],
   "repository": {
     "type": "git",
@@ -30,10 +27,10 @@
   },
   "packageManager": "[email protected]",
   "scripts": {
-    "pre-release": "yarn run changelog && yarn run prettier && yarn run generate-docs",
+    "build": "tsup",
     "generate-docs": "typedoc",
     "prettier": "prettier ./src/** -w",
-    "test": "ARRML_MATTER_CACHE_DISABLE=true node --loader=esmock --test",
+    "test": "ARRML_MATTER_CACHE_DISABLE=true node --import tsx --loader=esmock --test src/**/*.test.ts",
     "type-check": "tsc --noEmit --emitDeclarationOnly false",
     "prepare": "husky"
   },
@@ -59,9 +56,12 @@
     "prettier": "^4.0.0-alpha.8",
     "rehype": "^13.0.2",
     "remark-toc": "^9.0.0",
-    "typedoc": "^0.27.4",
-    "typedoc-plugin-markdown": "^4.3.2",
-    "typedoc-plugin-remark": "^1.2.0",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typedoc": "^0.27.5",
+    "typedoc-plugin-markdown": "^4.3.3",
+    "typedoc-plugin-remark": "^1.2.1",
+    "typedoc-plugin-zod": "^1.3.1",
     "typescript": "^5.7.2"
   }
 }

src/index.ts

@@ -0,0 +1,4 @@
+import astroRehypeRelativeMarkdownLinks from "./plugin";
+
+export type { Options, CollectionConfig } from "./options";
+export default astroRehypeRelativeMarkdownLinks;

src/options.test.mjs → src/options.test.ts

@@ -1,12 +1,15 @@
 import { describe, test } from "node:test";
-import { mergeCollectionOptions, validateOptions } from "./options.mjs";
+import {
+  mergeCollectionOptions,
+  type Options,
+  type CollectionConfig,
+  validateOptions,
+} from "./options";
 import assert from "node:assert";
 
-/** @type {import('./options.d.ts').CollectionConfig} */
-const defaultCollectionConfig = {};
+const defaultCollectionConfig: CollectionConfig = {};
 
-/** @type {import('./options.d.ts').Options} */
-const defaultOptions = {
+const defaultOptions: Options = {
   srcDir: "./src",
   trailingSlash: "ignore",
   collectionBase: "name",

src/options.mjs → src/options.ts

@@ -112,8 +112,21 @@ export const OptionsSchema = z.object({
     .default("ignore"),
 });
 
-/** @type {import('./options.d.ts').ValidateOptions} */
-export const validateOptions = (options) => {
+/** Collection specific options */
+export interface CollectionConfig extends z.input<CollectionConfigSchemaType> {}
+type CollectionConfigSchemaType = typeof CollectionConfigSchema;
+
+/** General options */
+export type Options = z.infer<typeof OptionsSchema>;
+interface EffectiveOptions extends Options {}
+export interface EffectiveCollectionOptions
+  extends Omit<EffectiveOptions, "collections"> {
+  collectionName: string;
+}
+
+export const validateOptions = (
+  options: Options | null | undefined
+): EffectiveOptions => {
   const result = OptionsSchema.safeParse(options || {});
   if (!result.success) {
     throw result.error;
@@ -122,8 +135,10 @@ export const validateOptions = (options) => {
   return result.data;
 };
 
-/** @type {import('./options.d.ts').MergeCollectionOptions} */
-export const mergeCollectionOptions = (collectionName, options) => {
+export const mergeCollectionOptions = (
+  collectionName: string,
+  options: EffectiveOptions
+): EffectiveCollectionOptions => {
   const config = options.collections[collectionName] || {};
   const { base = options.collectionBase, name = collectionName } = config;
   return {

src/index.test.mjs → src/plugin.test.ts

@@ -5,18 +5,18 @@ import path, { dirname } from "path";
 import { rehype } from "rehype";
 import { visit } from "unist-util-visit";
 import esmock from "esmock";
-import { validateOptions as validateOptionsOriginal } from "./options.mjs";
+import { validateOptions as validateOptionsOriginal } from "./options";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-import astroRehypeRelativeMarkdownLinks from "./index.mjs";
+import astroRehypeRelativeMarkdownLinks from "./plugin";
 
 /*
   NOTE ON ESMOCK USAGE
 
   node:test does not provide a stock way of mocking sub-modules.  There is work being done on this (see
-  links below) but for now some type of module loader is required.  Esmock (https://github.com/iambumblehead/esmock) 
+  links below) but for now some type of module loader is required.  Esmock (https://github.com/iambumblehead/esmock)
   seems to address what is needed for our use cases for now although there doesn't seem to be a simple way for a simple spy
   as you need to swap in the original manually.  If/When node:test supports this natively, esmock can be removed.
 
@@ -418,10 +418,10 @@ describe("astroRehypeRelativeMarkdownLinks", () => {
   });
 
   describe("config option validation", () => {
-    const runValidationTest = async (context, options) => {
+    const runValidationTest = async (context, options?) => {
       const validateOptionsMock = context.mock.fn(validateOptionsOriginal);
-      const astroRehypeRelativeMarkdownLinksMock = await esmock("./index.mjs", {
-        "./options.mjs": {
+      const astroRehypeRelativeMarkdownLinksMock = await esmock("./plugin.ts", {
+        "./options.ts": {
           validateOptions: validateOptionsMock,
         },
       });

src/index.mjs → src/plugin.ts

@@ -1,6 +1,8 @@
 import { visit } from "unist-util-visit";
 import * as path from "path";
 import { default as debugFn } from "debug";
+import type { Plugin } from "unified";
+import type { Root } from "hast";
 import {
   replaceExt,
   isValidRelativeLink,
@@ -16,17 +18,24 @@ import {
   shouldProcessFile,
   getMatter,
   resolveCollectionBase,
-} from "./utils.mjs";
-import { validateOptions, mergeCollectionOptions } from "./options.mjs";
+} from "./utils";
+import {
+  type Options,
+  validateOptions,
+  mergeCollectionOptions,
+} from "./options";
 
 // This package makes a lot of assumptions based on it being used with Astro
 
 const debug = debugFn("astro-rehype-relative-markdown-links");
 
 /**
- * @type {import('unified').Plugin<[(import('./options.d.ts').Options | null | undefined)?], import('hast').Root>}
+ * Rehype plugin for Astro to add support for transforming relative links in MD and MDX files into their final page paths.
  */
-function astroRehypeRelativeMarkdownLinks(opts) {
+const astroRehypeRelativeMarkdownLinks: Plugin<
+  [(Options | null | undefined)?],
+  Root
+> = (opts) => {
   const options = validateOptions(opts);
 
   return (tree, file) => {
@@ -71,23 +80,23 @@ function astroRehypeRelativeMarkdownLinks(opts) {
         content collections.
 
         Given this, the default behavior we follow is to to derive the the collection name from physical name of the collection
-        directory on disk and include it in the generated path.  Since we don't have internal info, we have to make an assumption 
-        that the site page path is mapped directly to a path that starts with the collection name followed by the slug of the content 
-        collection page.  We do this by following Astro's own assumptions on the directory structure of content collections - they 
+        directory on disk and include it in the generated path.  Since we don't have internal info, we have to make an assumption
+        that the site page path is mapped directly to a path that starts with the collection name followed by the slug of the content
+        collection page.  We do this by following Astro's own assumptions on the directory structure of content collections - they
         are subdirectories of content path.
 
         We make a couple of exceptions to the above based on options specified:
 
         1. By default, we derive the name of the collection from the physical name of the content collection directory, however when
            options.<collectionname>.name is specified, we use that value instead for the name of the collection.
         2. When the effective `collectionBase` (options.collectionBase or options.collections.<collectionname>.base
-           is `false`), we treat the content collection as the site root so we do not include the effective content collection 
-           name in the transformed url.  For example, with a content collection page of of src/content/docs/page-1.md, if the 
+           is `false`), we treat the content collection as the site root so we do not include the effective content collection
+           name in the transformed url.  For example, with a content collection page of of src/content/docs/page-1.md, if the
            effective collectionBase is `false`, the url would be `/page-1` whereas with effective collectionBase of `name`, it would be `/docs/page-1`.
 
         KNOWN LIMITATIONS/ISSUES
         - Astro allows mapping a content collection to multiple site paths (as mentioned above).  The current approach of this library
-        assumes that page paths always align 1:1 to their corresponding content collection paths based on physical directory name (or custom slug).  
+        assumes that page paths always align 1:1 to their corresponding content collection paths based on physical directory name (or custom slug).
         For example, if you have a content collection at src/content/blogs but your site page path is at /pages/my-blog/[...slug].astro and you have not
         overridden the collection name to `my-blog` via options.<collectionname>.name, the default functionality of this library will not work currently.
         Note, that even when overridden via options, if you map multiple page paths to the same collection (e.g., /pages/my-blog/[...slug].astro &
@@ -197,6 +206,6 @@ function astroRehypeRelativeMarkdownLinks(opts) {
       node.properties.href = webPathFinal;
     });
   };
-}
+};
 
 export default astroRehypeRelativeMarkdownLinks;

src/utils.test.mjs → src/utils.test.ts

@@ -11,7 +11,7 @@ import {
   resolveSlug,
   applyTrailingSlash,
   resolveCollectionBase,
-} from "./utils.mjs";
+} from "./utils";
 
 describe("replaceExt", () => {
   test("replaces extension with another extension", () => {