Protorians Parameters

Lightweight, type-safe parameter containers for TypeScript/JavaScript apps.

Languages: English | Français
Package: @protorians/parameters
Node: >= 22

Installation

Use your favorite package manager:

pnpm add @protorians/parameters
# or
npm i @protorians/parameters
# or
yarn add @protorians/parameters

Overview

This package provides two minimal helpers to manage parameters in memory:

StaticParameter — a simple Set-like bag for static values (e.g., enabled features, selected tags).
DynamicParameter — a key-value map of parameters with optional defaults and change listeners.

Both are strongly typed when used with TypeScript.

StaticParameter

StaticParameter is a thin wrapper over Set with a small convenience API.

import { StaticParameter } from "@protorians/parameters";

// Declare the value type
type Feature = "beta" | "dark-mode" | "a11y";

// Create with initial values
const features = new StaticParameter<Feature>(["a11y"]);

features.add("dark-mode");
console.log(features.has("a11y")); // true
console.log(features.entries()); // ["a11y", "dark-mode"]

console.log(features.value); // first value in the set (implementation detail), or undefined

// Reset back to initial values
features.clear().add("beta");
features.reset(); // back to ["a11y"]

// Clone with the same initial content
const copy = features.clone();

API (table):

Member	Signature	Returns	Description
constructor	new StaticParameter(initial: T[])	StaticParameter	Create a new bag with initial values.
value (get)	value	T \| undefined	First value in the set (if any).
entries	entries(): T[]	T[]	Array snapshot of current values.
add	add(value: T): this	this	Add a value to the set.
has	has(key: T): boolean	boolean	Check if a value exists.
remove	remove(key: T): this	this	Remove a value from the set.
clear	clear(): this	this	Remove all current values.
reset	reset(): this	this	Clear then re-apply initial values.
clone	clone(): this	this	New instance with the same initial values.

Notes:

Internally uses Set, so values are unique and iteration order is insertion order.

DynamicParameter

DynamicParameter manages a map of named parameters with optional defaults and change listeners.

Type parameters

T describes the shape of your data object.
Each property of T is stored as an IParameter: { value, defaultValue?, callback? }.

import { DynamicParameter } from "@protorians/parameters";

// Describe the parameter shape
interface Conf {
  theme: "light" | "dark";
  page: number;
}

// Create with initial values (and optional defaults / callbacks)
const conf = new DynamicParameter<Conf>({
  theme: { value: "light", defaultValue: "light" },
  page:  { value: 1,       defaultValue: 1 }
});

// Read
console.log(conf.get("theme")); // "light"

// Write
conf.set("theme", "dark");
conf.update("page", 2);

// Presence
console.log(conf.has("page")); // true

// Collect plain entries (values only)
console.log(conf.entries); // { theme: "dark", page: 2 }

// Listen to changes for a key
conf.listen("theme", (current) => {
  console.log("Theme changed to", current);
});

// Trigger listeners for a key
conf.dispatch("theme"); // invokes listeners with current value of theme

// Reset to initial definition
conf.reset();

// Clone to a new instance with the same initial definition
const copy = conf.clone();

API (table):

Member	Signature	Returns	Description
constructor	new DynamicParameter(initial: Record<keyof T, IParameter<T[keyof T]>>)	DynamicParameter	Create with the initial parameter definition.
entries (get)	entries	T	Plain object of current values only.
get	get(key: K): T[K] \| undefined	T[K] \| undefined	Current value, or defaultValue if value is falsy and a default exists.
set	set(key: K, value: T[K], defaultValue?, callback?)	this	Set value (and optional default); register callback as listener when provided.
update	update(key: K, value: T[K])	this	Update only if the key already exists.
has	has(key: K): boolean	boolean	Check key presence.
remove	remove(key: K): this	this	Remove a key from the map.
listen	listen(key: K, cb: (v: T[K]) => void): this	this	Register a change listener for a key.
dispatch	dispatch(key: K): this	this	Invoke listeners for a key with the current value.
clear	clear(): this	this	Remove all current values.
reset	reset(): this	this	Clear then re-initialize from initial.
clone	clone(): this	this	New instance with a shallow copy of the initial definition.

Notes:

When reading with get(key), the implementation returns data?.value || data.defaultValue || undefined. If value can be a falsy-but-meaningful value (e.g. 0 or ""), ensure you rely on entries or check presence accordingly.

Type Definitions

Relevant exported types are available under @protorians/parameters:

Type	Description
IParameter	Describes a parameter item with value, optional defaultValue and optional callback.
IStaticProps	Alias for T[] used by StaticParameter constructor.
IDynamicProps	Record mapping keys of T to IParameter<T[keyof T]>.
IStaticParameters	Interface implemented by StaticParameter.
IDynamicParameters	Interface implemented by DynamicParameter.
IParameterCallable	Listener signature for DynamicParameter values.

See source/types/index.ts for the complete definitions.

Development

Dev: pnpm dev
Build: pnpm build

License

ISC