@james-pre/config 1.1.0 → 1.2.1

package/README.md

@@ -1,3 +1,15 @@
 # @james-pre/config
 
 A small library for managing configuration files.
+
+## CLI
+
+`@james-pre/config/cli` adds a `config` command to a [Commander](https://github.com/tj/commander.js) program, with `dump`, `get`, `set`, `list`, and `schema`:
+
+```ts
+import { configCommand } from '@james-pre/config/cli';
+
+configCommand(program, configManager);
+```
+
+Commander is an optional peer dependency, needed only for the CLI.

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+import type { Command } from 'commander';
+import * as z from 'zod';
+import type { FileType, Manager } from './manager.js';
+export interface ConfigCommandOptions {
+    /** @default 'config' */
+    name?: string;
+    /**
+     * Keys whose values `--redact` hides, wherever they are.
+     * @default ['password', 'secret']
+     */
+    sensitive?: readonly string[];
+    /** The kind of file `set` writes to without `--type`, otherwise the most recently loaded one. */
+    defaultType?: FileType;
+}
+/**
+ * Add a command for reading and changing a manager's configuration to `parent`.
+ * @returns the new command, for adding more subcommands
+ */
+export declare function configCommand<C extends Command>(parent: C, manager: Manager<z.ZodObject>, options?: ConfigCommandOptions): Command;

package/dist/cli.js

@@ -0,0 +1,79 @@
+import { getByString, setByString } from 'utilium';
+import * as z from 'zod';
+const fileTypes = ['system', 'user', 'local'];
+function redact(value, keys) {
+    if (Array.isArray(value))
+        return value.map(item => redact(item, keys));
+    if (typeof value != 'object' || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, keys.includes(key) ? '[redacted]' : redact(child, keys)]));
+}
+/**
+ * Add a command for reading and changing a manager's configuration to `parent`.
+ * @returns the new command, for adding more subcommands
+ */
+export function configCommand(parent, manager, options = {}) {
+    const { sensitive = ['password', 'secret'] } = options;
+    const command = parent
+        .command(options.name ?? 'config')
+        .description('Manage the configuration')
+        .option('-j, --json', 'read and write values as JSON', false)
+        .option('-r, --redact', 'hide sensitive values', false);
+    function output(value) {
+        const { json, redact: hide } = command.opts();
+        if (hide)
+            value = redact(value, sensitive);
+        console.log(json ? JSON.stringify(value, null, 4) : value);
+    }
+    command
+        .command('dump')
+        .description('Output the entire current configuration')
+        .action(() => output(manager.data));
+    command
+        .command('get')
+        .description('Get a config value')
+        .argument('<key>', 'the key to get')
+        .action(key => output(getByString(manager.data, key)));
+    command
+        .command('set')
+        .description('Set a config value, which must be JSON for anything but a string')
+        .argument('<key>', 'the key to set')
+        .argument('<value>', 'the value')
+        .addOption(command.createOption('-t, --type <type>', 'the kind of file to write to').choices(fileTypes))
+        .addOption(command.createOption('-g, --global', 'write to the system file, like --type system').conflicts('type'))
+        .action(function (key, value, opts) {
+        let parsed = value;
+        if (command.opts().json) {
+            try {
+                parsed = JSON.parse(value);
+            }
+            catch {
+                this.error('error: value is not valid JSON');
+            }
+        }
+        const update = {};
+        setByString(update, key, parsed);
+        try {
+            manager.update(update, opts.global ? 'system' : (opts.type ?? options.defaultType));
+        }
+        catch (error) {
+            if (!(error instanceof z.ZodError))
+                throw error;
+            this.error('error: invalid value\n' + z.prettifyError(error));
+        }
+    });
+    command
+        .command('list')
+        .alias('ls')
+        .alias('files')
+        .description('List loaded config files')
+        .action(() => {
+        for (const path of manager.filePaths)
+            console.log(path);
+    });
+    command
+        .command('schema')
+        .description('Get the JSON schema for config files')
+        .action(() => output(z.toJSONSchema(manager.fileSchema, { io: 'input' })));
+    return command;
+}

package/dist/defaults.d.ts

@@ -0,0 +1,15 @@
+import * as z from 'zod';
+/**
+ * Remove `.default()` and `.prefault()` from a schema and everything nested within it.
+ */
+export declare function strip(schema: z.ZodType): z.ZodType;
+/**
+ * Compute a schema's default value from `.default()` on it and on anything nested within it.
+ * Members without a default are left out, so the result is not necessarily a complete config.
+ */
+export declare function of(schema: z.ZodType): unknown;
+/**
+ * Fill in defaults for anything missing from `value` in place, including within records, maps, arrays, and tuples.
+ */
+declare function _with(schema: z.ZodType, value: unknown): unknown;
+export { _with as with };

package/dist/defaults.js

