typesync 0.0.1a1__tar.gz

typesync-0.0.1a1/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Francisco rodrigues
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

typesync-0.0.1a1/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: typesync
+Version: 0.0.1a1
+Summary: Auto-generate TypeScript client code from Flask routes and Python type annotations.
+Author-email: Francisco Rodrigues <francisco.rodrigues0908@gmail.com>
+Project-URL: Homepage, https://github.com/ArmindoFlores/typesync
+Project-URL: GitHub, https://github.com/ArmindoFlores/typesync
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Requires-Dist: flask
+Requires-Dist: inflection>=0.5.1
+Dynamic: license-file
+
+# Typesync
+
+This project aims to automatically generate TypeScript types and client-side request helpers directly from a Flask application. It is heavily inspired by [JS Flask URLs](https://github.com/indico/js-flask-urls).
+
+By inspecting Flask routes and their Python type annotations, it produces strongly typed TypeScript definitions and functions that can call those endpoints with correct argument and return types. The project is currently incomplete, but the core idea and basic functionality are already in place.
+
+The main goal is to reduce duplication and type mismatches between backend and frontend codebases by treating the Flask app as the single source of truth for API structure and typing.
+
+## Intended and Existing Features
+
+Some features are already implemented, others are planned.
+
+- [x] Parse Flask routes and URL rules
+- [x] Parse route argument types from annotations
+- [x] Parse return types from annotated view functions
+- [x] Generate TypeScript type definitions
+- [x] Generate TypeScript request/helper functions for endpoints
+- [x] CLI integration with Flask via a custom command
+- [x] Vite support
+- [x] Handling of Flask converters (custom and built-in)
+- [x] Support for multiple HTTP methods (GET, POST, PUT, DELETE, etc.)
+- [x] Support for JSON request bodies with typed parameters
+    - [ ] Support validators such as pydantic
+- [ ] Support for `typing.Annotated` to:
+    - [ ] Ignore specific routes
+    - [ ] Customize generation behavior (naming, visibility, etc.)
+- [ ] Improved error reporting for unsupported or ambiguous annotations
+- [ ] Optional generation modes (types only, requests only)
+- [ ] Configuration file support
+- [x] Support custom formatting for generated code
+- [x] Handle recursive types (such as `type RecursiveType = tuple[int, RecursiveType]`)*
+- [x] Support returning with `jsonify(...)`
+- [x] Support extensions via translators
+
+\* Not all cases are supported.
+
+
+## Installation
+
+The project is not yet published on PyPI. Installation is currently done directly from source, preferably using `uv`.
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/ArmindoFlores/typesync
+cd typesync
+uv sync --dev
+uv pip install -e .
+```
+
+## Usage
+### TypeScript generation
+The tool is exposed as a Flask CLI command. Inside your Flask application environment, run:
+
+```bash
+flask typesync generate OUT_DIR
+```
+
+This command will load the Flask app, inspect the URL map and registered view functions, and generate the corresponding TypeScript files (types and request helpers), placing them inside `OUT_DIR`. The names of the generated files, types, and functions can be customized using command line options. For more information about these options, use `flask typesync generate --help`.
+
+### Using the generated code
+The main output of typesync is a `makeAPI()` function that is used to instantiate an object containing a function per HTTP method per endpoint. An example on how to use this function is provided in [example/frontend/src/api.ts](example/frontend/src/api.ts).
+
+### Rollup Plugin
+Typesync has a rollup plugin that can be used to integrate with Rollup/Vite projects. Additional documentation is provided in [rollup-plugin-typesync/README.md](rollup-plugin-typesync/README.md).
+
+
+## Inference
+
+Typesync is capable of some basic type inference. This can be helpful when trying to incrementally adopt this package in an existing codebase, or for unconventional Flask setups. This functionality is optional, and needs to be enabled using the `--inference` flag. Additionally, the inference module may need to use `eval()` for evaluating some types; this is disabled by default, but can be enabled using `--inference-can-eval`.
+
+
+## Running Tests
+
+Tests can be run using pytest:
+
+```bash
+pytest
+```

typesync-0.0.1a1/README.md

@@ -0,0 +1,79 @@
+# Typesync
+
+This project aims to automatically generate TypeScript types and client-side request helpers directly from a Flask application. It is heavily inspired by [JS Flask URLs](https://github.com/indico/js-flask-urls).
+
+By inspecting Flask routes and their Python type annotations, it produces strongly typed TypeScript definitions and functions that can call those endpoints with correct argument and return types. The project is currently incomplete, but the core idea and basic functionality are already in place.
+
+The main goal is to reduce duplication and type mismatches between backend and frontend codebases by treating the Flask app as the single source of truth for API structure and typing.
+
+## Intended and Existing Features
+
+Some features are already implemented, others are planned.
+
+- [x] Parse Flask routes and URL rules
+- [x] Parse route argument types from annotations
+- [x] Parse return types from annotated view functions
+- [x] Generate TypeScript type definitions
+- [x] Generate TypeScript request/helper functions for endpoints
+- [x] CLI integration with Flask via a custom command
+- [x] Vite support
+- [x] Handling of Flask converters (custom and built-in)
+- [x] Support for multiple HTTP methods (GET, POST, PUT, DELETE, etc.)
+- [x] Support for JSON request bodies with typed parameters
+    - [ ] Support validators such as pydantic
+- [ ] Support for `typing.Annotated` to:
+    - [ ] Ignore specific routes
+    - [ ] Customize generation behavior (naming, visibility, etc.)
+- [ ] Improved error reporting for unsupported or ambiguous annotations
+- [ ] Optional generation modes (types only, requests only)
+- [ ] Configuration file support
+- [x] Support custom formatting for generated code
+- [x] Handle recursive types (such as `type RecursiveType = tuple[int, RecursiveType]`)*
+- [x] Support returning with `jsonify(...)`
+- [x] Support extensions via translators
+
+\* Not all cases are supported.
+
+
+## Installation
+
+The project is not yet published on PyPI. Installation is currently done directly from source, preferably using `uv`.
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/ArmindoFlores/typesync
+cd typesync
+uv sync --dev
+uv pip install -e .
+```
+
+## Usage
+### TypeScript generation
+The tool is exposed as a Flask CLI command. Inside your Flask application environment, run:
+
+```bash
+flask typesync generate OUT_DIR
+```
+
+This command will load the Flask app, inspect the URL map and registered view functions, and generate the corresponding TypeScript files (types and request helpers), placing them inside `OUT_DIR`. The names of the generated files, types, and functions can be customized using command line options. For more information about these options, use `flask typesync generate --help`.
+
+### Using the generated code
+The main output of typesync is a `makeAPI()` function that is used to instantiate an object containing a function per HTTP method per endpoint. An example on how to use this function is provided in [example/frontend/src/api.ts](example/frontend/src/api.ts).
+
+### Rollup Plugin
+Typesync has a rollup plugin that can be used to integrate with Rollup/Vite projects. Additional documentation is provided in [rollup-plugin-typesync/README.md](rollup-plugin-typesync/README.md).
+
+
+## Inference
+
+Typesync is capable of some basic type inference. This can be helpful when trying to incrementally adopt this package in an existing codebase, or for unconventional Flask setups. This functionality is optional, and needs to be enabled using the `--inference` flag. Additionally, the inference module may need to use `eval()` for evaluating some types; this is disabled by default, but can be enabled using `--inference-can-eval`.
+
+
+## Running Tests
+
+Tests can be run using pytest:
+
+```bash
+pytest
+```

typesync-0.0.1a1/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+version = "0.0.1a1"
+name = "typesync"
+description = "Auto-generate TypeScript client code from Flask routes and Python type annotations."
+readme = "README.md"
+license-files = ["LICENSE"]
+dependencies = [
+  "click",
+  "flask",
+  "inflection>=0.5.1",
+]
+requires-python = ">= 3.12"
+authors = [
+  {name = "Francisco Rodrigues", email = "francisco.rodrigues0908@gmail.com"},
+]
+
+[project.urls]
+Homepage = "https://github.com/ArmindoFlores/typesync"
+GitHub = "https://github.com/ArmindoFlores/typesync"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["typesync*"]
+
+[dependency-groups]
+dev = [
+    "ty>=0.0.11",
+    "Flask-CORS",
+    "pytest>=9.0.2",
+    "types-flask-cors>=6.0.0.20250809",
+    "pre-commit>=4.5.1",
+    "ruff>=0.14.13",
+]
+
+[tool.ruff.lint]
+extend-select = [
+  "E",      # pycodestyle (errors)
+  "W",      # pycodestyle (warnings)
+  "F",      # pyflakes
+  "N",      # pep8-naming
+  "Q",      # flake8-quotes
+  "RUF",    # ruff
+  "UP",     # pyupgrade
+  "S",      # flake8-bandit
+  "C4",     # flake8-comprehensions
+  "INT",    # flake8-gettext
+  "LOG",    # flake8-logging
+  "G",      # flake8-logging-format
+  "B",      # flake8-bugbear
+  "A001",   # flake8-builtins
+  "COM",    # flake8-commas
+  "T10",    # flake8-debugger
+  "EXE",    # flake8-executable
+  "ISC",    # flake8-implicit-str-concat
+  "PIE",    # flake8-pie
+  "PT",     # flake8-pytest-style
+  "RSE",    # flake8-raise
+  "RET504", # flake8-return
+  "SIM",    # flake8-simplify
+  "TID",    # flake8-tidy-imports
+  "PGH",    # pygrep-hooks
+  "PL",     # pylint
+  "TRY",    # tryceratops
+  "PERF",   # perflint
+  "FURB",   # refurb
+]
+extend-ignore = [
+  "PLR0911",
+  "PLR0913",
+  "PLR2004",
+  "COM812",
+  "RET504",
+  "G004",
+  "TRY400",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = ["S101"]

typesync-0.0.1a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

typesync-0.0.1a1/tests/test_arg_types.py

@@ -0,0 +1,60 @@
+from flask import Flask
+
+from typesync.ts_types import TSObject, TSSimpleType
+
+from conftest import ParserFixture
+
+
+def test_args_int(app: Flask, args_parser: ParserFixture) -> None:
+    @app.route("/<int:test>")
+    def main(test) -> list:
+        return []
+
+    assert args_parser(app, "main") == TSObject(
+        ("test",),
+        (TSSimpleType("number"),),
+    )
+
+
+def test_args_float(app: Flask, args_parser: ParserFixture) -> None:
+    @app.route("/<float:test>")
+    def main(test) -> list:
+        return []
+
+    assert args_parser(app, "main") == TSObject(
+        ("test",),
+        (TSSimpleType("number"),),
+    )
+
+
+def test_args_path(app: Flask, args_parser: ParserFixture) -> None:
+    @app.route("/<path:test>")
+    def main(test) -> list:
+        return []
+
+    assert args_parser(app, "main") == TSObject(
+        ("test",),
+        (TSSimpleType("string"),),
+    )
+
+
+def test_args_uuid(app: Flask, args_parser: ParserFixture) -> None:
+    @app.route("/<uuid:test>")
+    def main(test) -> list:
+        return []
+
+    assert args_parser(app, "main") == TSObject(
+        ("test",),
+        (TSSimpleType("string"),),
+    )
+
+
+def test_args_unspecified(app: Flask, args_parser: ParserFixture) -> None:
+    @app.route("/<test>")
+    def main(test) -> list:
+        return []
+
+    assert args_parser(app, "main") == TSObject(
+        ("test",),
+        (TSSimpleType("string"),),
+    )

typesync-0.0.1a1/tests/test_inference.py

@@ -0,0 +1,131 @@
+import typing
+from flask import Flask
+
+from typesync.ts_types import TSArray, TSRecord, TSSimpleType
+
+from conftest import ParserFixture
+
+
+def test_literal_string(app: Flask, inf_return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main():
+        return "hello"
+
+    assert inf_return_parser(app, "main") == TSSimpleType("string")
+
+
+def test_literal_int(app: Flask, inf_return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main():
+        return 202
+
+    assert inf_return_parser(app, "main") == TSSimpleType("number")
+
+
+def test_literal_list_same_type(app: Flask, inf_return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main():
+        return [1, 2, 3]
+
+    assert inf_return_parser(app, "main") == TSArray(TSSimpleType("number"))
+
+
+def test_literal_list_mixed(app: Flask, inf_return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main():
+        return [1, "hello", 3]
+
+    assert inf_return_parser(app, "main") == TSArray(TSSimpleType("any"))
+
+
+def test_literal_tuple(app: Flask, inf_return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main():
+        return ("hello", 404)
+
+    assert inf_return_parser(app, "main") == TSSimpleType("string")
+
+
+def test_literal_dict_same_type(app: Flask, inf_return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main():
+        return {
+            "key1": [1, 2, 3],
+            "key2": [0, 1],
+        }
+
+    assert inf_return_parser(app, "main") == TSRecord(
+        TSSimpleType("string"), TSArray(TSSimpleType("number"))
+    )
+
+
+def test_literal_dict_mixed_v(app: Flask, inf_return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main():
+        return {
+            "key1": [1, 2, 3],
+            "key2": "hello",
+        }
+
+    assert inf_return_parser(app, "main") == TSRecord(
+        TSSimpleType("string"), TSSimpleType("any")
+    )
+
+
+def test_literal_dict_mixed_k(app: Flask, inf_return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main():
+        return {
+            12: 1,
+            "key2": 2,
+        }
+
+    assert inf_return_parser(app, "main") == TSRecord(
+        TSSimpleType("any"), TSSimpleType("number")
+    )
+
+
+def test_literal_dict_mixed(app: Flask, inf_return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main():
+        return {
+            12: [1, 2, 3],
+            "key2": "hello",
+        }
+
+    assert inf_return_parser(app, "main") == TSSimpleType("object")
+
+
+def test_function_call(app: Flask, inf_return_parser: ParserFixture) -> None:
+    def result(arg: int):
+        return arg
+
+    @app.route("/main")
+    def main():
+        return result(12)
+
+    assert inf_return_parser(app, "main") == TSSimpleType("number")
+
+
+def test_class_factory(app: Flask, inf_return_parser: ParserFixture) -> None:
+    R = typing.TypeVar("R")
+
+    class RHProtocol(typing.Protocol[R]):
+        def process(self) -> R: ...
+
+    class TestInference:
+        def process(self) -> int:
+            return 12
+
+    def make_route_function[R](
+        obj: typing.Callable[[], RHProtocol[R]],
+    ) -> typing.Callable[[], R]:
+        def wrapper() -> R:
+            inst = obj()
+            return inst.process()
+
+        return wrapper
+
+    app.add_url_rule("/main", "main", make_route_function(TestInference))
+
+    assert inf_return_parser(app, "main") == TSSimpleType("number")

typesync-0.0.1a1/tests/test_nested_types.py

@@ -0,0 +1,118 @@
+from flask import Flask
+
+from typesync.ts_types import (
+    TSArray,
+    TSSimpleType,
+    TSRecord,
+    TSTuple,
+    TSUnion,
+    TSRecursiveType,
+)
+
+from conftest import ParserFixture
+
+
+type Alias1[A] = list[A]
+type Alias2[B] = Alias1[B]
+type AliasedArgs[A, B] = dict[str, tuple[Alias1[B], Alias2[A]]]
+type Recursive1[A] = tuple[A | Recursive1[A], ...]
+type Recursive2[A, B] = tuple[A | Recursive2[B, A], ...]
+type Recursive3[A, B, C] = tuple[A | Recursive3[C, A, B], ...]
+
+
+def test_nested_depth_1(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> Alias1[str]:
+        return []
+
+    assert return_parser(app, "main") == TSArray(TSSimpleType("string"))
+
+
+def test_nested_depth_2(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> Alias2[str]:
+        return []
+
+    assert return_parser(app, "main") == TSArray(TSSimpleType("string"))
+
+
+def test_nested_args(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> AliasedArgs[int, bool]:
+        return {}
+
+    assert return_parser(app, "main") == TSRecord(
+        TSSimpleType("string"),
+        TSTuple(
+            (
+                TSArray(TSSimpleType("boolean")),
+                TSArray(TSSimpleType("number")),
+            )
+        ),
+    )
+
+
+def test_recursive_args_1(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> Recursive1[int]:
+        return ()
+
+    assert return_parser(app, "main") == TSArray(
+        TSUnion(
+            (
+                TSSimpleType("number"),
+                TSRecursiveType(),
+            )
+        )
+    )
+
+
+def test_recursive_args_2(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> Recursive2[bool, str]:
+        return ()
+
+    assert return_parser(app, "main") == TSArray(
+        TSUnion(
+            (
+                TSSimpleType("boolean"),
+                TSArray(
+                    TSUnion(
+                        (
+                            TSSimpleType("string"),
+                            TSRecursiveType(),
+                        )
+                    )
+                ),
+            )
+        )
+    )
+
+
+def test_recursive_args_3(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> Recursive3[bool, str, int]:
+        return ()
+
+    assert return_parser(app, "main") == TSArray(
+        TSUnion(
+            (
+                TSSimpleType("boolean"),
+                TSArray(
+                    TSUnion(
+                        (
+                            TSSimpleType("number"),
+                            TSArray(
+                                TSUnion(
+                                    (
+                                        TSSimpleType("string"),
+                                        TSRecursiveType(),
+                                    )
+                                )
+                            ),
+                        )
+                    )
+                ),
+            )
+        )
+    )

typesync-0.0.1a1/tests/test_return_types.py

@@ -0,0 +1,77 @@
+from flask import Flask
+
+from typesync.ts_types import TSArray, TSSimpleType, TSRecord
+
+from conftest import ParserFixture
+
+
+def test_return_dict(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> dict[str, int]:
+        return {"result": 42}
+
+    assert return_parser(app, "main") == TSRecord(
+        TSSimpleType("string"), TSSimpleType("number")
+    )
+
+
+def test_return_dict_complex(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> dict[str, dict[int, bool]]:
+        return {"result": {1: True}}
+
+    assert return_parser(app, "main") == TSRecord(
+        TSSimpleType("string"),
+        TSRecord(
+            TSSimpleType("number"),
+            TSSimpleType("boolean"),
+        ),
+    )
+
+
+def test_return_dict_missing_params(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> dict:
+        return {"result": 42}
+
+    assert return_parser(app, "main") == TSSimpleType("object")
+
+
+def test_return_list(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> list[int]:
+        return [1, 2, 3]
+
+    assert return_parser(app, "main") == TSArray(TSSimpleType("number"))
+
+
+def test_return_list_complex(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> list[list[str]]:
+        return [[""]]
+
+    assert return_parser(app, "main") == TSArray(TSArray(TSSimpleType("string")))
+
+
+def test_return_list_missing_params(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> list:
+        return []
+
+    assert return_parser(app, "main") == TSArray(TSSimpleType("any"))
+
+
+def test_return_tuple1(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> tuple[str, int]:
+        return ("Status", 200)
+
+    assert return_parser(app, "main") == TSSimpleType("string")
+
+
+def test_return_tuple2(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> tuple[str, int, tuple]:
+        return ("Status", 200, ())
+
+    assert return_parser(app, "main") == TSSimpleType("string")

typesync-0.0.1a1/tests/test_stubs.py

@@ -0,0 +1,28 @@
+from flask import Flask
+
+from typesync.ts_types import TSSimpleType, TSTuple
+from typesync.utils import Response, jsonify
+
+from conftest import ParserFixture
+
+
+def test_jsonify_none(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> Response[None]:
+        return jsonify(None)
+
+    assert return_parser(app, "main") == TSSimpleType("null")
+
+
+def test_jsonify_tuple(app: Flask, return_parser: ParserFixture) -> None:
+    @app.route("/main")
+    def main() -> Response[tuple[int, str, int]]:
+        return jsonify((1, "hello", 4))
+
+    assert return_parser(app, "main") == TSTuple(
+        (
+            TSSimpleType("number"),
+            TSSimpleType("string"),
+            TSSimpleType("number"),
+        )
+    )