Class: Item<S>

Defined in: cfds/base/item.ts:90

An Item instance represents a snapshot of a data item including all of its fields. An item is a map like object that tracks both the data and its schema. Items are the contents of specific versions (commits) in the version graph (history).

Typically you never need to create instances of this class directly. Instead, use GoatDB.item() in order to get a LiveItem instance that's much easier to work with.

Type Parameters

Type Parameter	Default type
S extends Schema	Schema

Implements

• ReadonlyItem<S>
• Encodable

Constructors

Constructor

new Item<S>(config, registry?): Item<S>

Defined in: cfds/base/item.ts:108

Creates a new Item instance.

Parameters

Parameter	Type	Description
config	ItemConfig<S> | ConstructorDecoderConfig<EncodedItem>	Either an ItemConfig object containing the schema and data, or a ConstructorDecoderConfig for deserializing an encoded item
registry?	DataRegistry	Optional schema manager to use. If not provided, the default schema manager will be used

Returns

Item<S>

Properties

Property	Modifier	Type	Defined in
registry	readonly	DataRegistry	cfds/base/item.ts:92

Accessors

checksum

Get Signature

get checksum(): string

Defined in: cfds/base/item.ts:224

Returns a checksum that can be used to efficiently test for equality between two records. It's also used to guard against diff/patch bugs.

Any legacy cryptographic hash would probably do here. The current implementation uses MD5 simply because its so common.

Returns

string

Implementation of

ReadonlyItem.checksum

---

isDeleted

Get Signature

get isDeleted(): boolean

Defined in: cfds/base/item.ts:188

Indicates whether this item had been deleted or not. Deleted items will eventually be garbage collected, and receive special treatment by the system.

NOTE: It's perfectly OK to mark a deleted item as not deleted. Yay for distributed version control. The delete marker goes through conflict resolution the same as any other schema field.

Returns

boolean

Set Signature

set isDeleted(flag): void

Defined in: cfds/base/item.ts:203

Sets or clears the delete marker from this item. Marking an item as deleted sets it for future garbage collection rather than delete it immediately.

A deleted item will not appear in query results, but will still get sync'ed and go through conflict resolution.

NOTE: It's perfectly fine to set this flag then clear it at a later time. Clearing the delete marker recovers the item and reverts it back to a regular, not deleted, item.

Parameters

Parameter	Type
flag	boolean

Returns

void

---

isLocked

Get Signature

get isLocked(): boolean

Defined in: cfds/base/item.ts:681

Returns whether this item is locked or not. Locked items cannot be modified. Items are locked when they represent a specific version in history.

Returns

boolean

---

isNull

Get Signature

get isNull(): boolean

Defined in: cfds/base/item.ts:145

Returns whether this item has a null schema or not. The null schema is empty and has no fields and no values.

Returns

boolean

Implementation of

ReadonlyItem.isNull

---

isValid

Get Signature

get isValid(): boolean

Defined in: cfds/base/item.ts:161

Returns the validation status of this item. Before persisting the item must first be valid or it won't be able to be persisted locally nor sync'ed across the network.

Returns

boolean

Implementation of

ReadonlyItem.isValid

---

keys

Get Signature

get keys(): keyof S["fields"][]

Defined in: cfds/base/item.ts:237

Returns the keys currently present in this item.

Returns

keyof S["fields"][]

---

schema

Get Signature

get schema(): S

Defined in: cfds/base/item.ts:152

The schema of this item.

Returns

S

Implementation of

ReadonlyItem.schema

Methods

assertValidData()

assertValidData(): void

Defined in: cfds/base/item.ts:659

Asserts that the item's data is valid according to its schema.

This method checks if the item's data conforms to the schema's requirements. If the data is invalid, it throws an assertion error with the corresponding error message.

Returns

void

Throws

If the item's data is invalid

---

clone()

clone(): Item<S>

Defined in: cfds/base/item.ts:384

Clones the current item.

This method creates a new Item instance with the same schema and data as the current item. The new item is a deep copy of the current item, including all nested objects and arrays.

Returns

Item<S>

---

cloneData()

cloneData(onlyFields?): Readwrite<SchemaDataType<S>>

Defined in: cfds/base/item.ts:403

Creates a deep copy of the item's data.

Parameters

Parameter	Type	Description
onlyFields?	keyof S["fields"][]	Optional array of field names to copy. If provided, only the specified fields will be cloned.

Returns

Readwrite<SchemaDataType<S>>

A deep copy of the item's data, or a partial copy if onlyFields is specified.

Implementation of

