import { Conversion } from '@fgv/ts-utils';
import { Converter } from '@fgv/ts-utils';
import { FileTree } from '@fgv/ts-json-base';
import { Hash as Hash_2 } from '@fgv/ts-utils';
import { JsonValue } from '@fgv/ts-json-base';
import { Result } from '@fgv/ts-utils';
import { Validator } from '@fgv/ts-utils';

declare namespace Converters {
    export {
        templateString,
        extendedArrayOf,
        rangeTypeOf,
        rangeOf,
        isoDate
    }
}
export { Converters }

declare namespace Csv {
    export {
        parseCsvString,
        CsvOptions,
        readCsvFileSync,
        readCsvFromTree
    }
}
export { Csv }

/**
 * Options for {@link Csv.readCsvFileSync | readCsvFileSync}
 * @beta
 */
declare interface CsvOptions {
    delimiter?: string;
}

/**
 * Default {@link Experimental.RangeOfFormats | formats} to use for both
 * open-ended and complete {@link Experimental.RangeOf | RangeOf<T>}.
 * @public
 */
declare const DEFAULT_RANGEOF_FORMATS: RangeOfFormats;

declare namespace Experimental {
    export {
        ExtendedArray,
        formatList,
        FormatTargets,
        Formattable,
        FormattableBase,
        Formatter,
        FormattersByExtendedTarget,
        FormattersByTarget,
        RangeOfProperties,
        RangeOfFormats,
        DEFAULT_RANGEOF_FORMATS,
        RangeOf
    }
}
export { Experimental }

/**
 * An experimental array template which extend built-in `Array` to include a handful
 * of predicates which return `Result<T>`.
 * @beta
 */
declare class ExtendedArray<T> extends Array<T> {
    readonly itemDescription: string;
    /**
     * Constructs an {@link Experimental.ExtendedArray | ExtendedArray}.
     * @param itemDescription - Brief description of the type of each item in this array.
     * @param items - The initial contents of the array.
     */
    constructor(itemDescription: string, ...items: T[]);
    /**
     * Type guard to determine if some arbitrary array is an
     * {@link Experimental.ExtendedArray}
     * @param a - The `Array` to be tested.
     * @returns Returns `true` if `a` is an {@link Experimental.ExtendedArray | ExtendedArray},
     * `false` otherwise.
     */
    static isExtendedArray<T>(a?: T[]): a is ExtendedArray<T>;
    /**
     * Determines if this array contains exactly one element which matches
     * a supplied predicate.
     * @param predicate - The predicate function to be applied.
     * @returns Returns `Success<T>` with the single matching
     * result if exactly one item matches `predicate`.  Returns `Failure<T>`
     * with an error message if there are no matches or more than one match.
     */
    single(predicate?: (item: T) => boolean): Result<T>;
    /**
     * Returns the first element of an {@link Experimental.ExtendedArray | ExtendedArray}. Fails with an
     * error message if the array is empty.
     * @param failMessage - Optional message to be displayed in the event of failure.
     * @returns Returns `Success<T>` with the value of the first element
     * in the array, or `Failure<T>` with an error message if the array is empty.
     */
    first(failMessage?: string): Result<T>;
    /**
     * Returns an array containing all elements of an {@link Experimental.ExtendedArray | ExtendedArray}.
     * Fails with an error message if the array is empty.
     * @param failMessage - Optional message to be displayed in the event of failure.
     * @returns Returns `Success<T>` with a new (non-extended) `Array`
     * containing the elements of this array, or `Failure<T>` with an error message
     * if the array is empty.
     */
    atLeastOne(failMessage?: string): Result<T[]>;
    /**
     * Gets a new (non-extended) `Array` containing all of the elements from this
     * {@link Experimental.ExtendedArray | ExtendedArray}.
     * @returns A new (non-extended) `Array<T>`.
     */
    all(): T[];
}

