forked from daren.hsu/line_push
156 lines
3.5 KiB
Markdown
156 lines
3.5 KiB
Markdown
# RC9
|
|
|
|
> Read/Write config couldn't be easier!
|
|
|
|
[![npm version][npm-version-src]][npm-version-href]
|
|
[![npm downloads][npm-downloads-src]][npm-downloads-href]
|
|
[![Github Actions][github-actions-src]][github-actions-href]
|
|
[![Codecov][codecov-src]][codecov-href]
|
|
|
|
## Install
|
|
|
|
Install using npm or yarn:
|
|
|
|
```bash
|
|
npm i rc9
|
|
# or
|
|
yarn add rc9
|
|
```
|
|
|
|
Import into your Node.js project:
|
|
|
|
```js
|
|
// CommonJS
|
|
const { read, write, update } = require('rc9')
|
|
|
|
// ESM
|
|
import { read, write, update } from 'rc9'
|
|
```
|
|
|
|
## Usage
|
|
|
|
`.conf`:
|
|
|
|
```ts
|
|
db.username=db username
|
|
db.password=db pass
|
|
db.enabled=true
|
|
```
|
|
|
|
**Update config:**
|
|
|
|
```ts
|
|
update({ 'db.enabled': true }) // or update(..., { name: '.conf' })
|
|
```
|
|
|
|
Push to an array:
|
|
|
|
```ts
|
|
update({ 'modules[]': 'test' })
|
|
```
|
|
|
|
**Read/Write config:**
|
|
|
|
```ts
|
|
const config = read() // or read('.conf')
|
|
|
|
// config = {
|
|
// db: {
|
|
// username: 'db username',
|
|
// password: 'db pass',
|
|
// enabled: true
|
|
// }
|
|
// }
|
|
|
|
config.enabled = false
|
|
write(config) // or write(config, '.conf')
|
|
```
|
|
|
|
**User Config:**
|
|
|
|
It is common to keep config in user home directory (MacOS: `/Users/{name}`, Linux: `/home/{name}`, Windows: `C:\users\{name}`)
|
|
|
|
you can use `readUser`/`writeuser`/`updateUser` shortcuts to quickly do this:
|
|
|
|
```js
|
|
writeUser({ token: 123 }, '.zoorc') // Will be saved in {home}/.zoorc
|
|
|
|
const conf = readUser('.zoorc') // { token: 123 }
|
|
```
|
|
|
|
## Unflatten
|
|
|
|
RC uses [flat](https://www.npmjs.com/package/flat) to automatically flat/unflat when writing and reading rcfile.
|
|
|
|
It means that you can use `.` for keys to define objects. Some examples:
|
|
|
|
- `hello.world = true` <=> `{ hello: { world: true }`
|
|
- `test.0 = A` <=> `tags: [ 'A' ]`
|
|
|
|
**Note:** If you use keys that can override like `x=` and `x.y=`, you can disable this feature by passing `flat: true` option.
|
|
|
|
**Tip:** You can use keys ending with `[]` to push to an array like `test[]=A`
|
|
|
|
## Native Values
|
|
|
|
RC uses [destr](https://www.npmjs.com/package/destr) to convert values into native javascript values.
|
|
|
|
So reading `count=123` results `{ count: 123 }` (instead of `{ count: "123" }`) if you want to preserve strings as is, can use `count="123"`.
|
|
|
|
## Exports
|
|
|
|
```ts
|
|
const defaults: RCOptions;
|
|
function parse(contents: string, options?: RCOptions): RC
|
|
function parseFile(path: string, options?: RCOptions): RC
|
|
function read(options?: RCOptions | string): RC;
|
|
function readUser(options?: RCOptions | string): RC;
|
|
function serialize(config: RC): string;
|
|
function write(config: RC, options?: RCOptions | string): void;
|
|
function writeUser(config: RC, options?: RCOptions | string): void;
|
|
function update(config: RC, options?: RCOptions | string): RC;
|
|
function updateUser(config: RC, options?: RCOptions | string): RC;
|
|
```
|
|
|
|
**Types:**
|
|
|
|
```ts
|
|
type RC = Record<string, any>;
|
|
interface RCOptions {
|
|
name?: string;
|
|
dir?: string;
|
|
flat?: boolean;
|
|
}
|
|
```
|
|
|
|
**Defaults:**
|
|
|
|
```ts
|
|
{
|
|
name: '.conf',
|
|
dir: process.cwd(),
|
|
flat: false
|
|
}
|
|
```
|
|
|
|
### Why RC9?
|
|
|
|
Be the first one to guess 🐇 <!-- Hint: do research about rc files history -->
|
|
|
|
## License
|
|
|
|
MIT. Made with 💖
|
|
|
|
<!-- Badges -->
|
|
[npm-version-src]: https://img.shields.io/npm/v/rc9?style=flat-square
|
|
[npm-version-href]: https://npmjs.com/package/rc9
|
|
|
|
[npm-downloads-src]: https://img.shields.io/npm/dm/rc9?style=flat-square
|
|
[npm-downloads-href]: https://npmjs.com/package/rc9
|
|
|
|
[github-actions-src]: https://img.shields.io/github/workflow/status/unjs/rc9/ci/main?style=flat-square
|
|
[github-actions-href]: https://github.com/unjs/rc9/actions?query=workflow%3Aci
|
|
|
|
[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/rc9/main?style=flat-square
|
|
[codecov-href]: https://codecov.io/gh/unjs/rc9
|