xulbux 1.9.5__cp311-cp311-macosx_11_0_arm64.whl

xulbux/__init__.py

@@ -0,0 +1,46 @@
+__package_name__ = "xulbux"
+__version__ = "1.9.5"
+__description__ = "A Python library to simplify common programming tasks."
+__status__ = "Production/Stable"
+
+__url__ = "https://github.com/XulbuX/PythonLibraryXulbuX"
+
+__author__ = "XulbuX"
+__email__ = "xulbux.real@gmail.com"
+__license__ = "MIT"
+__copyright__ = "Copyright (c) 2024 XulbuX"
+
+__requires_python__ = ">=3.10.0"
+__dependencies__ = [
+    "keyboard>=0.13.5",
+    "prompt_toolkit>=3.0.41",
+    "regex>=2023.10.3",
+]
+
+__all__ = [
+    "Code",
+    "Color",
+    "Console",
+    "Data",
+    "EnvPath",
+    "File",
+    "FileSys",
+    "FormatCodes",
+    "Json",
+    "Regex",
+    "String",
+    "System",
+]
+
+from .code import Code
+from .color import Color
+from .console import Console
+from .data import Data
+from .env_path import EnvPath
+from .file import File
+from .file_sys import FileSys
+from .format_codes import FormatCodes
+from .json import Json
+from .regex import Regex
+from .string import String
+from .system import System

xulbux/base/consts.py

