Convert directory-tree to TypeScript

.changeset/ts-directory-tree.md

@@ -0,0 +1,7 @@
+---
+'markdown-magic-directory-tree': minor
+---
+
+TypeScript: ship type declarations
+
+Also adds `dist` to the default ignore list so build artifacts never render in the generated tree (this package self-demos DIRTREE on its own README; a docs regen with a locally-built `dist/` present would otherwise diverge from CI, which regenerates before `pnpm -r build` runs).

packages/directory-tree/README.md

@@ -10,14 +10,14 @@ npm i markdown-magic markdown-magic-directory-tree --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 DIRTREE from './index.js';
+import DIRTREE from './index.ts';
 
 const config = {
   matchWord: 'AUTO-GENERATED-CONTENT',
@@ -40,12 +40,14 @@ await markdownMagic(markdownPath, config);
 directory-tree/
 ├── __fixtures__/
 ├── __snapshots__/
-├── example.js
-├── index.js
-├── index.spec.js
+├── example.ts
+├── index.spec.ts
+├── index.ts
 ├── LICENSE
 ├── package.json
-└── README.md
+├── README.md
+├── tsconfig.build.json
+└── types.ts
 ```
 
 <!-- AUTO-GENERATED-CONTENT:END -->

packages/directory-tree/example.js → packages/directory-tree/example.ts

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

packages/directory-tree/index.spec.js → packages/directory-tree/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, 'README.md');
 

packages/directory-tree/index.js → packages/directory-tree/index.ts

@@ -1,57 +1,78 @@
 import path from 'path';
 import archy from 'archy';
 import dirTree from 'directory-tree';
+import type { TransformArgs, TransformOptions } from './types.ts';
 
-const defaults = {
+export type { TransformArgs, TransformOptions } from './types.ts';
+
+interface Defaults {
+  depth: number;
+  dir: string;
+  onlyDirs: boolean;
+}
+
+const defaults: Defaults = {
   depth: Infinity,
   dir: '.',
   onlyDirs: false,
 };
 
-const sortEntries = (a, b) => {
+type DirNode = ReturnType<typeof dirTree>;
+
+const sortEntries = (a: DirNode, b: DirNode): number => {
   if (a.type === 'directory' && b.type !== 'directory') return -1;
   if (a.type !== 'directory' && b.type === 'directory') return 1;
   return a.name.localeCompare(b.name);
 };
 
-const processNode = (node, ignore, options, depth = 0) => {
+const processNode = (
+  node: DirNode,
+  ignore: string[],
+  options: Defaults & TransformOptions,
+  depth = 0,
+): archy.Data | undefined => {
   if (
     ignore.includes(node.name) ||
     depth > options.depth ||
     (options.onlyDirs && node.type !== 'directory')
   )
     return;
 
-  const response = {
+  const response: archy.Data = {
     label: `${node.name}${node.type === 'directory' ? '/' : ''}`,
   };
 
   if (node.type === 'directory' && depth < options.depth) {
     depth++;
-    response.nodes = node.children
+    response.nodes = (node.children ?? [])
       .sort(sortEntries)
       .map((child) => processNode(child, ignore, options, depth))
-      .filter((child) => !!child);
+      .filter((child): child is archy.Data => !!child);
   }
 
   return response;
 };
 
-export default function DIRTREE({ content: _content, options = {}, srcPath }) {
-  const opts = { ...defaults, ...options };
+export default function DIRTREE({
+  content: _content,
+  options = {},
+  srcPath,
+}: TransformArgs): string {
+  const opts: Defaults & TransformOptions = { ...defaults, ...options };
   const dir = path.resolve(path.dirname(srcPath), opts.dir);
   const ignore = opts.ignore || [
     '.git',
     '.gitkeep',
     '.gitignore',
     'node_modules',
     '.DS_Store',
+    'dist',
   ];
   // directory-tree@3 only returns `name`/`path` (+`children`) unless the
   // caller opts in to extra attributes; `type` is required for our
   // directory-vs-file logic (attributes docs: https://github.com/mihneadb/node-directory-tree#options)
   const tree = archy(
-    processNode(dirTree(dir, { attributes: ['type'] }), ignore, opts),
+    processNode(dirTree(dir, { attributes: ['type'] }), ignore, opts)!,
   );
 
   return ['```', tree.trim(), '```'].join('\n');

packages/directory-tree/package.json

@@ -3,9 +3,10 @@
   "version": "2.0.0",
   "description": "Print an archy tree for markdown file",
   "type": "module",
-  "main": "index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./index.js",
+    ".": "./dist/index.js",
     "./package.json": "./package.json"
   },
   "engines": {
@@ -33,8 +34,11 @@
     "plugin"
   ],
   "scripts": {
+    "prebuild": "rm -rf dist",
+    "build": "tsc --project tsconfig.build.json",
+    "prepack": "pnpm build",
     "test": "vitest run",
-    "docs": "node example.js && prettier --write README.md",
+    "docs": "node example.ts && prettier --write README.md",
     "format": "prettier --write ."
   },
   "dependencies": {
@@ -45,11 +49,14 @@
     "markdown-magic": "^4"
   },
   "devDependencies": {
+    "@types/archy": "^0.0.36",
+    "@types/node": "^24.13.2",
     "markdown-magic": "catalog:",
     "prettier": "catalog:",
+    "typescript": "^6.0.3",
     "vitest": "catalog:"
   },
   "files": [
-    "index.js"
+    "dist"
   ]
 }

packages/directory-tree/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/directory-tree/types.ts

@@ -0,0 +1,17 @@
+// 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 directory-tree options.
+export interface TransformOptions {
+  depth?: number;
+  dir?: string;
+  ignore?: string[];
+  onlyDirs?: boolean;
+  [key: string]: unknown;
+}
+
+export interface TransformArgs {
+  content: string;
+  options: TransformOptions;
+  srcPath: string;
+}