@arcadible/server-sdk 0.0.0-stage → 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/LICENSE +176 -0
- package/README.md +120 -2
- package/dist/server/api.d.ts +11 -0
- package/dist/server/api.js +75 -0
- package/dist/server/index.d.ts +27 -0
- package/dist/server/index.js +35 -0
- package/dist/server/issuer.d.ts +17 -0
- package/dist/server/issuer.js +46 -0
- package/dist/server/keys.d.ts +11 -0
- package/dist/server/keys.js +87 -0
- package/dist/server/players.d.ts +33 -0
- package/dist/server/players.js +33 -0
- package/dist/server/tickets.d.ts +59 -0
- package/dist/server/tickets.js +178 -0
- package/dist/shared/api.d.ts +16 -0
- package/dist/shared/api.js +75 -0
- package/dist/shared/error.d.ts +17 -0
- package/dist/shared/error.js +38 -0
- package/dist/shared/players.d.ts +23 -0
- package/dist/shared/players.js +69 -0
- package/dist/shared/values.d.ts +100 -0
- package/dist/shared/values.js +208 -0
- package/package.json +30 -4
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
// Values: a game's data kept on Arcadible, JSON under a key, in a scope. A
|
|
2
|
+
// game's server, its own or its function, reads all four scopes, and writes
|
|
3
|
+
// all but the developer's: its own (`server`, which no client reads, and
|
|
4
|
+
// which a function and a server with the channel's key share), the game's
|
|
5
|
+
// (`game`, which every client reads), and any player's of the game.
|
|
6
|
+
import { ArcadibleError, Codes } from "./error.js";
|
|
7
|
+
// A key: 1 to 128 letters, digits, `-`, `_`, `.`, and `/`.
|
|
8
|
+
const KEY = /^[A-Za-z0-9_./-]{1,128}$/u;
|
|
9
|
+
const PREFIX = /^[A-Za-z0-9_./-]{0,128}$/u;
|
|
10
|
+
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
|
|
11
|
+
// The most keys one call names, and one list gives.
|
|
12
|
+
export const MAX_KEYS = 32;
|
|
13
|
+
export const MAX_LIST = 100;
|
|
14
|
+
// [function]
|
|
15
|
+
function isObject(value) {
|
|
16
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
17
|
+
}
|
|
18
|
+
// [function]
|
|
19
|
+
function invalid(message) {
|
|
20
|
+
return new ArcadibleError(Codes.Invalid, message);
|
|
21
|
+
}
|
|
22
|
+
// [function]
|
|
23
|
+
// an answer that isn't the shape a server relies on.
|
|
24
|
+
function unreadable() {
|
|
25
|
+
return new ArcadibleError(Codes.Unavailable, "Arcadible's answer couldn't be read. Try again.");
|
|
26
|
+
}
|
|
27
|
+
// [function]
|
|
28
|
+
// what a request says of its scope: its name, and the player for a player's.
|
|
29
|
+
function scopeOf(scope) {
|
|
30
|
+
if (scope === "developer" || scope === "game" || scope === "server") {
|
|
31
|
+
return { scope };
|
|
32
|
+
}
|
|
33
|
+
if (isObject(scope) && typeof scope.id === "string" && UUID.test(scope.id)) {
|
|
34
|
+
return { player: scope.id, scope: "player" };
|
|
35
|
+
}
|
|
36
|
+
throw invalid('A scope is "developer", "game", "server", or a player, as { id }.');
|
|
37
|
+
}
|
|
38
|
+
// [function]
|
|
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.
|
|
42
|
+
function itemsOf(items) {
|
|
43
|
+
if (!Array.isArray(items) || !items.every(isObject)) {
|
|
44
|
+
throw invalid("A call takes a list of items, each { scope, key }.");
|
|
45
|
+
}
|
|
46
|
+
if (items.length > MAX_KEYS) {
|
|
47
|
+
throw new ArcadibleError(Codes.TooMany, `A call names up to ${MAX_KEYS} items.`);
|
|
48
|
+
}
|
|
49
|
+
const seen = new Set();
|
|
50
|
+
for (const item of items) {
|
|
51
|
+
const key = item["key"];
|
|
52
|
+
if (typeof key !== "string" || !KEY.test(key)) {
|
|
53
|
+
throw invalid("A key is 1 to 128 letters, digits, -, _, ., and /: " +
|
|
54
|
+
JSON.stringify(key));
|
|
55
|
+
}
|
|
56
|
+
const where = `${JSON.stringify(scopeOf(item["scope"]))} ${key}`;
|
|
57
|
+
if (seen.has(where))
|
|
58
|
+
throw invalid("A call names each key once in a scope.");
|
|
59
|
+
seen.add(where);
|
|
60
|
+
}
|
|
61
|
+
return items;
|
|
62
|
+
}
|
|
63
|
+
// [function]
|
|
64
|
+
// a value as JSON keeps it: `undefined`, a function, or a number that isn't
|
|
65
|
+
// one would be dropped or changed on the way, so each is refused here.
|
|
66
|
+
function jsonOf(key, value) {
|
|
67
|
+
let text;
|
|
68
|
+
try {
|
|
69
|
+
text = JSON.stringify(value, (_, each) => {
|
|
70
|
+
if (typeof each === "number" && !Number.isFinite(each)) {
|
|
71
|
+
throw new TypeError("not finite");
|
|
72
|
+
}
|
|
73
|
+
return each;
|
|
74
|
+
});
|
|
75
|
+
}
|
|
76
|
+
catch {
|
|
77
|
+
text = undefined;
|
|
78
|
+
}
|
|
79
|
+
if (text === undefined) {
|
|
80
|
+
throw invalid(`The value for ${JSON.stringify(key)} isn't JSON.`);
|
|
81
|
+
}
|
|
82
|
+
return JSON.parse(text);
|
|
83
|
+
}
|
|
84
|
+
// [function]
|
|
85
|
+
function revisionOf(revision) {
|
|
86
|
+
if (!Number.isSafeInteger(revision) || revision < 0) {
|
|
87
|
+
throw invalid("A revision is a value's own, from a read or a write, or 0.");
|
|
88
|
+
}
|
|
89
|
+
return revision;
|
|
90
|
+
}
|
|
91
|
+
// [function]
|
|
92
|
+
// a row of a read, a write, or a list, in the SDK's words.
|
|
93
|
+
function rowOf(entry) {
|
|
94
|
+
if (!isObject(entry) ||
|
|
95
|
+
typeof entry["key"] !== "string" ||
|
|
96
|
+
typeof entry["revision"] !== "number" ||
|
|
97
|
+
typeof entry["updated_at"] !== "string") {
|
|
98
|
+
throw unreadable();
|
|
99
|
+
}
|
|
100
|
+
return {
|
|
101
|
+
key: entry["key"],
|
|
102
|
+
revision: entry["revision"],
|
|
103
|
+
size: typeof entry["size"] === "number" ? entry["size"] : 0,
|
|
104
|
+
updatedAt: entry["updated_at"],
|
|
105
|
+
value: entry["value"],
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
// [function]
|
|
109
|
+
export function createValues(api) {
|
|
110
|
+
const read = async function (given) {
|
|
111
|
+
const items = itemsOf(given).map((item) => ({
|
|
112
|
+
...scopeOf(item.scope),
|
|
113
|
+
key: item.key,
|
|
114
|
+
...(item.since === undefined ? {} : { since: revisionOf(item.since) }),
|
|
115
|
+
}));
|
|
116
|
+
if (items.length === 0)
|
|
117
|
+
return [];
|
|
118
|
+
const data = await api().request("/values/read", { items });
|
|
119
|
+
if (!Array.isArray(data) || data.length !== items.length) {
|
|
120
|
+
throw unreadable();
|
|
121
|
+
}
|
|
122
|
+
return data.map((entry, at) => {
|
|
123
|
+
const scope = given[at].scope;
|
|
124
|
+
if (entry === null)
|
|
125
|
+
return null;
|
|
126
|
+
if (isObject(entry) &&
|
|
127
|
+
entry["unchanged"] === true &&
|
|
128
|
+
typeof entry["key"] === "string" &&
|
|
129
|
+
typeof entry["revision"] === "number") {
|
|
130
|
+
return {
|
|
131
|
+
key: entry["key"],
|
|
132
|
+
revision: entry["revision"],
|
|
133
|
+
scope,
|
|
134
|
+
unchanged: true,
|
|
135
|
+
};
|
|
136
|
+
}
|
|
137
|
+
const { key, revision, updatedAt, value } = rowOf(entry);
|
|
138
|
+
return { key, revision, scope, updatedAt, value };
|
|
139
|
+
});
|
|
140
|
+
};
|
|
141
|
+
const write = async function (given) {
|
|
142
|
+
const items = itemsOf(given).map((item) => ({
|
|
143
|
+
...scopeOf(item.scope),
|
|
144
|
+
key: item.key,
|
|
145
|
+
value: jsonOf(item.key, item.value),
|
|
146
|
+
...(item.revision === undefined
|
|
147
|
+
? {}
|
|
148
|
+
: { revision: revisionOf(item.revision) }),
|
|
149
|
+
}));
|
|
150
|
+
if (items.length === 0)
|
|
151
|
+
return [];
|
|
152
|
+
const data = await api().request("/values/write", { items });
|
|
153
|
+
if (!Array.isArray(data) || data.length !== items.length) {
|
|
154
|
+
throw unreadable();
|
|
155
|
+
}
|
|
156
|
+
return data.map((entry, at) => {
|
|
157
|
+
const { key, revision, updatedAt } = rowOf(entry);
|
|
158
|
+
return {
|
|
159
|
+
key,
|
|
160
|
+
revision,
|
|
161
|
+
scope: given[at].scope,
|
|
162
|
+
updatedAt,
|
|
163
|
+
};
|
|
164
|
+
});
|
|
165
|
+
};
|
|
166
|
+
const remove = async function (given) {
|
|
167
|
+
const items = itemsOf(given).map((item) => ({
|
|
168
|
+
...scopeOf(item.scope),
|
|
169
|
+
key: item.key,
|
|
170
|
+
...(item.revision === undefined
|
|
171
|
+
? {}
|
|
172
|
+
: { revision: revisionOf(item.revision) }),
|
|
173
|
+
}));
|
|
174
|
+
if (items.length === 0)
|
|
175
|
+
return;
|
|
176
|
+
await api().request("/values/remove", { items });
|
|
177
|
+
};
|
|
178
|
+
const list = async function (scope, options = {}) {
|
|
179
|
+
const { after = "", limit = 50, prefix = "" } = options;
|
|
180
|
+
if (typeof prefix !== "string" || !PREFIX.test(prefix)) {
|
|
181
|
+
throw invalid("A prefix is what a key starts with: a key's letters.");
|
|
182
|
+
}
|
|
183
|
+
if (typeof after !== "string" || !PREFIX.test(after)) {
|
|
184
|
+
throw invalid("`after` is a key: a list's `next`.");
|
|
185
|
+
}
|
|
186
|
+
if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIST) {
|
|
187
|
+
throw invalid(`A list gives 1 to ${MAX_LIST} keys.`);
|
|
188
|
+
}
|
|
189
|
+
const data = await api().request("/values/list", {
|
|
190
|
+
...scopeOf(scope),
|
|
191
|
+
after,
|
|
192
|
+
limit,
|
|
193
|
+
prefix,
|
|
194
|
+
});
|
|
195
|
+
if (!isObject(data) || !Array.isArray(data["entries"])) {
|
|
196
|
+
throw unreadable();
|
|
197
|
+
}
|
|
198
|
+
const next = data["next"];
|
|
199
|
+
return {
|
|
200
|
+
entries: data["entries"].map((entry) => {
|
|
201
|
+
const { key, revision, size, updatedAt } = rowOf(entry);
|
|
202
|
+
return { key, revision, size, updatedAt };
|
|
203
|
+
}),
|
|
204
|
+
next: typeof next === "string" ? next : null,
|
|
205
|
+
};
|
|
206
|
+
};
|
|
207
|
+
return { list, read, remove, write };
|
|
208
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,32 @@
|
|
|
1
1
|
{
|
|
2
|
+
"author": "Offst, Inc.",
|
|
3
|
+
"description": "The Arcadible Server SDK: how your own server works with Arcadible.",
|
|
4
|
+
"engines": {
|
|
5
|
+
"node": ">=22"
|
|
6
|
+
},
|
|
7
|
+
"exports": {
|
|
8
|
+
".": {
|
|
9
|
+
"import": "./dist/server/index.js",
|
|
10
|
+
"types": "./dist/server/index.d.ts"
|
|
11
|
+
}
|
|
12
|
+
},
|
|
13
|
+
"files": [
|
|
14
|
+
"dist"
|
|
15
|
+
],
|
|
16
|
+
"homepage": "https://developer.arcadible.com/references/arcadible-server-sdk",
|
|
17
|
+
"keywords": [
|
|
18
|
+
"arcadible",
|
|
19
|
+
"games",
|
|
20
|
+
"sdk",
|
|
21
|
+
"server",
|
|
22
|
+
"tickets"
|
|
23
|
+
],
|
|
24
|
+
"license": "Apache-2.0",
|
|
2
25
|
"name": "@arcadible/server-sdk",
|
|
3
|
-
"
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
26
|
+
"scripts": {
|
|
27
|
+
"prepack": "rm -rf dist && tsc -p ../tsconfig.server.json"
|
|
28
|
+
},
|
|
29
|
+
"type": "module",
|
|
30
|
+
"types": "./dist/server/index.d.ts",
|
|
31
|
+
"version": "0.5.0-next.0"
|
|
32
|
+
}
|