ConvoCore Types

A comprehensive TypeScript package providing types, utility functions, and Zod schemas for ConvoCore applications. Fully typed, tree-shakeable, and optimized for modern TypeScript projects.

📦 Installation

pnpm add convocore-types
# or
npm install convocore-types
# or
yarn add convocore-types

✨ Features

• 🎯 800+ TypeScript Types - Comprehensive type definitions organized by domain
• 🛡️ Zod Schemas - Runtime validation schemas with type inference
• 🔧 Utility Functions - Helper functions for API responses, validation, and common operations
• 📦 Tree Shakeable - Import only what you need with optimized exports
• 🚀 Zero Config - Ready to use out of the box
• 💪 Fully Typed - 100% TypeScript with complete IntelliSense support
• ⚡ Optimized - Small bundle size (48.8 kB), minimal dependencies

🏗️ Module Structure

The package is organized into logical domains for easy navigation:

Types

• /types/auth - Authentication & authorization (User, Role, Permission, Team, Session)
• /types/content - Messaging & content (Message, Conversation, Channel, Thread)
• /types/api - HTTP & API (Request/Response, Webhooks, WebSockets)
• /types/database - Database & ORM (Entities, Queries, Migrations)
• /types/ui - UI & frontend (Theme, Layout, Components)
• /types/config - Configuration (AppConfig, FeatureFlags, Settings)
• /types/utils - Advanced utility types (100+ TypeScript helpers)

Schemas

• /schemas/auth - Zod validation schemas for auth types
• /schemas - Legacy schemas for backwards compatibility

Utils

• /utils - Utility functions (API helpers, validation, async utilities)

🚀 Quick Start

import { 
  User, 
  Message, 
  ApiResponse,
  createSuccessResponse,
  UserSchema,
  z
} from 'convocore-types';

// Use types
const user: User = {
  id: '123',
  email: '[email protected]',
  name: 'John Doe',
  status: 'active',
  isVerified: true,
  isActive: true,
  createdAt: new Date(),
  updatedAt: new Date(),
};

// Validate with Zod
const result = UserSchema.safeParse(userData);
if (result.success) {
  console.log('Valid user:', result.data);
}

// Create API responses
const response = createSuccessResponse(user, 'User retrieved successfully');

📚 Usage Examples

Authentication Types

import { 
  User, 
  Team, 
  LoginRequest, 
  Session,
  UserProfile 
} from 'convocore-types/types/auth';

const loginData: LoginRequest = {
  email: '[email protected]',
  password: 'SecurePassword123',
  rememberMe: true,
};

Content & Messaging

import { 
  Message, 
  Conversation, 
  Channel,
  Reaction,
  Attachment 
} from 'convocore-types/types/content';

const message: Message = {
  id: '1',
  content: 'Hello, world!',
  type: 'text',
  authorId: 'user-123',
  channelId: 'channel-456',
  mentions: [],
  attachments: [],
  reactions: [],
  isEdited: false,
  isDeleted: false,
  createdAt: new Date(),
  updatedAt: new Date(),
};

API & HTTP Types

import { 
  ApiResponse,
  PaginatedResponse,
  WebhookEvent,
  HttpMethod,
  createSuccessResponse,
  createPaginatedResponse 
} from 'convocore-types';

// Create responses
const success = createSuccessResponse({ id: 1, name: 'Test' });
const paginated = createPaginatedResponse(items, 1, 10, 100);

Zod Schema Validation

import { 
  UserSchema,
  TeamSchema,
  LoginRequestSchema,
  validateEmail,
  validatePassword 
} from 'convocore-types/schemas/auth';

// Validate login data
const loginResult = LoginRequestSchema.safeParse({
  email: '[email protected]',
  password: 'SecurePass123',
});

if (loginResult.success) {
  // Data is valid and typed
  const { email, password } = loginResult.data;
}

// Use validation utilities
if (validateEmail('[email protected]')) {
  // Email is valid
}

Utility Functions

import { 
  createSuccessResponse,
  createErrorResponse,
  validateWithSchema,
  debounce,
  throttle,
  retry,
  formatBytes,
  slugify,
  sleep 
} from 'convocore-types/utils';

// API helpers
const success = createSuccessResponse(data, 'Operation successful');
const error = createErrorResponse('Not found', 'Resource not found');

// Validation
const result = validateWithSchema(UserSchema, userData);

// Async utilities
await sleep(1000);
const data = await retry(() => fetchData(), { retries: 3 });

// Formatting
const size = formatBytes(1024 * 1024); // "1 MB"
const slug = slugify('Hello World!'); // "hello-world"

