Subtitle Conversion Function Implementation

[BleedingDev]

Overview

Implement a type-safe function for converting strongly typed subtitle data objects into multiple output formats (SRT, VTT, plain text). The function should be built using EffectTS and be completely environment agnostic, supporting browser, Node.js, Bun, Cloudflare Workers, and AWS Lambda environments.

Business Context

Our API currently returns subtitle data in raw JSON format. We need to provide users with flexibility to choose their preferred output format(s) when consuming our API. This will improve user experience and reduce client-side processing requirements.

Requirements

Core Functionality

• Accept strongly typed subtitle data object as input
• Support multiple output format conversions from a single source object
• Provide type-safe error handling throughout the conversion process
• Enable users to request one or multiple output formats in a single API call
• Integrate seamlessly with existing codebase architecture

Supported Output Formats

1. JSON - Serialized JSON string from the typed object (current default)
2. SRT - SubRip subtitle format
3. VTT - WebVTT (Web Video Text Tracks) format
4. Plain Text - Formatted as readable sentences with logical paragraph breaks

Technical Constraints

• Must use EffectTS for implementation
• Must be environment agnostic (no environment-specific APIs)
• All errors must be type-safe and properly typed
• Input is strongly typed object, output is string
• No dependencies on Node.js-specific modules, browser-specific APIs, or any environment-specific features

Acceptance Criteria

Function Implementation

• Function accepts strongly typed subtitle data object as input
• Function returns converted subtitle data as string output
• Input object type is properly defined with all necessary fields
• All conversion logic is Effect-based with proper error types
• Function runs successfully in all target environments: browser, Node.js, Bun, Cloudflare Workers, AWS Lambda
• No environment-specific APIs or modules are used
• Function integrates cleanly with existing codebase patterns

Format Conversions

• Object to JSON string conversion properly serializes all data
• Object to SRT conversion maintains all timing and text data
• Object to VTT conversion includes proper WebVTT headers and formatting
• Object to plain text conversion produces readable paragraphs
• All conversions preserve the original content without data loss

API Integration

• API accepts output format parameter(s) in requests
• API supports single format requests (e.g., format=srt)
• API supports multiple format requests (e.g., format=srt,vtt)
• Use-case layer properly calls the conversion function based on format parameter
• API returns data in requested format(s)
• When multiple formats requested, response structure clearly identifies each format

Error Handling

• Invalid or malformed input object returns typed error with clear message
• Unsupported format requests return typed error
• Missing required fields in input object return typed error with specific issue
• All errors are type-safe and catchable using Effect error handling
• Errors integrate with existing error handling patterns in the codebase

Type Safety

• Input object type includes all required subtitle data fields
• Type definitions prevent passing invalid data structures
• Output format enum/union type ensures only valid formats can be requested
• Return type properly reflects single vs multiple format outputs

Testing

• Unit tests cover all format conversions
• Tests verify type safety with invalid input objects
• Tests verify function works in different environments (via test runners)
• Error cases are thoroughly tested
• Integration tests verify API parameter handling

Documentation

• Function signature and usage documented in code
• Input object type structure documented
• Error types documented with handling examples
• API parameter documentation updated with format options
• Examples provided for single and multiple format requests

Implementation Notes

• Define clear interface/type for the subtitle data object
• Follow existing codebase patterns for Effect usage
• Place function in appropriate utility module following project structure
• Ensure function signature aligns with existing use-case layer expectations
• Consider performance implications when multiple formats are requested

Success Metrics

• Users can successfully convert subtitle data to their preferred format(s)
• Zero runtime errors due to type mismatches
• Function works identically across all target environments
• API response time remains consistent regardless of output format
• Seamless integration with no breaking changes to existing functionality