datakit/build/index.d.ts

Simple JavaScript toolkit for data transform across JSON, CSV and YAML.

/**
 * Represents a field from a JavaScript object.
 */
export interface IFieldDesc {
    /**
     * The name of the field.
     */
    field: string;
    /**
     * The value of the field.
     */
    value: any;
}
/**
 * Convert a regular JavaScript object to 'tablular data'.
 * Each element of the matches a field from the object.
 *
 * @param obj - The JavaScript object to convert to a dataframe.
 *
 * @returns Returns an array with an element describing each field.
 */
export declare function fromObject(obj: any): IFieldDesc[];
/**
 * Configures parsing for named fields in the JSON data.
 */
export interface IFieldParserConfig {
    [fieldName: string]: (value: string) => any;
}
/**
 * Configuration for JSON deserialization.
 */
export interface IJsonInputConfig {
    /**
     * Configures parsing for named fields in the JSON data.
     */
    parser?: IFieldParserConfig;
}
/**
 * Deserialize JSON text to a JavaScript array.
 *
 * @param jsonTextString The JSON text to deserialize.
 *
 * @returns Returns an array of JavaScript objects that were deserialized from the JSON text.
 */
export declare function fromJson<RecordT>(jsonTextString: string, config?: IJsonInputConfig): RecordT[];
/**
 * Configures parsing for named columns in the CSV data.
 */
export interface IColumnParserConfig {
    [columnName: string]: (value: string) => any;
}
/**
 * Configuration for CSV deserialization.
 */
export interface ICsvInputConfig {
    /**
     * Configure parsing for named columns in the CSV data.
     */
    parser?: IColumnParserConfig;
    /**
     * Optionally specifies the column names (when enabled, assumes that the header row is not read from the CSV data).
     * Default: undefined
     */
    columnNames?: string[];
    /**
     * Automatically pick types based on what the value looks like.
     * Default: false.
     */
    dynamicTyping?: boolean;
    /**
     * Skip empty lines in the input.
     * Default: true
     */
    skipEmptyLines?: boolean;
}
/**
 * Deserialize CSV text to a JavaScript array.
 * Each element of the array contains fields that match the columns from the CSV data.
 *
 * @param csvTextString The CSV text to deserialize.
 * @param [config] Optional configuration options for parsing the CSV data.
 *
 * @returns Returns an array of JavaScript objects that were deserialized from the CSV text.
 */
export declare function fromCsv<RecordT>(csvTextString: string, config?: ICsvInputConfig): RecordT[];
/**
 * Deserialize YAML text to a JavaScript array.
 *
 * @param yamlTextString The YAML text to deserialize.
 *
 * @returns Returns an array of JavaScript objects that were deserialized from the YAML text.
 */
export declare function fromYaml<RecordT>(yamlTextString: string): RecordT[];
/**
 * Like fs.readFile but returns a promise for the file data.
 *
 * @param filePath Path to the file to be loaded.
 *
 * @returns A promise that is resolved with the contents of the file.
 *
 * @example
 * <pre>
 *
 * const data = await datakit.readFile("some-data-file.txt");
 * console.log(data);
 * </pre>
 *
 */
export declare function readFile(filePath: string): Promise<string>;
/**
 * Asynchronously deserialize a CSV file to a JavaScript array.
 * Each element of the array contains fields that match the columns from the CSV file.
 *
 * @param filePath Path to the file to be loaded.
 * @param [config] Optional configuration file for parsing.
 *
 * @returns Returns a promise for the loaded data.
 *
 * @example
 * <pre>
 *
 * const data = await datakit.readCsv("my-data-file.csv");
 * console.log(data);
 * </pre>
 *
 * const config = {
 *     dynamicTyping: true,
 *     // ... other options ...
 * };
 * const data = await datakit.readCsv("my-data-file.csv", config);
 * console.log(data);
 * </pre>
 */
export declare function readCsv<RecordT>(filePath: string, config?: ICsvInputConfig): Promise<RecordT[]>;
/**
 * Asynchronously deserialize a JSON file to a JavaScript array.
 *
 * @param filePath Path to the file to be loaded.
 *
 * @returns Returns a promise for the loaded data.
 *
 * @example
 * <pre>
 *
 * const data = await datakit.readJson("my-data-file.json");
 * console.log(data);
 * </pre>
 */
