202 lines
4.0 KiB
Markdown
202 lines
4.0 KiB
Markdown
# RC9
|
|
|
|
<!-- automd:badges color=yellow codecov bundlejs -->
|
|
|
|
[](https://npmjs.com/package/rc9)
|
|
[](https://npmjs.com/package/rc9)
|
|
[](https://bundlejs.com/?q=rc9)
|
|
[](https://codecov.io/gh/unjs/rc9)
|
|
|
|
<!-- /automd -->
|
|
|
|
Read/Write RC configs couldn't be easier!
|
|
|
|
## Install
|
|
|
|
Install dependencies:
|
|
|
|
<!-- automd:pm-i -->
|
|
|
|
```sh
|
|
# ✨ Auto-detect
|
|
npx nypm install rc9
|
|
|
|
# npm
|
|
npm install rc9
|
|
|
|
# yarn
|
|
yarn add rc9
|
|
|
|
# pnpm
|
|
pnpm install rc9
|
|
|
|
# bun
|
|
bun install rc9
|
|
```
|
|
|
|
<!-- /automd -->
|
|
|
|
Import utils:
|
|
|
|
<!-- automd:jsimport cjs src="./src/index.ts"-->
|
|
|
|
**ESM** (Node.js, Bun)
|
|
|
|
```js
|
|
import {
|
|
defaults,
|
|
parse,
|
|
parseFile,
|
|
read,
|
|
readUser,
|
|
serialize,
|
|
write,
|
|
writeUser,
|
|
update,
|
|
updateUser,
|
|
} from "rc9";
|
|
```
|
|
|
|
**CommonJS** (Legacy Node.js)
|
|
|
|
```js
|
|
const {
|
|
defaults,
|
|
parse,
|
|
parseFile,
|
|
read,
|
|
readUser,
|
|
serialize,
|
|
write,
|
|
writeUser,
|
|
update,
|
|
updateUser,
|
|
} = require("rc9");
|
|
```
|
|
|
|
<!-- /automd -->
|
|
|
|
|
|
## Usage
|
|
|
|
`.conf`:
|
|
|
|
```ini
|
|
db.username=username
|
|
db.password=multi word password
|
|
db.enabled=true
|
|
```
|
|
|
|
**Update config:**
|
|
|
|
```ts
|
|
update({ 'db.enabled': false }) // 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: 'username',
|
|
// password: 'multi word password',
|
|
// 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:**
|
|
|
|
```ini
|
|
{
|
|
name: '.conf',
|
|
dir: process.cwd(),
|
|
flat: false
|
|
}
|
|
```
|
|
|
|
### Why RC9?
|
|
|
|
Be the first one to guess 🐇 <!-- Hint: do research about rc files history -->
|
|
|
|
## License
|
|
|
|
<!-- automd:contributors license=MIT -->
|
|
|
|
Published under the [MIT](https://github.com/unjs/rc9/blob/main/LICENSE) license.
|
|
Made by [community](https://github.com/unjs/rc9/graphs/contributors) 💛
|
|
<br><br>
|
|
<a href="https://github.com/unjs/rc9/graphs/contributors">
|
|
<img src="https://contrib.rocks/image?repo=unjs/rc9" />
|
|
</a>
|
|
|
|
<!-- /automd -->
|