191 lines
4.0 KiB
Markdown
191 lines
4.0 KiB
Markdown
# RC9
|
|
|
|
<!-- automd:badges color=yellow codecov bundlejs -->
|
|
|
|
[](https://npmjs.com/package/rc9)
|
|
[](https://npm.chart.dev/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 add rc9
|
|
|
|
# bun
|
|
bun install rc9
|
|
|
|
# deno
|
|
deno install npm:rc9
|
|
```
|
|
|
|
<!-- /automd -->
|
|
|
|
Import utils:
|
|
|
|
<!-- automd:jsimport src="./src/index.ts"-->
|
|
|
|
**ESM** (Node.js, Bun, Deno)
|
|
|
|
```js
|
|
import {
|
|
defaults,
|
|
parse,
|
|
parseFile,
|
|
read,
|
|
readUser,
|
|
serialize,
|
|
write,
|
|
writeUser,
|
|
readUserConfig,
|
|
writeUserConfig,
|
|
updateUserConfig,
|
|
update,
|
|
updateUser,
|
|
} from "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:**
|
|
|
|
You can use `readUserConfig`/`writeUserConfig`/`updateUserConfig` to store config in the user's config directory (`$XDG_CONFIG_HOME` or `~/.config`):
|
|
|
|
```js
|
|
writeUserConfig({ token: 123 }, ".zoorc"); // Will be saved in ~/.config/.zoorc
|
|
|
|
const conf = readUserConfig(".zoorc"); // { token: 123 }
|
|
```
|
|
|
|
> [!NOTE]
|
|
> `readUser`/`writeUser`/`updateUser` are deprecated. Use `readUserConfig`/`writeUserConfig`/`updateUserConfig` instead, which follow XDG conventions (`~/.config`).
|
|
|
|
## 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 readUserConfig(options?: RCOptions | string): RC;
|
|
function serialize(config: RC): string;
|
|
function write(config: RC, options?: RCOptions | string): void;
|
|
function writeUserConfig(config: RC, options?: RCOptions | string): void;
|
|
function update(config: RC, options?: RCOptions | string): RC;
|
|
function updateUserConfig(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 -->
|