@james-pre/config 0.0.1

package/LICENSE.md

@@ -0,0 +1,157 @@
+# GNU LESSER GENERAL PUBLIC LICENSE
+
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc.
+<https://fsf.org/>
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+This version of the GNU Lesser General Public License incorporates the
+terms and conditions of version 3 of the GNU General Public License,
+supplemented by the additional permissions listed below.
+
+## 0. Additional Definitions.
+
+As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the
+GNU General Public License.
+
+"The Library" refers to a covered work governed by this License, other
+than an Application or a Combined Work as defined below.
+
+An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A "Combined Work" is a work produced by combining or linking an
+Application with the Library. The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+## 1. Exception to Section 3 of the GNU GPL.
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+## 2. Conveying Modified Versions.
+
+If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+- a) under this License, provided that you make a good faith effort
+  to ensure that, in the event an Application does not supply the
+  function or data, the facility still operates, and performs
+  whatever part of its purpose remains meaningful, or
+- b) under the GNU GPL, with none of the additional permissions of
+  this License applicable to that copy.
+
+## 3. Object Code Incorporating Material from Library Header Files.
+
+The object code form of an Application may incorporate material from a
+header file that is part of the Library. You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+- a) Give prominent notice with each copy of the object code that
+  the Library is used in it and that the Library and its use are
+  covered by this License.
+- b) Accompany the object code with a copy of the GNU GPL and this
+  license document.
+
+## 4. Combined Works.
+
+You may convey a Combined Work under terms of your choice that, taken
+together, effectively do not restrict modification of the portions of
+the Library contained in the Combined Work and reverse engineering for
+debugging such modifications, if you also do each of the following:
+
+- a) Give prominent notice with each copy of the Combined Work that
+  the Library is used in it and that the Library and its use are
+  covered by this License.
+- b) Accompany the Combined Work with a copy of the GNU GPL and this
+  license document.
+- c) For a Combined Work that displays copyright notices during
+  execution, include the copyright notice for the Library among
+  these notices, as well as a reference directing the user to the
+  copies of the GNU GPL and this license document.
+- d) Do one of the following:
+    -   0. Convey the Minimal Corresponding Source under the terms of
+           this License, and the Corresponding Application Code in a form
+           suitable for, and under terms that permit, the user to
+           recombine or relink the Application with a modified version of
+           the Linked Version to produce a modified Combined Work, in the
+           manner specified by section 6 of the GNU GPL for conveying
+           Corresponding Source.
+    -   1. Use a suitable shared library mechanism for linking with
+           the Library. A suitable mechanism is one that (a) uses at run
+           time a copy of the Library already present on the user's
+           computer system, and (b) will operate properly with a modified
+           version of the Library that is interface-compatible with the
+           Linked Version.
+- e) Provide Installation Information, but only if you would
+  otherwise be required to provide such information under section 6
+  of the GNU GPL, and only to the extent that such information is
+  necessary to install and execute a modified version of the
+  Combined Work produced by recombining or relinking the Application
+  with a modified version of the Linked Version. (If you use option
+  4d0, the Installation Information must accompany the Minimal
+  Corresponding Source and Corresponding Application Code. If you
+  use option 4d1, you must provide the Installation Information in
+  the manner specified by section 6 of the GNU GPL for conveying
+  Corresponding Source.)
+
+## 5. Combined Libraries.
+
+You may place library facilities that are a work based on the Library
+side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+- a) Accompany the combined library with a copy of the same work
+  based on the Library, uncombined with any other library
+  facilities, conveyed under the terms of this License.
+- b) Give prominent notice with the combined library that part of it
+  is a work based on the Library, and explaining where to find the
+  accompanying uncombined form of the same work.
+
+## 6. Revised Versions of the GNU Lesser General Public License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Library
+as you received it specifies that a certain numbered version of the
+GNU Lesser General Public License "or any later version" applies to
+it, you have the option of following the terms and conditions either
+of that published version or of any later version published by the
+Free Software Foundation. If the Library as you received it does not
+specify a version number of the GNU Lesser General Public License, you
+may choose any version of the GNU Lesser General Public License ever
+published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/README.md

