@socketsecurity/lib
v5.11.4
Published
Core utilities and infrastructure for Socket.dev security tools
Readme
@socketsecurity/lib
Core infrastructure library for Socket.dev security tools. Provides utilities for file system operations, process spawning, HTTP requests, environment detection, logging, spinners, and more.
Prerequisites
Node.js 22 or higher is required.
Install
# Using pnpm (recommended)
pnpm add @socketsecurity/lib
# Using npm
npm install @socketsecurity/lib
# Using yarn
yarn add @socketsecurity/libQuick Start
import { 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}`)Documentation
- 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
What's Inside
Visual Effects
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
File System
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)
HTTP Utilities
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
Process Management
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
Environment Detection
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()
Package Management
Detect and work with npm, pnpm, and yarn.
detectPackageManager()- Identify package manager from lock files- Package manifest operations
- Lock file management
Constants
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
Utilities
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
Features
- 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
Common Use Cases
Running Shell Commands
import { spawn } from '@socketsecurity/lib/spawn'
const result = await spawn('git', ['status'])
console.log(result.stdout)Making API Requests
import { httpJson } from '@socketsecurity/lib/http-request'
const data = await httpJson('https://api.example.com/data')Visual Feedback
import { Spinner } from '@socketsecurity/lib/spinner'
const spinner = Spinner({ text: 'Processing...' })
spinner.start()
// ... do work ...
spinner.successAndStop('Complete!')Safe File Deletion
import { safeDelete } from '@socketsecurity/lib/fs'
// Protected against deleting parent directories
await safeDelete('./build')Troubleshooting
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.
Development
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 issuesContributing
Contributions are welcome! Please read the CLAUDE.md file for development guidelines and coding standards.
License
MIT
