@bernierllc/todo-list/README.md

Pure todo list business logic and management utilities for @bernierllc packages

# @bernierllc/todo-list

Pure todo list business logic and management utilities for @bernierllc packages.

## Installation

```bash
npm install @bernierllc/todo-list
```

## Usage

```typescript
import { TaskManager, CreateTaskRequest } from '@bernierllc/todo-list';

const taskManager = new TaskManager();

// Create a new task
const createRequest: CreateTaskRequest = {
  userId: '123e4567-e89b-12d3-a456-426614174000',
  type: 'review',
  title: 'Review pull request',
  description: 'Review the new authentication feature PR',
  priority: 'high'
};

const result = taskManager.createTask(createRequest);
if (result.success) {
  console.log('Task created:', result.data);
} else {
  console.error('Error:', result.error);
}

// Get all tasks
const tasksResult = taskManager.getTasks();
if (tasksResult.success) {
  console.log('All tasks:', tasksResult.data);
}

// Filter tasks
const filteredResult = taskManager.getTasks({
  userId: '123e4567-e89b-12d3-a456-426614174000',
  status: 'pending',
  priority: 'urgent'
});

// Complete a task
const completionResult = taskManager.completeTask(result.data!.id, {
  completedBy: '123e4567-e89b-12d3-a456-426614174000',
  notes: 'Completed successfully'
});

// Get analytics
const analyticsResult = taskManager.getTaskAnalytics();
if (analyticsResult.success) {
  console.log('Completion rate:', analyticsResult.data!.completionRate);
}
```

## API Reference

### TaskManager

#### Core Methods

- `createTask(request: CreateTaskRequest): TaskOperationResult<Task>`
- `getTasks(filters?: TaskFilters): TaskOperationResult<Task[]>`
- `getTask(id: string): TaskOperationResult<Task | null>`
- `updateTask(id: string, request: UpdateTaskRequest, userId: string): TaskOperationResult<Task>`
- `completeTask(id: string, request: TaskCompletionRequest): TaskOperationResult<Task>`
- `deleteTask(id: string, userId: string): TaskOperationResult<void>`

#### Task Type Management

- `getTaskTypes(): TaskOperationResult<TaskType[]>`
- `createTaskType(taskType: TaskType): TaskOperationResult<TaskType>`
- `updateTaskType(id: string, updates: Partial<TaskType>): TaskOperationResult<TaskType>`
- `deleteTaskType(id: string): TaskOperationResult<void>`

#### Analytics & History

- `getTaskAnalytics(filters?: TaskFilters): TaskOperationResult<TaskAnalytics>`
- `getTaskHistory(taskId?: string): TaskOperationResult<TaskHistoryItem[]>`

#### Validation

- `validateTask(task: Partial<Task>): TaskValidationResult`

#### Utilities

- `getTaskCount(): number`
- `getTaskTypeCount(): number`
- `clearTasks(): void` (for testing)
- `clearTaskTypes(): void` (for testing)

### Types

#### Task

```typescript
interface Task {
  readonly id: string;
  readonly userId: string;
  readonly groupId?: string;
  readonly type: TaskType;
  readonly title: string;
  readonly description: string;
  readonly priority: TaskPriority;
  readonly dueDate?: string;
  readonly status: TaskStatus;
  readonly relatedId?: string;
  readonly actionUrl?: string;
  readonly canCompleteDirectly: boolean;
  readonly createdAt: string;
  readonly updatedAt: string;
  readonly completedAt?: string;
  readonly completedBy?: string;
}
```

#### TaskType

```typescript
interface TaskType {
  readonly id: string;
  readonly name: string;
  readonly description: string;
  readonly icon: string;
  readonly defaultPriority: TaskPriority;
}
```

#### TaskPriority

```typescript
type TaskPriority = 'urgent' | 'high' | 'normal';
```

#### TaskStatus

```typescript
type TaskStatus = 'pending' | 'in-progress' | 'completed';
```

### Default Task Types

The TaskManager comes with 4 built-in task types:

- **review** - Review Required (high priority)
- **approval** - Approval Needed (urgent priority)
- **update** - Update Required (normal priority)
- **notification** - Notification (normal priority)

## Configuration

All requests are validated using Zod schemas. Invalid data will result in operation failure with descriptive error messages.

### Validation Rules

- **Task titles**: Required, 1-255 characters
- **Task descriptions**: Required, 1-1000 characters
- **User IDs**: Must be valid UUIDs
- **Due dates**: Must be valid ISO datetime strings
- **Action URLs**: Must be valid URL format

## Error Handling

All methods return `TaskOperationResult<T>` with consistent structure:

```typescript
interface TaskOperationResult<T = void> {
  readonly success: boolean;
  readonly data?: T;
  readonly error?: string;
}
```

Always check the `success` property before accessing `data`.

## Features

- ✅ **Pure Business Logic** - No UI or external dependencies
- ✅ **Type Safety** - Full TypeScript support with strict typing
- ✅ **Validation** - Comprehensive input validation using Zod
- ✅ **Filtering & Sorting** - Flexible task filtering and priority-based sorting
- ✅ **Analytics** - Built-in analytics and completion metrics
- ✅ **Audit Trail** - Complete history tracking for all operations
- ✅ **Task Types** - Flexible task categorization system
- ✅ **Error Handling** - Consistent error handling with descriptive messages

## Integration Status

### Logger Integration
- **Status**: Not applicable
- **Justification**: This is a pure utility package with no I/O operations, network calls, or side effects. All operations are synchronous and in-memory, making logging integration unnecessary.

### Docs-Suite Integration
- **Status**: Ready
- **Format**: TypeDoc/JSDoc
- **Exports**: All types, interfaces, and classes are fully documented with JSDoc comments for automatic documentation generation.

### NeverHub Integration
- **Status**: Not applicable
- **Justification**: This is a core utility package providing pure business logic with no external service dependencies. It operates entirely in-memory with no need for service discovery or event bus communication.

All methods use the structured `TaskOperationResult<T>` pattern for consistent error handling without requiring external logger integration.

## See Also

- [@bernierllc/task-service](../../../service/task-service) - Higher-level task orchestration
- [@bernierllc/task-ui](../../../ui/task-ui) - React components for task management

## License

Copyright (c) 2025 Bernier LLC. All rights reserved.