Class: Dataset<TProps>
Defined in: api/dataset.ts:171
Type Parameters
TProps
TProps = unknown
Constructors
Constructor
new Dataset<
TProps>(options):Dataset<TProps>
Defined in: api/dataset.ts:181
Parameters
options
DatasetOptions<TProps>
Returns
Dataset<TProps>
Accessors
canRedo
Get Signature
get canRedo():
boolean
Defined in: api/dataset.ts:399
true while there is an undone changeset redo() can re-apply. Always false under
history: false.
Returns
boolean
canUndo
Get Signature
get canUndo():
boolean
Defined in: api/dataset.ts:393
true while there is a committed changeset undo() can reverse. Always false under
history: false.
Returns
boolean
datasetRevision
Get Signature
get datasetRevision():
number
Defined in: api/dataset.ts:364
A counter that rises once per committed change. Call: if (dataset.datasetRevision !== seen)
— read it to answer "has anything changed since I last looked?" without diffing entries.
A consumer reads this and never passes it anywhere. The library keeps its own caches fresh from it internally, so nothing an app author writes has to carry it.
Returns
number
entries
Get Signature
get entries():
EntryStore<TProps>
Defined in: api/dataset.ts:293
Returns
EntryStore<TProps>
fields
Get Signature
get fields():
object
Defined in: api/dataset.ts:335
Resolved Field declarations this Dataset owns, core Fields included, each after its
named type bundle merges in.
Returns
object
all
readonlyall: readonlyField[]
locale
Get Signature
get locale():
LocalesArgument
Defined in: api/dataset.ts:304
This Dataset's own locale (#583), fixed at construction — undefined when the consumer named
none. formatFieldValue's own locale argument beats it; a Gantt with no locale of its own
reads it before the runtime's own.
Returns
LocalesArgument
plugins
Get Signature
get plugins(): readonly
PluginOf<unknown,unknown>[]
Defined in: api/dataset.ts:282
The plugins this Dataset installed, in the order the caller wrote them. Read-only — see
DatasetOptions.plugins for why a Dataset cannot take a new set after construction. Each
plugin's own props stay erased here (DatasetOptions.plugins); the entry itself is unaffected.
Returns
readonly PluginOf<unknown, unknown>[]
time
Get Signature
get time():
ZonedTime
Defined in: api/dataset.ts:311
Zone-aware date math bound to this Dataset's own zone — the one way a plugin author
reaches time/ (the exports map seals it against a direct import). Call:
dataset.time.eachDay(span).filter((day) => dataset.time.dayOfWeek(day) >= 6).
Returns
timeZone
Get Signature
get timeZone():
string
Defined in: api/dataset.ts:297
Returns
string
Methods
destroy()
destroy():
void
Defined in: api/dataset.ts:288
Releases every installed data half, in reverse setup order. A Dataset with no plugins needs no
destroy() call — nothing holds a resource.
Returns
void
editableOf()
editableOf(
id,field):FieldEditable
Defined in: api/dataset.ts:355
Call: dataset.editableOf('van-1', 'cost') — the effective lock on one cell (#473): a plugin's
own per-entry lock rule's answer, or the Field's own editable when the rule has no opinion.
The same resolver entries.update(), an EditExtender cascade, and the grid all read (I14). An
undeclared key answers 'never': nothing is written to a key nothing declares.
Parameters
id
string | EntryId
field
Returns
field()
field(
key):Field|undefined
Defined in: api/dataset.ts:317
The resolved Field for this key, or undefined when the key is not declared. This is the
declaration, not an Entry value; entry.read(key) reads the value.
Parameters
key
Returns
Field | undefined
formatFieldValue()
formatFieldValue(
entry,key,locale?):string
Defined in: api/dataset.ts:327
Call: dataset.formatFieldValue(entry, 'cost', 'de-DE') — "format this entry's cost value, in
German". The same text a grid cell, a bar label and the tooltip show: the Field's own
formatValue, or the plain text of a primitive value. The zone is this Dataset's. locale
beats this Dataset's own locale (#583); omit both for the runtime's own locale. No Gantt is
needed, so a server-side export reads the text through this. Throws UnknownFieldError for an
undeclared key.
Parameters
entry
Entry<TProps>
key
locale?
LocalesArgument
Returns
string
off()
off<
K>(name,handler):void
Defined in: api/dataset.ts:384
Type Parameters
K
K extends keyof DatasetEventMap
Parameters
name
K
handler
(payload) => false | void
Returns
void
on()
on<
K>(name,handler):Disposer
Defined in: api/dataset.ts:377
Every plugin registration seam returns a Disposer that removes exactly its own registration
(I2); on is that seam for a Dataset event. off(name, handler) still works too.
Type Parameters
K
K extends keyof DatasetEventMap
Parameters
name
K
handler
(payload) => false | void
Returns
pluginStore()
Call Signature
pluginStore<
T>(pluginId):PluginStoreView<T> |undefined
Defined in: api/dataset.ts:447
Call: dataset.pluginStore('acme/locks') — one plugin's rows, read-only, or undefined when
that plugin never reserved a store. dataset.pluginStore() with no argument answers every store
this Dataset holds, as a record keyed by plugin id: Object.entries(dataset.pluginStore()).
A plugin's own data is not on this Dataset until that plugin installs and reserves a store — no door takes rows in ahead of that (ADR 0016). An application that must keep a plugin's data saves it by reading this, and restores it through the plugin's own API after re-installing the plugin.
Type Parameters
T
T extends object
Parameters
pluginId
string
Returns
PluginStoreView<T> | undefined
Call Signature
pluginStore():
Readonly<Record<PluginId,PluginStoreView<object>>>
Defined in: api/dataset.ts:448
Call: dataset.pluginStore('acme/locks') — one plugin's rows, read-only, or undefined when
that plugin never reserved a store. dataset.pluginStore() with no argument answers every store
this Dataset holds, as a record keyed by plugin id: Object.entries(dataset.pluginStore()).
A plugin's own data is not on this Dataset until that plugin installs and reserves a store — no door takes rows in ahead of that (ADR 0016). An application that must keep a plugin's data saves it by reading this, and restores it through the plugin's own API after re-installing the plugin.
Returns
Readonly<Record<PluginId, PluginStoreView<object>>>
redo()
redo():
void
Defined in: api/dataset.ts:420
Re-applies the most recently undone changeset. A no-op when canRedo is false. A write
arrives on on('change'). A click that only forgets steps fires historyChange and not
change, the same as undo(). Undoing this redo writes back exactly what this call wrote —
undo then redo is neutral, even across a sync in between.
Returns
void
replay()
replay(
changeSet,options?):void
Defined in: api/dataset.ts:436
Writes changeSet onto the store's current values, not blind
(plans/s2-data-core/s2b-undo-replay-seam.md, amended for local-only undo across a sync). A row
for an id or a Field a sync has already settled writes nothing for it; the rest of the changeset
still lands. A row for a key no Field declares writes nothing. An entry a foreign write changed
since the step recorded it keeps its current values, unless options.overwriteForeignWrites is
true (#549). No extension hook. It re-rolls every parent it touches, construction shape; with
no foreign write in between, the Rollup writes nothing. changeSet.origin must be 'undo' or
'redo'; 'user' throws InvalidReplayOriginError — that door is apply, not open yet. When
nothing is left to write, this is a no-op: no beforeChange, no change. Otherwise beforeChange
then change fire, and a veto throws MutationCancelledError and writes nothing. This is the
write path undo()/redo() use; a consumer History can now be written against this method alone,
plus invertChangeSet and on('change').
Parameters
changeSet
options?
Returns
void
setFieldEditable()
setFieldEditable(
key,editable):void
Defined in: api/dataset.ts:347
Call: dataset.setFieldEditable('start', 'never') — "set Field start editable to never."
The Field set is fixed after construction; this one attribute is not (ADR 0015). It changes a
Field the Dataset already declares and adds none, so an unknown key throws UnknownFieldError.
true and false still alias 'anywhere' and 'never'.
Which Entry a value is writable on is gantt.capabilities.edit, per row. This key states
which values are writable at all.
Parameters
key
editable
boolean | FieldEditable
Returns
void
transaction()
transaction<
T>(body):T
Defined in: api/dataset.ts:371
Batches body's mutations into one changeset. Nested calls join the open transaction.
'user' is the only origin a call to transaction() can produce — entries.load() and
entries.syncAll() refuse to run inside one, since each is always its own transaction.
Type Parameters
T
T
Parameters
body
() => T
Returns
T
undo()
undo():
void
Defined in: api/dataset.ts:412
Reverts the most recent undoable changeset (plans/s2-data-core/s2.5-undo-redo.md §1). A no-op
when canUndo is false. A write arrives on on('change'), like every other commit — a
refused undo throws MutationCancelledError and leaves the history exactly where it was.
Writes onto the store's current values, not blind. An entry a sync changed since this step was
recorded keeps the sync's values, and a step left with nothing to write is skipped in favor of
the one before it, in this same call (docs/11-server-data.md). A click that only forgets steps
writes nothing, so it fires historyChange and not change. Undo chrome listens on
on('historyChange').
Returns
void