@nodesecure/rc
TypeScript icon, indicating that this package has built-in type declarations

2.1.0 • Public • Published

@nodesecure/rc

npm version license ossf scorecard github ci workflow

NodeSecure runtime configuration.

Requirements

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

If undefined the location will be assigned to process.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 the disk.
   *
   * @default false
   */
  createIfDoesNotExist?: boolean;
  /**
   * RC Generation mode. This option allows to generate a more or less complete configuration for some NodeSecure tools.
   *
   * @default `minimal`
   */
  createMode?: RCGenerationMode | RCGenerationMode[];
  /**
   * RC automatic caching option. This option allows to cache a configuration passed in parameter.
   *
   * @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 with a JSON Schema: ./src/schema/nodesecurerc.json.

It can be retrieved by API if required:

import * as RC from "@nodesecure/rc";

console.log(RC.JSONSchema);

Contributors ✨

All Contributors

Thanks goes to these wonderful people (emoji key):

Gentilhomme
Gentilhomme

💻 🐛 👀 📖 🛡️
Antoine Coulon
Antoine Coulon

💻 🐛 👀
PierreD
PierreD

💻
Kouadio Fabrice Nguessan
Kouadio Fabrice Nguessan

💻 🚧

License

MIT

Readme

Keywords

Package Sidebar

Install

npm i @nodesecure/rc

Weekly Downloads

110

Version

2.1.0

License

MIT

Unpacked Size

42 kB

Total Files

46

Last publish

Collaborators

  • pierred
  • antoine-coulon
  • kawacrepe
  • fraxken
  • tonygo