@@ -0,0 +1,129 @@
+import * as z from 'zod';
+/**
+ * Remove `.default()` and `.prefault()` from a schema and everything nested within it.
+ */
+export function strip(schema) {
+    const def = schema._zod.def;
+    switch (def.type) {
+        case 'default':
+        case 'prefault':
+            return strip(def.innerType);
+        case 'object':
+            return z.core.clone(schema, {
+                ...def,
+                shape: Object.fromEntries(Object.entries(def.shape).map(([key, member]) => [key, strip(member)])),
+                catchall: def.catchall && strip(def.catchall),
+            });
+        case 'array':
+            return z.core.clone(schema, { ...def, element: strip(def.element) });
+        case 'record':
+        case 'map':
+        case 'set':
+            return z.core.clone(schema, { ...def, valueType: strip(def.valueType) });
+        case 'union':
+            return z.core.clone(schema, { ...def, options: def.options.map(strip) });
+        case 'tuple':
+            return z.core.clone(schema, {
+                ...def,
+                items: def.items.map(strip),
+                rest: def.rest && strip(def.rest),
+            });
+        case 'optional':
+        case 'nullable':
+        case 'readonly':
+        case 'nonoptional':
+        case 'catch':
+            return z.core.clone(schema, { ...def, innerType: strip(def.innerType) });
+        default:
+            return schema;
+    }
+}
+/**
+ * Compute a schema's default value from `.default()` on it and on anything nested within it.
+ * Members without a default are left out, so the result is not necessarily a complete config.
+ */
+export function of(schema) {
+    const def = schema._zod.def;
+    switch (def.type) {
+        case 'default':
+        case 'prefault':
+        case 'catch':
+            try {
+                return schema.parse(undefined);
+            }
+            catch {
+                return of(def.innerType);
+            }
+        case 'object': {
+            const value = {};
+            for (const [key, member] of Object.entries(def.shape)) {
+                const inner = of(member);
+                if (inner !== undefined)
+                    value[key] = inner;
+            }
+            return Object.keys(value).length ? value : undefined;
+        }
+        default:
+            return def.innerType ? of(def.innerType) : undefined;
+    }
+}
+/**
+ * Fill in defaults for anything missing from `value` in place, including within records, maps, arrays, and tuples.
+ */
+function _with(schema, value) {
+    const def = schema._zod.def;
+    switch (def.type) {
+        case 'default':
+        case 'prefault':
+        case 'catch':
+            return value === undefined ? of(schema) : _with(def.innerType, value);
+        case 'optional':
+        case 'nullable':
+        case 'readonly':
+        case 'nonoptional':
+            return value == null ? value : _with(def.innerType, value);
+        case 'object': {
+            if (typeof value != 'object' || value === null)
+                return value;
+            const object = value;
+            for (const [key, member] of Object.entries(def.shape)) {
+                const filled = _with(member, object[key]);
+                if (filled !== undefined)
+                    object[key] = filled;
+            }
+            return object;
+        }
+        case 'record': {
+            if (typeof value != 'object' || value === null)
+                return value;
+            const record = value;
+            for (const key of Object.keys(record))
+                record[key] = _with(def.valueType, record[key]);
+            return record;
+        }
+        case 'map':
+            if (!(value instanceof Map))
+                return value;
+            for (const [key, entry] of value)
+                value.set(key, _with(def.valueType, entry));
+            return value;
+        case 'array':
+            if (!Array.isArray(value))
+                return value;
+            for (let i = 0; i < value.length; i++)
+                value[i] = _with(def.element, value[i]);
+            return value;
+        case 'tuple':
+            if (!Array.isArray(value))
+                return value;
+            for (let i = 0; i < value.length; i++) {
+                const item = i < def.items.length ? def.items[i] : def.rest;
+                if (item)
+                    value[i] = _with(item, value[i]);
+            }
+            return value;
+        default:
+            return value;
+    }
+}
+export { _with as with };

package/dist/manager.js

@@ -39,6 +39,7 @@ import { homedir } from 'node:os';
 import { dirname, join, resolve, sep } from 'node:path';
 import { deepAssign, getByString, memoize, setByString } from 'utilium';
 import * as z from 'zod';
