easy-regex-lib 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,308 @@
+/** JSON schema version for serialized patterns. */
+declare const PATTERN_SCHEMA_VERSION: 1;
+type PatternFlags = {
+    /** Case-insensitive matching (`i`) */
+    ignoreCase?: boolean;
+    /** `m` — ^ and $ match line boundaries */
+    multiline?: boolean;
+    /** `s` — dot matches newline */
+    dotAll?: boolean;
+    /** `u` — Unicode mode */
+    unicode?: boolean;
+    /** Global (`g`) */
+    global?: boolean;
+    /** Sticky (`y`) */
+    sticky?: boolean;
+};
+type LetterCase = "lower" | "upper" | "both";
+type Pattern = {
+    kind: "Literal";
+    value: string;
+} | {
+    kind: "Any";
+} | {
+    kind: "Digit";
+    unicode: boolean;
+} | {
+    kind: "Word";
+    unicode: boolean;
+} | {
+    kind: "Whitespace";
+    unicode: boolean;
+} | {
+    kind: "Letter";
+    letterCase: LetterCase;
+    unicode: boolean;
+} | {
+    kind: "HexDigit";
+    uppercaseOnly?: boolean;
+} | {
+    kind: "Start";
+} | {
+    kind: "End";
+} | {
+    kind: "WordBoundary";
+} | {
+    kind: "Sequence";
+    children: readonly Pattern[];
+} | {
+    kind: "Choice";
+    children: readonly Pattern[];
+} | {
+    kind: "Repeat";
+    child: Pattern;
+    min: number;
+    max: number;
+    greedy: boolean;
+} | {
+    kind: "Optional";
+    child: Pattern;
+    greedy: boolean;
+} | {
+    kind: "NamedGroup";
+    name: string;
+    child: Pattern;
+} | {
+    kind: "NonCapturing";
+    child: Pattern;
+} | {
+    kind: "RawRegex";
+    source: string;
+    /** Engine flags merged at compile time */
+    flags?: PatternFlags;
+    /** Documentation only — core never trusts user input */
+    trusted?: boolean;
+};
+declare function seq(...children: Pattern[]): Pattern;
+declare function alt(...children: Pattern[]): Pattern;
+declare function repeat(child: Pattern, min: number, max: number, greedy?: boolean): Pattern;
+declare function optional(child: Pattern, greedy?: boolean): Pattern;
+declare function namedGroup(name: string, child: Pattern): Pattern;
+declare function nonCapturing(child: Pattern): Pattern;
+declare function literal(value: string): Pattern;
+declare function optimize(pattern: Pattern): Pattern;
+
+type DigitOpts = {
+    unicode?: boolean;
+};
+type LetterOpts = {
+    case?: LetterCase;
+    unicode?: boolean;
+};
+type Quantified = Pattern & {
+    exactly(n: number): Pattern;
+    atLeast(n: number): Pattern;
+    atMost(n: number): Pattern;
+    between(min: number, max: number): Pattern;
+    oneOrMore(): Pattern;
+    zeroOrMore(): Pattern;
+    maybe(): Pattern;
+};
+declare function anyChar(): Quantified;
+declare function digit(opts?: DigitOpts): Quantified;
+declare function word(opts?: DigitOpts): Quantified;
+declare function whitespace(opts?: DigitOpts): Quantified;
+declare function letter(opts?: LetterOpts): Quantified;
+declare function hexDigit(opts?: {
+    uppercaseOnly?: boolean;
+}): Quantified;
+declare function start(): Pattern;
+declare function end(): Pattern;
+declare function wordBoundary(): Pattern;
+/** Escape hatch: embed raw regex fragment (analyzer flags this). */
+declare function raw(source: string, flags?: PatternFlags): Pattern;
+declare function dash(): Pattern;
+declare function underscore(): Pattern;
+/** Dot literal */
+declare function dot(): Pattern;
+/** Integer sequence (no sign) — digits only */
+declare function integer(): Pattern;
+/** Matches `true` or `false` literally */
+declare function booleanLiteral(): Pattern;
+
+type CompileTarget = "javascript";
+type CompileOptions = {
+    target?: CompileTarget;
+    /** Base flags for the resulting RegExp */
+    flags?: PatternFlags;
+    /** When true, strip capturing groups (for simulation / diagnostics) */
+    nonCapturing?: boolean;
+};
+type CompileResult = {
+    pattern: string;
+    flags: string;
+    warnings: CompileWarning[];
+};
+type CompileWarning = {
+    code: string;
+    message: string;
+};
+declare function compilePattern(root: Pattern, options?: CompileOptions): CompileResult;
+declare function toRegExp(root: Pattern, options?: CompileOptions): RegExp;
+
+type ExplainClause = {
+    id: string;
+    text: string;
+};
+type ExplainResult = {
+    clauses: ExplainClause[];
+    summary: string;
+};
+/** Produce human-readable clauses and a short summary. */
+declare function explainPattern(root: Pattern): ExplainResult;
+
+type DiagnoseOk = {
+    ok: true;
+    match?: string;
+    index?: number;
+    groups?: Record<string, string>;
+};
+type DiagnoseFail = {
+    ok: false;
+    index: number;
+    message: string;
+    expected?: string;
+};
+type DiagnoseResult = DiagnoseOk | DiagnoseFail;
+declare function diagnose(root: Pattern, input: string, options?: CompileOptions): DiagnoseResult;
+
+type AnalysisFinding = {
+    severity: "info" | "warn" | "error";
+    code: string;
+    message: string;
+};
+/** Lightweight static hints (not a full ReDoS solver). */
+declare function analyzePattern(root: Pattern): AnalysisFinding[];
+
+type SerializedPattern = {
+    schemaVersion: typeof PATTERN_SCHEMA_VERSION;
+    pattern: JsonPattern;
+};
+type JsonPattern = {
+    kind: "Literal";
+    value: string;
+} | {
+    kind: "Any";
+} | {
+    kind: "Digit";
+    unicode: boolean;
+} | {
+    kind: "Word";
+    unicode: boolean;
+} | {
+    kind: "Whitespace";
+    unicode: boolean;
+} | {
+    kind: "Letter";
+    letterCase: LetterCase;
+    unicode: boolean;
+} | {
+    kind: "HexDigit";
+    uppercaseOnly?: boolean;
+} | {
+    kind: "Start";
+} | {
+    kind: "End";
+} | {
+    kind: "WordBoundary";
+} | {
+    kind: "Sequence";
+    children: JsonPattern[];
+} | {
+    kind: "Choice";
+    children: JsonPattern[];
+} | {
+    kind: "Repeat";
+    child: JsonPattern;
+    min: number;
+    max: number | "__inf__";
+    greedy: boolean;
+} | {
+    kind: "Optional";
+    child: JsonPattern;
+    greedy: boolean;
+} | {
+    kind: "NamedGroup";
+    name: string;
+    child: JsonPattern;
+} | {
+    kind: "NonCapturing";
+    child: JsonPattern;
+} | {
+    kind: "RawRegex";
+    source: string;
+    flags?: PatternFlags;
+    trusted?: boolean;
+};
+declare function serializePattern(root: Pattern): SerializedPattern;
+declare function deserializePattern(data: unknown): Pattern;
+declare function patternToJsonString(root: Pattern, space?: number): string;
+declare function patternFromJsonString(text: string): Pattern;
+
+/** Compile any AST into an executable pattern wrapper. */
+declare function compile<Captures extends Record<string, string> = Record<string, never>>(ast: Pattern, options?: CompileOptions): CompiledPattern<Captures>;
+declare class CompiledPattern<Captures extends Record<string, string> = Record<string, never>> {
+    readonly ast: Pattern;
+    private readonly compileOpts;
+    constructor(ast: Pattern, compileOpts?: CompileOptions);
+    /** Compiled regex source (body only). */
+    get source(): string;
+    /** Engine flags string, e.g. `"iu"`. */
+    get flags(): string;
+    /** Compiler warnings (for example raw-regex notices). */
+    get warnings(): CompileWarning[];
+    toRegExp(): RegExp;
+    test(input: string): boolean;
+    exec(input: string): RegExpExecArray | null;
+    explain(): ExplainResult;
+    diagnose(input: string): DiagnoseResult;
+    analyze(): AnalysisFinding[];
+    toJSON(): SerializedPattern;
+    toJSONString(space?: number): string;
+}
+type MatchBuilderOptions = {
+    flags?: PatternFlags;
+};
+
+declare class MatchBuilder<Captures extends Record<string, string> = Record<string, never>> {
+    private readonly defaults;
+    private readonly parts;
+    constructor(defaults?: MatchBuilderOptions);
+    /** Anchor start (`^`). */
+    start(): this;
+    /** Anchor end (`$`). */
+    end(): this;
+    boundary(): this;
+    /** Literal text segment (escaped on compile). */
+    text(value: string): this;
+    /** Alias of `text`. */
+    literal(value: string): this;
+    dash(): this;
+    /** Append any composed pattern fragment. */
+    take(fragment: Pattern): this;
+    digit(): this;
+    lettersUpper(): this;
+    lettersLower(): this;
+    named<K extends string>(name: K, inner: Pattern): MatchBuilder<Captures & Record<K, string>>;
+    build(): Pattern;
+    compile(options?: CompileOptions): CompiledPattern<Captures>;
+}
+declare function match(opts?: MatchBuilderOptions): MatchBuilder;
+/** Alias matching the conceptual name from the design doc. */
+declare function regex(opts?: MatchBuilderOptions): MatchBuilder;
+
+type HexColorOpts = {
+    /** Allow `#RGB` shorthand */
+    short?: boolean;
+    /** Allow `#RRGGBBAA` */
+    alpha?: boolean;
+};
+declare const presets: {
+    /** RFC 4122 UUID (case-insensitive hex). Version nibble not enforced here. */
+    uuid(): Pattern;
+    /** Conservative ASCII slug: lowercase letters, digits, single dashes between segments. */
+    slug(): Pattern;
+    hexColor(opts?: HexColorOpts): Pattern;
+};
+
+export { type AnalysisFinding, type CompileOptions, type CompileResult, type CompileWarning, CompiledPattern, type DiagnoseFail, type DiagnoseOk, type DiagnoseResult, type DigitOpts, type ExplainClause, type ExplainResult, type HexColorOpts, type LetterCase, type LetterOpts, MatchBuilder, type MatchBuilderOptions, PATTERN_SCHEMA_VERSION, type Pattern, type PatternFlags, type Quantified, type SerializedPattern, alt, analyzePattern, anyChar, booleanLiteral, compile, compilePattern, dash, deserializePattern, diagnose, digit, dot, end, explainPattern, hexDigit, integer, letter, literal, match, namedGroup, nonCapturing, optimize, optional, patternFromJsonString, patternToJsonString, presets, raw, regex, repeat, seq, serializePattern, start, toRegExp, underscore, whitespace, word, wordBoundary };