ReadonlyItem.cloneData

---

copyFrom()

copyFrom(doc): void

Defined in: cfds/base/item.ts:418

Copies data from another item into this one.

This method replaces the current item's schema and data with a deep copy of the source item's schema and data. The source item remains unchanged.

Parameters

Parameter	Type	Description
doc	Item<S> | ReadonlyItem<S>	The source item to copy from.

Returns

void

Throws

If this item is locked.

---

dataUnsafe()

dataUnsafe(): SchemaDataType<S>

Defined in: cfds/base/item.ts:213

WARNING: You probably shouldn't use this. Used internally as an optimization to avoid unnecessary copying.

Returns

SchemaDataType<S>

The underlying object primitive.

---

delete()

delete<T>(key): boolean

Defined in: cfds/base/item.ts:333

Deletes a given field from this item.

Type Parameters

Type Parameter
T extends string | number | symbol

Parameters

Parameter	Type	Description
key	T	The field to delete.

Returns

boolean

True if the field had been deleted, false if the field didn't exist and the item wasn't modified.

Throws

Throws if attempting to set a field not defined by this item's schema.

---

deserialize()

deserialize(decoder): void

Defined in: cfds/base/item.ts:604

Deserializes an encoded item into this instance.

This method decodes the item's schema, data, normalization status and checksum from an encoded format and updates this instance's state accordingly. The item is automatically normalized after deserialization.

Parameters

Parameter	Type	Description
decoder	Decoder	The decoder containing the encoded item data

Returns

void

Throws

If the item is locked or if the schema is unknown

---

diff()

diff(other, byCharacter?): DataChanges

Defined in: cfds/base/item.ts:441

Computes the differences between this item and another item.

This method compares the data of this item with another item of the same schema and returns an object describing the differences between them.

Parameters

Parameter	Type	Description
other	Item<S>	The item to compare against
byCharacter?	boolean	If true, rich text differences will be computed at the character level rather than at the paragraph/element level.

Returns

DataChanges

An object describing the differences between the two items

Throws

If the other item is not an Item instance

---

diffKeys()

diffKeys(other, local): string[]

Defined in: cfds/base/item.ts:484

Returns an array of field keys that differ between this item and another item.

This method compares the data of this item with another item of the same schema and returns an array of field keys where the values differ.

This is a much faster check than a full diff computation.

Parameters

Parameter	Type	Description
other	Item<S>	The item to compare against
local	boolean	If true, compare local fields. If false, ignores local fields

Returns

string[]

Array of field keys that have different values between the items

Throws

If the other item is not an Item instance

---

get()

get<T>(key): SchemaDataType<S>[T]

Defined in: cfds/base/item.ts:252

Returns the value for the given field or undefined.

If this is a null item (has no schema), returns undefined for all fields. Otherwise, returns the field's value, or undefined if not set.

Type Parameters

Type Parameter
T extends string | number | symbol

Parameters

Parameter	Type	Description
key	T	The field's name.

Returns

SchemaDataType<S>[T]

The field's value or undefined.

Throws

Throws if attempting to access a field not defined by this item's schema (unless this is a null item).

Implementation of

ReadonlyItem.get

---

has()

has<T>(key): boolean

Defined in: cfds/base/item.ts:277

Returns whether the given field is present on the current item or not.

Type Parameters

Type Parameter
T extends string | number | symbol

Parameters

Parameter	Type	Description
key	T	The field's name.

Returns

boolean

Whether the field is currently present on this item or not.

Throws

Throws if attempting to access a field not defined by this item's schema.

Implementation of

ReadonlyItem.has

---

isEqual()

isEqual(other): boolean

Defined in: cfds/base/item.ts:356

Compares this item with another item for equality. Two items are considered equal if they have the same schema and their data is equal after normalization.

Parameters

Parameter	Type	Description
other	Item<S>	The item to compare against

Returns

boolean

true if the items are equal, false otherwise

---

lock()

lock(): void

Defined in: cfds/base/item.ts:693

Locks this item, preventing any further modifications.

When an item is locked, attempts to modify its data will throw errors. The checksum is calculated and cached before locking to ensure consistency. Items are typically locked when they represent a specific version in history.

Returns

void

---

needsSchemaUpgrade()

needsSchemaUpgrade(): boolean

Defined in: cfds/base/item.ts:531

Checks if this item needs a schema upgrade.

This method checks if there is a newer schema version available for this item's namespace. It compares the item's current schema version with the latest schema version registered in the schema manager.

Returns

boolean

