From 14e28d3c99547946f5e24e14f8c81577cd8174af Mon Sep 17 00:00:00 2001 From: Farhan Date: Fri, 20 Nov 2026 21:15:07 +0000 Subject: [PATCH 01/16] Type the stubs of imported JavaScript modules from TypeScript and JSDoc The stub written next to an imported JavaScript module typed every function as `(*args: Any)`. It now reads each export's call signatures with the TypeScript checker, from annotations in a .ts file or JSDoc in a .js file, through script-signatures.js, which ships to .web beside the other build scripts an app runs: /** @param {number} count @param {string} elementId @param {boolean} [loud] */ export function celebrate(count, elementId, loud = false) {} def celebrate(count: float | Var[float], elementId: str | Var[str] | EventCallback[*tuple[Any, ...]], loud: bool | Var[bool] = ..., /) -> EventSpec: ... Arguments are positional-only, as JavaScript passes them. JSON types map to Python (number to float, T[] to Sequence, unions, literals, `| null`); types with no JSON form become Any. A string parameter also takes an event handler, which the call sends as its name. Overloads become @overload, rest parameters *args, and exports that are not functions are left out. typescript (pinned to the version reflex-frontend checks itself with, which a test keeps equal) is installed only with apps that import a module, and runs after the install, once for every stale module. The stub's header records a digest of the module and the scripts beside it, so typescript does not run while they are unchanged. When the types cannot be read (no node or bun, or the script fails) the stub stays untyped, with a warning, and is retried on the next compile. Part of ENG-9127. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- docs/api-reference/browser_javascript.md | 18 +- news/+js-module-stubs.feature.md | 1 + .../news/+js-module-stubs.feature.md | 1 + .../reflex-base/src/reflex_base/js/modules.py | 29 -- .../reflex-base/src/reflex_base/js/stubs.py | 314 ++++++++++++++++++ .../reflex-frontend/src/script-signatures.js | 84 +++++ .../tests/fixtures/signatures/jsdoc.js | 15 + .../tests/fixtures/signatures/typed.ts | 5 + .../tests/script_signatures.test.js | 80 +++++ reflex/compiler/compiler.py | 2 + reflex/compiler/utils.py | 98 +++++- .../tests_playwright/test_call_script.py | 25 ++ tests/units/compiler/test_compiler_utils.py | 107 ++++-- tests/units/reflex_base/js/test_modules.py | 12 - tests/units/reflex_base/js/test_stubs.py | 174 ++++++++++ 15 files changed, 890 insertions(+), 75 deletions(-) create mode 100644 news/+js-module-stubs.feature.md create mode 100644 packages/reflex-base/news/+js-module-stubs.feature.md create mode 100644 packages/reflex-base/src/reflex_base/js/stubs.py create mode 100644 packages/reflex-frontend/src/script-signatures.js create mode 100644 packages/reflex-frontend/tests/fixtures/signatures/jsdoc.js create mode 100644 packages/reflex-frontend/tests/fixtures/signatures/typed.ts create mode 100644 packages/reflex-frontend/tests/script_signatures.test.js create mode 100644 tests/units/reflex_base/js/test_stubs.py diff --git a/docs/api-reference/browser_javascript.md b/docs/api-reference/browser_javascript.md index ac2431a9d6a..f33e3a4da4c 100644 --- a/docs/api-reference/browser_javascript.md +++ b/docs/api-reference/browser_javascript.md @@ -232,7 +232,23 @@ rx.button("Report", on_click=report(PartyState.done, "clicked")) - The `.js` and `.ts` files beside the module are bundled with it, so it can import them with relative paths such as `./helpers.js`. - Reflex writes a type stub (`party.pyi`) next to the module when it compiles - the app, so type checkers resolve the import. + the app, so type checkers resolve the import and check each call. Argument + types come from TypeScript annotations or, in a `.js` file, JSDoc: + + ```javascript + /** + * @param {number} count + * @param {string} elementId + */ + export function celebrate(count, elementId) {} + ``` + + becomes `def celebrate(count: float | Var[float], elementId: str | Var[str] | ..., /) -> EventSpec`. + A `string` parameter also takes an event handler, sent as its name. + Arguments without a type, or of a type with no JSON form such as an + `HTMLElement`, are `Any`. The stub is rewritten only when a script in the + module's folder changes. Pyright reports a stub without a Python module as + `reportMissingModuleSource`; set it to `"none"` to silence it. ## Using React Hooks diff --git a/news/+js-module-stubs.feature.md b/news/+js-module-stubs.feature.md new file mode 100644 index 00000000000..0360ade0662 --- /dev/null +++ b/news/+js-module-stubs.feature.md @@ -0,0 +1 @@ +The type stub Reflex writes next to an imported JavaScript module now types each function's arguments from its TypeScript annotations or JSDoc, so type checkers catch a wrong argument in Python, e.g. `celebrate("lots")` for `@param {number} count`. diff --git a/packages/reflex-base/news/+js-module-stubs.feature.md b/packages/reflex-base/news/+js-module-stubs.feature.md new file mode 100644 index 00000000000..c9fd3fa22e8 --- /dev/null +++ b/packages/reflex-base/news/+js-module-stubs.feature.md @@ -0,0 +1 @@ +Type the stubs written next to JavaScript modules imported from Python: `script-signatures.js` reads each export's parameters from TypeScript annotations or JSDoc, and typescript is installed with apps that import a module. diff --git a/packages/reflex-base/src/reflex_base/js/modules.py b/packages/reflex-base/src/reflex_base/js/modules.py index 433c860db60..732691a8003 100644 --- a/packages/reflex-base/src/reflex_base/js/modules.py +++ b/packages/reflex-base/src/reflex_base/js/modules.py @@ -11,7 +11,6 @@ import dataclasses import inspect -import keyword import re from pathlib import Path from types import ModuleType @@ -174,31 +173,3 @@ def load_module(module: ModuleType, path: Path) -> None: for name in exports: setattr(module, name, JsFunction(module.__name__, name)) setattr(module, "__all__", exports) # noqa: B010 - - -def render_stub(path: Path, exports: list[str]) -> str: - """Render a type stub for a JavaScript module, so type checkers see it. - - Exports that are not Python identifiers cannot be imported and are left - out. The arguments are untyped. - - Args: - path: The JavaScript file. - exports: Its export names. - - Returns: - The ``.pyi`` source. - """ - lines = [ - f"# Generated by Reflex from {path.name}; rewritten when it changes.", - "from typing import Any", - "", - "from reflex_base.event import EventSpec", - "", - ] - lines.extend( - f"def {name}(*args: Any) -> EventSpec: ..." - for name in exports - if name.isidentifier() and not keyword.iskeyword(name) - ) - return "\n".join(lines) + "\n" diff --git a/packages/reflex-base/src/reflex_base/js/stubs.py b/packages/reflex-base/src/reflex_base/js/stubs.py new file mode 100644 index 00000000000..57341dec149 --- /dev/null +++ b/packages/reflex-base/src/reflex_base/js/stubs.py @@ -0,0 +1,314 @@ +"""Type stubs for JavaScript modules imported from Python. + +A stub sits next to its module (``party.js`` gets ``party.pyi``), so type +checkers resolve ``from my_app.scripts.party import celebrate`` and check the +call. Argument types come from the module's TypeScript annotations or JSDoc, +read by ``script-signatures.js`` in the app's ``.web``; without them, the +arguments are untyped. +""" + +from __future__ import annotations + +import hashlib +import keyword +import re +from collections.abc import Iterable, Mapping, Sequence +from pathlib import Path +from typing import TypedDict + +from reflex_base.js.finder import SCRIPT_EXTENSIONS + +# Bumped when the stub format changes, so every stub is rewritten. +_STUB_VERSION = "1" + +# Installed with an app that imports a JavaScript module, to read its types. +# Kept equal to the typescript reflex-frontend type-checks itself with. +TYPESCRIPT_PACKAGE = "typescript@5.9.3" + +# The script in .web that prints the signatures of modules' exports. +SIGNATURES_SCRIPT = "script-signatures.js" + +_HEADER = "# Generated by Reflex from {name} ({digest}); rewritten when it changes." + +_IMPORTS = """\ +from collections.abc import Mapping, Sequence +from typing import Any, overload + +from reflex_base.event import EventCallback, EventSpec +from reflex_base.vars.base import Var +""" + +# TypeScript types with a Python counterpart, by their checker spelling. +_SIMPLE_TYPES = { + "number": "float", + "bigint": "int", + "string": "str", + "boolean": "bool", + "true": "bool", + "false": "bool", + "null": "None", + "undefined": "None", + "void": "None", + "object": "Mapping[str, Any]", +} +_GENERIC_RE = re.compile( + r"(Array|ReadonlyArray|Set|ReadonlySet|Promise)<(.*)>", re.DOTALL +) +_STRING_LITERAL_RE = re.compile(r"""(["'`]).*\1""", re.DOTALL) +_NUMBER_LITERAL_RE = re.compile(r"-?\d[\d_]*(\.\d+)?") + + +class Parameter(TypedDict): + """A parameter of a signature, as ``script-signatures.js`` prints it.""" + + name: str + type: str + optional: bool + rest: bool + + +class Signature(TypedDict): + """A call signature of an export.""" + + parameters: list[Parameter] + + +class Export(TypedDict): + """An export and its call signatures; none when it is not a function.""" + + name: str + signatures: list[Signature] + + +def module_digest(path: Path) -> str: + """Hash a module and the script files beside it, which its types may use. + + Args: + path: The module. + + Returns: + A short hex digest. + """ + digest = hashlib.sha256(_STUB_VERSION.encode()) + for file in sorted(path.parent.iterdir()): + if file.suffix in SCRIPT_EXTENSIONS: + digest.update(file.name.encode()) + digest.update(b"\0") + digest.update(file.read_bytes()) + digest.update(b"\0") + return digest.hexdigest()[:16] + + +def stub_header(path: Path, digest: str) -> str: + """Get the first line of a module's stub, which records what it was made from. + + Args: + path: The module. + digest: Its ``module_digest``. + + Returns: + The header line. + """ + return _HEADER.format(name=path.name, digest=digest) + + +def _split_top_level(text: str, separator: str) -> list[str]: + """Split a type at the separators outside brackets and string literals. + + Args: + text: The type. + separator: A one-character separator. + + Returns: + The parts, stripped. + """ + parts: list[str] = [] + depth = 0 + quote = "" + start = 0 + for index, char in enumerate(text): + if quote: + if char == quote: + quote = "" + elif char in "\"'`": + quote = char + elif char in "([{<": + depth += 1 + elif char in ")]}>": + depth -= 1 + elif char == separator and depth == 0: + parts.append(text[start:index].strip()) + start = index + 1 + parts.append(text[start:].strip()) + return [part for part in parts if part] + + +def python_type(ts_type: str) -> str: + """Translate a TypeScript type to the Python type of a value sent as JSON. + + Types with no JSON counterpart, such as functions, DOM elements or a + library's own types, become ``Any``. + + Args: + ts_type: The type, as the TypeScript checker prints it. + + Returns: + The Python type. + """ + ts_type = ts_type.strip().removeprefix("readonly ") + union = _split_top_level(ts_type, "|") + if len(union) > 1: + members = dict.fromkeys(python_type(member) for member in union) + return "Any" if "Any" in members else " | ".join(members) + if ts_type.startswith("(") and ts_type.endswith(")"): + inner = ts_type[1:-1] + if _split_top_level(inner, ",") == [inner.strip()] and "=>" not in ts_type: + return python_type(inner) + if ts_type.endswith("[]"): + return f"Sequence[{python_type(ts_type[:-2])}]" + if match := _GENERIC_RE.fullmatch(ts_type): + inner = python_type(match.group(2)) + return inner if match.group(1) == "Promise" else f"Sequence[{inner}]" + if ts_type.startswith("["): + return "Sequence[Any]" + if ts_type.startswith(("{", "Record<", "Map<")): + return "Mapping[str, Any]" + if _STRING_LITERAL_RE.fullmatch(ts_type): + return "str" + if _NUMBER_LITERAL_RE.fullmatch(ts_type): + return "float" + return _SIMPLE_TYPES.get(ts_type, "Any") + + +def _annotation(ts_type: str) -> str: + """Get the annotation of a parameter: its value, or a Var of it. + + A string parameter also takes an event handler, which is sent as its name. + + Args: + ts_type: The parameter's TypeScript type. + + Returns: + The annotation. + """ + value = python_type(ts_type) + if value == "Any": + return "Any" + handler = ( + " | EventCallback[*tuple[Any, ...]]" if "str" in value.split(" | ") else "" + ) + return f"{value} | Var[{value}]{handler}" + + +def _render_signature(name: str, signature: Signature) -> str: + """Render one signature of an export as a ``def``. + + Arguments are positional-only, since JavaScript passes them by position, + so a parameter name that is not a Python identifier is renamed safely. + + Args: + name: The export name. + signature: The signature. + + Returns: + The ``def`` line. + """ + params: list[str] = [] + rest = "" + optional = False + for index, parameter in enumerate(signature["parameters"]): + param_name = parameter["name"] + if not param_name.isidentifier() or keyword.iskeyword(param_name): + param_name = f"arg{index}" + if parameter["rest"]: + rest = f"*{param_name}: {_annotation(parameter['type'])}" + break + optional = optional or parameter["optional"] + ts_type = parameter["type"] + if parameter["optional"]: + # The checker adds `undefined` to an optional parameter's type. + ts_type = ( + " | ".join( + member + for member in _split_top_level(ts_type, "|") + if member != "undefined" + ) + or "undefined" + ) + params.append( + f"{param_name}: {_annotation(ts_type)}" + (" = ..." if optional else "") + ) + rendered = [*params, "/"] if params else [] + if rest: + rendered.append(rest) + return f"def {name}({', '.join(rendered)}) -> EventSpec: ..." + + +def _importable(name: str) -> bool: + """Whether an export can be imported in Python. + + Args: + name: The export name. + + Returns: + Whether it is an identifier and not a keyword. + """ + return name.isidentifier() and not keyword.iskeyword(name) + + +def render_stub(path: Path, digest: str, exports: Iterable[Export]) -> str: + """Render the stub of a module from its exports' signatures. + + Exports that are not functions, and those Python cannot import, are left + out. An export with several signatures gets one overload each. + + Args: + path: The module. + digest: Its ``module_digest``. + exports: Its exports. + + Returns: + The ``.pyi`` source. + """ + lines = [stub_header(path, digest), _IMPORTS] + for export in exports: + signatures = export["signatures"] + if not signatures or not _importable(export["name"]): + continue + for signature in signatures: + if len(signatures) > 1: + lines.append("@overload") + lines.append(_render_signature(export["name"], signature)) + return "\n".join(lines) + "\n" + + +def render_untyped_stub(path: Path, digest: str, names: Sequence[str]) -> str: + """Render the stub of a module whose types could not be read. + + Args: + path: The module. + digest: Its ``module_digest``. + names: Its export names. + + Returns: + The ``.pyi`` source, with untyped arguments. + """ + lines = [stub_header(path, digest), _IMPORTS] + lines.extend( + f"def {name}(*args: Any) -> EventSpec: ..." + for name in names + if _importable(name) + ) + return "\n".join(lines) + "\n" + + +def exports_by_file(output: Mapping[str, list[Export]]) -> dict[Path, list[Export]]: + """Key the output of ``script-signatures.js`` by resolved path. + + Args: + output: The parsed JSON. + + Returns: + The exports of each module. + """ + return {Path(file).resolve(): exports for file, exports in output.items()} diff --git a/packages/reflex-frontend/src/script-signatures.js b/packages/reflex-frontend/src/script-signatures.js new file mode 100644 index 00000000000..fe9b7555282 --- /dev/null +++ b/packages/reflex-frontend/src/script-signatures.js @@ -0,0 +1,84 @@ +/* Print the call signatures of the functions JavaScript modules export, as + * JSON, for the Python type stubs Reflex writes next to modules an app imports + * from Python. Types come from TypeScript annotations or, in a .js file, JSDoc. + * + * Usage: node script-signatures.js ... + * Run from the app's .web directory, which installs typescript when an app + * imports a module. */ + +import { createRequire } from "node:module"; +import { join } from "node:path"; + +const require = createRequire(import.meta.url); +const ts = require("typescript"); + +const web = process.cwd(); +const files = process.argv.slice(2); +const program = ts.createProgram(files, { + allowJs: true, + noEmit: true, + skipLibCheck: true, + // Keep `null` and `undefined` in the types, for `| None` in Python. + strictNullChecks: true, + target: ts.ScriptTarget.ES2022, + module: ts.ModuleKind.ESNext, + moduleResolution: ts.ModuleResolutionKind.Bundler, + // Resolve `$/...` and npm packages as the app's bundler does, so imported + // types are known; a module outside .web finds no node_modules of its own. + baseUrl: web, + paths: { + "$/*": [join(web, "*")], + "*": [ + join(web, "node_modules", "@types", "*"), + join(web, "node_modules", "*"), + ], + }, +}); +const checker = program.getTypeChecker(); + +/** + * Describe one parameter of a signature. + * @param {any} parameter The parameter symbol. + * @param {any} location The node to resolve its type at. + * @returns {{name: string, type: string, optional: boolean, rest: boolean}} The parameter. + */ +const describeParameter = (parameter, location) => { + const declaration = parameter.valueDeclaration; + const rest = Boolean(declaration?.dotDotDotToken); + let type = checker.getTypeOfSymbolAtLocation(parameter, location); + if (rest && checker.isArrayType(type)) { + type = checker.getTypeArguments(/** @type {any} */ (type))[0]; + } + return { + name: parameter.getName(), + type: checker.typeToString(type), + optional: Boolean( + declaration && + (declaration.questionToken || + declaration.initializer || + checker.isOptionalParameter(declaration)), + ), + rest, + }; +}; + +/** @type {Record} */ +const result = {}; +for (const file of files) { + const source = program.getSourceFile(file); + const moduleSymbol = source && checker.getSymbolAtLocation(source); + result[file] = (moduleSymbol ? checker.getExportsOfModule(moduleSymbol) : []) + .filter((symbol) => symbol.getName() !== "default") + .map((symbol) => ({ + name: symbol.getName(), + signatures: checker + .getTypeOfSymbolAtLocation(symbol, source) + .getCallSignatures() + .map((signature) => ({ + parameters: signature + .getParameters() + .map((parameter) => describeParameter(parameter, source)), + })), + })); +} +process.stdout.write(JSON.stringify(result)); diff --git a/packages/reflex-frontend/tests/fixtures/signatures/jsdoc.js b/packages/reflex-frontend/tests/fixtures/signatures/jsdoc.js new file mode 100644 index 00000000000..9250f94234e --- /dev/null +++ b/packages/reflex-frontend/tests/fixtures/signatures/jsdoc.js @@ -0,0 +1,15 @@ +/** + * @param {number} count + * @param {string} elementId + * @param {boolean} [loud] + */ +export function celebrate(count, elementId, loud = false) {} + +/** @param {...string} names */ +export function many(...names) {} + +export const untyped = (a, b) => a + b; + +export const notAFunction = 3; + +export default function () {} diff --git a/packages/reflex-frontend/tests/fixtures/signatures/typed.ts b/packages/reflex-frontend/tests/fixtures/signatures/typed.ts new file mode 100644 index 00000000000..96967c8b602 --- /dev/null +++ b/packages/reflex-frontend/tests/fixtures/signatures/typed.ts @@ -0,0 +1,5 @@ +export function pick(mode: "a" | "b", maybe: string | null): void {} + +export function overloaded(n: number): void; +export function overloaded(): void; +export function overloaded(n?: number): void {} diff --git a/packages/reflex-frontend/tests/script_signatures.test.js b/packages/reflex-frontend/tests/script_signatures.test.js new file mode 100644 index 00000000000..884db83be7a --- /dev/null +++ b/packages/reflex-frontend/tests/script_signatures.test.js @@ -0,0 +1,80 @@ +// @vitest-environment node +/** + * `script-signatures.js` prints the call signatures of the functions modules + * export, which Reflex turns into Python type stubs. It runs in an app's .web + * with node, so this runs it the same way, as a child process. + */ +import { execFileSync } from "node:child_process"; +import { fileURLToPath } from "node:url"; +import { expect, test } from "vitest"; + +const root = fileURLToPath(new URL("..", import.meta.url)); +const fixture = (name) => + fileURLToPath(new URL(`./fixtures/signatures/${name}`, import.meta.url)); + +const signatures = (...files) => + JSON.parse( + execFileSync(process.execPath, ["src/script-signatures.js", ...files], { + cwd: root, + encoding: "utf-8", + }), + ); + +const param = (name, type, optional = false, rest = false) => ({ + name, + type, + optional, + rest, +}); + +test("reads JSDoc types, optional and rest parameters", () => { + const file = fixture("jsdoc.js"); + expect(signatures(file)).toEqual({ + [file]: [ + { + name: "celebrate", + signatures: [ + { + parameters: [ + param("count", "number"), + param("elementId", "string"), + param("loud", "boolean | undefined", true), + ], + }, + ], + }, + { + name: "many", + signatures: [{ parameters: [param("names", "string", false, true)] }], + }, + { + name: "untyped", + signatures: [{ parameters: [param("a", "any"), param("b", "any")] }], + }, + { name: "notAFunction", signatures: [] }, + ], + }); +}); + +test("reads TypeScript types and overloads, several files at once", () => { + const typed = fixture("typed.ts"); + const result = signatures(typed, fixture("jsdoc.js")); + expect(Object.keys(result)).toEqual([typed, fixture("jsdoc.js")]); + expect(result[typed]).toEqual([ + { + name: "pick", + signatures: [ + { + parameters: [ + param("mode", '"a" | "b"'), + param("maybe", "string | null"), + ], + }, + ], + }, + { + name: "overloaded", + signatures: [{ parameters: [param("n", "number")] }, { parameters: [] }], + }, + ]); +}); diff --git a/reflex/compiler/compiler.py b/reflex/compiler/compiler.py index bbe645ed8e5..4966ba5d382 100644 --- a/reflex/compiler/compiler.py +++ b/reflex/compiler/compiler.py @@ -1616,6 +1616,8 @@ def add_save_task( app._get_frontend_packages( utils.merge_imports(all_imports, script_module_imports) ) + # After the install: reading the modules' types needs typescript. + compile_results.extend(utils.compile_script_stubs()) frontend_skeleton.update_react_router_config( prerender_routes=prerender_routes, diff --git a/reflex/compiler/utils.py b/reflex/compiler/utils.py index 36531ebbd1d..e2b5afdb13d 100644 --- a/reflex/compiler/utils.py +++ b/reflex/compiler/utils.py @@ -9,6 +9,7 @@ import json import operator import os +import subprocess import tempfile import traceback from collections.abc import Iterable, Mapping, Sequence @@ -33,15 +34,19 @@ ) from reflex_base.constants.state import FIELD_MARKER from reflex_base.js.finder import SCRIPT_EXTENSIONS -from reflex_base.js.modules import ( - find_exports, - find_package_imports, - module_key, +from reflex_base.js.modules import find_exports, find_package_imports, module_key +from reflex_base.js.stubs import ( + SIGNATURES_SCRIPT, + TYPESCRIPT_PACKAGE, + exports_by_file, + module_digest, render_stub, + render_untyped_stub, + stub_header, ) from reflex_base.registry import RegistrationContext from reflex_base.style import Style -from reflex_base.utils import format, imports, memo_paths, serializers, types +from reflex_base.utils import console, format, imports, memo_paths, serializers, types from reflex_base.utils.exceptions import VarTypeError from reflex_base.utils.imports import ImportVar, ParsedImportDict from reflex_base.vars.base import Field, Var, VarData @@ -314,12 +319,11 @@ def compile_script_modules() -> tuple[ Each module is copied under ``utils/script_modules`` at the path of its Python name, with the script files beside it so its relative imports - resolve, and ``utils/scripts.js`` re-exports it under its module key. A - type stub is written next to the module, for type checkers. + resolve, and ``utils/scripts.js`` re-exports it under its module key. Returns: - The (path, code) outputs, and the npm packages the modules import, to - install. + The (path, code) outputs, and the npm packages to install: those the + modules import, and typescript, which reads their types for the stubs. """ web_dir = get_web_dir() outputs: list[tuple[str, str]] = [] @@ -347,8 +351,8 @@ def compile_script_modules() -> tuple[ package_imports[specifier] = [ImportVar(tag=None, render=False)] target = f"$/{constants.Dirs.SCRIPT_MODULES_PATH}/{package_dir.as_posix()}/{path.name}" index.append(f'export * as {module_key(name)} from "{target}";') - exports = find_exports(path.read_text(encoding="utf-8")) - outputs.append((str(path.with_suffix(".pyi")), render_stub(path, exports))) + if modules: + package_imports[TYPESCRIPT_PACKAGE] = [ImportVar(tag=None, render=False)] outputs.append(( str(web_dir / (constants.Dirs.SCRIPTS_PATH + constants.Ext.JS)), "\n".join(index) + "\n" if index else "export {};\n", @@ -356,6 +360,78 @@ def compile_script_modules() -> tuple[ return outputs, package_imports +def _read_script_signatures(paths: Sequence[Path]) -> dict[Path, list] | None: + """Read the signatures of the functions JavaScript modules export. + + Runs ``script-signatures.js`` in ``.web``, which needs typescript installed. + + Args: + paths: The modules. + + Returns: + The exports of each module by resolved path, or None if they could not + be read. + """ + runtime = path_ops.get_node_path() or path_ops.get_bun_path() + if runtime is None: + console.warn( + "Found neither node nor bun to read the types of JavaScript modules." + ) + return None + try: + process = subprocess.run( + [str(runtime), SIGNATURES_SCRIPT, *map(str, paths)], + cwd=get_web_dir(), + capture_output=True, + text=True, + timeout=120, + check=True, + ) + return exports_by_file(json.loads(process.stdout)) + except subprocess.CalledProcessError as error: + detail = error.stderr.strip() + except (OSError, subprocess.SubprocessError, ValueError) as error: + detail = str(error) + console.warn(f"Could not read the types of JavaScript modules: {detail}") + return None + + +def compile_script_stubs() -> list[tuple[str, str]]: + """Write a type stub next to each JavaScript module the app imports. + + Argument types come from the module's TypeScript annotations or JSDoc. A + stub whose header records the current module and its sibling files is + kept, so typescript only runs when a script changed. When the types cannot + be read, the stub has untyped arguments and is retried on the next compile. + + Returns: + The (path, code) outputs for the stubs to rewrite. + """ + stale: dict[Path, str] = {} + for path in RegistrationContext.ensure_context().script_modules.values(): + digest = module_digest(path) + try: + current = path.with_suffix(".pyi").read_text(encoding="utf-8") + except OSError: + current = "" + if current.partition("\n")[0] != stub_header(path, digest): + stale[path] = digest + if not stale: + return [] + signatures = _read_script_signatures(list(stale)) or {} + return [ + ( + str(path.with_suffix(".pyi")), + render_stub(path, digest, signatures[path.resolve()]) + if path.resolve() in signatures + else render_untyped_stub( + path, "untyped", find_exports(path.read_text(encoding="utf-8")) + ), + ) + for path, digest in stale.items() + ] + + def _restore_bundled_libraries() -> bool: """Restore the registry saved by the most recent compile. diff --git a/tests/integration/tests_playwright/test_call_script.py b/tests/integration/tests_playwright/test_call_script.py index 0af78422f7f..dc60788e5e6 100644 --- a/tests/integration/tests_playwright/test_call_script.py +++ b/tests/integration/tests_playwright/test_call_script.py @@ -43,9 +43,11 @@ def CallScript(): # A JavaScript module beside the app, imported from Python. Path(__file__).with_name("page_script.js").write_text( 'import { env } from "$/utils/script_env";\n' + "/** @param {string} id @param {string} text */\n" "export function setText(id, text) {\n" " document.getElementById(id).textContent = text;\n" "}\n" + "/** @param {string} handler @param {string} value */\n" "export async function report(handler, value) {\n" " await Promise.resolve();\n" " env.addEvents([env.event(handler, { value })]);\n" @@ -633,3 +635,26 @@ def test_js_module(call_script_page: Page): call_script_page.locator("#js_module_report").click() expect(call_script_page.locator("#env_result")).to_have_value("from a module") + + +def test_js_module_stub(call_script: AppHarness): + """A typed stub is written next to the module from its JSDoc. + + Args: + call_script: harness for CallScript app. + """ + from reflex_base.js.stubs import module_digest, stub_header + + module = call_script.app_path / call_script.app_name / "page_script.js" + handler = "str | Var[str] | EventCallback[*tuple[Any, ...]]" + assert (module.with_suffix(".pyi")).read_text() == ( + stub_header(module, module_digest(module)) + "\n" + "from collections.abc import Mapping, Sequence\n" + "from typing import Any, overload\n" + "\n" + "from reflex_base.event import EventCallback, EventSpec\n" + "from reflex_base.vars.base import Var\n" + "\n" + f"def setText(id: {handler}, text: {handler}, /) -> EventSpec: ...\n" + f"def report(handler: {handler}, value: {handler}, /) -> EventSpec: ...\n" + ) diff --git a/tests/units/compiler/test_compiler_utils.py b/tests/units/compiler/test_compiler_utils.py index 44f3da2d05c..fb89c851f04 100644 --- a/tests/units/compiler/test_compiler_utils.py +++ b/tests/units/compiler/test_compiler_utils.py @@ -11,6 +11,12 @@ import pytest from reflex_base import constants from reflex_base.components.memo import create_passthrough_component_memo +from reflex_base.js.stubs import ( + TYPESCRIPT_PACKAGE, + module_digest, + render_stub, + render_untyped_stub, +) from reflex_base.registry import RegistrationContext from reflex_components_core.base.fragment import Fragment from reflex_components_core.base.script import Script @@ -848,29 +854,7 @@ def test_compile_script_modules( assert outputs == [ (str(modules_dir / "app" / "scripts" / "helpers.js"), helpers.read_text()), (str(modules_dir / "app" / "scripts" / "party.js"), party.read_text()), - ( - str(scripts / "party.pyi"), - ( - "# Generated by Reflex from party.js; rewritten when it changes.\n" - "from typing import Any\n" - "\n" - "from reflex_base.event import EventSpec\n" - "\n" - "def celebrate(*args: Any) -> EventSpec: ...\n" - ), - ), (str(modules_dir / "app" / "typed.ts"), typed.read_text()), - ( - str(tmp_path / "app" / "typed.pyi"), - ( - "# Generated by Reflex from typed.ts; rewritten when it changes.\n" - "from typing import Any\n" - "\n" - "from reflex_base.event import EventSpec\n" - "\n" - "def typed(*args: Any) -> EventSpec: ...\n" - ), - ), ( str(web_dir / "utils" / "scripts.js"), ( @@ -882,6 +866,7 @@ def test_compile_script_modules( assert package_imports == { "canvas-confetti": [rx.ImportVar(tag=None, render=False)], "dayjs": [rx.ImportVar(tag=None, render=False)], + TYPESCRIPT_PACKAGE: [rx.ImportVar(tag=None, render=False)], } @@ -902,3 +887,81 @@ def test_compile_script_modules_without_modules( [(str(tmp_path / "utils" / "scripts.js"), "export {};\n")], {}, ) + + +def test_compile_script_stubs( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + clean_registration_context: RegistrationContext, +): + """Stubs are typed from the read signatures, and kept while scripts are unchanged. + + Args: + tmp_path: pytest tmp_path fixture. + monkeypatch: pytest monkeypatch fixture. + clean_registration_context: a fresh registry of imported modules. + """ + party = tmp_path / "party.js" + party.write_text("export function go(n) {}\n") + clean_registration_context.script_modules["app.party"] = party + exports = [ + { + "name": "go", + "signatures": [ + { + "parameters": [ + { + "name": "n", + "type": "number", + "optional": False, + "rest": False, + } + ] + } + ], + } + ] + reads: list[list[Path]] = [] + + def read(paths): + reads.append(list(paths)) + return {path.resolve(): exports for path in paths} + + monkeypatch.setattr(utils, "_read_script_signatures", read) + digest = module_digest(party) + typed = render_stub(party, digest, exports) # pyright: ignore[reportArgumentType] + + assert utils.compile_script_stubs() == [(str(tmp_path / "party.pyi"), typed)] + (tmp_path / "party.pyi").write_text(typed) + # Unchanged scripts keep their stub without reading the types again. + assert utils.compile_script_stubs() == [] + assert reads == [[party]] + + (tmp_path / "helpers.js").write_text("export const x = 1;\n") + new_digest = module_digest(party) + assert utils.compile_script_stubs() == [ + (str(tmp_path / "party.pyi"), render_stub(party, new_digest, exports)) # pyright: ignore[reportArgumentType] + ] + + +def test_compile_script_stubs_falls_back_to_untyped( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + clean_registration_context: RegistrationContext, +): + """When the types cannot be read the stub is untyped, and retried next time. + + Args: + tmp_path: pytest tmp_path fixture. + monkeypatch: pytest monkeypatch fixture. + clean_registration_context: a fresh registry of imported modules. + """ + party = tmp_path / "party.js" + party.write_text("export function go(n) {}\n") + clean_registration_context.script_modules["app.party"] = party + monkeypatch.setattr(utils, "_read_script_signatures", lambda paths: None) + untyped = render_untyped_stub(party, "untyped", ["go"]) + + assert utils.compile_script_stubs() == [(str(tmp_path / "party.pyi"), untyped)] + (tmp_path / "party.pyi").write_text(untyped) + assert utils.compile_script_stubs() == [(str(tmp_path / "party.pyi"), untyped)] diff --git a/tests/units/reflex_base/js/test_modules.py b/tests/units/reflex_base/js/test_modules.py index 51ad9362c16..5e9e86de850 100644 --- a/tests/units/reflex_base/js/test_modules.py +++ b/tests/units/reflex_base/js/test_modules.py @@ -13,7 +13,6 @@ find_exports, find_package_imports, module_key, - render_stub, ) from reflex_base.registry import RegistrationContext from reflex_base.vars.base import LiteralVar, Var @@ -102,17 +101,6 @@ def test_var_arguments_are_compiled_into_the_event(): ) -def test_render_stub_skips_names_python_cannot_import(): - assert render_stub(Path("party.js"), ["celebrate", "$private", "class"]) == ( - "# Generated by Reflex from party.js; rewritten when it changes.\n" - "from typing import Any\n" - "\n" - "from reflex_base.event import EventSpec\n" - "\n" - "def celebrate(*args: Any) -> EventSpec: ...\n" - ) - - @pytest.fixture def script_package( tmp_path: Path, clean_registration_context: RegistrationContext diff --git a/tests/units/reflex_base/js/test_stubs.py b/tests/units/reflex_base/js/test_stubs.py new file mode 100644 index 00000000000..8cc450439d7 --- /dev/null +++ b/tests/units/reflex_base/js/test_stubs.py @@ -0,0 +1,174 @@ +"""Tests for the type stubs of JavaScript modules imported from Python.""" + +import json +from pathlib import Path + +import pytest +from reflex_base.js.stubs import ( + TYPESCRIPT_PACKAGE, + Export, + module_digest, + python_type, + render_stub, + render_untyped_stub, + stub_header, +) + +FRONTEND_PACKAGE_JSON = ( + Path(__file__).parents[4] / "packages/reflex-frontend/package.json" +) + +IMPORTS = ( + "from collections.abc import Mapping, Sequence\n" + "from typing import Any, overload\n" + "\n" + "from reflex_base.event import EventCallback, EventSpec\n" + "from reflex_base.vars.base import Var\n" +) + + +@pytest.mark.parametrize( + ("ts_type", "expected"), + [ + ("number", "float"), + ("bigint", "int"), + ("string", "str"), + ("boolean", "bool"), + ("true", "bool"), + ("null", "None"), + ("undefined", "None"), + ("void", "None"), + ("any", "Any"), + ("unknown", "Any"), + ("never", "Any"), + ("object", "Mapping[str, Any]"), + ("{ a: number; }", "Mapping[str, Any]"), + ("Record", "Mapping[str, Any]"), + ("string | null", "str | None"), + ("string | number | string", "str | float"), + ("string | HTMLElement", "Any"), + ('"a" | "b"', "str"), + ("1 | 2", "float"), + ("number[]", "Sequence[float]"), + ("readonly string[]", "Sequence[str]"), + ("(string | null)[]", "Sequence[str | None]"), + ("Array", "Sequence[bool]"), + ("Set", "Sequence[float]"), + ("Promise", "str"), + ("[number, string]", "Sequence[Any]"), + ("(a: number) => void", "Any"), + ("HTMLElement", "Any"), + ("Options", "Any"), + ], +) +def test_python_type(ts_type: str, expected: str): + assert python_type(ts_type) == expected + + +def test_render_stub(): + exports: list[Export] = [ + { + "name": "celebrate", + "signatures": [ + { + "parameters": [ + { + "name": "count", + "type": "number", + "optional": False, + "rest": False, + }, + { + "name": "elementId", + "type": "string", + "optional": False, + "rest": False, + }, + { + "name": "loud", + "type": "boolean | undefined", + "optional": True, + "rest": False, + }, + ] + } + ], + }, + { + "name": "many", + "signatures": [ + { + "parameters": [ + { + "name": "class", + "type": "any", + "optional": False, + "rest": False, + }, + { + "name": "names", + "type": "string", + "optional": False, + "rest": True, + }, + ] + } + ], + }, + { + "name": "pick", + "signatures": [ + { + "parameters": [ + { + "name": "n", + "type": "number", + "optional": False, + "rest": False, + } + ] + }, + {"parameters": []}, + ], + }, + {"name": "MAX", "signatures": []}, + {"name": "$private", "signatures": [{"parameters": []}]}, + ] + assert render_stub(Path("party.js"), "abc", exports) == ( + stub_header(Path("party.js"), "abc") + "\n" + IMPORTS + "\n" + "def celebrate(count: float | Var[float], " + "elementId: str | Var[str] | EventCallback[*tuple[Any, ...]], " + "loud: bool | Var[bool] = ..., /) -> EventSpec: ...\n" + "def many(arg0: Any, /, *names: str | Var[str] | EventCallback[*tuple[Any, ...]]) -> EventSpec: ...\n" + "@overload\n" + "def pick(n: float | Var[float], /) -> EventSpec: ...\n" + "@overload\n" + "def pick() -> EventSpec: ...\n" + ) + + +def test_render_untyped_stub(): + assert render_untyped_stub(Path("party.ts"), "untyped", ["go", "class"]) == ( + "# Generated by Reflex from party.ts (untyped); rewritten when it changes.\n" + + IMPORTS + + "\n" + "def go(*args: Any) -> EventSpec: ...\n" + ) + + +def test_module_digest_covers_the_scripts_beside_the_module(tmp_path: Path): + module = tmp_path / "party.js" + module.write_text("export function go() {}\n") + helper = tmp_path / "helpers.ts" + helper.write_text("export type T = number;\n") + digest = module_digest(module) + assert len(digest) == 16 + (tmp_path / "notes.txt").write_text("not a script") + assert module_digest(module) == digest + helper.write_text("export type T = string;\n") + assert module_digest(module) != digest + + +def test_typescript_matches_the_frontend_package(): + dev_dependencies = json.loads(FRONTEND_PACKAGE_JSON.read_text())["devDependencies"] + assert f"typescript@{dev_dependencies['typescript']}" == TYPESCRIPT_PACKAGE From 478796aae314ca8ec4b2618bc612fcafc948637b Mon Sep 17 00:00:00 2001 From: Farhan Date: Fri, 20 Nov 2026 21:40:45 +0000 Subject: [PATCH 02/16] Stub review fixes: name collisions, trailing defaults, untyped exports, cache key - A parameter renamed from a non-identifier (`$value` -> `arg0`) no longer takes the name of another parameter, which made the stub invalid Python. - Only trailing optional parameters get defaults: in `f(prefix = "", count)` Python cannot omit `prefix`, so both are required. - A tuple rest parameter (`...args: [number, string]`) has no single element type and becomes `*args: Any` instead of `*args: Sequence[Any]`, which rejected the valid call. - An export of unknown type (`any`, e.g. re-exported from a package without declarations) keeps an untyped def instead of disappearing from the stub. - The stub digest covers the local files the module imports (as copied by the compiler) and the app's package.json, so a package upgrade re-reads the types; paths are hashed relative to the module, so the header is the same on every machine. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- .../reflex-base/src/reflex_base/js/stubs.py | 65 +++++-- .../reflex-frontend/src/script-signatures.js | 35 ++-- .../tests/fixtures/signatures/jsdoc.js | 3 + .../tests/fixtures/signatures/typed.ts | 4 + .../tests/script_signatures.test.js | 26 ++- reflex/compiler/utils.py | 11 +- .../tests_playwright/test_call_script.py | 3 +- tests/units/compiler/test_compiler_utils.py | 15 +- tests/units/reflex_base/js/test_modules.py | 6 +- tests/units/reflex_base/js/test_stubs.py | 178 ++++++++++-------- 10 files changed, 228 insertions(+), 118 deletions(-) diff --git a/packages/reflex-base/src/reflex_base/js/stubs.py b/packages/reflex-base/src/reflex_base/js/stubs.py index 57341dec149..2397e33c90c 100644 --- a/packages/reflex-base/src/reflex_base/js/stubs.py +++ b/packages/reflex-base/src/reflex_base/js/stubs.py @@ -11,12 +11,13 @@ import hashlib import keyword +import os import re from collections.abc import Iterable, Mapping, Sequence from pathlib import Path from typing import TypedDict -from reflex_base.js.finder import SCRIPT_EXTENSIONS +from reflex_base.js.source import module_files # Bumped when the stub format changes, so every stub is rewritten. _STUB_VERSION = "1" @@ -78,24 +79,32 @@ class Export(TypedDict): name: str signatures: list[Signature] + # Whether its type is unknown (`any`), so it may still be a function. + untyped: bool -def module_digest(path: Path) -> str: - """Hash a module and the script files beside it, which its types may use. +def module_digest(path: Path, dependencies: bytes = b"") -> str: + """Hash what a module's stub is made from. + + That is the module and the local files it imports, whose types it may use, + and the installed packages, whose declarations it may use too. Args: path: The module. + dependencies: The app's package manifest, so an upgrade rewrites the stub. Returns: A short hex digest. """ digest = hashlib.sha256(_STUB_VERSION.encode()) - for file in sorted(path.parent.iterdir()): - if file.suffix in SCRIPT_EXTENSIONS: - digest.update(file.name.encode()) - digest.update(b"\0") - digest.update(file.read_bytes()) - digest.update(b"\0") + directory = path.resolve().parent + for file in module_files(path): + # Relative, so the same sources give the same stub on every machine. + digest.update(os.path.relpath(file, directory).encode()) + digest.update(b"\0") + digest.update(file.read_bytes()) + digest.update(b"\0") + digest.update(dependencies) return digest.hexdigest()[:16] @@ -213,17 +222,35 @@ def _render_signature(name: str, signature: Signature) -> str: Returns: The ``def`` line. """ + parameters = signature["parameters"] + rest_index = next( + (index for index, parameter in enumerate(parameters) if parameter["rest"]), + len(parameters), + ) + # Python can only omit trailing arguments: a parameter with a default that a + # required one follows is required. + omittable = rest_index + while omittable > 0 and parameters[omittable - 1]["optional"]: + omittable -= 1 + # Rename the parameters that are not Python identifiers to names no other + # parameter has; arguments are positional-only, so callers never see them. + used = { + parameter["name"] + for parameter in parameters + if parameter["name"].isidentifier() and not keyword.iskeyword(parameter["name"]) + } params: list[str] = [] rest = "" - optional = False - for index, parameter in enumerate(signature["parameters"]): + for index, parameter in enumerate(parameters[: rest_index + 1]): param_name = parameter["name"] - if not param_name.isidentifier() or keyword.iskeyword(param_name): + if param_name not in used: param_name = f"arg{index}" + while param_name in used: + param_name += "_" + used.add(param_name) if parameter["rest"]: rest = f"*{param_name}: {_annotation(parameter['type'])}" break - optional = optional or parameter["optional"] ts_type = parameter["type"] if parameter["optional"]: # The checker adds `undefined` to an optional parameter's type. @@ -236,7 +263,8 @@ def _render_signature(name: str, signature: Signature) -> str: or "undefined" ) params.append( - f"{param_name}: {_annotation(ts_type)}" + (" = ..." if optional else "") + f"{param_name}: {_annotation(ts_type)}" + + (" = ..." if index >= omittable else "") ) rendered = [*params, "/"] if params else [] if rest: @@ -260,7 +288,8 @@ def render_stub(path: Path, digest: str, exports: Iterable[Export]) -> str: """Render the stub of a module from its exports' signatures. Exports that are not functions, and those Python cannot import, are left - out. An export with several signatures gets one overload each. + out; an export of unknown type keeps untyped arguments. An export with + several signatures gets one overload each. Args: path: The module. @@ -273,7 +302,11 @@ def render_stub(path: Path, digest: str, exports: Iterable[Export]) -> str: lines = [stub_header(path, digest), _IMPORTS] for export in exports: signatures = export["signatures"] - if not signatures or not _importable(export["name"]): + if not _importable(export["name"]): + continue + if not signatures: + if export["untyped"]: + lines.append(f"def {export['name']}(*args: Any) -> EventSpec: ...") continue for signature in signatures: if len(signatures) > 1: diff --git a/packages/reflex-frontend/src/script-signatures.js b/packages/reflex-frontend/src/script-signatures.js index fe9b7555282..f1fdc8b4de2 100644 --- a/packages/reflex-frontend/src/script-signatures.js +++ b/packages/reflex-frontend/src/script-signatures.js @@ -45,13 +45,19 @@ const checker = program.getTypeChecker(); const describeParameter = (parameter, location) => { const declaration = parameter.valueDeclaration; const rest = Boolean(declaration?.dotDotDotToken); - let type = checker.getTypeOfSymbolAtLocation(parameter, location); - if (rest && checker.isArrayType(type)) { - type = checker.getTypeArguments(/** @type {any} */ (type))[0]; + const type = checker.getTypeOfSymbolAtLocation(parameter, location); + let typeName = checker.typeToString(type); + if (rest) { + // A rest parameter's element type; a tuple's elements have no single type. + typeName = checker.isArrayType(type) + ? checker.typeToString( + checker.getTypeArguments(/** @type {any} */ (type))[0], + ) + : "any"; } return { name: parameter.getName(), - type: checker.typeToString(type), + type: typeName, optional: Boolean( declaration && (declaration.questionToken || @@ -62,23 +68,28 @@ const describeParameter = (parameter, location) => { }; }; -/** @type {Record} */ +/** @type {Record} */ const result = {}; for (const file of files) { const source = program.getSourceFile(file); const moduleSymbol = source && checker.getSymbolAtLocation(source); result[file] = (moduleSymbol ? checker.getExportsOfModule(moduleSymbol) : []) .filter((symbol) => symbol.getName() !== "default") - .map((symbol) => ({ - name: symbol.getName(), - signatures: checker - .getTypeOfSymbolAtLocation(symbol, source) - .getCallSignatures() - .map((signature) => ({ + .map((symbol) => { + const type = checker.getTypeOfSymbolAtLocation(symbol, source); + return { + name: symbol.getName(), + signatures: type.getCallSignatures().map((signature) => ({ parameters: signature .getParameters() .map((parameter) => describeParameter(parameter, source)), })), - })); + // An export of unknown type, such as one from a package without + // declarations, may still be a function. + untyped: Boolean( + type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown), + ), + }; + }); } process.stdout.write(JSON.stringify(result)); diff --git a/packages/reflex-frontend/tests/fixtures/signatures/jsdoc.js b/packages/reflex-frontend/tests/fixtures/signatures/jsdoc.js index 9250f94234e..383f2d4ff29 100644 --- a/packages/reflex-frontend/tests/fixtures/signatures/jsdoc.js +++ b/packages/reflex-frontend/tests/fixtures/signatures/jsdoc.js @@ -13,3 +13,6 @@ export const untyped = (a, b) => a + b; export const notAFunction = 3; export default function () {} + +/** @type {any} */ +export const anything = globalThis.somethingUntyped; diff --git a/packages/reflex-frontend/tests/fixtures/signatures/typed.ts b/packages/reflex-frontend/tests/fixtures/signatures/typed.ts index 96967c8b602..397cdefdf06 100644 --- a/packages/reflex-frontend/tests/fixtures/signatures/typed.ts +++ b/packages/reflex-frontend/tests/fixtures/signatures/typed.ts @@ -3,3 +3,7 @@ export function pick(mode: "a" | "b", maybe: string | null): void {} export function overloaded(n: number): void; export function overloaded(): void; export function overloaded(n?: number): void {} + +export function tupleRest(...args: [number, string]): void {} + +export function defaultFirst(prefix = "", count: number): void {} diff --git a/packages/reflex-frontend/tests/script_signatures.test.js b/packages/reflex-frontend/tests/script_signatures.test.js index 884db83be7a..30d9b5e6bfd 100644 --- a/packages/reflex-frontend/tests/script_signatures.test.js +++ b/packages/reflex-frontend/tests/script_signatures.test.js @@ -42,16 +42,20 @@ test("reads JSDoc types, optional and rest parameters", () => { ], }, ], + untyped: false, }, { name: "many", signatures: [{ parameters: [param("names", "string", false, true)] }], + untyped: false, }, { name: "untyped", signatures: [{ parameters: [param("a", "any"), param("b", "any")] }], + untyped: false, }, - { name: "notAFunction", signatures: [] }, + { name: "notAFunction", signatures: [], untyped: false }, + { name: "anything", signatures: [], untyped: true }, ], }); }); @@ -71,10 +75,30 @@ test("reads TypeScript types and overloads, several files at once", () => { ], }, ], + untyped: false, }, { name: "overloaded", signatures: [{ parameters: [param("n", "number")] }, { parameters: [] }], + untyped: false, + }, + { + // A tuple rest has no single element type. + name: "tupleRest", + signatures: [{ parameters: [param("args", "any", false, true)] }], + untyped: false, + }, + { + name: "defaultFirst", + signatures: [ + { + parameters: [ + param("prefix", "string", true), + param("count", "number"), + ], + }, + ], + untyped: false, }, ]); }); diff --git a/reflex/compiler/utils.py b/reflex/compiler/utils.py index c600b6007a1..ff6bbe9b01b 100644 --- a/reflex/compiler/utils.py +++ b/reflex/compiler/utils.py @@ -411,16 +411,21 @@ def compile_script_stubs() -> list[tuple[str, str]]: """Write a type stub next to each JavaScript module the app imports. Argument types come from the module's TypeScript annotations or JSDoc. A - stub whose header records the current module and its sibling files is - kept, so typescript only runs when a script changed. When the types cannot + stub whose header records the current module, the local files it imports + and the app's packages is kept, so typescript only runs when one changed. When the types cannot be read, the stub has untyped arguments and is retried on the next compile. Returns: The (path, code) outputs for the stubs to rewrite. """ stale: dict[Path, str] = {} + try: + # A package upgrade can change the types a module uses. + dependencies = (get_web_dir() / constants.PackageJson.PATH).read_bytes() + except OSError: + dependencies = b"" for path in RegistrationContext.ensure_context().script_modules.values(): - digest = module_digest(path) + digest = module_digest(path, dependencies) try: current = path.with_suffix(".pyi").read_text(encoding="utf-8") except OSError: diff --git a/tests/integration/tests_playwright/test_call_script.py b/tests/integration/tests_playwright/test_call_script.py index dc60788e5e6..0e581d357ae 100644 --- a/tests/integration/tests_playwright/test_call_script.py +++ b/tests/integration/tests_playwright/test_call_script.py @@ -646,9 +646,10 @@ def test_js_module_stub(call_script: AppHarness): from reflex_base.js.stubs import module_digest, stub_header module = call_script.app_path / call_script.app_name / "page_script.js" + package_json = (call_script.app_path / ".web" / "package.json").read_bytes() handler = "str | Var[str] | EventCallback[*tuple[Any, ...]]" assert (module.with_suffix(".pyi")).read_text() == ( - stub_header(module, module_digest(module)) + "\n" + stub_header(module, module_digest(module, package_json)) + "\n" "from collections.abc import Mapping, Sequence\n" "from typing import Any, overload\n" "\n" diff --git a/tests/units/compiler/test_compiler_utils.py b/tests/units/compiler/test_compiler_utils.py index 9c95a9bd593..a510f7bfd87 100644 --- a/tests/units/compiler/test_compiler_utils.py +++ b/tests/units/compiler/test_compiler_utils.py @@ -935,13 +935,18 @@ def test_compile_script_stubs( monkeypatch: pytest.MonkeyPatch, clean_registration_context: RegistrationContext, ): - """Stubs are typed from the read signatures, and kept while scripts are unchanged. + """Stubs are typed from the read signatures, and kept while nothing changed. Args: tmp_path: pytest tmp_path fixture. monkeypatch: pytest monkeypatch fixture. clean_registration_context: a fresh registry of imported modules. """ + web_dir = tmp_path / ".web" + web_dir.mkdir() + package_json = web_dir / "package.json" + package_json.write_text('{"dependencies": {"a": "1"}}') + monkeypatch.setattr(utils, "get_web_dir", lambda: web_dir) party = tmp_path / "party.js" party.write_text("export function go(n) {}\n") clean_registration_context.script_modules["app.party"] = party @@ -960,6 +965,7 @@ def test_compile_script_stubs( ] } ], + "untyped": False, } ] reads: list[list[Path]] = [] @@ -969,7 +975,7 @@ def read(paths): return {path.resolve(): exports for path in paths} monkeypatch.setattr(utils, "_read_script_signatures", read) - digest = module_digest(party) + digest = module_digest(party, package_json.read_bytes()) typed = render_stub(party, digest, exports) # pyright: ignore[reportArgumentType] assert utils.compile_script_stubs() == [(str(tmp_path / "party.pyi"), typed)] @@ -978,8 +984,9 @@ def read(paths): assert utils.compile_script_stubs() == [] assert reads == [[party]] - (tmp_path / "helpers.js").write_text("export const x = 1;\n") - new_digest = module_digest(party) + # A package upgrade can change the types: the stub is read again. + package_json.write_text('{"dependencies": {"a": "2"}}') + new_digest = module_digest(party, package_json.read_bytes()) assert utils.compile_script_stubs() == [ (str(tmp_path / "party.pyi"), render_stub(party, new_digest, exports)) # pyright: ignore[reportArgumentType] ] diff --git a/tests/units/reflex_base/js/test_modules.py b/tests/units/reflex_base/js/test_modules.py index 1a66d427363..bddb4399c5f 100644 --- a/tests/units/reflex_base/js/test_modules.py +++ b/tests/units/reflex_base/js/test_modules.py @@ -9,11 +9,7 @@ import pytest from reflex_base.event import EventSpec from reflex_base.js.finder import ScriptFinder -from reflex_base.js.modules import ( - JsFunction, - find_package_imports, - module_key, -) +from reflex_base.js.modules import JsFunction, find_package_imports, module_key from reflex_base.js.source import find_exports from reflex_base.registry import RegistrationContext from reflex_base.vars.base import LiteralVar, Var diff --git a/tests/units/reflex_base/js/test_stubs.py b/tests/units/reflex_base/js/test_stubs.py index 8cc450439d7..d92a99a0fa6 100644 --- a/tests/units/reflex_base/js/test_stubs.py +++ b/tests/units/reflex_base/js/test_stubs.py @@ -7,6 +7,7 @@ from reflex_base.js.stubs import ( TYPESCRIPT_PACKAGE, Export, + Parameter, module_digest, python_type, render_stub, @@ -62,92 +63,95 @@ ], ) def test_python_type(ts_type: str, expected: str): + """A TypeScript type maps to the Python type of the JSON value. + + Args: + ts_type: The TypeScript type. + expected: The Python type. + """ assert python_type(ts_type) == expected +def _param( + name: str, ts_type: str, optional: bool = False, rest: bool = False +) -> Parameter: + return {"name": name, "type": ts_type, "optional": optional, "rest": rest} + + +def _export(name: str, *signatures: list[Parameter], untyped: bool = False) -> Export: + return { + "name": name, + "signatures": [{"parameters": parameters} for parameters in signatures], + "untyped": untyped, + } + + +HANDLER = "str | Var[str] | EventCallback[*tuple[Any, ...]]" + + def test_render_stub(): - exports: list[Export] = [ - { - "name": "celebrate", - "signatures": [ - { - "parameters": [ - { - "name": "count", - "type": "number", - "optional": False, - "rest": False, - }, - { - "name": "elementId", - "type": "string", - "optional": False, - "rest": False, - }, - { - "name": "loud", - "type": "boolean | undefined", - "optional": True, - "rest": False, - }, - ] - } - ], - }, - { - "name": "many", - "signatures": [ - { - "parameters": [ - { - "name": "class", - "type": "any", - "optional": False, - "rest": False, - }, - { - "name": "names", - "type": "string", - "optional": False, - "rest": True, - }, - ] - } - ], - }, - { - "name": "pick", - "signatures": [ - { - "parameters": [ - { - "name": "n", - "type": "number", - "optional": False, - "rest": False, - } - ] - }, - {"parameters": []}, + """Each export becomes a positional-only def with Var-accepting arguments.""" + exports = [ + _export( + "celebrate", + [ + _param("count", "number"), + _param("elementId", "string"), + _param("loud", "boolean | undefined", optional=True), ], - }, - {"name": "MAX", "signatures": []}, - {"name": "$private", "signatures": [{"parameters": []}]}, + ), + _export("many", [_param("class", "any"), _param("names", "string", rest=True)]), + _export("pick", [_param("n", "number")], []), + _export("MAX"), + _export("anything", untyped=True), + _export("$private", []), ] assert render_stub(Path("party.js"), "abc", exports) == ( stub_header(Path("party.js"), "abc") + "\n" + IMPORTS + "\n" "def celebrate(count: float | Var[float], " - "elementId: str | Var[str] | EventCallback[*tuple[Any, ...]], " - "loud: bool | Var[bool] = ..., /) -> EventSpec: ...\n" - "def many(arg0: Any, /, *names: str | Var[str] | EventCallback[*tuple[Any, ...]]) -> EventSpec: ...\n" + f"elementId: {HANDLER}, loud: bool | Var[bool] = ..., /) -> EventSpec: ...\n" + f"def many(arg0: Any, /, *names: {HANDLER}) -> EventSpec: ...\n" "@overload\n" "def pick(n: float | Var[float], /) -> EventSpec: ...\n" "@overload\n" "def pick() -> EventSpec: ...\n" + "def anything(*args: Any) -> EventSpec: ...\n" + ) + + +def test_renamed_parameters_do_not_collide(): + """A parameter renamed from a non-identifier never takes another's name.""" + exports = [ + _export( + "send", + [_param("$value", "any"), _param("arg0", "any"), _param("arg0_", "any")], + ) + ] + assert render_stub(Path("send.js"), "abc", exports).splitlines()[-1] == ( + "def send(arg0__: Any, arg0: Any, arg0_: Any, /) -> EventSpec: ..." + ) + + +def test_only_trailing_optional_parameters_have_defaults(): + """A default that a required parameter follows cannot be omitted in Python.""" + exports = [ + _export( + "send", + [ + _param("prefix", "string", optional=True), + _param("count", "number"), + _param("suffix", "string | undefined", optional=True), + ], + ) + ] + assert render_stub(Path("send.ts"), "abc", exports).splitlines()[-1] == ( + f"def send(prefix: {HANDLER}, count: float | Var[float], " + f"suffix: {HANDLER} = ..., /) -> EventSpec: ..." ) def test_render_untyped_stub(): + """Without types, every export takes any arguments.""" assert render_untyped_stub(Path("party.ts"), "untyped", ["go", "class"]) == ( "# Generated by Reflex from party.ts (untyped); rewritten when it changes.\n" + IMPORTS @@ -156,19 +160,41 @@ def test_render_untyped_stub(): ) -def test_module_digest_covers_the_scripts_beside_the_module(tmp_path: Path): +def test_module_digest_covers_imports_and_packages(tmp_path: Path): + """The digest changes with the module's local imports and the app's packages. + + Args: + tmp_path: pytest tmp_path fixture. + """ + (tmp_path / "lib").mkdir() module = tmp_path / "party.js" - module.write_text("export function go() {}\n") - helper = tmp_path / "helpers.ts" + module.write_text('import { T } from "./lib/helpers";\nexport function go() {}\n') + helper = tmp_path / "lib" / "helpers.ts" helper.write_text("export type T = number;\n") - digest = module_digest(module) + digest = module_digest(module, b'{"a": "1"}') assert len(digest) == 16 - (tmp_path / "notes.txt").write_text("not a script") - assert module_digest(module) == digest + (tmp_path / "unused.js").write_text("export const u = 1;\n") + assert module_digest(module, b'{"a": "1"}') == digest + assert module_digest(module, b'{"a": "2"}') != digest helper.write_text("export type T = string;\n") - assert module_digest(module) != digest + assert module_digest(module, b'{"a": "1"}') != digest + + +def test_module_digest_is_the_same_on_every_machine(tmp_path: Path): + """The same sources in different directories give the same digest. + + Args: + tmp_path: pytest tmp_path fixture. + """ + for checkout in ("one", "two"): + (tmp_path / checkout).mkdir() + (tmp_path / checkout / "party.js").write_text("export function go() {}\n") + assert module_digest(tmp_path / "one" / "party.js") == module_digest( + tmp_path / "two" / "party.js" + ) def test_typescript_matches_the_frontend_package(): + """The typescript installed to read types is the one reflex-frontend uses.""" dev_dependencies = json.loads(FRONTEND_PACKAGE_JSON.read_text())["devDependencies"] assert f"typescript@{dev_dependencies['typescript']}" == TYPESCRIPT_PACKAGE From 770af5e850af2953ecf3a35f447b407c44e242f3 Mon Sep 17 00:00:00 2001 From: Farhan Date: Fri, 20 Nov 2026 22:09:37 +0000 Subject: [PATCH 03/16] Alias the stub's type names; key stubs on the types a module reads Review fixes: - The stub imports the types it uses under private aliases (`_str`, `_Var`, `_Sequence`, ...), so an export named `str`, `Var` or `Sequence` no longer replaces the type its annotations name; parameters keep their own names. An export named like one of the aliases is left out of the stub. Checked with pyright: a stub exporting `str`, `Var` and `any` type-checks, and calls are checked against it. - The stub digest, through module_files, also covers the files a module takes types from: `.d.ts` files an import resolves to, JSDoc `import("./types")` and `/// `. Editing them rewrites the stub. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- .../reflex-base/src/reflex_base/js/source.py | 47 +++++++++-- .../reflex-base/src/reflex_base/js/stubs.py | 54 ++++++++++--- reflex/compiler/utils.py | 4 +- .../tests_playwright/test_call_script.py | 16 ++-- tests/units/reflex_base/js/test_stubs.py | 77 +++++++++++++++---- 5 files changed, 154 insertions(+), 44 deletions(-) diff --git a/packages/reflex-base/src/reflex_base/js/source.py b/packages/reflex-base/src/reflex_base/js/source.py index d2ee6a39420..90bbdacbc1f 100644 --- a/packages/reflex-base/src/reflex_base/js/source.py +++ b/packages/reflex-base/src/reflex_base/js/source.py @@ -17,12 +17,17 @@ # Stylesheets, whose `@import` and `url(...)` references are followed. STYLESHEET_EXTENSION = ".css" # Tried in order for an import without an extension, as the bundler does. -_RESOLVE_EXTENSIONS = (".ts", ".tsx", ".js", ".jsx", ".mjs") +_RESOLVE_EXTENSIONS = (".ts", ".tsx", ".d.ts", ".js", ".jsx", ".mjs") _CSS_COMMENT_RE = re.compile(r"/\*.*?\*/", re.DOTALL) _CSS_REFERENCE_RE = re.compile( r"""@import\s+(?:url\(\s*)?["']?([^"')\s;]+)|url\(\s*["']?([^"')\s]+)["']?\s*\)""" ) +# Types a module uses from files it does not import: JSDoc `import("./types")` +# and `/// `, both inside comments. +_TYPE_REFERENCE_RE = re.compile( + r"""\bimport\(\s*["'](\.[^"']+)["']\s*\)|///\s*~^") @@ -543,6 +548,27 @@ def find_stylesheet_references(source: str) -> list[str]: ) +def find_type_references(source: str) -> list[str]: + """Find the local files a module reads types from without importing them. + + These are JSDoc ``import("./types")`` and triple-slash references, which + sit in comments and so are not imports, but change the module's types. + + Args: + source: The module source. + + Returns: + The relative references, without duplicates. + """ + return list( + dict.fromkeys( + jsdoc or reference + for jsdoc, reference in _TYPE_REFERENCE_RE.findall(source) + if (jsdoc or reference).startswith(".") + ) + ) + + def strip_query(specifier: str) -> str: """Remove the query and fragment of an import specifier. @@ -583,8 +609,10 @@ def _resolve_local(directory: Path, specifier: str) -> Path | None: def module_files(path: Path) -> list[Path]: """Find a module and every local file it imports, directly or not. - Scripts' relative imports are followed, and so are the ``@import`` and - ``url(...)`` references of the stylesheets among them. + Scripts' relative imports are followed, with the files their types come + from (``.d.ts`` files, JSDoc ``import("./types")``, triple-slash + references), and so are the ``@import`` and ``url(...)`` references of the + stylesheets among them. Args: path: The module. @@ -597,10 +625,17 @@ def module_files(path: Path) -> list[Path]: while pending: file = pending.pop() if file.suffix in SCRIPT_SOURCE_EXTENSIONS: + source = file.read_text(encoding="utf-8") + specifiers = [ + *( + specifier + for specifier in find_imports(source) + if specifier.startswith(".") + ), + *find_type_references(source), + ] targets = [ - _resolve_local(file.parent, specifier) - for specifier in find_imports(file.read_text(encoding="utf-8")) - if specifier.startswith(".") + _resolve_local(file.parent, specifier) for specifier in specifiers ] elif file.suffix == STYLESHEET_EXTENSION: targets = [ diff --git a/packages/reflex-base/src/reflex_base/js/stubs.py b/packages/reflex-base/src/reflex_base/js/stubs.py index 2397e33c90c..55a65c6eba7 100644 --- a/packages/reflex-base/src/reflex_base/js/stubs.py +++ b/packages/reflex-base/src/reflex_base/js/stubs.py @@ -31,12 +31,35 @@ _HEADER = "# Generated by Reflex from {name} ({digest}); rewritten when it changes." +# The stub's names for the types it uses, private so that an export named +# `str` or `Var` cannot replace one. +_ALIASES = { + name: f"_{name}" + for name in ( + "Any", + "EventCallback", + "EventSpec", + "Mapping", + "Sequence", + "Var", + "bool", + "float", + "int", + "overload", + "str", + "tuple", + ) +} +_ALIAS_RE = re.compile(r"\b(" + "|".join(_ALIASES) + r")\b") + _IMPORTS = """\ -from collections.abc import Mapping, Sequence -from typing import Any, overload +from builtins import bool as _bool, float as _float, int as _int, str as _str +from builtins import tuple as _tuple +from collections.abc import Mapping as _Mapping, Sequence as _Sequence +from typing import Any as _Any, overload as _overload -from reflex_base.event import EventCallback, EventSpec -from reflex_base.vars.base import Var +from reflex_base.event import EventCallback as _EventCallback, EventSpec as _EventSpec +from reflex_base.vars.base import Var as _Var """ # TypeScript types with a Python counterpart, by their checker spelling. @@ -202,11 +225,13 @@ def _annotation(ts_type: str) -> str: """ value = python_type(ts_type) if value == "Any": - return "Any" + return _ALIASES["Any"] handler = ( " | EventCallback[*tuple[Any, ...]]" if "str" in value.split(" | ") else "" ) - return f"{value} | Var[{value}]{handler}" + return _ALIAS_RE.sub( + lambda match: _ALIASES[match.group(1)], f"{value} | Var[{value}]{handler}" + ) def _render_signature(name: str, signature: Signature) -> str: @@ -269,7 +294,7 @@ def _render_signature(name: str, signature: Signature) -> str: rendered = [*params, "/"] if params else [] if rest: rendered.append(rest) - return f"def {name}({', '.join(rendered)}) -> EventSpec: ..." + return f"def {name}({', '.join(rendered)}) -> _EventSpec: ..." def _importable(name: str) -> bool: @@ -279,9 +304,14 @@ def _importable(name: str) -> bool: name: The export name. Returns: - Whether it is an identifier and not a keyword. + Whether it is an identifier, not a keyword, and not one of the stub's + own names for the types it uses. """ - return name.isidentifier() and not keyword.iskeyword(name) + return ( + name.isidentifier() + and not keyword.iskeyword(name) + and name not in _ALIASES.values() + ) def render_stub(path: Path, digest: str, exports: Iterable[Export]) -> str: @@ -306,11 +336,11 @@ def render_stub(path: Path, digest: str, exports: Iterable[Export]) -> str: continue if not signatures: if export["untyped"]: - lines.append(f"def {export['name']}(*args: Any) -> EventSpec: ...") + lines.append(f"def {export['name']}(*args: _Any) -> _EventSpec: ...") continue for signature in signatures: if len(signatures) > 1: - lines.append("@overload") + lines.append("@_overload") lines.append(_render_signature(export["name"], signature)) return "\n".join(lines) + "\n" @@ -328,7 +358,7 @@ def render_untyped_stub(path: Path, digest: str, names: Sequence[str]) -> str: """ lines = [stub_header(path, digest), _IMPORTS] lines.extend( - f"def {name}(*args: Any) -> EventSpec: ..." + f"def {name}(*args: _Any) -> _EventSpec: ..." for name in names if _importable(name) ) diff --git a/reflex/compiler/utils.py b/reflex/compiler/utils.py index 2b1b55df06a..489c972b7dc 100644 --- a/reflex/compiler/utils.py +++ b/reflex/compiler/utils.py @@ -323,7 +323,7 @@ def compile_script_modules() -> tuple[ the source tree. ``utils/scripts.js`` re-exports each module under its module key. - Returns: + Returns: <<<<<<< HEAD The (path, code) outputs, and the npm packages to install: those the modules import, and typescript, which reads their types for the stubs. @@ -333,7 +333,7 @@ def compile_script_modules() -> tuple[ reference, such as stylesheets and images, which may be binary. >>>>>>> farhan/focused-darwin-dx76ek-js-modules - Raises: + Raises: ReflexRuntimeError: If a module imports a file outside its top-level package's directory. """ diff --git a/tests/integration/tests_playwright/test_call_script.py b/tests/integration/tests_playwright/test_call_script.py index 0e581d357ae..0909fd821f3 100644 --- a/tests/integration/tests_playwright/test_call_script.py +++ b/tests/integration/tests_playwright/test_call_script.py @@ -647,15 +647,17 @@ def test_js_module_stub(call_script: AppHarness): module = call_script.app_path / call_script.app_name / "page_script.js" package_json = (call_script.app_path / ".web" / "package.json").read_bytes() - handler = "str | Var[str] | EventCallback[*tuple[Any, ...]]" + handler = "_str | _Var[_str] | _EventCallback[*_tuple[_Any, ...]]" assert (module.with_suffix(".pyi")).read_text() == ( stub_header(module, module_digest(module, package_json)) + "\n" - "from collections.abc import Mapping, Sequence\n" - "from typing import Any, overload\n" + "from builtins import bool as _bool, float as _float, int as _int, str as _str\n" + "from builtins import tuple as _tuple\n" + "from collections.abc import Mapping as _Mapping, Sequence as _Sequence\n" + "from typing import Any as _Any, overload as _overload\n" "\n" - "from reflex_base.event import EventCallback, EventSpec\n" - "from reflex_base.vars.base import Var\n" + "from reflex_base.event import EventCallback as _EventCallback, EventSpec as _EventSpec\n" + "from reflex_base.vars.base import Var as _Var\n" "\n" - f"def setText(id: {handler}, text: {handler}, /) -> EventSpec: ...\n" - f"def report(handler: {handler}, value: {handler}, /) -> EventSpec: ...\n" + f"def setText(id: {handler}, text: {handler}, /) -> _EventSpec: ...\n" + f"def report(handler: {handler}, value: {handler}, /) -> _EventSpec: ...\n" ) diff --git a/tests/units/reflex_base/js/test_stubs.py b/tests/units/reflex_base/js/test_stubs.py index d92a99a0fa6..771a78ad7f6 100644 --- a/tests/units/reflex_base/js/test_stubs.py +++ b/tests/units/reflex_base/js/test_stubs.py @@ -20,11 +20,13 @@ ) IMPORTS = ( - "from collections.abc import Mapping, Sequence\n" - "from typing import Any, overload\n" + "from builtins import bool as _bool, float as _float, int as _int, str as _str\n" + "from builtins import tuple as _tuple\n" + "from collections.abc import Mapping as _Mapping, Sequence as _Sequence\n" + "from typing import Any as _Any, overload as _overload\n" "\n" - "from reflex_base.event import EventCallback, EventSpec\n" - "from reflex_base.vars.base import Var\n" + "from reflex_base.event import EventCallback as _EventCallback, EventSpec as _EventSpec\n" + "from reflex_base.vars.base import Var as _Var\n" ) @@ -86,7 +88,7 @@ def _export(name: str, *signatures: list[Parameter], untyped: bool = False) -> E } -HANDLER = "str | Var[str] | EventCallback[*tuple[Any, ...]]" +HANDLER = "_str | _Var[_str] | _EventCallback[*_tuple[_Any, ...]]" def test_render_stub(): @@ -108,14 +110,14 @@ def test_render_stub(): ] assert render_stub(Path("party.js"), "abc", exports) == ( stub_header(Path("party.js"), "abc") + "\n" + IMPORTS + "\n" - "def celebrate(count: float | Var[float], " - f"elementId: {HANDLER}, loud: bool | Var[bool] = ..., /) -> EventSpec: ...\n" - f"def many(arg0: Any, /, *names: {HANDLER}) -> EventSpec: ...\n" - "@overload\n" - "def pick(n: float | Var[float], /) -> EventSpec: ...\n" - "@overload\n" - "def pick() -> EventSpec: ...\n" - "def anything(*args: Any) -> EventSpec: ...\n" + "def celebrate(count: _float | _Var[_float], " + f"elementId: {HANDLER}, loud: _bool | _Var[_bool] = ..., /) -> _EventSpec: ...\n" + f"def many(arg0: _Any, /, *names: {HANDLER}) -> _EventSpec: ...\n" + "@_overload\n" + "def pick(n: _float | _Var[_float], /) -> _EventSpec: ...\n" + "@_overload\n" + "def pick() -> _EventSpec: ...\n" + "def anything(*args: _Any) -> _EventSpec: ...\n" ) @@ -128,7 +130,7 @@ def test_renamed_parameters_do_not_collide(): ) ] assert render_stub(Path("send.js"), "abc", exports).splitlines()[-1] == ( - "def send(arg0__: Any, arg0: Any, arg0_: Any, /) -> EventSpec: ..." + "def send(arg0__: _Any, arg0: _Any, arg0_: _Any, /) -> _EventSpec: ..." ) @@ -145,18 +147,35 @@ def test_only_trailing_optional_parameters_have_defaults(): ) ] assert render_stub(Path("send.ts"), "abc", exports).splitlines()[-1] == ( - f"def send(prefix: {HANDLER}, count: float | Var[float], " - f"suffix: {HANDLER} = ..., /) -> EventSpec: ..." + f"def send(prefix: {HANDLER}, count: _float | _Var[_float], " + f"suffix: {HANDLER} = ..., /) -> _EventSpec: ..." ) +def test_exports_named_like_types_do_not_replace_them(): + """An export named ``str`` or ``Var`` leaves the stub's annotations intact. + + The stub uses private aliases for the types; an export named like one of + those cannot be imported through the stub. + """ + exports = [ + _export("str", [_param("value", "string"), _param("str", "number")]), + _export("Var", [_param("n", "number")]), + _export("_str", []), + ] + assert render_stub(Path("m.js"), "abc", exports).splitlines()[-2:] == [ + f"def str(value: {HANDLER}, str: _float | _Var[_float], /) -> _EventSpec: ...", + "def Var(n: _float | _Var[_float], /) -> _EventSpec: ...", + ] + + def test_render_untyped_stub(): """Without types, every export takes any arguments.""" assert render_untyped_stub(Path("party.ts"), "untyped", ["go", "class"]) == ( "# Generated by Reflex from party.ts (untyped); rewritten when it changes.\n" + IMPORTS + "\n" - "def go(*args: Any) -> EventSpec: ...\n" + "def go(*args: _Any) -> _EventSpec: ...\n" ) @@ -180,6 +199,30 @@ def test_module_digest_covers_imports_and_packages(tmp_path: Path): assert module_digest(module, b'{"a": "1"}') != digest +def test_module_digest_covers_the_types_a_module_reads(tmp_path: Path): + """Declaration files and JSDoc type imports are part of the digest. + + Args: + tmp_path: pytest tmp_path fixture. + """ + module = tmp_path / "party.js" + module.write_text( + '/// \n' + '/** @param {import("./types").Count} n */\n' + "export function go(n) {}\n" + ) + declarations = tmp_path / "types.d.ts" + declarations.write_text("export type Count = number;\n") + globals_ = tmp_path / "globals.d.ts" + globals_.write_text("declare const VERSION: string;\n") + digest = module_digest(module) + declarations.write_text("export type Count = string;\n") + changed = module_digest(module) + assert changed != digest + globals_.write_text("declare const VERSION: number;\n") + assert module_digest(module) != changed + + def test_module_digest_is_the_same_on_every_machine(tmp_path: Path): """The same sources in different directories give the same digest. From 1e6faf731329e7748c25040cdb8da7bbc813dea6 Mon Sep 17 00:00:00 2001 From: Farhan Date: Fri, 20 Nov 2026 22:10:20 +0000 Subject: [PATCH 04/16] Remove merge markers from a docstring; compare whole stubs in tests An earlier merge left conflict markers, then indented by the formatter, in compile_script_modules's Returns section; it now describes the three returned values once. The stub tests that compared only the last line or two of the rendered stub compare the complete output. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- reflex/compiler/utils.py | 26 ++++++++++-------------- tests/units/reflex_base/js/test_stubs.py | 19 +++++++++-------- 2 files changed, 22 insertions(+), 23 deletions(-) diff --git a/reflex/compiler/utils.py b/reflex/compiler/utils.py index 489c972b7dc..2e606d8044a 100644 --- a/reflex/compiler/utils.py +++ b/reflex/compiler/utils.py @@ -317,25 +317,21 @@ def compile_script_modules() -> tuple[ ]: """Compile the JavaScript modules the app imports from Python. - Each module and the local files it imports, directly or not, are copied - under ``utils/script_modules`` at their paths from the directory that holds - the module's top-level package, so relative imports resolve as they do in - the source tree. ``utils/scripts.js`` re-exports each module under its - module key. + Each module and the local files it imports, directly or not, are copied + under ``utils/script_modules`` at their paths from the directory that holds + the module's top-level package, so relative imports resolve as they do in + the source tree. ``utils/scripts.js`` re-exports each module under its + module key. Returns: - <<<<<<< HEAD - The (path, code) outputs, and the npm packages to install: those the - modules import, and typescript, which reads their types for the stubs. - ======= - The (path, code) outputs of the scripts, the npm packages they import, - to install, and the (source, target) copies of the other files they - reference, such as stylesheets and images, which may be binary. - >>>>>>> farhan/focused-darwin-dx76ek-js-modules + The (path, code) outputs of the scripts; the npm packages to install, + which are those the scripts import and typescript, which reads their + types for the stubs; and the (source, target) copies of the other files + they reference, such as stylesheets and images, which may be binary. Raises: - ReflexRuntimeError: If a module imports a file outside its top-level - package's directory. + ReflexRuntimeError: If a module imports a file outside its top-level + package's directory. """ web_dir = get_web_dir() modules_dir = web_dir / constants.Dirs.SCRIPT_MODULES_PATH diff --git a/tests/units/reflex_base/js/test_stubs.py b/tests/units/reflex_base/js/test_stubs.py index 771a78ad7f6..d9223938972 100644 --- a/tests/units/reflex_base/js/test_stubs.py +++ b/tests/units/reflex_base/js/test_stubs.py @@ -129,8 +129,9 @@ def test_renamed_parameters_do_not_collide(): [_param("$value", "any"), _param("arg0", "any"), _param("arg0_", "any")], ) ] - assert render_stub(Path("send.js"), "abc", exports).splitlines()[-1] == ( - "def send(arg0__: _Any, arg0: _Any, arg0_: _Any, /) -> _EventSpec: ..." + assert render_stub(Path("send.js"), "abc", exports) == ( + stub_header(Path("send.js"), "abc") + "\n" + IMPORTS + "\n" + "def send(arg0__: _Any, arg0: _Any, arg0_: _Any, /) -> _EventSpec: ...\n" ) @@ -146,9 +147,10 @@ def test_only_trailing_optional_parameters_have_defaults(): ], ) ] - assert render_stub(Path("send.ts"), "abc", exports).splitlines()[-1] == ( + assert render_stub(Path("send.ts"), "abc", exports) == ( + stub_header(Path("send.ts"), "abc") + "\n" + IMPORTS + "\n" f"def send(prefix: {HANDLER}, count: _float | _Var[_float], " - f"suffix: {HANDLER} = ..., /) -> _EventSpec: ..." + f"suffix: {HANDLER} = ..., /) -> _EventSpec: ...\n" ) @@ -163,10 +165,11 @@ def test_exports_named_like_types_do_not_replace_them(): _export("Var", [_param("n", "number")]), _export("_str", []), ] - assert render_stub(Path("m.js"), "abc", exports).splitlines()[-2:] == [ - f"def str(value: {HANDLER}, str: _float | _Var[_float], /) -> _EventSpec: ...", - "def Var(n: _float | _Var[_float], /) -> _EventSpec: ...", - ] + assert render_stub(Path("m.js"), "abc", exports) == ( + stub_header(Path("m.js"), "abc") + "\n" + IMPORTS + "\n" + f"def str(value: {HANDLER}, str: _float | _Var[_float], /) -> _EventSpec: ...\n" + "def Var(n: _float | _Var[_float], /) -> _EventSpec: ...\n" + ) def test_render_untyped_stub(): From 10f0c7bea73d10bc320531fd4f16864fce6952f9 Mon Sep 17 00:00:00 2001 From: Farhan Date: Fri, 20 Nov 2026 22:14:59 +0000 Subject: [PATCH 05/16] Resolve the runtime file of an import, and track its declaration beside it Trying `.d.ts` before `.js` when resolving `./helpers` picked helpers.d.ts whenever both existed, so helpers.js was not copied and a clean frontend build could not resolve the import. Runtime files resolve as the bundler does again, and the declaration file that types an import (helpers.d.ts for `./helpers` or `./helpers.js`, or alone for a types-only import) is tracked beside it, for the stub digest. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- .../reflex-base/src/reflex_base/js/source.py | 31 +++++++++++++++++-- tests/units/reflex_base/js/test_source.py | 27 ++++++++++++++++ 2 files changed, 56 insertions(+), 2 deletions(-) diff --git a/packages/reflex-base/src/reflex_base/js/source.py b/packages/reflex-base/src/reflex_base/js/source.py index 90bbdacbc1f..177f32c5369 100644 --- a/packages/reflex-base/src/reflex_base/js/source.py +++ b/packages/reflex-base/src/reflex_base/js/source.py @@ -17,7 +17,9 @@ # Stylesheets, whose `@import` and `url(...)` references are followed. STYLESHEET_EXTENSION = ".css" # Tried in order for an import without an extension, as the bundler does. -_RESOLVE_EXTENSIONS = (".ts", ".tsx", ".d.ts", ".js", ".jsx", ".mjs") +_RESOLVE_EXTENSIONS = (".ts", ".tsx", ".js", ".jsx", ".mjs") +# The extension of the declaration file that types a runtime file. +_DECLARATION_EXTENSION = ".d.ts" _CSS_COMMENT_RE = re.compile(r"/\*.*?\*/", re.DOTALL) _CSS_REFERENCE_RE = re.compile( @@ -606,6 +608,25 @@ def _resolve_local(directory: Path, specifier: str) -> Path | None: return next((candidate for candidate in candidates if candidate.is_file()), None) +def _resolve_declaration(directory: Path, specifier: str) -> Path | None: + """Find the declaration file that types what a relative import names. + + TypeScript reads ``helpers.d.ts`` for ``./helpers`` and ``./helpers.js`` + alike, beside the runtime file or, for a types-only import, alone. + + Args: + directory: The importing file's directory. + specifier: The relative specifier. + + Returns: + The declaration file, or None if there is none. + """ + target = directory / strip_query(specifier) + stem = target.with_suffix("") if target.suffix in _RESOLVE_EXTENSIONS else target + declaration = stem.with_name(stem.name + _DECLARATION_EXTENSION) + return declaration if declaration.is_file() else None + + def module_files(path: Path) -> list[Path]: """Find a module and every local file it imports, directly or not. @@ -634,8 +655,14 @@ def module_files(path: Path) -> list[Path]: ), *find_type_references(source), ] + # The runtime file the bundler loads, and the declaration typing it. targets = [ - _resolve_local(file.parent, specifier) for specifier in specifiers + resolved + for specifier in specifiers + for resolved in ( + _resolve_local(file.parent, specifier), + _resolve_declaration(file.parent, specifier), + ) ] elif file.suffix == STYLESHEET_EXTENSION: targets = [ diff --git a/tests/units/reflex_base/js/test_source.py b/tests/units/reflex_base/js/test_source.py index 08c7fa2c403..f86a8fb6401 100644 --- a/tests/units/reflex_base/js/test_source.py +++ b/tests/units/reflex_base/js/test_source.py @@ -142,3 +142,30 @@ def test_find_stylesheet_references(): "fonts.css", "./bg.png", ] + + +def test_module_files_keeps_runtime_files_beside_declarations(tmp_path: Path): + """A declaration file is tracked beside the runtime file it describes. + + Args: + tmp_path: pytest tmp_path fixture. + """ + module = tmp_path / "party.js" + module.write_text( + 'import { help } from "./helpers";\n' + 'import { format } from "./format.js";\n' + 'import type { Count } from "./types";\n' + ) + (tmp_path / "helpers.js").write_text("export const help = 1;\n") + (tmp_path / "helpers.d.ts").write_text("export declare const help: number;\n") + (tmp_path / "format.js").write_text("export const format = 1;\n") + (tmp_path / "format.d.ts").write_text("export declare const format: number;\n") + (tmp_path / "types.d.ts").write_text("export type Count = number;\n") + assert module_files(module) == [ + module.resolve(), + (tmp_path / "helpers.js").resolve(), + (tmp_path / "helpers.d.ts").resolve(), + (tmp_path / "format.js").resolve(), + (tmp_path / "format.d.ts").resolve(), + (tmp_path / "types.d.ts").resolve(), + ] From 7c653f182f3e3cead6e906bb8fba455368b8e691 Mon Sep 17 00:00:00 2001 From: Farhan Date: Fri, 20 Nov 2026 22:18:08 +0000 Subject: [PATCH 06/16] Track a directory's index.d.ts for a types-only import Dropping .d.ts from runtime resolution also dropped the lookup of types/index.d.ts for `./types`, so editing it left the stub digest unchanged. The declaration lookup now tries it after types.d.ts. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- packages/reflex-base/src/reflex_base/js/source.py | 10 +++++++--- tests/units/reflex_base/js/test_source.py | 4 ++++ 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/packages/reflex-base/src/reflex_base/js/source.py b/packages/reflex-base/src/reflex_base/js/source.py index 177f32c5369..66213a0aebb 100644 --- a/packages/reflex-base/src/reflex_base/js/source.py +++ b/packages/reflex-base/src/reflex_base/js/source.py @@ -612,7 +612,8 @@ def _resolve_declaration(directory: Path, specifier: str) -> Path | None: """Find the declaration file that types what a relative import names. TypeScript reads ``helpers.d.ts`` for ``./helpers`` and ``./helpers.js`` - alike, beside the runtime file or, for a types-only import, alone. + alike, and ``types/index.d.ts`` for a directory ``./types``, beside the + runtime file or, for a types-only import, alone. Args: directory: The importing file's directory. @@ -623,8 +624,11 @@ def _resolve_declaration(directory: Path, specifier: str) -> Path | None: """ target = directory / strip_query(specifier) stem = target.with_suffix("") if target.suffix in _RESOLVE_EXTENSIONS else target - declaration = stem.with_name(stem.name + _DECLARATION_EXTENSION) - return declaration if declaration.is_file() else None + candidates = ( + stem.with_name(stem.name + _DECLARATION_EXTENSION), + target / f"index{_DECLARATION_EXTENSION}", + ) + return next((candidate for candidate in candidates if candidate.is_file()), None) def module_files(path: Path) -> list[Path]: diff --git a/tests/units/reflex_base/js/test_source.py b/tests/units/reflex_base/js/test_source.py index f86a8fb6401..fb305bddfad 100644 --- a/tests/units/reflex_base/js/test_source.py +++ b/tests/units/reflex_base/js/test_source.py @@ -155,7 +155,10 @@ def test_module_files_keeps_runtime_files_beside_declarations(tmp_path: Path): 'import { help } from "./helpers";\n' 'import { format } from "./format.js";\n' 'import type { Count } from "./types";\n' + 'import type { Shape } from "./shapes";\n' ) + (tmp_path / "shapes").mkdir() + (tmp_path / "shapes" / "index.d.ts").write_text("export type Shape = string;\n") (tmp_path / "helpers.js").write_text("export const help = 1;\n") (tmp_path / "helpers.d.ts").write_text("export declare const help: number;\n") (tmp_path / "format.js").write_text("export const format = 1;\n") @@ -168,4 +171,5 @@ def test_module_files_keeps_runtime_files_beside_declarations(tmp_path: Path): (tmp_path / "format.js").resolve(), (tmp_path / "format.d.ts").resolve(), (tmp_path / "types.d.ts").resolve(), + (tmp_path / "shapes" / "index.d.ts").resolve(), ] From 7a8bad9bf9c61aa716f37a5222b2acdf1eef4dae Mon Sep 17 00:00:00 2001 From: Farhan Date: Fri, 20 Nov 2026 22:49:36 +0000 Subject: [PATCH 07/16] Find the generated stub next to the module Python imported test_js_module_stub failed when another test module had already run an app named `callscript` in the same process: the harness reloads that package, which keeps its first directory, so page_script.js and its stub live there, not under this harness's app_path. The test now takes the module's path from the imported module, and normalizes the digest in the header, which depends on the app's package.json (its value is covered by the unit tests), before comparing the whole stub. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- .../tests_playwright/test_call_script.py | 25 ++++++++++++++----- 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/tests/integration/tests_playwright/test_call_script.py b/tests/integration/tests_playwright/test_call_script.py index 0909fd821f3..af253b5e664 100644 --- a/tests/integration/tests_playwright/test_call_script.py +++ b/tests/integration/tests_playwright/test_call_script.py @@ -2,7 +2,10 @@ from __future__ import annotations +import re +import sys from collections.abc import Generator +from pathlib import Path import pytest from playwright.sync_api import Page, expect @@ -643,13 +646,23 @@ def test_js_module_stub(call_script: AppHarness): Args: call_script: harness for CallScript app. """ - from reflex_base.js.stubs import module_digest, stub_header - - module = call_script.app_path / call_script.app_name / "page_script.js" - package_json = (call_script.app_path / ".web" / "package.json").read_bytes() + from reflex_base.js.stubs import stub_header + + # The module Python imported: a harness that reloads an app package of the + # same name keeps the package's first directory. + spec = sys.modules[f"{call_script.app_name}.page_script"].__spec__ + assert spec is not None + assert spec.origin is not None + module = Path(spec.origin) handler = "_str | _Var[_str] | _EventCallback[*_tuple[_Any, ...]]" - assert (module.with_suffix(".pyi")).read_text() == ( - stub_header(module, module_digest(module, package_json)) + "\n" + # The digest depends on the app's package.json; the rest is exact. + stub = re.sub( + r"^(# Generated by Reflex from page_script\.js \()[0-9a-f]{16}(\))", + r"\1\2", + module.with_suffix(".pyi").read_text(), + ) + assert stub == ( + stub_header(module, "") + "\n" "from builtins import bool as _bool, float as _float, int as _int, str as _str\n" "from builtins import tuple as _tuple\n" "from collections.abc import Mapping as _Mapping, Sequence as _Sequence\n" From 6c55085f9832c031b3581a4648c73e65a2500253 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 22:28:03 +0000 Subject: [PATCH 08/16] Do not reload the backend when a type stub is written Granian watched .pyi files, so each stub Reflex wrote next to a JavaScript module restarted the backend once more. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- reflex/utils/exec.py | 2 ++ tests/units/utils/test_exec.py | 13 +++++++++++++ 2 files changed, 15 insertions(+) diff --git a/reflex/utils/exec.py b/reflex/utils/exec.py index 6a5603b234d..ebe5da2a4f4 100644 --- a/reflex/utils/exec.py +++ b/reflex/utils/exec.py @@ -781,6 +781,8 @@ def run_uvicorn_backend(host: str, port: int, loglevel: LogLevel): "bash", "log", "db", + # The type stubs Reflex writes next to JavaScript modules. + "pyi", ) HOTRELOAD_IGNORE_PATTERNS = ( diff --git a/tests/units/utils/test_exec.py b/tests/units/utils/test_exec.py index 4eeff83f785..68985f33041 100644 --- a/tests/units/utils/test_exec.py +++ b/tests/units/utils/test_exec.py @@ -5,6 +5,7 @@ import logging import multiprocessing import os +import re import socket import subprocess import sys @@ -1520,3 +1521,15 @@ def test_get_package_json_and_hash_reads_utf8(tmp_path: Path): ) content, _ = exec_utils.get_package_json_and_hash(package_json_path) assert content == {"description": "\u0101", "dependencies": {}} + + +def test_hot_reload_ignores_type_stubs(): + """Writing a type stub next to a JavaScript module does not reload the backend.""" + ignored = [ + name + for name in ("party.pyi", "party.py") + if any( + re.match(pattern, name) for pattern in exec_utils.HOTRELOAD_IGNORE_PATTERNS + ) + ] + assert ignored == ["party.pyi"] From d36ac6fa389cbacb8b5deac38e35b0d784e1a792 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 22:28:38 +0000 Subject: [PATCH 09/16] Document the typed stubs usage-first, with every warning The Type Stubs section shows what a JSDoc signature becomes, maps each TypeScript type to its Python type (Any included), says the stubs are written in development only and recommends committing them, and lists the warnings a compile can print with their fixes. The news fragments say what changed for users instead of naming internal files. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- docs/api-reference/browser_javascript.md | 102 +++++++++++++++--- news/+js-module-stubs.feature.md | 2 +- .../news/+js-module-stubs.feature.md | 2 +- 3 files changed, 87 insertions(+), 19 deletions(-) diff --git a/docs/api-reference/browser_javascript.md b/docs/api-reference/browser_javascript.md index 35f251ff7cf..4032a284c5b 100644 --- a/docs/api-reference/browser_javascript.md +++ b/docs/api-reference/browser_javascript.md @@ -360,24 +360,81 @@ Apps whose Content Security Policy forbids `unsafe-eval` can use them. - In a `.jsx` or `.tsx` file, JSX is read as JSX. In a `.js` or `.ts` file, `<` is never JSX, so a quote in what would be JSX text hides the code after it on that line. -- Reflex writes a type stub (`party.pyi`) next to the module when it compiles - the app, so type checkers resolve the import and check each call. Argument - types come from TypeScript annotations or, in a `.js` file, JSDoc: - - ```javascript - /** - * @param {number} count - * @param {string} elementId - */ - export function celebrate(count, elementId) {} - ``` - becomes `def celebrate(count: float | Var[float], elementId: str | Var[str] | ..., /) -> EventSpec`. - A `string` parameter also takes an event handler, sent as its name. - Arguments without a type, or of a type with no JSON form such as an - `HTMLElement`, are `Any`. The stub is rewritten only when a script in the - module's folder changes. Pyright reports a stub without a Python module as - `reportMissingModuleSource`; set it to `"none"` to silence it. +### Type Stubs + +While you develop, Reflex writes a type stub next to each module the app +imports, `party.pyi` beside `party.js`, so type checkers resolve the import and +check each call. Argument types come from TypeScript annotations or, in a `.js` +file, JSDoc: + +```javascript +// my_app/scripts/party.js +/** + * @param {number} count + * @param {string} elementId + * @param {"left" | "right"} [side] + */ +export function celebrate(count, elementId, side) { /* ... */ } +``` + +gives this stub, shown without its imports and with each private alias, such +as `_float`, as the name it stands for: + +```python +# my_app/scripts/party.pyi +def celebrate( + count: float | Var[float], + elementId: str | Var[str] | EventCallback[*tuple[Any, ...]], + side: Literal["left", "right"] | Var[Literal["left", "right"]] = ..., + /, +) -> EventSpec: ... +``` + +so `celebrate("lots", "results")` is a type error. Arguments are positional, +as JavaScript passes them, and each also takes a var. A function reads its +arguments as JSON, so each type becomes the type of the JSON value Python sends: + +| TypeScript or JSDoc | Python | +| --- | --- | +| `string` | `str`, or an event handler, sent as its name | +| `number` | `float` | +| `boolean` | `bool` | +| `null`, `undefined`, `void` | `None` | +| `"a" \| "b"`, `1 \| 2`, `true` | `Literal["a", "b"]`, `Literal[1, 2]`, `Literal[True]` | +| an enum | `Literal` of its values | +| `T[]`, `[T, U]` | `Sequence[T]`, `Sequence[T \| U]` | +| `Record`, `{ [key: string]: T }` | `Mapping[str, T]` | +| an object type or interface of your own | `Mapping[str, Any]` | +| `A \| B` | the union of their types, `Any` if either is `Any` | +| no type, `any`, `unknown`, `object`, `bigint`, `A & B`, a type parameter | `Any` | +| a function, a class, `Date`, `Map`, `Set`, `Promise`, `HTMLElement` and other types of the browser or an npm package | `Any` | +| `x?: T`, or a default value | `x: T = ...`, when no required parameter follows | +| `...rest: T[]` | `*rest: T` | + +An overloaded function gets one `@overload` per signature. An export +TypeScript knows is only a type, such as `export interface Options`, or is not +a function, is left out of the stub. + +- Commit the stubs, so your editor and type checks in CI see them without + running the app. A stub only changes when the types do: Reflex rewrites it + when the module, a file it imports or reads types from (a `.d.ts` file, + `import type`, a JSDoc `import("./types")`), the app's frontend packages or + Reflex itself changes. Writing a stub does not reload the backend. +- Stubs are written only in development. `reflex export` and `reflex run --env + prod` leave your source tree alone. +- When the app stops importing a module, Reflex removes the stub it wrote for + it. It never removes a `.pyi` file it did not write. +- Reflex reads the types with TypeScript, which it installs with the app's + frontend packages, run by Node.js or, without it, Bun. +- Pyright reports a stub that has no Python module beside it as + `reportMissingModuleSource`. Turn that rule off: + + ```toml + # pyproject.toml + [tool.pyright] + reportMissingModuleSource = "none" + ``` ### Errors @@ -400,6 +457,17 @@ Apps whose Content Security Policy forbids `unsafe-eval` can use them. not export a function of that name, or the frontend was built before the backend imported it. Export the function, or restart `reflex run` to rebuild the frontend. +- `Reflex could not read the argument types of the JavaScript modules + .../party.js, so their type stubs accept any arguments: reading them needs + Node.js or Bun, and neither was found.` The app still runs, but type + checkers accept any arguments. Install Node.js 22.22.0 or newer, then run + the app again. +- `Reflex could not read the argument types of the JavaScript modules + .../party.js, so their type stubs accept any arguments: script-signatures.js + failed: ...` The error after `failed:` says why. Reflex retries on the next + compile; if it keeps failing, delete `.web/node_modules` so the next run + reinstalls TypeScript, or report the error at + https://github.com/reflex-dev/reflex/issues. ## Using React Hooks diff --git a/news/+js-module-stubs.feature.md b/news/+js-module-stubs.feature.md index 0360ade0662..c03e3055d1c 100644 --- a/news/+js-module-stubs.feature.md +++ b/news/+js-module-stubs.feature.md @@ -1 +1 @@ -The type stub Reflex writes next to an imported JavaScript module now types each function's arguments from its TypeScript annotations or JSDoc, so type checkers catch a wrong argument in Python, e.g. `celebrate("lots")` for `@param {number} count`. +While you develop, the type stub Reflex writes next to an imported JavaScript module types each function's arguments from its TypeScript annotations or JSDoc, so type checkers catch a wrong argument in Python, such as `celebrate("lots")` for `@param {number} count`. Production builds leave the source tree alone, and writing a stub does not reload the backend; see [Type Stubs](https://reflex.dev/docs/api-reference/browser-javascript/#type-stubs). diff --git a/packages/reflex-base/news/+js-module-stubs.feature.md b/packages/reflex-base/news/+js-module-stubs.feature.md index c9fd3fa22e8..cab5e8d141f 100644 --- a/packages/reflex-base/news/+js-module-stubs.feature.md +++ b/packages/reflex-base/news/+js-module-stubs.feature.md @@ -1 +1 @@ -Type the stubs written next to JavaScript modules imported from Python: `script-signatures.js` reads each export's parameters from TypeScript annotations or JSDoc, and typescript is installed with apps that import a module. +The type stub written next to a JavaScript module imported from Python types each function's arguments from TypeScript annotations or JSDoc, as the JSON value Python sends (`number` is `float`, `"a" | "b"` is `Literal["a", "b"]`, a `Map` or `HTMLElement` is `Any`), and declares only the functions the module exports at runtime. From 3afdcd0ddb8e989be7c2102f1475121344207b04 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 22:29:40 +0000 Subject: [PATCH 10/16] Test that a production compile writes no stub and installs no typescript Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- tests/units/compiler/test_compiler.py | 55 +++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/tests/units/compiler/test_compiler.py b/tests/units/compiler/test_compiler.py index 0f42e0ea870..83248628278 100644 --- a/tests/units/compiler/test_compiler.py +++ b/tests/units/compiler/test_compiler.py @@ -16,6 +16,7 @@ from reflex_base.constants.base import LiteralColorMode from reflex_base.constants.compiler import PageNames from reflex_base.environment import environment +from reflex_base.js.stubs import _TYPESCRIPT_PACKAGE from reflex_base.plugins import CompileContext, CompilerHooks, PageContext from reflex_base.plugins.sitemap import SitemapPlugin from reflex_base.registry import RegistrationContext @@ -83,6 +84,60 @@ def __init__(self): assert task["current"] == task["total"] +@pytest.mark.parametrize("prod", [False, True]) +def test_compile_writes_stubs_only_in_development( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + mocker: MockerFixture, + clean_registration_context: RegistrationContext, + prod: bool, +): + """A production build installs no typescript and leaves the source tree alone. + + Args: + tmp_path: The temporary application directory. + monkeypatch: Fixture for selecting the application directory and mode. + mocker: Fixture for avoiding frontend dependency installation. + clean_registration_context: A fresh registry of imported modules. + prod: Whether to compile in production mode. + """ + monkeypatch.chdir(tmp_path) + if prod: + monkeypatch.setenv("REFLEX_ENV_MODE", constants.Env.PROD.value) + monkeypatch.setattr(utils.path_ops, "get_node_path", lambda: None) + monkeypatch.setattr(utils.path_ops, "get_bun_path", lambda: None) + monkeypatch.setattr(utils.console, "warn", lambda message: None) + mocker.patch( + "reflex_base.config._get_config", + return_value=rx.Config(app_name="stub_test", plugins=[]), + ) + party = tmp_path / "stub_test" / "party.js" + party.parent.mkdir() + party.write_text("export function go(n) {}\n") + clean_registration_context._script_modules["stub_test.party"] = party + app = rx.App(enable_state=False) + app.add_page(lambda: rx.el.div("hello"), route="index") + install = mocker.patch.object(app, "_get_frontend_packages") + web_dir = prerequisites.get_web_dir() + web_dir.mkdir() + (web_dir / "package.json").write_text("{}") + + compiler.compile_app(app, use_rich=False) + + (installed,) = install.call_args.args + stub = party.with_suffix(".pyi") + assert (_TYPESCRIPT_PACKAGE in installed, stub.is_file()) == (not prod, not prod) + if not prod: + assert stub.read_text() == ( + "# Generated by Reflex from party.js (untyped); rewritten when it changes.\n" + "from typing import Any as _Any\n" + "\n" + "from reflex_base.event import EventSpec as _EventSpec\n" + "\n" + "def go(*args: _Any) -> _EventSpec: ...\n" + ) + + @pytest.mark.parametrize("remove_assets_directory", [False, True]) @pytest.mark.usefixtures("clean_registration_context") def test_compile_removes_deleted_app_assets( From 789a235a2091d654b7fe4178bdf98f4ce44700c3 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 22:31:45 +0000 Subject: [PATCH 11/16] Tidy the stub compile loop; name the signatures script in the README Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- docs/api-reference/browser_javascript.md | 2 +- packages/reflex-frontend/README.md | 5 ++++- reflex/compiler/utils.py | 15 +++++++-------- 3 files changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/api-reference/browser_javascript.md b/docs/api-reference/browser_javascript.md index 4032a284c5b..c6f46122d02 100644 --- a/docs/api-reference/browser_javascript.md +++ b/docs/api-reference/browser_javascript.md @@ -420,7 +420,7 @@ a function, is left out of the stub. running the app. A stub only changes when the types do: Reflex rewrites it when the module, a file it imports or reads types from (a `.d.ts` file, `import type`, a JSDoc `import("./types")`), the app's frontend packages or - Reflex itself changes. Writing a stub does not reload the backend. + Reflex's stub generator changes. Writing a stub does not reload the backend. - Stubs are written only in development. `reflex export` and `reflex run --env prod` leave your source tree alone. - When the app stops importing a module, Reflex removes the stub it wrote for diff --git a/packages/reflex-frontend/README.md b/packages/reflex-frontend/README.md index 97593dc457e..0e59cd01341 100644 --- a/packages/reflex-frontend/README.md +++ b/packages/reflex-frontend/README.md @@ -17,7 +17,10 @@ In a checkout of the repository there is no embedded copy: reflex-base reads `src/` in place, so the next `reflex init` copies an edit without a rebuild. Everything in `src/` ships to every app, including the build tooling an app -runs (`compress-static.js`, the PostCSS config, the Vite plugins). Tests, +runs (`compress-static.js`, the PostCSS config, the Vite plugins) and +`script-signatures.js`, which reads the types of the JavaScript modules an app +imports from Python for their stubs; its output, the contract with +`reflex_base/js/stubs.py`, is `tests/fixtures/signatures/signatures.json`. Tests, fixtures and this package's own lint and type-check setup stay outside it. A change under `src/` is a change to reflex-base: its news fragment goes in diff --git a/reflex/compiler/utils.py b/reflex/compiler/utils.py index 6f58579d46b..324d126b09a 100644 --- a/reflex/compiler/utils.py +++ b/reflex/compiler/utils.py @@ -360,7 +360,7 @@ def _script_module_files( file, (modules_dir / file.relative_to(package_dir.parent), script) ) modules[name] = path.resolve() - sources[path.resolve()] = module_sources + sources[modules[name]] = module_sources return files, modules, sources @@ -521,13 +521,12 @@ def compile_script_stubs( for path, digest in stale.items(): # The module itself is a .js or .ts file, so it is a script. functions = cast("ScriptSource", sources[path][path]).functions - outputs.append(( - str(path.with_suffix(".pyi")), - _render_stub(path, digest, functions, signatures[path]) - if signatures is not None - # Never current, so the next compile tries again. - else _render_stub(path, "untyped", functions, None), - )) + if signatures is None: + # Never current, so the next compile reads the types again. + stub = _render_stub(path, "untyped", functions, None) + else: + stub = _render_stub(path, digest, functions, signatures[path]) + outputs.append((str(path.with_suffix(".pyi")), stub)) return outputs From dd9f006730c7002e72f587a2dca6f46ee75bd9b3 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 22:33:01 +0000 Subject: [PATCH 12/16] Format the signatures fixture as biome does Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- .../tests/fixtures/signatures/signatures.json | 20 ++++--------------- 1 file changed, 4 insertions(+), 16 deletions(-) diff --git a/packages/reflex-frontend/tests/fixtures/signatures/signatures.json b/packages/reflex-frontend/tests/fixtures/signatures/signatures.json index 6022169d598..4be33435f7e 100644 --- a/packages/reflex-frontend/tests/fixtures/signatures/signatures.json +++ b/packages/reflex-frontend/tests/fixtures/signatures/signatures.json @@ -105,10 +105,7 @@ "name": "maybe", "type": { "kind": "union", - "members": [ - "None", - "str" - ] + "members": ["None", "str"] }, "optional": false, "rest": false @@ -302,10 +299,7 @@ "kind": "list", "item": { "kind": "union", - "members": [ - "float", - "str" - ] + "members": ["float", "str"] } }, "optional": false, @@ -371,10 +365,7 @@ "kind": "list", "item": { "kind": "union", - "members": [ - "None", - "str" - ] + "members": ["None", "str"] } }, "optional": false, @@ -464,10 +455,7 @@ "name": "value", "type": { "kind": "union", - "members": [ - "None", - "str" - ] + "members": ["None", "str"] }, "optional": true, "rest": false From f7f7b9e27b695d993500fd46cab8ff642fa2d0a7 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 22:33:24 +0000 Subject: [PATCH 13/16] Use the parameters of the JSDoc fixture, which biome flagged as unused Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- .../reflex-frontend/tests/fixtures/signatures/jsdoc.js | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/packages/reflex-frontend/tests/fixtures/signatures/jsdoc.js b/packages/reflex-frontend/tests/fixtures/signatures/jsdoc.js index 383f2d4ff29..74dd3c6e515 100644 --- a/packages/reflex-frontend/tests/fixtures/signatures/jsdoc.js +++ b/packages/reflex-frontend/tests/fixtures/signatures/jsdoc.js @@ -3,10 +3,14 @@ * @param {string} elementId * @param {boolean} [loud] */ -export function celebrate(count, elementId, loud = false) {} +export function celebrate(count, elementId, loud = false) { + return [count, elementId, loud]; +} /** @param {...string} names */ -export function many(...names) {} +export function many(...names) { + return names; +} export const untyped = (a, b) => a + b; From 902693f9b143c34403f7f8ff432191e5f517c80a Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 22:34:41 +0000 Subject: [PATCH 14/16] Cover re-exported names in the signatures fixture; drop a dead branch `boolean` is always the union `true | false`, so classify never saw a lone BooleanLike type. A function re-exported under another name is in the stub, and a re-exported type is not. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- packages/reflex-frontend/src/script-signatures.js | 3 ++- .../tests/fixtures/signatures/signatures.json | 9 +++++++++ .../reflex-frontend/tests/fixtures/signatures/types.ts | 2 ++ tests/units/reflex_base/js/test_stubs.py | 4 +++- 4 files changed, 16 insertions(+), 2 deletions(-) diff --git a/packages/reflex-frontend/src/script-signatures.js b/packages/reflex-frontend/src/script-signatures.js index 13e8ad21ad4..34560a6c269 100644 --- a/packages/reflex-frontend/src/script-signatures.js +++ b/packages/reflex-frontend/src/script-signatures.js @@ -137,8 +137,9 @@ const classify = (type) => { return { kind: "literal", value: type === checker.getTrueType() }; } if (flags & ts.TypeFlags.StringLike) return "str"; + // `boolean` needs no case: it is the union `true | false`, which `union` + // makes "bool". if (flags & ts.TypeFlags.NumberLike) return "float"; - if (flags & ts.TypeFlags.BooleanLike) return "bool"; if ( flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined | ts.TypeFlags.Void) diff --git a/packages/reflex-frontend/tests/fixtures/signatures/signatures.json b/packages/reflex-frontend/tests/fixtures/signatures/signatures.json index 4be33435f7e..a327f3304d0 100644 --- a/packages/reflex-frontend/tests/fixtures/signatures/signatures.json +++ b/packages/reflex-frontend/tests/fixtures/signatures/signatures.json @@ -486,6 +486,15 @@ "signatures": [], "untyped": false }, + { + "name": "aliased", + "signatures": [ + { + "parameters": [] + } + ], + "untyped": false + }, { "name": "fromReexported", "signatures": [ diff --git a/packages/reflex-frontend/tests/fixtures/signatures/types.ts b/packages/reflex-frontend/tests/fixtures/signatures/types.ts index ad27cce7dbd..d02a830b0bc 100644 --- a/packages/reflex-frontend/tests/fixtures/signatures/types.ts +++ b/packages/reflex-frontend/tests/fixtures/signatures/types.ts @@ -19,6 +19,8 @@ export type Count = number; export class Widget {} export * from "./reexported.js"; +export { fromReexported as aliased } from "./reexported.js"; +export type { Shape } from "./shapes"; export function literals( color: Color, diff --git a/tests/units/reflex_base/js/test_stubs.py b/tests/units/reflex_base/js/test_stubs.py index 7fd61b2b4fe..d7855e4a07e 100644 --- a/tests/units/reflex_base/js/test_stubs.py +++ b/tests/units/reflex_base/js/test_stubs.py @@ -96,7 +96,8 @@ def test_render_stub_maps_types_without_json_form_to_any(): """Enums are their values; containers keep item types; Set, Map, bigint and the like are Any. Types, classes, enums and ``export *`` names are not functions the module - exports, so the stub declares none of them. + exports, so the stub declares none of them; a function re-exported by + name is one. """ def var(value: str) -> str: @@ -115,6 +116,7 @@ def var(value: str) -> str: "from reflex_base.event import EventCallback as _EventCallback, EventSpec as _EventSpec\n" "from reflex_base.vars.base import Var as _Var\n" "\n" + "def aliased() -> _EventSpec: ...\n" "def literals(" f"color: {color}, " f"level: {var('_Literal[0, 1]')}, " From e19f407193604f60eba54bb2779ca61d93a5ad28 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 22:58:01 +0000 Subject: [PATCH 15/16] Classify a type that contains itself as any at its repeat A recursive type such as interface Tree { [key: string]: Tree } sent classify into unbounded recursion, so the script crashed and every module got an untyped stub. The object types being classified are now tracked, and a repeat is any, the only JSON shape it can have. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- .../reflex-frontend/src/script-signatures.js | 20 ++++++++++++ .../tests/fixtures/signatures/recursive.ts | 7 +++++ .../tests/script_signatures.test.js | 31 +++++++++++++++++++ 3 files changed, 58 insertions(+) create mode 100644 packages/reflex-frontend/tests/fixtures/signatures/recursive.ts diff --git a/packages/reflex-frontend/src/script-signatures.js b/packages/reflex-frontend/src/script-signatures.js index 34560a6c269..6394b692bf9 100644 --- a/packages/reflex-frontend/src/script-signatures.js +++ b/packages/reflex-frontend/src/script-signatures.js @@ -98,6 +98,11 @@ const isOpaque = (type) => { ); }; +// The object types being classified, outermost first. A type that contains +// itself, such as `interface Tree { [key: string]: Tree }`, has no finite JSON +// shape: its repeat is classified as any. +const classifying = new Set(); + /** * Classify an object type: an array or tuple is a list, a string-keyed record * a mapping of its values, and another plain object a mapping. @@ -105,6 +110,21 @@ const isOpaque = (type) => { * @returns {JsonType} Its JSON type. */ const classifyObject = (type) => { + if (classifying.has(type)) return "any"; + classifying.add(type); + try { + return classifyShape(type); + } finally { + classifying.delete(type); + } +}; + +/** + * Classify an object type that is not already being classified. + * @param {any} type The type. + * @returns {JsonType} Its JSON type. + */ +const classifyShape = (type) => { if (checker.isArrayType(type)) { return { kind: "list", item: classify(checker.getTypeArguments(type)[0]) }; } diff --git a/packages/reflex-frontend/tests/fixtures/signatures/recursive.ts b/packages/reflex-frontend/tests/fixtures/signatures/recursive.ts new file mode 100644 index 00000000000..77d142ac5de --- /dev/null +++ b/packages/reflex-frontend/tests/fixtures/signatures/recursive.ts @@ -0,0 +1,7 @@ +export interface Tree { + [key: string]: Tree; +} + +export type Nested = Nested[]; + +export function grow(tree: Tree, nested: Nested, depth: number): void {} diff --git a/packages/reflex-frontend/tests/script_signatures.test.js b/packages/reflex-frontend/tests/script_signatures.test.js index e35b2820b9d..9abe9cb5cc6 100644 --- a/packages/reflex-frontend/tests/script_signatures.test.js +++ b/packages/reflex-frontend/tests/script_signatures.test.js @@ -52,3 +52,34 @@ test("classifies each parameter's type into the JSON value Python sends", async await signatures(["jsdoc.js", "typed.ts", "types.ts", "script.js"]), ).toEqual(JSON.parse(readFileSync(`${fixtures}signatures.json`, "utf-8"))); }); + +test("a type that contains itself stops at its first repeat", async () => { + // The repeat has no finite JSON shape, so it accepts any value. + expect(await signatures(["recursive.ts"])).toEqual({ + "recursive.ts": [ + { + name: "grow", + signatures: [ + { + parameters: [ + { + name: "tree", + type: { kind: "mapping", value: "any" }, + optional: false, + rest: false, + }, + { + name: "nested", + type: { kind: "list", item: "any" }, + optional: false, + rest: false, + }, + { name: "depth", type: "float", optional: false, rest: false }, + ], + }, + ], + untyped: false, + }, + ], + }); +}); From c1626173dadf11195f87cb1e7ac43cd4d52bceff Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 22:58:02 +0000 Subject: [PATCH 16/16] Compare the whole stub in the stub cleanup test Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- tests/units/compiler/test_compiler_utils.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/tests/units/compiler/test_compiler_utils.py b/tests/units/compiler/test_compiler_utils.py index 7fb774c2534..da8ecf83e9f 100644 --- a/tests/units/compiler/test_compiler_utils.py +++ b/tests/units/compiler/test_compiler_utils.py @@ -1108,7 +1108,12 @@ def test_compile_script_stubs_removes_stubs_of_modules_no_longer_imported( json.dumps([str(handwritten), str(stub_app / "gone.pyi")]) ) _compile_stubs() - assert party_stub.read_text().startswith("# Generated by Reflex from party.js (") + digest = _module_digest( + party, module_files(party), (web_dir / "package.json").read_bytes() + ) + assert party_stub.read_text() == ( + f"# Generated by Reflex from party.js ({digest}); rewritten when it changes.\n" + ) clean_registration_context._script_modules.clear() assert _compile_stubs() == [(str(web_dir / "script_stubs.json"), "[]")]