@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 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.id]);
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
- - **`players.read`** takes up to 50 ids. A name is the player's own, as they've set it on Arcadible; show it as text.
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 ids.
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(ids: readonly string[]): Promise<(Player | null)[]>;
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";
@@ -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 ids.
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): (ids: readonly string[]) => Promise<(Player | null)[]>;
21
+ export declare function readPlayers(api: () => Api): (players: readonly ({
22
+ readonly id: string;
23
+ } | null | undefined)[]) => Promise<(Player | null)[]>;
@@ -1,8 +1,11 @@
1
1
  // Players: what a game's server, or its function, may ask Arcadible about
2
- // the players it knows by their ids: their names. Each package adds its own
3
- // (the server's `deleted`, the function's `primary`).
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 ids one read takes.
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 ids.
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 (ids) => {
24
- if (!Array.isArray(ids) ||
25
- ids.length > MAX_PLAYERS ||
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 (ids.length === 0)
30
- return [];
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
  }
@@ -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, by their id in the game:
6
- * `{ id }`, as `players.primary(request)` or a ticket gives it.
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 32.
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
  /**
@@ -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: at least one, no more than a call takes, each an object
40
- // with a scope and a key, none named twice in a scope.
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
@@ -25,5 +25,5 @@
25
25
  },
26
26
  "type": "module",
27
27
  "types": "./dist/function/index.d.ts",
28
- "version": "0.4.0-next.0"
28
+ "version": "0.5.0-next.0"
29
29
  }