@rbxts/scribe 2.5.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.
Files changed (56) hide show
  1. package/LICENSE +21 -0
  2. package/NOTICE +21 -0
  3. package/README.md +100 -0
  4. package/Scribe-source-map.json +1 -0
  5. package/licenses/ProfileStore-Apache-2.0.txt +201 -0
  6. package/package.json +32 -0
  7. package/src/Client/DebugHook.luau +457 -0
  8. package/src/Client/init.luau +1607 -0
  9. package/src/Internal/Addons.luau +68 -0
  10. package/src/Internal/Big.luau +582 -0
  11. package/src/Internal/Budget.luau +377 -0
  12. package/src/Internal/Clock.luau +75 -0
  13. package/src/Internal/Config.luau +17 -0
  14. package/src/Internal/Conform.luau +400 -0
  15. package/src/Internal/Datatypes.luau +653 -0
  16. package/src/Internal/Defaults.luau +12 -0
  17. package/src/Internal/Derived.luau +428 -0
  18. package/src/Internal/Exchange.luau +556 -0
  19. package/src/Internal/ExchangeLeg.luau +1368 -0
  20. package/src/Internal/ExchangeVerdict.luau +179 -0
  21. package/src/Internal/Failure.luau +148 -0
  22. package/src/Internal/Health.luau +320 -0
  23. package/src/Internal/LeaderboardDiagnostics.luau +36 -0
  24. package/src/Internal/Log.luau +378 -0
  25. package/src/Internal/Marker.luau +76 -0
  26. package/src/Internal/Metrics.luau +152 -0
  27. package/src/Internal/Node.luau +3954 -0
  28. package/src/Internal/Profile.luau +69 -0
  29. package/src/Internal/Rng.luau +83 -0
  30. package/src/Internal/Sched.luau +56 -0
  31. package/src/Internal/Signal.luau +199 -0
  32. package/src/Internal/Store/ProfileStore.luau +3019 -0
  33. package/src/Internal/Store/init.luau +18 -0
  34. package/src/Internal/StudioCodec.luau +155 -0
  35. package/src/Internal/Template.luau +1848 -0
  36. package/src/Internal/Transport.luau +169 -0
  37. package/src/Internal/Util.luau +517 -0
  38. package/src/Internal/Version.luau +4 -0
  39. package/src/Internal/Wire.luau +1283 -0
  40. package/src/Server/Analytics.luau +223 -0
  41. package/src/Server/Commands.luau +728 -0
  42. package/src/Server/DebugHook.luau +1490 -0
  43. package/src/Server/Exchanges.luau +737 -0
  44. package/src/Server/Leaderboards.luau +2143 -0
  45. package/src/Server/Monetization.luau +3212 -0
  46. package/src/Server/Persistence.luau +3775 -0
  47. package/src/Server/Replication.luau +1253 -0
  48. package/src/Server/ServerStore.luau +81 -0
  49. package/src/Server/Timed.luau +579 -0
  50. package/src/Server/init.luau +672 -0
  51. package/src/Types.luau +480 -0
  52. package/src/init.luau +2231 -0
  53. package/types/api.d.ts +252 -0
  54. package/types/common.d.ts +355 -0
  55. package/types/index.d.ts +226 -0
  56. package/types/schema.d.ts +276 -0