@@ -0,0 +1,172 @@
+"""
+This module contains constant values used throughout the library.
+"""
+
+from .types import FormattableString, AllTextChars
+
+from typing import Final
+
+
+class COLOR:
+    """Hexadecimal color presets."""
+
+    WHITE: Final = "#F1F2FF"
+    LIGHT_GRAY: Final = "#B6B7C0"
+    GRAY: Final = "#7B7C8D"
+    DARK_GRAY: Final = "#67686C"
+    BLACK: Final = "#202125"
+    RED: Final = "#FF606A"
+    CORAL: Final = "#FF7069"
+    ORANGE: Final = "#FF876A"
+    TANGERINE: Final = "#FF9962"
+    GOLD: Final = "#FFAF60"
+    YELLOW: Final = "#FFD260"
+    LIME: Final = "#C9F16E"
+    GREEN: Final = "#7EE787"
+    NEON_GREEN: Final = "#4CFF85"
+    TEAL: Final = "#50EAAF"
+    CYAN: Final = "#3EDEE6"
+    ICE: Final = "#77DBEF"
+    LIGHT_BLUE: Final = "#60AAFF"
+    BLUE: Final = "#8085FF"
+    LAVENDER: Final = "#9B7DFF"
+    PURPLE: Final = "#AD68FF"
+    MAGENTA: Final = "#C860FF"
+    PINK: Final = "#F162EF"
+    ROSE: Final = "#FF609F"
+
+
+class CHARS:
+    """Character set constants for text validation and filtering."""
+
+    ALL: Final = AllTextChars()
+    """Sentinel value indicating all characters are allowed."""
+
+    DIGITS: Final = "0123456789"
+    """Numeric digits: `0`-`9`"""
+    FLOAT_DIGITS: Final = "." + DIGITS
+    """Numeric digits with decimal point: `0`-`9` and `.`"""
+    HEX_DIGITS: Final = "#" + DIGITS + "abcdefABCDEF"
+    """Hexadecimal digits: `0`-`9`, `a`-`f`, `A`-`F`, and `#`"""
+
+    LOWERCASE: Final = "abcdefghijklmnopqrstuvwxyz"
+    """Lowercase ASCII letters: `a`-`z`"""
+    LOWERCASE_EXTENDED: Final = LOWERCASE + "äëïöüÿàèìòùáéíóúýâêîôûãñõåæç"
+    """Lowercase ASCII letters with diacritic marks."""
+    UPPERCASE: Final = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    """Uppercase ASCII letters: `A`-`Z`"""
+    UPPERCASE_EXTENDED: Final = UPPERCASE + "ÄËÏÖÜÀÈÌÒÙÁÉÍÓÚÝÂÊÎÔÛÃÑÕÅÆÇß"
+    """Uppercase ASCII letters with diacritic marks."""
+
+    LETTERS: Final = LOWERCASE + UPPERCASE
+    """All ASCII letters: `a`-`z` and `A`-`Z`"""
+    LETTERS_EXTENDED: Final = LOWERCASE_EXTENDED + UPPERCASE_EXTENDED
+    """All ASCII letters with diacritic marks."""
+
+    SPECIAL_ASCII: Final = " !\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
+    """Standard ASCII special characters and symbols."""
+    SPECIAL_ASCII_EXTENDED: Final = SPECIAL_ASCII + "ø£Ø׃ªº¿®¬½¼¡«»░▒▓│┤©╣║╗╝¢¥┐└┴┬├─┼╚╔╩╦╠═╬¤ðÐı┘┌█▄¦▀µþÞ¯´≡­±‗¾¶§÷¸°¨·¹³²■ "
+    """Standard and extended ASCII special characters."""
+    STANDARD_ASCII: Final = DIGITS + LETTERS + SPECIAL_ASCII
+    """All standard ASCII characters (letters, digits, and symbols)."""
+    FULL_ASCII: Final = DIGITS + LETTERS_EXTENDED + SPECIAL_ASCII_EXTENDED
+    """Complete ASCII character set including extended characters."""
+
+
+class ANSI:
+    """Constants and utilities for ANSI escape code sequences."""
+
+    CHAR_ESCAPED: Final = r"\x1b"
+    """Printable ANSI escape character."""
+    CHAR: Final = "\x1b"
+    """ANSI escape character."""
+    START: Final = "["
+    """Start of an ANSI escape sequence."""
+    SEP: Final = ";"
+    """Separator between ANSI escape sequence parts."""
+    END: Final = "m"
+    """End of an ANSI escape sequence."""
+
+    @classmethod
+    def seq(cls, placeholders: int = 1) -> FormattableString:
+        """Generates an ANSI escape sequence with the specified number of placeholders."""
+        return cls.CHAR + cls.START + cls.SEP.join(["{}" for _ in range(placeholders)]) + cls.END
+
+    SEQ_COLOR: Final[FormattableString] = CHAR + START + "38" + SEP + "2" + SEP + "{}" + SEP + "{}" + SEP + "{}" + END
+    """ANSI escape sequence with three placeholders for setting the RGB text color."""
+    SEQ_BG_COLOR: Final[FormattableString] = CHAR + START + "48" + SEP + "2" + SEP + "{}" + SEP + "{}" + SEP + "{}" + END
+    """ANSI escape sequence with three placeholders for setting the RGB background color."""
+
+    COLOR_MAP: Final[tuple[str, ...]] = (
+        ########### DEFAULT CONSOLE COLOR NAMES ############
+        "black",
+        "red",
+        "green",
+        "yellow",
+        "blue",
+        "magenta",
+        "cyan",
+        "white",
+    )
+    """The standard terminal color names."""
+
+    CODES_MAP: Final[dict[str | tuple[str, ...], int]] = {
+        ################# SPECIFIC RESETS ##################
+        "_": 0,
+        ("_bold", "_b"): 22,
+        ("_dim", "_d"): 22,
+        ("_italic", "_i"): 23,
+        ("_underline", "_u"): 24,
+        ("_double-underline", "_du"): 24,
+        ("_inverse", "_invert", "_in"): 27,
+        ("_hidden", "_hide", "_h"): 28,
+        ("_strikethrough", "_s"): 29,
+        ("_color", "_c"): 39,
+        ("_background", "_bg"): 49,
+        ################### TEXT STYLES ####################
+        ("bold", "b"): 1,
+        ("dim", "d"): 2,
+        ("italic", "i"): 3,
+        ("underline", "u"): 4,
+        ("inverse", "invert", "in"): 7,
+        ("hidden", "hide", "h"): 8,
+        ("strikethrough", "s"): 9,
+        ("double-underline", "du"): 21,
+        ################## DEFAULT COLORS ##################
+        "black": 30,
+        "red": 31,
+        "green": 32,
+        "yellow": 33,
+        "blue": 34,
+        "magenta": 35,
+        "cyan": 36,
+        "white": 37,
+        ############## BRIGHT DEFAULT COLORS ###############
+        "br:black": 90,
+        "br:red": 91,
+        "br:green": 92,
+        "br:yellow": 93,
+        "br:blue": 94,
+        "br:magenta": 95,
+        "br:cyan": 96,
+        "br:white": 97,
+        ############ DEFAULT BACKGROUND COLORS #############
+        "bg:black": 40,
+        "bg:red": 41,
+        "bg:green": 42,
+        "bg:yellow": 43,
+        "bg:blue": 44,
+        "bg:magenta": 45,
+        "bg:cyan": 46,
+        "bg:white": 47,
+        ######### BRIGHT DEFAULT BACKGROUND COLORS #########
+        "bg:br:black": 100,
+        "bg:br:red": 101,
+        "bg:br:green": 102,
+        "bg:br:yellow": 103,
+        "bg:br:blue": 104,
+        "bg:br:magenta": 105,
+        "bg:br:cyan": 106,
+        "bg:br:white": 107,
+    }
+    """Dictionary mapping format keys to their corresponding ANSI code numbers."""

