depflow 3.0.0-dev.1 → 3.0.0-dev.11

package/dist/config/Config.js

@@ -0,0 +1,45 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Depflow main configuration store, persisted as JSON or YAML with generated comments.
+ * @license Apache-2.0
+ */
+import { Path } from '@netfeez/common-node';
+import schema from '../schema/schema.js';
+import Settings from './Settings.js';
+import JsonSchema from './JsonSchema.js';
+import JsonCodec from './codecs/JsonCodec.js';
+import YamlCodec from './codecs/YamlCodec.js';
+export class Config extends Settings {
+    static schema = schema.Config;
+    /**
+     * The formats of the config file, in resolution order.
+     *
+     * The YAML one carries the header of a generated file; the comments of each key come from the
+     * descriptions of the schema, on their own.
+     * @returns The JSON codec and the YAML codec of the config.
+     */
+    static get codecs() {
+        return [
+            new JsonCodec(),
+            new YamlCodec(schema.Config, {
+                header: [
+                    '# Depflow Configuration File',
+                    '# You can use the Red Hat extension for JSON schema validation in VSCode: "$schema: .depflow/schema.json"',
+                    '', ''
+                ]
+            })
+        ];
+    }
+    /**
+     * Saves the config and refreshes the editor JSON Schema under the project `.depflow` directory.
+     * @param path - The path to save the config file to.
+     * @returns A promise that resolves when the config and the editor schema have been written.
+     **/
+    async save(path = this.path) {
+        const dir = Path.dirname(path);
+        await super.save(path);
+        await JsonSchema.write(dir);
+    }
+}
+export default Config;
+//# sourceMappingURL=Config.js.map

package/dist/config/Config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Config.js","sourceRoot":"","sources":["../../src/config/Config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAG5C,OAAO,MAAM,MAAM,qBAAqB,CAAC;AACzC,OAAO,QAAQ,MAAM,eAAe,CAAC;AACrC,OAAO,UAAU,MAAM,iBAAiB,CAAC;AACzC,OAAO,SAAS,MAAM,uBAAuB,CAAC;AAC9C,OAAO,SAAS,MAAM,uBAAuB,CAAC;AAE9C,MAAM,OAAO,MAAO,SAAQ,QAAwC;IACtD,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAExC;;;;;;OAMG;IACO,MAAM,KAAc,MAAM;QAChC,OAAO;YACH,IAAI,SAAS,EAAE;YACf,IAAI,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE;gBACzB,MAAM,EAAE;oBACJ,8BAA8B;oBAC9B,2GAA2G;oBAC3G,EAAE,EAAE,EAAE;iBACT;aACJ,CAAC;SACL,CAAC;IACN,CAAC;IAED;;;;QAII;IACY,KAAK,CAAC,IAAI,CAAC,IAAI,GAAW,IAAI,CAAC,IAAK;QAChD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,MAAM,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;CACJ;AAID,eAAe,MAAM,CAAC"}