/**
 * A helper function to create a `Converter` which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.
 * @remarks
 * If `onError` is `'failOnError'` (default), then the entire conversion fails if any element cannot
 * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.
 * @param converter - `Converter` used to convert each item in the array
 * @param ignoreErrors - Specifies treatment of unconvertible elements
 * @beta
 */
declare function extendedArrayOf<T, TC = undefined>(label: string, converter: Converter<T, TC>, onError?: Conversion.OnError): Converter<ExtendedArray<T>, TC>;

/**
 * Formats a list of items using the supplied template and formatter, one result
 * per output line.
 * @param format - A mustache template used to format each item.
 * @param items - The items to be formatted.
 * @param itemFormatter - The {@link Experimental.Formatter | Formatter<T>} used to format each item.
 * @returns The resulting string.
 * @beta
 */
declare function formatList<T>(format: string, items: T[], itemFormatter: Formatter<T>): Result<string>;

/**
 * Interface for an object that can be formatted.
 * @beta
 */
declare interface Formattable {
    /**
     * Formats an object using the supplied mustache template.
     * @param format - A mustache template used to format the object.
     * @returns `Success<string>` with the resulting string, or `Failure<string>`
     * with an error message if an error occurs.
     */
    format(format: string): Result<string>;
}

/**
 * Base class which adds common formatting.
 * @beta
 */
declare class FormattableBase {
    /**
     * Helper enables derived classes to add named details to a formatted presentation.
     * @param details - An array of detail description strings.
     * @param label - Label to use for the new detail.
     * @param value - Value to use for the new detail.
     * @internal
     */
    protected static _tryAddDetail(details: string[], label: string, value: string | undefined): void;
    /**
     * {@inheritdoc Experimental.Formattable.format}
     */
    format(template: string): Result<string>;
}

/**
 * Destination format for some formatted string.
 * @beta
 */
declare type FormatTargets = 'text' | 'markdown' | 'embed';

/**
 * Type definition for a formatting function, which takes a `string` and an
 * item and returns `Result<string>`.
 * @beta
 */
declare type Formatter<T> = (format: string, item: T) => Result<string>;

/**
 * A collection of {@link Experimental.Formatter | formatters} indexed by target name, to enable
 * different format methods per output target.
 * @beta
 */
declare type FormattersByExtendedTarget<TFT extends FormatTargets, T> = Record<TFT, Formatter<T>>;

/**
 * A collection of {@link Experimental.Formatter | formatters} indexed by the
 * {@link Experimental.FormatTargets | default supported target formats}.
 * @beta
 */
declare type FormattersByTarget<T> = FormattersByExtendedTarget<FormatTargets, T>;

declare namespace Hash {
    export {
        Md5Normalizer
    }
}
export { Hash }

/**
 * A `Converter` which converts an iso formatted string, a number or a `Date` object to
 * a `Date` object.
 * @public
 */
declare const isoDate: Converter<Date, unknown>;

/**
 * @public
 */
declare type JarFieldPicker<T extends JarRecord = JarRecord> = (record: T) => (keyof T)[];

/**
 * Represents a single record in a JAR file
 * @public
 */
declare type JarRecord = Record<string, string | string[]>;

/**
 * Options for a JAR record parser.
 * @public
 */
declare interface JarRecordParserOptions {
    readonly arrayFields?: string[] | JarFieldPicker;
    readonly fixedContinuationSize?: number;
}

/**
 * A hashing normalizer which computes object
 * hash using the MD5 algorithm.
 * @public
 */
declare class Md5Normalizer extends Hash_2.HashingNormalizer {
    constructor();
    static md5Hash(parts: string[]): string;
}

/**
 * Parses CSV data from a string.
 * @param body - The CSV string to parse.
 * @param options - optional parameters to control the processing
 * @returns The parsed CSV data.
 * @beta
 */
declare function parseCsvString(body: string, options?: CsvOptions): Result<unknown>;

/**
 * Reads a record-jar from an array of strings, each of which represents one
 * line in the source file.
 * @param lines - the array of strings to be parsed
 * @param options - Optional parser configuration
 * @returns a corresponding array of `Record<string, string>`
 * @public
 */