xulbux/base/decorators.py

@@ -0,0 +1,28 @@
+"""
+This module contains custom decorators used throughout the library.
+"""
+
+from typing import Callable, TypeVar, Any
+
+
+T = TypeVar("T")
+
+
+def _noop_decorator(obj: T) -> T:
+    """No-op decorator that returns the object unchanged."""
+    return obj
+
+
+def mypyc_attr(**kwargs: Any) -> Callable[[T], T]:
+    """A custom decorator that wraps `mypy_extensions.mypyc_attr` when available,<br>
+    or acts as a no-op decorator when `mypy_extensions` is not installed.\n
+    This allows the use of `mypyc` compilation hints for compiling without making
+    `mypy_extensions` a required dependency.\n
+    -----------------------------------------------------------------------------------------
+    - `**kwargs` -⠀keyword arguments to pass to `mypy_extensions.mypyc_attr` if available"""
+    try:
+        from mypy_extensions import mypyc_attr as _mypyc_attr
+        return _mypyc_attr(**kwargs)
+    except ImportError:
+        # IF 'mypy_extensions' IS NOT INSTALLED, JUST RETURN A NO-OP DECORATOR
+        return _noop_decorator

xulbux/base/exceptions.py

@@ -0,0 +1,23 @@
+"""
+This module contains all custom exception classes used throughout the library.
+"""
+
+from .decorators import mypyc_attr
+
+#
+################################################## FILE ##################################################
+
+
+@mypyc_attr(native_class=False)
+class SameContentFileExistsError(FileExistsError):
+    """Raised when attempting to create a file that already exists with identical content."""
+    ...
+
+
+################################################## PATH ##################################################
+
+
+@mypyc_attr(native_class=False)
+class PathNotFoundError(FileNotFoundError):
+    """Raised when a file system path does not exist or cannot be accessed."""
+    ...

xulbux/base/types.py

