@classytic/payroll 1.0.0

package/src/factories/compensation.factory.js

@@ -0,0 +1,198 @@
+/**
+ * Compensation Factory - Clean Compensation Structure Creation
+ * Beautiful, testable compensation management
+ */
+
+import { calculateGross, calculateNet } from '../utils/calculation.utils.js';
+
+export class CompensationFactory {
+  static create({
+    baseAmount,
+    frequency = 'monthly',
+    currency = 'BDT',
+    allowances = [],
+    deductions = [],
+    effectiveFrom = new Date(),
+  }) {
+    return {
+      baseAmount,
+      frequency,
+      currency,
+      allowances: allowances.map(this.createAllowance),
+      deductions: deductions.map(this.createDeduction),
+      effectiveFrom,
+      lastUpdated: new Date(),
+    };
+  }
+
+  static createAllowance({ type, name, value, isPercentage = false }) {
+    return {
+      type,
+      name: name || type,
+      value,
+      isPercentage,
+    };
+  }
+
+  static createDeduction({ type, name, value, isPercentage = false }) {
+    return {
+      type,
+      name: name || type,
+      value,
+      isPercentage,
+    };
+  }
+
+  static updateBaseAmount(compensation, newAmount, effectiveFrom = new Date()) {
+    return {
+      ...compensation,
+      baseAmount: newAmount,
+      lastUpdated: effectiveFrom,
+    };
+  }
+
+  static addAllowance(compensation, allowance) {
+    return {
+      ...compensation,
+      allowances: [...compensation.allowances, this.createAllowance(allowance)],
+      lastUpdated: new Date(),
+    };
+  }
+
+  static removeAllowance(compensation, allowanceType) {
+    return {
+      ...compensation,
+      allowances: compensation.allowances.filter((a) => a.type !== allowanceType),
+      lastUpdated: new Date(),
+    };
+  }
+
+  static addDeduction(compensation, deduction) {
+    return {
+      ...compensation,
+      deductions: [...compensation.deductions, this.createDeduction(deduction)],
+      lastUpdated: new Date(),
+    };
+  }
+
+  static removeDeduction(compensation, deductionType) {
+    return {
+      ...compensation,
+      deductions: compensation.deductions.filter((d) => d.type !== deductionType),
+      lastUpdated: new Date(),
+    };
+  }
+
+  static calculateBreakdown(compensation) {
+    const { baseAmount, allowances, deductions } = compensation;
+
+    const calculatedAllowances = allowances.map((a) => ({
+      ...a,
+      amount: a.isPercentage ? (baseAmount * a.value) / 100 : a.value,
+    }));
+
+    const calculatedDeductions = deductions.map((d) => ({
+      ...d,
+      amount: d.isPercentage ? (baseAmount * d.value) / 100 : d.value,
+    }));
+
+    const gross = calculateGross(baseAmount, calculatedAllowances);
+    const net = calculateNet(gross, calculatedDeductions);
+
+    return {
+      baseAmount,
+      allowances: calculatedAllowances,
+      deductions: calculatedDeductions,
+      grossAmount: gross,
+      netAmount: net,
+    };
+  }
+
+  static applyIncrement(compensation, { percentage, amount, effectiveFrom = new Date() }) {
+    const newBaseAmount = amount
+      ? compensation.baseAmount + amount
+      : compensation.baseAmount * (1 + percentage / 100);
+
+    return this.updateBaseAmount(compensation, Math.round(newBaseAmount), effectiveFrom);
+  }
+}
+
+export class CompensationBuilder {
+  constructor() {
+    this.data = {
+      allowances: [],
+      deductions: [],
+      frequency: 'monthly',
+      currency: 'BDT',
+    };
+  }
+
+  withBase(amount, frequency = 'monthly', currency = 'BDT') {
+    this.data.baseAmount = amount;
+    this.data.frequency = frequency;
+    this.data.currency = currency;
+    return this;
+  }
+
+  addAllowance(type, value, isPercentage = false, name = null) {
+    this.data.allowances.push({ type, value, isPercentage, name });
+    return this;
+  }
+
+  addDeduction(type, value, isPercentage = false, name = null) {
+    this.data.deductions.push({ type, value, isPercentage, name });
+    return this;
+  }
+
+  effectiveFrom(date) {
+    this.data.effectiveFrom = date;
+    return this;
+  }
+
+  build() {
+    return CompensationFactory.create(this.data);
+  }
+}
+
+export const createCompensation = () => new CompensationBuilder();
+
+/**
+ * Standard Compensation Presets
+ */
+export const CompensationPresets = {
+  basic(baseAmount) {
+    return createCompensation().withBase(baseAmount).build();
+  },
+
+  withHouseRent(baseAmount, rentPercentage = 50) {
+    return createCompensation()
+      .withBase(baseAmount)
+      .addAllowance('house_rent', rentPercentage, true, 'House Rent')
+      .build();
+  },
+
+  withMedical(baseAmount, medicalPercentage = 10) {
+    return createCompensation()
+      .withBase(baseAmount)
+      .addAllowance('medical', medicalPercentage, true, 'Medical Allowance')
+      .build();
+  },
+
+  standard(baseAmount) {
+    return createCompensation()
+      .withBase(baseAmount)
+      .addAllowance('house_rent', 50, true, 'House Rent')
+      .addAllowance('medical', 10, true, 'Medical Allowance')
+      .addAllowance('transport', 5, true, 'Transport Allowance')
+      .build();
+  },
+
+  withProvidentFund(baseAmount, pfPercentage = 10) {
+    return createCompensation()
+      .withBase(baseAmount)
+      .addAllowance('house_rent', 50, true, 'House Rent')
+      .addAllowance('medical', 10, true, 'Medical Allowance')
+      .addDeduction('provident_fund', pfPercentage, true, 'Provident Fund')
+      .build();
+  },
+};