+import * as defaults from './defaults.js';
 const kInit = Symbol.for('LoadOptions:init');
 const include = z.string().array().optional();
 function canInclude(options, file) {
@@ -63,74 +64,6 @@ function typeFromPath(path) {
 function withExtension(path) {
     return path.endsWith('.json') ? path : path + '.json';
 }
-/**
- * Remove `.default()` and `.prefault()` from a schema and everything nested within it.
- */
-function stripDefaults(schema) {
-    const def = schema._zod.def;
-    switch (def.type) {
-        case 'default':
-        case 'prefault':
-            return stripDefaults(def.innerType);
-        case 'object':
-            return z.core.clone(schema, {
-                ...def,
-                shape: Object.fromEntries(Object.entries(def.shape).map(([key, member]) => [key, stripDefaults(member)])),
-                catchall: def.catchall && stripDefaults(def.catchall),
-            });
-        case 'array':
-            return z.core.clone(schema, { ...def, element: stripDefaults(def.element) });
-        case 'record':
-        case 'map':
-        case 'set':
-            return z.core.clone(schema, { ...def, valueType: stripDefaults(def.valueType) });
-        case 'union':
-            return z.core.clone(schema, { ...def, options: def.options.map(stripDefaults) });
-        case 'tuple':
-            return z.core.clone(schema, {
-                ...def,
-                items: def.items.map(stripDefaults),
-                rest: def.rest && stripDefaults(def.rest),
-            });
-        case 'optional':
-        case 'nullable':
-        case 'readonly':
-        case 'nonoptional':
-        case 'catch':
-            return z.core.clone(schema, { ...def, innerType: stripDefaults(def.innerType) });
-        default:
-            return schema;
-    }
-}
-/**
- * Compute a schema's default value from `.default()` on it and on anything nested within it.
- * Members without a default are left out, so the result is not necessarily a complete config.
- */
-function defaultsOf(schema) {
-    const def = schema._zod.def;
-    switch (def.type) {
-        case 'default':
-        case 'prefault':
-        case 'catch':
-            try {
-                return schema.parse(undefined);
-            }
-            catch {
-                return defaultsOf(def.innerType);
-            }
-        case 'object': {
-            const value = {};
-            for (const [key, member] of Object.entries(def.shape)) {
-                const inner = defaultsOf(member);
-                if (inner !== undefined)
-                    value[key] = inner;
-            }
-            return Object.keys(value).length ? value : undefined;
-        }
-        default:
-            return def.innerType ? defaultsOf(def.innerType) : undefined;
-    }
-}
 /**
  * Manager for configuration files
  */
@@ -163,7 +96,7 @@ let Manager = (() => {
             super({ captureRejections: true });
             this.schema = schema;
             this.options = options;
-            this.fileSchema = z.deepPartial(stripDefaults(z.object(options.enableIncludes ? { ...schema.shape, include } : schema.shape)));
+            this.fileSchema = z.deepPartial(defaults.strip(z.object(options.enableIncludes ? { ...schema.shape, include } : schema.shape)));
             this.data = this.schema.parse(this.defaults);
         }
         /**
@@ -178,7 +111,7 @@ let Manager = (() => {
          * A fresh config with only the schema's defaults applied.
          */
         get defaults() {
-            return structuredClone(defaultsOf(this.schema) ?? {});
+            return structuredClone(defaults.of(this.schema) ?? {});
         }
         get(key) {
             return getByString(this.data, key);
@@ -191,6 +124,7 @@ let Manager = (() => {
          */
         merge(config) {
             deepAssign(this.data, structuredClone(config), { replaceArrays: true });
+            defaults.with(this.schema, this.data);
             this.emit('change');
         }
         /** Replace the current config with `config`, applying defaults for anything missing. */

package/package.json

@@ -1,14 +1,25 @@
 {
 	"name": "@james-pre/config",
-	"version": "1.1.0",
+	"version": "1.2.1",
 	"description": "Manage configuration files",
+	"author": "James Prevett <jp@jamespre.dev> (https://jamespre.dev)",
+	"license": "LGPL-3.0-or-later",
 	"funding": {
 		"type": "individual",
 		"url": "https://github.com/sponsors/james-pre"
 	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/james-pre/common.git",
+		"directory": "packages/config"
+	},
+	"homepage": "https://github.com/james-pre/common/tree/main/packages/config#readme",
+	"bugs": {
+		"url": "https://github.com/james-pre/common/issues"
+	},
+	"type": "module",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
-	"type": "module",
 	"exports": {
 		".": "./dist/index.js",
 		"./*": "./dist/*.js"
@@ -18,51 +29,24 @@
 		"README.md"
 	],
 	"scripts": {
-		"format:check": "prettier --check .",
-		"format": "prettier --write .",
-		"build": "tsc -b",
-		"lint": "tsc -b --noEmit && eslint src",
-		"prepublishOnly": "npx tsc"
+		"build": "tsc"
 	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/james-pre/config"
-	},
-	"author": "James Prevett <jp@jamespre.dev> (https://jamespre.dev)",
-	"license": "LGPL-3.0-or-later",
-	"bugs": {
-		"url": "https://github.com/james-pre/config/issues"
-	},
-	"homepage": "https://github.com/james-pre/config#readme",
 	"engines": {
 		"node": ">=22.0.0"
 	},
 	"peerDependencies": {
+		"commander": "^15.0.0",
 		"utilium": "^3.7.0",
 		"zod": "^4.5.0"
 	},
+	"peerDependenciesMeta": {
+		"commander": {
+			"optional": true
+		}
+	},
 	"publishConfig": {
 		"provenance": true,
 		"access": "public"
 	},
-	"devDependencies": {
-		"@eslint/js": "^10.0.1",
-		"@types/node": "^24.7.0",
-		"eslint": "^10.1.0",
-		"globals": "^17.4.0",
-		"prettier": "^3.2.5",
-		"typedoc": "^0.28.18",
-		"typescript": "^6.0.2",
-		"typescript-eslint": "^8.58.0"
-	},
-	"prettier": {
-		"singleQuote": true,
-		"useTabs": true,
-		"trailingComma": "es5",
-		"tabWidth": 4,
-		"printWidth": 120,
-		"arrowParens": "avoid",
-		"experimentalOperatorPosition": "start"
-	},
 	"sideEffects": false
 }