Convert subpackage-list to TypeScript

.changeset/ts-subpackage-list.md

@@ -0,0 +1,5 @@
+---
+'markdown-magic-subpackage-list': minor
+---
+
+TypeScript: ship type declarations

packages/subpackage-list/README.md

@@ -10,14 +10,14 @@ npm i markdown-magic markdown-magic-subpackage-list --save-dev
 
 ## Adding the plugin
 
-See `example.js` for usage.
+See `example.ts` for usage.
 
-<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./example.js) -->
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./example.ts) -->
 
-```js
+```ts
 import path from 'path';
 import { markdownMagic } from 'markdown-magic';
-import SUBPACKAGELIST from './index.js';
+import SUBPACKAGELIST from './index.ts';
 
 const config = {
   matchWord: 'AUTO-GENERATED-CONTENT',

packages/subpackage-list/example.js → packages/subpackage-list/example.ts

@@ -1,6 +1,6 @@
 import path from 'path';
 import { markdownMagic } from 'markdown-magic';
-import SUBPACKAGELIST from './index.js';
+import SUBPACKAGELIST from './index.ts';
 
 const config = {
   matchWord: 'AUTO-GENERATED-CONTENT',

packages/subpackage-list/index.spec.js → packages/subpackage-list/index.spec.ts

@@ -1,6 +1,6 @@
 import path from 'path';
 import { describe, expect, it } from 'vitest';
-import format from './index.js';
+import format from './index.ts';
 
 const srcPath = path.join(import.meta.dirname, '__fixtures__', 'README.md');
 

packages/subpackage-list/index.js → packages/subpackage-list/index.ts

@@ -1,18 +1,30 @@
 import fs from 'fs';
 import path from 'path';
+import type {
+  PackageManifest,
+  TransformArgs,
+  TransformOptions,
+} from './types.ts';
 
-const defaults = {
-  dir: './packages',
-  verbose: false,
-  bullet: '*',
-};
+export type {
+  PackageManifest,
+  TransformArgs,
+  TransformOptions,
+} from './types.ts';
+
+const defaults: Required<Pick<TransformOptions, 'dir' | 'verbose' | 'bullet'>> =
+  {
+    dir: './packages',
+    verbose: false,
+    bullet: '*',
+  };
 
 export default function SUBPACKAGELIST({
   content: _content,
   options = {},
   srcPath,
-}) {
-  const opts = Object.assign({}, defaults, options);
+}: TransformArgs): string {
+  const opts = Object.assign({}, defaults, options) as typeof defaults;
 
   const packagesDir = path.resolve(path.dirname(srcPath), opts.dir);
 
@@ -21,7 +33,7 @@ export default function SUBPACKAGELIST({
     .map((filename) => path.join(packagesDir, filename))
     .filter((filePath) => fs.statSync(filePath).isDirectory())
     .filter((dirPath) => fs.existsSync(path.join(dirPath, 'package.json')))
-    .map((dirPath) => [
+    .map((dirPath): [string, PackageManifest] => [
       path.relative(path.dirname(srcPath), dirPath),
       JSON.parse(fs.readFileSync(path.join(dirPath, 'package.json'), 'utf8')),
     ])

packages/subpackage-list/package.json

@@ -3,7 +3,23 @@
   "version": "2.0.0",
   "description": "Print a list of subpackages for markdown file",
   "type": "module",
-  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "prebuild": "rm -rf dist",
+    "build": "tsc --project tsconfig.build.json",
+    "prepack": "pnpm build",
+    "test": "vitest run",
+    "docs": "node example.ts && prettier --write README.md",
+    "format": "prettier --write ."
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/camacho/markdown-magic-plugins.git",
@@ -21,28 +37,18 @@
     "list",
     "plugin"
   ],
-  "main": "index.js",
-  "exports": {
-    ".": "./index.js",
-    "./package.json": "./package.json"
-  },
-  "engines": {
-    "node": ">=22.18.0"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "docs": "node example.js && prettier --write README.md",
-    "format": "prettier --write ."
-  },
-  "peerDependencies": {
-    "markdown-magic": "^4"
-  },
+  "license": "MIT",
   "devDependencies": {
+    "@types/node": "^24.13.2",
     "markdown-magic": "catalog:",
     "prettier": "catalog:",
+    "typescript": "^6.0.3",
     "vitest": "catalog:"
   },
+  "peerDependencies": {
+    "markdown-magic": "^4"
+  },
   "files": [
-    "index.js"
+    "dist"
   ]
 }

packages/subpackage-list/tsconfig.build.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "outDir": "dist",
+    "rootDir": ".",
+    "types": ["node"]
+  },
+  "exclude": [
+    "node_modules",
+    "dist",
+    "*.spec.ts",
+    "example.ts",
+    "__fixtures__",
+    "__snapshots__"
+  ],
+  "include": ["*.ts"]
+}

packages/subpackage-list/types.ts

@@ -0,0 +1,23 @@
+// Transform interface shared by markdown-magic plugins. Adapted from
+// format-package's scripts/markdown-transformers.ts TransformArgs/TransformOptions
+// (content: unknown -> content: string, the plugins' actual contract), plus
+// this package's own `dir`/`verbose`/`bullet` options.
+export interface TransformOptions {
+  dir?: string;
+  verbose?: boolean | string;
+  bullet?: string;
+  [key: string]: unknown;
+}
+
+export interface TransformArgs {
+  content: string;
+  options: TransformOptions;
+  srcPath: string;
+}
+
+// Minimal shape of a package.json manifest as read from disk for each
+// discovered subpackage.
+export interface PackageManifest {
+  name: string;
+  description?: string;
+}