declare function parseRecordJarLines(lines: string[], options?: JarRecordParserOptions): Result<JarRecord[]>;

/**
 * Simple implementation of a possibly open-ended range of some comparable
 * type `<T>` with test and formatting.
 * @public
 */
declare class RangeOf<T> implements RangeOfProperties<T> {
    /**
     * Minimum extent of the range.
     */
    readonly min?: T;
    /**
     * Maximum extent of the range.
     */
    readonly max?: T;
    /**
     * Creates a new {@link Experimental.RangeOf | RangeOf<T>}.
     * @param min - Optional minimum extent of the range.
     * @param max - Optional maximum extent of the range.
     */
    constructor(min?: T, max?: T);
    /**
     * Static constructor for a {@link Experimental.RangeOf | RangeOf<T>}.
     * @param init - {@link Experimental.RangeOfProperties | Range initializer}.
     * @returns A new {@link Experimental.RangeOf | RangeOf<T>}.
     */
    static createRange<T>(init?: RangeOfProperties<T>): Result<RangeOf<T>>;
    /**
     * Gets a formatted description of a {@link Experimental.RangeOfProperties | RangeOfProperties<T>} given an
     * optional set of formats and 'empty' value to use.
     * @param range - The {@link Experimental.RangeOfProperties | RangeOfProperties<T>} to be formatted.
     * @param formats - Optional {@link Experimental.RangeOfFormats | formats} to use. Default is
     * {@link Experimental.DEFAULT_RANGEOF_FORMATS | DEFAULT_RANGEOF_FORMATS}.
     * @param emptyValue - Value which represents unbounded minimum or maximum for this range. Default is `undefined`.
     * @returns A string representation of the range.
     */
    static propertiesToString<T>(range: RangeOfProperties<T>, formats?: RangeOfFormats, emptyValue?: T): string | undefined;
    /**
     * Default comparison uses javascript built-in comparison.
     * @param t1 - First value to be compared.
     * @param t2 - Second value to be compared.
     * @returns `'less'` if `t1` is less than `t2`, `'greater'` if `t1` is larger
     * and `'equal'` if `t1` and `t2` are equal.
     * @internal
     */
    protected static _defaultCompare<T>(t1: T, t2: T): 'less' | 'equal' | 'greater';
    /**
     * Checks if a supplied value is within this range.
     * @param t - The value to be tested.
     * @returns `'included'` if `t` falls within the range, `'less'` if `t` falls
     * below the minimum extent of the range and `'greater'` if `t` is above the
     * maximum extent.
     */
    check(t: T): 'less' | 'included' | 'greater';
    /**
     * Determines if a supplied value is within this range.
     * @param t - The value to be tested.
     * @returns Returns `true` if `t` falls within the range, `false` otherwise.
     */
    includes(t: T): boolean;
    /**
     * Finds the transition value that would bring a supplied value `t` into
     * range.
     * @param t - The value to be tested.
     * @returns The minimum extent of the range if `t` is below the range or
     * the maximum extent of the range if `t` is above the range.  Returns
     * `undefined` if `t` already falls within the range.
     */
    findTransition(t: T): T | undefined;
    /**
     * Formats the minimum and maximum values of this range.
     * @param format - A format function used to format the values.
     * @returns A {@link Experimental.RangeOfProperties | RangeOfProperties<string>} containing the
     * formatted representation of the {@link Experimental.RangeOf.min | minimum} and
     * {@link Experimental.RangeOf.max | maximum}
     * extent of the range, or `undefined` for an extent that is not present.
     */
    toFormattedProperties(format: (value: T) => string | undefined): RangeOfProperties<string>;
    /**
     * Formats this range using the supplied format function.
     * @param format - Format function used to format minimum and maximum extent values.
     * @param formats - The {@link Experimental.RangeOfFormats | format strings} used to format the range
     * (default {@link Experimental.DEFAULT_RANGEOF_FORMATS}).
     * @returns Returns a formatted representation of this range.
     */
    format(format: (value: T) => string | undefined, formats?: RangeOfFormats): string | undefined;
    /**
     * Inner compare method can be overridden by a derived class.
     * @param t1 - First value to compare.
     * @param t2 - Second value to compare.
     * @returns `'less'` if `t1` is less than `t2`, `'greater'` if `t1` is larger
     * and `'equal'` if `t1` and `t2` are equal.
     * @internal
     */
    protected _compare(t1: T, t2: T): 'less' | 'equal' | 'greater';
}