@@ -0,0 +1,118 @@
+"""
+This module contains all custom type definitions used throughout the library.
+"""
+
+from typing import TYPE_CHECKING, Annotated, TypeAlias, TypedDict, Optional, Protocol, Literal, Union, Any
+from pathlib import Path
+
+# PREVENT CIRCULAR IMPORTS
+if TYPE_CHECKING:
+    from ..color import rgba, hsla, hexa
+
+#
+################################################## Annotated ##################################################
+
+Int_0_100 = Annotated[int, "Integer constrained to the range [0, 100] inclusive."]
+"""Integer constrained to the range [0, 100] inclusive."""
+Int_0_255 = Annotated[int, "Integer constrained to the range [0, 255] inclusive."]
+"""Integer constrained to the range [0, 255] inclusive."""
+Int_0_360 = Annotated[int, "Integer constrained to the range [0, 360] inclusive."]
+"""Integer constrained to the range [0, 360] inclusive."""
+Float_0_1 = Annotated[float, "Float constrained to the range [0.0, 1.0] inclusive."]
+"""Float constrained to the range [0.0, 1.0] inclusive."""
+
+FormattableString = Annotated[str, "String made to be formatted with the `.format()` method."]
+"""String made to be formatted with the `.format()` method."""
+
+#
+################################################## TypeAlias ##################################################
+
+PathsList: TypeAlias = Union[list[Path], list[str], list[Path | str]]
+"""Union of all supported list types for a list of paths."""
+
+DataStructure: TypeAlias = Union[list, tuple, set, frozenset, dict]
+"""Union of supported data structures used in the `data` module."""
+DataStructureTypes = (list, tuple, set, frozenset, dict)
+"""Tuple of supported data structures used in the `data` module."""
+
+IndexIterable: TypeAlias = Union[list, tuple, set, frozenset]
+"""Union of all iterable types that support indexing operations."""
+IndexIterableTypes = (list, tuple, set, frozenset)
+"""Tuple of all iterable types that support indexing operations."""
+
+Rgba: TypeAlias = Union[
+    tuple[Int_0_255, Int_0_255, Int_0_255],
+    tuple[Int_0_255, Int_0_255, Int_0_255, Float_0_1],
+    list[Int_0_255],
+    list[Union[Int_0_255, Float_0_1]],
+    dict[str, Union[int, float]],
+    "rgba",
+    str,
+]
+"""Matches all supported RGBA color value formats."""
+Hsla: TypeAlias = Union[
+    tuple[Int_0_360, Int_0_100, Int_0_100],
+    tuple[Int_0_360, Int_0_100, Int_0_100, Float_0_1],
+    list[Union[Int_0_360, Int_0_100]],
+    list[Union[Int_0_360, Int_0_100, Float_0_1]],
+    dict[str, Union[int, float]],
+    "hsla",
+    str,
+]
+"""Matches all supported HSLA color value formats."""
+Hexa: TypeAlias = Union[str, int, "hexa"]
+"""Matches all supported hexadecimal color value formats."""
+
+AnyRgba: TypeAlias = Any
+"""Generic type alias for RGBA color values in any supported format (type checking disabled)."""
+AnyHsla: TypeAlias = Any
+"""Generic type alias for HSLA color values in any supported format (type checking disabled)."""
+AnyHexa: TypeAlias = Any
+"""Generic type alias for hexadecimal color values in any supported format (type checking disabled)."""
+
+ArgParseConfig: TypeAlias = Union[set[str], "ArgConfigWithDefault", Literal["before", "after"]]
+"""Matches the command-line-parsing configuration of a single argument."""
+ArgParseConfigs: TypeAlias = dict[str, ArgParseConfig]
+"""Matches the command-line-parsing configurations of multiple arguments, packed in a dictionary."""
+
+#
+################################################## Sentinel ##################################################
+
+
+class AllTextChars:
+    """Sentinel class indicating all characters are allowed."""
+    ...
+
+
+################################################## TypedDict ##################################################
+
+
+class ArgConfigWithDefault(TypedDict):
+    """Configuration schema for a flagged command-line argument that has a specified default value."""
+    flags: set[str]
+    default: str
+
+
+class ArgData(TypedDict):
+    """Schema for the resulting data of parsing a single command-line argument."""
+    exists: bool
+    is_pos: bool
+    values: list[str]
+    flag: Optional[str]
+
+
+class MissingLibsMsgs(TypedDict):
+    """Configuration schema for custom messages in `System.check_libs()` when checking library dependencies."""
+    found_missing: str
+    should_install: str
+
+
+################################################## Protocol ##################################################
+
+
+class ProgressUpdater(Protocol):
+    """Protocol for a progress updater function used in console progress bars."""
+
+    def __call__(self, current: Optional[int] = None, label: Optional[str] = None) -> None:
+        """Update the current progress value and/or label."""
+        ...

xulbux/cli/help.py

