# fs-chmod

> A drop-in replacement of fs.chmod with `+x` support

Latest version **1.0.6** (published 2019-06-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install fs-chmod
pnpm add fs-chmod
yarn add fs-chmod
bun add fs-chmod
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.6 |
| Published | 2019-06-14 |
| First published | 2019-06-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 6 |
| Dependencies | 4 |
| Unpacked size | 10 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | kaelzhang |
| Maintainers | kael |
| Keywords | fs-chmod, chmod, symbolic notations, +x, rwx, sticky, setgid, setuid, read, write, execute |

## Links

- npm: https://www.npmjs.com/package/fs-chmod
- Repository: https://github.com/kaelzhang/fs-chmod
- Homepage: https://github.com/kaelzhang/fs-chmod#readme
- Issues: https://github.com/kaelzhang/fs-chmod/issues
- npm.io page: https://npm.io/package/fs-chmod

## Dependencies (4)

- [mz](https://npm.io/package/mz.md) ^2.7.0
- [stat-mode](https://npm.io/package/stat-mode.md) ^0.3.0
- [core-util-is](https://npm.io/package/core-util-is.md) ^1.0.2
- [has-own-prop](https://npm.io/package/has-own-prop.md) ^2.0.0

## Alternatives

- [csv-to-markdown-table](https://npm.io/package/csv-to-markdown-table.md) — 47.0K weekly downloads
- [@sapphire/ratelimits](https://npm.io/package/@sapphire/ratelimits.md) — 4.4K weekly downloads
- [js-csvparser](https://npm.io/package/js-csvparser.md) — 2.0K weekly downloads
- [@adadapted/js-sdk](https://npm.io/package/@adadapted/js-sdk.md) — 251 weekly downloads
- [@grapecity/spread-sheets-sparklines](https://npm.io/package/@grapecity/spread-sheets-sparklines.md) — 103 weekly downloads

## Recent versions

- 1.0.6 (latest) — 2019-06-14
- 1.0.5 — 2019-06-14
- 1.0.4 — 2019-06-14
- 1.0.3 — 2019-06-14
- 1.0.2 — 2019-06-14
- 1.0.1 — 2019-06-14
- 1.0.0 — 2019-06-14
- 0.0.0 — 2019-06-14

## README

[![Build Status](https://travis-ci.org/kaelzhang/fs-chmod.svg?branch=master)](https://travis-ci.org/kaelzhang/fs-chmod)
[![Coverage](https://codecov.io/gh/kaelzhang/fs-chmod/branch/master/graph/badge.svg)](https://codecov.io/gh/kaelzhang/fs-chmod)
<!-- optional appveyor tst
[![Windows Build Status](https://ci.appveyor.com/api/projects/status/github/kaelzhang/fs-chmod?branch=master&svg=true)](https://ci.appveyor.com/project/kaelzhang/fs-chmod)
-->
<!-- optional npm version
[![NPM version](https://badge.fury.io/js/fs-chmod.svg)](http://badge.fury.io/js/fs-chmod)
-->
<!-- optional npm downloads
[![npm module downloads per month](http://img.shields.io/npm/dm/fs-chmod.svg)](https://www.npmjs.org/package/fs-chmod)
-->
<!-- optional dependency status
[![Dependency Status](https://david-dm.org/kaelzhang/fs-chmod.svg)](https://david-dm.org/kaelzhang/fs-chmod)
-->

# fs-chmod

A drop-in replacement of [`fs.chmod`][chmod] with `+x` support.

- supports **finer-grained [symbolic modes]**, such as `+x`, `ug+rw`, and etc.
- supports **mode object** to make the mode better described.

## Install

```sh
$ npm i fs-chmod
```

## Usage

```js
const {
  chmod,
  chmodSync,
  parse
} = require('fs-chmod')

chmod('/path/to/file.js', '+x').then(() => {
  console.log('done')
})

chmodSync.sync('/path/to/file.js', 'a+x')
```

### chmod(path, mode): Promise
### chmod(path, mode, callback): void
### chmodSync(path, mode): void

- **path** `string | Buffer | URL` the same as vanilla [`fs.chmod`][chmod]
- **mode** `integer | Mode | string`
- **callback** `Function(error?)`

Changes the permissions of a file.

### parse(str): Mode

- **str** `string` Symbolic notation string of file system permissions

Parses the symbolic notation string, such as `+x`, `ug+rwx` into an object of the interface `Mode`(see below)

```js
const mode = parse('u+x')

console.log(mode.owner.execute)  // true
console.log(mode.owner.read)     // false
console.log(mode.group)         // undefined
```

## mode

### mode `integer`

The same as the the second parameter of vanilla [`fs.chmod`][chmod].

**PAY ATTENTION** that `mode` should be an **octal** number.

```js
chmodSync('/path/to/file', 0o777)  // ✅ Correct~
chmodSync('/path/to/file', 777)    // ❌ WRONG!
```

### mode `object<Mode>`

```ts
interface Permission {
  read?: boolean
  write?: boolean
  execute?: boolean
}

interface Mode {
  owner?: Permission
  group?: Permission
  others?: Permission
  setuid?: boolean
  setgid?: boolean
  sticky?: boolean
}
```

For details, see [symbolic modes]


```sh
# bash
chmod ug+rst /path/to/file
```

is equivalent to

```js
chmodSync('path/to/file', 'ug+rst')

// or
chmodSync('path/to/file', {
  owner: {
    read: true
  },
  group: {
    read: true
  },
  setuid: true,
  setgid: true,
  sticky: true
})
```

### mode `string`

```
[references][operator][modes]
```

- Supported references: `u`, `g`, `o`, `a`
- Supported operators: `+`, `=`, `-`
- Supported modes:
  - `r`, `w`, `x`
  <!-- - `X`: special execute -->
  - `s`: setuid/setgid
  - `t`: sticky

## License

[MIT](LICENSE)

[chmod]: https://nodejs.org/dist/latest/docs/api/fs.html#fs_fs_chmod_path_mode_callback
[symbolic modes]: https://en.wikipedia.org/wiki/Chmod#Symbolic_modes

---
_Source: https://npm.io/package/fs-chmod · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
