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

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

@@ -0,0 +1,329 @@
+"""
+Zod Schemas Generator - Generates Zod validation schemas from IR.
+
+This generator creates Zod schemas for runtime validation:
+- Object schemas (z.object)
+- Enum schemas (z.nativeEnum)
+- Array schemas (z.array)
+- Type inference (z.infer<typeof Schema>)
+"""
+
+from __future__ import annotations
+
+from jinja2 import Environment
+from ..base import GeneratedFile, BaseGenerator
+from ...ir import IRContext, IRSchemaObject
+
+
+class SchemasGenerator:
+    """
+    Generate Zod schemas from IR schemas.
+
+    Features:
+    - Runtime validation with Zod
+    - Type inference from schemas
+    - Enum validation with z.nativeEnum()
+    - Nested object validation
+    - Array and nullable types
+    """
+
+    def __init__(self, jinja_env: Environment, context: IRContext, base: BaseGenerator):
+        self.jinja_env = jinja_env
+        self.context = context
+        self.base = base
+
+    def generate_schema(self, schema: IRSchemaObject) -> str:
+        """
+        Generate Zod schema for a single IR schema.
+
+        Args:
+            schema: IRSchemaObject to convert to Zod
+
+        Returns:
+            Zod schema code as string
+
+        Examples:
+            >>> generate_schema(User)
+            export const UserSchema = z.object({
+              id: z.number(),
+              email: z.string().email(),
+              username: z.string().min(1).max(150),
+            })
+        """
+        if schema.type == "object":
+            return self._generate_object_schema(schema)
+        elif schema.type == "array":
+            return self._generate_array_schema(schema)
+        elif schema.enum:
+            return self._generate_enum_schema(schema)
+        else:
+            # Primitive type
+            return self._map_type_to_zod(schema)
+
+    def _generate_object_schema(self, schema: IRSchemaObject) -> str:
+        """Generate z.object() schema."""
+        lines = []
+
+        # Schema comment
+        if schema.description:
+            lines.append(f"/**\n * {schema.description}\n */")
+
+        # Start schema definition
+        lines.append(f"export const {schema.name}Schema = z.object({{")
+
+        # Generate fields
+        if schema.properties:
+            for prop_name, prop_schema in schema.properties.items():
+                field_code = self._generate_field(prop_name, prop_schema, schema.required)
+                lines.append(f"  {field_code},")
+
+        lines.append("})")
+
+        return "\n".join(lines)
+
+    def _generate_field(
+        self,
+        name: str,
+        schema: IRSchemaObject,
+        required_fields: list[str],
+    ) -> str:
+        """
+        Generate Zod field validation.
+
+        Examples:
+            id: z.number()
+            email: z.string().email()
+            username: z.string().min(1).max(150)
+            status: z.nativeEnum(Enums.StatusEnum)
+            created_at: z.string().datetime()
+        """
+        # Check if this field is an enum
+        if schema.enum and schema.name:
+            # Use enum validation
+            zod_type = f"z.nativeEnum(Enums.{self.base.sanitize_enum_name(schema.name)})"
+        # Check if this field is a reference to an enum
+        elif schema.ref and schema.ref in self.context.schemas:
+            ref_schema = self.context.schemas[schema.ref]
+            if ref_schema.enum:
+                # Reference to enum component
+                zod_type = f"z.nativeEnum(Enums.{self.base.sanitize_enum_name(schema.ref)})"
+            else:
+                # Reference to another schema
+                zod_type = f"{schema.ref}Schema"
+        else:
+            # Map TypeScript type to Zod type
+            zod_type = self._map_type_to_zod(schema)
+
+        # Check if required
+        is_required = name in required_fields
+
+        # Handle optional fields
+        if not is_required:
+            zod_type = f"{zod_type}.optional()"
+
+        # Handle nullable fields
+        if schema.nullable:
+            zod_type = f"{zod_type}.nullable()"
+
+        return f"{name}: {zod_type}"
+
+    def _map_type_to_zod(self, schema: IRSchemaObject) -> str:
+        """
+        Map OpenAPI/TypeScript type to Zod validation.
+
+        Args:
+            schema: IRSchemaObject with type information
+
+        Returns:
+            Zod validation code
+
+        Examples:
+            string -> z.string()
+            string (format: email) -> z.string().email()
+            string (format: date-time) -> z.string().datetime()
+            string (format: uri) -> z.string().url()
+            integer -> z.number().int()
+            number -> z.number()
+            boolean -> z.boolean()
+            array -> z.array(...)
+        """
+        schema_type = schema.type
+        schema_format = schema.format
+
+        # String types with format validation
+        if schema_type == "string":
+            base_type = "z.string()"
+
+            # Add format validation
+            if schema_format == "email":
+                base_type = "z.string().email()"
+            elif schema_format in ("date-time", "datetime"):
+                base_type = "z.string().datetime()"
+            elif schema_format == "date":
+                base_type = "z.string().date()"
+            elif schema_format in ("uri", "url"):
+                base_type = "z.string().url()"
+            elif schema_format == "uuid":
+                base_type = "z.string().uuid()"
+
+            # Add length constraints
+            if schema.min_length is not None:
+                base_type = f"{base_type}.min({schema.min_length})"
+            if schema.max_length is not None:
+                base_type = f"{base_type}.max({schema.max_length})"
+
+            # Add pattern validation
+            if schema.pattern:
+                # Escape regex pattern for JS
+                escaped_pattern = schema.pattern.replace('\\', '\\\\')
+                base_type = f"{base_type}.regex(/{escaped_pattern}/)"
+
+            return base_type
+
+        # Integer type
+        elif schema_type == "integer":
+            base_type = "z.number().int()"
+
+            # Add range constraints
+            if schema.minimum is not None:
+                base_type = f"{base_type}.min({schema.minimum})"
+            if schema.maximum is not None:
+                base_type = f"{base_type}.max({schema.maximum})"
+
+            return base_type
+
+        # Number type
+        elif schema_type == "number":
+            base_type = "z.number()"
+
+            # Add range constraints
+            if schema.minimum is not None:
+                base_type = f"{base_type}.min({schema.minimum})"
+            if schema.maximum is not None:
+                base_type = f"{base_type}.max({schema.maximum})"
+
+            return base_type
+
+        # Boolean type
+        elif schema_type == "boolean":
+            return "z.boolean()"
+
+        # Array type
+        elif schema_type == "array":
+            if schema.items:
+                item_type = self._map_type_to_zod(schema.items)
+                return f"z.array({item_type})"
+            return "z.array(z.any())"
+
+        # Object type
+        elif schema_type == "object":
+            # Only reference schema if it's a defined component (not an inline property)
+            # Inline objects should use z.record() or z.object({})
+            if schema.ref:
+                # Explicit reference
+                return f"{schema.ref}Schema"
+            elif schema.properties:
+                # Inline object with properties - shouldn't reach here, but use z.object
+                return "z.object({})"
+            else:
+                # Object with no properties (like additionalProperties: {})
+                # Use z.record(z.string(), z.any()) for dynamic objects
+                return "z.record(z.string(), z.any())"
+
+        # Fallback to any
+        return "z.any()"
+
+    def _generate_array_schema(self, schema: IRSchemaObject) -> str:
+        """Generate z.array() schema."""
+        lines = []
+
+        if schema.description:
+            lines.append(f"/**\n * {schema.description}\n */")
+
+        item_type = "z.any()"
+        if schema.items:
+            item_type = self._map_type_to_zod(schema.items)
+
+        lines.append(f"export const {schema.name}Schema = z.array({item_type})")
+
+        return "\n".join(lines)
+
+    def _generate_enum_schema(self, schema: IRSchemaObject) -> str:
+        """Generate z.nativeEnum() schema."""
+        enum_name = self.base.sanitize_enum_name(schema.name)
+
+        lines = []
+
+        if schema.description:
+            lines.append(f"/**\n * {schema.description}\n */")
+
+        lines.append(f"export const {enum_name}Schema = z.nativeEnum(Enums.{enum_name})")
+
+        return "\n".join(lines)
+
+    def generate_schema_file(self, schema: IRSchemaObject, refs: set[str]) -> GeneratedFile:
+        """
+        Generate individual Zod schema file.
+
+        Args:
+            schema: Schema to generate
+            refs: Set of schema names that are referenced
+
+        Returns:
+            GeneratedFile with Zod schema
+        """
+        # Generate schema code
+        schema_code = self.generate_schema(schema)
+
+        # Check if has enums
+        has_enums = self._schema_uses_enums(schema)
+
+        # Render template
+        template = self.jinja_env.get_template("schemas/schema.ts.jinja")
+        content = template.render(
+            schema_name=schema.name,
+            description=schema.description,
+            schema_code=schema_code,
+            has_enums=has_enums,
+            has_refs=bool(refs),
+            refs=sorted(refs),
+        )
+
+        return GeneratedFile(
+            path=f"_utils/schemas/{schema.name}.schema.ts",
+            content=content,
+            description=f"Zod schema for {schema.name}",
+        )
+
+    def generate_schemas_index_file(self, schema_names: list[str]) -> GeneratedFile:
+        """Generate index.ts for schemas folder."""
+        template = self.jinja_env.get_template("schemas/index.ts.jinja")
+        content = template.render(schema_names=sorted(schema_names))
+
+        return GeneratedFile(
+            path="_utils/schemas/index.ts",
+            content=content,
+            description="Zod schemas index",
+        )
+
+    def _schema_uses_enums(self, schema: IRSchemaObject) -> bool:
+        """Check if schema uses any enums."""
+        if schema.enum:
+            return True
+
+        if schema.properties:
+            for prop in schema.properties.values():
+                if prop.enum or (prop.ref and self._is_enum_ref(prop.ref)):
+                    return True
+
+        if schema.items:
+            if schema.items.enum or (schema.items.ref and self._is_enum_ref(schema.items.ref)):
+                return True
+
+        return False
+
+    def _is_enum_ref(self, ref: str) -> bool:
+        """Check if reference points to an enum."""
+        if ref in self.context.schemas:
+            return self.context.schemas[ref].enum is not None
+        return False