true if a newer schema version exists and the item needs an upgrade, false otherwise

---

normalize()

normalize(): void

Defined in: cfds/base/item.ts:558

Normalizes the item's data according to its schema.

This method ensures that all fields in the item's data conform to the schema's requirements by applying normalization rules. For example, it may:

• Convert field values to their proper types
• Apply default values for missing required fields
• Remove fields not defined in the schema

The normalization is only performed once - subsequent calls will have no effect. Null items (those with a null schema) are always normalized by definition.

Returns

void

---

patch()

patch(changes): void

Defined in: cfds/base/item.ts:462

Applies changes to this item's data.

This method takes a DataChanges object (typically produced by the diff() method) and applies those changes to this item's data. The item's data will be modified in place.

Parameters

Parameter	Type	Description
changes	DataChanges	The changes to apply to this item's data

Returns

void

Throws

If this item is locked

---

serialize()

serialize(encoder, options?): void

Defined in: cfds/base/item.ts:579

Serializes the item into an encoded format.

This method encodes the item's schema, data, normalization status and checksum into a format that can be stored or transmitted. The item is automatically normalized before serialization.

Parameters

Parameter	Type	Description
encoder	Encoder<string, CoreValue>	The encoder to use for serialization
options	{ local: boolean; }	Serialization options
options.local	boolean	If true, serialization includes local data. If false, local data is skipped.

Returns

void

Implementation of

Encodable.serialize

---

set()

set<T>(key, value): void

Defined in: cfds/base/item.ts:295

Sets the value for the given field.

Type Parameters

Type Parameter
T extends string | number | symbol

Parameters

Parameter	Type	Description
key	T	The field's name.
value	SchemaDataType<S>[T]	The value to set. Must match the value defined in this item's schema. If undefined is passed, this is the equivalent of calling Item.delete(key).

Returns

void

Throws

Throws if attempting to set a field not defined by this item's schema.

---

setMulti()

setMulti(data): void

Defined in: cfds/base/item.ts:317

A convenience method for setting several fields and values at once.

Parameters

Parameter	Type	Description
data	Partial<SchemaDataType<S>>	The values to set.

Returns

void

---

toJS()

toJS(local?): ReadonlyJSONObject

Defined in: cfds/base/item.ts:631

Serializes this item to a JSON-compatible object.

Parameters

Parameter	Type	Default value	Description
local	boolean	false	If true, serialization includes local data. If false, local data is skipped.

Returns

ReadonlyJSONObject

A JSON object representing this item's serialized state.

---

unlock()

unlock(): void

Defined in: cfds/base/item.ts:708

Unlocks this item, allowing modifications.

When an item is unlocked, its data can be modified. This reverses the effect of calling lock().

WARNING: Unlocking items is dangerous and should never be needed in normal usage. Unlocking can corrupt historical versions and lead to serious data inconsistencies.

Returns

void

---

upgradeSchema()

upgradeSchema(newSchema?): boolean

Defined in: cfds/base/item.ts:507

Upgrades this item's data to a newer schema version.

This method takes an optional target schema and attempts to upgrade the item's data to match that schema. If no target schema is provided, it will upgrade to the latest schema version available for this namespace.

The upgrade process is performed by applying the upgrade functions defined in each schema version between the current and target versions. The upgrade will fail if any intermediate schema versions are missing.

Parameters

Parameter	Type	Description
newSchema?	Schema	Optional target schema to upgrade to

Returns

boolean

true if the data was upgraded, false if no upgrade was needed

Throws

If this item is locked or if the upgrade fails

---

validate()

validate(): [boolean, string]

Defined in: cfds/base/item.ts:175

Validates the item's data against its schema.

This method checks if the item's data conforms to the schema's requirements and returns the validation result.

Returns

[boolean, string]

A tuple containing:

• valid: boolean indicating if the data is valid
• error: error message if validation failed, empty string otherwise

---

fromJS()

static fromJS<S>(obj): Item<S>

Defined in: cfds/base/item.ts:643

Deserializes a JSON-compatible object into an Item instance.

Type Parameters

Type Parameter
S extends Schema

Parameters

Parameter	Type	Description
obj	ReadonlyJSONObject	The JSON object to deserialize

Returns

Item<S>

An Item instance representing the deserialized data

---

nullItem()

static nullItem<S>(registry): Item<S>

Defined in: cfds/base/item.ts:129

Type Parameters

Type Parameter	Default type
S extends Schema	Schema

Parameters

Parameter	Type
registry	DataRegistry

Returns

Item<S>

An item with the null schema.