import { Structure } from "./structure.ts";
import { type ConfigurationDescription, type PrimativeOptions } from "./specifications.ts";
import { type ConfigurationResult } from "./parsers.ts";
import { type StructContext } from "./struct-context.ts";
/**
 * @group Configuration
 *
 * Options for creating a platform-sepcific {@link Configuration} object,
 * different methods provide abstractions over the filesystem & parsing capabilities of the Configuration.
 *
 * For instance, you could create one that loads remote files over S3 and parses them as YAML,
 * or just a simple one that loads JSON files from the filesystem
 */
export interface ConfigurationOptions {
    /** Read in a file and decode it as text, or return null if it doesn't exist */
    readTextFile(url: URL | string): Promise<string | null>;
    /** Get a specific environment variable, or undefined if it is not set */
    getEnvironmentVariable(key: string): string | undefined;
    /** Get a specific CLI option, like `--some-thing`, or undefined if it is not set */
    getCommandArgument(key: string): string | undefined;
    /** Convert an in-memory value to a string for displaying to the user */
    stringify(value: any): string | Promise<string>;
    /** Parse a text file into in-memory values */
    parse(value: string): any;
}
/**
 * @group Configuration
 *
 * **Configuration** is both an abstraction around processing config files,
 * environment variables & CLI flags from the platform
 * and also a tool for users to declaratively define how their configuration is.
 *
 * Each platform specifies a default `options` to load JSON files,
 * but you can also construct your own if you want to customise how it works.
 *
 * With an instance, you can then define how an app's config can be specified as either configuration files,
 * CLI flag, environment variables or a combination of any of them.
 *
 * ```js
 * const config = new Configuration({
 * 	readTextFile(url) {},
 * 	getEnvironmentVariable(key) {},
 * 	getCommandArgument() {},
 * 	stringify(value) {},
 * 	parse(value) {},
 * })
 * ```
 */
export declare class Configuration {
    static readonly spec: unique symbol;
    options: ConfigurationOptions;
    constructor(options: ConfigurationOptions);
    _loadValue<T>(path: string | URL, structure: Structure<T>, context: StructContext): Promise<T | null>;
    /** Wrap a primativ Structure with configuration logic */
    _primative<T>(struct: Structure<T>, options: PrimativeOptions<T>, deconfigure: (result: ConfigurationResult) => unknown): Structure<T>;
    /**
     * Group or nest configuration in an object.
     *
     * ```js
     * config.object({
     * 	name: config.string({ fallback: "Geoff Testington" }),
     * 	age: config.number({ fallback: 42 }),
     * })
     * ```
     */
    object<T extends Record<string, unknown>>(fields: {
        [K in keyof T]: Structure<T[K]>;
    }): Structure<T>;
    /**
     * @unstable
     *
     * Create an ordered list of another type
     *
     * ```js
     * config.array(
     * 	Structure.string()
     * )
     * ```
     */
    array<T extends unknown>(item: Structure<T>): Structure<T[]>;
    /**
     * @unstable
     *
     * Load another configuration file or use value in the original configuration
     *
     * ```js
     * config.external(
     * 	new URL("./api-keys.json", import.meta.url),
     * 	config.object({
     * 		keys: Structure.array(Structure.string())
     * 	})
     * )
     * ```
     *
     * Which will attempt to load "api-keys.json" and parse that,
     * and if that doesn't exist it will also try the value in the original configuration.
     */
    external<T extends Record<string, unknown> | Array<unknown>>(path: string | URL, struct: Structure<T>): Structure<T>;
    /**
     * Define a string-based value with options to load from the config-file,
     * an environment variable or a CLI flag.
     * The only required field is **fallback**
     *
     * ```js
     * config.string({
     * 	variable: "HOSTNAME",
     * 	flag: "--host",
     * 	fallback: "localhost"
     * })
     * ```
     */
    string(options: PrimativeOptions<string>): Structure<string>;
    /**
     * Define a numeric value with options to load from the config-file,
     * an environment variable or a CLI flag.
     * The only required field is **fallback**
     *
     * It will also coerce floating point numbers from strings
     *
     * ```js
     * config.number({
     * 	variable: "PORT",
     * 	flag: "--port",
     * 	fallback: "1234"
     * })
     * ```
     */
    number(options: PrimativeOptions<number>): Structure<number>;
    /**
     * Define a boolean value with options to load from the config-file,
     * an environment variable or a CLI flag.
     * The only required field is **fallback**
     *
     * There are extra coercions for boolean-like strings
     *
     * - `1`, `true` & `yes` coerce to true
     * - `0`, `false` & `no` coerce to false
     *
     * ```js
     * config.boolean({
     * 	variable: "USE_SSL",
     * 	flag: "--ssl",
     * 	fallback: false
     * })
     * ```
     */
    boolean(options: PrimativeOptions<boolean>): Structure<boolean>;
    /**
     * Define a URL based value, the value is validated and converted into a [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL).
     *
     * ```js
     * config.url({
     * 	variable: "SELF_URL",
     * 	flag: "--url",
     * 	fallback: "http://localhost:1234"
     * })
     * ```
     */
    url(options: PrimativeOptions<string | URL>): Structure<URL>;
    /**
     * Load configuration with a base file, also pulling in environment variables and CLI flags using {@link ConfigurationOptions}
     *
     * ```js
     * const struct = config.object({
     * 	env: config.string({ variable: "NODE_ENV", fallback: "development" })
     * })
     *
     * config.load(
     * 	new URL("./app-config.json", import.meta.url),
     * 	struct
     * )
     * ```
     *
     * It will asynchronously load the configuration, validate it and return the coerced value.
     * If it fails it will output a friendly string listing what is wrong and throw the Structure.Error
     */
    load<T>(url: URL | string, struct: Structure<T>): Promise<T>;
    /**
     * Given a structure defined using Configuration, generate human-readable usage information.
     * The usage includes a table of all configuration options and what the default value would be if no other soruces are used.
     *
     * Optionally, output the current value of the configuration too.
     */
    getUsage(struct: unknown, currentValue?: unknown): string;
    /**
     * @ignore
     *
     * Given a structure defined using configuration, get meta-information about it
     */
    describe(value: unknown, prefix?: string): ConfigurationDescription;
    /**
     * @unstable
     *
     * Given a structure defined using configuration, generate a JSON Schema to validate it. This could be useful to write to a file then use a IDE-based validator using something like
     *
     * ```json
     * {
     * 	"$schema": "./app-config.schema.json",
     * }
     * ```
     */
    getJSONSchema(struct: Structure<any>): import("./structure.ts").Schema;
}
//# sourceMappingURL=configuration.d.ts.map