@nodesecure/rc
v4.0.0
Published
NodeSecure runtime configuration
Downloads
213
Readme
NodeSecure runtime configuration.
Requirements
- Node.js v18 or higher
Getting Started
This package is available in the Node Package Repository and can be easily installed with npm or yarn.
$ npm i @nodesecure/rc
# or
$ yarn add @nodesecure/rc
Usage example
read:
import * as RC from "@nodesecure/rc";
const configurationPayload = (
await RC.read(void 0, { createIfDoesNotExist: true })
).unwrap();
console.log(configurationPayload);
write:
import assert from "node:assert/strict";
import * as RC from "@nodesecure/rc";
const writeOpts: RC.writeOptions = {
payload: { version: "2.0.0" },
partialUpdate: true,
};
const result = (await RC.write(void 0, writeOpts)).unwrap();
assert.strictEqual(result, void 0);
memoize/memoized:
import * as RC from "@nodesecure/rc";
import assert from "node:assert";
const configurationPayload = (
await RC.read(void 0, { createMode: "ci" })
).unwrap()
RC.memoize(configurationPayload, { overwrite: true });
const memoizedPayload = RC.memoized();
assert.deepEqual(configurationPayload, memoizedPayload);
👀 .read and .write return Rust like Result object.
API
[!NOTE] If
undefined
, the location will be assigned toprocess.cwd()
.
read(location?: string, options?: readOptions): Promise< Result< RC, NodeJS.ErrnoException > >
interface createReadOptions {
/**
* If enabled, the file will be created if it does not exist on disk.
*
* @default false
*/
createIfDoesNotExist?: boolean;
/**
* Generate a more or less complete configuration.
*
* @default `minimal`
*/
createMode?: RCGenerationMode | RCGenerationMode[];
/**
* Automatically cache the configuration when enabled.
*
* @default false
*/
memoize?: boolean;
}
export type readOptions = RequireAtLeastOne<
createReadOptions,
"createIfDoesNotExist" | "createMode"
>;
The createIfDoesNotExist
argument can be ignored if createMode
is provided.
import * as RC from "@nodesecure/rc";
const configurationPayload = (
await RC.read(void 0, { createMode: "ci" })
).unwrap();
console.log(configurationPayload);
write(location?: string, options: writeOptions): Promise< Result< void, NodeJS.ErrnoException > >
By default the write API will overwrite the current payload with the provided one. When the partialUpdate
option is enabled it will merge the new properties with the existing one.
/**
* Overwrite the complete payload. partialUpdate property is mandatory.
*/
export interface writeCompletePayload {
payload: RC;
partialUpdate?: false;
}
/**
* Partially update the payload. This implies not to rewrite the content of the file when enabled.
**/
export interface writePartialPayload {
payload: Partial<RC>;
partialUpdate: true;
}
export type writeOptions = writeCompletePayload | writePartialPayload;
memoize(payload: Partial< RC >, options: memoizeOptions = {}): void
By default, the memory API overwrites the previous stored payload. When the OVERWRITE
option is false
, it merges new properties with existing properties.
export interface memoizeOptions {
overwrite?: boolean;
}
The overwrite
option is used to specify whether data should be overwritten or merged.
memoized(options: memoizedOptions): Partial< RC > | null
This method returns null, when the default value is null, otherwise, it returns the current value of memoizedValue
.
export interface memoizedOptions {
defaultValue: Partial<RC>;
}
If the defaultValue
property is at null, then this value will be returned when memoized
is called.
maybeMemoized(): Option< Partial< RC > >
Same as memoized but return an Option monad.
import * as RC from "@nodesecure/rc";
const memoized = RC.maybeMemoized()
.unwrapOr({}); // Some default RC here
clearMemoized(): void
Clear/reset memoized RC
homedir(): string
Dedicated directory for NodeSecure to store the configuration in the os HOME directory.
import * as RC from "@nodesecure/rc";
const homedir = RC.homedir();
CONSTANTS
import assert from "node:assert/strict";
import * as RC from "@nodesecure/rc";
assert.strictEqual(RC.CONSTANTS.CONFIGURATION_NAME, ".nodesecurerc");
Generation Mode
We provide by default a configuration generation that we consider minimal
. On the contrary, a complete
value will indicate the generation with all possible default keys.
export type RCGenerationMode = "minimal" | "ci" | "report" | "scanner" | "complete";
However, depending on the NodeSecure tool you are working on, it can be interesting to generate a configuration with some property sets specific to your needs.
Note that you can combine several modes:
import * as RC from "@nodesecure/rc";
await RC.read(void 0, { createMode: ["ci", "report"] });
JSON Schema
The runtime configuration is validated using a JSON Schema: ./src/schema/nodesecurerc.json
.
It can be retrieved via API if needed:
import * as RC from "@nodesecure/rc";
console.log(RC.JSONSchema);
The JSON schema is a composition of multiple definitions for each tool:
Contributors ✨
Thanks goes to these wonderful people (emoji key):
License
MIT