@james-pre/config 0.0.1

package/dist/manager.js

@@ -0,0 +1,343 @@
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import EventEmitter from 'node:events';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+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';
+const kInit = Symbol.for('LoadOptions:init');
+const include = z.string().array().optional();
+function canInclude(options, file) {
+    return (!!options.enableIncludes
+        && typeof file === 'object'
+        && file !== null
+        && 'include' in file
+        && Array.isArray(file.include));
+}
+const xdgConfigDir = process.env.XDG_CONFIG_HOME
+    || (process.platform == 'win32' ? process.env.APPDATA : null)
+    || join(homedir(), '.config');
+const systemConfigDir = (process.platform == 'win32' ? process.env.PROGRAMDATA : null) || '/etc';
+function typeFromPath(path) {
+    if (path.startsWith(systemConfigDir + sep))
+        return 'system';
+    if (path.startsWith(xdgConfigDir + sep))
+        return 'user';
+    return 'local';
+}
+/** Resolve a `ManagerOptions` path, which may omit the `.json` extension */
+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
+ */
+let Manager = (() => {
+    let _classSuper = EventEmitter;
+    let _instanceExtraInitializers = [];
+    let _get_defaultPaths_decorators;
+    return class Manager extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _get_defaultPaths_decorators = [memoize];
+            __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;
+        fileSchema;
+        files = new Map();
+        data;
+        constructor(shape, options = {}) {
+            super({ captureRejections: true });
+            this.options = options;
+            this.schema = z.object(shape);
+            this.fileSchema = z.deepPartial(stripDefaults(z.object(options.enableIncludes ? { ...shape, include } : shape)));
+            this.data = this.schema.parse(this.defaults);
+        }
+        /**
+         * A fresh config with only the schema's defaults applied.
+         */
+        get defaults() {
+            return structuredClone(defaultsOf(this.schema) ?? {});
+        }
+        get(key) {
+            return getByString(this.data, key);
+        }
+        set(key, value) {
+            setByString(this.data, key, value);
+        }
+        /**
+         * Deeply merge `config` into the current config. Arrays are replaced rather than combined.
+         */
+        merge(config) {
+            deepAssign(this.data, structuredClone(config), { replaceArrays: true });
+            this.emit('change');
+        }
+        /** Replace the current config with `config`, applying defaults for anything missing. */
+        replace(config) {
+            for (const key of Object.keys(this.data))
+                delete this.data[key];
+            Object.assign(this.data, this.schema.parse(config));
+            this.emit('change');
+        }
+        loadFile(path, options) {
+            if (this.files.has(path))
+                return;
+            let json;
+            try {
+                json = JSON.parse(readFileSync(path, 'utf8'));
+            }
+            catch (e) {
+                if (!options.create || e.code != 'ENOENT') {
+                    if (!options.optional)
+                        throw e;
+                    this.emit('load_error', path, 'read', e);
+                    return;
+                }
+                try {
+                    mkdirSync(dirname(path), { recursive: true });
+                    writeFileSync(path, '{}', 'utf-8');
+                }
+                catch (e) {
+                    if (!options.optional)
+                        throw e;
+                    this.emit('load_error', path, 'create', e);
+                    return;
+                }
+                this.emit('create', path);
+                json = {};
+            }
+            let file;
+            try {
+                file = this.fileSchema.parse(json);
+            }
+            catch (e) {
+                if (!options.loose)
+                    throw e;
+                this.emit('load_error', path, 'parse', e);
+                file = json;
+            }
+            this.files.set(path, {
+                auto: false,
+                wasIncluded: false,
+                type: typeFromPath(path),
+                ...(options[kInit] || {}),
+                data: file,
+                path,
+            });
+            this.merge(file);
+            this.emit('load', path, file);
+            if (canInclude(this.options, file))
+                for (const include of file.include ?? []) {
+                    this.loadFile(resolve(dirname(path), include), {
+                        ...options,
+                        optional: true,
+                        create: false,
+                        [kInit]: { ...options[kInit], wasIncluded: true },
+                    });
+                }
+            this.emit('post_load', path, file);
+        }
+        /** Get the entry for `path`, adding one for a file that has not been loaded */
+        fileAt(path) {
+            const existing = this.files.get(path);
+            if (existing)
+                return existing;
+            const file = {
+                path,
+                data: {},
+                type: typeFromPath(path),
+                auto: false,
+                wasIncluded: false,
+            };
+            this.files.set(path, file);
+            return file;
+        }
+        writeFile(file) {
+            mkdirSync(dirname(file.path), { recursive: true });
+            writeFileSync(file.path, JSON.stringify(file.data, null, '\t'), 'utf-8');
+            this.emit('write', file.path, file.data);
+        }
+        /**
+         * Replace the contents of the config file at `path` and write it,
+         * then rebuild the current config from the defaults and all loaded files.
+         */
+        replaceFile(path, config) {
+            const file = this.fileAt(path);
+            file.data = this.fileSchema.parse(config);
+            this.writeFile(file);
+            this.replace(this.defaults);
+            for (const file of this.files.values())
+                this.merge(file.data);
+        }
+        /**
+         * Merge `config` into the current config and into the config file at `path`, then write it.
+         */
+        updateFile(path, config) {
+            const file = this.fileAt(path);
+            deepAssign(file.data, this.fileSchema.parse(config), { replaceArrays: true });
+            this.merge(config);
+            this.writeFile(file);
+        }
+        /**
+         * The files `loadDefaults` will try to load, ordered from most global to most local.
+         * @internal
+         */
+        get defaultPaths() {
+            const paths = [];
+            const { system, xdg } = this.options;
+            if (system)
+                paths.push({ type: 'system', path: join(systemConfigDir, withExtension(system)) });
+            if (xdg)
+                paths.push({ type: 'user', path: join(xdgConfigDir, withExtension(xdg)) });
+            return paths;
+        }
+        /**
+         * Load the files from `defaultPaths`. Missing files are skipped unless `options` says otherwise.
+         */
+        loadDefaults(options) {
+            for (const { path, type } of this.defaultPaths) {
+                this.loadFile(path, { optional: true, ...options, [kInit]: { type, auto: true } });
+            }
+        }
+        /**
+         * The file a change of the given type is written to:
+         * the most recently loaded file of that type, or the path `loadDefaults` would use for it.
+         */
+        findPath(type) {
+            const loaded = this.files
+                .values()
+                .filter(file => (!type || file.type == type) && !file.wasIncluded)
+                .map(file => file.path)
+                .toArray();
+            if (loaded.length)
+                return loaded.at(-1);
+            const fallback = type ? this.defaultPaths.find(entry => entry.type == type) : this.defaultPaths.at(-1);
+            if (!fallback)
+                throw new Error(`No ${type ?? 'writable'} configuration file to write to`);
+            return fallback.path;
+        }
+        /**
+         * Merge `config` into the current config and save it.
+         */
+        update(config, type) {
+            this.updateFile(this.findPath(type), config);
+        }
+        reloadFiles(options) {
+            const files = this.files
+                .values()
+                .filter(file => !file.wasIncluded)
+                .toArray();
+            this.files.clear();
+            this.replace(this.defaults);
+            for (const file of files) {
+                this.loadFile(file.path, { ...options, [kInit]: { type: file.type, auto: file.auto } });
+            }
+            this.emit('reload');
+        }
+    };
+})();
+export { Manager };