// Debounce/Throttle
const debouncedFn = debounce(handleInput, 300);
const throttledFn = throttle(handleScroll, 100);

Advanced Utility Types

import { 
  DeepPartial,
  DeepReadonly,
  RequiredFields,
  PickByType,
  Path,
  Jsonify 
} from 'convocore-types/types/utils';

// Make all properties optional (including nested)
type PartialUser = DeepPartial<User>;

// Make specific fields required
type RequiredEmailUser = RequiredFields<Partial<User>, 'email' | 'name'>;

// Pick properties by type
type StringFields = PickByType<User, string>;

// Type-safe path access
type UserPaths = Path<User>; // 'id' | 'email' | 'name' | ...

Database Types

import { 
  BaseEntity,
  DatabaseConfig,
  Migration,
  QueryBuilder 
} from 'convocore-types/types/database';

interface Product extends BaseEntity {
  name: string;
  price: number;
}

// Product automatically has: id, createdAt, updatedAt, deletedAt

UI Types

import { 
  Theme,
  Layout,
  FormField,
  ButtonStyles 
} from 'convocore-types/types/ui';

const theme: Theme = {
  id: 'dark',
  name: 'Dark Theme',
  colors: { /* ... */ },
  typography: { /* ... */ },
  // ... other theme properties
};

Configuration

import { 
  AppConfig,
  FeatureFlags,
  DatabaseSettings 
} from 'convocore-types/types/config';

const config: AppConfig = {
  app: {
    name: 'MyApp',
    version: '1.0.0',
    // ... other settings
  },
  features: {
    authentication: true,
    twoFactorAuth: false,
    // ... other feature flags
  },
  // ... other config
};

📖 Import Paths

The package supports both main exports and submodule imports for optimal tree-shaking:

// Main export (includes everything)
import { User, UserSchema, createSuccessResponse } from 'convocore-types';

// Submodule imports (tree-shakeable)
import { User } from 'convocore-types/types/auth';
import { Message } from 'convocore-types/types/content';
import { ApiResponse } from 'convocore-types/types/api';
import { UserSchema } from 'convocore-types/schemas/auth';
import { createSuccessResponse } from 'convocore-types/utils';

🎯 Type Inference

Use Zod's type inference to automatically generate TypeScript types:

import { z } from 'convocore-types';
import { UserSchema } from 'convocore-types/schemas/auth';

// Infer the type from the schema
type User = z.infer<typeof UserSchema>;

// Now you have a fully typed User without importing the type separately
const user: User = {
  id: '123',
  email: '[email protected]',
  // ... TypeScript knows all the required fields
};

🛠️ Development

# Install dependencies
pnpm install

# Build the package
pnpm run build

# Watch mode
pnpm run dev

# Clean dist folder
pnpm run clean

📝 Type Coverage

• Authentication: 50+ types (User, Role, Permission, Team, Session, OAuth)
• Content: 40+ types (Message, Conversation, Channel, Thread, Reaction)
• API: 60+ types (HTTP, Webhooks, WebSocket, File Upload, Batch Operations)
• Database: 30+ types (Entities, Queries, Migrations, Transactions)
• UI: 25+ types (Theme, Layout, Components, Forms, State Management)
• Config: 20+ types (AppConfig, FeatureFlags, Integrations, User Preferences)
• Utils: 100+ advanced TypeScript utility types

⚡ Performance & Optimization

• Small Bundle: 48.8 kB gzipped
• Tree Shakeable: Import only what you need
• Zero Runtime Overhead: Pure TypeScript types have no runtime cost
• Optimized Exports: Submodule imports for maximum tree-shaking
• Type-Only Imports: Use import type for zero-cost type imports

// Type-only import (no runtime code)
import type { User } from 'convocore-types';

// Runtime import (includes Zod schema)
import { UserSchema } from 'convocore-types/schemas/auth';

🤝 Contributing

Contributions are welcome! This package is designed to be comprehensive and cover all common use cases.

📄 License

MIT © ConvoCore

🔗 Links

• npm
• GitHub

📊 Package Stats

• Version: 1.0.1
• Dependencies: zod (only runtime dependency)
• TypeScript: ✅ Fully typed
• Bundle Size: 48.8 kB
• Files: 50+ compiled files
• Types: 800+ interfaces and types

🎉 What's New in v1.0.1

• ✅ Optimized export paths for better tree-shaking
• ✅ Submodule imports support (convocore-types/types/auth, etc.)
• ✅ Comprehensive authentication schemas with Zod
• ✅ Utility functions for API responses and validation
• ✅ 100+ advanced TypeScript utility types
• ✅ Full IntelliSense support for all modules
• ✅ Tested and production-ready

Made with ❤️ for the TypeScript community