core.d.mts 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459
  1. type SelectOption = {
  2. label: string;
  3. value: string;
  4. hint?: string;
  5. };
  6. declare const kCancel: unique symbol;
  7. type PromptCommonOptions = {
  8. /**
  9. * Specify how to handle a cancelled prompt (e.g. by pressing Ctrl+C).
  10. *
  11. * Default strategy is `"default"`.
  12. *
  13. * - `"default"` - Resolve the promise with the `default` value or `initial` value.
  14. * - `"undefined`" - Resolve the promise with `undefined`.
  15. * - `"null"` - Resolve the promise with `null`.
  16. * - `"symbol"` - Resolve the promise with a symbol `Symbol.for("cancel")`.
  17. * - `"reject"` - Reject the promise with an error.
  18. */
  19. cancel?: "reject" | "default" | "undefined" | "null" | "symbol";
  20. };
  21. type TextPromptOptions = PromptCommonOptions & {
  22. /**
  23. * Specifies the prompt type as text.
  24. * @optional
  25. * @default "text"
  26. */
  27. type?: "text";
  28. /**
  29. * The default text value.
  30. * @optional
  31. */
  32. default?: string;
  33. /**
  34. * A placeholder text displayed in the prompt.
  35. * @optional
  36. */
  37. placeholder?: string;
  38. /**
  39. * The initial text value.
  40. * @optional
  41. */
  42. initial?: string;
  43. };
  44. type ConfirmPromptOptions = PromptCommonOptions & {
  45. /**
  46. * Specifies the prompt type as confirm.
  47. */
  48. type: "confirm";
  49. /**
  50. * The initial value for the confirm prompt.
  51. * @optional
  52. */
  53. initial?: boolean;
  54. };
  55. type SelectPromptOptions = PromptCommonOptions & {
  56. /**
  57. * Specifies the prompt type as select.
  58. */
  59. type: "select";
  60. /**
  61. * The initial value for the select prompt.
  62. * @optional
  63. */
  64. initial?: string;
  65. /**
  66. * The options to select from. See {@link SelectOption}.
  67. */
  68. options: (string | SelectOption)[];
  69. };
  70. type MultiSelectOptions = PromptCommonOptions & {
  71. /**
  72. * Specifies the prompt type as multiselect.
  73. */
  74. type: "multiselect";
  75. /**
  76. * The options to select from. See {@link SelectOption}.
  77. */
  78. initial?: string[];
  79. /**
  80. * The options to select from. See {@link SelectOption}.
  81. */
  82. options: (string | SelectOption)[];
  83. /**
  84. * Whether the prompt requires at least one selection.
  85. */
  86. required?: boolean;
  87. };
  88. /**
  89. * Defines a combined type for all prompt options.
  90. */
  91. type PromptOptions = TextPromptOptions | ConfirmPromptOptions | SelectPromptOptions | MultiSelectOptions;
  92. type inferPromptReturnType<T extends PromptOptions> = T extends TextPromptOptions ? string : T extends ConfirmPromptOptions ? boolean : T extends SelectPromptOptions ? T["options"][number] extends SelectOption ? T["options"][number]["value"] : T["options"][number] : T extends MultiSelectOptions ? T["options"] : unknown;
  93. type inferPromptCancalReturnType<T extends PromptOptions> = T extends {
  94. cancel: "reject";
  95. } ? never : T extends {
  96. cancel: "default";
  97. } ? inferPromptReturnType<T> : T extends {
  98. cancel: "undefined";
  99. } ? undefined : T extends {
  100. cancel: "null";
  101. } ? null : T extends {
  102. cancel: "symbol";
  103. } ? typeof kCancel : inferPromptReturnType<T>;
  104. /**
  105. * Asynchronously prompts the user for input based on specified options.
  106. * Supports text, confirm, select and multi-select prompts.
  107. *
  108. * @param {string} message - The message to display in the prompt.
  109. * @param {PromptOptions} [opts={}] - The prompt options. See {@link PromptOptions}.
  110. * @returns {Promise<inferPromptReturnType<T>>} - A promise that resolves with the user's response, the type of which is inferred from the options. See {@link inferPromptReturnType}.
  111. */
  112. declare function prompt<_ = any, __ = any, T extends PromptOptions = TextPromptOptions>(message: string, opts?: PromptOptions): Promise<inferPromptReturnType<T> | inferPromptCancalReturnType<T>>;
  113. /**
  114. * Defines the level of logs as specific numbers or special number types.
  115. *
  116. * @type {0 | 1 | 2 | 3 | 4 | 5 | (number & {})} LogLevel - Represents the log level.
  117. * @default 0 - Represents the default log level.
  118. */
  119. type LogLevel = 0 | 1 | 2 | 3 | 4 | 5 | (number & {});
  120. /**
  121. * A mapping of `LogType` to its corresponding numeric log level.
  122. *
  123. * @type {Record<LogType, number>} LogLevels - key-value pairs of log types to their numeric levels. See {@link LogType}.
  124. */
  125. declare const LogLevels: Record<LogType, number>;
  126. /**
  127. * Lists the types of log messages supported by the system.
  128. *
  129. * @type {"silent" | "fatal" | "error" | "warn" | "log" | "info" | "success" | "fail" | "ready" | "start" | "box" | "debug" | "trace" | "verbose"} LogType - Represents the specific type of log message.
  130. */
  131. type LogType = "silent" | "fatal" | "error" | "warn" | "log" | "info" | "success" | "fail" | "ready" | "start" | "box" | "debug" | "trace" | "verbose";
  132. /**
  133. * Maps `LogType` to a `Partial<LogObject>`, primarily defining the log level.
  134. *
  135. * @type {Record<LogType, Partial<LogObject>>} LogTypes - key-value pairs of log types to partial log objects, specifying log levels. See {@link LogType} and {@link LogObject}.
  136. */
  137. declare const LogTypes: Record<LogType, Partial<LogObject>>;
  138. interface ConsolaOptions {
  139. /**
  140. * An array of ConsolaReporter instances used to handle and output log messages.
  141. */
  142. reporters: ConsolaReporter[];
  143. /**
  144. * A record mapping LogType to InputLogObject, defining the log configuration for each log type.
  145. * See {@link LogType} and {@link InputLogObject}.
  146. */
  147. types: Record<LogType, InputLogObject>;
  148. /**
  149. * The minimum log level to output. See {@link LogLevel}.
  150. */
  151. level: LogLevel;
  152. /**
  153. * Default properties applied to all log messages unless overridden. See {@link InputLogObject}.
  154. */
  155. defaults: InputLogObject;
  156. /**
  157. * The maximum number of times a log message can be repeated within a given timeframe.
  158. */
  159. throttle: number;
  160. /**
  161. * The minimum time in milliseconds that must elapse before a throttled log message can be logged again.
  162. */
  163. throttleMin: number;
  164. /**
  165. * The Node.js writable stream for standard output. See {@link NodeJS.WriteStream}.
  166. * @optional
  167. */
  168. stdout?: NodeJS.WriteStream;
  169. /**
  170. * The Node.js writeable stream for standard error output. See {@link NodeJS.WriteStream}.
  171. * @optional
  172. */
  173. stderr?: NodeJS.WriteStream;
  174. /**
  175. * A function that allows you to mock log messages for testing purposes.
  176. * @optional
  177. */
  178. mockFn?: (type: LogType, defaults: InputLogObject) => (...args: any) => void;
  179. /**
  180. * Custom prompt function to use. It can be undefined.
  181. * @optional
  182. */
  183. prompt?: typeof prompt | undefined;
  184. /**
  185. * Configuration options for formatting log messages. See {@link FormatOptions}.
  186. */
  187. formatOptions: FormatOptions;
  188. }
  189. /**
  190. * @see https://nodejs.org/api/util.html#util_util_inspect_object_showhidden_depth_colors
  191. */
  192. interface FormatOptions {
  193. /**
  194. * The maximum number of columns to output, affects formatting.
  195. * @optional
  196. */
  197. columns?: number;
  198. /**
  199. * Whether to include timestamp information in log messages.
  200. * @optional
  201. */
  202. date?: boolean;
  203. /**
  204. * Whether to use colors in the output.
  205. * @optional
  206. */
  207. colors?: boolean;
  208. /**
  209. * Specifies whether or not the output should be compact. Accepts a boolean or numeric level of compactness.
  210. * @optional
  211. */
  212. compact?: boolean | number;
  213. /**
  214. * Error cause level.
  215. */
  216. errorLevel?: number;
  217. /**
  218. * Allows additional custom formatting options.
  219. */
  220. [key: string]: unknown;
  221. }
  222. interface InputLogObject {
  223. /**
  224. * The logging level of the message. See {@link LogLevel}.
  225. * @optional
  226. */
  227. level?: LogLevel;
  228. /**
  229. * A string tag to categorise or identify the log message.
  230. * @optional
  231. */
  232. tag?: string;
  233. /**
  234. * The type of log message, which affects how it's processed and displayed. See {@link LogType}.
  235. * @optional
  236. */
  237. type?: LogType;
  238. /**
  239. * The main log message text.
  240. * @optional
  241. */
  242. message?: string;
  243. /**
  244. * Additional text or texts to be logged with the message.
  245. * @optional
  246. */
  247. additional?: string | string[];
  248. /**
  249. * Additional arguments to be logged with the message.
  250. * @optional
  251. */
  252. args?: any[];
  253. /**
  254. * The date and time when the log message was created.
  255. * @optional
  256. */
  257. date?: Date;
  258. }
  259. interface LogObject extends InputLogObject {
  260. /**
  261. * The logging level of the message, overridden if required. See {@link LogLevel}.
  262. */
  263. level: LogLevel;
  264. /**
  265. * The type of log message, overridden if required. See {@link LogType}.
  266. */
  267. type: LogType;
  268. /**
  269. * A string tag to categorise or identify the log message, overridden if necessary.
  270. */
  271. tag: string;
  272. /**
  273. * Additional arguments to be logged with the message, overridden if necessary.
  274. */
  275. args: any[];
  276. /**
  277. * The date and time the log message was created, overridden if necessary.
  278. */
  279. date: Date;
  280. /**
  281. * Allows additional custom properties to be set on the log object.
  282. */
  283. [key: string]: unknown;
  284. }
  285. interface ConsolaReporter {
  286. /**
  287. * Defines how a log message is processed and displayed by this reporter.
  288. * @param logObj The LogObject containing the log information to process. See {@link LogObject}.
  289. * @param ctx An object containing context information such as options. See {@link ConsolaOptions}.
  290. */
  291. log: (logObj: LogObject, ctx: {
  292. options: ConsolaOptions;
  293. }) => void;
  294. }
  295. /**
  296. * Consola class for logging management with support for pause/resume, mocking and customisable reporting.
  297. * Provides flexible logging capabilities including level-based logging, custom reporters and integration options.
  298. *
  299. * @class Consola
  300. */
  301. declare class Consola {
  302. options: ConsolaOptions;
  303. _lastLog: {
  304. serialized?: string;
  305. object?: LogObject;
  306. count?: number;
  307. time?: Date;
  308. timeout?: ReturnType<typeof setTimeout>;
  309. };
  310. _mockFn?: ConsolaOptions["mockFn"];
  311. /**
  312. * Creates an instance of Consola with specified options or defaults.
  313. *
  314. * @param {Partial<ConsolaOptions>} [options={}] - Configuration options for the Consola instance.
  315. */
  316. constructor(options?: Partial<ConsolaOptions>);
  317. /**
  318. * Gets the current log level of the Consola instance.
  319. *
  320. * @returns {number} The current log level.
  321. */
  322. get level(): LogLevel;
  323. /**
  324. * Sets the minimum log level that will be output by the instance.
  325. *
  326. * @param {number} level - The new log level to set.
  327. */
  328. set level(level: LogLevel);
  329. /**
  330. * Displays a prompt to the user and returns the response.
  331. * Throw an error if `prompt` is not supported by the current configuration.
  332. *
  333. * @template T
  334. * @param {string} message - The message to display in the prompt.
  335. * @param {T} [opts] - Optional options for the prompt. See {@link PromptOptions}.
  336. * @returns {promise<T>} A promise that infer with the prompt options. See {@link PromptOptions}.
  337. */
  338. prompt<T extends PromptOptions>(message: string, opts?: T): Promise<(T extends TextPromptOptions ? string : T extends ConfirmPromptOptions ? boolean : T extends SelectPromptOptions ? T["options"][number] extends {
  339. label: string;
  340. value: string;
  341. hint?: string;
  342. } ? T["options"][number]["value"] : T["options"][number] : T extends MultiSelectOptions ? T["options"] : unknown) | (T extends {
  343. cancel: "reject";
  344. } ? never : T extends {
  345. cancel: "default";
  346. } ? T extends infer T_1 ? T_1 extends T ? T_1 extends TextPromptOptions ? string : T_1 extends ConfirmPromptOptions ? boolean : T_1 extends SelectPromptOptions ? T_1["options"][number] extends {
  347. label: string;
  348. value: string;
  349. hint?: string;
  350. } ? T_1["options"][number]["value"] : T_1["options"][number] : T_1 extends MultiSelectOptions ? T_1["options"] : unknown : never : never : T extends {
  351. cancel: "undefined";
  352. } ? undefined : T extends {
  353. cancel: "null";
  354. } ? null : T extends {
  355. cancel: "symbol";
  356. } ? typeof kCancel : T extends TextPromptOptions ? string : T extends ConfirmPromptOptions ? boolean : T extends SelectPromptOptions ? T["options"][number] extends {
  357. label: string;
  358. value: string;
  359. hint?: string;
  360. } ? T["options"][number]["value"] : T["options"][number] : T extends MultiSelectOptions ? T["options"] : unknown)>;
  361. /**
  362. * Creates a new instance of Consola, inheriting options from the current instance, with possible overrides.
  363. *
  364. * @param {Partial<ConsolaOptions>} options - Optional overrides for the new instance. See {@link ConsolaOptions}.
  365. * @returns {ConsolaInstance} A new Consola instance. See {@link ConsolaInstance}.
  366. */
  367. create(options: Partial<ConsolaOptions>): ConsolaInstance;
  368. /**
  369. * Creates a new Consola instance with the specified default log object properties.
  370. *
  371. * @param {InputLogObject} defaults - Default properties to include in any log from the new instance. See {@link InputLogObject}.
  372. * @returns {ConsolaInstance} A new Consola instance. See {@link ConsolaInstance}.
  373. */
  374. withDefaults(defaults: InputLogObject): ConsolaInstance;
  375. /**
  376. * Creates a new Consola instance with a specified tag, which will be included in every log.
  377. *
  378. * @param {string} tag - The tag to include in each log of the new instance.
  379. * @returns {ConsolaInstance} A new Consola instance. See {@link ConsolaInstance}.
  380. */
  381. withTag(tag: string): ConsolaInstance;
  382. /**
  383. * Adds a custom reporter to the Consola instance.
  384. * Reporters will be called for each log message, depending on their implementation and log level.
  385. *
  386. * @param {ConsolaReporter} reporter - The reporter to add. See {@link ConsolaReporter}.
  387. * @returns {Consola} The current Consola instance.
  388. */
  389. addReporter(reporter: ConsolaReporter): this;
  390. /**
  391. * Removes a custom reporter from the Consola instance.
  392. * If no reporter is specified, all reporters will be removed.
  393. *
  394. * @param {ConsolaReporter} reporter - The reporter to remove. See {@link ConsolaReporter}.
  395. * @returns {Consola} The current Consola instance.
  396. */
  397. removeReporter(reporter: ConsolaReporter): ConsolaReporter[] | this;
  398. /**
  399. * Replaces all reporters of the Consola instance with the specified array of reporters.
  400. *
  401. * @param {ConsolaReporter[]} reporters - The new reporters to set. See {@link ConsolaReporter}.
  402. * @returns {Consola} The current Consola instance.
  403. */
  404. setReporters(reporters: ConsolaReporter[]): this;
  405. wrapAll(): void;
  406. restoreAll(): void;
  407. /**
  408. * Overrides console methods with Consola logging methods for consistent logging.
  409. */
  410. wrapConsole(): void;
  411. /**
  412. * Restores the original console methods, removing Consola overrides.
  413. */
  414. restoreConsole(): void;
  415. /**
  416. * Overrides standard output and error streams to redirect them through Consola.
  417. */
  418. wrapStd(): void;
  419. _wrapStream(stream: NodeJS.WriteStream | undefined, type: LogType): void;
  420. /**
  421. * Restores the original standard output and error streams, removing the Consola redirection.
  422. */
  423. restoreStd(): void;
  424. _restoreStream(stream?: NodeJS.WriteStream): void;
  425. /**
  426. * Pauses logging, queues incoming logs until resumed.
  427. */
  428. pauseLogs(): void;
  429. /**
  430. * Resumes logging, processing any queued logs.
  431. */
  432. resumeLogs(): void;
  433. /**
  434. * Replaces logging methods with mocks if a mock function is provided.
  435. *
  436. * @param {ConsolaOptions["mockFn"]} mockFn - The function to use for mocking logging methods. See {@link ConsolaOptions["mockFn"]}.
  437. */
  438. mockTypes(mockFn?: ConsolaOptions["mockFn"]): void;
  439. _wrapLogFn(defaults: InputLogObject, isRaw?: boolean): (...args: any[]) => false | undefined;
  440. _logFn(defaults: InputLogObject, args: any[], isRaw?: boolean): false | undefined;
  441. _log(logObj: LogObject): void;
  442. }
  443. interface LogFn {
  444. (message: InputLogObject | any, ...args: any[]): void;
  445. raw: (...args: any[]) => void;
  446. }
  447. type ConsolaInstance = Consola & Record<LogType, LogFn>;
  448. /**
  449. * Utility for creating a new Consola instance with optional configuration.
  450. *
  451. * @param {Partial<ConsolaOptions>} [options={}] - Optional configuration options for the new Consola instance. See {@link ConsolaOptions}.
  452. * @returns {ConsolaInstance} A new instance of Consola. See {@link ConsolaInstance}.
  453. */
  454. declare function createConsola(options?: Partial<ConsolaOptions>): ConsolaInstance;
  455. export { type ConfirmPromptOptions, Consola, type ConsolaInstance, type ConsolaOptions, type ConsolaReporter, type FormatOptions, type InputLogObject, type LogLevel, LogLevels, type LogObject, type LogType, LogTypes, type MultiSelectOptions, type PromptOptions, type SelectPromptOptions, type TextPromptOptions, createConsola };