Preview leveling#

Show the user what leveling would change before it touches the project, then keep the leveled plan or throw it away.

project.level() commits. It writes leveling_delay and pauses into the project and accepts the leveled dates as the new baseline. To get a proposal instead, level a copy made with project.clone().

Prerequisites#

• A solved Project: project.solve(data) has run.
• The data has resources and assignments, so there's overallocation to level.
• The project is forward-scheduled. level refuses config.schedule_from_end: true with an InputError.

Steps#

1. Clone the solved project:

   Copy

   const draft = project.clone();
   

2. Level the clone. The original keeps its dates, its baseline and its overallocation:

   Copy

   const proposal = draft.level();
   

3. Show the proposal. proposal.updates lists the tasks leveling moved, with their new dates, leveling_delay and pauses. The diff is relative to the state the call started from. That state matches the original, so you can apply the entries to the model you already hold.

   Copy

   for (const u of proposal.updates) {
     console.log(`${u.id}: start ${u.start_date}, delay ${u.leveling_delay}, pauses ${JSON.stringify(u.pauses ?? [])}`);
   }
   

   Note

   The leveling result is a ScheduleResult with an added rounds field; read updates directly on it.

4. Show what leveling couldn't fix. proposal.overallocations holds the windows left after leveling. Each window has a reason, such as fixed-task or priority-1000:

   Copy

   for (const over of proposal.overallocations ?? []) {
     for (const w of over.windows ?? []) {
       console.log(`${over.resource}: ${w.from} .. ${w.to}, ${w.reason}`);
     }
   }
   

   Note

   windows is absent, not an empty array, when a resource has no overallocated window.

5. Apply the user's choice:

   • Accept: replace the original with the clone, project = draft;. The project now holds the leveled baseline.
   • Reject: drop draft. Nothing else needs undoing.

   Replace the original only if it hasn't been edited since you cloned it. Otherwise the proposal was computed from an older state, so level a new clone.

The full example levels two tasks that book the same developer full time on Monday and Tuesday:

import { Project } from "plen-js";

// Monday, August 10, 2026, on the default calendar.
const data = {
  tasks: [
    { id: "A", start_date: "2026-08-10 08:00", duration: 2 },
    { id: "B", start_date: "2026-08-10 08:00", duration: 2 },
  ],
  resources: [{ id: "dev1" }],
  assignments: [
    { task: "A", resource: "dev1", value: 1 },
    { task: "B", resource: "dev1", value: 1 },
  ],
};

let project = new Project();
project.solve(data);

const draft = project.clone();
const proposal = draft.level();

for (const u of proposal.updates) {
  console.log(`${u.id}: ${u.start_date} .. ${u.end_date}, delay ${u.leveling_delay}`);
}
const left = proposal.overallocations?.length ?? 0;
console.log(`overallocated resources left: ${left}`);

const userAccepts = true;
if (userAccepts) {
  project = draft;
}
const plan = project.solve(null);
console.log(`baseline: ${plan.baselineId === proposal.baselineId ? "leveled" : "original"}`);

Result#

The example prints the one task leveling moved, and nothing is left overallocated:

B: 2026-08-12 08:00 .. 2026-08-14 08:00, delay 2
overallocated resources left: 0
baseline: leveled

B waits two days for A, so its leveling_delay is 2. Until you replace project with draft, project still reports the Monday-Tuesday window on dev1, and a solve(null) on it returns no updates. After the swap, baselineId is the token from the leveling result.

The clone is a full solved project, so you can also call draft.loadProfile() on it to draw the leveled load. See Resource load. To compare leveling across several alternative change sets with scores, use evaluate with the level option instead. See Evaluating alternatives. For options, reasons and splits, see Leveling resources.