js-dev-tool 1.1.3 → 1.2.0

package/literate-regex/dist/index.d.ts

@@ -1,385 +0,0 @@
-/*!
-// Copyright jeffy-g 2025
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//      http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-*/
-/**
- * @file literate-regex/index.d.ts
- * @desc It is recommended to add `"skipLibCheck": true` to your tsconfig.
- * @todo publish as "literate-regex"
- * @todo implement runtime utility function for `/<source>/<flags>`
- */
-/*!
-// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-//                                   Basics
-// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-*/
-export type Brand<Tag extends string> = {
-  [k in Tag]: true;
-};
-export type TypedRegExpBrand = Brand<"__TypedRegExp">;
-export type TypedRegExp<P extends string, F extends string = ""> = RegExp & {
-  readonly source: P;
-  readonly flags: F;
-} & TypedRegExpBrand;
-/**
- * Extracts the literal type from the source property of a RegExp.
- * @template R - A RegExp type.
- */
-export type RegExpSource<R extends RegExp> = R extends RegExp & { readonly source: infer T } ? T : never;
-export declare function createRegExp<
-  const P extends string,
-  const F extends string = ""
->(pattern: P, flags?: F): TypedRegExp<P, F>;
-type IsEmptyRecord<T> =
-  [T] extends [undefined] ? true :
-  [keyof T] extends [never] ? true : false;
-/*!
-// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-//                            Named Capture Groups
-// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-*/
-type FirstChar<S extends string> = S extends `${infer F}${infer _}` ? F : never;
-/**
- * Recursively extracts parts that match the format (?<GroupName>...) from a string pattern,
- * without considering nesting, and unions them.
- * @template S - A string pattern.
- */
-export type ExtractGroupNames<S extends unknown> =
-  S extends `${infer _Before}(?<${infer Rest}`
-    ? FirstChar<Rest> extends "=" | "!"
-      ? ExtractGroupNames<Rest>
-      : Rest extends `${infer GroupName}>${infer After}`
-        ? GroupName extends ""
-          ? "ExtractGroupNames: regex pattern error!"
-          : GroupName | ExtractGroupNames<After>
-        : never
-    : never;
-/**
- * Creates an object type with keys as the extracted group names and values as strings.
- * If no groups are found, it results in an empty object.
- * @template R - A RegExp type.
- * @date 2025/12/24 14:46:30 - It may be possible to extract the group name accurately (?)
- */
-export type RegExpNamedGroups<R extends RegExp> =
-  R extends RegExp & { readonly source: infer S extends string }
-    ? ExtractGroupNames<S> extends infer K
-      ? [K] extends [never]
-        ? undefined
-        : { [P in K & string]: string | undefined }
-      : undefined
-    : undefined;
-/*!
-// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-//                               Capture Groups
-// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-*/
-/**
- * Preprocesses escape sequences in a string pattern by replacing escaped backslashes and characters.
- * 
- * + NOTE: This type is used to preprocess the pattern string before counting capture groups.
- * 
- * @template S - A string pattern.
- * @template Result - The resulting string after preprocessing. 
- * @internal
- */
-export type __PreprocessEscapes<S extends string, Result extends string = ""> =
-  S extends `\\\\${infer Rest}`
-    ? __PreprocessEscapes<Rest, `${Result}__`>
-    : S extends `\\${infer EscapedChar}${infer Rest}`
-      ? __PreprocessEscapes<Rest, `${Result}_!`>
-      : S extends `${infer Char}${infer Rest}`
-        ? __PreprocessEscapes<Rest, `${Result}${Char}`>
-        : Result;
-/**
- * Counts the exact number of capture groups in a string pattern.
- * @template S - A string pattern.
- * @template Counter - An array used to count the capture groups.
- */
-export type CountCaptureGroups<
-  S extends string,
-  Counter extends unknown[] = []
-> =
-  __PreprocessEscapes<S> extends `${infer _Before}(${infer Rest}`
-    ? Rest extends `${"?:" | "?=" | "?!" | "?<=" | "?<!"}${infer After}`
-      ? CountCaptureGroups<After, Counter>
-      : CountCaptureGroups<Rest, [...Counter, unknown]>
-    : Counter["length"];
-/**
- * Represents a fixed version of RegExpExecArray that includes the matched string,
- * captures, and optionally named groups.
- * @template R - A RegExp type.
- * @template S - The source string of the RegExp.
- * @template GroupCount - The number of capture groups.
- */
-export type RegExpExecArrayFixed<
-  R extends RegExp,
-  S extends RegExpSource<R> = RegExpSource<R>,
-  GroupCount extends number = CountCaptureGroups<S>,
-  NamedGroups = RegExpNamedGroups<R>
-> = [match: string, ...BuildCaptureTuple<GroupCount, string | undefined>] & {
-  groups: IsEmptyRecord<NamedGroups> extends true ? undefined : NamedGroups;
-  index: number;
-  input: string;
-};
-type CaptureOptTuple<N extends number, T = string | undefined> =
-  N extends 0 ? [] :
-  N extends 1 ? [$1: T] :
-  N extends 2 ? [$1: T, $2: T] :
-  N extends 3 ? [$1: T, $2: T, $3: T] :
-  N extends 4 ? [$1: T, $2: T, $3: T, $4: T] :
-  N extends 5 ? [$1: T, $2: T, $3: T, $4: T, $5: T] :
-  N extends 6 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T] :
-  N extends 7 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T] :
-  N extends 8 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T] :
-  N extends 9 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T] :
-  N extends 10 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T] :
-  N extends 11 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T, $11: T] :
-  N extends 12 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T, $11: T, $12: T] :
-  N extends 13 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T, $11: T, $12: T, $13: T] :
-  N extends 14 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T, $11: T, $12: T, $13: T, $14: T] :
-  N extends 15 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T, $11: T, $12: T, $13: T, $14: T, $15: T] :
-  N extends 16 ? [$1: T, $2: T, $3: T, $4: T, $5: T, $6: T, $7: T, $8: T, $9: T, $10: T, $11: T, $12: T, $13: T, $14: T, $15: T, $16: T] :
-  BuildCaptureTuple<N, T>;
-export type RegExpExecArrayFixedPretty<
-  R extends RegExp,
-  S extends RegExpSource<R> = RegExpSource<R>,
-  GroupCount extends number = CountCaptureGroups<S>,
-  NamedGroups = RegExpNamedGroups<R>
-> = [match: string, ...CaptureOptTuple<GroupCount>] & {
-  groups: IsEmptyRecord<NamedGroups> extends true ? undefined : NamedGroups;
-  index: number;
-  input: string;
-};
-export type TupleOf<
-  Count extends number, ArrayType,
-  Result extends ArrayType[] = []
-> = Result["length"] extends Count
-  ? Result
-  : TupleOf<Count, ArrayType, [...Result, ArrayType]>;
-/**
- * Builds a tuple type whose length equals the number of capture groups.
- * @template Count - Number of capture groups.
- * @template Result - Accumulator (internal).
- */
-export type BuildCaptureTuple<
-  Count extends number, ArrayType = string,
-> = TupleOf<Count, ArrayType>;
-/*!
-// ============================================================================
-//                          Helper Types for Replacer
-// ============================================================================
-*/
-/**
- * Creates the parameter types for String.replace callback function.
- * 
- * @example
- * type Params = ReplaceCallbackParams<typeof myRegex>;
- * // [match: string, ...captures: string[], offset: number, string: string, groups?: {...}]
- */
-export type ReplaceCallbackParams<
-  R extends RegExp,
-  S extends RegExpSource<R> = RegExpSource<R>,
-  GroupCount extends number = CountCaptureGroups<S>,
-  NamedGroups = RegExpNamedGroups<R>
-> = IsEmptyRecord<NamedGroups> extends true ? [
-  match: string,
-  ...captures: CaptureOptTuple<GroupCount>,
-  offset: number,
-  input: string,
-] : [
-  match: string,
-  ...captures: CaptureOptTuple<GroupCount>,
-  offset: number,
-  input: string,
-  groups: NamedGroups
-];
-export type ReplacerFunctionSignature<R extends unknown> =
-  R extends (
-    RegExp & { readonly source: infer T }
-  ) ? R extends TypedRegExpBrand
-    ? (...args: ReplaceCallbackParams<R/* , T */>) => string
-    : (match: string, ...rest: any[]) => string
-  : string;
-/*! [2025/12/31 13:01:03]
- * ## Support PCRE-style regex source (type-level)
- *
- * @remarks
- * This module provides **type-level normalization** for "PCRE-ish" regex sources:
- * you can write a readable multi-line regex with indentation and `# ...` comments,
- * then derive a compact JavaScript `RegExp` source at compile time.
- *
- * Why type-level? Because it lets us:
- * - keep the regex readable in source code (with comments and formatting)
- * - ensure the normalized output is stable and verifiable (via type assertions)
- *
- * ## Supported rules
- * - `#` starts a comment and consumes the rest of the **current line**
- * - `\#` escapes `#` as a literal (comment is NOT started) and normalizes to `#`
- * - whitespace characters are removed during normalization
- * - newlines are normalized: `\r\n` and `\r` become `\n`
- *
- * ## Design note (ts(2589) survival)
- * Naively scanning the entire string character-by-character (multiple passes)
- * can hit TypeScript's instantiation depth limit (`ts(2589)`).
- * This implementation is **line-oriented**:
- * it strips each line, then concatenates results.
- * That tends to scale much better for long, commented regex sources.
- *
- * ## Non-goals (for now)
- * This is not a full PCRE parser. It intentionally focuses on comment + whitespace
- * normalization for readability and DX.
- */
-/**
- * Union of whitespace characters used by this library.
- * 
- * + A set aligned with ECMAScript RegExp **`\s`** (WhiteSpace ∪ LineTerminator)
- * 
- * The union is used to normalize "PCRE-style" regex sources at the type level.
- */
-export type TWhiteSpace =
-  | "\x09"
-  | "\x0A"
-  | "\x0B"
-  | "\x0C"
-  | "\x0D"
-  | "\x20"
-  | "\u00A0"
-  | "\u1680"
-  | "\u2000"
-  | "\u2001"
-  | "\u2002"
-  | "\u2003"
-  | "\u2004"
-  | "\u2005"
-  | "\u2006"
-  | "\u2007"
-  | "\u2008"
-  | "\u2009"
-  | "\u200A"
-  | "\u2028" | "\u2029"
-  | "\u202F" | "\u205F" | "\u3000"
-  | "\uFEFF";
-/**
- * Normalize newline sequences for line-based parsing.
- * 
- * + Align **`\r\n`** and **`\r`** to **`\n`** (makes splitting easier)
- *
- * @template S - Input string literal.
- * @returns A new string literal with `\r\n` and `\r` normalized to `\n`.
- *
- * @example
- * type X = NormalizeNewlines<"a\r\nb\rc\n">; // "a\nb\nc\n"
- */
-type NormalizeNewlines<S extends string> =
-  S extends `${infer A}\r\n${infer B}` ? NormalizeNewlines<`${A}\n${B}`> :
-  S extends `${infer A}\r${infer B}` ? NormalizeNewlines<`${A}\n${B}`> :
-  S;
-/**
- * Strip and normalize a single line of a PCRE-style regex source.
- *
- * @remarks
- * Rules:
- * - `\#` is treated as a literal `#` (the backslash is dropped)
- * - an unescaped `#` starts a line comment and truncates the rest
- * - all whitespace characters are removed
- * - other escapes like `\s`, `\w`, `\/`, `\*` are preserved as-is
- *
- * @template S - One line of source (no `\n`).
- * @template Acc - Accumulator for the normalized output.
- *
- * @example
- * type A = StripLine<"  \\#\\w+   # comment  ">; // "#\\w+"
- * type B = StripLine<"  abc  # comment">;        // "abc"
- *
- * @internal
- *
- * @todo
- * - Handle `\\#` (a literal backslash + literal #) more strictly.
- * - Do not treat `#` as a comment starter inside character classes (`[...]`).
- */
-type StripLine<S extends string, Acc extends string = ""> =
-  S extends `\\#${infer Rest}`
-    ? StripLine<Rest, `${Acc}#`>
-    : S extends `\\${infer C}${infer Rest}`
-      ? StripLine<Rest, `${Acc}\\${C}`>
-      : S extends `#${string}`
-        ? Acc
-        : S extends `${infer C}${infer Rest}`
-          ? C extends TWhiteSpace
-            ? StripLine<Rest, Acc>
-            : StripLine<Rest, `${Acc}${C}`>
-          : Acc;
-/**
- * Convert a multi-line PCRE-style regex source into a compact JS `RegExp.source`.
- *
- * @remarks
- * This type:
- * 1) normalizes newlines, 2) splits by line, 3) applies {@link StripLine},
- * then 4) concatenates the results.
- *
- * @template Input - A `const` string literal of the PCRE-ish source.
- * @template Acc - Accumulator for the result.
- * @template S - Internal normalized newline buffer (do not pass manually).
- *
- * @example
- * const RE_SOURCE = `
- * ^              # start
- * (?:\\#\\w+)     # keep literal "#"
- * ` as const;
- *
- * type Src = PCREStyleToJsRegExpSource<typeof RE_SOURCE>;
- * // "^(:?##\\w+)" ... (depending on your actual input)
- */
-export type PCREStyleToJsRegExpSource<
-  Input extends string,
-  Acc extends string = "",
-  S extends string = NormalizeNewlines<Input>,
-> =
-  S extends `${infer Line}\n${infer Rest}`
-    ? PCREStyleToJsRegExpSource<Input, `${Acc}${StripLine<Line>}`, Rest>
-    : `${Acc}${StripLine<S>}`;
-/*!
-// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-//                    Parse PCRE Style Regex Literal
-// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-*/
-type AllowedRegExpFlag = "d" | "g" | "i" | "m" | "s" | "u" | "v" | "y";
-type StripFlagsFromEnd<S extends string, Acc extends string = ""> =
-  S extends `${infer Rest}y` ? StripFlagsFromEnd<Rest, `y${Acc}`> :
-  S extends `${infer Rest}v` ? StripFlagsFromEnd<Rest, `v${Acc}`> :
-  S extends `${infer Rest}u` ? StripFlagsFromEnd<Rest, `u${Acc}`> :
-  S extends `${infer Rest}s` ? StripFlagsFromEnd<Rest, `s${Acc}`> :
-  S extends `${infer Rest}m` ? StripFlagsFromEnd<Rest, `m${Acc}`> :
-  S extends `${infer Rest}i` ? StripFlagsFromEnd<Rest, `i${Acc}`> :
-  S extends `${infer Rest}g` ? StripFlagsFromEnd<Rest, `g${Acc}`> :
-  S extends `${infer Rest}d` ? StripFlagsFromEnd<Rest, `d${Acc}`> :
-  { body: S; flags: Acc };
-export type RegExpLiteralParts<L extends string> =
-  StripFlagsFromEnd<L> extends { body: infer B extends string; flags: infer F extends string }
-    ? B extends `/${infer AfterStart}`
-      ? AfterStart extends `${infer Pattern}/`
-        ? { pattern: Pattern; flags: F }
-        : never
-      : never
-    : never;
-export type PCREStyleRegExpParts<S extends string> = RegExpLiteralParts<PCREStyleToJsRegExpSource<S>>;
-export type PCREStyleRegExpPattern<S extends string> = PCREStyleRegExpParts<S>["pattern"];
-export type PCREStyleRegExpFlags<S extends string> = PCREStyleRegExpParts<S>["flags"];
-export declare const normalizePCREStyleSource: <S extends string>(src: S) => PCREStyleToJsRegExpSource<S>;
-export declare const extractJsRegexPartsFromPCREStyleRegExpLiteral: <const S extends string>(src: S) => PCREStyleRegExpParts<S>;
-export declare const compilePCREStyleRegExpLiteral: <const S extends string>(src: S) => TypedRegExp<
-  PCREStyleRegExpPattern<S>,
-  PCREStyleRegExpFlags<S>
->;
-export as namespace XRegex;

package/literate-regex/package.json

@@ -1,34 +0,0 @@
-{
-  "name": "literate-regex",
-  "version": "0.1.0",
-  "description": "Write readable (literate) regex sources with # comments, then normalize them to JS RegExp.source at the type level.",
-  "license": "Apache-2.0",
-  "sideEffects": false,
-  "main": "./dist/cjs/index.js",
-  "module": "./dist/esm/index.mjs",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/esm/index.mjs",
-      "require": "./dist/cjs/index.js"
-    },
-    "./global": {
-      "types": "./dist/global.d.ts"
-    }
-  },
-  "files": [
-    "README.md",
-    "LICENSE",
-    "dist"
-  ],
-  "keywords": [
-    "regex",
-    "regexp",
-    "literate",
-    "types",
-    "typescript",
-    "pcre",
-    "jsdoc"
-  ]
-}