tinylib

onChange(fn): () => void;

Calls fn after the name or the notifications switch changes. Returns a function that stops it.

Parameters

Returns

() => void

Example

tinylib.persona.onChange(() => (title.textContent = tinylib.persona.name))

edit(setting): Promise<boolean>;

Opens Tinylib's card for this app's notifications switch, where the person changes it. Resolves with the switch's value when the card closes, unchanged if the person backed out. Rejects with offline. Throws a TypeError for any setting but 'notifications'.

Parameters

Returns

Promise<boolean>

Example

button.onclick = async () => (button.hidden = await tinylib.persona.edit('notifications'))

onChange(fn): () => void;

Calls fn after online changes. Returns a function that stops it.

Parameters

Returns

() => void

Example

tinylib.connection.onChange(() => (offline.hidden = tinylib.connection.online))

go(address, options?): void;

Moves to address without loading a page, as a link to it does. replace replaces the current place in the history instead of adding one. Throws a TypeError for an address that starts with /.

Parameters

Returns

void

Example

tinylib.places.go(`game/${id}`)

onChange(fn): () => void;

Calls fn after any move: the page's own, back and forward, or Tinylib landing the person on an address. Returns a function that stops it.

Parameters

Returns

() => void

Example

tinylib.places.onChange(route)

share(address, text?): Promise<void>;

Opens Tinylib's share sheet with a link to address in the app, and text with it. Resolves when the sheet closes.

Parameters

Returns

Promise<void>

Example

await tinylib.places.share(`list/${id}`, 'Our shopping list')

get<K>(key): DataValue<K> | undefined;

The value under key, or undefined.

Type Parameters

Parameters

Returns

DataValue<K> | undefined

set<K>(
   key, 
   value, 
   options?
): void;

Saves value under key on the device at once, and syncs it after. audience: 'friends' shows it to the persona's friends who have the app; 'me', the default, keeps it to the persona. Throws a TypeError for a value JSON can't hold or a key tinylib.json declares for the rules, and a TinylibError with limit past the data cap. A save that fails after reaches onChange with its error.

Type Parameters

Parameters

Returns

void

Example

tinylib.data.set('best', 42, { audience: 'friends' })

remove(key): void;

Removes the value under key. Throws a TypeError for a key tinylib.json declares for the rules.

Parameters

Returns

void

entries(prefix?): [string, unknown][];

[key, value] for every key that starts with prefix, sorted by key. Without prefix, every key.

Parameters

Returns

[string, unknown][]

Example

const entries = tinylib.data.entries('entry/')

keys(prefix?): string[];

The keys that start with prefix, in entries' order.

Parameters

Returns

string[]

values(prefix?): unknown[];

The values under the keys that start with prefix, in entries' order.

Parameters

Returns

unknown[]

onChange(fn): () => void;

Calls fn(keys) after values change from another device or the rules, and fn(keys, error) after a save this page made fails, with those keys back to what the store holds. Returns a function that stops it.

Parameters

Returns

() => void

Example

tinylib.data.onChange((keys, error) => (error ? toast(error.message) : draw()))

list(): Promise<object[]>;

Resolves with the persona's friends who have the app. Rejects with offline.

Returns

Promise<object[]>

Example

const friends = await tinylib.friends.list()

sendApp(): Promise<void>;

Opens Tinylib's Send sheet, where the person sends the app to friends. Resolves when it closes, without saying who was picked. Rejects with offline or limit.

Returns

Promise<void>

A friend's value.

Properties

A read-only store that lives on Tinylib's servers, read with tinylib.data's verbs, each async.

Type Parameters

get(key): Promise<V | undefined>;

keys(prefix?): Promise<string[]>;

values(prefix?): Promise<V[]>;

entries(prefix?): Promise<[string, V][]>;

create(kind, options?): Promise<{
  id: string;
}>;

Creates a room of kind, the name of a rules.js export, with the persona as its first member and options passed to the kind's create. Resolves with the room's id. Rejects with refused when the rules refuse it, limit, or offline. Throws a TypeError for options JSON can't hold.

Parameters

Returns

Promise<{ id: string; }>

Example

const { id } = await tinylib.rooms.create('game')

open<K>(id): Promise<OpenRoom<RoomMessage<K>>>;

Opens the room on this page and connects the persona to it. Resolves with the open room. Rejects with not_member, ended, offline or failed.

Type Parameters

Parameters

Returns

Promise<OpenRoom<RoomMessage<K>>>

Example

const room = await tinylib.rooms.open(id)

join(code): Promise<{
  id: string;
}>;

Joins the room a short code names. Resolves with its id. Rejects with not_found for a code no room of the app has, refused when the rules refuse the join, limit after too many codes, or offline.

Parameters

Returns

Promise<{ id: string; }>

Example

const { id } = await tinylib.rooms.join('K7QD')

invite(id, personaId?): Promise<void>;

Invites personaId, a friend or someone from the persona's rooms. Without personaId, opens Tinylib's invite sheet for the room, which also shares its link. Resolves once sent, or when the sheet closes. Inviting someone who blocked the persona resolves as if sent. Rejects with refused when the rules refuse it, not_member, ended, limit, or offline.