export declare function readJson<RecordT>(filePath: string): Promise<RecordT[]>;
/**
 * Asynchronously deserialize a YAML file to a JavaScript array.
 *
 * @param filePath Path to the file to be loaded.
 *
 * @returns Returns a promise for the loaded data.
 *
 * @example
 * <pre>
 *
 * const data = await datakit.readYaml("my-data-file.yaml");
 * console.log(data);
 * </pre>
 */
export declare function readYaml<RecordT>(filePath: string): Promise<RecordT[]>;
/**
 * Synchronously deserialize a CSV file to a JavaScript array.
 * Each element of the array contains fields that match the columns from the CSV file.
 *
 * @param filePath Path to the file to be loaded.
 * @param [config] Optional configuration file for parsing.
 *
 * @returns Returns the loaded data.
 *
 * @example
 * <pre>
 *
 * const data = datakit.readCsvSync("my-data-file.csv");
 * console.log(data);
 * </pre>
 *
 * @example
 * <pre>
 *
 * const config = {
 *     dynamicTyping: true,
 *     // ... other options ...
 * };
 * const data = datakit.readCsvSync("my-data-file.csv", config);
 * console.log(data);
 * </pre>
 */
export declare function readCsvSync<RecordT>(filePath: string, config?: ICsvInputConfig): RecordT[];
/**
 * Synchronously deserialize a JSON file to a JavaScript array.
 *
 * @param filePath Path to the file to be loaded.
 *
 * @returns Returns the loaded data.
 *
 * @example
 * <pre>
 *
 * const data = datakit.readJsonSync("my-data-file.json");
 * console.log(data);
 * </pre>
 */
export declare function readJsonSync<RecordT>(filePath: string): RecordT[];
/**
 * Synchronously deserialize a YAML file to a JavaScript array.
 *
 * @param filePath Path to the file to be loaded.
 *
 * @returns Returns the loaded data.
 *
 * @example
 * <pre>
 *
 * const data = datakit.readYamlSync("my-data-file.yaml");
 * console.log(data);
 * </pre>
 */
export declare function readYamlSync<RecordT>(filePath: string): RecordT[];
/**
 * Configures formatting for named fields in the JSON data.
 */
export interface IFieldFormatterConfig {
    [fieldName: string]: (value: string) => any;
}
/**
 * Configuration for JSON serialization.
 */
export interface IJsonOutputConfig {
    /**
     * Configures formatting for named fields in the JSON data.
     */
    formatter?: IColumnFormatterConfig;
}
/**
 * Serialize a JavaScript array to the JSON data format.
 *
 * @param input The data to be serialized.
 *
 * @return Returns a string in the JSON data format that represents the data.
 *
 * @example
 * <pre>
 *
 * const data = ... JavaScript data ...;
 * const jsonData = datakit.toJson(data);
 * console.log(jsonData);
 * </pre>
 */
export declare function toJson(input: any[], config?: IJsonOutputConfig): string;
/**
 * Configures formatting for named columns in the CSV data.
 */
export interface IColumnFormatterConfig {
    [columnName: string]: (value: string) => any;
}
/**
 * Configuration for CSV serialization.
 */
export interface ICsvOutputConfig {
    /**
     * Configures formatting for named columns in the CSV data.
     */
    formatter?: IColumnFormatterConfig;
    /**
     * Enable or disable output of the CSV header line.
     * Defaults to true.
     */
    header?: boolean;
    /**
     * Names of columns to output.
     */
    columnNames?: string[];
}
/**
 * Serialize a JavaScript array to the CSV data format.
 * Columns in the CSV file match fields from the objects in the array.
 *
 * @param input The data to be serialized.
 *
 * @return Returns a string in the CSV data format that represents the data.
 *
 * @example
 * <pre>
 *
 * const data = [ ... JavaScript array of data ... ];
 * const csvData = datakit.toCsv(data);
 * console.log(csvData);
 * </pre>
 *
 * @example
 * <pre>
 *
 * const data = [ ... JavaScript array of data ... ];
 * const config = {
 *     header: false,
 *     // ... other options ...
 * };
 * const csvData = datakit.toCsv(data, config);
 * console.log(csvData);
 * </pre>
 */