/**
 * A helper wrapper to construct a `Converter` which converts to {@link Experimental.RangeOf | RangeOf<T>}
 * where `<T>` is some comparable type.
 * @param converter - `Converter` used to convert `min` and `max` extent of the range.
 * @public
 */
declare function rangeOf<T, TC = unknown>(converter: Converter<T, TC>): Converter<RangeOf<T>, TC>;

/**
 * Format strings (in mustache format) to
 * use for both open-ended and complete
 * {@link Experimental.RangeOf | RangeOf<T>}.
 * @public
 */
declare interface RangeOfFormats {
    minOnly: string;
    maxOnly: string;
    minMax: string;
}

/**
 * Represents a generic range of some comparable type `<T>`.
 * @public
 */
declare interface RangeOfProperties<T> {
    readonly min?: T;
    readonly max?: T;
}

/**
 * A helper wrapper to construct a `Converter` which converts to an arbitrary strongly-typed
 * range of some comparable type.
 * @param converter - `Converter` used to convert `min` and `max` extent of the range.
 * @param constructor - Static constructor to instantiate the object.
 * @public
 */
declare function rangeTypeOf<T, RT extends RangeOf<T>, TC = unknown>(converter: Converter<T, TC>, constructor: (init: RangeOfProperties<T>) => Result<RT>): Converter<RT, TC>;

/**
 * Reads a CSV file from a supplied path.
 * @param srcPath - Source path from which the file is read.
 * @param options - optional parameters to control the processing
 * @returns The contents of the file.
 * @beta
 */
declare function readCsvFileSync(srcPath: string, options?: CsvOptions): Result<unknown>;

/**
 * Reads a CSV file from a FileTree.
 * @param fileTree - The FileTree to read from.
 * @param filePath - Path of the file within the tree.
 * @param options - optional parameters to control the processing
 * @returns The parsed CSV data.
 * @beta
 */
declare function readCsvFromTree(fileTree: FileTree.FileTree, filePath: string, options?: CsvOptions): Result<unknown>;

/**
 * Reads a record-jar file from a supplied path.
 * @param srcPath - Source path from which the file is read.
 * @param options - Optional parser configuration
 * @returns The contents of the file as an array of `Record<string, string>`
 * @see https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01
 * @public
 */
declare function readRecordJarFileSync(srcPath: string, options?: JarRecordParserOptions): Result<JarRecord[]>;

/**
 * Reads a record-jar file from a FileTree.
 * @param fileTree - The FileTree to read from.
 * @param filePath - Path of the file within the tree.
 * @param options - Optional parser configuration
 * @returns The contents of the file as an array of `Record<string, string>`
 * @see https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01
 * @public
 */
declare function readRecordJarFromTree(fileTree: FileTree.FileTree, filePath: string, options?: JarRecordParserOptions): Result<JarRecord[]>;

declare namespace RecordJar {
    export {
        parseRecordJarLines,
        JarRecord,
        JarFieldPicker,
        JarRecordParserOptions,
        readRecordJarFileSync,
        readRecordJarFromTree
    }
}
export { RecordJar }

/**
 * Helper function to create a `StringConverter` which converts
 * `unknown` to `string`, applying template conversions supplied at construction time or at
 * runtime as context.
 * @remarks
 * Template conversions are applied using `mustache` syntax.
 * @param defaultContext - Optional default context to use for template values.
 * @returns A new `Converter` returning `string`.
 * @public
 */