django_cfg/modules/django_client/core/generator/typescript/templates/api_instance.ts.jinja

@@ -0,0 +1,131 @@
+/**
+ * Global API Instance - Singleton configuration
+ *
+ * This module provides a global API instance that can be configured once
+ * and used throughout your application.
+ *
+ * Usage:
+ * ```typescript
+ * // Configure once (e.g., in your app entry point)
+ * import { configureAPI } from './api-instance'
+ *
+ * configureAPI({
+ *   baseUrl: 'https://api.example.com',
+ *   token: 'your-jwt-token'
+ * })
+ *
+ * // Then use fetchers and hooks anywhere without configuration
+ * import { getUsers } from './fetchers'
+ * const users = await getUsers({ page: 1 })
+ * ```
+ *
+ * For SSR or multiple instances:
+ * ```typescript
+ * import { API } from './index'
+ * import { getUsers } from './fetchers'
+ *
+ * const api = new API('https://api.example.com')
+ * const users = await getUsers({ page: 1 }, api)
+ * ```
+ */
+
+import { API, type APIOptions } from './index'
+
+let globalAPI: API | null = null
+
+/**
+ * Get the global API instance
+ * @throws Error if API is not configured
+ */
+export function getAPIInstance(): API {
+  if (!globalAPI) {
+    throw new Error(
+      'API not configured. Call configureAPI() with your base URL before using fetchers or hooks.\n\n' +
+      'Example:\n' +
+      '  import { configureAPI } from "./api-instance"\n' +
+      '  configureAPI({ baseUrl: "https://api.example.com" })'
+    )
+  }
+  return globalAPI
+}
+
+/**
+ * Check if API is configured
+ */
+export function isAPIConfigured(): boolean {
+  return globalAPI !== null
+}
+
+/**
+ * Configure the global API instance
+ *
+ * @param baseUrl - Base URL for the API
+ * @param options - Optional configuration (storage, retry, logger)
+ *
+ * @example
+ * ```typescript
+ * configureAPI({
+ *   baseUrl: 'https://api.example.com',
+ *   token: 'jwt-token',
+ *   options: {
+ *     retryConfig: { maxRetries: 3 },
+ *     loggerConfig: { enabled: true }
+ *   }
+ * })
+ * ```
+ */
+export function configureAPI(config: {
+  baseUrl: string
+  token?: string
+  refreshToken?: string
+  options?: APIOptions
+}): API {
+  globalAPI = new API(config.baseUrl, config.options)
+
+  if (config.token) {
+    globalAPI.setToken(config.token, config.refreshToken)
+  }
+
+  return globalAPI
+}
+
+/**
+ * Reconfigure the global API instance with new settings
+ * Useful for updating tokens or base URL
+ */
+export function reconfigureAPI(updates: {
+  baseUrl?: string
+  token?: string
+  refreshToken?: string
+}): API {
+  const instance = getAPIInstance()
+
+  if (updates.baseUrl) {
+    instance.setBaseUrl(updates.baseUrl)
+  }
+
+  if (updates.token) {
+    instance.setToken(updates.token, updates.refreshToken)
+  }
+
+  return instance
+}
+
+/**
+ * Clear tokens from the global API instance
+ */
+export function clearAPITokens(): void {
+  const instance = getAPIInstance()
+  instance.clearTokens()
+}
+
+/**
+ * Reset the global API instance
+ * Useful for testing or logout scenarios
+ */
+export function resetAPI(): void {
+  if (globalAPI) {
+    globalAPI.clearTokens()
+  }
+  globalAPI = null
+}