package/dist/config/ImportMap.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Updates and persists the import map file from compiled path aliases.
+ * @license Apache-2.0
+ */
+import { Logger } from '@netfeez/vterm';
+import schema from '../schema/schema.js';
+import Settings from './Settings.js';
+import type AliasCompiler from '../resolve/AliasCompiler.js';
+export declare class ImportMap extends Settings<typeof schema.ImportMap> {
+    protected static schema: import("@netfeez/schema").Schema<{
+        readonly type: "object";
+        readonly additional: true;
+        readonly default: {};
+        readonly keys: {
+            readonly imports: {
+                readonly type: "object";
+                readonly additional: true;
+                readonly default: {};
+                readonly description: "Mapping of bare specifiers to their resolved URLs or paths.";
+            };
+            readonly scopes: {
+                readonly type: "object";
+                readonly additional: true;
+                readonly default: {};
+                readonly description: "Scope-based mappings of bare specifiers to their resolved URLs or paths.";
+            };
+        };
+        readonly description: "Structure of an import map file.";
+    }>;
+    protected logger: Logger;
+    constructor(data: ImportMap.Data, options?: ImportMap.Options);
+    /**
+     * The formats of the import map file: JSON only, so it never reaches a YAML parser.
+     * @returns The JSON codec of the file.
+     */
+    protected static get codecs(): readonly Settings.AnyCodec[];
+    /**
+     * Updates the import map data based on the provided compiled aliases.
+     * It constructs an "imports" section where each alias is mapped to its target path.
+     * @param aliases - An array of compiled aliases.
+     * @param mode - The resolution mode ('local' or 'cdn').
+     */
+    updateImports(aliases: AliasCompiler.CompiledAlias[], mode: 'local' | 'cdn'): void;
+    /**
+     * Saves the current import map data to a file.
+     * It ensures that the directory for the file exists, converts the data to a JSON string with proper formatting, and writes it to the file system using the File.write method.
+     * The method also includes logging to inform users when the save operation is successful.
+     * @param path - The path to the import map file to save.
+     * @returns A promise that resolves when the save operation is complete, or rejects if an error occurs during the process.
+     */
+    save(path?: string): Promise<void>;
+}
+export declare namespace ImportMap {
+    type Data = schema.ImportMap.Root;
+    interface Options extends Settings.Options {
+        logger?: Logger;
+    }
+}
+export default ImportMap;

package/dist/config/ImportMap.js

@@ -0,0 +1,66 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Updates and persists the import map file from compiled path aliases.
+ * @license Apache-2.0
+ */
+import { Logger } from '@netfeez/vterm';
+import { Path } from '@netfeez/common-node';
+import schema from '../schema/schema.js';
+import Settings from './Settings.js';
+import JsonCodec from './codecs/JsonCodec.js';
+export class ImportMap extends Settings {
+    static schema = schema.ImportMap;
+    logger;
+    constructor(data, options = {}) {
+        super(data, options);
+        this.logger = options.logger || new Logger({ name: 'IMP-MAP' });
+    }
+    /**
+     * The formats of the import map file: JSON only, so it never reaches a YAML parser.
+     * @returns The JSON codec of the file.
+     */
+    static get codecs() { return [new JsonCodec()]; }
+    /**
+     * Updates the import map data based on the provided compiled aliases.
+     * It constructs an "imports" section where each alias is mapped to its target path.
+     * @param aliases - An array of compiled aliases.
+     * @param mode - The resolution mode ('local' or 'cdn').
+     */
+    updateImports(aliases, mode) {
+        if (!this.data.imports)
+            this.data.imports = {};
+        const projectRoot = Path.dirname(this.path);
+        for (const aliasObj of aliases) {
+            const key = aliasObj.isWildcard ? `${aliasObj.alias}/` : aliasObj.alias;
+            let target = mode === 'cdn' && aliasObj.targets.cdn
+                ? aliasObj.targets.cdn
+                : aliasObj.targets.local;
+            if (target === aliasObj.targets.local) {
+                target = Path.diff(projectRoot, target);
+                target = target.startsWith('.') ? target : `./${target}`;
+                target = Path.normalize(target);
+            }
+            if (aliasObj.isWildcard) {
+                if (!target.endsWith('/'))
+                    target += '/';
+            }
+            this.data.imports[key] = target;
+        }
+    }
+    /**
+     * Saves the current import map data to a file.
+     * It ensures that the directory for the file exists, converts the data to a JSON string with proper formatting, and writes it to the file system using the File.write method.
+     * The method also includes logging to inform users when the save operation is successful.
+     * @param path - The path to the import map file to save.
+     * @returns A promise that resolves when the save operation is complete, or rejects if an error occurs during the process.
+     */
+    async save(path = this.path) {
+        await super.save(path);
+        if (path !== this.path)
+            this.path = path;
+        const filename = Path.fileName(path);
+        this.logger.log(`&C2Saved file &C4${filename}`);
+    }
+}
+export default ImportMap;
+//# sourceMappingURL=ImportMap.js.map

