NPKill API

January 25, 2026 · View on GitHub

This document does not include all project documentation at this stage. It brings together the basic concepts. For more details see the project interfaces.

Interface: Npkill

The core of the system is the NpkillInterface. It offers methods to:

  • Scan folders recursively.
  • Get metadata about folders (size, last modified).
  • Perform safe deletions.
  • Stream logs and validate folders.

startScan$(rootPath, options?)

Starts a recursive scan from a given root folder.

  • Parameters:

    • rootPath: string — Folder to start scanning from.
    • options: ScanOptions — Optional scan configuration.

  • Returns: Observable<ScanFoundFolder>

  • Description: Emits each matching folder as it's found.

stopScan()

Stops any ongoing scan and releases resources.

getSize$(path, options?)

Returns the total size of a directory.

  • Parameters:

  • Returns: Observable<GetSizeResult>

getNewestFile$(path)

Gets the most recently modified file inside a directory (recursively).

  • Parameters:

    • path: string

  • Returns: Observable<GetNewestFileResult | null>

delete$(path, options?)

Deletes a folder, optionally as a dry-run. Only allowed if the folder is within the target of the initial scan.

  • Parameters:

  • Returns: Observable<DeleteResult>

  • Throws: If the path is outside the original target.

getLogs$()

Streams internal log entries.

  • Returns: Observable<LogEntry[]>

isValidRootFolder(path)

Validates whether a folder is suitable for scanning.

getVersion()

Returns the current version of npkill from package.json.

  • Returns: string

Interfaces & Types

ScanOptions

interface ScanOptions {
  targets: string[];
  exclude?: string[];
  sortBy?: 'path' | 'size' | 'age';
  performRiskAnalysis?: boolean; // Default: true
}

ScanFoundFolder

interface ScanFoundFolder {
  path: string;
  riskAnalysis?: RiskAnalysis;
}

RiskAnalysis

Determines whether a result is safe to delete. That is, if it is likely to belong to some application and deleting it could break it.

interface RiskAnalysis {
  isSensitive: boolean;
  reason?: string;
}

GetSizeOptions

interface GetSizeOptions {
  unit?: 'bytes'; // Default: 'bytes'
}

GetSizeResult

interface GetSizeResult {
  size: number;
  unit: 'bytes';
}

GetNewestFileResult

interface GetNewestFileResult {
  path: string;
  name: string;
  timestamp: number;
}

DeleteOptions

interface DeleteOptions {
  dryRun?: boolean;
}

Usage Example

This is a minimal example where:

  1. it will start a search for .nx folders.
  2. Get the most recent file
  3. Get the total size of the directory
import { Npkill } from 'npkill';
import { mergeMap, filter, map } from 'rxjs';

const npkill = new Npkill();

let files: {
  path: string;
  size: number;
  newestFile: string;
}[] = [];

npkill
  .startScan$('/home/user/projects/', { target: '.nx' })
  .pipe(
    // Step 1: For each scan result, get the newest file
    mergeMap((scanResult) =>
      npkill.getNewestFile$(scanResult.path).pipe(
        // Step 2: If no newest file, skip this result
        filter((newestFile) => newestFile !== null),
        // Step 3: Combine scanResult and newestFile
        map((newestFile) => ({
          path: scanResult.path,
          newestFile: newestFile.path,
        })),
      ),
    ),
    // Step 4: For each result, get the folder size
    mergeMap((result) =>
      npkill.getSize$(result.path).pipe(
        map(({ size }) => ({
          ...result,
          size,
        })),
      ),
    ),
  )
  .subscribe({
    next: (result) => {
      files.push(result);
    },
    complete: () => {
      console.log('✅ Scan complete. Found folders:', files.length);
      console.table(files);
      console.log(JSON.stringify(files));
    },
  });

Output:

✅ Scan complete. Found folders: 3
┌─────────┬───────────────────────────────────────────┬──────────────────────────────────────────────────────────────────────────┬─────────┐
│ (index) │ path                                      │ newestFile                                                               │ size    │
├─────────┼───────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────┼─────────┤
│ 0       │ '/home/user/projects/hello-world/.nx'     │ '/home/user/projects/hello-world/.nx/cache/18.3.4-nx.linux-x64-gnu.node' │ 9388032 │
│ 1       │ '/home/user/projects/another-project/.nx' │ '/home/user/projects/another-project/.nx/workspace-data/d/daemon.log'    │ 3182592 │
│ 2       │ '/home/user/projects/ARCHIVED/demo/.nx'   │ '/home/user/projects/ARCHIVED/demo/.nx/cache/d/daemon.log'               │ 2375680 │
└─────────┴───────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────┴─────────┘
[
  {
    "path": "/home/user/projects/hello-world/.nx",
    "newestFile": "/home/user/projects/hello-world/.nx/cache/18.3.4-nx.linux-x64-gnu.node",
    "size": 9388032
  },
  {
    "path": "/home/user/projects/another-project/.nx",
    "newestFile": "/home/user/projects/another-project/.nx/workspace-data/d/daemon.log",
    "size": 3182592
  },
  ........
]