package/src/factories/employee.factory.js

@@ -0,0 +1,173 @@
+/**
+ * Employee Factory - Clean Object Creation
+ * Beautiful, testable, immutable object creation
+ */
+
+import { calculateProbationEnd } from '../utils/date.utils.js';
+
+export class EmployeeFactory {
+  static create({
+    userId,
+    organizationId,
+    employment = {},
+    compensation = {},
+    bankDetails = {},
+  }) {
+    const hireDate = employment.hireDate || new Date();
+
+    return {
+      userId,
+      organizationId,
+      employeeId: employment.employeeId,
+      employmentType: employment.type || 'full_time',
+      status: 'active',
+      department: employment.department,
+      position: employment.position,
+      hireDate,
+      probationEndDate: calculateProbationEnd(hireDate, employment.probationMonths),
+      compensation: this.createCompensation(compensation),
+      workSchedule: employment.workSchedule || this.defaultWorkSchedule(),
+      bankDetails: bankDetails || {},
+    };
+  }
+
+  static createCompensation({
+    baseAmount,
+    frequency = 'monthly',
+    currency = 'BDT',
+    allowances = [],
+    deductions = [],
+  }) {
+    return {
+      baseAmount,
+      frequency,
+      currency,
+      allowances: allowances.map(this.createAllowance),
+      deductions: deductions.map(this.createDeduction),
+    };
+  }
+
+  static createAllowance({ type, name, amount, isPercentage = false }) {
+    return {
+      type,
+      name: name || type,
+      amount,
+      isPercentage,
+    };
+  }
+
+  static createDeduction({ type, name, amount, isPercentage = false }) {
+    return {
+      type,
+      name: name || type,
+      amount,
+      isPercentage,
+    };
+  }
+
+  static defaultWorkSchedule() {
+    return {
+      hoursPerWeek: 40,
+      daysPerWeek: 5,
+      workDays: ['monday', 'tuesday', 'wednesday', 'thursday', 'friday'],
+    };
+  }
+
+  static createTermination({ reason, date = new Date(), notes, context = {} }) {
+    return {
+      terminatedAt: date,
+      terminationReason: reason,
+      terminationNotes: notes,
+      terminatedBy: {
+        userId: context.userId,
+        name: context.userName,
+        role: context.userRole,
+      },
+    };
+  }
+}
+
+export class EmployeeBuilder {
+  constructor() {
+    this.data = {};
+  }
+
+  forUser(userId) {
+    this.data.userId = userId;
+    return this;
+  }
+
+  inOrganization(organizationId) {
+    this.data.organizationId = organizationId;
+    return this;
+  }
+
+  withEmployeeId(employeeId) {
+    this.data.employment = { ...this.data.employment, employeeId };
+    return this;
+  }
+
+  asDepartment(department) {
+    this.data.employment = { ...this.data.employment, department };
+    return this;
+  }
+
+  asPosition(position) {
+    this.data.employment = { ...this.data.employment, position };
+    return this;
+  }
+
+  withEmploymentType(type) {
+    this.data.employment = { ...this.data.employment, type };
+    return this;
+  }
+
+  hiredOn(date) {
+    this.data.employment = { ...this.data.employment, hireDate: date };
+    return this;
+  }
+
+  withProbation(months) {
+    this.data.employment = { ...this.data.employment, probationMonths: months };
+    return this;
+  }
+
+  withBaseSalary(amount, frequency = 'monthly', currency = 'BDT') {
+    this.data.compensation = {
+      ...this.data.compensation,
+      baseAmount: amount,
+      frequency,
+      currency,
+    };
+    return this;
+  }
+
+  addAllowance(type, amount, name) {
+    const allowances = this.data.compensation?.allowances || [];
+    this.data.compensation = {
+      ...this.data.compensation,
+      allowances: [...allowances, { type, amount, name }],
+    };
+    return this;
+  }
+
+  addDeduction(type, amount, name) {
+    const deductions = this.data.compensation?.deductions || [];
+    this.data.compensation = {
+      ...this.data.compensation,
+      deductions: [...deductions, { type, amount, name }],
+    };
+    return this;
+  }
+
+  withBankDetails(bankDetails) {
+    this.data.bankDetails = bankDetails;
+    return this;
+  }
+
+  build() {
+    return EmployeeFactory.create(this.data);
+  }
+}
+
+export const createEmployee = () => new EmployeeBuilder();

