@rubriqflow/contracts

Immutable TypeScript interface contracts for RubriqFlow applications.

🎯 Purpose

This package provides pure TypeScript interfaces with ZERO runtime dependencies. It serves as the immutable contract layer for all RubriqFlow applications, ensuring type safety and consistency across the entire platform.

✨ Key Features

• 🔒 Immutable Contracts: Interfaces never change without version bump
• 🚫 Zero Dependencies: No runtime dependencies, pure TypeScript
• 📦 Semantic Versioning: Independent versioning lifecycle
• 🏗️ Interface Segregation: Clean, focused interface design
• 🧪 100% Test Coverage: Comprehensive test suite
• 📚 Full Documentation: TSDoc comments for all interfaces

📦 Installation

npm install @rubriqflow/contracts
# or
yarn add @rubriqflow/contracts
# or
pnpm add @rubriqflow/contracts

🚀 Quick Start

import { 
  IUserRepository, 
  IAuthService, 
  UserRecord, 
  AuthResult 
} from '@rubriqflow/contracts';

// Use interfaces in your implementations
class DatabaseUserRepository implements IUserRepository {
  async create(input: CreateUserInput): Promise<UserRecord> {
    // Implementation here
  }
  
  async getById(id: string): Promise<UserRecord | null> {
    // Implementation here
  }
  
  // ... implement all interface methods
}

// Use types in your code
const user: UserRecord = {
  id: 'user_123',
  email: '[email protected]',
  firstName: 'John',
  lastName: 'Doe',
  // ... other required fields
};

📋 Available Interfaces

🔐 Authentication & Authorization

• IAuthService - Authentication and authorization operations
• IUserRepository - User data access operations
• IOrganizationRepository - Organization data access operations

📧 Communication

• IEmailService - Email sending and template management
• IFileStorageService - File upload, download, and management

🎭 Event System

• IEventBus - Event-driven architecture support

📝 Type Definitions

• UserRecord - User data structure
• OrganizationRecord - Organization data structure
• AuthResult - Authentication result
• BaseEvent - Event system foundation

🏗️ Architecture Principles

1. Interface Segregation Principle (ISP)

Each interface focuses on a single responsibility:

// ✅ GOOD: Focused interface
interface IUserReader {
  getById(id: string): Promise<UserRecord | null>;
  getByEmail(email: string): Promise<UserRecord | null>;
}

interface IUserWriter {
  create(input: CreateUserInput): Promise<UserRecord>;
  update(input: UpdateUserInput): Promise<UserRecord>;
  delete(id: string): Promise<void>;
}

// ❌ BAD: Monolithic interface
interface IUserRepository {
  // 50+ methods mixing read/write operations
}

2. Immutable Contracts

Interfaces are treated as immutable contracts:

// ✅ GOOD: Add new methods in new version
interface IUserRepositoryV2 extends IUserRepository {
  getByOrganization(orgId: string): Promise<UserRecord[]>;
}

// ❌ BAD: Modify existing interface
interface IUserRepository {
  // Changing existing method signature breaks all implementations
  getById(id: string, includeDeleted?: boolean): Promise<UserRecord | null>;
}

3. Zero Dependencies

No runtime dependencies means no version conflicts:

{
  "dependencies": {},
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

🧪 Testing

The contracts package includes comprehensive tests to ensure interface integrity:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Test Categories

1. Interface Structure Tests - Verify interfaces exist and are properly structured
2. Type Safety Tests - Ensure TypeScript compilation works correctly
3. Immutability Tests - Verify interfaces are treated as immutable
4. Contract Completeness Tests - Ensure all expected interfaces are exported

📚 Documentation

All interfaces include comprehensive TSDoc comments:

/**
 * User Repository Interface
 * Contract for user data access operations
 * 
 * @example
 * ```typescript
 * class DatabaseUserRepository implements IUserRepository {
 *   async create(input: CreateUserInput): Promise<UserRecord> {
 *     // Implementation
 *   }
 * }
 * ```
 */
export interface IUserRepository {
  /**
   * Create a new user
   * @param input - User creation data
   * @returns Promise resolving to created user record
   * @throws {ValidationError} When input data is invalid
   */
  create(input: CreateUserInput): Promise<UserRecord>;
}

🔄 Versioning

This package follows Semantic Versioning:

• MAJOR (1.0.0 → 2.0.0): Breaking changes to existing interfaces
• MINOR (1.0.0 → 1.1.0): New interfaces or non-breaking additions
• PATCH (1.0.0 → 1.0.1): Bug fixes or documentation updates

Breaking Changes

Breaking changes require creating new interface versions:

// v1.0.0
interface IUserRepository {
  getById(id: string): Promise<UserRecord | null>;
}

// v2.0.0 - Breaking change
interface IUserRepositoryV2 {
  getById(id: string, options?: GetUserOptions): Promise<UserRecord | null>;
}

// Keep old interface for backward compatibility
interface IUserRepository {
  getById(id: string): Promise<UserRecord | null>;
}

🏢 Usage in Applications

RubriqFlow v2

// v2/lib/implementations/repositories/DatabaseUserRepository.ts
import { IUserRepository, UserRecord, CreateUserInput } from '@rubriqflow/contracts';

export class DatabaseUserRepository implements IUserRepository {
  // Implementation using Drizzle ORM
}

FileDrop MVP

// filedrop/lib/implementations/repositories/FileDropUserRepository.ts
import { IUserRepository, UserRecord, CreateUserInput } from '@rubriqflow/contracts';

export class FileDropUserRepository implements IUserRepository {
  // Implementation using same contracts
}

🤝 Contributing

1. Interface Changes: Create new interface versions, don't modify existing ones
2. Documentation: Add TSDoc comments for all new interfaces
3. Tests: Write tests for new interfaces
4. Versioning: Update version according to semantic versioning rules

📄 License

MIT License - see LICENSE file for details.

🔗 Related Packages

• @rubriqflow/core - Business logic implementations
• @rubriqflow/database - Database schema and utilities
• @rubriqflow/ui-components - React component library

📊 Package Statistics

• Interfaces: 11 total
• Type Definitions: 25+ types
• Bundle Size: ~0KB (TypeScript only)
• Dependencies: 0 runtime dependencies
• Test Coverage: 100%

Built with ❤️ by the RubriqFlow Team