Working time and calendars#

This guide shows how to tell Planning Engine when work can happen: working hours, weekdays, holidays and short days. It also covers how tasks and resources pick a calendar, and how to turn calendars off.

How calendars work#

A task's duration is working time. A 16-hour task doesn't end 16 hours after it starts. It ends once it has used 16 hours of its calendar's working time, so nights, weekends and holidays stretch it. Lags work the same way. leveling_delay and pauses are the exception: they're elapsed wall-clock time.

Calendars go in ProjectData.calendars. Each one is a CalendarData object: an id plus an optional worktime with three fields:

• hours: the working ranges of a day, as "H:MM-H:MM" strings. Default: ["8:00-12:00", "13:00-17:00"]. "24:00" is the only hour-24 value. A range that ends before it starts crosses midnight.
• days: exactly seven entries, booleans or numbers, index 0 is Sunday. Default: Monday to Friday.
• dates: exceptions keyed by "YYYY-MM-DD". A value of false (or 0) makes the date a day off. true (or a non-zero number) makes it a working day with the calendar's hours. An array of ranges such as ["9:00-13:00"] makes it a working day with those hours.

Every project has a calendar named "global". If you don't define one, the engine uses the built-in Monday-Friday, 08:00-12:00 and 13:00-17:00. A calendar with the id "global" in calendars replaces it.

Which calendar a piece of work uses depends on config.calendar_mode (see SchedulingConfig):

"resource" follows MS Project. "task" and "task-inherited" use task calendars only.

config.use_calendars sits above all of this. It's true by default, and null also reads as true. Set it to false and every calendar becomes flat 24/7 time.

The engine checks calendars when you pass data to schedule or solve. These cases return a validation error envelope with the field path:

The JSON decoder rejects a few shapes before the engine sees them. These come back as validation with path: null: an hour range it can't read ("8:00-25:00"), a days list without exactly 7 entries, and customWeeks, which isn't supported. For example:

{
  "error": { "code": null, "kind": "validation", "message": "invalid hour range", "path": null },
  "ok": false
}

Calendars belong to the snapshot only. SchedulingChanges has no calendars field, so apply can't add or edit a calendar. Sending one is a parse error. To change a calendar, send the full data again with solve(dataJson, ...). Edits can still point tasks and resources at existing calendars through calendar_id. An unknown id there is a rejected operation in the ApplyReport, not an error envelope. See Error handling for both levels.

Defining calendars#

Replace "global" to change the working week for the whole project. The calendar below works Monday to Friday, 09:00-17:00. Thursday the 13th is a short day and Friday the 14th is a holiday:

const { schedule } = require("./pkg-node/plen_wasm.js");

const data = {
  config: { duration_unit: "hour" },
  calendars: [
    {
      id: "global",
      worktime: {
        hours: ["9:00-17:00"],
        days: [0, 1, 1, 1, 1, 1, 0], // Sunday..Saturday
        dates: {
          "2026-08-13": ["9:00-13:00"], // Thursday: a short day
          "2026-08-14": false, // Friday: a public holiday
        },
      },
    },
  ],
  tasks: [{ id: "build", start_date: "2026-08-10 09:00", duration: 36 }],
};

const response = JSON.parse(schedule(JSON.stringify(data), '{"includeUnchanged":true}'));
if (!response.ok) {
  throw new Error(`${response.error.kind}: ${response.error.message} (at ${response.error.path})`);
}
for (const update of response.result.updates) {
  console.log(`${update.id}: ${update.start_date} -> ${update.end_date}`);
}

Output:

build: 2026-08-10 09:00 -> 2026-08-17 17:00

The 36 hours are Monday to Wednesday (24 h), the short Thursday (4 h) and the next Monday (8 h). The holiday and the weekend hold no work. includeUnchanged makes updates list the task even though its start didn't move.

Each worktime field you leave out keeps its default. { "days": [0, 1, 1, 1, 1, 1, 1] } changes the weekdays and keeps the 08:00-12:00, 13:00-17:00 hours.

Task calendars#

Set a task's calendar_id to run that task on a different calendar. Here migrate runs on a night shift, while review stays on the default "global" calendar:

