@venturialstd/project

A NestJS module for managing organizational projects with CRUD operations and organization-specific project management.

📋 Table of Contents

• Features
• Installation
• Quick Start
• API Reference
• Examples

✨ Features

• 🏢 Project Management: Complete CRUD operations for projects
• 🏷️ Project Attributes: Support for keys, statuses, tags, and date ranges
• 📦 Organization Isolation: Each project belongs to a specific organization
• 🔄 TypeORM Integration: Full database support with TypeORM
• 📦 Fully Typed: Complete TypeScript support
• 🎯 Archive Support: Archive and unarchive projects

📦 Installation

npm install @venturialstd/project

Peer Dependencies

{
  "@dataui/crud": "^6.0.0",
  "@dataui/crud-typeorm": "^6.0.0",
  "@nestjs/common": "^11.0.11",
  "@nestjs/core": "^11.0.5",
  "@nestjs/swagger": "^8.0.3",
  "@nestjs/typeorm": "^10.0.0",
  "class-transformer": "^0.5.1",
  "class-validator": "^0.14.1",
  "typeorm": "^0.3.20"
}

🚀 Quick Start

1. Import the Module

import { Module } from '@nestjs/common';
import { ProjectModule } from '@venturialstd/project';

@Module({
  imports: [ProjectModule],
})
export class AppModule {}

2. Use the Services

import { Injectable } from '@nestjs/common';
import { 
  OrganizationProjectService,
  CreateProjectDto,
  OrganizationProject,
} from '@venturialstd/project';

@Injectable()
export class YourService {
  constructor(
    private readonly projectService: OrganizationProjectService,
  ) {}

  async createProject(organizationId: string, name: string) {
    return this.projectService.createProjectForOrganization({
      organizationId,
      name,
      description: 'My new project',
      status: 'active',
    });
  }

  async getProjects(organizationId: string) {
    return this.projectService.getProjectsByOrganization(organizationId);
  }
}

📚 API Reference

Services

OrganizationProjectService

class OrganizationProjectService {
  // Create a new project
  createProjectForOrganization(dto: CreateProjectDto): Promise<OrganizationProject>

  // Update a project
  updateProject(id: string, dto: UpdateProjectDto): Promise<OrganizationProject | null>

  // Get all projects for an organization
  getProjectsByOrganization(
    organizationId: string,
    includeArchived?: boolean
  ): Promise<OrganizationProject[]>

  // Get project by ID
  getProjectById(id: string): Promise<OrganizationProject | null>

  // Get active projects
  getActiveProjectsByOrganization(organizationId: string): Promise<OrganizationProject[]>

  // Archive a project
  archiveProject(id: string): Promise<OrganizationProject | null>

  // Delete a project
  deleteProject(id: string): Promise<void>
}

Entities

OrganizationProject

class OrganizationProject {
  id: string;
  organizationId: string;
  name: string;
  description?: string;
  key?: string;              // Project key/code (e.g., "PROJ", "DEV")
  status?: string;           // e.g., "active", "completed", "archived", "on-hold"
  startDate?: Date;
  endDate?: Date;
  ownerId?: string;          // User who owns/leads the project
  tags?: string[];
  isArchived: boolean;
  createdAt: Date;
  updatedAt: Date;
}

DTOs

CreateProjectDto

class CreateProjectDto {
  organizationId: string;    // Required
  name: string;              // Required
  description?: string;
  key?: string;
  status?: string;
  startDate?: string;        // ISO date string
  endDate?: string;          // ISO date string
  ownerId?: string;
  tags?: string[];
  isArchived?: boolean;
}

UpdateProjectDto

class UpdateProjectDto {
  name?: string;
  description?: string;
  key?: string;
  status?: string;
  startDate?: string;
  endDate?: string;
  ownerId?: string;
  tags?: string[];
  isArchived?: boolean;
}

💻 Examples

Example 1: Create and Configure a Project

@Injectable()
export class ProjectSetupService {
  constructor(
    private readonly projectService: OrganizationProjectService,
  ) {}

  async setupNewProject(organizationId: string, ownerId: string) {
    const project = await this.projectService.createProjectForOrganization({
      organizationId,
      name: 'Q1 2024 Initiative',
      description: 'Strategic goals for Q1 2024',
      key: 'Q1-2024',
      status: 'active',
      startDate: '2024-01-01',
      endDate: '2024-03-31',
      ownerId,
      tags: ['strategic', 'quarterly'],
    });

    return project;
  }
}

Example 2: Get Active Projects

@Injectable()
export class DashboardService {
  constructor(
    private readonly projectService: OrganizationProjectService,
  ) {}

  async getActiveDashboard(organizationId: string) {
    const activeProjects = await this.projectService.getActiveProjectsByOrganization(
      organizationId
    );

    return {
      total: activeProjects.length,
      projects: activeProjects,
    };
  }
}

Example 3: Archive Completed Projects

@Injectable()
export class ProjectMaintenanceService {
  constructor(
    private readonly projectService: OrganizationProjectService,
  ) {}

  async archiveCompletedProjects(organizationId: string) {
    const projects = await this.projectService.getProjectsByOrganization(
      organizationId
    );

    const completedProjects = projects.filter(
      p => p.status === 'completed' && !p.isArchived
    );

    for (const project of completedProjects) {
      await this.projectService.archiveProject(project.id);
    }

    return { archived: completedProjects.length };
  }
}

📄 License

MIT

🤝 Contributing

Contributions welcome! Please read the contributing guidelines before submitting PRs.