declare function templateString(defaultContext?: unknown): Conversion.StringConverter<string, unknown>;

/**
 * Implementation of `IFileTreeDirectoryItem` for directories in a ZIP archive.
 * @public
 */
declare class ZipDirectoryItem<TCT extends string = string> implements FileTree.IFileTreeDirectoryItem<TCT> {
    /**
     * Indicates that this `FileTree.FileTreeItem` is a directory.
     */
    readonly type: 'directory';
    /**
     * The absolute path of the directory within the ZIP archive.
     */
    readonly absolutePath: string;
    /**
     * The name of the directory
     */
    readonly name: string;
    /**
     * The ZIP file tree accessors that created this item.
     */
    private readonly _accessors;
    /**
     * Constructor for ZipDirectoryItem.
     * @param directoryPath - The path of the directory within the ZIP.
     * @param accessors - The ZIP file tree accessors.
     */
    constructor(directoryPath: string, accessors: ZipFileTreeAccessors<TCT>);
    /**
     * Gets the children of the directory.
     */
    getChildren(): Result<ReadonlyArray<FileTree.FileTreeItem<TCT>>>;
}

/**
 * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.
 * @public
 */
declare class ZipFileItem<TCT extends string = string> implements FileTree.IFileTreeFileItem<TCT> {
    /**
     * Indicates that this `FileTree.FileTreeItem` is a file.
     */
    readonly type: 'file';
    /**
     * The absolute path of the file within the ZIP archive.
     */
    readonly absolutePath: string;
    /**
     * The name of the file
     */
    readonly name: string;
    /**
     * The base name of the file (without extension)
     */
    readonly baseName: string;
    /**
     * The extension of the file
     */
    readonly extension: string;
    /**
     * The content type of the file.
     */
    get contentType(): TCT | undefined;
    /**
     * The pre-loaded contents of the file.
     */
    private readonly _contents;
    /**
     * The ZIP file tree accessors that created this item.
     */
    private readonly _accessors;
    /**
     * Mutable content type of the file.
     */
    private _contentType;
    /**
     * Flag to track if content type should be inferred on first access.
     */
    private _shouldInferContentType;
    /**
     * Constructor for ZipFileItem.
     * @param zipFilePath - The path of the file within the ZIP.
     * @param contents - The pre-loaded contents of the file.
     * @param accessors - The ZIP file tree accessors.
     */
    constructor(zipFilePath: string, contents: string, accessors: ZipFileTreeAccessors<TCT>);
    /**
     * Sets the content type of the file.
     * @param contentType - The content type of the file.
     */
    setContentType(contentType: TCT | undefined): void;
    /**
     * Gets the contents of the file as parsed JSON.
     */
    getContents(): Result<JsonValue>;
    getContents<T>(converter: Validator<T> | Converter<T>): Result<T>;
    /**
     * Gets the raw contents of the file as a string.
     */
    getRawContents(): Result<string>;
}

declare namespace ZipFileTree {
    export {
        ZipFileTreeAccessors,
        ZipFileItem,
        ZipDirectoryItem
    }
}
export { ZipFileTree }

/**
 * File tree accessors for ZIP archives.
 * @public
 */