package/dist/index.d.ts

@@ -0,0 +1,308 @@
+/** JSON schema version for serialized patterns. */
+declare const PATTERN_SCHEMA_VERSION: 1;
+type PatternFlags = {
+    /** Case-insensitive matching (`i`) */
+    ignoreCase?: boolean;
+    /** `m` — ^ and $ match line boundaries */
+    multiline?: boolean;
+    /** `s` — dot matches newline */
+    dotAll?: boolean;
+    /** `u` — Unicode mode */
+    unicode?: boolean;
+    /** Global (`g`) */
+    global?: boolean;
+    /** Sticky (`y`) */
+    sticky?: boolean;
+};
+type LetterCase = "lower" | "upper" | "both";
+type Pattern = {
+    kind: "Literal";
+    value: string;
+} | {
+    kind: "Any";
+} | {
+    kind: "Digit";
+    unicode: boolean;
+} | {
+    kind: "Word";
+    unicode: boolean;
+} | {
+    kind: "Whitespace";
+    unicode: boolean;
+} | {
+    kind: "Letter";
+    letterCase: LetterCase;
+    unicode: boolean;
+} | {
+    kind: "HexDigit";
+    uppercaseOnly?: boolean;
+} | {
+    kind: "Start";
+} | {
+    kind: "End";
+} | {
+    kind: "WordBoundary";
+} | {
+    kind: "Sequence";
+    children: readonly Pattern[];
+} | {
+    kind: "Choice";
+    children: readonly Pattern[];
+} | {
+    kind: "Repeat";
+    child: Pattern;
+    min: number;
+    max: number;
+    greedy: boolean;
+} | {
+    kind: "Optional";
+    child: Pattern;
+    greedy: boolean;
+} | {
+    kind: "NamedGroup";
+    name: string;
+    child: Pattern;
+} | {
+    kind: "NonCapturing";
+    child: Pattern;
+} | {
+    kind: "RawRegex";
+    source: string;
+    /** Engine flags merged at compile time */
+    flags?: PatternFlags;
+    /** Documentation only — core never trusts user input */
+    trusted?: boolean;
+};
+declare function seq(...children: Pattern[]): Pattern;
+declare function alt(...children: Pattern[]): Pattern;
+declare function repeat(child: Pattern, min: number, max: number, greedy?: boolean): Pattern;
+declare function optional(child: Pattern, greedy?: boolean): Pattern;
+declare function namedGroup(name: string, child: Pattern): Pattern;
+declare function nonCapturing(child: Pattern): Pattern;
+declare function literal(value: string): Pattern;
+declare function optimize(pattern: Pattern): Pattern;
+
+type DigitOpts = {
+    unicode?: boolean;
+};
+type LetterOpts = {
+    case?: LetterCase;
+    unicode?: boolean;
+};
+type Quantified = Pattern & {
+    exactly(n: number): Pattern;
+    atLeast(n: number): Pattern;
+    atMost(n: number): Pattern;
+    between(min: number, max: number): Pattern;
+    oneOrMore(): Pattern;
+    zeroOrMore(): Pattern;
+    maybe(): Pattern;
+};
+declare function anyChar(): Quantified;
+declare function digit(opts?: DigitOpts): Quantified;
+declare function word(opts?: DigitOpts): Quantified;
+declare function whitespace(opts?: DigitOpts): Quantified;
+declare function letter(opts?: LetterOpts): Quantified;
+declare function hexDigit(opts?: {
+    uppercaseOnly?: boolean;
+}): Quantified;
+declare function start(): Pattern;
+declare function end(): Pattern;
+declare function wordBoundary(): Pattern;
+/** Escape hatch: embed raw regex fragment (analyzer flags this). */
+declare function raw(source: string, flags?: PatternFlags): Pattern;
+declare function dash(): Pattern;
+declare function underscore(): Pattern;
+/** Dot literal */
+declare function dot(): Pattern;
+/** Integer sequence (no sign) — digits only */
+declare function integer(): Pattern;
+/** Matches `true` or `false` literally */
+declare function booleanLiteral(): Pattern;
+
+type CompileTarget = "javascript";
+type CompileOptions = {
+    target?: CompileTarget;
+    /** Base flags for the resulting RegExp */
+    flags?: PatternFlags;
+    /** When true, strip capturing groups (for simulation / diagnostics) */
+    nonCapturing?: boolean;
+};
+type CompileResult = {
+    pattern: string;
+    flags: string;
+    warnings: CompileWarning[];
+};
+type CompileWarning = {
+    code: string;
+    message: string;
+};
+declare function compilePattern(root: Pattern, options?: CompileOptions): CompileResult;
+declare function toRegExp(root: Pattern, options?: CompileOptions): RegExp;
+
+type ExplainClause = {
+    id: string;
+    text: string;
+};
+type ExplainResult = {
+    clauses: ExplainClause[];
+    summary: string;
+};
+/** Produce human-readable clauses and a short summary. */
+declare function explainPattern(root: Pattern): ExplainResult;
+
+type DiagnoseOk = {
+    ok: true;
+    match?: string;
+    index?: number;
+    groups?: Record<string, string>;
+};
+type DiagnoseFail = {
+    ok: false;
+    index: number;
+    message: string;
+    expected?: string;
+};
+type DiagnoseResult = DiagnoseOk | DiagnoseFail;
+declare function diagnose(root: Pattern, input: string, options?: CompileOptions): DiagnoseResult;
+
+type AnalysisFinding = {
+    severity: "info" | "warn" | "error";
+    code: string;
+    message: string;
+};
+/** Lightweight static hints (not a full ReDoS solver). */
+declare function analyzePattern(root: Pattern): AnalysisFinding[];
+
+type SerializedPattern = {
+    schemaVersion: typeof PATTERN_SCHEMA_VERSION;
+    pattern: JsonPattern;
+};
+type JsonPattern = {
+    kind: "Literal";
+    value: string;
+} | {
+    kind: "Any";
+} | {
+    kind: "Digit";
+    unicode: boolean;
+} | {
+    kind: "Word";
+    unicode: boolean;
+} | {
+    kind: "Whitespace";
+    unicode: boolean;
+} | {
+    kind: "Letter";
+    letterCase: LetterCase;
+    unicode: boolean;
+} | {
+    kind: "HexDigit";
+    uppercaseOnly?: boolean;
+} | {
+    kind: "Start";
+} | {
+    kind: "End";
+} | {
+    kind: "WordBoundary";
+} | {
+    kind: "Sequence";
+    children: JsonPattern[];
+} | {
+    kind: "Choice";
+    children: JsonPattern[];
+} | {
+    kind: "Repeat";
+    child: JsonPattern;
+    min: number;
+    max: number | "__inf__";
+    greedy: boolean;
+} | {
+    kind: "Optional";
+    child: JsonPattern;
+    greedy: boolean;
+} | {
+    kind: "NamedGroup";
+    name: string;
+    child: JsonPattern;
+} | {
+    kind: "NonCapturing";
+    child: JsonPattern;
+} | {
+    kind: "RawRegex";
+    source: string;
+    flags?: PatternFlags;
+    trusted?: boolean;
+};
+declare function serializePattern(root: Pattern): SerializedPattern;
+declare function deserializePattern(data: unknown): Pattern;
+declare function patternToJsonString(root: Pattern, space?: number): string;
+declare function patternFromJsonString(text: string): Pattern;
+
+/** Compile any AST into an executable pattern wrapper. */
+declare function compile<Captures extends Record<string, string> = Record<string, never>>(ast: Pattern, options?: CompileOptions): CompiledPattern<Captures>;
+declare class CompiledPattern<Captures extends Record<string, string> = Record<string, never>> {
+    readonly ast: Pattern;
+    private readonly compileOpts;
+    constructor(ast: Pattern, compileOpts?: CompileOptions);
+    /** Compiled regex source (body only). */
+    get source(): string;
+    /** Engine flags string, e.g. `"iu"`. */
+    get flags(): string;
+    /** Compiler warnings (for example raw-regex notices). */
+    get warnings(): CompileWarning[];
+    toRegExp(): RegExp;
+    test(input: string): boolean;
+    exec(input: string): RegExpExecArray | null;
+    explain(): ExplainResult;
+    diagnose(input: string): DiagnoseResult;
+    analyze(): AnalysisFinding[];
+    toJSON(): SerializedPattern;
+    toJSONString(space?: number): string;
+}
+type MatchBuilderOptions = {
+    flags?: PatternFlags;
+};
+
+declare class MatchBuilder<Captures extends Record<string, string> = Record<string, never>> {
+    private readonly defaults;
+    private readonly parts;
+    constructor(defaults?: MatchBuilderOptions);
+    /** Anchor start (`^`). */
+    start(): this;
+    /** Anchor end (`$`). */
+    end(): this;
+    boundary(): this;
+    /** Literal text segment (escaped on compile). */
+    text(value: string): this;
+    /** Alias of `text`. */
+    literal(value: string): this;
+    dash(): this;
+    /** Append any composed pattern fragment. */
+    take(fragment: Pattern): this;
+    digit(): this;
+    lettersUpper(): this;
+    lettersLower(): this;
+    named<K extends string>(name: K, inner: Pattern): MatchBuilder<Captures & Record<K, string>>;
+    build(): Pattern;
+    compile(options?: CompileOptions): CompiledPattern<Captures>;
+}
+declare function match(opts?: MatchBuilderOptions): MatchBuilder;
+/** Alias matching the conceptual name from the design doc. */
+declare function regex(opts?: MatchBuilderOptions): MatchBuilder;
+
+type HexColorOpts = {
+    /** Allow `#RGB` shorthand */
+    short?: boolean;
+    /** Allow `#RRGGBBAA` */
+    alpha?: boolean;
+};
+declare const presets: {
+    /** RFC 4122 UUID (case-insensitive hex). Version nibble not enforced here. */
+    uuid(): Pattern;
+    /** Conservative ASCII slug: lowercase letters, digits, single dashes between segments. */
+    slug(): Pattern;
+    hexColor(opts?: HexColorOpts): Pattern;
+};
+
+export { type AnalysisFinding, type CompileOptions, type CompileResult, type CompileWarning, CompiledPattern, type DiagnoseFail, type DiagnoseOk, type DiagnoseResult, type DigitOpts, type ExplainClause, type ExplainResult, type HexColorOpts, type LetterCase, type LetterOpts, MatchBuilder, type MatchBuilderOptions, PATTERN_SCHEMA_VERSION, type Pattern, type PatternFlags, type Quantified, type SerializedPattern, alt, analyzePattern, anyChar, booleanLiteral, compile, compilePattern, dash, deserializePattern, diagnose, digit, dot, end, explainPattern, hexDigit, integer, letter, literal, match, namedGroup, nonCapturing, optimize, optional, patternFromJsonString, patternToJsonString, presets, raw, regex, repeat, seq, serializePattern, start, toRegExp, underscore, whitespace, word, wordBoundary };