or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdconfiguration.mddata-operations.mdindex.md
tile.json

tessl/npm-conf

Simple config handling for your app or module

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/conf@14.0.x

To install, run

npx @tessl/cli install tessl/npm-conf@14.0.0

index.mddocs/

Conf

Conf is a simple config handling library for Node.js applications that provides persistent storage for application settings and user preferences. It handles all the complex details like storage locations, data validation, atomic writes, and cross-platform compatibility, so you only need to focus on what data to persist.

Package Information

  • Package Name: conf
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install conf

Core Imports

import Conf from "conf";
import type { Options, Schema } from "conf";

All Available Named Exports:

import Conf, { 
  type Options, 
  type Schema,
  type AjvOptions 
} from "conf";

// Additional types available for import
import type {
  Migrations,
  BeforeEachMigrationContext,
  BeforeEachMigrationCallback,
  OnDidChangeCallback,
  OnDidAnyChangeCallback,
  Unsubscribe,
  Serialize,
  Deserialize,
  DotNotationKeyOf,
  DotNotationValueOf,
  PartialObjectDeep,
  ValueSchema
} from "conf";

For CommonJS:

const Conf = require("conf");

Basic Usage

import Conf from "conf";

// Create a configuration store
const config = new Conf({ projectName: "my-app" });

// Set configuration values
config.set("username", "john");
config.set("preferences.theme", "dark");
config.set("preferences.notifications", true);

// Get configuration values
console.log(config.get("username")); // => "john"
console.log(config.get("preferences.theme")); // => "dark"
console.log(config.get("nonexistent", "default")); // => "default"

// Use dot notation for nested properties
config.set("user.profile.name", "John Doe");
console.log(config.get("user.profile.name")); // => "John Doe"

// Check if values exist
if (config.has("username")) {
  console.log("Username is configured");
}

// Delete configuration values
config.delete("username");
console.log(config.get("username")); // => undefined

// Get all configuration as an object
console.log(config.store);
// => { preferences: { theme: "dark", notifications: true }, user: { profile: { name: "John Doe" } } }

Architecture

Conf is built around several key components:

  • Storage Management: Automatic handling of cross-platform config directories with atomic writes to prevent corruption during crashes
  • Type Safety: Full TypeScript support with generic type parameters for strongly-typed configuration schemas
  • Validation System: JSON Schema validation with AJV for data integrity and default value handling
  • Advanced Features: Encryption for obfuscation, version-based migrations, file watching, and event-driven change notifications
  • Flexible Access: Support for both direct property access and dot notation for nested properties

Capabilities

Configuration Management

Core functionality for storing and retrieving configuration data with full type safety and validation.

class Conf<T extends Record<string, any> = Record<string, unknown>> {
  constructor(options?: Partial<Options<T>>);
  
  // Core data operations
  get<Key extends keyof T>(key: Key): T[Key];
  get<Key extends keyof T>(key: Key, defaultValue: Required<T>[Key]): Required<T>[Key];
  set<Key extends keyof T>(key: Key, value?: T[Key]): void;
  set(object: PartialObjectDeep<T>): void;
  has<Key extends keyof T>(key: Key): boolean;
  delete<Key extends keyof T>(key: Key): void;
  clear(): void;
  reset<Key extends keyof T>(...keys: Key[]): void;
}

Configuration Management

Data Operations

Methods for getting, setting, and manipulating configuration data with support for nested properties via dot notation.

// Dot notation support for nested properties
get<Key extends DotNotationKeyOf<T>>(key: Key): DotNotationValueOf<T, Key>;
set<Key extends DotNotationKeyOf<T>>(key: Key, value?: DotNotationValueOf<T, Key>): void;
has<Key extends DotNotationKeyOf<T>>(key: Key): boolean;
delete<Key extends DotNotationKeyOf<T>>(key: Key): void;

// Properties
readonly path: string;
readonly size: number;
store: T;

Data Operations

Advanced Features

Powerful features for production applications including schema validation, encryption, migrations, and change monitoring.

// Event handling
onDidChange<Key extends keyof T>(key: Key, callback: OnDidChangeCallback<T[Key]>): Unsubscribe;
onDidAnyChange(callback: OnDidAnyChangeCallback<T>): Unsubscribe;

// Iteration support
[Symbol.iterator](): IterableIterator<[keyof T, T[keyof T]]>;

Advanced Features

Types

interface Options<T extends Record<string, any>> {
  projectName?: string;
  configName?: string;
  defaults?: Readonly<T>;
  schema?: Schema<T>;
  cwd?: string;
  encryptionKey?: string | Uint8Array | NodeJS.TypedArray | DataView;
  fileExtension?: string;
  watch?: boolean;
  accessPropertiesByDotNotation?: boolean;
  clearInvalidConfig?: boolean;
  configFileMode?: number;
  migrations?: Migrations<T>;
  beforeEachMigration?: BeforeEachMigrationCallback<T>;
  serialize?: Serialize<T>;
  deserialize?: Deserialize<T>;
  projectSuffix?: string;
  projectVersion?: string;
  rootSchema?: Omit<JSONSchema, 'properties'>;
  ajvOptions?: AjvOptions;
}

type Schema<T> = {[Property in keyof T]: ValueSchema};
type ValueSchema = JSONSchema;

type OnDidChangeCallback<T> = (newValue?: T, oldValue?: T) => void;
type OnDidAnyChangeCallback<T> = (newValue?: Readonly<T>, oldValue?: Readonly<T>) => void;
type Unsubscribe = () => void;

type Migrations<T> = Record<string, (store: Conf<T>) => void>;
type BeforeEachMigrationCallback<T> = (store: Conf<T>, context: BeforeEachMigrationContext) => void;

interface BeforeEachMigrationContext {
  fromVersion: string;
  toVersion: string;
  finalVersion: string;
  versions: string[];
}

type Serialize<T> = (value: T) => string;
type Deserialize<T> = (text: string) => T;

type DotNotationKeyOf<T extends Record<string, any>> = // Complex utility type for dot notation keys
type DotNotationValueOf<T extends Record<string, any>, K extends DotNotationKeyOf<T>> = // Complex utility type for dot notation values
type PartialObjectDeep<T> = {[K in keyof T]?: PartialObjectDeep<T[K]>};

// Re-exported from AJV for convenience
type AjvOptions = import('ajv/dist/core.js').CurrentOptions;