@vltpkg/cli-sdk 0.0.0-2

package/dist/esm/config/index.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Module that handles all vlt configuration needs
+ *
+ * Project-level configs are set in a `vlt.json` file in the local project
+ * if present. This will override the user-level configs in the appropriate
+ * XDG config path.
+ *
+ * Command-specific configuration can be specified by putting options in a
+ * field in the `command` object. For example:
+ *
+ * ```json
+ * {
+ *   "registry": "https://registry.npmjs.org/",
+ *   "command": {
+ *     "publish": {
+ *       "registry": "http://registry.internal"
+ *     }
+ *   }
+ * }
+ * ```
+ * @module
+ */
+import { PackageJson } from '@vltpkg/package-json';
+import { Monorepo } from '@vltpkg/workspaces';
+import type { Jack, OptionsResults, Unwrap } from 'jackspeak';
+import { PathScurry } from 'path-scurry';
+import { kIndent, kNewline } from 'polite-json';
+import { commands, definition, isRecordField, recordFields } from './definition.ts';
+import type { Commands, RecordField } from './definition.ts';
+export { recordFields, isRecordField };
+export { definition, commands, type Commands };
+export type RecordPairs = Record<string, unknown>;
+export type RecordString = Record<string, string>;
+export type ConfigFiles = Record<string, ConfigFileData>;
+export type PairsAsRecords = Omit<ConfigOptions, 'projectRoot' | 'scurry' | 'packageJson' | 'monorepo'> & {
+    command?: Record<string, ConfigOptions>;
+};
+export declare const pairsToRecords: (obj: ConfigFileData) => PairsAsRecords;
+export declare const recordsToPairs: (obj: RecordPairs) => RecordPairs;
+/**
+ * Config data can be any options, and also a 'command' field which
+ * contains command names and override options for that command.
+ */
+export type ConfigData = OptionsResults<ConfigDefinitions> & {
+    command?: Record<string, OptionsResults<ConfigDefinitions>>;
+};
+/**
+ * Config data as it appears in config files, with kv pair lists
+ * stored as `Record<string, string>`.
+ */
+export type ConfigFileData = {
+    [k in keyof ConfigData]?: k extends OptListKeys<ConfigData> ? RecordString | string[] : k extends 'command' ? ConfigFiles : ConfigData[k];
+};
+export type ConfigOptions = {
+    [k in keyof ConfigData]: k extends RecordField ? RecordString : k extends 'command' ? never : ConfigData[k];
+} & {
+    packageJson: PackageJson;
+    scurry: PathScurry;
+    projectRoot: string;
+    monorepo?: Monorepo;
+};
+/**
+ * The base config definition set as a type
+ */
+export type ConfigDefinitions = Unwrap<typeof definition>;
+export type StringListKeys<O> = {
+    [k in keyof O]: O[k] extends string[] | undefined ? k : never;
+};
+export type OptListKeys<O> = Exclude<StringListKeys<O>[keyof StringListKeys<O>], undefined>;
+/**
+ * Class that handles configuration for vlt.
+ *
+ * Call {@link Config.load} to get one of these.
+ */
+export declare class Config {
+    #private;
+    /**
+     * The {@link https://npmjs.com/jackspeak | JackSpeak} object
+     * representing vlt's configuration
+     */
+    jack: Jack<ConfigDefinitions>;
+    stringifyOptions: {
+        [kIndent]: string;
+        [kNewline]: string;
+    };
+    configFiles: ConfigFiles;
+    /**
+     * Parsed values in effect
+     */
+    values?: OptionsResults<ConfigDefinitions>;
+    /**
+     * Command-specific config values
+     */
+    commandValues: {
+        [cmd in Commands[keyof Commands]]?: ConfigData;
+    };
+    /**
+     * A flattened object of the parsed configuration
+     */
+    get options(): ConfigOptions;
+    /**
+     * Reset the options value, optionally setting a new project root
+     * to recalculate the options.
+     */
+    resetOptions(projectRoot?: string): void;
+    /**
+     * positional arguments to the vlt process
+     */
+    positionals?: string[];
+    /**
+     * The root of the project where a vlt.json, vlt-workspaces.json,
+     * package.json, or .git was found. Not necessarily the `process.cwd()`,
+     * though that is the default location.
+     *
+     * Never walks up as far as `$HOME`. So for example, if a project is in
+     * `~/projects/xyz`, then the highest dir it will check is `~/projects`
+     */
+    projectRoot: string;
+    /**
+     * `Record<alias, canonical name>` to dereference command aliases.
+     */
+    commands: Commands;
+    /**
+     * Which command name to use for overriding with command-specific values,
+     * determined from the argv when parse() is called.
+     */
+    command?: Commands[keyof Commands];
+    constructor(jack?: Jack<ConfigDefinitions>, projectRoot?: string);
+    /**
+     * Parse the arguments and set configuration and positionals accordingly.
+     */
+    parse(args?: string[]): this & ParsedConfig;
+    /**
+     * Get a `key=value` list option value as an object.
+     *
+     * For example, a list option with a vlaue of `['key=value', 'xyz=as=df' ]`
+     * would be returned as `{key: 'value', xyz: 'as=df'}`
+     *
+     * Results are memoized, so subsequent calls for the same key will return the
+     * same object. If new strings are added to the list, then the memoized value
+     * is *not* updated, so only use once configurations have been fully loaded.
+     *
+     * If the config value is not set at all, an empty object is returned.
+     */
+    getRecord(k: OptListKeys<ConfigData>): RecordString;
+    /**
+     * Get a configuration value.
+     *
+     * Note: `key=value` pair configs are returned as a string array. To get them
+     * as an object, use {@link Config#getRecord}.
+     */
+    get<K extends keyof OptionsResults<ConfigDefinitions>>(k: K): OptionsResults<ConfigDefinitions>[K];
+    /**
+     * Write the config values to the user or project config file.
+     */
+    writeConfigFile(which: 'project' | 'user', values: ConfigFileData): Promise<ConfigFileData>;
+    /**
+     * Fold in the provided fields with the existing properties
+     * in the config file.
+     */
+    addConfigToFile(which: 'project' | 'user', values: ConfigFileData): Promise<ConfigFileData>;
+    getFilename(which?: 'project' | 'user'): string;
+    deleteConfigKeys(which: 'project' | 'user', fields: string[]): Promise<boolean>;
+    /**
+     * Edit the user or project configuration file.
+     *
+     * If the file isn't present, then it starts with `{}` so the user has
+     * something to work with.
+     *
+     * If the result is not valid, or no config settings are contained in the
+     * file after editing, then it's restored to what it was before, which might
+     * mean deleting the file.
+     */
+    editConfigFile(which: 'project' | 'user', edit: (file: string) => Promise<void> | void): Promise<void>;
+    /**
+     * Find the local config file and load both it and the user-level config in
+     * the XDG config home.
+     *
+     * Note: if working in a workspaces monorepo, then the vlt.json file MUST
+     * be in the same folder as the vlt-workspaces.json file, because we stop
+     * looking when we find either one.
+     */
+    loadConfigFile(): Promise<this>;
+    /**
+     * Determine whether we should use colors in the output. Update
+     * chalk appropriately.
+     *
+     * Implicitly calls this.parse() if it not parsed already.
+     */
+    loadColor(): Promise<this & LoadedConfig>;
+    /**
+     * Load the configuration and return a Promise to a
+     * {@link Config} object
+     */
+    static load(projectRoot?: string, argv?: string[], 
+    /**
+     * only used in tests, resets the memoization
+     * @internal
+     */
+    reload?: boolean): Promise<LoadedConfig>;
+}
+export type ParsedConfig = Config & {
+    command: NonNullable<Config['command']>;
+    values: OptionsResults<ConfigDefinitions>;
+    positionals: string[];
+};
+/**
+ * A fully loaded {@link Config} object
+ */
+export type LoadedConfig = ParsedConfig & {
+    get(k: 'color'): boolean;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/config/index.ts"],"names":[],"mappings":"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"}