@arcadible/function-sdk 0.4.0-next.0 → 0.5.0-next.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -4
- package/dist/function/players.d.ts +9 -2
- package/dist/shared/players.d.ts +7 -2
- package/dist/shared/players.js +30 -13
- package/dist/shared/values.d.ts +5 -4
- package/dist/shared/values.js +9 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -45,12 +45,15 @@ export default {
|
|
|
45
45
|
const me = players.primary(request);
|
|
46
46
|
// { id }, or null for a guest
|
|
47
47
|
|
|
48
|
-
const [sam] = await players.read([me
|
|
48
|
+
const [sam] = await players.read([me]);
|
|
49
49
|
// { id, name }, or null for a player who's gone, or a guest
|
|
50
50
|
```
|
|
51
51
|
|
|
52
52
|
- **`players.primary(request)`** is who sent the request, by their id in your game, the same one your game's `players.primary` has. Arcadible set it after checking the request's ticket, so there's nothing to check.
|
|
53
|
-
-
|
|
53
|
+
- **A player is an object,** in every call: `players.read` takes up to 50, each anything with a player's `id`, such as `players.primary(request)` or a `{ id }` your function kept in a value. An id alone isn't taken. A missing player, `null`, as `players.primary(request)` is for a guest, comes back `null`.
|
|
54
|
+
- **A guest is `null` here,** though your game's own `players.primary` has a guest, with an id and `guest: true`. That id is the device's, kept in the browser, and proves nothing, so Arcadible never passes it to your function.
|
|
55
|
+
- **A player may gain properties.** Arcadible may add to a player later, and every call that takes one reads only its `id`. Don't depend on a player's exact shape, such as by comparing whole objects or expecting the same properties back: compare and keep the `id`.
|
|
56
|
+
- **A name** is the player's own, as they've set it on Arcadible; show it as text.
|
|
54
57
|
|
|
55
58
|
## Values
|
|
56
59
|
|
|
@@ -73,7 +76,7 @@ await values.remove([{ scope: "server", key: `seats/${code}` }]);
|
|
|
73
76
|
const { entries, next: after } = await values.list("game", { prefix: "match/" });
|
|
74
77
|
```
|
|
75
78
|
|
|
76
|
-
- **`read`, `write`, and `remove`** take items, each naming its scope and key, up to 32, as one request across scopes: a read is one snapshot, and a write or a remove is all made or none.
|
|
79
|
+
- **`read`, `write`, and `remove`** take items, each naming its scope and key, up to 32, as one request across scopes: a read is one snapshot, and a write or a remove is all made or none. With no items, nothing is asked.
|
|
77
80
|
- **A `revision`** makes a write, or a remove, only if the value is still that one (`0`: only if there's none); otherwise the whole call rejects with `conflict`, and your function reads again.
|
|
78
81
|
- **`since`** on a read item, a revision you have: if the value is still at it, it comes back `{ scope, key, revision, unchanged: true }`, without its value.
|
|
79
82
|
- **`list`** gives a scope's keys, with their sizes and times and no values, 50 at a time.
|
|
@@ -82,7 +85,7 @@ Every call rejects with an `ArcadibleError`, whose `code` says what to do: `inva
|
|
|
82
85
|
|
|
83
86
|
## Development
|
|
84
87
|
|
|
85
|
-
`arc serve` runs your function beside your game, as Arcadible would, and the Function SDK's calls go to `arc serve`'s own values and players: nothing reaches Arcadible.
|
|
88
|
+
`arc serve` runs your function beside your game, as Arcadible would, and the Function SDK's calls go to `arc serve`'s own values and players: nothing reaches Arcadible. It differs from Arcadible in a few ways: `players.read` knows only the players who've played in this run, and the limits on how often your function is called, and calls Arcadible, aren't enforced.
|
|
86
89
|
|
|
87
90
|
## License
|
|
88
91
|
|
|
@@ -16,9 +16,16 @@ export interface Players {
|
|
|
16
16
|
primary(request: Request): PrimaryPlayer | null;
|
|
17
17
|
/**
|
|
18
18
|
* Each player, in the order given: their id and name, or `null` for one
|
|
19
|
-
* who's gone, never was, or is a guest. Up to 50
|
|
19
|
+
* who's gone, never was, or is a guest. Up to 50 players, each anything
|
|
20
|
+
* with a player's `id`: `primary(request)`, or a `{ id }` the function
|
|
21
|
+
* kept. An id alone isn't taken. A missing player, `null`, as
|
|
22
|
+
* `primary(request)` is for a guest, is `null`, and isn't asked for.
|
|
23
|
+
* Rejects with `invalid` for what isn't a list of players, and
|
|
24
|
+
* `too_many` past 50.
|
|
20
25
|
*/
|
|
21
|
-
read(
|
|
26
|
+
read(players: readonly ({
|
|
27
|
+
readonly id: string;
|
|
28
|
+
} | null | undefined)[]): Promise<(Player | null)[]>;
|
|
22
29
|
}
|
|
23
30
|
/** The header Arcadible sets on a request to a function: the player's id, or empty for a guest. */
|
|
24
31
|
export declare const PLAYER = "x-arcadible-player";
|
package/dist/shared/players.d.ts
CHANGED
|
@@ -13,6 +13,11 @@ export declare function isObject(value: unknown): value is Record<string, unknow
|
|
|
13
13
|
export declare function unreadable(): ArcadibleError;
|
|
14
14
|
/**
|
|
15
15
|
* `players.read`: each player, in the order given, their id and name, or
|
|
16
|
-
* `null` for one who's gone, never was, or is a guest. Up to 50
|
|
16
|
+
* `null` for one who's gone, never was, or is a guest. Up to 50 players,
|
|
17
|
+
* each anything with a player's `id`; an id alone isn't taken. A missing
|
|
18
|
+
* player, `null` or `undefined`, as a guest's ticket has, is `null`, and
|
|
19
|
+
* isn't asked for.
|
|
17
20
|
*/
|
|
18
|
-
export declare function readPlayers(api: () => Api): (
|
|
21
|
+
export declare function readPlayers(api: () => Api): (players: readonly ({
|
|
22
|
+
readonly id: string;
|
|
23
|
+
} | null | undefined)[]) => Promise<(Player | null)[]>;
|
package/dist/shared/players.js
CHANGED
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
// Players: what a game's server, or its function, may ask Arcadible about
|
|
2
|
-
// the players it knows
|
|
3
|
-
//
|
|
2
|
+
// the players it knows: their names. A player is an object, in and out: a
|
|
3
|
+
// call takes anything with a player's `id` (a ticket's `player`, the
|
|
4
|
+
// function's `primary`, a `read`'s or a `deleted`'s entry, a stored
|
|
5
|
+
// `{ id }`), never an id alone, and answers with objects. Each package adds
|
|
6
|
+
// its own (the server's `deleted`, the function's `primary`).
|
|
4
7
|
import { ArcadibleError, Codes } from "./error.js";
|
|
5
|
-
// The most
|
|
8
|
+
// The most players one read takes.
|
|
6
9
|
export const MAX_PLAYERS = 50;
|
|
7
10
|
export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
|
|
8
11
|
// [function]
|
|
@@ -17,19 +20,33 @@ export function unreadable() {
|
|
|
17
20
|
// [function]
|
|
18
21
|
/**
|
|
19
22
|
* `players.read`: each player, in the order given, their id and name, or
|
|
20
|
-
* `null` for one who's gone, never was, or is a guest. Up to 50
|
|
23
|
+
* `null` for one who's gone, never was, or is a guest. Up to 50 players,
|
|
24
|
+
* each anything with a player's `id`; an id alone isn't taken. A missing
|
|
25
|
+
* player, `null` or `undefined`, as a guest's ticket has, is `null`, and
|
|
26
|
+
* isn't asked for.
|
|
21
27
|
*/
|
|
22
28
|
export function readPlayers(api) {
|
|
23
|
-
return async (
|
|
24
|
-
if (!Array.isArray(
|
|
25
|
-
|
|
26
|
-
!ids.every((id) => typeof id === "string" && UUID.test(id))) {
|
|
27
|
-
throw new TypeError(`players.read takes up to ${MAX_PLAYERS} ids, each a player's id in the game.`);
|
|
29
|
+
return async (players) => {
|
|
30
|
+
if (!Array.isArray(players)) {
|
|
31
|
+
throw new ArcadibleError(Codes.Invalid, "players.read takes a list of players.");
|
|
28
32
|
}
|
|
29
|
-
if (
|
|
30
|
-
|
|
33
|
+
if (players.length > MAX_PLAYERS) {
|
|
34
|
+
throw new ArcadibleError(Codes.TooMany, `players.read takes up to ${MAX_PLAYERS} players at once, not ${players.length}.`);
|
|
35
|
+
}
|
|
36
|
+
const ids = players.map((player, index) => {
|
|
37
|
+
if (player === null || player === undefined)
|
|
38
|
+
return null;
|
|
39
|
+
if (!isObject(player) ||
|
|
40
|
+
typeof player["id"] !== "string" ||
|
|
41
|
+
!UUID.test(player["id"])) {
|
|
42
|
+
throw new ArcadibleError(Codes.Invalid, `players.read takes players, each with their id in the game, as { id }: a ticket's player, players.primary(request), or one a server kept. Entry ${index} isn't one; an id alone isn't a player.`);
|
|
43
|
+
}
|
|
44
|
+
return player["id"];
|
|
45
|
+
});
|
|
31
46
|
// each id once, then every place it was asked for
|
|
32
|
-
const asked = [...new Set(ids)];
|
|
47
|
+
const asked = [...new Set(ids.filter((id) => id !== null))];
|
|
48
|
+
if (asked.length === 0)
|
|
49
|
+
return ids.map(() => null);
|
|
33
50
|
const data = await api().request(`/players/${asked.join(",")}`);
|
|
34
51
|
if (!Array.isArray(data) || data.length !== asked.length) {
|
|
35
52
|
throw unreadable();
|
|
@@ -47,6 +64,6 @@ export function readPlayers(api) {
|
|
|
47
64
|
name: typeof name === "string" && name !== "" ? name : null,
|
|
48
65
|
});
|
|
49
66
|
}
|
|
50
|
-
return ids.map((id) => found.get(id) ?? null);
|
|
67
|
+
return ids.map((id) => (id === null ? null : (found.get(id) ?? null)));
|
|
51
68
|
};
|
|
52
69
|
}
|
package/dist/shared/values.d.ts
CHANGED
|
@@ -2,13 +2,13 @@ import type { Api } from "./api.js";
|
|
|
2
2
|
/**
|
|
3
3
|
* Whose the values are: `"developer"`, what the developer publishes, to
|
|
4
4
|
* read; `"game"`, what every player reads and only the game's server writes;
|
|
5
|
-
* `"server"`, the server's alone; or a player
|
|
6
|
-
*
|
|
5
|
+
* `"server"`, the server's alone; or a player: anything with their `id` in
|
|
6
|
+
* the game, as `players.primary(request)` or a ticket's `player` is.
|
|
7
7
|
*/
|
|
8
8
|
export type Scope = "developer" | WritableScope;
|
|
9
9
|
/** A scope a server writes: every one but the developer's. */
|
|
10
10
|
export type WritableScope = "game" | "server" | {
|
|
11
|
-
id: string;
|
|
11
|
+
readonly id: string;
|
|
12
12
|
};
|
|
13
13
|
/** A value, with the revision a write may name to replace it. */
|
|
14
14
|
export type Value = {
|
|
@@ -74,7 +74,8 @@ export interface Values {
|
|
|
74
74
|
/**
|
|
75
75
|
* The values of the items, in their order, in one call and one snapshot,
|
|
76
76
|
* across scopes: each with its revision, `Unchanged` for an item whose
|
|
77
|
-
* `since` is still its revision, or `null` for a key with none. Up to
|
|
77
|
+
* `since` is still its revision, or `null` for a key with none. Up to
|
|
78
|
+
* 32; with none, `[]`, and nothing is asked.
|
|
78
79
|
*/
|
|
79
80
|
read(items: readonly ReadItem[]): Promise<(Value | Unchanged | null)[]>;
|
|
80
81
|
/**
|
package/dist/shared/values.js
CHANGED
|
@@ -36,14 +36,13 @@ function scopeOf(scope) {
|
|
|
36
36
|
throw invalid('A scope is "developer", "game", "server", or a player, as { id }.');
|
|
37
37
|
}
|
|
38
38
|
// [function]
|
|
39
|
-
// a call's items:
|
|
40
|
-
//
|
|
39
|
+
// a call's items: no more than a call takes, each an object with a scope
|
|
40
|
+
// and a key, none named twice in a scope. None at all is a call with
|
|
41
|
+
// nothing to ask, answered without a request.
|
|
41
42
|
function itemsOf(items) {
|
|
42
43
|
if (!Array.isArray(items) || !items.every(isObject)) {
|
|
43
44
|
throw invalid("A call takes a list of items, each { scope, key }.");
|
|
44
45
|
}
|
|
45
|
-
if (items.length === 0)
|
|
46
|
-
throw invalid("A call names at least one item.");
|
|
47
46
|
if (items.length > MAX_KEYS) {
|
|
48
47
|
throw new ArcadibleError(Codes.TooMany, `A call names up to ${MAX_KEYS} items.`);
|
|
49
48
|
}
|
|
@@ -114,6 +113,8 @@ export function createValues(api) {
|
|
|
114
113
|
key: item.key,
|
|
115
114
|
...(item.since === undefined ? {} : { since: revisionOf(item.since) }),
|
|
116
115
|
}));
|
|
116
|
+
if (items.length === 0)
|
|
117
|
+
return [];
|
|
117
118
|
const data = await api().request("/values/read", { items });
|
|
118
119
|
if (!Array.isArray(data) || data.length !== items.length) {
|
|
119
120
|
throw unreadable();
|
|
@@ -146,6 +147,8 @@ export function createValues(api) {
|
|
|
146
147
|
? {}
|
|
147
148
|
: { revision: revisionOf(item.revision) }),
|
|
148
149
|
}));
|
|
150
|
+
if (items.length === 0)
|
|
151
|
+
return [];
|
|
149
152
|
const data = await api().request("/values/write", { items });
|
|
150
153
|
if (!Array.isArray(data) || data.length !== items.length) {
|
|
151
154
|
throw unreadable();
|
|
@@ -168,6 +171,8 @@ export function createValues(api) {
|
|
|
168
171
|
? {}
|
|
169
172
|
: { revision: revisionOf(item.revision) }),
|
|
170
173
|
}));
|
|
174
|
+
if (items.length === 0)
|
|
175
|
+
return;
|
|
171
176
|
await api().request("/values/remove", { items });
|
|
172
177
|
};
|
|
173
178
|
const list = async function (scope, options = {}) {
|
package/package.json
CHANGED