tablemark/dist/index.d.ts

Generate markdown tables from a list of objects or JSON data.

import * as changeCase from "change-case";

//#region src/constants.d.ts
declare const alignmentOptions: {
  readonly left: "left";
  readonly center: "center";
  readonly right: "right";
};
declare const headerCaseOptions: Record<HeaderCase, HeaderCase>;
declare const unknownKeyStrategies: {
  readonly ignore: "ignore";
  readonly throw: "throw";
};
declare const overflowStrategies: {
  readonly wrap: "wrap";
  readonly truncateStart: "truncateStart";
  readonly truncateEnd: "truncateEnd";
};
declare const lineBreakStrategies: {
  readonly preserve: "preserve";
  readonly truncate: "truncate";
  readonly strip: "strip";
};
declare const textHandlingStrategies: {
  readonly auto: "auto";
  readonly basic: "basic";
  readonly advanced: "advanced";
};
//#endregion
//#region src/types.d.ts
type ChangeCaseExports = keyof typeof changeCase;
type TextCaseMethod = keyof { [TKey in ChangeCaseExports as TKey extends `${string}Case` ? TKey : never]: (typeof changeCase)[TKey] };
/**
 * Text casing methods supported for column titles.
 */
type HeaderCase = TextCaseMethod | "preserve";
type LooseObject = Record<string, unknown>;
type DataRecord = Record<string, string>;
type InputData<T = LooseObject> = readonly T[];
type NonEmptyInputData<T = LooseObject> = [T, ...T[]];
type NonEmptyData<T = DataRecord> = [T, ...T[]];
type GetDataKeys<T extends InputData> = keyof T[0];
type Alignment = keyof typeof alignmentOptions;
type UnknownKeyStrategy = keyof typeof unknownKeyStrategies;
type OverflowStrategy = keyof typeof overflowStrategies;
type LineBreakStrategy = keyof typeof lineBreakStrategies;
type TextHandlingStrategy = keyof typeof textHandlingStrategies;
interface ColumnDescriptor {
  /**
   * Alignment to use for this column.
   */
  align?: Alignment;
  /**
   * Maximum content width of this column, overriding the root configuration.
   */
  maxWidth?: number;
  /**
   * Text to use as the column title.
   */
  name?: string;
  /**
   * What to do when this column's content reaches `maxWidth`, overriding the
   * root configuration.
   */
  overflowStrategy?: OverflowStrategy;
  /**
   * What to do when this column's header content reaches `maxWidth`, overriding
   * the root configuration.
   */
  overflowHeaderStrategy?: OverflowStrategy;
  /**
   * Which text processing method to use for this column, overriding the root
   * configuration.
   */
  textHandlingStrategy?: TextHandlingStrategy;
  /**
   * Fixed display width for the column, overriding both the root
   * configuration's `maxWidth` property and this column's `maxWidth`.
   */
  width?: number;
}
interface ToHeaderTitle<TKey = string> {
  (props: {
    /**
     * Original object key.
     */
    key: TKey;
    /**
     * Column title with casing applied according to `config.headerCase`.
     */
    title: string;
  }): string;
}
interface ToCellText<TKey = string> {
  (props: {
    /**
     * Original object key.
     */
    key: TKey;
    /**
     * Input value which can be altered before being rendered into the table cell.
     */
    value: unknown;
  }): string;
}
interface TablemarkOptions<TData extends InputData = InputData, TKey = keyof TData[0]> {
  /**
   * Default alignment to use for all columns, `left` by default.
   */
  align?: Alignment;
  /**
   * @deprecated Use `headerCase: "preserve"` or `headerCase: "sentenceCase"` instead.
   */
  caseHeaders?: boolean;
  /**
   * Array for configuring individual columns, where each element sets options
   * for its corresponding item in the input data.
   *
   * Each element can be either an object, in which case its properties control
   * the display of the column (overriding the same settings from the root
   * configuration), or a `string` to be used as the column title.
   */
  columns?: (ColumnDescriptor | string)[];
  /**
   * Whether to count ANSI escape codes when calculating string width. The
   * default is `false`, meaning ANSI escape codes are treated as zero-width.
   */
  countAnsiEscapeCodes?: boolean;
  /**
   * Text casing method for header titles derived from input object keys.
   */
  headerCase?: HeaderCase;
  /**
   * What to do when cell content contains line breaks. The default is
   * "preserve".
   */
  lineBreakStrategy?: LineBreakStrategy;
  /**
   * Text to use as the line ending, `\n` by default.
   */
  lineEnding?: string;
  /**
   * Maximum content width of all columns. The default is `Infinity`, meaning
   * columns will fit to content width.
   */
  maxWidth?: number;
  /**
   * @deprecated Use `maxWidth` instead.
   */
  wrapWidth?: number;
  /**
   * What to do when body cell content reaches `maxWidth`. The default is
   * "wrap".
   */
  overflowStrategy?: OverflowStrategy;
  /**
   * What to do when header cell content reaches `maxWidth`. The default is
   * "wrap".
   */
  overflowHeaderStrategy?: OverflowStrategy;
  /**
   * Include padding on the header separator row, `true` by default.
   */
  padHeaderSeparator?: boolean;
  /**
   * Function used to convert input values to `string`s suitable for display
   * in the output table. By default all values are converted using `String()`
   * and `|` characters are escaped.
   */
  toCellText?: ToCellText<TKey>;
  /**
   * Function used to transform header titles, receiving as arguments both the
   * original object key as well as the title (cased according to `headerCase`).
   */
  toHeaderTitle?: ToHeaderTitle<TKey>;
  /**
   * Strategy for handling unknown keys, `"ignore"` by default.
   */
  unknownKeyStrategy?: UnknownKeyStrategy;
  /**
   * The default "auto" strategy detects and provides broader support of
   * languages, Unicode entities like emoji and
   * [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms)
   * characters, and ANSI escape codes (like terminal colors and styles).
   *
   * To force this enhanced support, set this to `"advanced"`.
   *
   * To force using a faster, more "naive" strategy, set this to `"basic"`.
   * However, this can result in misaligned columns and improper ANSI styling.
   *
   * Note that ANSI escape codes are treated as zero-width regardless of the
   * strategy. If you want to change that behavior, use the
   * `countAnsiEscapeCodes` option.
   */
  textHandlingStrategy?: TextHandlingStrategy;
  /**
   * Whether to add `|` characters when wrapping within rows.
   */
  wrapWithGutters?: boolean;
}
type TablemarkOptionsNormalized = Omit<{ [key in keyof TablemarkOptions]-?: TablemarkOptions[key] }, "caseHeaders" | "columns" | "toHeaderTitle" | "wrapWidth"> & {
  columns: ColumnDescriptor[];
  toHeaderTitle?: TablemarkOptions["toHeaderTitle"];
  stringWidthMethod: (string: string) => number;
  stringWrapMethod: (string: string, width: number) => string[];
};
//#endregion
//#region src/utilities.d.ts
/**
 * The default cell content transformer.
 */
declare const toCellText: ToCellText;
//#endregion
//#region src/index.d.ts
declare const tablemark: <T extends InputData>(input: T, options?: TablemarkOptions<T>) => string;
//#endregion
export { Alignment, ColumnDescriptor, DataRecord, GetDataKeys, HeaderCase, InputData, LineBreakStrategy, LooseObject, NonEmptyData, NonEmptyInputData, OverflowStrategy, TablemarkOptions, TablemarkOptionsNormalized, TextHandlingStrategy, ToCellText, ToHeaderTitle, UnknownKeyStrategy, alignmentOptions, headerCaseOptions, lineBreakStrategies, overflowStrategies, tablemark, textHandlingStrategies, toCellText, unknownKeyStrategies };