tinylib
tinylib is a global in every page of your app, ready with the user's data before your own scripts run. It exists
only inside Tinylib and at the address npx tinylib-sdk dev prints. The tinylib-sdk package declares its type, and
Register adds your app's data and room types to it.
interface User
The person using your app.
Properties
- idstringread-only
- The user's id in your app. The same person has a different id in every app.
- namestringread-only
- The user's name. It can change and isn't unique, so tell users apart by
id. - settings{ readonly notifications: boolean; readonly reminders: boolean }read-only
- The user's switches for your app in Tinylib, which aren't the phone's permission to show notifications.
notificationsis the Rooms switch, for what your rules send withctx.notify, andremindersis the Reminders switch. Both are true by default. - JavaScriptdocument.querySelector('#remind-me').hidden = !tinylib.user.settings.reminders
- guestbooleanread-only
- True when the user is a guest: someone without a Tinylib account, known only on the device they use. A guest has data, reminders and every room call, with the same id in every room of your app. A guest gets no notifications or invitations, and can't invite anyone, add friends, or report: Guests lists the calls that reject with
refusedfor one.
Methods
- onChange(fn)
- Calls
fnafternameorsettingschanges. - manageSettings()
- Opens Tinylib's sheet where the user turns your app's switches on and off.
tinylib.user.onChange(fn: () => void): () => void
Calls
fn after name or settings changes.JavaScript
tinylib.user.onChange(() => {
document.querySelector('#name').textContent = tinylib.user.name
})
Parameters
- fn() => void
- Called with no arguments.
Returns
- () => void
- A function that stops the calls.
Throws
- TypeError
- When
fnisn't a function.
tinylib.user.manageSettings(): Promise<{ notifications: boolean; reminders: boolean }>
JavaScript
const turnOn = document.querySelector('#turn-on-reminders')
turnOn.addEventListener('click', async () => {
try {
const settings = await tinylib.user.manageSettings()
turnOn.hidden = settings.reminders
} catch (error) {
toast(error.message)
}
})
Returns
- Promise<{ notifications: boolean; reminders: boolean }>
- The user's
settingsonce the sheet closes.
Rejects with
- offline
interface Connection
Whether the device can reach Tinylib's servers now. Errors and offline lists what works without a connection. While a room your app has open can't reach Tinylib, Tinylib shows so over your app, so your app doesn't show its own.
Properties
- onlinebooleanread-only
- True while the device can reach Tinylib's servers.
Methods
- onChange(fn)
- Calls
fnafteronlinechanges.
tinylib.connection.onChange(fn: () => void): () => void
Calls
fn after online changes.JavaScript
tinylib.connection.onChange(() => {
document.querySelector('#new-game').disabled = !tinylib.connection.online
})
Parameters
- fn() => void
- Called with no arguments.
Returns
- () => void
- A function that stops the calls.
Throws
- TypeError
- When
fnisn't a function.
tinylib.now(): number
Returns the current time on Tinylib's clock, in milliseconds since the Unix epoch. Tinylib's servers and
ctx.now in the rules use the same clock. Date.now() uses the device's clock, which can be wrong.JavaScript
await tinylib.reminders.set('break', { title: 'Back to work', at: tinylib.now() + 15 * 60_000 })
Returns
- number
- The time in milliseconds.
tinylib.block(userId: string): Promise<boolean>
Opens Tinylib's sheet for the user to confirm blocking
userId. Let users block and report says when your app must offer it.A block keeps the two from reaching each other again, in every app: neither can invite the other, and neither can join a room the other is in. Rooms they're already in go on unchanged. Works for a guest.
JavaScript
if (await tinylib.block(player.id)) tinylib.places.go('')
Parameters
- userIdstring
- The id of someone the user has met in your app: someone who has been in a room of your app with them, who invited them to one or was invited by them, or a friend, when your app's
useshas"friends".
Returns
- Promise<boolean>
- True if the user blocked them, or false if they canceled.
Rejects with
- not_found
- When
userIdisn't someone the user has met in your app. - refused
- When
userIdis the user's own. - offline
tinylib.report(userId: string): Promise<boolean>
Opens Tinylib's sheet for the user to report
userId to Tinylib.JavaScript
await tinylib.report(player.id)
Parameters
- userIdstring
- The id of someone the user has met in your app, such as a member of one of their rooms.
Returns
- Promise<boolean>
- True if the user sent a report, or false if they canceled.
Rejects with
- not_found
- When
userIdisn't someone the user has met in your app. - refused
- When
userIdis the user's own, or the user is a guest. - offline
interface TinylibError extends Error
The error a failed call rejects with, or a synchronous call throws: an
Error whose name is 'TinylibError', with a code and a message you can show the user. There's no class to test with instanceof, so check code.Extends
Error.Besides the codes each call's entry lists, any call that returns a promise can reject with failed when Tinylib's
servers or the device fail.
A mistake in your own code, such as an argument of the wrong type, is a plain TypeError instead, with no code.
JavaScript
try {
await room.act('move', 4)
} catch (error) {
if (error.code !== 'refused') throw error
toast(error.message)
}
type ErrorCode =
| 'refused'
| 'failed'
| 'offline'
| 'limit'
| 'not_member'
| 'ended'
| 'not_found'
The
code of a TinylibError.