package/dist/node/config.d.ts

@@ -0,0 +1,119 @@
+import EventEmitter from 'node:events';
+import type { FlattenKeys, GetByString, PartialRecursive } from 'utilium';
+import * as z from 'zod';
+export type FileType = 'system' | 'user' | 'local';
+/** Information about a loaded config file */
+interface File<Value> {
+    path: string;
+    wasIncluded: boolean;
+    data: Value;
+    type: FileType;
+    auto: boolean;
+}
+/**
+ * How a file is being loaded
+ * @internal
+ */
+interface FileLoadInit {
+    wasIncluded?: boolean;
+    type?: FileType;
+    auto?: boolean;
+}
+export interface LoadOptions {
+    /**
+     * If enabled, the config file will still be loaded if it does not match the schema.
+     */
+    loose?: boolean;
+    /**
+     * If enabled, the config file will be skipped if it does not exist.
+     */
+    optional?: boolean;
+    /**
+     * If enabled, an empty config file will be created when it does not exist.
+     * Included files are never created.
+     */
+    create?: boolean;
+    /**
+     * Used to mark files that are included, auto-loaded, etc.
+     * @internal
+     */
+    [kInit]?: FileLoadInit;
+}
+declare const kInit: unique symbol;
+export interface ManagerOptions {
+    /** If true, allow specifying `include: [...]` to load additional files */
+    enableIncludes?: boolean;
+    /**
+     * If set, try to load files in the XDG config directory (or the OS-equivalent).
+     * This corresponds to the relative path, though you can omit `.json`
+     */
+    xdg?: string;
+    /**
+     * Try to load system-wide configuration from `/etc` (or the OS-equivalent).
+     * Trailing `.json` can be omitted.
+     */
+    system?: string;
+}
+/**
+ * Manage for configuration files
+ */
+export declare class Manager<Shape extends Readonly<Record<string, z.ZodType>>, LoadOpts extends LoadOptions = LoadOptions, out In extends z.input<z.ZodObject<Shape>> = z.input<z.ZodObject<Shape>>> extends EventEmitter<{
+    load: [path: string, config: z.output<ReturnType<typeof z.deepPartial<z.ZodObject<Shape>>>>];
+    load_error: [path: string, stage: 'read' | 'create' | 'parse', error: Error];
+    change: [];
+}> {
+    protected options: ManagerOptions;
+    readonly schema: z.ZodObject<Shape>;
+    readonly fileSchema: ReturnType<typeof z.deepPartial<z.ZodObject<Shape>>>;
+    protected files: Map<string, File<z.output<typeof this.fileSchema>>>;
+    readonly data: z.output<z.ZodObject<Shape>>;
+    constructor(shape: Shape, options?: ManagerOptions);
+    /**
+     * 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;
+    /**
+     * Deeply merge `config` into the current config. Arrays are replaced rather than combined.
+     */
+    merge(config: PartialRecursive<In>): void;
+    /** Replace the current config with `config`, applying defaults for anything missing. */
+    replace(config: In): void;
+    loadFile(path: string, options: LoadOpts): void;
+    /** Get the entry for `path`, adding one for a file that has not been loaded */
+    protected fileAt(path: string): File<z.output<typeof this.fileSchema>>;
+    protected writeFile(file: File<z.output<typeof this.fileSchema>>): 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.
+     */
+    replaceFile(path: string, config: In): void;
+    /**
+     * Merge `config` into the current config and into the config file at `path`, then write it.
+     */
+    updateFile(path: string, config: PartialRecursive<In>): void;
+    /**
+     * The files `loadDefaults` will try to load, ordered from most global to most local.
+     * @internal
+     */
+    get defaultPaths(): ReadonlyArray<{
+        path: string;
+        type: FileType;
+    }>;
+    /**
+     * Load the files from `defaultPaths`. Missing files are skipped unless `options` says otherwise.
+     */
+    loadDefaults(options: LoadOpts): void;
+    /**
+     * The file a change of the given type is written to:
+     * the most recently loaded file of that type, or the path `loadDefaults` would use for it.
+     */
+    findPath(type?: FileType): string;
+    /**
+     * Merge `config` into the current config and save it.
+     */
+    update(config: PartialRecursive<In>, type?: FileType): void;
+    reloadFiles(options: LoadOpts): void;
+}
+export {};