Persistable
Persistable manages unstructured data storage associated with a scene element.
static use(name: string): Persistable
Returns a Persistable instance connected to a specific object in the scene for persistence operations.
Parameters:
name: The name of the object to associate with this persistable store.
Example:
const store = Persistable.use('player');
inspect(): Promise<any>
Returns the current state of all persisted data.
Returns:
- A promise that resolves to the object's data, or null on failure.
Example:
const data = await store.inspect();
console.log(data);
get(key: string, defaultValue?: any): Promise<any>
Fetches a value from the persistent storage by its key.
Parameters:
key: The name of the property to retrieve.defaultValue(optional): The default value if the property is not found or an error occurs.
Example:
const score = await store.get('score', 0);
set(key: string, value: any): Promise<any>
Stores a value under the given key, replacing any existing value.
Parameters:
key: The name of the property to set.value: The value to store.
Returns:
- A promise that resolves to the updated object data, or null on failure.
Example:
await store.set('score', 100);
delete(key: string): Promise<any>
Deletes a specific key-value pair from the persistent storage.
Parameters:
key: The name of the property to remove.
Example:
await store.delete('score');
clear(): Promise<boolean>
Removes all stored data associated with the connected object, resetting it to an empty object.
Returns:
- A promise that resolves to true on success, false on failure.
Example:
await store.clear();
inc(key: string, value: number): Promise<any>
Increments a numeric stored value by a specified amount.
Parameters:
key: The key of a numeric value to increment.value: The amount to add.
Example:
await store.inc('score', 10);
mult(key: string, value: number): Promise<any>
Multiplies a numeric stored value by the given factor.
Parameters:
key: The key of a numeric value to multiply.value: The multiplier.
Example:
await store.mult('score', 2);
arrPush(key: string, item: any): Promise<any>
Pushes an item to the end of an array in the persistent storage.
Parameters:
key: The name of the array property.item: The item to append to the array.
Example:
await store.arrPush('items', 'sword');
arrInsertAt(key: string, index: number, item: any): Promise<any>
Inserts an item at a specific position in an array stored persistently.
Parameters:
key: The name of the array property.index: The position at which to insert the item.item: The item to insert.
Example:
await store.arrInsertAt('items', 1, 'shield');
arrPull(key: string, value: any): Promise<any>
Removes all occurrences of the value from the array in persistent storage.
Parameters:
key: The name of the array property.value: The value to remove from the array.
Example:
await store.arrPull('items', 'sword');
arrPullAt(key: string, index: number): Promise<any>
Removes an item at a specific index from an array stored persistently.
Parameters:
key: The name of the array property.index: The position of the element to remove.
Example:
await store.arrPullAt('items', 0);
lock(timeoutInMilliseconds: number): Promise<boolean>
Locks the persistable object to prevent other operations for a given timeout duration.
Parameters:
timeoutInMilliseconds: Duration in milliseconds to maintain the lock.
Example:
await store.lock(5000);
unlock(): Promise<boolean>
Manually unlocks the persistable object, enabling further operations.
Example:
await store.unlock();
ttl(timestampInMilliseconds: number): Promise<boolean>
Sets a time-to-live (TTL) for the stored data.
Parameters:
timestampInMilliseconds: A Unix timestamp (milliseconds) after which the data should expire.
Example:
await store.ttl(Date.now() + 3600000); // expire in 1 hour
drop(): Promise<boolean>
Completely removes the persistable object from the storage, all data will be lost irreversibly.
Example:
await store.drop();