[Canonical page](<https://docs.dhtmlx.com/planning-engine/js/api/types/common/>)
[Full documentation index](<https://docs.dhtmlx.com/planning-engine/llms.txt>)


# Common types

Scalar types, string unions and small object shapes that several calls and records share. Every one of them is exported as a type from `plen-js`.

## Id

The id of a task, link, calendar, resource, assignment, slot or candidate.

```ts
type Id = string | number;
```

Ids compare the way JavaScript object keys do, so `7` and `"7"` name the same object. Numeric ids are plain `number`s: an integer above `Number.MAX_SAFE_INTEGER` loses precision, so pass 64-bit ids as strings. Results return each id in the type it was passed in.

```js
const ids = [1, "1", "task-7", 2.5]; // the first two name the same object
```

Used wherever a record or option refers to an object: `id`, `parent`, `source`, `target`, `task`, `resource`, `calendar_id`, and the id lists in results. See [Numbers and ids](<https://docs.dhtmlx.com/planning-engine/js/plain-objects-and-dates.md#numbers-and-ids>).

## DateValue

A date and time of day, as a string or a `Date`.

```ts
type DateValue = string | Date;
```

| Direction | Form |
|---|---|
| Input string | `YYYY-MM-DD`, with an optional `HH:MM` or `HH:MM:SS` after a space or a `T`. A bare date means `00:00`. Seconds are dropped. |
| Input `Date` | Read from its local components (year, month, day, hour, minute). Seconds and milliseconds are dropped. |
| Output | A `"YYYY-MM-DD HH:MM"` string. A local `Date` when the project was created with [`dates: "date"`](<https://docs.dhtmlx.com/planning-engine/js/api/project.md#projectoptions>). |

Dates have no timezone: every value is local wall-clock time at minute precision.

```js
const starts = ["2026-03-02", "2026-03-02 08:00", "2026-03-02T08:00:30", new Date(2026, 2, 2, 8, 0)];
// read as 2026-03-02 00:00, then 2026-03-02 08:00 three times
```

An unparseable string throws [`InputError`](<https://docs.dhtmlx.com/planning-engine/js/api/types/errors.md>) with `kind: "validation"` and message `"invalid date"`. An invalid `Date` throws `InputError` with message `"Invalid Date"`.

Used by task and constraint dates, `config.project_start` / `project_end`, profile and leveling ranges, and every date in a result. See [Plain objects and dates](<https://docs.dhtmlx.com/planning-engine/js/plain-objects-and-dates.md#dates-in>).

## TimeUnit

The unit of a duration, a lag, a leveling delay or a pause.

```ts
type TimeUnit = "minute" | "hour" | "day";
```

`"week"`, `"month"` and `"year"` are reserved and throw `InputError` with `kind: "validation"`. In the elapsed fields `leveling_delay` and `pauses`, an hour is 60 minutes and a day is 24 hours.

Used by [`SchedulingConfig`](<https://docs.dhtmlx.com/planning-engine/js/api/types/scheduling-config.md>)`.duration_unit` (default `"day"`), [`TaskData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/task-data.md>)`.duration_unit` and [`LinkData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/link-data.md>)`.lag_unit`.

## ConstraintType

A task's scheduling constraint. Values match in any case, so `"SNET"` is accepted.

```ts
type ConstraintType = "asap" | "alap" | "snet" | "snlt" | "fnet" | "fnlt" | "mso" | "mfo";
```

| Value | Constraint | Needs `constraint_date` |
|---|---|---|
| `"asap"` | As soon as possible | no |
| `"alap"` | As late as possible | no |
| `"snet"` | Start no earlier than | yes |
| `"snlt"` | Start no later than | yes |
| `"fnet"` | Finish no earlier than | yes |
| `"fnlt"` | Finish no later than | yes |
| `"mso"` | Must start on | yes |
| `"mfo"` | Must finish on | yes |

Any other string throws `InputError` with `kind: "validation"`. Used by [`TaskData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/task-data.md>)`.constraint_type`, [`TaskUpdate`](<https://docs.dhtmlx.com/planning-engine/js/api/types/task-update.md>)`.constraint_type` and the `constraint-violation` [conflict](<https://docs.dhtmlx.com/planning-engine/js/api/types/schedule-result.md#conflict>). How constraints act is in [Links, constraints and summaries](<https://docs.dhtmlx.com/planning-engine/js/scheduling/links-constraints-summaries.md#constraints>).

## ResourceData

A resource that assignments book.

```ts
interface ResourceData { id: Id; capacity?: number | null; calendar_id?: Id | null }
```

| Field | Type | Default | Description |
|---|---|---|---|
| `id` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>) | required | Resource id. |
| `capacity` | `number \| null` | `config.default_resource_capacity` (`1`) | Units the resource carries per bucket, in assignment `value` units (`1` = 100 %). Finite and `>= 0`. |
| `calendar_id` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>) `\| null` | none | The resource's calendar. With `calendar_mode: "resource"` it must name a calendar in `ProjectData.calendars`. |

Unknown fields are ignored. An invalid `capacity` throws `InputError` with `kind: "validation"` at `resources[i].capacity`; an unknown `calendar_id` at `resources[i].calendar_id`.

Used by [`ProjectData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/project-data.md>)`.resources` and `resources.add` in [`SchedulingChanges`](<https://docs.dhtmlx.com/planning-engine/js/api/types/scheduling-changes.md>). An edit to an existing resource is a [`ResourceUpdate`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#linkupdate-resourceupdate-assignmentupdate>). How resource calendars work is in [Working time and calendars](<https://docs.dhtmlx.com/planning-engine/js/scheduling/working-time-calendars.md#resource-calendars>).

## LinkAdd

A new link in `links.add` of a change set: a [`LinkData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/link-data.md>) whose `id` is optional.

```ts
type LinkAdd = Omit<LinkData, "id"> & { id?: Id | null };
```

A link without an `id` (or with `id: null`) gets a generated one. Used by [`SchedulingChanges`](<https://docs.dhtmlx.com/planning-engine/js/api/types/scheduling-changes.md>)`.links.add`.

## LinkUpdate, ResourceUpdate, AssignmentUpdate

Partial records in the `update` arrays of a change set: `id` is required, every other field of the base record is optional.

```ts
type LinkUpdate = Partial<LinkData> & { id: Id };
type ResourceUpdate = Partial<ResourceData> & { id: Id };
type AssignmentUpdate = Partial<AssignmentData> & { id: Id };
```

| Type | Base record | Used by |
|---|---|---|
| `LinkUpdate` | [`LinkData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/link-data.md>) | `links.update` |
| `ResourceUpdate` | [`ResourceData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#resourcedata>) | `resources.update` |
| `AssignmentUpdate` | [`AssignmentData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/assignment-data.md>) | `assignments.update` |

All three go in [`SchedulingChanges`](<https://docs.dhtmlx.com/planning-engine/js/api/types/scheduling-changes.md>). A task edit is a [`TaskUpdate`](<https://docs.dhtmlx.com/planning-engine/js/api/types/task-update.md>).

## Pause

One leveling split in a task's work.

```ts
interface Pause { at: number; length: number; by?: "leveling" }
```

| Field | Type | Default | Description |
|---|---|---|---|
| `at` | `number` | required | Start of the pause after the task start. Elapsed time in the task's `duration_unit`, finite and `>= 0`. |
| `length` | `number` | required | Length of the pause. Elapsed time in the task's `duration_unit`, finite and `> 0`. |
| `by` | `"leveling"` | absent | Who wrote the pause. `"leveling"` is the only value; the leveler sets it on every pause it writes. |

A pause occupies the whole minutes from `round(at)` to `round(at + length)`. A pause that rounds to zero length is ignored. Unknown fields are ignored.

Used by [`TaskData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/task-data.md>)`.pauses`, [`TaskUpdate`](<https://docs.dhtmlx.com/planning-engine/js/api/types/task-update.md>)`.pauses` and [`Mutation`](<https://docs.dhtmlx.com/planning-engine/js/api/types/schedule-result.md#mutation>)`.pauses`. How pauses affect dates and load is in [Leveling resources](<https://docs.dhtmlx.com/planning-engine/js/resources-and-assignment/leveling-resources.md#delays-and-pauses>).

## Subtree

Limits a run to one task's subtree and the tasks that depend on it.

```ts
interface Subtree { task: Id; inclusive?: boolean }
```

| Field | Type | Default | Description |
|---|---|---|---|
| `task` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>) | required | Root task of the branch. Must be a known, scheduled task. |
| `inclusive` | `boolean` | `true` | Whether the root task itself is scheduled. `null` reads as `true`. |

Unknown fields throw `InputError` with `kind: "parse"`. An unknown or unscheduled `task` throws `InputError` with `kind: "validation"` at `subtree.task`.

Used by [`SolveOptions`](<https://docs.dhtmlx.com/planning-engine/js/api/types/solve-options.md>)`.subtree` and [`PreviewOptions`](<https://docs.dhtmlx.com/planning-engine/js/api/project-preview.md#previewoptions>)`.subtree`. See [Reschedule a branch](<https://docs.dhtmlx.com/planning-engine/js/how-to/reschedule-a-branch.md>).

## AnalyticsOptions

Requests analytics in a result.

```ts
interface AnalyticsOptions { slack?: boolean; criticalPath?: boolean }
```

| Field | Type | Default | Description |
|---|---|---|---|
| `slack` | `boolean` | `false` | `true` fills `analytics.slack`: total and free slack per task, in `config.duration_unit`. |
| `criticalPath` | `boolean` | `false` | `true` fills `analytics.criticalPath`: critical task and link ids. |

`null` reads as `false`. Unknown fields throw `InputError` with `kind: "parse"`. The filled shape is [`Analytics`](<https://docs.dhtmlx.com/planning-engine/js/api/types/schedule-result.md#analytics>).

Used by [`SolveOptions`](<https://docs.dhtmlx.com/planning-engine/js/api/types/solve-options.md>)`.analytics`, [`PreviewOptions`](<https://docs.dhtmlx.com/planning-engine/js/api/project-preview.md#previewoptions>)`.analytics` and [`AnalyzeOptions`](<https://docs.dhtmlx.com/planning-engine/js/api/project-analyze.md#analyzeoptions>)`.analytics`. See [Critical path and slack](<https://docs.dhtmlx.com/planning-engine/js/scheduling/critical-path-and-slack.md>).

## ProfileQuery

The range, resources and detail a load profile covers.

```ts
interface ProfileQuery {
  from: DateValue;
  to: DateValue;
  resources?: Id[];
  basis?: "hour" | "day";
  tasks?: "none" | "overallocated" | "all";
}
```

| Field | Type | Default | Description |
|---|---|---|---|
| `from` | [`DateValue`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#datevalue>) | required | Range start. Buckets whose start lies in `[from, to)` are reported. |
| `to` | [`DateValue`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#datevalue>) | required | Range end, after `from`. |
| `resources` | [`Id`](<https://docs.dhtmlx.com/planning-engine/js/api/types/common.md#id>)`[]` | every resource | Resources to report. |
| `basis` | `"hour" \| "day"` | derived from `config.duration_unit` | Bucket size: `"day"` for a `"day"` unit, `"hour"` for `"hour"` and `"minute"`. |
| `tasks` | `"none" \| "overallocated" \| "all"` | `"none"` | Task ids per bucket: none (the field is absent), only in buckets where load exceeds capacity, or every booked task. `null` reads as `"none"`. |

Unknown fields throw `InputError` with `kind: "parse"`. These throw `InputError` with `kind: "validation"`:

- `to` not after `from`, or more than 100 000 buckets per resource, at `to`
- an unknown resource id, at `resources`
- any other `tasks` value

Used by [`PreviewOptions`](<https://docs.dhtmlx.com/planning-engine/js/api/project-preview.md#previewoptions>)`.profile`. [`LoadProfileOptions`](<https://docs.dhtmlx.com/planning-engine/js/api/project-load-profile.md#loadprofileoptions>) takes the same fields flat, next to `baselineId`. The result is a [`LoadProfile`](<https://docs.dhtmlx.com/planning-engine/js/api/types/load-profile.md>). See [Resource load](<https://docs.dhtmlx.com/planning-engine/js/resources-and-assignment/resource-load.md>).

## RejectedOperation

An operation of a change set that was refused.

```ts
interface RejectedOperation { path: string; message: string }
```

| Field | Type | Description |
|---|---|---|
| `path` | `string` | The refused operation, e.g. `"tasks.update[0]"`. |
| `message` | `string` | Why the operation was refused. |

Used by [`ApplyReport`](<https://docs.dhtmlx.com/planning-engine/js/api/project-apply.md#applyreport>)`.rejected` and [`CandidateResult`](<https://docs.dhtmlx.com/planning-engine/js/api/project-evaluate.md#candidateresult>)`.error`. See [Recover from rejected changes](<https://docs.dhtmlx.com/planning-engine/js/how-to/recover-from-rejected-changes.md>).

## Related

- [`ProjectData`](<https://docs.dhtmlx.com/planning-engine/js/api/types/project-data.md>) - the plan these shapes appear in
- [`SchedulingChanges`](<https://docs.dhtmlx.com/planning-engine/js/api/types/scheduling-changes.md>) - the change set that uses the add and update shapes
- [Plain objects and dates](<https://docs.dhtmlx.com/planning-engine/js/plain-objects-and-dates.md>) - how ids, dates and numbers are read
- [Project data](<https://docs.dhtmlx.com/planning-engine/js/scheduling/project-data.md>) - tasks, links, ids and dates in a plan