Convert install-command to TypeScript

.changeset/ts-install-command.md

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

packages/install-command/README.md

@@ -14,14 +14,14 @@ npm add -D markdown-magic-install-command markdown-magic@^4
 
 ## 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 INSTALLCMD from './index.js';
+import INSTALLCMD from './index.ts';
 
 const config = {
   matchWord: 'AUTO-GENERATED-CONTENT',

packages/install-command/example.js → packages/install-command/example.ts

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

packages/install-command/index.spec.js → packages/install-command/index.spec.ts

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

packages/install-command/index.js → packages/install-command/index.ts

@@ -1,14 +1,17 @@
 import { existsSync, readFileSync } from 'fs';
 import path from 'path';
 import { findUpSync } from 'find-up';
+import type { Client, TransformArgs, TransformOptions } from './types.ts';
+
+export type { Client, TransformArgs, TransformOptions } from './types.ts';
 
 const defaults = {
   flags: '["--save"]',
   peers: true,
   exact: false,
 };
 
-const installMappings = {
+const installMappings: Record<string, Record<Client, string>> = {
   '--global': { npm: '--global', yarn: '', pnpm: '--global', bun: '--global' },
   '--save': { npm: '--save', yarn: '', pnpm: '', bun: '' },
   '--save-exact': {
@@ -31,15 +34,15 @@ const installMappings = {
   },
 };
 
-function quoteSpacesInDep(dep) {
+function quoteSpacesInDep(dep: string): string {
   return dep.includes(' ') ? `"${dep}"` : dep;
 }
 
-function filterFalseyAndJoin(array, join = ' ') {
+function filterFalseyAndJoin(array: unknown[], join = ' '): string {
   return array.filter((v) => !!v).join(join);
 }
 
-function findPkg(dir) {
+function findPkg(dir: string): string {
   const pkgPath = findUpSync('package.json', { cwd: dir });
 
   if (!pkgPath) {
@@ -49,7 +52,7 @@ function findPkg(dir) {
   return pkgPath;
 }
 
-function pickClient(dir) {
+function pickClient(dir: string): Client {
   if (
     existsSync(path.join(dir, 'bun.lock')) ||
     existsSync(path.join(dir, 'bun.lockb'))
@@ -68,7 +71,15 @@ function pickClient(dir) {
   return 'npm';
 }
 
-function buildDeps(pkg, exactFlag, peersFlag) {
+function buildDeps(
+  pkg: {
+    name: string;
+    version: string;
+    peerDependencies?: Record<string, string>;
+  },
+  exactFlag?: boolean,
+  peersFlag?: boolean,
+): string {
   const mainDep = filterFalseyAndJoin(
     [pkg.name, exactFlag ? pkg.version : ''],
     '@',
@@ -79,18 +90,21 @@ function buildDeps(pkg, exactFlag, peersFlag) {
   const pkgPeers = pkg.peerDependencies;
   if (!pkgPeers) return mainDep;
 
-  const peers = Object.keys(pkg.peerDependencies).map(buildDep(pkgPeers));
+  const peers = Object.keys(pkgPeers).map(buildDep(pkgPeers));
 
   return filterFalseyAndJoin([mainDep, ...peers]);
 }
 
-const buildDep = (obj) => (key) => quoteSpacesInDep([key, obj[key]].join('@'));
+const buildDep =
+  (obj: Record<string, string>) =>
+  (key: string): string =>
+    quoteSpacesInDep([key, obj[key]].join('@'));
 
-function buildInstallCmd(client, isGlobal) {
+function buildInstallCmd(client: Client, isGlobal: boolean): string {
   return `${client}${isGlobal && client === 'yarn' ? ' global' : ''} add`;
 }
 
-function buildCmdFlags(client, flags) {
+function buildCmdFlags(client: Client, flags: string[]): string {
   return filterFalseyAndJoin(
     flags.map((flag) => installMappings[flag]?.[client] ?? flag),
   );
@@ -100,11 +114,11 @@ export default function INSTALLCMD({
   content: _content,
   options: _options = {},
   srcPath,
-}) {
-  const options = Object.assign({}, defaults, _options);
-  options.flags = JSON.parse(options.flags);
+}: TransformArgs): string {
+  const options: TransformOptions = Object.assign({}, defaults, _options);
+  const flags: string[] = JSON.parse(options.flags as unknown as string);
 
-  let pkgPath;
+  let pkgPath: string;
 
   if (options.pkg) {
     pkgPath = path.resolve(path.dirname(srcPath), options.pkg);
@@ -116,8 +130,8 @@ export default function INSTALLCMD({
   const client = options.client || pickClient(path.dirname(pkgPath));
 
   const cmd = filterFalseyAndJoin([
-    buildInstallCmd(client, options.flags.includes('--global')),
-    buildCmdFlags(client, options.flags),
+    buildInstallCmd(client, flags.includes('--global')),
+    buildCmdFlags(client, flags),
     buildDeps(pkg, options.exact, options.peers !== 'false'),
   ]);
 

packages/install-command/package.json

@@ -3,17 +3,21 @@
   "version": "3.0.0",
   "description": "Print install command 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": {
     "node": ">=22.18.0"
   },
   "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 ."
   },
   "keywords": [
@@ -25,8 +29,10 @@
   "author": "Patrick Camacho <patrick@daftdevelopers.com>",
   "license": "MIT",
   "devDependencies": {
+    "@types/node": "^24.13.2",
     "markdown-magic": "catalog:",
     "prettier": "catalog:",
+    "typescript": "^6.0.3",
     "vitest": "catalog:"
   },
   "peerDependencies": {
@@ -45,6 +51,6 @@
   },
   "homepage": "https://github.com/camacho/markdown-magic-plugins#readme",
   "files": [
-    "index.js"
+    "dist"
   ]
 }

packages/install-command/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/install-command/types.ts

@@ -0,0 +1,20 @@
+// 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 `pkg`/`client`/`flags`/`peers`/`exact` options.
+export type Client = 'npm' | 'yarn' | 'pnpm' | 'bun';
+
+export interface TransformOptions {
+  pkg?: string;
+  client?: Client;
+  flags?: string;
+  peers?: boolean | string;
+  exact?: boolean;
+  [key: string]: unknown;
+}
+
+export interface TransformArgs {
+  content: string;
+  options: TransformOptions;
+  srcPath: string;
+}