Parameters

Returns

Promise<void>

Example

await tinylib.rooms.invite(id, friend.id)

getLink(id, options?): Promise<{
  url: string;
  code: string | null;
}>;

Resolves with the room's one link, made if it has none, and its short code, or null. code: true adds a short code to the same link if it has none. Rejects with refused when the rules refuse it, not_member, ended, or offline.

Parameters

Returns

Promise<{ url: string; code: string | null; }>

Example

const { url, code } = await tinylib.rooms.getLink(id, { code: true })

deleteLink(id): Promise<void>;

Stops the room's link and its short code for good; getLink makes a new one. Rejects with refused when the rules refuse it, not_member, ended, or offline.

Parameters

Returns

Promise<void>

leave(id): Promise<void>;

Takes the persona out of the room, which stays in list() marked left. Rejects with offline.

Parameters

Returns

Promise<void>

list(): Promise<RoomItem[]>;

Resolves with the persona's rooms in this app: current ones, then past ones.

Returns

Promise<RoomItem[]>

Example

const waiting = (await tinylib.rooms.list()).filter((room) => room.waiting)

onChange(fn): () => void;

Calls fn with the list after it changes. Returns a function that stops it.

Parameters

Returns

() => void

data(roomId): RemoteStore<unknown>;

The data the rules keep with the room, for its members during the room and after. Someone who left reads it as it was when they left. Each call rejects with not_member for a room the persona was never in, or offline.

Parameters

Returns

RemoteStore<unknown>

Example

const moves = await tinylib.rooms.data(id).values('move/')

A room the page has open, from tinylib.rooms.open.

Type Parameters

Properties

close(): void;

send(action, data?): Promise<void>;

await room.send('move', { square: 4 })

onMessage(fn): () => void;

room.onMessage(({ view }) => draw(view))

onChange(fn): () => void;

type RoomListItem = RoomItem;

One of the persona's rooms, as rooms.list() gives it.

Properties

list(): Promise<Invitation[]>;

Resolves with every invitation, without taking any from Tinylib's card.

Returns

Promise<Invitation[]>

handle(pick, fn): () => void;

Takes the invitations pick returns true for: fn gets them now and after every change, and Tinylib shows its own card only for those no handler takes. An invitation two handlers pick goes to both. Returns a function that stops it. Throws a TypeError unless both are functions.

Parameters

Returns

() => void

Example

tinylib.invitations.handle((invitation) => invitation.from.id === opponent.id, showRematch)

An invitation to a room.

Properties

accept(): Promise<{
  id: string;
}>;

dismiss(): Promise<void>;

set(name, options): Promise<void>;

Sets the reminder name, replacing one set under that name before. With the app's notifications switch off, Tinylib asks the person first. Rejects with notifications_off if they leave it off, and with refused or limit for one Tinylib can't set. Throws a TypeError for options that don't have a title and exactly one of at and repeat.

Parameters

Returns

Promise<void>

Example

await tinylib.reminders.set('evening', { title: 'Journal', text: 'How was today?', repeat: tinylib.reminders.daily('18:00') })

daily(time): Repeat;

Every day at time, 'HH:MM' where the reminder is set. Throws a TypeError for another time.

Parameters

Returns

Repeat

weekly(days, time): Repeat;

On each of days at time. Throws a TypeError for no days, a day twice, or a time that isn't 'HH:MM'.

Parameters

Returns

Repeat

Example

tinylib.reminders.weekly(['mon', 'tue', 'wed', 'thu', 'fri'], '09:30')

monthly(day, time): Repeat;

On day day, 1 to 31, of every month at time. Throws a TypeError for another day or time.

Parameters

Returns

Repeat

list(): Promise<ReminderItem[]>;

Resolves with the persona's reminders in this app.

Returns

Promise<ReminderItem[]>

cancel(name): Promise<void>;

Cancels the reminder name.

Parameters

Returns

Promise<void>

Properties

type Reminder = ReminderItem;

One of the persona's reminders, as reminders.list() gives it.

Properties

type Repeat = 
  | {
  every: "day";
  time: string;
}
  | {
  every: "week";
  days: Day[];
  time: string;
}
  | {
  every: "month";
  day: number;
  time: string;
};

type Day = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";

Types an app's data and rooms, in one declaration in the app:

declare module 'tinylib-sdk' {
  interface Register {
    data: { score: number; [key: `entry/${string}`]: string }
    rooms: { game: { view: GameView } }   // what each kind's rules send
  }
}

type DataKey = keyof DataShape & string;

A key of Register's data, or any string without one.

type DataValue<K> = K extends keyof DataShape ? DataShape[K] : unknown;

The value Register's data gives a key, or unknown.

Type Parameters

type RoomKind = keyof RoomShape & string;

A kind of room Register's rooms names, or any string without one.

type RoomMessage<K> = K extends keyof RoomShape ? RoomShape[K] : unknown;

The messages Register's rooms gives a kind, or unknown.

Type Parameters