@@ -0,0 +1,77 @@
+from .. import __version__
+from ..format_codes import FormatCodes
+from ..console import Console
+
+from urllib.error import HTTPError
+from typing import Optional
+import urllib.request as _request
+import json as _json
+
+
+def get_latest_version() -> Optional[str]:
+    with _request.urlopen(URL) as response:
+        if response.status == 200:
+            data = _json.load(response)
+            return data["info"]["version"]
+        else:
+            raise HTTPError(URL, response.status, "Failed to fetch latest version info", response.headers, None)
+
+
+def is_latest_version() -> Optional[bool]:
+    try:
+        if (latest := get_latest_version()) in {"", None}:
+            return None
+        latest_v_parts = tuple(int(part) for part in (latest or "").lower().lstrip("v").split("."))
+        installed_v_parts = tuple(int(part) for part in __version__.lower().lstrip("v").split("."))
+        return latest_v_parts <= installed_v_parts
+    except Exception:
+        return None
+
+
+URL = "https://pypi.org/pypi/xulbux/json"
+IS_LATEST_VERSION = is_latest_version()
+
+CLI_COLORS = {
+    "border": "dim|br:black",
+    "class": "br:cyan",
+    "const": "br:blue",
+    "func": "br:green",
+    "heading": "br:white",
+    "import": "magenta",
+    "lib": "br:magenta",
+    "link": "u|br:blue",
+    "notice": "br:yellow",
+    "punctuator": "br:black",
+    "text": "white",
+}
+CLI_HELP = FormatCodes.to_ansi(
+    rf"""  [_|b|#7075FF]               __  __
+  [b|#7075FF]  _  __ __  __/ / / /_  __  ___  __
+  [b|#7075FF] | |/ // / / / / / __ \/ / / | |/ /
+  [b|#7075FF] > , </ /_/ / /_/ /_/ / /_/ /> , <
+  [b|#7075FF]/_/|_|\____/\__/\____/\____//_/|_|  [*|#000|BG:#8085FF] v[b]{__version__} [*|dim|{CLI_COLORS["notice"]}]({"" if IS_LATEST_VERSION else " (newer available)"})[*]
+
+  [i|#9095FF]A TON OF COOL FUNCTIONS, YOU NEED![*]
+
+  [b|{CLI_COLORS["heading"]}](Usage:)[*]
+  [{CLI_COLORS["border"]}](╭────────────────────────────────────────────────────╮)[*]
+  [{CLI_COLORS["border"]}](│) [i|{CLI_COLORS["punctuator"]}](# LIBRARY CONSTANTS)[*]                                [{CLI_COLORS["border"]}](│)[*]
+  [{CLI_COLORS["border"]}](│) [{CLI_COLORS["import"]}]from [{CLI_COLORS["lib"]}]xulbux[{CLI_COLORS["punctuator"]}].[{CLI_COLORS["lib"]}]base[{CLI_COLORS["punctuator"]}].[{CLI_COLORS["lib"]}]consts [{CLI_COLORS["import"]}]import [{CLI_COLORS["const"]}]COLOR[{CLI_COLORS["punctuator"]}], [{CLI_COLORS["const"]}]CHARS[{CLI_COLORS["punctuator"]}], [{CLI_COLORS["const"]}]ANSI[*]  [{CLI_COLORS["border"]}](│)[*]
+  [{CLI_COLORS["border"]}](│) [i|{CLI_COLORS["punctuator"]}](# Main Classes)[*]                                     [{CLI_COLORS["border"]}](│)[*]
+  [{CLI_COLORS["border"]}](│) [{CLI_COLORS["import"]}]from [{CLI_COLORS["lib"]}]xulbux [{CLI_COLORS["import"]}]import [{CLI_COLORS["class"]}]Code[{CLI_COLORS["punctuator"]}], [{CLI_COLORS["class"]}]Color[{CLI_COLORS["punctuator"]}], [{CLI_COLORS["class"]}]Console[{CLI_COLORS["punctuator"]}], ...[*]       [{CLI_COLORS["border"]}](│)[*]
+  [{CLI_COLORS["border"]}](│) [i|{CLI_COLORS["punctuator"]}](# module specific imports)[*]                          [{CLI_COLORS["border"]}](│)[*]
+  [{CLI_COLORS["border"]}](│) [{CLI_COLORS["import"]}]from [{CLI_COLORS["lib"]}]xulbux[{CLI_COLORS["punctuator"]}].[{CLI_COLORS["lib"]}]color [{CLI_COLORS["import"]}]import [{CLI_COLORS["func"]}]rgba[{CLI_COLORS["punctuator"]}], [{CLI_COLORS["func"]}]hsla[{CLI_COLORS["punctuator"]}], [{CLI_COLORS["func"]}]hexa[*]          [{CLI_COLORS["border"]}](│)
+  [{CLI_COLORS["border"]}](╰────────────────────────────────────────────────────╯)[*]
+  [b|{CLI_COLORS["heading"]}](Documentation:)[*]
+  [{CLI_COLORS["border"]}](╭────────────────────────────────────────────────────╮)[*]
+  [{CLI_COLORS["border"]}](│) [{CLI_COLORS["text"]}]For more information see the GitHub page.          [{CLI_COLORS["border"]}](│)[*]
+  [{CLI_COLORS["border"]}](│) [{CLI_COLORS["link"]}](https://github.com/XulbuX/PythonLibraryXulbuX/wiki) [{CLI_COLORS["border"]}](│)[*]
+  [{CLI_COLORS["border"]}](╰────────────────────────────────────────────────────╯)[*]
+  [_]"""
+)
+
+
+def show_help() -> None:
+    FormatCodes._config_console()
+    print(CLI_HELP)
+    Console.pause_exit(pause=True, prompt="  [dim](Press any key to exit...)\n\n")