declare class ZipFileTreeAccessors<TCT extends string = string> implements FileTree.IFileTreeAccessors<TCT> {
    /**
     * The unzipped file data.
     */
    private readonly _files;
    /**
     * Optional prefix to prepend to paths.
     */
    private readonly _prefix;
    /**
     * Content type inference function.
     */
    private readonly _inferContentType;
    /**
     * Cache of all items in the ZIP for efficient lookups.
     */
    private readonly _itemCache;
    /**
     * Constructor for ZipFileTreeAccessors.
     * @param files - The unzipped file data from fflate.
     * @param params - Optional initialization parameters.
     */
    private constructor();
    /**
     * Default function to infer the content type of a file.
     * @param filePath - The path of the file.
     * @param provided - Optional supplied content type.
     * @returns `Success` with the content type of the file if successful, or
     * `Failure` with an error message otherwise.
     * @remarks This default implementation always returns `Success` with `undefined`.
     * @public
     */
    static defaultInferContentType<TCT extends string = string>(__filePath: string, __provided?: string): Result<TCT | undefined>;
    /**
     * Creates a new ZipFileTreeAccessors instance from a ZIP file buffer (synchronous).
     * @param zipBuffer - The ZIP file as an ArrayBuffer or Uint8Array.
     * @param prefix - Optional prefix to prepend to paths.
     * @returns Result containing the ZipFileTreeAccessors instance.
     */
    static fromBuffer<TCT extends string = string>(zipBuffer: ArrayBuffer | Uint8Array, prefix?: string): Result<ZipFileTreeAccessors<TCT>>;
    /**
     * Creates a new ZipFileTreeAccessors instance from a ZIP file buffer (synchronous).
     * @param zipBuffer - The ZIP file as an ArrayBuffer or Uint8Array.
     * @param params - Optional initialization parameters.
     * @returns Result containing the ZipFileTreeAccessors instance.
     */
    static fromBuffer<TCT extends string = string>(zipBuffer: ArrayBuffer | Uint8Array, params?: FileTree.IFileTreeInitParams<TCT>): Result<ZipFileTreeAccessors<TCT>>;
    /**
     * Creates a new ZipFileTreeAccessors instance from a ZIP file buffer (asynchronous).
     * @param zipBuffer - The ZIP file as an ArrayBuffer or Uint8Array.
     * @param prefix - Optional prefix to prepend to paths.
     * @returns Promise containing Result with the ZipFileTreeAccessors instance.
     */
    static fromBufferAsync<TCT extends string = string>(zipBuffer: ArrayBuffer | Uint8Array, prefix?: string): Promise<Result<ZipFileTreeAccessors<TCT>>>;
    /**
     * Creates a new ZipFileTreeAccessors instance from a ZIP file buffer (asynchronous).
     * @param zipBuffer - The ZIP file as an ArrayBuffer or Uint8Array.
     * @param params - Optional initialization parameters.
     * @returns Promise containing Result with the ZipFileTreeAccessors instance.
     */
    static fromBufferAsync<TCT extends string = string>(zipBuffer: ArrayBuffer | Uint8Array, params?: FileTree.IFileTreeInitParams<TCT>): Promise<Result<ZipFileTreeAccessors<TCT>>>;
    /**
     * Creates a new ZipFileTreeAccessors instance from a File object (browser environment).
     * @param file - The File object containing ZIP data.
     * @param params - Optional initialization parameters.
     * @returns Result containing the ZipFileTreeAccessors instance.
     */
    static fromFile<TCT extends string = string>(file: File, params?: FileTree.IFileTreeInitParams<TCT>): Promise<Result<ZipFileTreeAccessors<TCT>>>;
    /**
     * Builds the cache of all items in the ZIP archive.
     */
    private _buildItemCache;
    /**
     * Resolves paths to an absolute path.
     */
    resolveAbsolutePath(...paths: string[]): string;
    /**
     * Gets the extension of a path.
     */
    getExtension(path: string): string;
    /**
     * Gets the base name of a path.
     */
    getBaseName(path: string, suffix?: string): string;
    /**
     * Joins paths together.
     */
    joinPaths(...paths: string[]): string;
    /**
     * Gets an item from the file tree.
     */
    getItem(path: string): Result<FileTree.FileTreeItem<TCT>>;
    /**
     * Gets the contents of a file in the file tree.
     */
    getFileContents(path: string): Result<string>;
    /**
     * Gets the content type of a file in the file tree.
     */
    getFileContentType(path: string, provided?: string): Result<TCT | undefined>;
    /**
     * Gets the children of a directory in the file tree.
     */
    getChildren(path: string): Result<ReadonlyArray<FileTree.FileTreeItem<TCT>>>;
    /**
     * Checks if childPath is a direct child of parentPath.
     */
    private _isDirectChild;
}

export { }