Core infrastructure library for Socket.dev security tools. Provides utilities for file system operations, process spawning, HTTP requests, environment detection, logging, spinners, and more.
Node.js 22 or higher is required.
# Using pnpm (recommended)
pnpm add @socketsecurity/lib
# Using npm
npm install @socketsecurity/lib
# Using yarn
yarn add @socketsecurity/libimport { Spinner } from '@socketsecurity/lib/spinner'
import { getDefaultLogger } from '@socketsecurity/lib/logger'
import { readJson } from '@socketsecurity/lib/fs'
const logger = getDefaultLogger()
const spinner = Spinner({ text: 'Loading package.json...' })
spinner.start()
const pkg = await readJson('./package.json')
spinner.successAndStop('Loaded successfully')
logger.success(`Package: ${pkg.name}@${pkg.version}`)- Getting Started - Prerequisites, installation, and first examples
- Visual Effects - Spinners, loggers, themes, and progress indicators
- File System - File operations, globs, paths, and safe deletion
- HTTP Utilities - Making requests, downloading files, and retry logic
- Process Utilities - Spawning processes, IPC, and locks
- Package Management - npm/pnpm/yarn detection and operations
- Environment - CI detection, env getters, and platform checks
- Constants - Node versions, npm URLs, and platform values
- Examples - Real-world usage patterns
- Troubleshooting - Common issues and solutions
Spinners, colored loggers, themes, progress bars, and terminal output formatting.
Spinner- Animated CLI spinners with progress trackinggetDefaultLogger()- Colored console logger with symbolsLOG_SYMBOLS- Colored terminal symbols (✓, ✗, ⚠, ℹ, →)setTheme()- Customize colors across the library
Cross-platform file operations with safe deletion and convenient wrappers.
readFileUtf8(),readFileBinary()- Read files as text or binaryreadJson(),writeJson()- Parse and format JSON filessafeDelete()- Protected deletion with safety checksfindUp(),findUpSync()- Traverse up to find filessafeMkdir()- Create directories without EEXIST errorsvalidateFiles()- Check file readability (useful for Yarn PnP, pnpm)
Native Node.js HTTP/HTTPS requests with retry logic and redirects.
httpJson()- Fetch and parse JSON from APIshttpText()- Fetch text/HTML contenthttpDownload()- Download files with progress callbackshttpRequest()- Full control over requests and responses- Automatic redirects, exponential backoff retries, timeout support
Spawn child processes safely with cross-platform support.
spawn()- Promise-based process spawning with output capturespawnSync()- Synchronous version for blocking operations- Array-based arguments prevent command injection
- Automatic Windows
.cmd/.bathandling ProcessLock- Ensure only one instance runs at a timesetupIPC()- Inter-process communication
Type-safe environment variable access and platform detection.
getCI()- Detect CI environmentgetNodeEnv()- Get NODE_ENV valueisTest()- Check if running testsgetHome()- Home directory (Unix/Linux/macOS)- Test rewiring with
setEnv(),resetEnv()
Detect and work with npm, pnpm, and yarn.
detectPackageManager()- Identify package manager from lock files- Package manifest operations
- Lock file management
Pre-defined values for Node.js, npm, and platform detection.
getNodeMajorVersion()- Get current Node.js major versionWIN32,DARWIN- Platform booleans (use!WIN32 && !DARWINfor Linux)getAbortSignal()- Global abort signal
Helpers for arrays, objects, strings, promises, sorting, and more.
- Arrays, objects, strings manipulation
- Promise utilities and queues
- Natural sorting
- Version comparison
- Error handling with causes
- Tree-shakeable exports - Import only what you need
- Cross-platform - Works on Windows, macOS, and Linux
- TypeScript-first - Full type safety with .d.ts files
- Zero dependencies (for core HTTP - uses Node.js native modules)
- Well-tested - 84% coverage with comprehensive test suite
- Security-focused - Safe defaults, command injection protection
- CommonJS output - Compatible with Node.js tooling
import { spawn } from '@socketsecurity/lib/spawn'
const result = await spawn('git', ['status'])
console.log(result.stdout)import { httpJson } from '@socketsecurity/lib/http-request'
const data = await httpJson('https://api.example.com/data')import { Spinner } from '@socketsecurity/lib/spinner'
const spinner = Spinner({ text: 'Processing...' })
spinner.start()
// ... do work ...
spinner.successAndStop('Complete!')import { safeDelete } from '@socketsecurity/lib/fs'
// Protected against deleting parent directories
await safeDelete('./build')Module not found: Verify you're importing from the correct path:
// Correct
import { Spinner } from '@socketsecurity/lib/spinner'
// Wrong
import { Spinner } from '@socketsecurity/lib'Node version error: This library requires Node.js 22+. Check your version:
node --versionFor more issues, see the Troubleshooting Guide.
pnpm install # Install dependencies
pnpm build # Build the library
pnpm test # Run tests
pnpm run cover # Run tests with coverage
pnpm dev # Watch mode
pnpm run lint # Check code style
pnpm run fix # Fix formatting issuesContributions are welcome! Please read the CLAUDE.md file for development guidelines and coding standards.
MIT