@james-pre/config 1.0.2 → 1.2.0

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/manager.d.ts

@@ -58,7 +58,7 @@ export interface ManagerOptions {
 /**
  * Manager for configuration files
  */
-export declare class Manager<LoadOpts extends LoadOptions = LoadOptions, Shape extends Readonly<Record<string, z.ZodType>> = Readonly<Record<string, z.ZodType>>, out In extends z.input<z.ZodObject<Shape>> = z.input<z.ZodObject<Shape>>, out FileData = z.output<ReturnType<typeof z.deepPartial<z.ZodObject<Shape>>>>> extends EventEmitter<{
+export declare class Manager<Schema extends z.ZodObject, LoadOpts extends LoadOptions = LoadOptions, out In extends z.input<Schema> = z.input<Schema>, out FileData = z.output<ReturnType<typeof z.deepPartial<Schema>>>> extends EventEmitter<{
     load: [path: string, config: FileData, options: Partial<LoadOpts>];
     post_load: [path: string, config: FileData, options: Partial<LoadOpts>];
     load_error: [path: string, stage: 'read' | 'create' | 'parse', error: Error];
@@ -67,19 +67,26 @@ export declare class Manager<LoadOpts extends LoadOptions = LoadOptions, Shape e
     write: [path: string, data: FileData];
     reload: [];
 }> {
+    readonly schema: Schema;
     protected options: ManagerOptions;
-    readonly schema: z.ZodObject<Shape>;
-    readonly fileSchema: ReturnType<typeof z.deepPartial<z.ZodObject<Shape>>>;
-    protected readonly files: Map<string, File<FileData>>;
+    readonly fileSchema: ReturnType<typeof z.deepPartial<Schema>>;
+    protected readonly _files: Map<string, File<FileData, LoadOpts>>;
     get filePaths(): MapIterator<string>;
-    readonly data: z.output<z.ZodObject<Shape>>;
-    constructor(shape: Shape, options?: ManagerOptions);
+    get files(): IteratorObject<Readonly<File<FileData, LoadOpts>>>;
+    configAt(path: string): Readonly<FileData> | undefined;
+    readonly data: z.output<Schema>;
+    constructor(schema: Schema, options?: ManagerOptions);
+    /**
+     * Narrow the type of this manager's load options
+     */
+    $loadOptions<O extends object>(): Manager<Schema, LoadOpts & O, In, FileData>;
+    $assertLoadOptions<O extends object>(): asserts this is Manager<Schema, LoadOpts & O, In, FileData>;
     /**
      * A fresh config with only the schema's defaults applied.
      */
-    get defaults(): z.output<z.ZodObject<Shape>> & In;
-    get<const K extends string | number = FlattenKeys<z.output<z.ZodObject<Shape>>>>(key: K): GetByString<z.output<z.ZodObject<Shape>>, K>;
-    set<const K extends string | number = FlattenKeys<z.output<z.ZodObject<Shape>>>, V = GetByString<z.output<z.ZodObject<Shape>>, K>>(key: K, value: V): void;
+    get defaults(): z.output<Schema> & In;
+    get<const K extends string | number = FlattenKeys<z.output<Schema>>>(key: K): GetByString<z.output<Schema>, K>;
+    set<const K extends string | number = FlattenKeys<z.output<Schema>>, V = GetByString<z.output<Schema>, K>>(key: K, value: V): void;
     /**
      * Deeply merge `config` into the current config. Arrays are replaced rather than combined.
      */
@@ -88,8 +95,8 @@ export declare class Manager<LoadOpts extends LoadOptions = LoadOptions, Shape e
     replace(config: In): void;
     loadFile(path: string, options: Partial<LoadOpts>): void;
     /** Get the entry for `path`, adding one for a file that has not been loaded */
-    protected fileAt(path: string): File<FileData>;
-    protected writeFile(file: File<FileData>): void;
+    protected fileAt(path: string): File<FileData, LoadOpts>;
+    protected writeFile(file: File<FileData, LoadOpts>): void;
     /**
      * Replace the contents of the config file at `path` and write it,
      * then rebuild the current config from the defaults and all loaded files.

package/dist/manager.js

@@ -145,21 +145,35 @@ let Manager = (() => {
             __esDecorate(this, null, _get_defaultPaths_decorators, { kind: "getter", name: "defaultPaths", static: false, private: false, access: { has: obj => "defaultPaths" in obj, get: obj => obj.defaultPaths }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
-        options = __runInitializers(this, _instanceExtraInitializers);
-        schema;
+        schema = __runInitializers(this, _instanceExtraInitializers);
+        options;
         fileSchema;
-        files = new Map();
+        _files = new Map();
         get filePaths() {
-            return this.files.keys();
+            return this._files.keys();
+        }
+        get files() {
+            return this._files.values().map(f => structuredClone(f));
+        }
+        configAt(path) {
+            return structuredClone(this._files.get(path)?.data);
         }
         data;
-        constructor(shape, options = {}) {
+        constructor(schema, options = {}) {
             super({ captureRejections: true });
+            this.schema = schema;
             this.options = options;
-            this.schema = z.object(shape);
-            this.fileSchema = z.deepPartial(stripDefaults(z.object(options.enableIncludes ? { ...shape, include } : shape)));
+            this.fileSchema = z.deepPartial(stripDefaults(z.object(options.enableIncludes ? { ...schema.shape, include } : schema.shape)));
             this.data = this.schema.parse(this.defaults);
         }
+        /**
+         * Narrow the type of this manager's load options
+         */
+        $loadOptions() {
+            this.$assertLoadOptions();
+            return this;
+        }
+        $assertLoadOptions() { }
         /**
          * A fresh config with only the schema's defaults applied.
          */
@@ -187,7 +201,7 @@ let Manager = (() => {
             this.emit('change');
         }
         loadFile(path, options) {
-            if (this.files.has(path))
+            if (this._files.has(path))
                 return;
             let json;
             try {
@@ -223,7 +237,7 @@ let Manager = (() => {
                 this.emit('load_error', path, 'parse', e);
                 file = json;
             }
-            this.files.set(path, {
+            this._files.set(path, {
                 auto: false,
                 wasIncluded: false,
                 type: typeFromPath(path),
@@ -247,7 +261,7 @@ let Manager = (() => {
         }
         /** Get the entry for `path`, adding one for a file that has not been loaded */
         fileAt(path) {
-            const existing = this.files.get(path);
+            const existing = this._files.get(path);
             if (existing)
                 return existing;
             const file = {
@@ -258,7 +272,7 @@ let Manager = (() => {
                 wasIncluded: false,
                 options: {},
             };
-            this.files.set(path, file);
+            this._files.set(path, file);
             return file;
         }
         writeFile(file) {
@@ -275,7 +289,7 @@ let Manager = (() => {
             file.data = this.fileSchema.parse(config);
             this.writeFile(file);
             this.replace(this.defaults);
-            for (const file of this.files.values())
+            for (const file of this._files.values())
                 this.merge(file.data);
         }
         /**
@@ -313,7 +327,7 @@ let Manager = (() => {
          * the most recently loaded file of that type, or the path `loadDefaults` would use for it.
          */
         findPath(type) {
-            const loaded = this.files
+            const loaded = this._files
                 .values()
                 .filter(file => (!type || file.type == type) && !file.wasIncluded)
                 .map(file => file.path)
@@ -332,11 +346,11 @@ let Manager = (() => {
             this.updateFile(this.findPath(type), config);
         }
         reloadFiles(options = {}) {
-            const files = this.files
+            const files = this._files
                 .values()
                 .filter(file => !file.wasIncluded)
                 .toArray();
-            this.files.clear();
+            this._files.clear();
             this.replace(this.defaults);
             for (const file of files) {
                 this.loadFile(file.path, { ...options, [kInit]: { type: file.type, auto: file.auto } });

package/package.json

@@ -1,14 +1,25 @@
 {
 	"name": "@james-pre/config",
-	"version": "1.0.2",
+	"version": "1.2.0",
 	"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
 }