django_cfg/modules/django_client/core/generator/{templates/typescript → typescript/templates}/client/app_client.ts.jinja

@@ -12,7 +12,7 @@ export class {{ class_name }} {
   }
 
 {% for operation in operations %}
-  {{ operation }}
+{{ operation }}
 
 {% endfor %}
 }

django_cfg/modules/django_client/core/generator/{templates/typescript → typescript/templates}/client/client.ts.jinja

@@ -7,6 +7,7 @@ import { {{ tag.class_name }} } from "./{{ tag.slug }}";
 import { HttpClientAdapter, FetchAdapter } from "./http";
 import { APIError, NetworkError } from "./errors";
 import { APILogger, type LoggerConfig } from "./logger";
+import { withRetry, type RetryConfig } from "./retry";
 
 
 {% endif %}
@@ -29,6 +30,7 @@ export class APIClient {
   private baseUrl: string;
   private httpClient: HttpClientAdapter;
   private logger: APILogger | null = null;
+  private retryConfig: RetryConfig | null = null;
 
   // Sub-clients
 {% for tag in tags %}
@@ -40,6 +42,7 @@ export class APIClient {
     options?: {
       httpClient?: HttpClientAdapter;
       loggerConfig?: Partial<LoggerConfig>;
+      retryConfig?: RetryConfig;
     }
   ) {
     this.baseUrl = baseUrl.replace(/\/$/, '');
@@ -50,6 +53,11 @@ export class APIClient {
       this.logger = new APILogger(options.loggerConfig);
     }
 
+    // Store retry configuration
+    if (options?.retryConfig !== undefined) {
+      this.retryConfig = options.retryConfig;
+    }
+
     // Initialize sub-clients
 {% for tag in tags %}
     this.{{ tag.property }} = new {{ tag.class_name }}(this);
@@ -71,6 +79,7 @@ export class APIClient {
 
   /**
    * Make HTTP request with Django CSRF and session handling.
+   * Automatically retries on network errors and 5xx server errors.
    */
   async request<T>(
     method: string,
@@ -80,6 +89,41 @@ export class APIClient {
       body?: any;
       formData?: FormData;
     }
+  ): Promise<T> {
+    // Wrap request in retry logic if configured
+    if (this.retryConfig) {
+      return withRetry(() => this._makeRequest<T>(method, path, options), {
+        ...this.retryConfig,
+        onFailedAttempt: (info) => {
+          // Log retry attempts
+          if (this.logger) {
+            this.logger.warn(
+              `Retry attempt ${info.attemptNumber}/${info.retriesLeft + info.attemptNumber} ` +
+              `for ${method} ${path}: ${info.error.message}`
+            );
+          }
+          // Call user's onFailedAttempt if provided
+          this.retryConfig?.onFailedAttempt?.(info);
+        },
+      });
+    }
+
+    // No retry configured, make request directly
+    return this._makeRequest<T>(method, path, options);
+  }
+
+  /**
+   * Internal request method (without retry wrapper).
+   * Used by request() method with optional retry logic.
+   */
+  private async _makeRequest<T>(
+    method: string,
+    path: string,
+    options?: {
+      params?: Record<string, any>;
+      body?: any;
+      formData?: FormData;
+    }
   ): Promise<T> {
     const url = new URL(path, this.baseUrl);
     const startTime = Date.now();
@@ -216,6 +260,7 @@ export class APIClient {
 import * as Enums from "./enums";
 import { HttpClientAdapter, FetchAdapter } from "./http";
 import { APIError, NetworkError } from "./errors";
+import { withRetry, type RetryConfig } from "./retry";
 
 
 /**
@@ -235,13 +280,22 @@ import { APIError, NetworkError } from "./errors";
 export class APIClient {
   private baseUrl: string;
   private httpClient: HttpClientAdapter;
+  private retryConfig: RetryConfig | null = null;
 
   constructor(
     baseUrl: string,
-    options?: { httpClient?: HttpClientAdapter }
+    options?: {
+      httpClient?: HttpClientAdapter;
+      retryConfig?: RetryConfig;
+    }
   ) {
     this.baseUrl = baseUrl.replace(/\/$/, '');
     this.httpClient = options?.httpClient || new FetchAdapter();
+
+    // Store retry configuration
+    if (options?.retryConfig !== undefined) {
+      this.retryConfig = options.retryConfig;
+    }
   }
 
   /**
@@ -259,6 +313,7 @@ export class APIClient {
 
   /**
    * Make HTTP request with Django CSRF and session handling.
+   * Automatically retries on network errors and 5xx server errors.
    */
   private async request<T>(
     method: string,
@@ -268,6 +323,27 @@ export class APIClient {
       body?: any;
       formData?: FormData;
     }
+  ): Promise<T> {
+    // Wrap request in retry logic if configured
+    if (this.retryConfig) {
+      return withRetry(() => this._makeRequest<T>(method, path, options), this.retryConfig);
+    }
+
+    // No retry configured, make request directly
+    return this._makeRequest<T>(method, path, options);
+  }
+
+  /**
+   * Internal request method (without retry wrapper).
+   */
+  private async _makeRequest<T>(
+    method: string,
+    path: string,
+    options?: {
+      params?: Record<string, any>;
+      body?: any;
+      formData?: FormData;
+    }
   ): Promise<T> {
     const url = new URL(path, this.baseUrl);
 

django_cfg/modules/django_client/core/generator/{templates/typescript → typescript/templates}/client/main_client_file.ts.jinja

@@ -4,6 +4,7 @@ import { {{ tag.class_name }} } from "./{{ tag.slug }}";
 import { HttpClientAdapter, FetchAdapter } from "./http";
 import { APIError, NetworkError } from "./errors";
 import { APILogger, type LoggerConfig } from "./logger";
+import { withRetry, type RetryConfig } from "./retry";
 
 
 {{ client_code }}

django_cfg/modules/django_client/core/generator/{templates/typescript → typescript/templates}/client/sub_client.ts.jinja

@@ -2,14 +2,14 @@
  * API endpoints for {{ tag }}.
  */
 class {{ class_name }} {
-  private client: APIClient;
+  private client: any;
 
-  constructor(client: APIClient) {
+  constructor(client: any) {
     this.client = client;
   }
 
 {% for operation in operations %}
-  {{ operation }}
+{{ operation }}
 
 {% endfor %}
 }

django_cfg/modules/django_client/core/generator/typescript/templates/fetchers/fetchers.ts.jinja

@@ -0,0 +1,45 @@
+/**
+ * Typed fetchers for {{ tag_display_name }}
+ *
+ * Universal functions that work in any environment:
+ * - Next.js (App Router / Pages Router / Server Components)
+ * - React Native
+ * - Node.js backend
+ *
+ * These fetchers use Zod schemas for runtime validation.
+ *
+ * Usage:
+ * ```typescript
+ * // Configure API once (in your app entry point)
+ * import { configureAPI } from '../../api-instance'
+ * configureAPI({ baseUrl: 'https://api.example.com' })
+ *
+ * // Then use fetchers anywhere
+ * const users = await getUsers({ page: 1 })
+ *
+ * // With SWR
+ * const { data } = useSWR(['users', params], () => getUsers(params))
+ *
+ * // With React Query
+ * const { data } = useQuery(['users', params], () => getUsers(params))
+ *
+ * // In Server Component or SSR (pass custom client)
+ * import { API } from '../../index'
+ * const api = new API('https://api.example.com')
+ * const users = await getUsers({ page: 1 }, api)
+ * ```
+ */
+{% if has_schemas %}
+{% for schema_name in schema_names %}
+import { {{ schema_name }}Schema, type {{ schema_name }} } from '../schemas/{{ schema_name }}.schema'
+{% endfor %}
+{% endif %}
+{% if has_client %}
+import { getAPIInstance } from '../../api-instance'
+import type { API } from '../../index'
+{% endif %}
+
+{% for fetcher in fetchers %}
+{{ fetcher }}
+
+{% endfor %}