django-cfg 1.4.11__py3-none-any.whl → 1.4.13__py3-none-any.whl

django_cfg/modules/django_client/core/generator/typescript/fetchers_generator.py

@@ -0,0 +1,428 @@
+"""
+Fetchers Generator - Generates typed fetcher functions from IR.
+
+This generator creates universal TypeScript functions that:
+- Use Zod schemas for runtime validation
+- Work in any environment (Next.js, React Native, Node.js)
+- Are type-safe with proper TypeScript types
+- Can be used with any data-fetching library
+"""
+
+from __future__ import annotations
+
+from jinja2 import Environment
+from ..base import GeneratedFile, BaseGenerator
+from ...ir import IRContext, IROperationObject
+
+
+class FetchersGenerator:
+    """
+    Generate typed fetcher functions from IR operations.
+
+    Features:
+    - Runtime validation with Zod
+    - Type-safe parameters and responses
+    - Works with any data-fetching library (SWR, React Query)
+    - Server Component compatible
+    """
+
+    def __init__(self, jinja_env: Environment, context: IRContext, base: BaseGenerator):
+        self.jinja_env = jinja_env
+        self.context = context
+        self.base = base
+
+    def generate_fetcher_function(self, operation: IROperationObject) -> str:
+        """
+        Generate a single fetcher function for an operation.
+
+        Args:
+            operation: IROperationObject to convert to fetcher
+
+        Returns:
+            TypeScript fetcher function code
+
+        Examples:
+            >>> generate_fetcher_function(users_list)
+            export async function getUsers(params?: GetUsersParams): Promise<PaginatedUser> {
+              const response = await api.users.list(params)
+              return PaginatedUserSchema.parse(response)
+            }
+        """
+        # Get function name (e.g., "getUsers", "createUser")
+        func_name = self._operation_to_function_name(operation)
+
+        # Get parameters structure
+        param_info = self._get_param_structure(operation)
+
+        # Get response type and schema
+        response_type, response_schema = self._get_response_info(operation)
+
+        # Get API client call
+        api_call = self._get_api_call(operation)
+
+        # Build JSDoc comment
+        jsdoc = self._generate_jsdoc(operation, func_name)
+
+        # Build function
+        lines = []
+
+        # JSDoc
+        if jsdoc:
+            lines.append(jsdoc)
+
+        # Function signature with optional client parameter
+        if param_info['func_params']:
+            lines.append(f"export async function {func_name}(")
+            lines.append(f"  {param_info['func_params']},")
+            lines.append(f"  client?: API")
+            lines.append(f"): Promise<{response_type}> {{")
+        else:
+            lines.append(f"export async function {func_name}(")
+            lines.append(f"  client?: API")
+            lines.append(f"): Promise<{response_type}> {{")
+
+        # Get client instance (either passed or global)
+        lines.append("  const api = client || getAPIInstance()")
+        lines.append("")
+
+        # Function body - build API call
+        api_call_params = param_info['api_call_params']
+        # Replace API. with api.
+        api_call_instance = api_call.replace("API.", "api.")
+
+        if api_call_params:
+            lines.append(f"  const response = await {api_call_instance}({api_call_params})")
+        else:
+            lines.append(f"  const response = await {api_call_instance}()")
+
+        # Validation with Zod
+        if response_schema:
+            lines.append(f"  return {response_schema}.parse(response)")
+        else:
+            lines.append("  return response")
+
+        lines.append("}")
+
+        return "\n".join(lines)
+
+    def _operation_to_function_name(self, operation: IROperationObject) -> str:
+        """
+        Convert operation to function name.
+
+        Examples:
+            users_list (GET) -> getUsers
+            users_retrieve (GET) -> getUser
+            users_create (POST) -> createUser
+            users_update (PUT) -> updateUser
+            users_partial_update (PATCH) -> updateUser
+            users_destroy (DELETE) -> deleteUser
+        """
+        # Remove tag prefix from operation_id
+        op_id = operation.operation_id
+
+        # Handle common patterns (remove only suffix, not all occurrences)
+        if op_id.endswith("_list"):
+            resource = op_id.removesuffix("_list")
+            return f"get{self._to_pascal_case(resource)}"
+        elif op_id.endswith("_retrieve"):
+            resource = op_id.removesuffix("_retrieve")
+            # Singular
+            return f"get{self._to_pascal_case(resource).rstrip('s')}"
+        elif op_id.endswith("_create"):
+            resource = op_id.removesuffix("_create")
+            return f"create{self._to_pascal_case(resource)}"
+        elif op_id.endswith("_partial_update"):
+            resource = op_id.removesuffix("_partial_update")
+            return f"partialUpdate{self._to_pascal_case(resource)}"
+        elif op_id.endswith("_update"):
+            resource = op_id.removesuffix("_update")
+            return f"update{self._to_pascal_case(resource)}"
+        elif op_id.endswith("_destroy"):
+            resource = op_id.removesuffix("_destroy")
+            return f"delete{self._to_pascal_case(resource)}"
+        else:
+            # Custom action - use operation_id as is
+            return self._to_camel_case(op_id)
+
+    def _to_pascal_case(self, snake_str: str) -> str:
+        """Convert snake_case to PascalCase."""
+        return ''.join(word.capitalize() for word in snake_str.split('_'))
+
+    def _to_camel_case(self, snake_str: str) -> str:
+        """Convert snake_case to camelCase."""
+        components = snake_str.split('_')
+        return components[0] + ''.join(x.capitalize() for x in components[1:])
+
+    def _get_param_structure(self, operation: IROperationObject) -> dict:
+        """
+        Get structured parameter information for function generation.
+
+        Returns dict with:
+            - func_params: Function signature params (e.g., "slug: string, params?: { page?: number }")
+            - api_call_params: API call params (e.g., "slug, params" or "slug" or "params")
+
+        Examples:
+            GET /users/{id}/ -> {
+                func_params: "id: number",
+                api_call_params: "id"
+            }
+
+            GET /users/ with query params -> {
+                func_params: "params?: { page?: number }",
+                api_call_params: "params"
+            }
+
+            GET /users/{id}/ with query params -> {
+                func_params: "id: number, params?: { page?: number }",
+                api_call_params: "id, params"
+            }
+
+            POST /users/ -> {
+                func_params: "data: UserRequest",
+                api_call_params: "data"
+            }
+
+            POST /users/{id}/action/ -> {
+                func_params: "id: number, data: ActionRequest",
+                api_call_params: "id, data"
+            }
+        """
+        func_params = []
+        api_call_params = []
+
+        # Path parameters (always passed individually)
+        if operation.path_parameters:
+            for param in operation.path_parameters:
+                param_type = self._map_param_type(param.schema_type)
+                func_params.append(f"{param.name}: {param_type}")
+                api_call_params.append(param.name)
+
+        # Query parameters (passed as params object, but unpacked when calling API)
+        if operation.query_parameters:
+            query_fields = []
+            # params is required only if all parameters are required
+            all_required = all(param.required for param in operation.query_parameters)
+            params_accessor = "params." if all_required else "params?."
+
+            for param in operation.query_parameters:
+                param_type = self._map_param_type(param.schema_type)
+                optional = "?" if not param.required else ""
+                query_fields.append(f"{param.name}{optional}: {param_type}")
+                # Unpack from params object when calling API
+                api_call_params.append(f"{params_accessor}{param.name}")
+
+            if query_fields:
+                params_optional = "" if all_required else "?"
+                func_params.append(f"params{params_optional}: {{ {'; '.join(query_fields)} }}")
+
+        # Request body (passed as data)
+        if operation.request_body:
+            schema_name = operation.request_body.schema_name
+            # Use schema only if it exists as a component (not inline)
+            if schema_name and schema_name in self.context.schemas:
+                body_type = schema_name
+            else:
+                body_type = "any"
+            func_params.append(f"data: {body_type}")
+            api_call_params.append("data")
+
+        return {
+            'func_params': ", ".join(func_params) if func_params else "",
+            'api_call_params': ", ".join(api_call_params) if api_call_params else ""
+        }
+
+    def _get_params_type(self, operation: IROperationObject) -> tuple[str, bool]:
+        """
+        Get parameters type definition.
+
+        Returns:
+            (type_definition, has_params)
+
+        Examples:
+            ("params?: { page?: number; page_size?: number }", True)
+            ("id: number", True)
+            ("", False)
+        """
+        params = []
+
+        # Path parameters
+        if operation.path_parameters:
+            for param in operation.path_parameters:
+                param_type = self._map_param_type(param.schema_type)
+                params.append(f"{param.name}: {param_type}")
+
+        # Query parameters
+        if operation.query_parameters:
+            query_fields = []
+            all_required = all(param.required for param in operation.query_parameters)
+
+            for param in operation.query_parameters:
+                param_type = self._map_param_type(param.schema_type)
+                optional = "?" if not param.required else ""
+                query_fields.append(f"{param.name}{optional}: {param_type}")
+
+            if query_fields:
+                params_optional = "" if all_required else "?"
+                params.append(f"params{params_optional}: {{ {'; '.join(query_fields)} }}")
+
+        # Request body
+        if operation.request_body:
+            schema_name = operation.request_body.schema_name
+            # Use schema only if it exists as a component (not inline)
+            if schema_name and schema_name in self.context.schemas:
+                body_type = schema_name
+            else:
+                body_type = "any"
+            params.append(f"data: {body_type}")
+
+        if not params:
+            return ("", False)
+
+        return (", ".join(params), True)
+
+    def _map_param_type(self, param_type: str) -> str:
+        """Map OpenAPI param type to TypeScript type."""
+        type_map = {
+            "integer": "number",
+            "number": "number",
+            "string": "string",
+            "boolean": "boolean",
+            "array": "any[]",
+            "object": "any",
+        }
+        return type_map.get(param_type, "any")
+
+    def _get_response_info(self, operation: IROperationObject) -> tuple[str, str | None]:
+        """
+        Get response type and schema name.
+
+        Returns:
+            (response_type, response_schema_name)
+
+        Examples:
+            ("PaginatedUser", "PaginatedUserSchema")
+            ("User", "UserSchema")
+            ("void", None)
+        """
+        # Get 2xx response
+        for status_code in [200, 201, 202, 204]:
+            if status_code in operation.responses:
+                response = operation.responses[status_code]
+                if response.schema_name:
+                    schema_name = response.schema_name
+                    return (schema_name, f"{schema_name}Schema")
+
+        # No response or void
+        if 204 in operation.responses or operation.http_method == "DELETE":
+            return ("void", None)
+
+        return ("any", None)
+
+    def _get_api_call(self, operation: IROperationObject) -> str:
+        """
+        Get API client method call path.
+
+        Examples:
+            API.users.list
+            API.users.retrieve
+            API.posts.create
+        """
+        # Get tag/resource name
+        tag = operation.tags[0] if operation.tags else "default"
+        tag_property = self.base.tag_to_property_name(tag)
+
+        # Get method name from operation_id
+        method_name = self.base.remove_tag_prefix(operation.operation_id, tag)
+        method_name = self._to_camel_case(method_name)
+
+        return f"API.{tag_property}.{method_name}"
+
+    def _generate_jsdoc(self, operation: IROperationObject, func_name: str) -> str:
+        """Generate JSDoc comment for function."""
+        lines = ["/**"]
+
+        # Summary
+        if operation.summary:
+            lines.append(f" * {operation.summary}")
+        else:
+            lines.append(f" * {func_name}")
+
+        # Description
+        if operation.description:
+            lines.append(" *")
+            for desc_line in operation.description.split("\n"):
+                lines.append(f" * {desc_line}")
+
+        # HTTP method and path
+        lines.append(" *")
+        lines.append(f" * @method {operation.http_method}")
+        lines.append(f" * @path {operation.path}")
+
+        lines.append(" */")
+        return "\n".join(lines)
+
+    def generate_tag_fetchers_file(
+        self,
+        tag: str,
+        operations: list[IROperationObject],
+    ) -> GeneratedFile:
+        """
+        Generate fetchers file for a specific tag/resource.
+
+        Args:
+            tag: Tag name (e.g., "users", "posts")
+            operations: List of operations for this tag
+
+        Returns:
+            GeneratedFile with fetchers
+        """
+        # Generate individual fetchers
+        fetchers = []
+        schema_names = set()
+
+        for operation in operations:
+            fetcher_code = self.generate_fetcher_function(operation)
+            fetchers.append(fetcher_code)
+
+            # Collect schema names
+            _, response_schema = self._get_response_info(operation)
+            if response_schema:
+                schema_name = response_schema.replace("Schema", "")
+                schema_names.add(schema_name)
+
+            # Add request body schemas (only if they exist as components)
+            if operation.request_body and operation.request_body.schema_name:
+                # Only add if schema exists in components (not inline)
+                if operation.request_body.schema_name in self.context.schemas:
+                    schema_names.add(operation.request_body.schema_name)
+
+        # Get display name and folder name (use same naming as APIClient)
+        tag_display_name = self.base.tag_to_display_name(tag)
+        folder_name = self.base.tag_and_app_to_folder_name(tag, operations)
+
+        # Render template
+        template = self.jinja_env.get_template("fetchers/fetchers.ts.jinja")
+        content = template.render(
+            tag_display_name=tag_display_name,
+            fetchers=fetchers,
+            has_schemas=bool(schema_names),
+            schema_names=sorted(schema_names),
+            has_client=True,
+        )
+
+        return GeneratedFile(
+            path=f"_utils/fetchers/{folder_name}.ts",
+            content=content,
+            description=f"Typed fetchers for {tag_display_name}",
+        )
+
+    def generate_fetchers_index_file(self, module_names: list[str]) -> GeneratedFile:
+        """Generate index.ts for fetchers folder."""
+        template = self.jinja_env.get_template("fetchers/index.ts.jinja")
+        content = template.render(modules=sorted(module_names))
+
+        return GeneratedFile(
+            path="_utils/fetchers/index.ts",
+            content=content,
+            description="Fetchers index",
+        )