export declare function toCsv(input: any[], config?: ICsvOutputConfig): string;
/**
 * Serialize a JavaScript array to the YAML data format.
 *
 * @param input The data to be serialized.
 *
 * @return Returns a string in the YAML data format that represents the data.
 *
 * @example
 * <pre>
 *
 * const data = [ ... JavaScript array of data ... ];
 * const yamlData = datakit.toYaml(data);
 * console.log(yamlData);
 * </pre>
 */
export declare function toYaml(input: any[]): string;
/**
 * Like fs.writeFile but returns a promise for completion of the asynchronous file write.
 *
 * @param filePath Path to the file to be written.
 * @param data Data to be written the to file.
 *
 * @returns A promise that is resolved when the file has been written.
 *
 * @example
 * <pre>
 *
 * const data = "... JavaScript string with text data ...";
 * await datakit.writeFile("some-data-file.txt", data);
 * </pre>
 *
 */
export declare function writeFile(filePath: string, data: string): Promise<void>;
/**
 * Asynchronously serialize a JavaScript array to a CSV file.
 * The fields in the objects of the array become the columns in the CSV file.
 *
 * @param filePath Path to the file to be written.
 * @param [config] Optional configuration file for parsing.
 *
 * @return Returns a promise that resolves when the file has been written.
 *
 * @example
 * <pre>
 *
 * const data = [ ... JavaScript array of data ... ];
 * await datakit.writeCsv("my-data-file.csv", data);
 * </pre>
 *
 * @example
 * <pre>
 * const config = {
 *     // ... Options for serialization ...
 * };
 * const data = [ ... JavaScript array of data ... ];
 * await datakit.writeCsv("my-data-file.csv", config);
 * </pre>
 */
export declare function writeCsv(filePath: string, input: any[], config?: ICsvOutputConfig): Promise<void>;
/**
 * Synchronously serialize a JavaScript array to a CSV file.
 * The fields in the objects of the array become the columns in the CSV file.
 *
 * @param filePath Path to the file to be written.
 * @param [config] Optional configuration file for parsing.
 *
 * @example
 * <pre>
 *
 * const data = [ ... JavaScript array of data ... ];
 * datakit.writeCsvSync("my-data-file.csv", data);
 * </pre>
 *
 * @example
 * <pre>
 *
 * const config = {
 *     // ... Options for serialization ...
 * };
 * const data = [ ... JavaScript array of data ... ];
 * datakit.writeCsvSync("my-data-file.csv", config);
 * </pre>
 */
export declare function writeCsvSync(filePath: string, input: any[], config?: ICsvOutputConfig): void;
/**
 * Asynchronously serialize a JavaScript array to a JSON file.
 *
 * @param filePath Path to the file to be written.
 *
 * @return Returns a promise that resolves when the file has been written.
 *
 * @example
 * <pre>
 *
 * const data = [ ... JavaScript array of data ... ];
 * await datakit.writeJson("my-data-file.json", data);
 * </pre>
 */
export declare function writeJson(filePath: string, input: any[]): Promise<void>;
/**
 * Synchronously serialize a JavaScript array to a JSON file.
 *
 * @param filePath Path to the file to be written.
 *
 * @return Returns a promise that resolves when the file has been written.
 *
 * @example
 * <pre>
 *
 * const data = [ ... JavaScript array of data ... ];
 * datakit.writeJsonSync("my-data-file.json", data);
 * </pre>
 */
export declare function writeJsonSync(filePath: string, input: any[]): void;
/**
 * Asynchronously serialize a JavaScript array to a YAML file.
 *
 * @param filePath Path to the file to be written.
 *
 * @return Returns a promise that resolves when the file has been written.
 *
 * @example
 * <pre>
 *
 * const data = [ ... JavaScript array of data ... ];
 * await datakit.writeYaml("my-data-file.yaml", data);
 * </pre>
 */
export declare function writeYaml(filePath: string, input: any[]): Promise<void>;
/**
 * Synchronously serialize a JavaScript array to a Yaml file.
 *
 * @param filePath Path to the file to be written.
 *
 * @return Returns a promise that resolves when the file has been written.
 *
 * @example
 * <pre>
 *
 * const data = [ ... JavaScript array of data ... ];
 * datakit.writeYamlSync("my-data-file.yaml", data);
 * </pre>
 */
export declare function writeYamlSync(filePath: string, input: any[]): void;