const { schedule } = require("./pkg-node/plen_wasm.js");

const data = {
  config: { duration_unit: "hour" },
  calendars: [
    // 22:00-6:00 ends before it starts, so it crosses midnight
    // and belongs to the day it starts on.
    { id: "night", worktime: { hours: ["22:00-6:00"] } },
  ],
  tasks: [
    { id: "review", start_date: "2026-08-10 08:00", duration: 16 },
    { id: "migrate", start_date: "2026-08-10 22:00", duration: 16, calendar_id: "night" },
  ],
};

const response = JSON.parse(schedule(JSON.stringify(data), '{"includeUnchanged":true}'));
if (!response.ok) {
  throw new Error(`${response.error.kind}: ${response.error.message} (at ${response.error.path})`);
}
for (const update of response.result.updates) {
  console.log(`${update.id}: ${update.start_date} -> ${update.end_date}`);
}

Output:

review: 2026-08-10 08:00 -> 2026-08-11 17:00
migrate: 2026-08-10 22:00 -> 2026-08-12 06:00

The night shift keeps the default Monday-to-Friday days. Monday's shift runs until Tuesday 06:00, because a range that crosses midnight belongs to the day it starts on.

A task's own calendar (else "global") also matters in "resource" mode. Milestones, lag and slack always use it.

Inheriting a calendar from a summary#

In "task" and "resource" modes a child doesn't look at its parent's calendar. Set calendar_mode to "task-inherited" to make a task without a calendar_id use the nearest ancestor's:

const { schedule } = require("./pkg-node/plen_wasm.js");

const data = {
  config: { duration_unit: "hour", calendar_mode: "task-inherited" },
  calendars: [{ id: "six-day", worktime: { days: [0, 1, 1, 1, 1, 1, 1] } }],
  tasks: [
    { id: "phase", type: "summary", calendar_id: "six-day" },
    { id: "pour", parent: "phase", start_date: "2026-08-14 08:00", duration: 16 }, // Friday
  ],
};

const response = JSON.parse(schedule(JSON.stringify(data), '{"includeUnchanged":true}'));
if (!response.ok) {
  throw new Error(`${response.error.kind}: ${response.error.message} (at ${response.error.path})`);
}
for (const update of response.result.updates) {
  console.log(`${update.id}: ${update.start_date} -> ${update.end_date}`);
}

Output:

pour: 2026-08-14 08:00 -> 2026-08-15 17:00
phase: 2026-08-14 08:00 -> 2026-08-15 17:00

pour works Friday and Saturday on the summary's six-day week. Drop calendar_mode and it runs on "global" instead: Friday, then Monday, ending 2026-08-17 17:00.

Resource calendars#

In the default "resource" mode each assignment works on its resource's calendar, and the task's dates follow its assignments. Give a resource a calendar through its calendar_id. The example runs the same project in "resource" and "task" mode:

const { schedule } = require("./pkg-node/plen_wasm.js");

function project(mode) {
  return {
    config: { duration_unit: "hour", calendar_mode: mode },
    calendars: [{ id: "tue-sat", worktime: { days: [0, 0, 1, 1, 1, 1, 1] } }],
    tasks: [
      // `prepare` has no resources, so it runs on the global calendar
      // and ends Friday 17:00.
      { id: "prepare", start_date: "2026-08-14 08:00", duration: 8 },
      { id: "inspect", start_date: "2026-08-14 08:00", duration: 16 },
    ],
    links: [{ id: "l1", source: "prepare", target: "inspect", type: "fs" }],
    resources: [{ id: "dana", calendar_id: "tue-sat" }],
    assignments: [{ id: "inspect:dana", task: "inspect", resource: "dana", value: 1 }],
  };
}

for (const mode of ["resource", "task"]) {
  const response = JSON.parse(schedule(JSON.stringify(project(mode)), '{"includeUnchanged":true}'));
  if (!response.ok) {
    throw new Error(`${response.error.kind}: ${response.error.message} (at ${response.error.path})`);
  }
  for (const update of response.result.updates) {
    console.log(`${mode} ${update.id}: ${update.start_date} -> ${update.end_date}`);
  }
}

