regex-explain 0.0.0-stage → 1.0.0

package/dist/cjs/explainer.d.ts

@@ -0,0 +1,123 @@
+/** One explained piece of the pattern. */
+export interface ExplanationNode {
+    /** The pattern source this node explains. */
+    readonly raw: string;
+    /** Offset of `raw` in the pattern, inclusive. */
+    readonly start: number;
+    /** Offset of `raw` in the pattern, exclusive. */
+    readonly end: number;
+    /** A sentence or noun phrase describing `raw`. May contain Markdown code spans. */
+    readonly description: string;
+    /** Explanations of the parts of `raw`, in source order. */
+    readonly children: readonly ExplanationNode[];
+}
+/** The meaning of one flag. */
+export interface FlagExplanation {
+    /** The flag letter, such as `g`. */
+    readonly flag: string;
+    /** The `RegExp` property the flag sets, such as `global`. */
+    readonly name: string;
+    /** What the flag does. May contain Markdown code spans. */
+    readonly description: string;
+}
+/** A regex as `new RegExp(pattern, flags)` takes it: the pattern without slashes, and the flags. */
+export interface RegexSource {
+    /** The pattern, without slashes. */
+    readonly pattern: string;
+    /** The flags. */
+    readonly flags: string;
+}
+/**
+ * Checks whether a value is a {@link RegexSource}, such as an untyped command argument.
+ *
+ * @param value The value.
+ *
+ * @returns Whether the value has string `pattern` and `flags` properties.
+ */
+export declare function isRegexSource(value: unknown): value is RegexSource;
+/** A pattern that can take super-linear time to reject some inputs (ReDoS). */
+export interface BacktrackingWarning {
+    /** The quantifier that backtracks, as pattern source. */
+    readonly raw: string;
+    /** Offset of `raw` in the pattern, inclusive. */
+    readonly start: number;
+    /** Offset of `raw` in the pattern, exclusive. */
+    readonly end: number;
+    /** Whether the backtracking is exponential rather than polynomial. */
+    readonly exponential: boolean;
+    /** A character that, repeated many times, triggers the backtracking. */
+    readonly attackCharacter: string;
+    /** What the problem is. May contain Markdown code spans. */
+    readonly description: string;
+    /** An equivalent regex without this problem, when one could be derived. */
+    readonly fix?: RegexSource;
+}
+/** How long a match can be. */
+export interface LengthSummary {
+    /** The fewest characters a match consumes. */
+    readonly min: number;
+    /** The most characters a match consumes; `Infinity` when unbounded. */
+    readonly max: number;
+}
+/** A successfully explained regex. */
+export interface RegexExplanation extends RegexSource {
+    /** Discriminates success from {@link RegexExplanationError}. */
+    readonly ok: true;
+    /** Top-level explanation steps, in match order. */
+    readonly nodes: readonly ExplanationNode[];
+    /** The meaning of each flag, in the order given. */
+    readonly flagExplanations: readonly FlagExplanation[];
+    /** How long a match can be. */
+    readonly length: LengthSummary;
+    /** Catastrophic backtracking problems; empty when none were found or the check was disabled. */
+    readonly warnings: readonly BacktrackingWarning[];
+    /**
+     * Whether `^` and `$` match at line breaks anywhere in the pattern, through the `m` flag or a
+     * group such as `(?m:...)`, so that text is matched as separate lines.
+     */
+    readonly multiline: boolean;
+}
+/** A regex that could not be parsed. */
+export interface RegexExplanationError extends RegexSource {
+    /** Discriminates failure from {@link RegexExplanation}. */
+    readonly ok: false;
+    /** The parser's error message. */
+    readonly message: string;
+    /** Offset into the pattern where the error was detected, if known. */
+    readonly index?: number;
+}
+/** The result of {@link explainRegex}. */
+export type ExplainResult = RegexExplanation | RegexExplanationError;
+/** Options for {@link explainRegex}. */
+export interface ExplainOptions {
+    /** Check for catastrophic backtracking. Defaults to `true`. */
+    readonly checkBacktracking?: boolean;
+}
+/**
+ * Explains a regex pattern compiled with the given flags. Syntax errors are returned, not thrown.
+ *
+ * @param pattern The pattern without surrounding slashes, as passed to `new RegExp()`.
+ * @param flags The flags, such as `"gi"`.
+ * @param options Analysis options.
+ *
+ * @returns The explanation, or the reason the pattern is invalid.
+ */
+export declare function explainRegex(pattern: string, flags?: string, options?: ExplainOptions): ExplainResult;
+/**
+ * Reads typed or selected text as a regex.
+ *
+ * @param text Either a literal such as `/ab+c/gi`, optionally surrounded by whitespace, or a bare
+ *   pattern.
+ *
+ * @returns The regex; bare patterns have no flags. The pattern is not validated.
+ */
+export declare function parseRegexInput(text: string): RegexSource;
+/**
+ * Words a repetition count.
+ *
+ * @param min The minimum count.
+ * @param max The maximum count; `Infinity` when unbounded.
+ *
+ * @returns A phrase such as "one or more times".
+ */
+export declare function describeCount(min: number, max: number): string;