@@ -0,0 +1,3 @@
+# @james-pre/config
+
+A small library for managing configuration files.

package/dist/core.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Get a human-readable string for a date that also fits into CLIs well (fixed-width)
+ */
+export declare function prettyDate(date: Date): string;
+export declare let _debugOutput: boolean;
+/**
+ * Enable or disable debug output.
+ */
+export declare function _setDebugOutput(enabled: boolean): void;
+export declare function start(message: string): Disposable;
+export declare let progress: (value: number, max: number, message?: any, valueText?: string) => void;
+export declare let done: (noPrint?: boolean) => void;
+export interface ProgressIO {
+    start(message: string): void;
+    progress(value: number, max: number, message?: any, valueText?: string): void;
+    done(noPrint?: boolean): void;
+}
+export declare function useProgress(io: ProgressIO): void;
+export declare let debug: (...args: any[]) => void;
+export declare let log: (...args: any[]) => void;
+export declare let info: (...args: any[]) => void;
+export declare let warn: (...args: any[]) => void;
+export declare let error: (...args: any[]) => void;
+export interface ConsoleLike {
+    debug(...args: any[]): void;
+    log(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+}
+export declare function useOutput(output: ConsoleLike): void;
+export declare function warnOnce(...args: any[]): void;
+/**
+ * This is a factory for handling errors when performing operations.
+ * The handler will allow the parent scope to continue if certain errors occur,
+ * rather than fatally exiting.
+ */
+export declare function someWarnings(...allowList: [RegExp, string?][]): (error: string | Error) => void;
+export declare function errorText(error: unknown): string;
+/** @hidden @internal for other APIs that take a `Console` but check `.constructor.name` */
+export declare const constructor: {
+    name: string;
+};

package/dist/core.js

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+/* eslint-disable @typescript-eslint/only-throw-error */
+const _month = new Intl.DateTimeFormat(undefined, { month: 'short' });
+// Shortcut to convert to 2-digit. Mostly used to make the line shorter.
+const _2 = (v) => v.toString().padStart(2, '0');
+/**
+ * Get a human-readable string for a date that also fits into CLIs well (fixed-width)
+ */
+export function prettyDate(date) {
+    return `${date.getFullYear()} ${_month.format(date)} ${_2(date.getDate())} ${_2(date.getHours())}:${_2(date.getMinutes())}:${_2(date.getSeconds())}.${date.getMilliseconds().toString().padStart(3, '0')}`;
+}
+export let _debugOutput = false;
+/**
+ * Enable or disable debug output.
+ */
+export function _setDebugOutput(enabled) {
+    _debugOutput = enabled;
+}
+// I/O for "progressive" actions
+let _start;
+export function start(message) {
+    _start(message);
+    return { [Symbol.dispose]: () => done(true) };
+}
+export let progress;
+export let done;
+export function useProgress(io) {
+    _start = io.start.bind(io);
+    progress = io.progress.bind(io);
+    done = io.done.bind(io);
+}
+// User-facing messaging
+export let debug = console.debug;
+export let log = console.log;
+export let info = console.info;
+export let warn = console.warn;
+export let error = console.error;
+export function useOutput(output) {
+    debug = output.debug.bind(output);
+    log = output.log.bind(output);
+    info = output.info.bind(output);
+    warn = output.warn.bind(output);
+    error = output.error.bind(output);
+}
+const _warned = new Set();
+export function warnOnce(...args) {
+    const key = args.map(String).join(' ');
+    if (_warned.has(key))
+        return;
+    _warned.add(key);
+    warn(...args);
+}
+/**
+ * This is a factory for handling errors when performing operations.
+ * The handler will allow the parent scope to continue if certain errors occur,
+ * rather than fatally exiting.
+ */
+export function someWarnings(...allowList) {
+    return (error) => {
+        error = typeof error == 'object' && 'message' in error ? error.message : error;
+        for (const [pattern, message = error] of allowList) {
+            if (!pattern.test(error))
+                continue;
+            warn(message);
+            return;
+        }
+        throw error;
+    };
+}
+const zod = await import('zod/v4/core').catch(() => null);
+export function errorText(error) {
+    if (zod && error instanceof zod.$ZodError)
+        return zod.prettifyError(error);
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+/** @hidden @internal for other APIs that take a `Console` but check `.constructor.name` */
+export const constructor = { name: 'Console' };

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './manager.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+export * from './manager.js';

package/dist/jobs.d.ts

@@ -0,0 +1,48 @@
+export interface JobResult {
+    status: 'succeeded' | 'failed';
+    text: {
+        toString(): string;
+    };
+}
+export declare function useClear(clear: (lastDrawLineCount: number) => void): void;
+export declare function useDraw(draw: (lines: string[]) => void): void;
+export declare function useResultFormat(format: (result: JobResult) => string): void;
+/** @internal */
+export declare function _disableInPlaceUpdates(): void;
+export interface Options {
+    concurrency: number;
+    jobStartText?: string;
+}
+export interface Results {
+    failed: number;
+    noJobs?: boolean;
+}
+export interface Context {
+    nextIndex: number;
+    remaining: number;
+    failed: number;
+    finished: number;
+    prefix(i: number, number?: number): string;
+}
+export interface JobContext {
+    progress(this: void, ...args: any[]): void;
+}
+type JobFn = (context: JobContext) => JobResult | Promise<JobResult>;
+export type Job = JobFn | {
+    run: JobFn;
+    name?: string;
+};
+/**
+ * A position in a job list that enforces job ordering.
+ * Every job before it finishes before any job after it starts.
+ * It is not work of its own, so it is not counted or numbered.
+ */
+export declare const barrier: unique symbol;
+export declare function run(options: Options, entries: (Job | typeof barrier)[]): Promise<Results>;
+export interface OptionsWithData<T> extends Options {
+    run(data: T, progress: (...args: any[]) => void): JobResult | Promise<JobResult>;
+    name?(data: T): string | undefined;
+    group?(data: T): unknown;
+}
+export declare function runWithData<T>(options: OptionsWithData<T>, data: T[]): Promise<Results>;
+export {};

package/dist/jobs.js

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import * as io from './core.js';
+let clearActiveLines, drawActiveLines, formatJobResult = (result) => result.text ? result.text.toString() : result.status == 'failed' ? 'failed' : 'done', _noInPlaceUpdate = false;
+export function useClear(clear) {
+    clearActiveLines = clear;
+}
+export function useDraw(draw) {
+    drawActiveLines = draw;
+}
+export function useResultFormat(format) {
+    formatJobResult = format;
+}
+/** @internal */
+export function _disableInPlaceUpdates() {
+    _noInPlaceUpdate = true;
+}
+/**
+ * A position in a job list that enforces job ordering.
+ * Every job before it finishes before any job after it starts.
+ * It is not work of its own, so it is not counted or numbered.
+ */
+export const barrier = Symbol('ioium.jobs.barrier');
+export async function run(options, entries) {
+    const jobs = [];
+    const segments = [];
+    for (const entry of entries) {
+        if (entry !== barrier) {
+            jobs.push(entry);
+            continue;
+        }
+        if (jobs.length && segments.at(-1) !== jobs.length)
+            segments.push(jobs.length);
+    }
+    if (!jobs.length) {
+        return { failed: 0, noJobs: true };
+    }
+    if (segments.at(-1) !== jobs.length)
+        segments.push(jobs.length);
+    const totalWidth = jobs.length.toString().length;
+    const $ = {
+        nextIndex: 0,
+        remaining: jobs.length,
+        failed: 0,
+        finished: 0,
+        prefix(i, number = i + 1) {
+            let prefix = `[${number.toString().padStart(totalWidth)}/${jobs.length}]`;
+            if (typeof jobs[i] === 'object' && jobs[i].name)
+                prefix += ' ' + jobs[i].name;
+            return prefix;
+        },
+    };
+    const activeJobs = [];
+    let lastDrawLineCount = 0;
+    function _draw() {
+        if (_noInPlaceUpdate)
+            return;
+        drawActiveLines?.(activeJobs.map((j, i) => `${$.prefix(j.index, $.finished + 1 + i)} ${j.message}`));
+        lastDrawLineCount = activeJobs.length;
+    }
+    function _clear() {
+        if (!lastDrawLineCount || _noInPlaceUpdate)
+            return;
+        clearActiveLines?.(lastDrawLineCount);
+        lastDrawLineCount = 0;
+    }
+    async function nextJob(limit, noInitialDraw = false) {
+        if ($.nextIndex >= limit)
+            return;
+        const index = $.nextIndex++;
+        const job = { message: options.jobStartText || 'starting...', index };
+        if (!_noInPlaceUpdate && !noInitialDraw)
+            _clear();
+        activeJobs.push(job);
+        if (_noInPlaceUpdate)
+            io.log($.prefix(index, $.finished + activeJobs.length), job.message);
+        else if (!noInitialDraw)
+            _draw();
+        function progress(...args) {
+            const line = args.join(' ').trim();
+            if (!line)
+                return;
+            job.message = line;
+            _clear();
+            _draw();
+        }
+        const runJob = typeof jobs[index] === 'function' ? jobs[index] : jobs[index].run;
+        let result;
+        try {
+            result = await runJob({ progress });
+        }
+        catch (e) {
+            result = { status: 'failed', text: io.errorText(e) };
+        }
+        if (result.status == 'failed')
+            $.failed++;
+        _clear();
+        io.log($.prefix(index, ++$.finished), formatJobResult(result));
+        const jobIdx = activeJobs.indexOf(job);
+        if (jobIdx === -1)
+            throw new Error('BUG: Could not remove a job from the active jobs list');
+        activeJobs.splice(jobIdx, 1);
+        _draw();
+        $.remaining--;
+        return await nextJob(limit);
+    }
+    for (const end of segments) {
+        const allDone = [];
+        for (let i = 0; i < options.concurrency; i++) {
+            if ($.nextIndex >= end)
+                break;
+            allDone.push(nextJob(end, true));
+        }
+        _clear();
+        _draw();
+        await Promise.all(allDone);
+    }
+    return { failed: $.failed };
+}
+export async function runWithData(options, data) {
+    const entries = [];
+    let previous;
+    for (const [i, d] of data.entries()) {
+        if (options.group) {
+            const group = options.group(d);
+            if (i && !Object.is(group, previous))
+                entries.push(barrier);
+            previous = group;
+        }
+        entries.push({
+            run: (context) => options.run(d, context.progress),
+            name: options.name?.(d),
+        });
+    }
+    return await run(options, entries);
+}

package/dist/manager.d.ts

@@ -0,0 +1,123 @@
+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;
+}
+/**
+ * Manager 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>>, out FileData = z.output<ReturnType<typeof z.deepPartial<z.ZodObject<Shape>>>>> extends EventEmitter<{
+    load: [path: string, config: FileData];
+    post_load: [path: string, config: FileData];
+    load_error: [path: string, stage: 'read' | 'create' | 'parse', error: Error];
+    create: [path: string];
+    change: [];
+    write: [path: string, data: FileData];
+    reload: [];
+}> {
+    protected options: ManagerOptions;
+    readonly schema: z.ZodObject<Shape>;
+    readonly fileSchema: ReturnType<typeof z.deepPartial<z.ZodObject<Shape>>>;
+    protected files: Map<string, File<FileData>>;
+    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<FileData>;
+    protected writeFile(file: File<FileData>): 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 {};