Item
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.
Implements: ReadonlyItem, Encodable
Constructor
new Item(config: ItemConfig<S> | ConstructorDecoderConfig<EncodedItem>, registry: DataRegistry<>)
Creates a new Item instance.
Methods
assertValidData()
assertValidData(): void
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.
clone()
clone(): Item<S>
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.
cloneData()
cloneData(onlyFields: keyof S['fields'][]): Readwrite<SchemaDataType<S>>
Creates a deep copy of the item's data.
copyFrom()
copyFrom(doc: Item<S> | ReadonlyItem<S>): void
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.
dataUnsafe()
dataUnsafe(): SchemaDataType<S>
WARNING: You probably shouldn't use this. Used internally as an optimization to avoid unnecessary copying.
delete()
delete(key: T): boolean
Deletes a given field from this item.
deserialize()
deserialize(decoder: Decoder<>): void
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.
diff()
diff(other: Item<S>, byCharacter: boolean): DataChanges<>
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.
diffKeys()
diffKeys(other: Item<S>, local: boolean): string[]
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.
get()
get(key: T): SchemaDataType<S>[T]
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.
has()
has(key: T): boolean
Returns whether the given field is present on the current item or not.
isEqual()
isEqual(other: Item<S>): boolean
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.
lock()
lock(): void
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.
needsSchemaUpgrade()
needsSchemaUpgrade(): boolean
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.
normalize()
normalize(): void
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.
patch()
patch(changes: DataChanges<>): void
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.
serialize()
serialize(encoder: Encoder<string, CoreValue>, options: { local: boolean }): void
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.
set()
set(key: T, value: SchemaDataType<S>[T]): void
Sets the value for the given field.
setMulti()
setMulti(data: Partial<SchemaDataType<S>>): void
A convenience method for setting several fields and values at once.
toJS()
toJS(local: boolean): ReadonlyJSONObject
Serializes this item to a JSON-compatible object.
unlock()
unlock(): void
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.
upgradeSchema()
upgradeSchema(newSchema: Schema): boolean
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.
validate()
validate(): [boolean, string]
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.
fromJS()
fromJS(obj: ReadonlyJSONObject): Item<S>
Deserializes a JSON-compatible object into an Item instance.
nullItem()
nullItem(registry: DataRegistry<>): Item<S>