@@ -0,0 +1,428 @@
1
+ --!strict
2
+ -- Derived fields. A derived field is computed from other declared fields instead of
3
+ -- accepting writes: never persisted, recomputed when an input changes, and replicated
4
+ -- only when the receiving realm cannot compute it for itself. This module owns the
5
+ -- compile-time half (resolve input paths, order the graph, decide who computes, build
6
+ -- the write index) plus a realm-agnostic evaluator.
7
+ --
8
+ -- Schema nodes are typed `any` throughout: Template requires this module for its
9
+ -- post-compile pass, so importing Template's SchemaNode back would be a cycle.
10
+
11
+ local Big = require(script.Parent.Big)
12
+ local Datatypes = require(script.Parent.Datatypes)
13
+ local Util = require(script.Parent.Util)
14
+
15
+ local Derived = {}
16
+
17
+ -- Read form must be a plain, immutable scalar: the value is handed to user code on
18
+ -- every recompute, so a mutable shape would let a compute function mutate live
19
+ -- state through its own argument.
20
+ local ALLOWED_INPUT_TYPES: { [string]: boolean } = {
21
+ int = true,
22
+ number = true,
23
+ string = true,
24
+ boolean = true,
25
+ enum = true,
26
+ big = true,
27
+ datatype = true,
28
+ }
29
+
30
+ -- Outputs are narrower than inputs: this module computes the compile-time default,
31
+ -- and a big/datatype default would have to be converted to its stored form and
32
+ -- bounds-checked, which is validateWrite's job on the runtime path.
33
+ local ALLOWED_OUTPUT_TYPES: { [string]: boolean } = {
34
+ int = true,
35
+ number = true,
36
+ string = true,
37
+ boolean = true,
38
+ enum = true,
39
+ }
40
+
41
+ -- ServerOnly's audience is a subset of Replicated's, which is a subset of Shared's,
42
+ -- so "can this audience see that field" is a rank comparison.
43
+ local VISIBILITY_RANK: { [string]: number } = {
44
+ ServerOnly = 0,
45
+ Replicated = 1,
46
+ Shared = 2,
47
+ }
48
+
49
+ Derived.ALLOWED_INPUT_TYPES = ALLOWED_INPUT_TYPES
50
+ Derived.ALLOWED_OUTPUT_TYPES = ALLOWED_OUTPUT_TYPES
51
+
52
+ -- Stored -> read form for the value handed to a compute function. Mirrors
53
+ -- Node.unpackRead for the two split-representation types; every other allowed
54
+ -- input type stores what it reads.
55
+ function Derived.ReadForm(node: any, stored: any): any
56
+ if stored == nil then
57
+ return nil
58
+ end
59
+ if node.ValueType == "big" then
60
+ return Big.from(stored)
61
+ end
62
+ if node.ValueType == "datatype" and type(stored) == "buffer" then
63
+ return Datatypes.Unpack(node.Datatype :: string, stored)
64
+ end
65
+ return stored
66
+ end
67
+
68
+ -- Compile time -----------------------------------------------------------------
69
+
70
+ -- Walk STATIC children only. A container (ArrayOf/DictOf) holds its element schema
71
+ -- on AnyChild rather than Children, and a dynamic key has no schema at all, so
72
+ -- stopping at Children is exactly the "must exist in the template" rule.
73
+ local function resolveStatic(root: any, segments: { string }): any
74
+ local node = root
75
+ for _, segment in segments do
76
+ local children = node.Children
77
+ if children == nil then
78
+ return nil
79
+ end
80
+ local child = children[segment]
81
+ if child == nil then
82
+ return nil
83
+ end
84
+ node = child
85
+ end
86
+ return node
87
+ end
88
+
89
+ local function describe(node: any): string
90
+ if node.Timed then
91
+ return "a Scribe.Timed field"
92
+ elseif node.Container ~= nil then
93
+ return `a Scribe.{node.Container}Of container`
94
+ elseif node.ValueType == "flags" then
95
+ return "a Scribe.Flags field"
96
+ elseif node.ValueType == "table" then
97
+ return "a record"
98
+ elseif node.ValueType == "any" then
99
+ return "an undeclared (dynamic) field"
100
+ end
101
+ return `a {node.ValueType} field`
102
+ end
103
+
104
+ --[[
105
+ Resolves every collected derived field against the finished schema tree.
106
+
107
+ `pending` is what buildNode collected, in template order: each entry is
108
+ { Node, InputPaths (dotted strings), Compute }. `fail` is Template's compileError,
109
+ passed in so the error text keeps one format.
110
+
111
+ Returns the topologically ordered node list and the write index.
112
+ ]]
113
+ function Derived.Resolve(
114
+ root: any,
115
+ pending: { { Node: any, InputPaths: { string }, Compute: (...any) -> any } },
116
+ reservedRoots: { [string]: boolean },
117
+ fail: (path: { string }, message: string) -> ()
118
+ ): ({ any }, { [string]: { any } })
119
+ -- Resolve and validate every input before ordering: a cycle message is only
120
+ -- useful once the edges it names are known to be real fields.
121
+ for _, entry in pending do
122
+ local node = entry.Node
123
+ local path = node.Path
124
+ if not ALLOWED_OUTPUT_TYPES[node.ValueType] then
125
+ fail(
126
+ path,
127
+ `Scribe.Derived produces {describe(node)}, but a derived field must be an Int, Number, String, `
128
+ .. "Boolean or Enum"
129
+ )
130
+ end
131
+ if #entry.InputPaths == 0 then
132
+ fail(path, "Scribe.Derived requires at least one input path")
133
+ end
134
+ -- A gap silently narrows the field: the loop below skips it, so the string check
135
+ -- never sees it and Compute takes nil for that parameter forever.
136
+ local gap = Util.firstGap(entry.InputPaths)
137
+ if gap ~= nil then
138
+ fail(path, `Scribe.Derived input {gap} is nil; the input list cannot have a gap`)
139
+ end
140
+
141
+ local inputs: { any } = {}
142
+ local inputPaths: { { string } } = {}
143
+ local seen: { [string]: boolean } = {}
144
+ for _, raw in entry.InputPaths do
145
+ if type(raw) ~= "string" then
146
+ fail(path, `Scribe.Derived inputs must be dotted path strings, got a {typeof(raw)}`)
147
+ end
148
+ local segments = Util.parsePath(raw)
149
+ if #segments == 0 then
150
+ fail(path, `Scribe.Derived input "{raw}" is not a path`)
151
+ end
152
+ if reservedRoots[segments[1]] then
153
+ fail(
154
+ path,
155
+ `Scribe.Derived input "{raw}" reads a library-owned root; derived fields cannot depend on `
156
+ .. "Scribe's own state (perks, ownership, save info)"
157
+ )
158
+ end
159
+ local key = table.concat(segments, ".")
160
+ if seen[key] then
161
+ fail(path, `Scribe.Derived lists the input "{raw}" twice`)
162
+ end
163
+ seen[key] = true
164
+
165
+ local resolved = resolveStatic(root, segments)
166
+ if resolved == nil then
167
+ fail(
168
+ path,
169
+ `Scribe.Derived input "{raw}" does not resolve to a declared field. Inputs must name a field `
170
+ .. "that exists in the template (a container entry or a runtime key has no schema)"
171
+ )
172
+ end
173
+ if resolved == node then
174
+ fail(path, "Scribe.Derived reads itself")
175
+ end
176
+ if resolved.Timed then
177
+ fail(
178
+ path,
179
+ `Scribe.Derived input "{raw}" is a Scribe.Timed field. A timer lapses on the wall clock `
180
+ .. "rather than on a write, and an expired-but-uncleared value reads differently online "
181
+ .. "and offline, so the same profile would derive two different values"
182
+ )
183
+ end
184
+ if resolved.Kind ~= "leaf" or not ALLOWED_INPUT_TYPES[resolved.ValueType] then
185
+ fail(
186
+ path,
187
+ `Scribe.Derived input "{raw}" is {describe(resolved)}. Inputs must be an Int, Number, String, `
188
+ .. "Boolean, Enum, Big or datatype field"
189
+ )
190
+ end
191
+ table.insert(inputs, resolved)
192
+ table.insert(inputPaths, segments)
193
+ end
194
+
195
+ node.Derived = {
196
+ Inputs = inputs,
197
+ InputPaths = inputPaths,
198
+ Compute = entry.Compute,
199
+ Transmit = false, -- decided below, once the graph is ordered
200
+ OfflineComputable = false,
201
+ Label = table.concat(node.Path, "."),
202
+ }
203
+ end
204
+
205
+ -- Topological order over derived -> derived edges, three-colour DFS. `pending`
206
+ -- is in sorted template order, so server and client end up with the same order.
207
+ local ordered: { any } = {}
208
+ local mark: { [any]: string } = {}
209
+ local stack: { any } = {}
210
+ local function visit(node: any)
211
+ local state = mark[node]
212
+ if state == "done" then
213
+ return
214
+ end
215
+ if state == "open" then
216
+ local cycle = {}
217
+ local started = false
218
+ for _, entry in stack do
219
+ if entry == node then
220
+ started = true
221
+ end
222
+ if started then
223
+ table.insert(cycle, table.concat(entry.Path, "."))
224
+ end
225
+ end
226
+ table.insert(cycle, table.concat(node.Path, "."))
227
+ fail(node.Path, `derived fields form a cycle ({table.concat(cycle, " -> ")})`)
228
+ end
229
+ mark[node] = "open"
230
+ table.insert(stack, node)
231
+ for _, input in node.Derived.Inputs do
232
+ if input.Derived ~= nil then
233
+ visit(input)
234
+ end
235
+ end
236
+ table.remove(stack)
237
+ mark[node] = "done"
238
+ table.insert(ordered, node)
239
+ end
240
+ for _, entry in pending do
241
+ visit(entry.Node)
242
+ end
243
+
244
+ -- Who computes. Runs after ordering because a derived input's visibility is the
245
+ -- visibility of that derived field.
246
+ for _, node in ordered do
247
+ local outRank = VISIBILITY_RANK[node.Visibility] or 1
248
+ local transmit = false
249
+ if node.Visibility ~= "ServerOnly" then
250
+ for _, input in node.Derived.Inputs do
251
+ if (VISIBILITY_RANK[input.Visibility] or 1) < outRank then
252
+ transmit = true
253
+ break
254
+ end
255
+ end
256
+ end
257
+ node.Derived.Transmit = transmit
258
+
259
+ -- Offline reads see stored data only, so a root-level field whose every input
260
+ -- persists can be computed over a snapshot. A derived input never persists but
261
+ -- is filled in first (both passes run in topological order), so it counts as
262
+ -- available exactly when it is itself computable.
263
+ local offline = #node.Path == 1
264
+ if offline then
265
+ for _, input in node.Derived.Inputs do
266
+ local viaDerived = input.Derived ~= nil and input.Derived.OfflineComputable
267
+ if not input.Persist and not viaDerived then
268
+ offline = false
269
+ break
270
+ end
271
+ end
272
+ end
273
+ node.Derived.OfflineComputable = offline
274
+ end
275
+
276
+ -- Write index: a write at path W must recompute a dependent on input I when
277
+ -- W == I or W is an ancestor of I (a whole-root Set from an init snapshot, say).
278
+ -- Inputs are leaves, so no other relationship exists and one exact lookup per
279
+ -- write is complete.
280
+ local byWrite: { [string]: { any } } = {}
281
+ for _, node in ordered do
282
+ for _, segments in node.Derived.InputPaths do
283
+ local prefix: { string | number } = {}
284
+ for _, segment in segments do
285
+ table.insert(prefix, segment)
286
+ local key = Util.pathKey(prefix)
287
+ local list = byWrite[key]
288
+ if list == nil then
289
+ list = {}
290
+ byWrite[key] = list
291
+ end
292
+ local present = false
293
+ for _, existing in list do
294
+ if existing == node then
295
+ present = true
296
+ break
297
+ end
298
+ end
299
+ if not present then
300
+ table.insert(list, node)
301
+ end
302
+ end
303
+ end
304
+ end
305
+
306
+ return ordered, byWrite
307
+ end
308
+
309
+ -- Validates a computed value against the output declarator, at the one place that
310
+ -- has no applySet to lean on: the compile-time default. Returns an error string.
311
+ local function checkDefault(node: any, value: any): string?
312
+ local t = type(value)
313
+ if node.ValueType == "int" or node.ValueType == "number" then
314
+ if t ~= "number" then
315
+ return `returned a {typeof(value)}, but the field is a {node.ValueType}`
316
+ end
317
+ if value ~= value or value == math.huge or value == -math.huge then
318
+ return "returned NaN or infinity"
319
+ end
320
+ elseif node.ValueType == "string" then
321
+ if t ~= "string" then
322
+ return `returned a {typeof(value)}, but the field is a string`
323
+ end
324
+ if not Util.isUtf8(value :: string) then
325
+ return "returned a string containing invalid UTF-8"
326
+ end
327
+ elseif node.ValueType == "boolean" then
328
+ if t ~= "boolean" then
329
+ return `returned a {typeof(value)}, but the field is a boolean`
330
+ end
331
+ elseif node.ValueType == "enum" then
332
+ if t ~= "string" or node.MemberIndex == nil or node.MemberIndex[value] == nil then
333
+ return `returned {tostring(value)}, which is not a member of the enum`
334
+ end
335
+ end
336
+ return nil
337
+ end
338
+
339
+ --[[
340
+ Seeds every derived field's Default from its inputs' defaults, in topological
341
+ order, so a brand-new profile / a fresh session store / an edit-mode client all
342
+ start out correct with no runtime work. Also the earliest possible purity check:
343
+ the function runs once per realm at startup, before any player exists.
344
+ ]]
345
+ function Derived.SeedDefaults(ordered: { any }, fail: (path: { string }, message: string) -> ())
346
+ for _, node in ordered do
347
+ local spec = node.Derived
348
+ local values = table.create(#spec.Inputs)
349
+ for i, input in spec.Inputs do
350
+ values[i] = Derived.ReadForm(input, input.Default)
351
+ end
352
+ local ok, value = pcall(spec.Compute, table.unpack(values, 1, #spec.Inputs))
353
+ if not ok then
354
+ fail(node.Path, `the Scribe.Derived compute function threw while evaluating its default: {tostring(value)}`)
355
+ end
356
+ local problem = checkDefault(node, value)
357
+ if problem then
358
+ fail(node.Path, `the Scribe.Derived compute function {problem}`)
359
+ end
360
+ node.Default = value
361
+ end
362
+ end
363
+
364
+ -- Evaluation -------------------------------------------------------------------
365
+
366
+ --- Runs one field's compute function. Never raises: a throwing function must not
367
+ --- fail the write that triggered the recompute.
368
+ function Derived.Compute(node: any, values: { any }, count: number): (boolean, any)
369
+ return pcall(node.Derived.Compute, table.unpack(values, 1, count))
370
+ end
371
+
372
+ local function readPlain(data: { [string]: any }, segments: { string }): (boolean, any)
373
+ local value: any = data
374
+ for _, segment in segments do
375
+ if type(value) ~= "table" then
376
+ return false, nil
377
+ end
378
+ value = value[segment]
379
+ end
380
+ return true, value
381
+ end
382
+
383
+ --[[
384
+ Evaluates derived fields over a plain data table (an offline profile snapshot, a
385
+ client's Shared mirror for another player) rather than over an accessor tree.
386
+
387
+ `filter` selects which fields apply; a field whose parent table is absent from
388
+ `data` is skipped, which is what keeps an offline snapshot from growing a root
389
+ that stored data never had.
390
+ ]]
391
+ function Derived.EvaluateInto(compiled: any, data: { [string]: any }, filter: (node: any) -> boolean)
392
+ local ordered = compiled.DerivedNodes
393
+ if ordered == nil then
394
+ return
395
+ end
396
+ for _, node in ordered do
397
+ if filter(node) then
398
+ local spec = node.Derived
399
+ local values = table.create(#spec.Inputs)
400
+ local complete = true
401
+ for i, input in spec.Inputs do
402
+ local ok, stored = readPlain(data, spec.InputPaths[i])
403
+ if not ok then
404
+ complete = false
405
+ break
406
+ end
407
+ values[i] = Derived.ReadForm(input, stored)
408
+ end
409
+ if complete then
410
+ -- Resolve the parent container in `data`; skip rather than create,
411
+ -- so a mirror that never received this root stays as it was.
412
+ local container: any = data
413
+ local path = node.Path
414
+ for i = 1, #path - 1 do
415
+ container = if type(container) == "table" then container[path[i]] else nil
416
+ end
417
+ if type(container) == "table" then
418
+ local ok, value = Derived.Compute(node, values, #spec.Inputs)
419
+ if ok then
420
+ container[path[#path]] = value
421
+ end
422
+ end
423
+ end
424
+ end
425
+ end
426
+ end
427
+
428
+ return Derived