Migrate Backend to Strict TypeScript

launchdarkly/react/.tsbuildinfo

@@ -0,0 +1 @@
+{"fileNames":[],"fileInfos":[],"root":[],"options":{"allowSyntheticDefaultImports":true,"esModuleInterop":true,"module":1,"skipLibCheck":true,"target":9,"tsBuildInfoFile":"./.tsbuildinfo"},"version":"5.8.3"}

launchdarkly/react/ARCHITECTURE.md

@@ -0,0 +1,156 @@
+# Domain-API Type Separation Architecture
+
+This document describes the new architecture that separates internal domain types from external API representation types.
+
+## Overview
+
+The codebase has been refactored to implement a clear separation between:
+- **Domain Models**: Internal business logic types that represent core entities
+- **API Types**: External communication types for requests and responses
+- **Transformers**: Functions that convert between domain and API representations
+
+## Directory Structure
+
+```
+launchdarkly/react/
+├── domain/           # Internal domain models for business logic
+│   ├── common.ts     # Common domain types and branded identifiers
+│   ├── user.ts       # User domain model and business interfaces
+│   ├── feature-flag.ts # Feature flag domain model and evaluation logic
+│   ├── analytics.ts  # Analytics domain model and event tracking
+│   └── index.ts      # Domain type exports
+├── api/              # External API request/response types
+│   ├── common-api.ts # Common API types and RPC structures
+│   ├── user-api.ts   # User API request/response schemas
+│   ├── feature-flag-api.ts # Feature flag API schemas
+│   ├── analytics-api.ts # Analytics API schemas
+│   └── index.ts      # API type exports
+├── transformers/     # Transformation functions between domain and API
+│   ├── user-transformer.ts # User domain ↔ API transformations
+│   ├── feature-flag-transformer.ts # Feature flag transformations
+│   ├── analytics-transformer.ts # Analytics transformations
+│   └── index.ts      # Transformer exports
+└── rpc-interfaces.ts # Legacy types (deprecated)
+```
+
+## Key Principles
+
+### 1. Domain-Driven Design
+- **Domain models** represent business concepts and rules
+- Types use branded identifiers for type safety: `UserId`, `FlagKey`, `EventId`
+- Domain interfaces define business operations: `UserService`, `FeatureFlagService`
+
+### 2. API Boundary Isolation
+- **API types** are pure data transfer objects
+- No business logic in API types
+- Simple, serializable structures for external communication
+
+### 3. Transformation Layer
+- **Transformers** handle all conversions between domain and API types
+- Bidirectional transformations: `domainToApi` and `apiToDomain`
+- Array helpers for bulk operations
+
+## Usage Examples
+
+### Domain Types (Business Logic)
+```typescript
+import { User, CreateUserRequest, UserService } from './domain';
+
+// Business logic uses domain types
+class UserBusinessLogic implements UserService {
+  async createUser(request: CreateUserRequest): Promise<User> {
+    // Business validation and logic here
+    return await this.repository.create(request);
+  }
+}
+```
+
+### API Types (External Communication)
+```typescript
+import { CreateUserApiRequest, CreateUserApiResponse } from './api';
+
+// API layer uses API types
+async function handleCreateUserRequest(
+  apiRequest: CreateUserApiRequest
+): Promise<CreateUserApiResponse> {
+  // HTTP/RPC communication logic here
+}
+```
+
+### Transformers (Boundary Translation)
+```typescript
+import { createUserRequestFromApi, userToApiResponse } from './transformers';
+
+// Convert API request to domain model
+const domainRequest = createUserRequestFromApi(apiRequest);
+
+// Process in business layer
+const domainUser = await userService.createUser(domainRequest);
+
+// Convert domain model back to API response
+const apiResponse = userToApiResponse(domainUser);
+```
+
+## Benefits
+
+### 1. Clear Separation of Concerns
+- Domain logic is isolated from API serialization concerns
+- Business rules don't leak into API contracts
+- API changes don't affect business logic
+
+### 2. Type Safety
+- Branded types prevent mixing of different ID types
+- Compile-time validation of transformations
+- Explicit boundaries between layers
+
+### 3. Maintainability
+- Changes to API schemas don't break business logic
+- Domain models evolve independently
+- Easier testing with focused concerns
+
+### 4. Flexibility
+- Multiple API versions can map to same domain models
+- Different transport protocols (HTTP, WebSocket, gRPC) use same domain logic
+- Easy to add new API endpoints without changing business logic
+
+## Migration Guide
+
+### For New Code
+1. Use domain types for all business logic
+2. Use API types for external communication
+3. Use transformers at the boundary
+
+### For Existing Code
+1. `rpc-interfaces.ts` is now deprecated but maintained for compatibility
+2. Gradually migrate to new structure
+3. Import from `./domain`, `./api`, or `./transformers` instead
+
+### Example Migration
+```typescript
+// Old approach (mixed concerns)
+import { UserOutput, CreateUserInput } from './rpc-interfaces';
+
+// New approach (separated concerns)
+import { User, CreateUserRequest } from './domain';
+import { CreateUserApiRequest, UserApiResponse } from './api';
+import { createUserRequestFromApi, userToApiResponse } from './transformers';
+```
+
+## Best Practices
+
+1. **Never import domain types in API layer**
+2. **Never import API types in domain layer**
+3. **Always use transformers at boundaries**
+4. **Keep transformers pure (no side effects)**
+5. **Validate at boundaries, not in transformers**
+6. **Use branded types for type safety**
+7. **Keep API types serializable**
+8. **Keep domain types focused on business rules**
+
+## File Organization Rules
+
+- `domain/`: Only business logic types and interfaces
+- `api/`: Only serializable request/response types
+- `transformers/`: Only pure transformation functions
+- No circular dependencies between layers
+- Transformers can import from both domain and API layers