package/dist/config/ImportMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImportMap.js","sourceRoot":"","sources":["../../src/config/ImportMap.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAE5C,OAAO,MAAM,MAAM,qBAAqB,CAAC;AACzC,OAAO,QAAQ,MAAM,eAAe,CAAC;AACrC,OAAO,SAAS,MAAM,uBAAuB,CAAC;AAI9C,MAAM,OAAO,SAAU,SAAQ,QAAiC;IAClD,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC;IACjC,MAAM,CAAS;IAEzB,YAAY,IAAoB,EAAE,OAAO,GAAsB,EAAE;QAC7D,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;IACpE,CAAC;IAED;;;OAGG;IACO,MAAM,KAAc,MAAM,KAAmC,OAAO,CAAE,IAAI,SAAS,EAAE,CAAE,CAAC,CAAC,CAAC;IAEpG;;;;;OAKG;IACI,aAAa,CAAC,OAAsC,EAAE,IAAqB;QAC9E,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAE/C,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAK,CAAC,CAAC;QAE7C,KAAK,MAAM,QAAQ,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,GAAG,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;YAExE,IAAI,MAAM,GAAG,IAAI,KAAK,KAAK,IAAI,QAAQ,CAAC,OAAO,CAAC,GAAG;gBAC/C,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG;gBACtB,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC;YAE7B,IAAI,MAAM,KAAK,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;gBACpC,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;gBACxC,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;gBACzD,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YACpC,CAAC;YACD,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;gBACtB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;oBAAE,MAAM,IAAI,GAAG,CAAC;YAC7C,CAAC;YAED,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;QACpC,CAAC;IACL,CAAC;IACD;;;;;;OAMG;IACI,KAAK,CAAC,IAAI,CAAC,IAAI,GAAW,IAAI,CAAC,IAAK;QACvC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,IAAI,KAAK,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,oBAAoB,QAAQ,EAAE,CAAC,CAAC;IACpD,CAAC;CACJ;AASD,eAAe,SAAS,CAAC"}

package/dist/config/JsonSchema.d.ts

@@ -0,0 +1,12 @@
+export declare namespace JsonSchema {
+    /**
+     * Writes the configuration JSON Schema to `<projectRoot>/.depflow/schema.json`.
+     * Editors and tools use the file to validate and autocomplete the config.
+     * Effectively replaces the pre-dispatch write that used to run on every CLI
+     * invocation with a write anchored to the project that owns the config.
+     * @param projectRoot - Absolute path of the directory containing the config file.
+     * @returns A promise that resolves when the schema file has been written.
+     **/
+    function write(projectRoot: string): Promise<void>;
+}
+export default JsonSchema;

package/dist/config/JsonSchema.js

@@ -0,0 +1,26 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Keeps the editor JSON Schema of the depflow configuration in sync under the project flow directory.
+ * @license Apache-2.0
+ */
+import { File, Path } from '@netfeez/common-node';
+import schema from '../schema/schema.js';
+export var JsonSchema;
+(function (JsonSchema) {
+    /**
+     * Writes the configuration JSON Schema to `<projectRoot>/.depflow/schema.json`.
+     * Editors and tools use the file to validate and autocomplete the config.
+     * Effectively replaces the pre-dispatch write that used to run on every CLI
+     * invocation with a write anchored to the project that owns the config.
+     * @param projectRoot - Absolute path of the directory containing the config file.
+     * @returns A promise that resolves when the schema file has been written.
+     **/
+    async function write(projectRoot) {
+        const path = Path.join(projectRoot, '.depflow', 'schema.json');
+        await File.ensureDir(Path.dirname(path));
+        await File.write(path, JSON.stringify(schema.Config.jsonSchema));
+    }
+    JsonSchema.write = write;
+})(JsonSchema || (JsonSchema = {}));
+export default JsonSchema;
+//# sourceMappingURL=JsonSchema.js.map

