@johnqh/types

@johnqh/types

Comprehensive TypeScript type definitions and utilities for the 0xmail.box Web3 email ecosystem.

🚀 Overview

This package provides a complete type-safe foundation for 0xmail.box applications, featuring:

• 267 comprehensive tests ensuring type reliability
• Zero runtime dependencies for optimal performance
• Dual module support (ESM + CommonJS)
• Complete TypeScript coverage with strict type checking
• AI-friendly documentation for enhanced development experience

📦 Features

Core Type System

• Business Logic Types: Email, User, WalletData, MailBox interfaces
• Blockchain Types: Multi-chain support (Ethereum, Solana, Polygon, etc.)
• API Types: Complete request/response type definitions
• Infrastructure Types: Analytics, navigation, network client abstractions
• Utility Types: Optional<T>, Result<T, E>, ValidationResult<T>

Utilities & Helpers

• Address Validation: EVM, Solana, ENS, SNS address validation
• Blockchain Utilities: Network configuration, chain detection, event helpers
• Formatting: Date, currency, string formatting utilities
• Validation: Type guards, schema validation, Web3 username validation
• URL Management: Type-safe URL parameter handling

Development Features

• Tree Shakeable: Import only what you need
• Framework Agnostic: Works with React, Vue, Node.js, React Native
• Zero Config: Ready to use out of the box
• Type-Safe: Complete IntelliSense support

🛠 Installation

npm install @johnqh/types

📖 Usage Examples

Basic Types

import {
  Email,
  User,
  WalletUserData,
  AuthStatus,
  ChainType,
  Optional
} from '@johnqh/types';

// Email handling
const email: Email = {
  from: '[e-mail]',
  to: '[e-mail]',
  subject: 'Web3 Email',
  body: 'Hello from the blockchain!',
  id: 'msg_123',
  timestamp: Date.now(),
  read: false
};

// User management with optional fields
const user: WalletUserData = {
  walletAddress: '0x742d35Cc6634C0532925a3b8D2C36B7f12345678',
  chainType: ChainType.EVM,
  emails: [email],
  folders: []
};

// Optional type usage
const maybeUser: Optional<User> = null; // T | undefined | null

Blockchain Integration

import {
  Message,
  TransactionResult,
  MessageType,
  isEvmAddress,
  isSolanaAddress
} from '@johnqh/types';

// Multi-chain message
const message: Message = {
  from: '0x742d35Cc6634C0532925a3b8D2C36B7f12345678',
  to: '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM',
  subject: 'Cross-chain message',
  body: 'EVM to Solana communication',
  timestamp: Date.now(),
  txHash: '0x123abc...',
  messageType: MessageType.PRIORITY
};

// Address validation
const evmValid = isEvmAddress('0x742d35Cc6634C0532925a3b8D2C36B7f12345678'); // true
const solanaValid = isSolanaAddress('9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'); // true

API Integration

import {
  ApiResponse,
  ValidationResult,
  IndexerApiResponse,
  Result
} from '@johnqh/types';

// Type-safe API responses
const apiResponse: ApiResponse<User> = {
  success: true,
  data: user,
  timestamp: new Date().toISOString()
};

// Result pattern for error handling
const validateUser = (data: unknown): Result<User> => {
  // Validation logic...
  return { success: true, data: user as User };
};

Utilities

import {
  formatWalletAddress,
  parseEmailAddress,
  createMultiChainId,
  Web3UsernameValidator
} from '@johnqh/types';

// Address formatting
const formatted = formatWalletAddress('0x742d35Cc6634C0532925a3b8D2C36B7f12345678');
// Result: "0x742d...5678"

// Email parsing
const parsed = parseEmailAddress('[e-mail]');
// Result: { address: 'user', domain: 'domain.eth', type: AddressType.ENSName }

// Multi-chain ID generation
const id = createMultiChainId(1, '0x123...', 0);
// Result: "1-0x123...-0"

// Web3 username validation
const validation = Web3UsernameValidator.validate('vitalik.eth');
// Result: { name: 'vitalik.eth', address: null, chainType: ChainType.EVM }

🏗 Project Structure