Output:

resource prepare: 2026-08-14 08:00 -> 2026-08-14 17:00
resource inspect: 2026-08-15 08:00 -> 2026-08-18 17:00
task prepare: 2026-08-14 08:00 -> 2026-08-14 17:00
task inspect: 2026-08-17 08:00 -> 2026-08-18 17:00

In "resource" mode Dana works Saturday, so inspect starts right after prepare and runs Saturday and Tuesday. In "task" mode her calendar is ignored and inspect waits for Monday on "global".

The rules for picking an assignment's calendar:

• The resource has a calendar and the task doesn't: the resource's calendar.
• Both have one: their intersection. Give a task a mornings-only calendar and assign it to Dana, and the work runs Tuesday to Friday mornings only.
• The resource has none: the task's calendar.
• Summaries and milestones always use the task's calendar.

A task with several assignments on different calendars spans the envelope of its assignments. Each assignment starts at the first working time of its own calendar and runs the full duration there. The task ends when the last one ends. The reported duration stays the working time of each assignment, not the length of the envelope. Results don't include per-assignment dates.

Resource calendars also shape resource load: each assignment books work only on its own calendar. See Resource load.

Flat time#

Set config.use_calendars to false to schedule without working hours. Every calendar becomes 24/7, so a day of duration is 24 hours:

const { schedule } = require("./pkg-node/plen_wasm.js");

const data = {
  config: { use_calendars: false },
  tasks: [{ id: "burn-in", start_date: "2026-08-14 08:00", duration: 2 }], // Friday, 2 days
};

const response = JSON.parse(schedule(JSON.stringify(data), '{"includeUnchanged":true}'));
if (!response.ok) {
  throw new Error(`${response.error.kind}: ${response.error.message} (at ${response.error.path})`);
}
for (const update of response.result.updates) {
  console.log(`${update.id}: ${update.start_date} -> ${update.end_date}`);
}

Output:

burn-in: 2026-08-14 08:00 -> 2026-08-16 08:00

With calendars on, the same task skips the weekend and ends on Tuesday at 08:00. The engine still validates calendar ids, but they all resolve to the same flat time. That lets you toggle use_calendars without touching the rest of the data. In flat mode, resource and assignment edits never move dates.

When use_calendars is left out, the engine schedules on calendars, so send false explicitly for flat time.

Explicit starts on non-working time#

When an edit sets a start that falls on non-working time, the engine doesn't always snap it. A task with no predecessor keeps the exact start you gave it. Its end is computed forward on the working calendar, so the duration is still right. A task with a predecessor gets its start from the link instead.

const { JsonProject } = require("./pkg-node/plen_wasm.js");

function unwrap(text) {
  const response = JSON.parse(text);
  if (!response.ok) {
    const { kind, code, message, path } = response.error;
    throw new Error(`${kind} ${code ?? ""}: ${message} (at ${path})`);
  }
  return response.result;
}

const data = {
  config: { duration_unit: "hour" },
  tasks: [{ id: "deploy", start_date: "2026-08-13 08:00", duration: 4 }], // Thursday
};

const project = new JsonProject("{}");
try {
  unwrap(project.solve(JSON.stringify(data), "{}"));

  // The user drags the task onto Saturday 10:00.
  const changes = { tasks: { update: [{ id: "deploy", start_date: "2026-08-15 10:00" }] } };
  const report = unwrap(project.apply(JSON.stringify(changes)));
  if (report.needsResync) {
    throw new Error("the edit was rejected");
  }

  const result = unwrap(project.solve(undefined, "{}"));
  for (const update of result.updates) {
    console.log(`${update.id}: ${update.start_date} -> ${update.end_date}`);
  }
} finally {
  project.free();
}

Output:

deploy: 2026-08-15 10:00 -> 2026-08-17 12:00

The start stays on Saturday 10:00. The four hours of work run Monday 08:00-12:00. This applies to apply and preview, the calls behind drags in an editor.

This is by design: the UI layer owns snapping. If your editor should only allow working-time starts, snap the date before you send the TaskUpdate.