@krizaka/settings
Configuration as data: a typed registry, user over workspace over global, every change audited.
Install
npm install @krizaka/settingsA product's configuration as data: a typed registry of settings (flags, integers, choices, subsets, bilingual texts), resolved user → workspace → global → default, changed by an administrator without a redeploy, every change leaving an audit line (who, what, when, before, after). A JSON-safe description of the registry is what an admin screen draws from.
import { defineSettings, flag, integer, postgresSettings, settingsMigration, GLOBAL, WORKSPACE_SCOPES } from "@krizaka/settings";
const settings = defineSettings({ "features.apiKeys": flag("features", true, WORKSPACE_SCOPES), "limits.maxFileMb": integer("limits", 10, { min: 1, max: 10, unit: "MB" }) } as const);
await db.query(settingsMigration()); // once, in your migrations (idempotent)
const service = postgresSettings(settings, { query, workspaceOf, clock: () => performance.now() });
await service.get("features.apiKeys", { userId }); // typed: boolean
await service.set({ id: adminId, label: email }, GLOBAL, "features.apiKeys", false, now);What stays in the product: its registry (the keys, groups, defaults), the checks it makes at its own boundary (« the server refuses what is off »), who may be an administrator, the HTTP routes. The clock is passed in; nothing here reads it.
Exports
The 36 names the package exports, read from its types.
| Name | Kind | What it is |
|---|---|---|
Actor | type | |
ALL_SCOPES | constant | |
AuditEntry | type | |
bilingual | function | |
choice | function | |
Context | type | |
Def | type | |
defineSettings | function | The tools over one registry: what is a key, its definition, the keys of a group. |
describeSettings | function | |
flag | function | |
GLOBAL | constant | |
GLOBAL_ONLY | constant | |
integer | function | |
KeyOf | type | |
Kind | type | |
KIND | constant | |
Layers | type | What each scope has set for one key (absent = not overridden there). |
postgresSettings | function | The adapter over the product's PostgreSQL (app_settings, settings_audit; see settingsMigration). |
PostgresSettingsDeps | type | |
Query | type | A SQL executor: the rows of a statement and its parameters (the product's pool). |
Registry | type | A registry: keys to definitions (write it as const satisfies Registry to keep the keys and the value types). |
Resolved | type | |
resolveValue | function | The effective value: user, then workspace, then global, then the default. |
Scope | type | |
SCOPE | constant | A product's settings as a typed registry: its key, its type, its default and the scopes it can be overridden at. |
ScopeRef | type | |
SCOPES_BY_SPECIFICITY | constant | The order a value is looked up in: the most specific wins (user, then workspace, then global). |
seedLegacySettings | function | A deployment that was configured by environment before settings existed keeps behaving the same: at server start, each legacy value that differs from the reg… |
SettingDescription | type | A setting as an administration screen draws it: JSON-safe (no schema), so it can cross to the browser. |
SettingsDefinition | type | |
SettingsError | class | |
settingsMigration | function | The tables of the settings: the overrides (global, for a workspace, for one user — the most specific wins) and the audit of every change (who, what, when, be… |
SettingsService | type | The service: the app asks for a setting (user, then workspace, then global, then the default); an administrator changes it, every change leaving an audit line. |
subset | function | |
ValueOf | type | |
WORKSPACE_SCOPES | constant |
Package
| Version on npm | 0.1.0 (npm) |
| Licence | Apache-2.0 |
| Node.js | >=22 |
| Dependencies | none |
| Peer dependencies | zod >=3.23 |
| Source | settings |
Changelog
0.1.0
Minor changes
- First release: the typed registry, resolution user > workspace > global > default, the audit of every change, the admin description, the PostgreSQL adapter and its migration.