package/dist/config/JsonSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonSchema.js","sourceRoot":"","sources":["../../src/config/JsonSchema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAElD,OAAO,MAAM,MAAM,qBAAqB,CAAC;AAEzC,MAAM,KAAW,UAAU,CAc1B;AAdD,WAAiB,UAAU;IACvB;;;;;;;QAOI;IACG,KAAK,UAAU,KAAK,CAAC,WAAmB;QAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;QAC/D,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IACrE,CAAC;IAJqB,WAAA,KAAK,QAI1B,CAAA;AACL,CAAC,EAdgB,UAAU,KAAV,UAAU,QAc1B;AAED,eAAe,UAAU,CAAC"}

package/dist/config/Settings.d.ts

@@ -0,0 +1,201 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Abstract schema-backed config store with flattened property access, whose file format lives in a codec that owns the document it preserves.
+ * @license Apache-2.0
+ */
+import { Flatten } from '@netfeez/common';
+import Schema, { Definition } from '@netfeez/schema';
+export declare abstract class Settings<S extends Schema<Definition.Object>, TDocument = never> {
+    /** The schema describing and validating the config. */
+    protected static schema: Schema<any>;
+    /**
+     * The formats this config can be persisted in, in resolution order.
+     *
+     * Declaring the formats is what replaces the implicit "every config is JSON and YAML": a class
+     * that only needs JSON declares only the JSON codec and never reaches a YAML parser.
+     * @returns The codecs of the class, empty when it declares no format at all.
+     *
+     * @remarks The types are widened because a static cannot see the type parameters of its class.
+     * {@link Settings.codec} is the narrowing seam, named {@link Settings.AnyCodec} on purpose.
+     */
+    protected static get codecs(): readonly Settings.AnyCodec[];
+    protected vData: Settings.Data<S>;
+    protected props: Flatten.Document;
+    protected document: TDocument | null;
+    protected path: string | null;
+    /** The formats of the class this instance was built from, the only way it reaches them. **/
+    protected formats: Settings.Formats;
+    /**
+     * Creates the config store.
+     * @param data - The processed data to store.
+     * @param options - Additional options for the config store.
+     */
+    constructor(data: Settings.Data<S>, options?: Settings.Options<TDocument>);
+    get data(): Settings.Data<S>;
+    set data(value: Settings.Data<S>);
+    /**
+     * Gets a config property by its path.
+     * @param path - The path to the config property.
+     * @returns The value of the config property at the specified path.
+     */
+    get<TKey extends keyof Settings.Props<S>>(path: TKey): Settings.Props<S>[TKey];
+    set<TKey extends keyof Settings.Props<S>>(path: TKey, value: Settings.Props<S>[TKey]): void;
+    merge(partial: Settings.DeepPartial<Settings.Data<S>>): void;
+    /**
+     * Saves the config to the given path, in the format of its extension.
+     *
+     * The document the config was loaded with is handed to the codec, so untouched keys, comments
+     * and formatting survive the round trip. When the config is saved into another format than it
+     * was loaded from (`json-to-yaml`), there is no document of that format yet, so the codec
+     * creates one from the data and the file is written as if it had always been in that format.
+     * @param path - The path to save the config file to, defaulting to the path it was loaded from.
+     * @returns A promise that resolves when the config is saved.
+     * @throws { Error} When no path is given, or the class declares no format for the extension.
+     */
+    save(path?: string): Promise<void>;
+    /**
+     * Loads a config from the given path, creating it with defaults when missing.
+     *
+     * The file is read as plain text and nothing more: the codec of the extension decides what that
+     * text means and hands back both the data and the document the format preserves. A file holding
+     * no document at all (missing, blank, or holding nothing but comments) decodes to nothing, and
+     * the config is then built from the defaults the schema resolves, seeded into a fresh document.
+     * @param this - The concrete Settings subclass constructor.
+     * @param path - The path to the config file.
+     * @param options - Options for loading the config.
+     * @returns A promise that resolves with the loaded config.
+     * @throws { Error} When the class declares no format for the extension of the path.
+     */
+    static load<C extends Settings<any, any>>(this: Settings.Ctor<C>, path: string, options?: Settings.LoadOptions): Promise<C>;
+    /**
+     * Validates the data of a file against the schema, filling in the defaults of whatever is
+     * absent, so that a partial file yields a complete config.
+     * @param data - The data read from the file.
+     * @returns The data of the config, ready to be stored.
+     *
+     * @remarks The return type is widened because a static cannot see the type parameters of its
+     * class. {@link Settings.Ctor} is where a caller of {@link load} gets it back, as the data of
+     * the subclass it asked for.
+     */
+    static parse(data: unknown): Settings.Data<any>;
+    /**
+     * The codec this class declares for a file extension.
+     * @param extension - The lower-cased file extension, including the leading dot.
+     * @returns The codec that reads and writes that extension, or `null` when the class declares no
+     * format for it.
+     *
+     * @remarks The types are widened because a static cannot see the type parameters of its class,
+     * as in {@link codecs}.
+     */
+    static codec(extension: string): Settings.AnyCodec | null;
+    /**
+     * The codec of a path, as declared by the class it is asked for.
+     * @param formats - The formats of the class, either its static side or a loaded config.
+     * @param path - The path the config is read from or written to.
+     * @returns The codec of the extension of the path.
+     * @throws { Error } When no format is declared for that extension.
+     */
+    private static require;
+    /**
+     * The lower-cased extension of a path, the form formats are selected by.
+     * @param path - The path to get the extension of.
+     * @returns The lower-cased extension of the path, including the leading dot.
+     */
+    private static extension;
+    /**
+     * Checks if a value is a non-null object (not an array).
+     * @param value - The value to check.
+     * @returns `true` if the value is a non-null object, `false` otherwise.
+     */
+    private static isObject;
+    /**
+     * Merges two objects deeply, recursively merging their properties.
+     * @param target - The object to merge into.
+     * @param source - The object to merge from.
+     * @returns The merged object.
+     */
+    private static deepMerge;
+}
+export declare namespace Settings {
+    type DeepPartial<T> = T extends object ? {
+        [K in keyof T]?: DeepPartial<T[K]>;
+    } : T;
+    type Data<S extends Schema<any>> = S['infer'];
+    type Props<S extends Schema<any>> = Flatten.Object<Extract<S['infer'], Flatten.Document>>;
+    interface Options<TDocument = never> {
+        /** The document the format of the file preserves, carried across loads and saves. */
+        document?: TDocument | null;
+        path?: string | null;
+    }
+    interface LoadOptions {
+        logger?: Logger;
+        create?: boolean;
+    }
+    interface Logger {
+        log(...args: any[]): void;
+        warn?(...args: any[]): void;
+        error(...args: any[]): void;
+    }
+    /**
+     * A codec with both of its types widened, which is what a static can name: the statics of a
+     * class cannot see the type parameters of that class, so this is the shape a codec is looked up
+     * and carried in, and the only widening in the design.
+     */
+    type AnyCodec = Settings.Codec<any, any>;
+    /**
+     * The formats of a class, as far as a caller needs them: the codec of an extension, or `null`
+     * when the class declares no format for it.
+     *
+     * This is what a config keeps of its own class (its formats) and what a static side exposes
+     * ({@link Settings.Ctor}), so both resolve a format the same way.
+     */
+    interface Formats {
+        codec(extension: string): Settings.AnyCodec | null;
+    }
+    /**
+     * What a concrete subclass must expose for {@link load} to build it: its constructor, the
+     * schema behind {@link parse}, and the formats it declares.
+     */
+    interface Ctor<C extends Settings<any, any>> extends Settings.Formats {
+        new (data: any, options?: Settings.Options<any>): C;
+        parse(data: unknown): Settings.Data<any>;
+    }
+    /**
+     * A bidirectional text format: it reads the text of a config file, writes it back, and carries
+     * the document of that file — whatever the format keeps around the values — from one to the other.
+     *
+     * @typeParam TDocument - The document the format preserves; `null` for a format that keeps
+     * nothing beyond the data, whose document is the data itself.
+     * @typeParam TData - The data the format renders.
+     */
+    interface Codec<TDocument, TData> {
+        /** The lower-cased file extensions this codec is selected by, including the leading dot. */
+        readonly extensions: readonly string[];
+        /**
+         * Parses the text of a file into the data it holds and the document that holds it.
+         * @param text - The text of the file.
+         * @returns The data and the document, or `null` when the text holds no document at all.
+         */
+        decode(text: string): Settings.Decoded<TDocument> | null;
+        /**
+         * Creates the document of a file that does not exist yet, holding the given data.
+         * @param data - The data to hold in the new document.
+         * @returns The new document.
+         */
+        create(data: TData): TDocument;
+        /**
+         * Renders the data through the document, keeping whatever the format preserves.
+         * @param data - The data to render.
+         * @param document - The document the data is rendered through.
+         * @returns The text of the file.
+         */
+        encode(data: TData, document: TDocument): string;
+    }
+    interface Decoded<TDocument> {
+        /** The data the file holds, before the schema validates it. */
+        data: unknown;
+        /** The document the file is written through, and written back from. */
+        document: TDocument;
+    }
+}
+export default Settings;