django_cfg/modules/django_client/core/generator/typescript/files_generator.py

@@ -0,0 +1,207 @@
+"""
+TypeScript Files Generator - Generates utility files (index, http, errors, logger, etc.).
+"""
+
+from __future__ import annotations
+
+from jinja2 import Environment
+from ...ir import IROperationObject
+from ..base import GeneratedFile
+
+
+class FilesGenerator:
+    """Generates TypeScript utility files."""
+
+    def __init__(self, jinja_env: Environment, context, base):
+        self.jinja_env = jinja_env
+        self.context = context
+        self.base = base
+        self.openapi_schema = getattr(base, 'openapi_schema', None)
+
+    def generate_index_file(self):
+        """Generate index.ts with exports."""
+
+        template = self.jinja_env.get_template('index.ts.jinja')
+        content = template.render(
+            has_enums=bool(self.base.get_enum_schemas())
+        )
+
+        return GeneratedFile(
+            path="index.ts",
+            content=content,
+            description="Module exports",
+        )
+
+    def generate_app_index_file(self, tag: str, operations: list[IROperationObject]):
+        """Generate index.ts for a specific app."""
+        from ..base import GeneratedFile
+
+        template = self.jinja_env.get_template('app_index.ts.jinja')
+        content = template.render()
+
+        folder_name = self.base.tag_and_app_to_folder_name(tag, operations)
+        return GeneratedFile(
+            path=f"{folder_name}/index.ts",
+            content=content,
+            description=f"Module exports for {tag}",
+        )
+
+    def generate_main_index_file(self):
+        """Generate main index.ts with API class and JWT management."""
+
+        ops_by_tag = self.base.group_operations_by_tag()
+        tags = sorted(ops_by_tag.keys())
+
+        # Prepare tags data for template
+        tags_data = [
+            {
+                "class_name": self.base.tag_to_class_name(tag, suffix=""),
+                "property": self.base.tag_to_property_name(tag),
+                "slug": self.base.tag_and_app_to_folder_name(tag, ops_by_tag[tag]),
+            }
+            for tag in tags
+        ]
+
+        # Check if we have enums
+        all_schemas = self.context.schemas
+        all_enums = self.base._collect_enums_from_schemas(all_schemas)
+
+        template = self.jinja_env.get_template('main_index.ts.jinja')
+        content = template.render(
+            api_title=self.context.openapi_info.title,
+            tags=tags_data,
+            has_enums=bool(all_enums),
+            generate_zod_schemas=getattr(self.base, 'generate_zod_schemas', False),
+            generate_fetchers=getattr(self.base, 'generate_fetchers', False),
+            generate_swr_hooks=getattr(self.base, 'generate_swr_hooks', False),
+        )
+
+        return GeneratedFile(
+            path="index.ts",
+            content=content,
+            description="Main index with API class and JWT management",
+        )
+
+    def generate_http_adapter_file(self):
+        """Generate http.ts with HttpClient adapter interface."""
+
+        template = self.jinja_env.get_template('utils/http.ts.jinja')
+        content = template.render()
+
+        return GeneratedFile(
+            path="http.ts",
+            content=content,
+            description="HTTP client adapter interface and implementations",
+        )
+
+    def generate_errors_file(self):
+        """Generate errors.ts with APIError class."""
+
+        template = self.jinja_env.get_template('utils/errors.ts.jinja')
+        content = template.render()
+
+        return GeneratedFile(
+            path="errors.ts",
+            content=content,
+            description="API error classes",
+        )
+
+    def generate_storage_file(self):
+        """Generate storage.ts with StorageAdapter implementations."""
+
+        template = self.jinja_env.get_template('utils/storage.ts.jinja')
+        content = template.render()
+
+        return GeneratedFile(
+            path="storage.ts",
+            content=content,
+            description="Storage adapters for cross-platform support",
+        )
+
+    def generate_logger_file(self):
+        """Generate logger.ts with Consola integration."""
+
+        template = self.jinja_env.get_template('utils/logger.ts.jinja')
+        content = template.render()
+
+        return GeneratedFile(
+            path="logger.ts",
+            content=content,
+            description="API Logger with Consola",
+        )
+
+    def generate_retry_file(self):
+        """Generate retry.ts with p-retry integration."""
+
+        template = self.jinja_env.get_template('utils/retry.ts.jinja')
+        content = template.render()
+
+        return GeneratedFile(
+            path="retry.ts",
+            content=content,
+            description="Retry utilities with p-retry",
+        )
+
+    def generate_api_instance_file(self):
+        """Generate api-instance.ts with global singleton."""
+
+        template = self.jinja_env.get_template('api_instance.ts.jinja')
+        content = template.render()
+
+        return GeneratedFile(
+            path="api-instance.ts",
+            content=content,
+            description="Global API singleton for universal configuration",
+        )
+
+    def generate_package_json_file(self, package_config: dict = None):
+        """Generate package.json for npm publishing."""
+        if package_config is None:
+            package_config = {}
+
+        # Default configuration
+        defaults = {
+            "package_name": package_config.get("name", "api-client"),
+            "version": package_config.get("version", "1.0.0"),
+            "description": package_config.get("description") or f"Auto-generated TypeScript client for {self.context.openapi_info.title}",
+            "author": package_config.get("author"),
+            "license": package_config.get("license", "MIT"),
+            "repository_url": package_config.get("repository_url"),
+            "keywords": package_config.get("keywords", ["api", "client", "typescript", "openapi"]),
+            "private": package_config.get("private", False),
+        }
+
+        # Add Zod flag
+        defaults["generate_zod_schemas"] = self.base.generate_zod_schemas
+
+        template = self.jinja_env.get_template('package.json.jinja')
+        content = template.render(**defaults)
+
+        return GeneratedFile(
+            path="package.json",
+            content=content,
+            description="NPM package configuration",
+        )
+
+    def generate_tsconfig_file(self):
+        """Generate tsconfig.json for TypeScript compilation."""
+        template = self.jinja_env.get_template('tsconfig.json.jinja')
+        content = template.render()
+
+        return GeneratedFile(
+            path="tsconfig.json",
+            content=content,
+            description="TypeScript compiler configuration",
+        )
+
+    def generate_schema_file(self):
+        """Generate schema.ts with OpenAPI schema as const."""
+
+        template = self.jinja_env.get_template('utils/schema.ts.jinja')
+        content = template.render(schema=self.openapi_schema)
+
+        return GeneratedFile(
+            path="schema.ts",
+            content=content,
+            description="OpenAPI Schema",
+        )