package/src/factories/payroll.factory.js

@@ -0,0 +1,247 @@
+/**
+ * Payroll Factory - Beautiful Salary Calculation & Record Creation
+ * Clean, testable, immutable payroll object creation
+ */
+
+import {
+  calculateGross,
+  calculateNet,
+  createAllowanceCalculator,
+  createDeductionCalculator,
+} from '../utils/calculation.utils.js';
+
+import { getPayPeriod } from '../utils/date.utils.js';
+
+export class PayrollFactory {
+  static create({
+    employeeId,
+    organizationId,
+    baseAmount,
+    allowances = [],
+    deductions = [],
+    period = {},
+    metadata = {},
+  }) {
+    const calculatedAllowances = this.calculateAllowances(baseAmount, allowances);
+    const calculatedDeductions = this.calculateDeductions(baseAmount, deductions);
+
+    const gross = calculateGross(baseAmount, calculatedAllowances);
+    const net = calculateNet(gross, calculatedDeductions);
+
+    return {
+      employeeId,
+      organizationId,
+      period: this.createPeriod(period),
+      breakdown: {
+        baseAmount,
+        allowances: calculatedAllowances,
+        deductions: calculatedDeductions,
+        grossSalary: gross,
+        netSalary: net,
+      },
+      status: 'pending',
+      processedAt: null,
+      paidAt: null,
+      metadata: {
+        currency: metadata.currency || 'BDT',
+        paymentMethod: metadata.paymentMethod,
+        notes: metadata.notes,
+      },
+    };
+  }
+
+  static createPeriod({ month, year } = {}) {
+    const now = new Date();
+    return getPayPeriod(
+      month || now.getMonth() + 1,
+      year || now.getFullYear()
+    );
+  }
+
+  static calculateAllowances(baseAmount, allowances) {
+    return allowances.map((allowance) => {
+      const amount = allowance.isPercentage
+        ? (baseAmount * allowance.value) / 100
+        : allowance.value;
+
+      return {
+        type: allowance.type,
+        name: allowance.name || allowance.type,
+        amount,
+        isPercentage: allowance.isPercentage || false,
+        value: allowance.value,
+      };
+    });
+  }
+
+  static calculateDeductions(baseAmount, deductions) {
+    return deductions.map((deduction) => {
+      const amount = deduction.isPercentage
+        ? (baseAmount * deduction.value) / 100
+        : deduction.value;
+
+      return {
+        type: deduction.type,
+        name: deduction.name || deduction.type,
+        amount,
+        isPercentage: deduction.isPercentage || false,
+        value: deduction.value,
+      };
+    });
+  }
+
+  static createBonus({ type, amount, reason, approvedBy }) {
+    return {
+      type,
+      amount,
+      reason,
+      approvedBy,
+      approvedAt: new Date(),
+    };
+  }
+
+  static createDeduction({ type, amount, reason, appliedBy }) {
+    return {
+      type,
+      amount,
+      reason,
+      appliedBy,
+      appliedAt: new Date(),
+    };
+  }
+
+  static markAsPaid(payroll, { paidAt = new Date(), transactionId, paymentMethod } = {}) {
+    return {
+      ...payroll,
+      status: 'paid',
+      paidAt,
+      processedAt: payroll.processedAt || paidAt,
+      metadata: {
+        ...payroll.metadata,
+        transactionId,
+        paymentMethod: paymentMethod || payroll.metadata.paymentMethod,
+      },
+    };
+  }
+
+  static markAsProcessed(payroll, { processedAt = new Date() } = {}) {
+    return {
+      ...payroll,
+      status: 'processed',
+      processedAt,
+    };
+  }
+}
+
+export class PayrollBuilder {
+  constructor() {
+    this.data = {
+      allowances: [],
+      deductions: [],
+      period: {},
+      metadata: {},
+    };
+  }
+
+  forEmployee(employeeId) {
+    this.data.employeeId = employeeId;
+    return this;
+  }
+
+  inOrganization(organizationId) {
+    this.data.organizationId = organizationId;
+    return this;
+  }
+
+  withBaseAmount(amount) {
+    this.data.baseAmount = amount;
+    return this;
+  }
+
+  forPeriod(month, year) {
+    this.data.period = { month, year };
+    return this;
+  }
+
+  addAllowance(type, value, isPercentage = false, name = null) {
+    this.data.allowances.push({ type, value, isPercentage, name });
+    return this;
+  }
+
+  addDeduction(type, value, isPercentage = false, name = null) {
+    this.data.deductions.push({ type, value, isPercentage, name });
+    return this;
+  }
+
+  addBonus(amount, reason, approvedBy) {
+    this.data.allowances.push({
+      type: 'bonus',
+      value: amount,
+      isPercentage: false,
+      name: reason,
+    });
+    return this;
+  }
+
+  withCurrency(currency) {
+    this.data.metadata.currency = currency;
+    return this;
+  }
+
+  withPaymentMethod(method) {
+    this.data.metadata.paymentMethod = method;
+    return this;
+  }
+
+  withNotes(notes) {
+    this.data.metadata.notes = notes;
+    return this;
+  }
+
+  build() {
+    return PayrollFactory.create(this.data);
+  }
+}
+
+export const createPayroll = () => new PayrollBuilder();
+
+/**
+ * Batch Payroll Factory - Process multiple employees
+ */
+export class BatchPayrollFactory {
+  static createBatch(employees, { month, year, organizationId }) {
+    return employees.map((employee) =>
+      PayrollFactory.create({
+        employeeId: employee._id || employee.userId,
+        organizationId: organizationId || employee.organizationId,
+        baseAmount: employee.compensation.baseAmount,
+        allowances: employee.compensation.allowances || [],
+        deductions: employee.compensation.deductions || [],
+        period: { month, year },
+      })
+    );
+  }
+
+  static calculateTotalPayroll(payrolls) {
+    return payrolls.reduce(
+      (totals, payroll) => ({
+        count: totals.count + 1,
+        totalGross: totals.totalGross + payroll.breakdown.grossSalary,
+        totalNet: totals.totalNet + payroll.breakdown.netSalary,
+        totalAllowances:
+          totals.totalAllowances +
+          payroll.breakdown.allowances.reduce((sum, a) => sum + a.amount, 0),
+        totalDeductions:
+          totals.totalDeductions +
+          payroll.breakdown.deductions.reduce((sum, d) => sum + d.amount, 0),
+      }),
+      {
+        count: 0,
+        totalGross: 0,
+        totalNet: 0,
+        totalAllowances: 0,
+        totalDeductions: 0,
+      }
+    );
+  }
+}