[Canonical page]() [Full documentation index]() # Editing a Project This guide covers how to change a live [`JsonProject`]() as the user works. It explains how to add, update and remove tasks, links, resources and assignments, how to reschedule after an edit, and how to recover when part of an edit is refused. ## How editing works A [`JsonProject`]() holds one accepted state: the data from the last [`solve(dataJson, …)`](), every edit since, and the dates the last solve accepted. You don't send the whole plan again for each change. Describe the change as a [`SchedulingChanges`]() object, serialize it, and pass it to [`apply`](). Editing takes two separate calls: 1. `apply(changesJson)` writes the edit into the accepted state and marks the project unsolved. It doesn't schedule anything. 2. `solve(undefined, optionsJson)` schedules the edited state, accepts the new dates and returns what moved. Between the two calls the project has no baseline. [`preview`](), [`loadProfile`](), [`evaluate`](), [`slots`]() and [`suggestAssignments`]() return a `project` error with code [`no-baseline`]() until you solve. You can call `apply` several times before one `solve`, and the edits add up. `apply` accepts what it can. Each operation in the change set is applied or rejected on its own. A rejection isn't an error envelope. The response is `ok: true`, the rejection is listed in the returned [`ApplyReport`](), and `needsResync` is set. From then on, `solve` without data, `apply` and [`level`]() return a `project` error with code [`needs-resync`](). Your model and the project's state may now disagree, and the only way back is to send the full data with `solve(dataJson, …)`. An error envelope from `apply` means nothing was applied. The cases are: - `project` with code `stale-baseline`: the change set names a baseline that isn't current anymore. This check runs first. - `project` with code `needs-resync`: an earlier `apply` rejected an operation. - `parse` or `validation`: the JSON itself was refused. Examples are an unknown field in the change set or its buckets, a missing required field, or a value the decoder can't read, such as a malformed date. See [Error handling]() for the envelope and [Wire format]() for field spelling. ## Change sets A [`SchedulingChanges`]() object groups the edits by record kind. Each group has up to three lists: `add`, `update` and `remove`. Leave out any group or list you don't need. | Group | `add` | `update` | `remove` | |---|---|---|---| | `tasks` | [`TaskData`]() | [`TaskUpdate`]() | task ids | | `links` | [`LinkAdd`]() | [`LinkUpdate`]() | link ids | | `resources` | [`ResourceData`]() | [`ResourceUpdate`]() | resource ids | | `assignments` | [`AssignmentData`]() | [`AssignmentUpdate`]() | assignment ids | Additions use the same records as [`ProjectData`](), in the same snake_case spelling, except links: in `links.add` the `id` is optional. Leave out a link or assignment `id` (or send `null`), and `apply` generates one (`$generated_link_1`, `$generated_assignment_1`, ...). Generated ids come back in the report's [`effects`](), so you can store them in your model. ```js 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 = { tasks: [ { id: 1, start_date: "2026-08-10 08:00", duration: 2 }, { id: 2, start_date: "2026-08-10 08:00", duration: 3 }, ], links: [{ id: 1, source: 1, target: 2, type: "fs" }], }; const project = new JsonProject("{}"); try { unwrap(project.solve(JSON.stringify(data), "{}")); const changes = { tasks: { // A new task, and task 1 now takes three days. add: [{ id: 3, start_date: "2026-08-10 08:00", duration: 1 }], update: [{ id: 1, duration: 3 }], }, // The new link has no id: apply generates one. links: { add: [{ source: 2, target: 3, type: "fs" }] }, }; const report = unwrap(project.apply(JSON.stringify(changes))); for (const op of report.applied) console.log(`applied ${op.path}`); console.log("generated links:", report.effects.generatedLinks); const result = unwrap(project.solve(undefined, "{}")); for (const update of result.updates) { console.log(`task ${update.id}: ${update.start_date} .. ${update.end_date}`); } } finally { project.free(); } ``` The report lists `tasks.add[0]`, `tasks.update[0]` and `links.add[0]`, and the new link is `$generated_link_1`. After the solve: ``` task 1: 2026-08-10 08:00 .. 2026-08-13 08:00 task 2: 2026-08-13 08:00 .. 2026-08-18 08:00 task 3: 2026-08-18 08:00 .. 2026-08-19 08:00 ``` `apply` doesn't run the operations in the order you wrote them. It uses a [fixed order](), so every reference comes after the adds it may need, and every removal comes before the edits it could break: 1. tasks: remove, add, update 2. links: remove, update, add 3. resources: remove, add, update 4. assignments: remove, update, add An operation is named by its group, list and index, such as `tasks.update[0]`. The same path shows up in the [report]()'s `applied` and `rejected` lists. The change set and its `{add, update, remove}` buckets reject unknown fields with a `parse` error. The records inside the lists ignore them, like records in `ProjectData`. ## Update records An update record names its target by `id` and lists only the fields to change. Each field has three states: - Left out: the field keeps its value. - A value: the field is set. - `null`: an optional field is cleared, or a field that always has a value goes back to its default. `auto_scheduling` goes back to `true`, `unscheduled` to `false`, `progress` to `0`, `priority` to `500`, `leveling_delay` to `0`, `pauses` to empty, a link's `type` to `"fs"` and its `lag` to `0`. `constraint_type: ""` clears the constraint the same way `null` does. ```js 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; } function edit(project, update) { const report = unwrap(project.apply(JSON.stringify({ tasks: { update: [update] } }))); if (report.needsResync) throw new Error(report.rejected[0].message); return unwrap(project.solve(undefined, "{}")).updates; } const data = { config: { apply_constraints: true }, tasks: [{ id: "review", start_date: "2026-08-10 08:00", duration: 1 }], }; const project = new JsonProject("{}"); try { unwrap(project.solve(JSON.stringify(data), "{}")); // A value sets a field: "start no earlier than Thursday". for (const update of edit(project, { id: "review", constraint_type: "snet", constraint_date: "2026-08-13 08:00", })) { console.log(`pinned: ${update.id} starts ${update.start_date}`); } // null clears the constraint; start_date moves the task back. // Every field you leave out keeps its value. for (const update of edit(project, { id: "review", constraint_type: null, constraint_date: null, start_date: "2026-08-10 08:00", })) { console.log(`unpinned: ${update.id} starts ${update.start_date}`); } } finally { project.free(); } ``` The first solve moves the task to `2026-08-13 08:00`. The second puts it back on Monday. Clearing the constraint alone wouldn't do that. The accepted state already holds the Thursday dates, so the update also sets `start_date`. Be careful with `undefined` and non-finite numbers in your update objects. `JSON.stringify` drops a field set to `undefined`, so the field stays unchanged. It turns `NaN` and `Infinity` into `null`, which clears the field. Check values before you serialize them. The full field lists are on [`TaskUpdate`]() and [common types](). :::note A `priority` outside 0..1000 or a malformed hour range fails the whole call with a `validation` error that has no `path`. In `apply`, this means no operation from that change set is applied. ::: ### Which dates a task update keeps A task has three linked date fields: `start_date`, `end_date` and `duration`. When an update sets some of them, `apply` keeps what you sent and derives the rest: - `start_date` alone keeps the duration and recomputes the end (a drag). - `end_date` alone keeps the start and recomputes the duration (a resize from the right edge). - `duration` alone keeps the start and recomputes the end. - `start_date` and `end_date` together recompute the duration. - A new `calendar_id`, or a new `parent` while [`config.calendar_mode`]() is `"task-inherited"`, keeps the start and duration and recomputes the end on the new calendar. Descendants that inherit that calendar re-derive their ends too. An explicit `start_date` on non-working time is kept as sent when the task has no predecessor. The end is computed forward from it on the working calendar, so only the start sits outside working time. Snap the date in your UI if you don't want that. ### Feeding results back The entries in `result.updates` (see [`ScheduleResult`]()) use the same snake_case field names as a task update. Their extra `kind` and `reason` fields are ignored as unknown fields. So you can send result entries back to [`apply`]() as they are. This is how you commit dates from [`preview`]() or from a leveled [clone](): ```js 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 = { tasks: [ { id: 1, start_date: "2026-08-10 08:00", duration: 2 }, { id: 2, start_date: "2026-08-10 08:00", duration: 2 }, ], links: [{ id: "l", source: 1, target: 2, type: "fs" }], }; const project = new JsonProject("{}"); try { unwrap(project.solve(JSON.stringify(data), "{}")); const preview = unwrap( project.preview(JSON.stringify({ tasks: { update: [{ id: 1, duration: 3 }] } }), "{}"), ); // Commit exactly the dates the user saw. const report = unwrap( project.apply( JSON.stringify({ baselineId: preview.baselineId, tasks: { update: preview.updates } }), ), ); if (report.needsResync) throw new Error("edit rejected; resync with solve(dataJson, ...)"); unwrap(project.solve(undefined, "{}")); } finally { project.free(); } ``` [`pauses`]() replaces the whole list. Send `[]` or `null` to remove every pause. See [Clear leveling](). ## Applying [`apply`]() returns an [`ApplyReport`]() in the envelope's `result`: - `applied` lists the path of every accepted operation. - `rejected` lists the path and message of every refused one. - [`effects`]() lists what the edit changed beyond the records you named (below). - `needsResync` is `true` when anything was rejected. - `revision` is the project's revision number after this edit. Removals cascade, and `effects` tells you what went with them. Removing a task removes its descendants, every link that touches any of them and every assignment on them. Removing a resource removes its assignments. ```js 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 = { tasks: [ { id: "phase", type: "summary" }, { id: "spec", parent: "phase", start_date: "2026-08-10 08:00", duration: 2 }, { id: "release", start_date: "2026-08-10 08:00", duration: 1 }, ], links: [{ id: "spec-release", source: "spec", target: "release", type: "fs" }], resources: [{ id: "ann" }], assignments: [{ id: "ann-spec", task: "spec", resource: "ann", value: 1 }], }; const project = new JsonProject("{}"); try { unwrap(project.solve(JSON.stringify(data), "{}")); const report = unwrap(project.apply(JSON.stringify({ tasks: { remove: ["phase"] } }))); const { removedTasks, removedLinks, removedAssignments } = report.effects; console.log("tasks:", removedTasks); console.log("links:", removedLinks); console.log("assignments:", removedAssignments); } finally { project.free(); } ``` Removing the summary `phase` also removes `spec`, the link `spec-release` and the assignment `ann-spec`. Delete the same records from your own model. The other `effects` lists: - `generatedLinks` and `generatedAssignments` hold the ids `apply` made up for additions without one. - `droppedLinks` and `droppedAssignments` hold records that were accepted but are inactive, for example a link to an unscheduled task. They stay in the project and come back into play when the task does. The next solve explains each one in a `dropped-link` or `dropped-assignment` [note](). `apply` edits the handle in place. A [`clone()`]() made earlier doesn't see the edit. To try a multi-step edit, apply it to a clone and [`free()`]() the clone if the user cancels. For a single edit, [`preview`]() does the same job without a clone. See [Previewing changes](). Field-only task edits and assignment updates take a fast path that patches the affected records without rebuilding the whole model. Frequent small edits, like drags, stay cheap. The change set is still JSON text, so send only the fields that changed. See [Module and handles](). ## Rescheduling After `apply`, call [`solve(undefined, optionsJson)`](). It schedules the edited state, accepts the dates as the new baseline and returns the updates relative to the previous one. Tasks that a successful operation added or updated are always reported, even when the planner leaves them exactly where the edit put them. The same goes for tasks whose working calendars changed because of a resource or assignment edit. So your model gets the derived end or duration of every task you edited, not only of the ones that moved. These reported tasks accumulate across several `apply` calls until the next acyclic `solve` without data, or [`level`](). A cyclic solve keeps them pending. ### Guarding against stale edits A UI usually edits the dates it showed the user. If the project changed in between (an edit from another tab, a leveling run), applying the edit can do the wrong thing. Set [`baselineId`]() in the change set to the token of the result the user saw. `apply` then refuses the whole change set with [`stale-baseline`]() when that token isn't current. ```js 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 = { tasks: [{ id: 1, start_date: "2026-08-10 08:00", duration: 2 }] }; const project = new JsonProject("{}"); try { const loaded = unwrap(project.solve(JSON.stringify(data), "{}")); const seen = loaded.baselineId; // The edit was made against the dates the user saw. const changesJson = JSON.stringify({ baselineId: seen, tasks: { update: [{ id: 1, duration: 3 }] }, }); unwrap(project.apply(changesJson)); // A second edit still carrying the old token is refused as a whole. const response = JSON.parse(project.apply(changesJson)); if (!response.ok && response.error.code === "stale-baseline") { console.log("stale: reload first"); } const solved = unwrap(project.solve(undefined, "{}")); console.log("new baseline differs:", solved.baselineId !== seen); } finally { project.free(); } ``` A token names a baseline only while the project is solved and clean. After an `apply`, any `baselineId` is stale until the next solve, so take a fresh token from each result. Tokens are opaque: don't store them or compare them across runs. Leave `baselineId` out to skip the check. ## Rejections and resync An operation is rejected when it can't apply. Typical causes: - an unknown id in `update` or `remove` - a duplicate id in `add` - `null` on a required field: a link's `source` or `target`, an assignment's `task`, `resource` or `value` - a record that fails validation after the edit, such as an invalid pause or assignment slice Each operation is tried on its own copy, so a rejected operation leaves no partial edit behind, and the operations around it still apply. ```js 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; } // Your own model: the source of truth for a resync. function loadJson() { return JSON.stringify({ tasks: [{ id: "design", start_date: "2026-08-10 08:00", duration: 2 }], }); } const project = new JsonProject("{}"); try { unwrap(project.solve(loadJson(), "{}")); const changes = { tasks: { remove: ["deleted-elsewhere"], update: [{ id: "design", duration: 4 }], }, }; const report = unwrap(project.apply(JSON.stringify(changes))); for (const op of report.applied) console.log(`applied ${op.path}`); for (const op of report.rejected) console.log(`rejected ${op.path}: ${op.message}`); if (report.needsResync) { // solve without data and apply now fail until the full data is sent again. const response = JSON.parse(project.solve(undefined, "{}")); if (!response.ok && response.error.code === "needs-resync") { unwrap(project.solve(loadJson(), "{}")); } } } finally { project.free(); } ``` The update applies and the removal is rejected: ``` applied tasks.update[0] rejected tasks.remove[0]: unknown task id ``` The project now holds the update but not the removal, which is probably not what your model holds. That's why any rejection blocks further edits. `solve` without data, `apply` and `level` return [`needs-resync`]() until a successful `solve(dataJson, …)` replaces the whole state with data you know is right. The resync data must pass validation. If it doesn't, you get a `parse` or `validation` error envelope, and the project still needs a resync. See [Recover from rejected changes](). [`evaluate`]() and [`suggestAssignments`]() run the same apply on disposable copies. A rejected candidate shows up as its [`CandidateResult.error`]() (`{path, message}`) instead of blocking the project. See [Evaluating alternatives](). ## What change sets can't do Some edits have no operation. For these, rebuild the data in your model and send it with [`solve(dataJson, …)`](): - Calendars can't be added, changed or removed. Tasks and resources can switch to another existing calendar through `calendar_id`. - [`config`]() can't change: `duration_unit`, `use_calendars`, `calendar_mode`, `apply_constraints` and the other settings stay fixed until the next full solve. - A task's `type` and `duration_unit` aren't in [`TaskUpdate`](). To turn a task into a summary or a milestone, remove it and add it again (its links and assignments go with the removal), or resync. - An id can't be renamed. `update` finds the record by its id and never changes it. - A [resource update]() changes only `capacity` and `calendar_id`. Calls that don't need a change set don't take one. [`level`]() writes its own `leveling_delay` and `pauses` edits and accepts the result. See [Leveling resources]().