feat: replace old programmatic API with one matching the CLI commands

.changeset/polite-plants-destroy.md

@@ -0,0 +1,5 @@
+---
+'clean-modules': major
+---
+
+**BREAKING** Replace old programmatic API with one that better correspond to the CLI commands. See the README for information on how to import them.

README.md

@@ -14,6 +14,7 @@
 - 📁 Cleans up empty directories after removing files
 - ⚡️ Super fast, but still written in Node
 - 🔍 Allows analyzing results, like which pattern excluded which file
+- 🧑‍💻 Supports both CLI and programmatic usage
 
 <p align="center">
   <img alt="Small project" title="Small project" src="images/small-project.png" width="240" />
@@ -25,8 +26,8 @@
 
 <details><summary>Click to open</summary>
 
-- [Installation](#installation)
 - [Quick start](#quick-start)
+- [Installation](#installation)
 - [Commands](#commands)
   - [`clean-modules clean` (default command) 🧹](#clean-modules-clean-default-command-)
     - [Usage](#usage)
@@ -49,6 +50,7 @@
   - [Default globs](#default-globs)
     - [Common extra inclusions](#common-extra-inclusions)
     - [Common extra exclusions](#common-extra-exclusions)
+- [Programmatic usage](#programmatic-usage)
 - [Alternatives](#alternatives)
   - [Comparisons](#comparisons)
     - [clean-modules (this project)](#clean-modules-this-project)
@@ -57,7 +59,6 @@
     - [node-prune](#node-prune)
     - [nm-prune](#nm-prune)
 
-
 </details>
 
 ## Quick start
@@ -296,6 +297,34 @@ custom exclusions depending on what packages you use.
   `clean-modules` removes sourcemap files by default since they take up a lot of space and does not
   break builds when removed. They can be nice to have though, especially while developing.
 
+## Programmatic usage
+
+Clean modules can be used programmatically too!
+
+Simply import the corresponding function from the package:
+
+````ts
+import { clean, analyze } from 'clean-modules';
+
+// analyze, all options are optional
+const analyzeResult = await analyze({
+  directory: '/path/to/node_modules',
+  globFile: '/path/to/.cleanmodules',
+  globs: ['**/*.js'],
+  noDefaults: false,
+});
+
+// clean, all options are optional
+const cleanResult = await clean({
+  directory: '/path/to/node_modules',
+  globFile: '/path/to/.cleanmodules',
+  globs: ['**/*.js'],
+  noDefaults: false,
+  keepEmpty: false,
+  dryRun: false,
+});
+````
+
 ## Alternatives
 
 The most common issues I found with available tools are:

__mocks__/fs/index.ts

@@ -1,3 +1,3 @@
 import { fs } from 'memfs';
 
-module.exports = fs
+module.exports = fs;

src/__test__/absolutePathSnapshotSerializer.ts

@@ -0,0 +1,16 @@
+import { expect } from 'vitest';
+
+export function enableAbsolutePathSnapshotSerializer(cwd: string = process.cwd()) {
+  const cwdRegex = new RegExp(cwd, 'g');
+
+  expect.addSnapshotSerializer({
+    serialize(val, config, indentation, depth, refs, printer) {
+      const snapshot = printer(val, config, indentation, depth, refs);
+      return snapshot.replace(cwdRegex, '/absolute-test-path');
+    },
+    test(val) {
+      const containsAbsolutePath = cwdRegex.test(JSON.stringify(val));
+      return containsAbsolutePath;
+    },
+  });
+}

src/__test__/getMockedFileStructure.ts

@@ -1,14 +1,14 @@
 import fs from 'fs';
 import { vi } from 'vitest';
-import { DEFAULT_GLOBS_FILE_PATH } from '../constants.js';
+import { DEFAULT_GLOBS_FILE_PATH } from '../shared.js';
 
 export async function getMockedFileStructure(): Promise<Record<string, any>> {
   const actualFs = await vi.importActual<typeof fs.promises>('fs/promises');
   const defaultGlobs = (await actualFs.readFile(DEFAULT_GLOBS_FILE_PATH)).toString();
 
   return {
     [DEFAULT_GLOBS_FILE_PATH]: defaultGlobs,
-    node_modules: {
+    'node_modules': {
       dep1: {
         __tests__: {
           'test1.js': '.',