xulbux/code.py

@@ -0,0 +1,137 @@
+"""
+This module provides the `Code` class, which offers methods to work with code strings.
+"""
+
+from .string import String
+from .regex import Regex
+from .data import Data
+
+import regex as _rx
+
+
+class Code:
+    """This class includes methods to work with code strings."""
+
+    @classmethod
+    def add_indent(cls, code: str, indent: int) -> str:
+        """Adds `indent` spaces at the beginning of each line.\n
+        --------------------------------------------------------------------------
+        - `code` -⠀the code to indent
+        - `indent` -⠀the amount of spaces to add at the beginning of each line"""
+        if indent < 0:
+            raise ValueError(f"The 'indent' parameter must be non-negative, got {indent!r}")
+
+        return "\n".join(" " * indent + line for line in code.splitlines())
+
+    @classmethod
+    def get_tab_spaces(cls, code: str) -> int:
+        """Will try to get the amount of spaces used for indentation.\n
+        ----------------------------------------------------------------
+        - `code` -⠀the code to analyze"""
+        indents = [len(line) - len(line.lstrip()) for line in String.get_lines(code, remove_empty_lines=True)]
+        return min(non_zero_indents) if (non_zero_indents := [i for i in indents if i > 0]) else 0
+
+    @classmethod
+    def change_tab_size(cls, code: str, new_tab_size: int, remove_empty_lines: bool = False) -> str:
+        """Replaces all tabs with `new_tab_size` spaces.\n
+        --------------------------------------------------------------------------------
+        - `code` -⠀the code to modify the tab size of
+        - `new_tab_size` -⠀the new amount of spaces per tab
+        - `remove_empty_lines` -⠀is true, empty lines will be removed in the process"""
+        if new_tab_size < 0:
+            raise ValueError(f"The 'new_tab_size' parameter must be non-negative, got {new_tab_size!r}")
+
+        code_lines = String.get_lines(code, remove_empty_lines=remove_empty_lines)
+
+        if ((tab_spaces := cls.get_tab_spaces(code)) == new_tab_size) or tab_spaces == 0:
+            if remove_empty_lines:
+                return "\n".join(code_lines)
+            return code
+
+        result = []
+        for line in code_lines:
+            indent_level = (len(line) - len(stripped := line.lstrip())) // tab_spaces
+            result.append((" " * (indent_level * new_tab_size)) + stripped)
+
+        return "\n".join(result)
+
+    @classmethod
+    def get_func_calls(cls, code: str) -> list:
+        """Will try to get all function calls and return them as a list.\n
+        -------------------------------------------------------------------
+        - `code` -⠀the code to analyze"""
+        nested_func_calls = []
+
+        for _, func_attrs in (funcs := _rx.findall(r"(?i)" + Regex.func_call(), code)):
+            if (nested_calls := _rx.findall(r"(?i)" + Regex.func_call(), func_attrs)):
+                nested_func_calls.extend(nested_calls)
+
+        return list(Data.remove_duplicates(funcs + nested_func_calls))
+
+    @classmethod
+    def is_js(cls, code: str, funcs: set[str] = {"__", "$t", "$lang"}) -> bool:
+        """Will check if the code is very likely to be JavaScript.\n
+        -------------------------------------------------------------
+        - `code` -⠀the code to analyze
+        - `funcs` -⠀a list of custom function names to check for"""
+        if len(code.strip()) < 3:
+            return False
+
+        for func in funcs:
+            if _rx.match(r"^[\s\n]*" + _rx.escape(func) + r"\([^\)]*\)[\s\n]*$", code):
+                return True
+
+        direct_js_patterns = [
+            r"""^[\s\n]*\$\(["'][^"']+["']\)\.[\w]+\([^\)]*\);?[\s\n]*$""",  # jQuery calls
+            r"^[\s\n]*\$\.[a-zA-Z]\w*\([^\)]*\);?[\s\n]*$",  # $.ajax(), etc.
+            r"^[\s\n]*\(\s*function\s*\(\)\s*\{.*\}\s*\)\(\);?[\s\n]*$",  # IIFE
+            r"^[\s\n]*document\.[a-zA-Z]\w*\([^\)]*\);?[\s\n]*$",  # document.getElementById()
+            r"^[\s\n]*window\.[a-zA-Z]\w*\([^\)]*\);?[\s\n]*$",  # window.alert()
+            r"^[\s\n]*console\.[a-zA-Z]\w*\([^\)]*\);?[\s\n]*$",  # console.log()
+        ]
+        for pattern in direct_js_patterns:
+            if _rx.match(pattern, code):
+                return True
+
+        arrow_function_patterns = [
+            r"^[\s\n]*\b[\w_]+\s*=\s*\([^\)]*\)\s*=>\s*[^;{]*[;]?[\s\n]*$",  # const x = (y) => y*2;
+            r"^[\s\n]*\b[\w_]+\s*=\s*[\w_]+\s*=>\s*[^;{]*[;]?[\s\n]*$",  # const x = y => y*2;
+            r"^[\s\n]*\(\s*[\w_,\s]+\s*\)\s*=>\s*[^;{]*[;]?[\s\n]*$",  # (x) => x*2
+            r"^[\s\n]*[\w_]+\s*=>\s*[^;{]*[;]?[\s\n]*$",  # x => x*2
+        ]
+        for pattern in arrow_function_patterns:
+            if _rx.match(pattern, code):
+                return True
+
+        js_score = 0.0
+        funcs_pattern = r"(" + "|".join(_rx.escape(func) for func in funcs) + r")" + Regex.brackets("()")
+        js_indicators: list[tuple[str, float]] = [
+            (r"\b(var|let|const)\s+[\w_$]+", 2.0),  # JS VARIABLE DECLARATIONS
+            (r"\$[\w_$]+\s*=", 2.0),  # jQuery-STYLE VARIABLES
+            (r"\$[\w_$]+\s*\(", 2.0),  # jQuery FUNCTION CALLS
+            (r"\bfunction\s*[\w_$]*\s*\(", 2.0),  # FUNCTION DECLARATIONS
+            (r"[\w_$]+\s*=\s*function\s*\(", 2.0),  # FUNCTION ASSIGNMENTS
+            (r"\b[\w_$]+\s*=>\s*[\{\(]", 2.0),  # ARROW FUNCTIONS
+            (r"\(function\s*\(\)\s*\{", 2.0),  # IIFE PATTERN
+            (funcs_pattern, 2.0),  # CUSTOM PREDEFINED FUNCTIONS
+            (r"\b(true|false|null|undefined)\b", 1.0),  # JS LITERALS
+            (r"===|!==|\+\+|--|\|\||&&", 1.5),  # JS-SPECIFIC OPERATORS
+            (r"\bnew\s+[\w_$]+\s*\(", 1.5),  # OBJECT INSTANTIATION WITH NEW
+            (r"\b(document|window|console|Math|Array|Object|String|Number)\.", 2.0),  # JS OBJECTS
+            (r"\basync\s+function|\bawait\b", 2.0),  # ASYNC/AWAIT
+            (r"\b(if|for|while|switch)\s*\([^)]*\)\s*\{", 1.0),  # CONTROL STRUCTURES WITH BRACES
+            (r"\btry\s*\{[^}]*\}\s*catch\s*\(", 1.5),  # TRY-CATCH
+            (r";[\s\n]*$", 0.5),  # SEMICOLON LINE ENDINGS
+        ]
+
+        line_endings = [line.strip() for line in code.splitlines() if line.strip()]
+        if (semicolon_endings := sum(1 for line in line_endings if line.endswith(";"))) >= 1:
+            js_score += min(semicolon_endings, 2)
+        if (opening_braces := code.count("{")) > 0 and opening_braces == code.count("}"):
+            js_score += 1
+
+        for pattern, score in js_indicators:
+            if (matches := _rx.compile(pattern, _rx.IGNORECASE).findall(code)):
+                js_score += len(matches) * score
+
+        return js_score >= 2.0