Domain Builders: Assembling Shift and Day Structures

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dmaman86/shiftly/llms.txt

Use this file to discover all available pages before exploring further.

​

The Builder Interface

export interface Builder<Input, Output> {
  build(params: Input): Output;
}

​

Builders Overview

​

ShiftSegmentBuilder

​

Signature

class ShiftSegmentBuilder implements Builder<
  { shift: Shift; meta: WorkDayMeta },
  LabeledSegmentRange[]
>

​

Type Reference

export interface Point {
  start: number; // minutes from midnight (day-start)
  end: number;   // minutes from midnight
}

export interface LabeledSegmentRange {
  point: Point;
  percent: number; // e.g. 0.2, 0.5, 1.0, 1.5, 2.0
  key: string;     // "hours20" | "hours50" | "hours100" | "shabbat150" | "shabbat200"
}

export interface WorkDayMeta {
  date: string;                     // ISO date string, e.g. "2024-09-13"
  typeDay: WorkDayType;             // Regular | SpecialPartialStart | SpecialFull
  crossDayContinuation: boolean;    // true when the previous night was a special day
  holidayKey?: HolidayKey;          // optional holiday identifier
}

​

How It Works

1. Validates the shift — calls shiftService.isValidShiftDuration(shift); returns [] for zero-duration or inverted shifts.
2. Splits on midnight — computes end minutes relative to the start date using ShiftService.getMinutesFromMidnight. If the shift extends beyond 30:00 (06:00 the next day), it creates a secondPart point.
3. Resolves each part — delegates each Point to ShiftSegmentResolver.resolve({ point, meta }), which maps the point against the correct time-window map for Regular, SpecialPartialStart, or SpecialFull days.
4. Handles the second day — the second part uses a synthetic metaNextDay where typeDay is set to SpecialFull if meta.crossDayContinuation is true, otherwise Regular. All resulting segment points are shifted by +1440 minutes so they sit in a continuous coordinate space.
5. Merges and sorts — combines both part arrays and sorts by point.start.

​

DST Awareness

​

DefaultShiftMapBuilder

​

Signature

class DefaultShiftMapBuilder implements ShiftMapBuilder

// ShiftMapBuilder is:
type ShiftMapBuilder = Builder<
  {
    shift: Shift;
    meta: WorkDayMeta;
    standardHours: number;
    isFieldDutyShift: boolean;
  },
  ShiftPayMap
>

​

Output Type

// shift level
export interface ShiftPayMap extends BasePayMap {
  perDiemShift: { isFieldDutyShift: boolean; hours: number };
}

export interface BasePayMap {
  regular: RegularBreakdown;
  extra: ExtraBreakdown;
  special: SpecialBreakdown;
  totalHours: number;
}

​

Construction Logic

build(params: {
  shift: Shift;
  meta: WorkDayMeta;
  standardHours: number;
  isFieldDutyShift: boolean;
}): ShiftPayMap

1. Calls segmentBuilder.build({ shift, meta }) to get LabeledSegmentRange[].
2. Computes totalHours via shiftService.getDurationShift(shift).
3. Passes segments to extraCalculator.calculate(labeledSegments) → ExtraBreakdown.
4. Passes segments to specialCalculator.calculate(labeledSegments) → SpecialBreakdown.
5. Subtracts special hours from totalHours to get regularHours (Shabbat hours are not double-counted in the regular bracket).
6. Passes { totalHours: regularHours, standardHours, meta } to regularCalculator.calculate(...) → RegularBreakdown.
7. Constructs and returns the ShiftPayMap.

​

DefaultDayPayMapBuilder

​

Signature

class DefaultDayPayMapBuilder implements DayPayMapBuilder

// DayPayMapBuilder is:
type DayPayMapBuilder = Builder<
  {
    shifts: ShiftPayMap[];
    status: WorkDayStatus;     // normal | sick | vacation
    meta: WorkDayMeta;
    standardHours: number;
    year: number;
    month: number;
  },
  WorkDayMap
>

​

Output Type

// day level
export interface WorkDayMap {
  workMap: BasePayMap;
  hours100Sick: Segment;
  hours100Vacation: Segment;
  extra100Shabbat: Segment;
  perDiem: DailyPerDiemInfo;
  mealAllowance: MealAllowance;
  totalHours: number;
}

​

Construction Logic

​

DefaultWorkDaysForMonthBuilder

​

Signature

class DefaultWorkDaysForMonthBuilder implements WorkDaysForMonthBuilder

// WorkDaysForMonthBuilder is:
type WorkDaysForMonthBuilder = Builder<
  {
    year: number;
    month: number;
    eventMap: Record<string, string[]>; // ISO date → array of Hebcal event titles
  },
  WorkDayInfo[]
>

​

Output Element Type

export interface WorkDayInfo {
  meta: WorkDayMeta;   // date, typeDay, crossDayContinuation, holidayKey
  hebrewDay: string;   // e.g. "א", "ב", ... "ש"
}

​

Construction Logic

1. Looks up eventMap[formattedDate] to get the array of Hebcal event titles for that date.
2. Calls holidayResolver.resolve({ weekday, eventTitles }) to determine WorkDayType:
   • Saturday or a paid holiday → SpecialFull
   • Friday or an eve-of-holiday event → SpecialPartialStart
   • Otherwise → Regular
3. Resolves the holidayKey from the event titles using a prefix-match against hebrewHolidayNames.
4. Sets crossDayContinuation on day n-1 to true when day n is SpecialFull — this tells the shift builder that a shift ending the following morning is still in Shabbat/holiday time.
5. After all days are processed, checks the first day of the next month to correctly set the last day’s crossDayContinuation flag.