Core infrastructure library for Socket.dev security tools — utilities, constants, and helpers with zero dependencies.
pnpm add @socketsecurity/lib// Import what you need - tree-shakeable exports
import { Spinner } from '@socketsecurity/lib/spinner'
import { readJsonFile } from '@socketsecurity/lib/fs'
import { NODE_MODULES } from '@socketsecurity/lib/constants/packages'
const spinner = Spinner({ text: 'Loading...' })
spinner.start()
const pkg = await readJsonFile('./package.json')
spinner.stop()@socketsecurity/lib
├── Visual Effects → Spinners, shimmer, themes, logger
├── File System → fs, paths, globs, temp files
├── Package Management → npm, pnpm, yarn utilities
├── Process & Spawn → Safe process spawning, IPC
├── Environment → 68 typed env getters (CI, paths, etc)
├── Constants → Node.js, npm, platform constants
├── Utilities → Arrays, objects, strings, promises
└── Types → Full TypeScript definitions
Themed spinners and text effects:
import { Spinner, setTheme } from '@socketsecurity/lib'
setTheme('ultra') // 🌈 Rainbow mode!
const spinner = Spinner({ text: 'Processing...' })
spinner.enableShimmer()
spinner.start()5 Built-in Themes: socket (purple) · coana · socket-firewall · socket-cli-python · ultra (rainbow)
Safe, typed file operations:
import { readJsonFile, writeJsonFile } from '@socketsecurity/lib/fs'
const pkg = await readJsonFile<PackageJson>('./package.json')
await writeJsonFile('./output.json', { data: pkg })Parse and validate package specs:
import { parsePackageSpec } from '@socketsecurity/lib/packages'
const spec = parsePackageSpec('lodash@^4.17.0')
// { name: 'lodash', version: '^4.17.0', type: 'range', ... }68 typed environment getters:
import { getCI } from '@socketsecurity/lib/env/ci'
import { getHome } from '@socketsecurity/lib/env/home'
import { getNodeEnv } from '@socketsecurity/lib/env/node-env'
if (getCI()) {
console.log('Running in CI')
}Access platform and Node.js constants:
import {
NODE_MODULES,
PACKAGE_JSON,
NPM_REGISTRY_URL,
} from '@socketsecurity/lib/constants/packages'
import { DARWIN, WIN32 } from '@socketsecurity/lib/constants/platform'import { withSpinner, Spinner } from '@socketsecurity/lib/spinner'
await withSpinner({
message: 'Installing packages...',
spinner: Spinner({ color: [140, 82, 255] }),
operation: async () => {
await installPackages()
}
})import { spawn } from '@socketsecurity/lib/spawn'
const result = await spawn('npm', ['install'], {
cwd: '/path/to/project',
timeout: 30000
})import { readJsonFile, writeJsonFile } from '@socketsecurity/lib/fs'
const data = await readJsonFile('./config.json')
data.version = '2.0.0'
await writeJsonFile('./config.json', data)import { timeout, retry } from '@socketsecurity/lib/promises'
// Timeout after 5 seconds
const result = await timeout(fetchData(), 5000)
// Retry up to 3 times
const data = await retry(() => fetchData(), { maxAttempts: 3 })120+ granular exports organized by category:
/constants/ → Node.js, npm, platform constants
├─ packages → PACKAGE_JSON, NODE_MODULES, etc.
├─ platform → DARWIN, WIN32, S_IXUSR, etc.
├─ node → NODE_VERSION, NODE_PATH, etc.
├─ time → MILLISECONDS_PER_*, DLX_BINARY_CACHE_TTL
└─ encoding → UTF8, CHAR_* codes
/env/ → 68 typed environment getters
├─ ci → getCI() - Detect CI environment
├─ home → getHome() - User home directory
├─ node-env → getNodeEnv() - NODE_ENV value
└─ ... → And 65 more!
/packages/ → Package management utilities
├─ validation → Package name/version validation
├─ operations → Install, extract, manifest
├─ registry → npm registry utilities
└─ editable → Editable installs detection
/effects/ → Visual effects for CLI
├─ text-shimmer → Animated gradient text
├─ pulse-frames → Pulsing text effect
└─ ultra → Rainbow gradients
/stdio/ → Terminal I/O utilities
├─ stdout → Safe stdout operations
├─ stderr → Safe stderr operations
├─ clear → Clear terminal
└─ footer → Terminal footers
/themes/ → Theme system for consistent branding
├─ types → Theme type definitions
├─ themes → 5 built-in themes
├─ context → Global theme management
└─ utils → Color resolution, theme creation
| Doc | Description |
|---|---|
| Getting Started | Development workflow, commands, architecture |
| Theme System | Themed spinners, colors, and effects |
| Build Architecture | Vendored dependencies, build system |
| CLAUDE.md | Coding standards and patterns |
┌─────────────────────────────────────────────────────┐
│ @socketsecurity/lib │
│ Zero runtime dependencies │
├─────────────────────────────────────────────────────┤
│ src/ │
│ ├── constants/ 14 modules │
│ ├── env/ 68 getters │
│ ├── packages/ 12 utilities │
│ ├── effects/ 4 visual effects │
│ ├── stdio/ 9 I/O utilities │
│ ├── themes/ Theme system │
│ ├── external/ 40+ vendored deps │
│ └── ... 60+ more modules │
├─────────────────────────────────────────────────────┤
│ Build: esbuild → CommonJS (ES2022) │
│ Types: tsgo (TypeScript Native Preview) │
│ Tests: Vitest (4600+ tests, 100% coverage) │
└─────────────────────────────────────────────────────┘
# Setup
git clone https://github.com/SocketDev/socket-lib.git
cd socket-lib
pnpm install
# Build
pnpm run build # Production build
pnpm run dev # Watch mode
# Test
pnpm test # Run all tests
pnpm run cover # With coverage
# Quality
pnpm run check # Type check
pnpm run lint # Lint code
pnpm run fix # Auto-fix issues- 183 TypeScript modules
- 120+ granular exports
- 68 typed environment getters
- 14 constant modules
- 4600+ tests passing
- Zero runtime dependencies
See CLAUDE.md for:
- Code style and patterns
- Path alias usage
- Testing guidelines
- Build system details
MIT
Built by Socket.dev — socket.dev | @SocketSecurity