src/
├── types/                    # Type definitions by domain
│   ├── indexer/             # Indexer API request/response types
│   ├── blockchain/          # Web3 and blockchain types
│   ├── business/            # Core business logic types
│   ├── common.ts            # Shared utility types (Optional<T>, Result<T>)
│   ├── config/              # Configuration types
│   └── infrastructure/      # Infrastructure abstractions
├── utils/                   # Pure utility functions
│   ├── auth/                # Authentication utilities
│   ├── blockchain/          # Blockchain utilities
│   ├── constants/           # Shared constants
│   ├── formatting/          # Formatting utilities
│   ├── logging/             # Logging utilities
│   ├── url/                 # URL utilities
│   └── validation/          # Validation utilities
├── wildduck-requests.ts     # WildDuck email server types
└── index.ts                 # Main exports

🧪 Development

Available Scripts

# Development
npm run build          # Build both ESM and CommonJS
npm run dev            # Watch mode development
npm test               # Run all 267 tests
npm run test:watch     # Watch mode testing
npm run test:coverage  # Generate coverage report

# Quality Assurance
npm run lint           # ESLint checking
npm run lint:fix       # Fix linting issues
npm run format         # Format with Prettier
npm run typecheck      # TypeScript type checking
npm run verify         # Complete verification pipeline

# AI Development Tools
npm run ai:analyze     # Analyze type structure
npm run ai:validate    # Validate exports
npm run ai:docs        # Generate AI documentation

Quality Standards

• 100% TypeScript: Strict mode enabled with comprehensive coverage
• 267 Tests: Complete test suite with Vitest
• Zero Lint Errors: ESLint v9 with flat config
• Perfect Formatting: Prettier integration
• Dual Module Support: ESM + CommonJS builds

🤖 AI Development Optimization

This project is optimized for AI-assisted development with:

Enhanced Documentation

• Comprehensive JSDoc comments on all public APIs
• Usage examples for common patterns
• Type relationships clearly documented
• Change logs with migration guides

AI-Friendly Patterns

• Consistent naming conventions across all types
• Semantic type organization by domain
• Clear export patterns with barrel exports
• Utility type composition for complex scenarios

Development Support

• CLAUDE.md with project-specific instructions
• TYPE_CHANGES.md documenting all type evolution
• AI analysis scripts for type validation
• Comprehensive test coverage for validation

📚 Key Type Categories

Core Business Types

• Email, User, WalletUserData - Core application entities
• MailBox, Folder - Email organization structures
• AuthStatus, ConnectionState - Authentication states

Blockchain Types

• Message, PreparedMessage - Multi-chain messaging
• TransactionResult, TransactionStatus - Transaction handling
• NetworkConfig, DeploymentAddresses - Network configuration

Utility Types

• Optional<T> - Null/undefined safe typing
• Result<T, E> - Error handling patterns
• ValidationResult<T> - Validation patterns
• PaginatedResponse<T> - API pagination

Infrastructure Types

• AnalyticsService - Analytics abstraction
• NetworkClient - HTTP client interface
• UINavigationService - Navigation abstraction

🔧 Configuration

TypeScript Config

The package is built with strict TypeScript settings:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}

Import Patterns

// Main exports
import { Email, User, Optional } from '@johnqh/types';

// Specific modules (tree-shakeable)
import { ChainType } from '@johnqh/types/enums';
import { ValidationResponse } from '@johnqh/types/indexer';

// Utilities
import { formatWalletAddress } from '@johnqh/types/utils';

🔄 Recent Updates (v1.6.2)

• ✅ Optional Consistency: Standardized optional type usage
• ✅ Enhanced Type Safety: Replaced any with unknown throughout
• ✅ Improved Documentation: Comprehensive JSDoc coverage
• ✅ Better AI Support: Enhanced for AI-assisted development
• ✅ Performance: Zero runtime dependencies maintained

🤝 Contributing

This project follows strict quality standards:

• All types must have JSDoc documentation
• Comprehensive tests required for utilities
• Zero external runtime dependencies
• Backward compatibility maintained
• AI-friendly code patterns

📄 License

MIT © 0xmail.box

Built with ❤️ for the Web3 email revolution

This package powers the type-safe foundation of 0xmail.box, the first Web3-native email platform.