unix-permissions
A comprehensive JavaScript library for parsing, converting, and manipulating Unix file permissions across multiple notation types.
What is unix-permissions?
Unix-permissions is a JavaScript library that provides tools for parsing, converting, and manipulating Unix file permissions across multiple notation types. It solves the problem of working with different permission formats (symbolic, octal, stat) by offering a unified API for conversions and operations like setting, testing, and inverting permissions.
Developers and system administrators working with file systems in Node.js or browser environments, especially those building tools that need to handle Unix permissions programmatically or via CLI.
It eliminates the tedium and errors of manual bitwise operations or string parsing by providing a comprehensive, type-safe utility that supports all common permission notations and operations in one package.
Overview
Swiss Army knife for Unix permissions
Use Cases
Best For
- Converting between symbolic, octal, and stat permission notations
- Programmatically setting or testing file permissions in Node.js scripts
- Building CLI tools that manipulate Unix permissions
- Aggregating or comparing permissions across multiple files during directory recursion
- Handling special permissions like setuid, setgid, and sticky bits
- Validating and normalizing user-provided permission strings in applications
Not Ideal For
- Projects exclusively targeting Windows or non-Unix file systems
- Simple scripts that only use static permissions without conversion or manipulation needs
- High-performance applications where direct bitwise operations are preferred for minimal overhead
- Environments stuck on Node.js versions older than 18.18.0
Pros & Cons
Pros
Supports symbolic, octal, stat, and object representations, enabling seamless conversion between all common Unix permission notations as demonstrated in the examples and API.
Provides high-level methods for setting, testing, inverting, and comparing permissions, eliminating error-prone bitwise logic detailed in the README's operations section.
Automatically validates permission syntax and normalizes to canonical forms, such as condensing 'u+r,u+w' to 'u+rw', ensuring consistency without manual parsing.
Runs in Node.js ≥18.18.0 and modern browsers as an ES module, making it versatile for both server-side and client-side use, as highlighted in the install notes.
Cons
Requires Node.js ≥18.18.0, which excludes older projects or environments that haven't upgraded, as explicitly stated in the install section, limiting backward compatibility.
Must be loaded using import statements, not require(), which can be a hurdle for CommonJS-based projects without migration efforts, adding setup complexity.
Manipulates permission strings only, requiring additional utilities like fs.chmod or stat to apply permissions to files, as admitted in the README, which adds extra steps to workflows.
Frequently Asked Questions
Related Projects
BatA cat(1) clone with wings.
sccSloc, Cloc and Code: scc is a very fast accurate code counter with complexity calculations and COCOMO estimates written in pure Go
entrRun arbitrary commands when files change
f2F2 is a cross-platform command-line tool for batch renaming files and directories quickly and safely. Written in Go!
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.