mdat/dist/lib/index.d.ts

CLI tool and TypeScript library implementing the Markdown Autophagic Template (MDAT) system. MDAT lets you use comments as dynamic content templates in Markdown files, making it easy to generate and update readme boilerplate.

import { Options, Rules } from "remark-mdat";
import { VFile } from "vfile";
import { Simplify } from "type-fest";

//#region src/lib/config.d.ts
type Config = Simplify<Options & {
  assetsPath?: string;
  packageFile?: string;
}>;
type ConfigLoaded = {
  addMetaComment: boolean | string;
  assetsPath: string;
  closingPrefix: string;
  keywordPrefix: string;
  metaCommentIdentifier: string;
  packageFile: string | undefined;
  rules: Rules;
};
/**
 * Generously accept either string paths to .ts, .js, or .json files with
 * `Config` type default exports. Takes a single value, or an array of values which
 * will be merged right to left.
 */
type ConfigToLoad = Array<Config | string> | Config | string;
/**
 * Generously accept either string paths to .ts, .js, or .json files with
 * `Rules` type default exports.
 */
type RulesToLoad = Array<Rules | string> | Rules | string;
/**
 * Load and validate mdat configuration / rule sets
 * Uses cosmiconfig to search in the usual places.
 * Merge precedence: Base Defaults < Readme Defaults < Searched Config < Additional Config Paths
 *
 * Generic to accommodate additional Config options, so set T to your custom config type if needed. You must provide a matching configExtensionSchema as well.
 */
declare function loadConfig(options?: {
  /**
   * Additional Config objects to merge.
   *
   * Strings are treated as paths to `ts`, `js`, or `json` files with `Config` type default exports. These will be dynamically loaded by Cosmiconfig.
   * Accepts an individual item, or an array. Objects in the array will be merged right to left.
   *
   */
  additionalConfig?: ConfigToLoad;
  /**
   * Additional Rules objects to merge.
   *
   * Strings are treated as paths to `ts`, `js`, or `json` files with `Rules` type default exports. These will be dynamically loaded by Cosmiconfig.
   * Accepts an individual item, or an array. Objects in the array will be merged right to left, and take precedence over any rules in previously loaded Config objects as well.
   */
  additionalRules?: RulesToLoad;
  /**
   * Readme-specific defaults that have higher priority than base defaults but lower than searched config.
   * Used internally by loadConfigReadme.
   */
  readmeDefaults?: Config; /** Search for config in specific directories, mainly useful for testing. Cosmiconfig default search paths used if unset. */
  searchFrom?: string;
}): Promise<ConfigLoaded>;
/**
 * Convenience function for merging configs
 * Performs a deep merge, with the rightmost object taking precedence
 */
declare function mergeConfigs(a: Config, b: Config): Config;
//#endregion
//#region src/lib/api.d.ts
/**
 * Expand MDAT comments in one or more Markdown files
 * Writing is the responsibility of the caller (e.g. via `await write(result)`)
 * @returns an array of VFiles (Even if you only pass a single file path!)
 */
declare function expandFiles(files: string | string[], name?: string, output?: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
/**
 * Expand MDAT comments in a Markdown string
 */
declare function expandString(markdown: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile>;
/**
 * Check and validate MDAT comments in one or more Markdown files
 * @returns an array of VFiles (Even if you only pass a single file path!)
 */
declare function checkFiles(files: string | string[], name?: string, output?: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
/**
 * Check and validate MDAT comments in a Markdown string
 */
declare function checkString(markdown: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile>;
/**
 * Collapse MDAT comments in one or more Markdown files
 * Writing is the responsibility of the caller (e.g. via `await write(result)`)
 * @returns an array of VFiles (Even if you only pass a single file path!)
 */
declare function collapseFiles(files: string | string[], name?: string, output?: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
/**
 * Collapse MDAT comments in a Markdown string
 */
declare function collapseString(markdown: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile>;
//#endregion
//#region src/lib/readme/api.d.ts
/**
 * Expands MDAT readme comments in the closest readme.md file
 * Basically an alias to `expandReadmeFiles()` with certain arguments elided.
 * @see `findReadme()` for more details on the search process.
 */
declare function expandReadme(config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
/**
 * Expands MDAT readme comments in one or more Markdown files
 * Searches up for a readme.md file if none is provided.
 * @see `findReadme()` for more details on the search process.
 */
declare function expandReadmeFiles(files?: string | string[], name?: string, output?: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
/**
 * Expands MDAT readme comments in a Markdown string
 */
declare function expandReadmeString(markdown: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile>;
/**
 * Checks and validates MDAT readme comments in the closest readme.md file
 * Basically an alias to `checkReadmeFiles()` with certain arguments elided.
 * @see `findReadme()` for more details on the search process.
 */
declare function checkReadme(config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
/**
 * Checks and validates MDAT readme comments in one or more Markdown files
 * Searches up for a readme.md file if none is provided.
 * @see `findReadme()` for more details on the search process.
 */
declare function checkReadmeFiles(files?: string | string[], name?: string, output?: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
/**
 * Checks and validates MDAT readme comments in a Markdown string
 */
declare function checkReadmeString(markdown: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile>;
/**
 * Collapses MDAT readme comments in the closest readme.md file
 * Basically an alias to `collapseReadmeFiles()` with certain arguments elided.
 * @see `findReadme()` for more details on the search process.
 */
declare function collapseReadme(config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
/**
 * Collapses MDAT readme comments in one or more Markdown files
 * Searches up for a readme.md file if none is provided.
 * @see `findReadme()` for more details on the search process.
 */
declare function collapseReadmeFiles(files?: string | string[], name?: string, output?: string, config?: ConfigToLoad, rules?: RulesToLoad): Promise<VFile[]>;
//#endregion
//#region src/lib/readme/config.d.ts
type ReadmeConfigLoaded = Simplify<ConfigLoaded & {
  packageFile: string;
}>;
type LoadConfigOptions = Parameters<typeof loadConfig>[0];
/**
 * Convenience loader to always include the default readme config.
 * The readme defaults should have lower priority than searched/user config,
 * but higher priority than base mdat defaults.
 */
declare function loadConfigReadme(options?: LoadConfigOptions): Promise<ReadmeConfigLoaded>;
//#endregion
export { type Config, type Rules, checkFiles, checkReadme, checkReadmeFiles, checkReadmeString, checkString, collapseFiles, collapseReadme, collapseReadmeFiles, collapseString, expandFiles, expandReadme, expandReadmeFiles, expandReadmeString, expandString, loadConfig, loadConfigReadme, mergeConfigs };