package/dist/config/Settings.js

@@ -0,0 +1,191 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Abstract schema-backed config store with flattened property access, whose file format lives in a codec that owns the document it preserves.
+ * @license Apache-2.0
+ */
+import { File, Path } from '@netfeez/common-node';
+import { Flatten } from '@netfeez/common';
+export class Settings {
+    /** The schema describing and validating the config. */
+    static schema;
+    /**
+     * The formats this config can be persisted in, in resolution order.
+     *
+     * Declaring the formats is what replaces the implicit "every config is JSON and YAML": a class
+     * that only needs JSON declares only the JSON codec and never reaches a YAML parser.
+     * @returns The codecs of the class, empty when it declares no format at all.
+     *
+     * @remarks The types are widened because a static cannot see the type parameters of its class.
+     * {@link Settings.codec} is the narrowing seam, named {@link Settings.AnyCodec} on purpose.
+     */
+    static get codecs() { return []; }
+    vData;
+    props;
+    document;
+    path;
+    /** The formats of the class this instance was built from, the only way it reaches them. **/
+    formats;
+    /**
+     * Creates the config store.
+     * @param data - The processed data to store.
+     * @param options - Additional options for the config store.
+     */
+    constructor(data, options = {}) {
+        this.formats = new.target;
+        this.vData = data;
+        this.props = Flatten.object(this.vData);
+        this.document = options.document ?? null;
+        this.path = options.path ?? null;
+    }
+    get data() { return this.vData; }
+    set data(value) {
+        this.vData = value;
+        this.props = Flatten.object(this.vData);
+    }
+    /**
+     * Gets a config property by its path.
+     * @param path - The path to the config property.
+     * @returns The value of the config property at the specified path.
+     */
+    get(path) {
+        return this.props[path];
+    }
+    set(path, value) {
+        this.props[path] = value;
+        this.vData = Flatten.unObject(this.props);
+    }
+    merge(partial) {
+        this.vData = Settings.deepMerge(this.vData, partial);
+        this.props = Flatten.object(this.vData);
+    }
+    /**
+     * Saves the config to the given path, in the format of its extension.
+     *
+     * The document the config was loaded with is handed to the codec, so untouched keys, comments
+     * and formatting survive the round trip. When the config is saved into another format than it
+     * was loaded from (`json-to-yaml`), there is no document of that format yet, so the codec
+     * creates one from the data and the file is written as if it had always been in that format.
+     * @param path - The path to save the config file to, defaulting to the path it was loaded from.
+     * @returns A promise that resolves when the config is saved.
+     * @throws { Error} When no path is given, or the class declares no format for the extension.
+     */
+    async save(path = this.path) {
+        if (!path)
+            throw new Error('No path specified for saving the config.');
+        const codec = Settings.require(this.formats, path);
+        await File.ensureDir(Path.dirname(path));
+        await File.write(path, codec.encode(this.vData, this.document ?? codec.create(this.vData)), 'utf-8');
+    }
+    /**
+     * Loads a config from the given path, creating it with defaults when missing.
+     *
+     * The file is read as plain text and nothing more: the codec of the extension decides what that
+     * text means and hands back both the data and the document the format preserves. A file holding
+     * no document at all (missing, blank, or holding nothing but comments) decodes to nothing, and
+     * the config is then built from the defaults the schema resolves, seeded into a fresh document.
+     * @param this - The concrete Settings subclass constructor.
+     * @param path - The path to the config file.
+     * @param options - Options for loading the config.
+     * @returns A promise that resolves with the loaded config.
+     * @throws { Error} When the class declares no format for the extension of the path.
+     */
+    static async load(path, options = {}) {
+        const logger = options.logger;
+        const codec = Settings.require(this, path);
+        if (logger)
+            logger.log(`loading config from &C6[${path}]`);
+        const text = await File.exists(path) ? await File.read(path, 'utf-8') : null;
+        if (text === null && logger)
+            logger.log(`config file &C6[${path}]&R does not exist, creating it`);
+        try {
+            const source = text === null ? null : codec.decode(text);
+            const data = this.parse(source === null ? {} : source.data);
+            const config = new this(data, { document: source?.document ?? codec.create(data), path });
+            if (text === null) {
+                if (options.create)
+                    await config.save();
+                if (logger)
+                    logger.log(`config file &C6[${path}]&R &C2was created successfully`);
+            }
+            return config;
+        }
+        catch (error) {
+            if (logger)
+                logger.error(`config file &C6[${path}]&R &C1could not be loaded`);
+            throw error;
+        }
+    }
+    /**
+     * Validates the data of a file against the schema, filling in the defaults of whatever is
+     * absent, so that a partial file yields a complete config.
+     * @param data - The data read from the file.
+     * @returns The data of the config, ready to be stored.
+     *
+     * @remarks The return type is widened because a static cannot see the type parameters of its
+     * class. {@link Settings.Ctor} is where a caller of {@link load} gets it back, as the data of
+     * the subclass it asked for.
+     */
+    static parse(data) { return this.schema.processUnknown(data); }
+    /**
+     * The codec this class declares for a file extension.
+     * @param extension - The lower-cased file extension, including the leading dot.
+     * @returns The codec that reads and writes that extension, or `null` when the class declares no
+     * format for it.
+     *
+     * @remarks The types are widened because a static cannot see the type parameters of its class,
+     * as in {@link codecs}.
+     */
+    static codec(extension) {
+        return this.codecs.find(candidate => candidate.extensions.includes(extension)) ?? null;
+    }
+    /**
+     * The codec of a path, as declared by the class it is asked for.
+     * @param formats - The formats of the class, either its static side or a loaded config.
+     * @param path - The path the config is read from or written to.
+     * @returns The codec of the extension of the path.
+     * @throws { Error } When no format is declared for that extension.
+     */
+    static require(formats, path) {
+        const extension = Settings.extension(path);
+        const codec = formats.codec(extension);
+        if (!codec)
+            throw new Error(`Unsupported config file extension: ${extension}`);
+        return codec;
+    }
+    /**
+     * The lower-cased extension of a path, the form formats are selected by.
+     * @param path - The path to get the extension of.
+     * @returns The lower-cased extension of the path, including the leading dot.
+     */
+    static extension(path) { return Path.extName(path).toLowerCase(); }
+    /**
+     * Checks if a value is a non-null object (not an array).
+     * @param value - The value to check.
+     * @returns `true` if the value is a non-null object, `false` otherwise.
+     */
+    static isObject(value) {
+        return value !== null && typeof value === 'object' && !Array.isArray(value);
+    }
+    /**
+     * Merges two objects deeply, recursively merging their properties.
+     * @param target - The object to merge into.
+     * @param source - The object to merge from.
+     * @returns The merged object.
+     */
+    static deepMerge(target, source) {
+        if (!Settings.isObject(target) || !Settings.isObject(source))
+            return source;
+        const result = { ...target };
+        for (const key of Object.keys(source)) {
+            if (source[key] === undefined)
+                continue;
+            if (Settings.isObject(result[key]) && Settings.isObject(source[key]))
+                result[key] = Settings.deepMerge(result[key], source[key]);
+            else
+                result[key] = source[key];
+        }
+        return result;
+    }
+}
+export default Settings;
+//# sourceMappingURL=Settings.js.map

