mdat 1.3.4 → 1.4.0

package/dist/lib/index.d.ts

@@ -0,0 +1,155 @@
+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 };