chore: Refactor the TypeScript generator to share the logic with the Golang generator (#42129)

Author: vdekrijger

posthog/api/event_definition.py

@@ -1,4 +1,3 @@
-from datetime import datetime
 from typing import Any, Literal, Optional, cast
 
 from django.core.cache import cache
@@ -10,6 +9,7 @@
 
 from posthog.api.event_definition_generators.base import EventDefinitionGenerator
 from posthog.api.event_definition_generators.golang import GolangGenerator
+from posthog.api.event_definition_generators.typescript import TypeScriptGenerator
 from posthog.api.routing import TeamAndOrgViewSetMixin
 from posthog.api.shared import UserBasicSerializer
 from posthog.api.tagged_item import TaggedItemSerializerMixin, TaggedItemViewSetMixin
@@ -402,260 +402,28 @@ def destroy(self, request: request.Request, *args: Any, **kwargs: Any) -> respon
 
     @action(detail=False, methods=["GET"], url_path="typescript", required_scopes=["event_definition:read"])
     def typescript_definitions(self, *args, **kwargs):
-        """Generate TypeScript definitions from event schemas"""
-        # Version of the TypeScript generator - increment when changing the structure
-        # This ensures clients update even when schemas don't change
-        # TODO migrate to its own custom generator.
-        generator_version = "1.0.0"
-        language = "TypeScript"
-
-        # Fetch event definitions and schemas using shared helper
-        event_definitions, schema_map = EventDefinitionGenerator.fetch_event_definitions_and_schemas(self.project_id)
-
-        # Calculate the deterministic hash for this update
-        schema_hash = EventDefinitionGenerator.calculate_schema_hash(
-            generator_version,
-            event_definitions,
-            schema_map,
-        )
-
-        # Generate TypeScript definitions
-        ts_content = self._generate_typescript(generator_version, event_definitions, schema_map)
-
-        # Report telemetry for this generation request
-        EventDefinitionGenerator.record_report_generation(
-            language, generator_version, self.request.user, self.team_id, self.project_id
-        )
-
-        return response.Response(
-            {
-                "content": ts_content,
-                "event_count": len(event_definitions),
-                "schema_hash": schema_hash,
-                "generator_version": generator_version,
-            }
-        )
-
-    def _generate_typescript(self, generator_version: str, event_definitions, schema_map):
-        """Generate complete TypeScript module with type definitions and exports"""
-        # Generate file header
-        header = f"""/**
- * GENERATED FILE - DO NOT EDIT
- *
- * This file was auto-generated by PostHog
- * Generated at: {datetime.now().isoformat()}
- * Generator version: {generator_version}
- *
- * Provides capture() for type-safe events and captureRaw() for flexibility
- */
-import originalPostHog from 'posthog-js'
-import type {{ CaptureOptions, CaptureResult, PostHog as OriginalPostHog, Properties }} from 'posthog-js'
-"""
-
-        # Generate event schemas interface
-        event_schemas_lines = [
-            "// Define event schemas with their required and optional fields",
-            "interface EventSchemas {",
-        ]
-
-        for event_def in event_definitions:
-            properties = schema_map.get(str(event_def.id), [])
-            event_name_json = orjson.dumps(event_def.name).decode("utf-8")
-
-            if not properties:
-                event_schemas_lines.append(f"    {event_name_json}: Record<string, any>")
-            else:
-                event_schemas_lines.append(f"    {event_name_json}: {{")
-                for prop in properties:
-                    ts_type = self._map_property_type(prop.property_type)
-                    optional_marker = "" if prop.is_required else "?"
-                    # Use orjson.dumps() for proper escaping of property names
-                    prop_name_json = orjson.dumps(prop.name).decode("utf-8")
-                    event_schemas_lines.append(f"        {prop_name_json}{optional_marker}: {ts_type}")
-                event_schemas_lines.append("    }")
-
-        event_schemas_lines.append("}")
-        event_schemas = "\n".join(event_schemas_lines)
-
-        # Generate type aliases
-        type_aliases = """
-// Type alias for all valid event names
-export type EventName = keyof EventSchemas
-
-// Type helper to get properties for a specific event
-// Intersects the schema with Record<string, any> to allow additional properties
-export type EventProperties<K extends EventName> = EventSchemas[K] & Record<string, any>
-
-// Helper type to check if a type has required properties
-type HasRequiredProperties<K extends EventName> = {} extends EventSchemas[K] ? false : true
-
-// Helper to detect if T is exactly 'string' (not a literal)
-type IsExactlyString<T> = string extends T ? (T extends string ? true : false) : false
-"""
-
-        # Generate TypedPostHog interface
-        typed_posthog_interface = """
-// Enhanced PostHog interface with typed capture
-interface TypedPostHog extends Omit<OriginalPostHog, 'capture'> {
-    /**
-     * Type-safe capture for defined events, or flexible capture for undefined events
-     *
-     * Note: For defined events, wrap properties in a variable to allow additional properties:
-     * const props = { file_size_b: 100, extra: 'data' }
-     * posthog.capture('downloaded_file', props)
-     *
-     * @example
-     * // Defined event with type safety
-     * posthog.capture('uploaded_file', {
-     *   file_name: 'test.txt',
-     *   file_size_b: 100
-     * })
-     *
-     * @example
-     * // For events with all optional properties, properties argument is optional
-     * posthog.capture('logged_out') // no properties needed
-     *
-     * @example
-     * // Undefined events work with arbitrary properties
-     * posthog.capture('custom_event', { whatever: 'data' })
-     * posthog.capture('another_event') // or no properties
-     */
-    // Overload 1: For known events (specific EventName literals)
-    // This should match first for all known event names
-    capture<K extends EventName>(
-        event_name: K,
-        ...args: HasRequiredProperties<K> extends true
-            ? [properties: EventProperties<K>, options?: CaptureOptions]
-            : [properties?: EventProperties<K>, options?: CaptureOptions]
-    ): CaptureResult | undefined
-
-    // Overload 2: For undefined events and blocking string variables
-    // Only matches if event_name is NOT a known EventName
-    // The conditional type rejects broad string type
-    capture<T extends string>(
-        event_name: IsExactlyString<T> extends true ? never : (T extends EventName ? never : T),
-        properties?: Properties | null,
-        options?: CaptureOptions
-    ): CaptureResult | undefined
-
-    /**
-     * Raw capture for any event (original behavior, no type checking)
-     *
-     * Use capture() for type-safe defined events or flexible undefined events.
-     * Use captureRaw() only when you need to bypass all type checking.
-     *
-     * @example
-     * posthog.captureRaw('Any Event Name', { whatever: 'data' })
-     */
-    captureRaw(event_name: string, properties?: Properties | null, options?: CaptureOptions): CaptureResult | undefined
-}
-"""
-
-        # Generate implementation
-        implementation = """
-// Create the implementation
-const createTypedPostHog = (original: OriginalPostHog): TypedPostHog => {
-    // Create the enhanced PostHog object
-    const enhanced: TypedPostHog = Object.create(original)
-
-    // Add capture method (type-safe for defined events, flexible for undefined)
-    enhanced.capture = function (event_name: string, ...args: any[]): CaptureResult | undefined {
-        const [properties, options] = args
-        return original.capture(event_name, properties, options)
-    }
-
-    // Add captureRaw method for untyped/flexible event tracking
-    enhanced.captureRaw = function (
-        event_name: string,
-        properties?: Properties | null,
-        options?: CaptureOptions
-    ): CaptureResult | undefined {
-        return original.capture(event_name, properties, options)
-    }
-
-    // Proxy to delegate all other properties/methods to the original
-    return new Proxy(enhanced, {
-        get(target, prop) {
-            if (prop in target) {
-                return (target as any)[prop]
-            }
-            return (original as any)[prop]
-        },
-        set(target, prop, value) {
-            ;(original as any)[prop] = value
-            return true
-        },
-    })
-}
-"""
-
-        # Generate exports
-        exports = """
-// Create and export the typed instance
-const posthog = createTypedPostHog(originalPostHog as OriginalPostHog)
-
-export default posthog
-export type { EventSchemas, TypedPostHog }
-
-// Re-export everything else from posthog-js
-export * from 'posthog-js'
-
-/**
- * USAGE GUIDE
- * ===========
- *
- * For type-safe defined events (recommended):
- *   posthog.capture('uploaded_file', { file_name: 'test.txt', file_size_b: 100 })
- *
- * For undefined events (flexible):
- *   posthog.capture('Custom Event', { whatever: 'data' })
- *
- * For bypassing all type checking (rare):
- *   posthog.captureRaw('Any Event', { whatever: 'data' })
- */
-"""
-
-        # Combine all sections
-        return header + event_schemas + type_aliases + typed_posthog_interface + implementation + exports
-
-    def _map_property_type(self, property_type: str) -> str:
-        """Map PostHog property types to TypeScript types"""
-        type_map = {
-            "String": "string",
-            "Numeric": "number",
-            "Boolean": "boolean",
-            "DateTime": "string | Date",
-            "Array": "any[]",
-            "Object": "Record<string, any>",
-        }
-        return type_map.get(property_type, "any")
+        return self._generate_definitions(TypeScriptGenerator())
 
     @action(detail=False, methods=["GET"], url_path="golang", required_scopes=["event_definition:read"])
     def golang_definitions(self, *args, **kwargs):
-        """Generate Go code definitions from event schemas"""
-        generator = GolangGenerator()
+        return self._generate_definitions(GolangGenerator())
 
-        # Fetch event definitions and schemas using shared helper
-        event_definitions, schema_map = EventDefinitionGenerator.fetch_event_definitions_and_schemas(self.project_id)
+    def _generate_definitions(self, generator: EventDefinitionGenerator) -> response.Response:
+        event_definitions, schema_map = generator.fetch_event_definitions_and_schemas(self.project_id)
 
-        # Calculate the deterministic hash for this update
-        schema_hash = generator.calculate_schema_hash(generator.generator_version(), event_definitions, schema_map)
+        schema_hash = generator.calculate_schema_hash(event_definitions, schema_map)
 
-        # Generate Go code using the generator
-        go_content = generator.generate(event_definitions, schema_map)
+        content = generator.generate(event_definitions, schema_map)
 
-        # Report telemetry for this generation request
         generator.record_report_generation(
-            generator.language_name(),
-            generator.generator_version(),
             self.request.user,
             self.team_id,
             self.project_id,
         )
 
         return response.Response(
             {
-                "content": go_content,
+                "content": content,
                 "event_count": len(event_definitions),
                 "schema_hash": schema_hash,
                 "generator_version": generator.generator_version(),

posthog/api/event_definition_generators/base.py

@@ -38,24 +38,12 @@ def generate(
         """
         pass
 
-    @abstractmethod
-    def map_property_type(self, property_type: str) -> str:
-        """
-        Map PostHog property types to target language types.
-        Implement this in subclasses for language-specific type mappings.
-        """
-        pass
-
-    @staticmethod
     def calculate_schema_hash(
-        generator_version: str,
+        self,
         event_definitions: QuerySet[EventDefinition],
         schema_map: dict[str, list[SchemaPropertyGroupProperty]],
     ) -> str:
         """
-        Note: This is a `staticmethod` temporarily only until the typescript generator has been migrated to this
-        setup as well.
-
         Calculate a deterministic hash of the event schemas and generator version.
         The hash is used by clients to know when to regenerate their code.
         """
@@ -71,41 +59,32 @@ def calculate_schema_hash(
 
         # Include generator version to force regeneration on structural changes
         hash_input = {
-            "version": generator_version,
+            "version": self.generator_version(),
             "schemas": schema_data,
         }
 
         return hashlib.sha256(orjson.dumps(hash_input, option=orjson.OPT_SORT_KEYS)).hexdigest()[:32]
 
-    @staticmethod
-    def record_report_generation(
-        language_name: str, generator_version: str, user, team_id: int, project_id: int
-    ) -> None:
+    def record_report_generation(self, user, team_id: int, project_id: int) -> None:
         """
-        Note: This is a `staticmethod` temporarily only until the typescript generator has been migrated to this
-        setup as well.
-
         A convenience method to structurally report telemetry for code generation.
         """
         report_user_action(
             user,
             "event definitions generated",
             {
-                "language": language_name,
-                "generator_version": generator_version,
+                "language": self.language_name(),
+                "generator_version": self.generator_version(),
                 "team_id": team_id,
                 "project_id": project_id,
             },
         )
 
-    @staticmethod
     def fetch_event_definitions_and_schemas(
+        self,
         project_id: int,
     ) -> tuple[QuerySet[EventDefinition], dict[str, list[SchemaPropertyGroupProperty]]]:
         """
-        Note: This is a `staticmethod` temporarily only until the typescript generator has been migrated to this
-        setup as well.
-
         Fetch event definitions and build schema map. The key of `schema_map` references a EventDefinition.ID
         from the returned event_definitions set.
         """

posthog/api/event_definition_generators/golang.py

@@ -196,7 +196,7 @@ def _generate_option_function(
         used_function_names: set[str],
     ) -> str:
         """Generate a With* option function for an optional property"""
-        param_type = self.map_property_type(prop.property_type)
+        param_type = self._map_property_type(prop.property_type)
         prop_name = self._escape_go_string(prop.name)
         param_name = self._to_go_param_name(prop_name)
         suffix = self._to_pascal_name(prop_name)
@@ -228,7 +228,7 @@ def _generate_capture_function(
             param_name = self._get_unique_name(self._to_go_param_name(prop_name), used_param_names)
             props_init_lines.append(f"\t\t{prop_name}: {param_name},")
 
-            param_type = self.map_property_type(prop.property_type)
+            param_type = self._map_property_type(prop.property_type)
             params.append(f"{param_name} {param_type}")
 
         params_str = ",\n\t".join(params)
@@ -275,7 +275,7 @@ def _generate_capture_from_base_function(
             param_name = self._get_unique_name(self._to_go_param_name(prop_name), used_param_names)
             props_init_lines.append(f"\t\t{prop_name}: {param_name},")
 
-            param_type = self.map_property_type(prop.property_type)
+            param_type = self._map_property_type(prop.property_type)
             params.append(f"{param_name} {param_type}")
 
         params_str = ",\n\t".join(params)
@@ -306,7 +306,7 @@ def _generate_capture_from_base_function(
 }}
 """
 
-    def map_property_type(self, property_type: str) -> str:
+    def _map_property_type(self, property_type: str) -> str:
         type_map = {
             "String": "string",
             "Numeric": "float64",