package/dist/config/Settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Settings.js","sourceRoot":"","sources":["../../src/config/Settings.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG1C,MAAM,OAAgB,QAAQ;IAC1B,uDAAuD;IAC7C,MAAM,CAAC,MAAM,CAAc;IAErC;;;;;;;;;OASG;IACO,MAAM,KAAK,MAAM,KAAmC,OAAO,EAAE,CAAC,CAAC,CAAC;IAEhE,KAAK,CAAmB;IACxB,KAAK,CAAmB;IACxB,QAAQ,CAAmB;IAC3B,IAAI,CAAgB;IAE9B,4FAA4F;IAClF,OAAO,CAAmB;IAEpC;;;;OAIG;IACH,YAAmB,IAAsB,EAAE,OAAO,GAAgC,EAAE;QAChF,IAAI,CAAC,OAAO,GAAG,IAAI,MAAM,CAAC;QAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC;IACrC,CAAC;IAED,IAAW,IAAI,KAAuB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1D,IAAW,IAAI,CAAC,KAAuB;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACI,GAAG,CAAuC,IAAU;QACvD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IACM,GAAG,CAAuC,IAAU,EAAE,KAA8B;QACvF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC;IACM,KAAK,CAAC,OAA+C;QACxD,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACrD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;OAUG;IACI,KAAK,CAAC,IAAI,CAAC,IAAI,GAAW,IAAI,CAAC,IAAK;QACvC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QACvE,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACnD,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACzG,CAAC;IAED;;;;;;;;;;;;OAYG;IACI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAuD,IAAY,EAAE,OAAO,GAAyB,EAAE;QAC3H,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3C,IAAI,MAAM;YAAE,MAAM,CAAC,GAAG,CAAC,2BAA2B,IAAI,GAAG,CAAC,CAAC;QAE3D,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7E,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM;YAAE,MAAM,CAAC,GAAG,CAAC,mBAAmB,IAAI,iCAAiC,CAAC,CAAC;QAElG,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACzD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC5D,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1F,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBAChB,IAAI,OAAO,CAAC,MAAM;oBAAE,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;gBACxC,IAAI,MAAM;oBAAE,MAAM,CAAC,GAAG,CAAC,mBAAmB,IAAI,iCAAiC,CAAC,CAAC;YACrF,CAAC;YACD,OAAO,MAAM,CAAC;QAClB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,MAAM;gBAAE,MAAM,CAAC,KAAK,CAAC,mBAAmB,IAAI,4BAA4B,CAAC,CAAC;YAC9E,MAAM,KAAK,CAAC;QAChB,CAAC;IACL,CAAC;IAED;;;;;;;;;OASG;IACI,MAAM,CAAC,KAAK,CAAC,IAAa,IAAwB,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAEnG;;;;;;;;OAQG;IACI,MAAM,CAAC,KAAK,CAAC,SAAiB;QACjC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,IAAI,IAAI,CAAC;IAC3F,CAAC;IAED;;;;;;OAMG;IACK,MAAM,CAAC,OAAO,CAAC,OAAyB,EAAE,IAAY;QAC1D,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,SAAS,EAAE,CAAC,CAAC;QAC/E,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACK,MAAM,CAAC,SAAS,CAAC,IAAY,IAAY,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAE3F;;;;OAIG;IACK,MAAM,CAAC,QAAQ,CAAC,KAAU;QAC9B,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAChF,CAAC;IAED;;;;;OAKG;IACK,MAAM,CAAC,SAAS,CAAC,MAAW,EAAE,MAAW;QAC7C,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC;QAC5E,MAAM,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;QAC7B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACpC,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS;gBAAE,SAAS;YACxC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAChE,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;;gBAC1D,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,MAAM,CAAC;IAClB,CAAC;CACJ;AAyFD,eAAe,QAAQ,CAAC"}