@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,169 @@
1
+ --!strict
2
+ -- Transport. A transport moves opaque buffers; Scribe owns serialization, batching
3
+ -- and RPC correlation. "Default" is two RemoteEvents under a folder in
4
+ -- ReplicatedStorage.
5
+
6
+ local ReplicatedStorage = game:GetService("ReplicatedStorage")
7
+ local RunService = game:GetService("RunService")
8
+
9
+ local Types = require(script.Parent.Parent.Types)
10
+
11
+ --- A replication channel. The send methods MUST NOT YIELD: Scribe calls them from
12
+ --- inside the handshake and from the per-frame flush, and one that parks there
13
+ --- stalls that frame's remaining work for every player. Buffer and return instead.
14
+ ---
15
+ --- Re-exported from Types so what a game sees and what Resolve returns cannot drift.
16
+ export type ScribeTransport = Types.ScribeTransport
17
+
18
+ local FOLDER_PREFIX = "ScribeTransport"
19
+
20
+ local Transport = {}
21
+
22
+ -- Two Scribe instances listening on the same RemoteEvents would receive each
23
+ -- other's frames and fail schema decoding; fail loudly at startup instead.
24
+ local boundServerChannels: { [string]: boolean } = {}
25
+
26
+ -- How to hand a claimed channel back, keyed by folder name. The claim above is
27
+ -- module-global and outlives any one bundle: without a release, a stopped bundle
28
+ -- keeps its channel and its OnServerEvent listener for the rest of the process, so
29
+ -- client frames still reach a bundle whose save paths are dead.
30
+ local channelReleases: { [string]: () -> () } = {}
31
+
32
+ local function folderName(channel: string?): string
33
+ if channel and channel ~= "" and channel ~= "Default" then
34
+ return `{FOLDER_PREFIX}_{channel}`
35
+ end
36
+ return FOLDER_PREFIX
37
+ end
38
+
39
+ local function buildDefault(channel: string?): ScribeTransport
40
+ local name = folderName(channel)
41
+ local down: RemoteEvent
42
+ local up: RemoteEvent
43
+ -- The server list backs ReleaseChannel and the claim; the client list backs Release.
44
+ local serverConnections: { RBXScriptConnection }? = nil
45
+ local clientConnections: { RBXScriptConnection } = {}
46
+
47
+ if RunService:IsServer() then
48
+ if boundServerChannels[name] then
49
+ error(
50
+ `Scribe: another Scribe instance is already using the "{channel or "Default"}" transport channel; `
51
+ .. "give each instance a distinct TransportChannel option",
52
+ 0
53
+ )
54
+ end
55
+ boundServerChannels[name] = true
56
+ -- Recorded on the channel rather than returned from ListenServer, which would
57
+ -- widen the public ScribeTransport signature custom adapters are written to.
58
+ local connections: { RBXScriptConnection } = {}
59
+ serverConnections = connections
60
+ channelReleases[name] = function()
61
+ for _, connection in connections do
62
+ pcall(function()
63
+ connection:Disconnect()
64
+ end)
65
+ end
66
+ table.clear(connections)
67
+ end
68
+ local folder = ReplicatedStorage:FindFirstChild(name)
69
+ if not folder then
70
+ local newFolder = Instance.new("Folder")
71
+ newFolder.Name = name
72
+ newFolder.Parent = ReplicatedStorage
73
+ folder = newFolder
74
+ end
75
+ local function ensureRemote(remoteName: string): RemoteEvent
76
+ local remote = (folder :: Instance):FindFirstChild(remoteName)
77
+ if not remote then
78
+ local newRemote = Instance.new("RemoteEvent")
79
+ newRemote.Name = remoteName
80
+ newRemote.Parent = folder
81
+ remote = newRemote
82
+ end
83
+ return remote :: RemoteEvent
84
+ end
85
+ down = ensureRemote("Down")
86
+ up = ensureRemote("Up")
87
+ else
88
+ local folder = ReplicatedStorage:WaitForChild(name)
89
+ down = folder:WaitForChild("Down") :: RemoteEvent
90
+ up = folder:WaitForChild("Up") :: RemoteEvent
91
+ end
92
+
93
+ return {
94
+ Name = "Default",
95
+ SendToClient = function(_, player: Player, bytes: buffer)
96
+ down:FireClient(player, bytes)
97
+ end,
98
+ SendToAllClients = function(_, bytes: buffer)
99
+ down:FireAllClients(bytes)
100
+ end,
101
+ ListenServer = function(_, callback: (player: Player, bytes: buffer) -> ())
102
+ local connection = up.OnServerEvent:Connect(function(player: Player, bytes: any)
103
+ -- Validated here so adapters and Scribe's decoder can assume buffers.
104
+ if typeof(bytes) == "buffer" then
105
+ callback(player, bytes)
106
+ end
107
+ end)
108
+ -- Only on the server, where serverConnections exists.
109
+ if serverConnections ~= nil then
110
+ table.insert(serverConnections, connection)
111
+ end
112
+ end,
113
+ SendToServer = function(_, bytes: buffer)
114
+ up:FireServer(bytes)
115
+ end,
116
+ ListenClient = function(_, callback: (bytes: buffer) -> ())
117
+ local connection = down.OnClientEvent:Connect(function(bytes: any)
118
+ if typeof(bytes) == "buffer" then
119
+ callback(bytes)
120
+ end
121
+ end)
122
+ table.insert(clientConnections, connection)
123
+ end,
124
+ Release = function()
125
+ for _, connection in clientConnections do
126
+ pcall(function()
127
+ connection:Disconnect()
128
+ end)
129
+ end
130
+ table.clear(clientConnections)
131
+ end,
132
+ }
133
+ end
134
+
135
+ --- Hand a Default channel back, so a later bundle in this process can claim it.
136
+ --- Disconnects what the channel connected and clears the claim. Idempotent, and a
137
+ --- no-op for a name that was never bound. Call it only from the scope that built the
138
+ --- channel: a bundle on a custom transport releasing Default would take it from
139
+ --- whoever legitimately holds it.
140
+ function Transport.ReleaseChannel(channel: string?)
141
+ local name = folderName(channel)
142
+ local release = channelReleases[name]
143
+ channelReleases[name] = nil
144
+ boundServerChannels[name] = nil
145
+ if release ~= nil then
146
+ release()
147
+ end
148
+ end
149
+
150
+ -- Resolve the Transport option: "Default", an adapter table, or nil.
151
+ function Transport.Resolve(spec: any, channel: string?): ScribeTransport
152
+ if spec == nil or spec == "Default" then
153
+ return buildDefault(channel)
154
+ end
155
+ if type(spec) == "table" then
156
+ local required: { string } = if RunService:IsServer()
157
+ then { "SendToClient", "ListenServer" }
158
+ else { "SendToServer", "ListenClient" }
159
+ for _, key in required do
160
+ if type((spec :: any)[key]) ~= "function" then
161
+ error(`Scribe: custom transport is missing "{key}" (see the ScribeTransport type)`, 0)
162
+ end
163
+ end
164
+ return spec :: ScribeTransport
165
+ end
166
+ error(`Scribe: invalid Transport option ({typeof(spec)})`, 0)
167
+ end
168
+
169
+ return Transport
@@ -0,0 +1,517 @@
1
+ --!strict
2
+ -- Small shared utilities.
3
+
4
+ local HttpService = game:GetService("HttpService")
5
+
6
+ -- Datatypes requires nothing, so this cannot cycle back into Util. Used only to
7
+ -- tell a raw-but-packable datatype apart from a genuinely unstorable value.
8
+ local Datatypes = require(script.Parent.Datatypes)
9
+
10
+ local Util = {}
11
+
12
+ -- Deepest nesting a written value may have, counted from the root. Enforced by
13
+ -- Node.validateWrite at write time and against ArrayOf/DictOf element shapes at compile
14
+ -- time, so an unsatisfiable template fails at startup rather than on every write.
15
+ Util.MAX_VALUE_DEPTH = 24
16
+
17
+ function Util.cloneBuffer(value: buffer): buffer
18
+ local out = buffer.create(buffer.len(value))
19
+ buffer.copy(out, 0, value)
20
+ return out
21
+ end
22
+
23
+ -- True when `s` is valid UTF-8, the only strings (and JSON object keys) a DataStore
24
+ -- will persist. Anything else fails the whole profile save with DataStore error 104.
25
+ function Util.isUtf8(s: string): boolean
26
+ return utf8.len(s) ~= nil
27
+ end
28
+
29
+ export type Unpersistable = {
30
+ Path: { string | number }, -- ancestor keys are all valid UTF-8, so safe to log
31
+ Kind: string, -- stable anomaly reason: "InvalidUtf8" or "Unserializable"
32
+ Detail: string, -- human-readable message
33
+ }
34
+
35
+ -- Depth-first scan for the first value or key a DataStore cannot store: invalid UTF-8
36
+ -- (error 104) or an unserializable leaf. Used by the raw-table save boundaries that
37
+ -- bypass Node.validateWrite, where the alternative is the whole save failing opaquely.
38
+ -- A bad key is reported before recursing under it, so the offender's ancestors are all
39
+ -- valid. The path rides a scratch stack: `n` is the live count, passed by value, so a
40
+ -- frame only reads `stack[1..n]` and nothing is popped.
41
+ local function snapshotPath(stack: { string | number }, n: number, extra: (string | number)?): { string | number }
42
+ local out: { string | number } = {}
43
+ table.move(stack, 1, n, 1, out)
44
+ if extra ~= nil then
45
+ out[n + 1] = extra
46
+ end
47
+ return out
48
+ end
49
+
50
+ local function scanUnpersistable(
51
+ value: any,
52
+ stack: { string | number },
53
+ n: number,
54
+ d: number,
55
+ stats: { MaxDepth: number }?
56
+ ): Unpersistable?
57
+ if stats and d > stats.MaxDepth then
58
+ stats.MaxDepth = d
59
+ end
60
+ -- Checked first, and on typeof rather than type: a Roblox datatype is storable but not
61
+ -- raw, and it is userdata on Roblox yet a plain table under the headless shim, so
62
+ -- recursing into one reports a confusing key-type error instead of the real problem.
63
+ -- Do not gate it on `type(value)` to skip the typeof call: a miss here is a false
64
+ -- negative, and every future save then fails with no path in the log.
65
+ local typeName = typeof(value)
66
+ if Datatypes.IsSupported(typeName) then
67
+ return {
68
+ Path = snapshotPath(stack, n),
69
+ Kind = "Unserializable",
70
+ Detail = `a raw {typeName}, which only the accessor packs; write `
71
+ .. `Scribe.Datatypes.Pack("{typeName}", value) here, or store a plain number instead`,
72
+ }
73
+ end
74
+ local t = type(value)
75
+ if t == "string" then
76
+ if Util.isUtf8(value :: string) then
77
+ return nil
78
+ end
79
+ return {
80
+ Path = snapshotPath(stack, n),
81
+ Kind = "InvalidUtf8",
82
+ Detail = "string contains invalid UTF-8 bytes",
83
+ }
84
+ elseif t == "boolean" or t == "buffer" then
85
+ return nil
86
+ elseif t == "number" then
87
+ if value ~= value or value == math.huge or value == -math.huge then
88
+ return { Path = snapshotPath(stack, n), Kind = "Unserializable", Detail = "NaN/inf number" }
89
+ end
90
+ return nil
91
+ elseif t == "table" then
92
+ -- A cyclic table would recurse forever, and this scan runs unprotected inside the
93
+ -- load path, so an overflow kills the player's load. Capped well past
94
+ -- MAX_VALUE_DEPTH; nothing this deep is writable or wire-encodable anyway.
95
+ if d > 64 then
96
+ return {
97
+ Path = snapshotPath(stack, n),
98
+ Kind = "Unserializable",
99
+ Detail = "nested deeper than 64 levels (or cyclic)",
100
+ }
101
+ end
102
+ local hasNum, hasStr = false, false
103
+ -- One pass, and the order is load-bearing: splitting this into a key pass and a
104
+ -- value pass would report a different offender for the same data, and would leave
105
+ -- stats.MaxDepth short, since the recursion is what deepens it.
106
+ for k, v in value :: any do
107
+ local kt = type(k)
108
+ if kt ~= "string" and kt ~= "number" then
109
+ return {
110
+ Path = snapshotPath(stack, n, "<key>"),
111
+ Kind = "Unserializable",
112
+ Detail = `unsupported key type "{kt}"`,
113
+ }
114
+ end
115
+ hasNum = hasNum or kt == "number"
116
+ hasStr = hasStr or kt == "string"
117
+ if hasNum and hasStr then
118
+ -- JSON cannot encode a table mixing array indices and object keys;
119
+ -- the whole profile save fails.
120
+ return {
121
+ Path = snapshotPath(stack, n),
122
+ Kind = "Unserializable",
123
+ Detail = "table mixes array indices and string keys",
124
+ }
125
+ end
126
+ if kt == "string" and not Util.isUtf8(k :: string) then
127
+ return {
128
+ Path = snapshotPath(stack, n, "<invalid-key>"),
129
+ Kind = "InvalidUtf8",
130
+ Detail = "object key contains invalid UTF-8 bytes",
131
+ }
132
+ end
133
+ stack[n + 1] = k
134
+ local found = scanUnpersistable(v, stack, n + 1, d + 1, stats)
135
+ if found ~= nil then
136
+ return found
137
+ end
138
+ end
139
+ return nil
140
+ end
141
+ -- userdata (Instance), function, thread, native vector, etc. A packable
142
+ -- datatype never reaches here: it is caught by the typeof check at the top.
143
+ return {
144
+ Path = snapshotPath(stack, n),
145
+ Kind = "Unserializable",
146
+ Detail = `unsupported type "{typeName}"`,
147
+ }
148
+ end
149
+
150
+ function Util.findUnpersistable(
151
+ value: any,
152
+ path: { string | number }?,
153
+ depth: number?,
154
+ stats: { MaxDepth: number }?
155
+ ): Unpersistable?
156
+ -- Cloned, not adopted: the caller still owns `path`, and the scratch stack would
157
+ -- otherwise leave its bookkeeping behind in someone else's table.
158
+ local stack: { string | number } = if path then table.clone(path) else {}
159
+ return scanUnpersistable(value, stack, #stack, depth or 0, stats)
160
+ end
161
+
162
+ -- Deep copy of a plain data value. Buffers are mutable, so they are copied
163
+ -- too; other non-table values are returned as-is.
164
+ function Util.deepClone<T>(value: T): T
165
+ local t = type(value)
166
+ if t == "buffer" then
167
+ return Util.cloneBuffer(value :: any) :: any
168
+ elseif t ~= "table" then
169
+ return value
170
+ end
171
+ local out = {}
172
+ for k, v in value :: any do
173
+ local vt = type(v)
174
+ if vt == "table" then
175
+ out[k] = Util.deepClone(v)
176
+ elseif vt == "buffer" then
177
+ out[k] = Util.cloneBuffer(v)
178
+ else
179
+ out[k] = v
180
+ end
181
+ end
182
+ return out :: any
183
+ end
184
+
185
+ -- Recursively freeze a table (template safety).
186
+ function Util.deepFreeze<T>(value: T): T
187
+ if type(value) == "table" then
188
+ for _, v in value :: any do
189
+ if type(v) == "table" and not table.isfrozen(v) then
190
+ Util.deepFreeze(v)
191
+ end
192
+ end
193
+ if not table.isfrozen(value :: any) then
194
+ table.freeze(value :: any)
195
+ end
196
+ end
197
+ return value
198
+ end
199
+
200
+ -- Sorted list of string keys of a table. Deterministic traversal for schema derivation.
201
+ function Util.sortedKeys(t: { [string]: any }): { string }
202
+ local keys = {}
203
+ for k in t do
204
+ if type(k) == "string" then
205
+ table.insert(keys, k)
206
+ end
207
+ end
208
+ table.sort(keys)
209
+ return keys
210
+ end
211
+
212
+ function Util.hasNumericKeys(t: { [any]: any }): boolean
213
+ for k in t do
214
+ if type(k) == "number" then
215
+ return true
216
+ end
217
+ end
218
+ return false
219
+ end
220
+
221
+ function Util.count(t: { [any]: any }): number
222
+ local n = 0
223
+ for _ in t do
224
+ n += 1
225
+ end
226
+ return n
227
+ end
228
+
229
+ -- What each byte costs beyond the raw one it already occupies, indexed by `byte + 1` so
230
+ -- every lookup lands in the array part.
231
+ --
232
+ -- Non-ASCII is free: the encoder emits raw UTF-8, not \uXXXX escapes. \b \t \n \f \r have
233
+ -- two-byte escapes and cost one extra; every other control character below 0x20 is
234
+ -- written as \u00XX, so five extra. A quote and a backslash cost one each.
235
+ local ESCAPE_COST: { number } = table.create(256, 0)
236
+ for b = 0, 31 do
237
+ ESCAPE_COST[b + 1] = 5
238
+ end
239
+ for _, b in { 8, 9, 10, 12, 13 } do
240
+ ESCAPE_COST[b + 1] = 1
241
+ end
242
+ ESCAPE_COST[35] = 1 -- byte 34, a double quote
243
+ ESCAPE_COST[93] = 1 -- byte 92, a backslash
244
+
245
+ -- Bytes JSON spends on a string literal, quotes included. No `string.find` fast path in
246
+ -- front of the byte walk: Luau's pattern matcher tests a character class per byte with no
247
+ -- vectorised path, and measured 2.6x slower than `string.byte` plus an array-part index.
248
+ local function jsonStringBytes(s: string): number
249
+ local n = #s
250
+ local total = n + 2
251
+ for i = 1, n do
252
+ total += ESCAPE_COST[string.byte(s, i) + 1]
253
+ end
254
+ return total
255
+ end
256
+
257
+ -- Digits in a non-negative integral double below 1e21.
258
+ local function decimalDigits(n: number): number
259
+ if n < 10 then
260
+ return 1
261
+ elseif n < 100 then
262
+ return 2
263
+ elseif n < 1000 then
264
+ return 3
265
+ elseif n < 10000 then
266
+ return 4
267
+ elseif n < 100000 then
268
+ return 5
269
+ elseif n < 1000000 then
270
+ return 6
271
+ end
272
+ -- Past a million the comparison ladder stops paying for itself. %.0f prints
273
+ -- the double's exact integer value, so this stays exact rather than fitted.
274
+ return #string.format("%.0f", n)
275
+ end
276
+
277
+ local function jsonNumberBytes(v: number): number
278
+ if v ~= v or v == math.huge or v == -math.huge then
279
+ -- Not encodable at all; findUnpersistable rejects these separately, so
280
+ -- charge `null` and move on rather than inventing a size.
281
+ return 4
282
+ end
283
+ -- The encoder writes integral values in full decimal all the way to 1e20 and only
284
+ -- switches to exponent form at 1e21, so %.17g alone renders 1e20 as "1e+20" and
285
+ -- under-counts it by sixteen bytes.
286
+ if v % 1 == 0 and v > -1e21 and v < 1e21 then
287
+ local digits = decimalDigits(if v < 0 then -v else v)
288
+ return if v < 0 then digits + 1 else digits
289
+ end
290
+ return #string.format("%.17g", v)
291
+ end
292
+
293
+ -- Approximate serialized size in bytes, as an upper bound on what the DataStore would
294
+ -- store, which is the number the ~4 MB per-key ceiling is measured against. Buffer-aware
295
+ -- (DataStores store buffers as base64, 4/3 of their raw length rounded up to a 4-byte
296
+ -- group), so it works where JSONEncode would throw.
297
+ --
298
+ -- Upper bound rather than best guess: PROFILE_SIZE warns before saves start failing at the
299
+ -- ceiling, so an under-count is silent while an over-count only costs an early warning. It
300
+ -- never builds the string, and only array positions inside 1..#t are free: the encoder
301
+ -- writes {[123]="a"} as {"123":"a"} (hence Template.CoerceMapKeys), so a numeric key
302
+ -- outside the array part is charged like a string one.
303
+ function Util.approxSize(value: any, depth: number?): number
304
+ local d = depth or 0
305
+ local t = type(value)
306
+ if t == "string" then
307
+ return jsonStringBytes(value :: string)
308
+ elseif t == "number" then
309
+ return jsonNumberBytes(value :: number)
310
+ elseif t == "boolean" then
311
+ return if value then 4 else 5
312
+ elseif t == "buffer" then
313
+ return 4 * math.ceil(buffer.len(value :: buffer) / 3) + 2
314
+ elseif t == "table" then
315
+ -- This also measures live data from the raw-write boundaries, which can be cyclic,
316
+ -- and it runs unprotected on the save path, so a cycle here would kill the save
317
+ -- rather than fail it. Cap exactly where findUnpersistable does.
318
+ if d > 64 then
319
+ return 2
320
+ end
321
+ local arrayLength = #(value :: any)
322
+ local total, entries = 2, 0 -- {} / []
323
+ for k, v in value :: any do
324
+ entries += 1
325
+ if type(k) == "number" and k >= 1 and k <= arrayLength and k % 1 == 0 then
326
+ total += Util.approxSize(v, d + 1)
327
+ else
328
+ -- The key dispatch tests the key type rather than asserting it. Casting a
329
+ -- key to number here raises on a boolean or table key, and approxSize runs
330
+ -- inside a save-path Signal handler that swallows the raise, so the
331
+ -- PROFILE_SIZE warning silently stops firing. The 6 for an unencodable key
332
+ -- measures nothing (findUnpersistable reports it); what matters is that the
333
+ -- walk continues past it.
334
+ local kt = type(k)
335
+ local keyBytes = if kt == "string"
336
+ then jsonStringBytes(k :: string)
337
+ elseif kt == "number" then jsonNumberBytes(k :: number) + 2 -- quoted, as the encoder writes it
338
+ else 6
339
+ total += keyBytes + 1 + Util.approxSize(v, d + 1) -- + ':'
340
+ end
341
+ end
342
+ if entries > 1 then
343
+ total += entries - 1 -- separating commas, not one per entry
344
+ end
345
+ return total
346
+ end
347
+ return 4
348
+ end
349
+
350
+ local BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
351
+
352
+ -- Base64 for JSON exports of buffer fields.
353
+ function Util.base64FromBuffer(value: buffer): string
354
+ local length = buffer.len(value)
355
+ local out = table.create(math.ceil(length / 3))
356
+ local index = 0
357
+ while index < length do
358
+ local a = buffer.readu8(value, index)
359
+ local b = if index + 1 < length then buffer.readu8(value, index + 1) else 0
360
+ local c = if index + 2 < length then buffer.readu8(value, index + 2) else 0
361
+ local n = a * 65536 + b * 256 + c
362
+ local chunk = {
363
+ string.sub(BASE64, math.floor(n / 262144) % 64 + 1, math.floor(n / 262144) % 64 + 1),
364
+ string.sub(BASE64, math.floor(n / 4096) % 64 + 1, math.floor(n / 4096) % 64 + 1),
365
+ if index + 1 < length
366
+ then string.sub(BASE64, math.floor(n / 64) % 64 + 1, math.floor(n / 64) % 64 + 1)
367
+ else "=",
368
+ if index + 2 < length then string.sub(BASE64, n % 64 + 1, n % 64 + 1) else "=",
369
+ }
370
+ table.insert(out, table.concat(chunk))
371
+ index += 3
372
+ end
373
+ return table.concat(out)
374
+ end
375
+
376
+ function Util.guid(): string
377
+ return HttpService:GenerateGUID(false)
378
+ end
379
+
380
+ -- Byte equality for two buffers, for the array search accessors. Buffers compare by
381
+ -- identity under `==`, so a packed datatype in the store never equals a freshly packed
382
+ -- needle even when they hold the same value.
383
+ function Util.bufferEquals(a: buffer, b: buffer): boolean
384
+ local len = buffer.len(a)
385
+ if len ~= buffer.len(b) then
386
+ return false
387
+ end
388
+ local i = 0
389
+ while i + 4 <= len do
390
+ if buffer.readu32(a, i) ~= buffer.readu32(b, i) then
391
+ return false
392
+ end
393
+ i += 4
394
+ end
395
+ while i < len do
396
+ if buffer.readu8(a, i) ~= buffer.readu8(b, i) then
397
+ return false
398
+ end
399
+ i += 1
400
+ end
401
+ return true
402
+ end
403
+
404
+ -- Shallow equality for "did this leaf change" checks. Tables and buffers always count as
405
+ -- changes: both are mutable, so a re-Set of the same reference may carry in-place edits
406
+ -- that must replicate.
407
+ function Util.leafEquals(a: any, b: any): boolean
408
+ local t = type(a)
409
+ return a == b and t ~= "table" and t ~= "buffer"
410
+ end
411
+
412
+ -- table.concat that tolerates numeric segments.
413
+ function Util.pathKey(path: { string | number }): string
414
+ if #path == 0 then
415
+ return ""
416
+ end
417
+ local parts = table.create(#path)
418
+ for i, seg in path do
419
+ parts[i] = tostring(seg)
420
+ end
421
+ return table.concat(parts, "\31")
422
+ end
423
+
424
+ function Util.pathString(path: { string | number }): string
425
+ local parts = table.create(#path)
426
+ for i, seg in path do
427
+ parts[i] = tostring(seg)
428
+ end
429
+ return table.concat(parts, ".")
430
+ end
431
+
432
+ -- Split a dotted path string ("Attributes.Money") into segments.
433
+ function Util.parsePath(s: string): { string }
434
+ local out = {}
435
+ for seg in string.gmatch(s, "[^%.]+") do
436
+ table.insert(out, seg)
437
+ end
438
+ return out
439
+ end
440
+
441
+ -- Call `fn` through xpcall with a logged traceback; never throws. Returns ok plus
442
+ -- whatever `fn` returned.
443
+ function Util.safeCall(onError: (err: string) -> (), fn: (...any) -> ...any, ...: any): (boolean, ...any)
444
+ local args = table.pack(...)
445
+ local results: any
446
+ local traceback: string?
447
+ local ok = xpcall(function()
448
+ results = table.pack(fn(table.unpack(args, 1, args.n)))
449
+ end, function(e)
450
+ traceback = debug.traceback(tostring(e), 2)
451
+ end)
452
+ if not ok then
453
+ onError(tostring(traceback))
454
+ return false
455
+ end
456
+ return true, table.unpack(results, 1, results.n)
457
+ end
458
+
459
+ -- FNV-1a 32-bit hash over a string; used for the schema handshake checksum.
460
+ function Util.fnv32(s: string, seed: number?): number
461
+ local hash = seed or 2166136261
462
+ for i = 1, #s do
463
+ hash = bit32.bxor(hash, string.byte(s, i))
464
+ hash = bit32.band(hash * 16777619, 0xFFFFFFFF)
465
+ end
466
+ return hash
467
+ end
468
+
469
+ -- Sanitize a context table for logging: Instances become names, Players become
470
+ -- {UserId, Name}, depth-limited, JSON-safe.
471
+ function Util.sanitizeContext(context: any, depth: number?): any
472
+ local d = depth or 0
473
+ if d > 4 then
474
+ return "<deep>"
475
+ end
476
+ local t = typeof(context)
477
+ if t == "Instance" then
478
+ if context:IsA("Player") then
479
+ return { UserId = context.UserId, Name = context.Name }
480
+ end
481
+ return context:GetFullName()
482
+ elseif t == "table" then
483
+ local out = {}
484
+ for k, v in context do
485
+ out[tostring(k)] = Util.sanitizeContext(v, d + 1)
486
+ end
487
+ return out
488
+ elseif t == "string" or t == "number" or t == "boolean" or t == "nil" then
489
+ return context
490
+ end
491
+ return tostring(context)
492
+ end
493
+
494
+ --- The first missing index in what is meant to be a dense array, or nil. `#` cannot
495
+ --- answer this alone: it counts past a constructor hole (`{ "a", nil, "b" }` is 3) and
496
+ --- stops short of an assigned one (t[1], t[3] is 1), and iteration skips either. Named
497
+ --- keys are not gaps.
498
+ function Util.firstGap(list: { any }): number?
499
+ local count, highest = 0, 0
500
+ for key in list do
501
+ count += 1
502
+ if type(key) == "number" and key > highest then
503
+ highest = key
504
+ end
505
+ end
506
+ if count == highest then
507
+ return nil
508
+ end
509
+ for i = 1, highest do
510
+ if list[i] == nil then
511
+ return i
512
+ end
513
+ end
514
+ return nil
515
+ end
516
+
517
+ return Util
@@ -0,0 +1,4 @@
1
+ --!strict
2
+ -- Single source of truth for the release version. Keep wally.toml in sync.
3
+
4
+ return "2.5.0"