tinylib.data
Tinylib keeps the user's data on the device as keys with JSON values, and syncs it to the user's other devices. Every call is synchronous and works offline. Data explains syncing and the keys only your rules write.
JavaScript
const best = tinylib.data.get('best') ?? 0
Parameters
- keyK
- The key to read.
Returns
- DataValue<K> | undefined
- The value, or
undefinedwhen there's none.
Throws
- TypeError
- When
keyis empty or isn't a string.
tinylib.data.set<K extends DataKey>(key: K, value: DataValue<K>, options?: { audience?: Audience }): void
Saves
value under key on this device and syncs it to the user's other devices. It doesn't call this client's onChange unless the save later fails, and then onChange receives the error.JavaScript
tinylib.data.set('best', 42, { audience: 'friends' })
Parameters
- keyK
- The key to save under.
- valueDataValue<K>
- Any value JSON can represent.
- options{ audience?: Audience }optional
- options.audienceAudienceoptional
- Who can read the value:
'me', the user alone, or'friends', the user and their friends who use your app, throughtinylib.friends.data. Without it, the value keeps the audience it had, or'me'for a new key.'friends'needs"friends"in your app'suses; without it, the save fails withrefused.
Throws
- TypeError
- When
keyis empty, isn't a string, is over 128 bytes, or is declared inrulesKeys. - When
valuecan't be represented as JSON. - When
audienceisn't'me'or'friends'.
- When
- limit
- When the user's data your client writes would grow past 1 MB.
Removes the value under
key and syncs the removal. Does nothing when there's no value.JavaScript
tinylib.data.remove('draft')
Returns the
[key, value] pairs whose keys start with prefix.JavaScript
const entries = tinylib.data.entries('entry/')
Parameters
- prefixstringoptional
- The start of the keys to return. Without it, returns every pair.
Returns
- [DataKey, unknown][]
- The pairs, sorted by key.
Throws
- TypeError
- When
prefixisn't a string.
Returns the keys that start with
prefix.JavaScript
const drafts = tinylib.data.keys('draft/')
Parameters
- prefixstringoptional
- The start of the keys to return. Without it, returns every key.
Returns
- DataKey[]
- The keys, sorted.
Throws
- TypeError
- When
prefixisn't a string.
tinylib.data.values(prefix?: string): unknown[]
Returns the values under the keys that start with
prefix.JavaScript
const texts = tinylib.data.values('entry/')
Parameters
- prefixstringoptional
- The start of the keys whose values to return. Without it, returns every value.
Returns
- unknown[]
- The values, sorted by key.
Throws
- TypeError
- When
prefixisn't a string.
tinylib.data.onChange(fn: (keys: string[], error?: { code: ErrorCode; message: string }) => void): () => void
Calls
fn after the user's other tabs or devices, or your rules, change values, and after a save this client made fails. A failed key goes back to the value on Tinylib's servers, unless a later save to it is still waiting to be sent. Keep what the user typed on screen if they should try again.A failed save's error.code is one of:
limit: the user's data, with writes from their other devices, would pass 1 MB, or this device is out of space.refused: the value was saved withaudience: 'friends', and your app'suseslacks"friends".failed: this device or Tinylib's servers couldn't save it.
JavaScript
tinylib.data.onChange((keys, error) => {
if (error) toast(error.message)
drawEntries()
})
Parameters
- fn(keys: string[], error?: { code: ErrorCode; message: string }) => void
- Called with
keys, the keys that changed, and, when a save failed,error, with thecodeandmessageof aTinylibError.
Returns
- () => void
- A function that stops the calls.
Throws
- TypeError
- When
fnisn't a function.