@rbxts/scribe 2.5.0 → 2.6.1

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/src/init.luau CHANGED
@@ -61,6 +61,32 @@ export type EconomyConfig = Types.EconomyConfig
61
61
  export type EconomyCurrencyConfig = Types.EconomyCurrencyConfig
62
62
  export type EconomyFieldSpec = Types.EconomyFieldSpec
63
63
  export type EconomyLogFn = Types.EconomyLogFn
64
+ export type PathSegment = Types.PathSegment
65
+ export type Path = Types.Path
66
+ export type OpKind = Types.OpKind
67
+ export type SessionState = Types.SessionState
68
+ export type Visibility = Types.Visibility
69
+ export type BigScore = Types.BigScore
70
+ export type Disconnect = Types.Disconnect
71
+ export type LogFilter = Log.LogFilter
72
+ export type Percentiles = Metrics.Percentiles
73
+ export type AddonAction = Addons.Action
74
+ export type AddonActions = Addons.Actions
75
+ --- Shared read methods for helpers and adapters.
76
+ export type ReadableNode<T> = {
77
+ --[[
78
+ Returns the current value.
79
+ ]]
80
+ read Get: () -> T,
81
+ --[[
82
+ Calls back immediately and on changes; returns a disconnect function.
83
+ ]]
84
+ read Observe: (callback: (value: T) -> ()) -> () -> (),
85
+ --[[
86
+ Calls back with new and previous values; returns a disconnect function.
87
+ ]]
88
+ read Changed: (callback: (value: T, previous: T) -> ()) -> () -> (),
89
+ }
64
90
  -- LeaderboardConfig<T>, ProductConfig<T> and PurchaseSpec<T> are defined after the
65
91
  -- type functions below, which they need to derive their paths from the template.
66
92
 
@@ -69,9 +95,44 @@ export type EconomyLogFn = Types.EconomyLogFn
69
95
  -- the recursive typed accessor tree.
70
96
  --------------------------------------------------------------------------------
71
97
 
98
+ -- Copy these small signatures to retain editor labels without changing node types.
99
+ type NodeFunctionNames = {
100
+ Listener: (callback: any) -> (),
101
+ Value: (value: any) -> (),
102
+ Change: (newValue: any, oldValue: any) -> (),
103
+ ChildChange: (key: any, newValue: any, oldValue: any) -> (),
104
+ IndexedValue: (value: any, index: any) -> (),
105
+ KeyValue: (key: any, value: any) -> (),
106
+ Set: (value: any, replicate: any) -> (),
107
+ Update: (callback: any, replicate: any) -> (),
108
+ Increment: (delta: any, tagsOrReplicate: any) -> (),
109
+ Insert: (value: any, index: any, replicate: any) -> (),
110
+ RemoveIndex: (index: any, replicate: any) -> (),
111
+ RemoveKey: (key: any, replicate: any) -> (),
112
+ Key: (key: any) -> (),
113
+ Flag: (name: any) -> (),
114
+ FlagWrite: (name: any, replicate: any) -> (),
115
+ Replicate: (replicate: any) -> (),
116
+ SetTimed: (value: any, seconds: any, replicate: any) -> (),
117
+ ExtendTimed: (seconds: any, replicate: any) -> (),
118
+ }
119
+
120
+ -- Read-only EconomyMeta fields accept tags declared in a local.
121
+ type AmountTags = {
122
+ read Flow: ("Source" | "Sink")?,
123
+ read TransactionType: (Enum.AnalyticsEconomyTransactionType | string)?,
124
+ read ItemSku: string?,
125
+ read Currency: string?,
126
+ read Fields: { [string]: any }?,
127
+ read Source: string?,
128
+ read Item: string?,
129
+ }
130
+
72
131
  -- selene: allow(undefined_variable) -- `types` is the type-function runtime library
73
- export type function ValueType(T)
132
+ -- "client" omits timer writes; "clientstore" omits all writes. Defaults to server.
133
+ type function BuildValueType(T, Names: type?, Mode: type?)
74
134
  local ts = types
135
+ local mode = if Mode ~= nil and Mode:is("singleton") then Mode:value() else nil
75
136
 
76
137
  local nilType = ts.singleton(nil)
77
138
 
@@ -82,8 +143,19 @@ export type function ValueType(T)
82
143
  local anyType = ts.any
83
144
  local optBool = optional(ts.boolean)
84
145
  local optNumber = optional(ts.number)
85
-
86
- local function fn(params: { type }, rets: { type }): type
146
+ -- Strings otherwise satisfy the all-optional tags shape through their metatable.
147
+ local amountOptions = optional(ts.unionof(ts.boolean, ts.intersectionof(AmountTags, ts.negationof(ts.string))))
148
+
149
+ local function fn(params: { type }, rets: { type }, name: string?): type
150
+ if name ~= nil and Names ~= nil then
151
+ local prototype = Names:readproperty(ts.singleton(name))
152
+ if prototype ~= nil then
153
+ local result = ts.copy(prototype)
154
+ result:setparameters(params)
155
+ result:setreturns(rets)
156
+ return result
157
+ end
158
+ end
87
159
  return ts.newfunction({ head = params }, { head = rets })
88
160
  end
89
161
 
@@ -162,8 +234,7 @@ export type function ValueType(T)
162
234
  return big
163
235
  end
164
236
 
165
- -- Big, Flags and SetOf carry their label in the metatable rather than in a field,
166
- -- so each declarator's own type is already the read shape. See BigValue.
237
+ -- Big, Flags and SetOf carry their brands in the metatable.
167
238
  local function hasMarker(t: type, name: string): boolean
168
239
  local mt = t:metatable()
169
240
  return mt ~= nil and mt:readproperty(ts.singleton(name)) ~= nil
@@ -203,9 +274,30 @@ export type function ValueType(T)
203
274
  return out
204
275
  end
205
276
 
277
+ -- Unwrap Optional(ServerOnly(x)); leave other unions alone.
278
+ local function optionalServerOnly(t: type): type?
279
+ local marked: type? = nil
280
+ for _, member in t:components() do
281
+ local inner = if member:is("table") then member:readproperty(ts.singleton("__scribeServerOnly")) else nil
282
+ if inner ~= nil then
283
+ marked = inner
284
+ elseif not member:is("nil") then
285
+ return nil
286
+ end
287
+ end
288
+ return marked
289
+ end
290
+
206
291
  local unwrapCache: { [type]: type } = {}
207
292
  local function unwrapWrappers(t: type, depth: number): type
208
- if depth > MAX_DEPTH or not t:is("table") then
293
+ if depth > MAX_DEPTH then
294
+ return t
295
+ end
296
+ if t:is("union") then
297
+ local inner = optionalServerOnly(t)
298
+ return if inner ~= nil then optional(unwrapWrappers(widen(inner), depth + 1)) else t
299
+ end
300
+ if not t:is("table") then
209
301
  return t
210
302
  end
211
303
  local cached = unwrapCache[t]
@@ -228,9 +320,8 @@ export type function ValueType(T)
228
320
  if derived ~= nil then
229
321
  return memo(unwrapWrappers(widen(derived), depth + 1))
230
322
  end
231
- -- A marker cannot hide under one of the branded declarators: their metatable
232
- -- brand means the shape below them is already the read shape.
233
- if hasMarker(t, "__scribeBig") or hasMarker(t, "__scribeFlags") or hasMarker(t, "__scribeSet") then
323
+ -- Big and Flags already have read shapes; set elements may still contain markers.
324
+ if hasMarker(t, "__scribeBig") or hasMarker(t, "__scribeFlags") then
234
325
  return memo(t)
235
326
  end
236
327
  local props: { [type]: type } = {}
@@ -257,7 +348,8 @@ export type function ValueType(T)
257
348
  if not rebuilt then
258
349
  return memo(t)
259
350
  end
260
- return memo(ts.newtable(props, spec, nil))
351
+ -- Preserve set and map brands.
352
+ return memo(ts.newtable(props, spec, t:metatable()))
261
353
  end
262
354
 
263
355
  -- A canonical key for a subtree, so two identical subtrees are built once. A template
@@ -379,6 +471,12 @@ export type function ValueType(T)
379
471
  if inner ~= nil then
380
472
  t = widen(inner)
381
473
  end
474
+ elseif t:is("union") then
475
+ -- Scribe.Optional(Scribe.ServerOnly(x)): the node is x?.
476
+ local inner = optionalServerOnly(t)
477
+ if inner ~= nil then
478
+ t = optional(widen(inner))
479
+ end
382
480
  end
383
481
 
384
482
  -- A Scribe.Derived node reads as V and never writes, so this only records the
@@ -418,6 +516,9 @@ export type function ValueType(T)
418
516
  -- index-based Remove, neither of which a set has. `t` is already the members.
419
517
  local isSet = t:is("table") and hasMarker(t, "__scribeSet")
420
518
 
519
+ -- Derived fields and client stores are read-only.
520
+ local writable = not isDerived and mode ~= "clientstore"
521
+
421
522
  -- Second ServerOnly unwrap, for a marker nested inside another declarator
422
523
  -- rather than wrapped around one. The server reads these normally;
423
524
  -- StripServerOnly is what drops them from the client type.
@@ -440,7 +541,7 @@ export type function ValueType(T)
440
541
  if indexer ~= nil then
441
542
  mapKey = indexer.index
442
543
  mapValue = indexer.readresult
443
- mapElement = widen(indexer.readresult)
544
+ mapElement = unwrapWrappers(widen(indexer.readresult), depth + 1)
444
545
  end
445
546
  end
446
547
 
@@ -467,7 +568,7 @@ export type function ValueType(T)
467
568
  if childType ~= nil then
468
569
  local childNode = build(childType, false, depth + 1)
469
570
  table.insert(props, { key = key, ty = childNode })
470
- table.insert(childLookups, fn({ key }, { childNode }))
571
+ table.insert(childLookups, fn({ key }, { childNode }, "Key"))
471
572
  end
472
573
  end
473
574
 
@@ -479,51 +580,70 @@ export type function ValueType(T)
479
580
  local childType = prop.read or prop.write
480
581
  if childType ~= nil then
481
582
  table.insert(childKeys, key)
482
- table.insert(childValues, widen(childType))
583
+ table.insert(childValues, unwrapWrappers(widen(childType), depth + 1))
483
584
  end
484
585
  end
485
586
 
486
587
  local indexer = t:indexer()
487
588
  if indexer ~= nil then
488
- local elementType = widen(indexer.readresult)
589
+ -- Read values exclude nested markers.
590
+ local elementType = unwrapWrappers(widen(indexer.readresult), depth + 1)
489
591
  local elementIn = readOnlyDeep(elementType, depth + 1)
490
592
  if indexer.index:is("number") then
491
593
  -- Array node: the indexer makes `arr[i]` an accessor node, which is
492
594
  -- the only way to reach a Scribe.ArrayOf element field.
493
595
  local elemNode = build(indexer.readresult, false, depth + 1)
494
- table.insert(childLookups, fn({ indexer.index }, { elemNode }))
596
+ table.insert(childLookups, fn({ indexer.index }, { elemNode }, "Key"))
495
597
  indexerSpec = {
496
598
  index = indexer.index,
497
599
  readresult = elemNode,
498
600
  writeresult = elemNode,
499
601
  }
500
- add("Insert", fn({ elementIn, optNumber, optBool }, {}))
501
- -- Remove returns nil on an empty/missing array (matches RemoveValue).
502
- add("Remove", fn({ optNumber, optBool }, { optional(elementType) }))
503
- add("RemoveValue", fn({ elementIn, optBool }, { optional(elementType), optNumber }))
504
- add("Find", fn({ elementIn }, { optNumber }))
505
- add("Has", fn({ elementIn }, { ts.boolean }))
506
- add("OnInsert", fn({ fn({ elementType, ts.number }, {}) }, { disconnectType }))
507
- add("OnRemove", fn({ fn({ elementType, ts.number }, {}) }, { disconnectType }))
602
+ if writable then
603
+ add("Insert", fn({ elementIn, optNumber, optBool }, {}, "Insert"))
604
+ -- Remove returns nil on an empty/missing array (matches RemoveValue).
605
+ add("Remove", fn({ optNumber, optBool }, { optional(elementType) }, "RemoveIndex"))
606
+ add("RemoveValue", fn({ elementIn, optBool }, { optional(elementType), optNumber }, "Set"))
607
+ end
608
+ add("Find", fn({ elementIn }, { optNumber }, "Value"))
609
+ add("Has", fn({ elementIn }, { ts.boolean }, "Value"))
610
+ add(
611
+ "OnInsert",
612
+ fn({ fn({ elementType, ts.number }, {}, "IndexedValue") }, { disconnectType }, "Listener")
613
+ )
614
+ add(
615
+ "OnRemove",
616
+ fn({ fn({ elementType, ts.number }, {}, "IndexedValue") }, { disconnectType }, "Listener")
617
+ )
508
618
  else
509
619
  -- Dictionary node: children are accessor nodes.
510
620
  local childNode = build(indexer.readresult, false, depth + 1)
511
- table.insert(childLookups, fn({ indexer.index }, { childNode }))
621
+ table.insert(childLookups, fn({ indexer.index }, { childNode }, "Key"))
512
622
  indexerSpec = {
513
623
  index = indexer.index,
514
624
  readresult = childNode,
515
625
  writeresult = childNode,
516
626
  }
517
- add("Remove", fn({ ts.string, optBool }, { optional(elementType) }))
518
- add("OnKeyAdded", fn({ fn({ indexer.index, elementType }, {}) }, { disconnectType }))
519
- add("OnKeyRemoved", fn({ fn({ indexer.index, elementType }, {}) }, { disconnectType }))
627
+ if writable then
628
+ add("Remove", fn({ ts.string, optBool }, { optional(elementType) }, "RemoveKey"))
629
+ end
630
+ add(
631
+ "OnKeyAdded",
632
+ fn({ fn({ indexer.index, elementType }, {}, "KeyValue") }, { disconnectType }, "Listener")
633
+ )
634
+ add(
635
+ "OnKeyRemoved",
636
+ fn({ fn({ indexer.index, elementType }, {}, "KeyValue") }, { disconnectType }, "Listener")
637
+ )
638
+ end
639
+ if writable then
640
+ add("Clear", fn({ optBool }, {}, "Replicate"))
520
641
  end
521
- add("Clear", fn({ optBool }, {}))
522
642
  add("Count", fn({}, { ts.number }))
523
643
  -- A dynamic container's children are homogeneous, so the key and value
524
644
  -- types here are exact rather than a union over declared fields.
525
645
  table.insert(childKeys, indexer.index)
526
- table.insert(childValues, widen(indexer.readresult))
646
+ table.insert(childValues, elementType)
527
647
  end
528
648
 
529
649
  if #childKeys > 0 then
@@ -536,7 +656,10 @@ export type function ValueType(T)
536
656
  local childValue = if #childValues > MAX_CHILD_UNION
537
657
  then optional(anyType)
538
658
  else optional(ts.unionof(table.unpack(childValues)))
539
- add("OnChildChanged", fn({ fn({ childKey, childValue, childValue }, {}) }, { disconnectType }))
659
+ add(
660
+ "OnChildChanged",
661
+ fn({ fn({ childKey, childValue, childValue }, {}, "ChildChange") }, { disconnectType }, "Listener")
662
+ )
540
663
  end
541
664
  end
542
665
 
@@ -545,13 +668,24 @@ export type function ValueType(T)
545
668
  -- events and Remove carry the element rather than the whole map.
546
669
  local element = mapElement :: type
547
670
  local childNode = build(mapValue :: type, false, depth + 1)
548
- table.insert(childLookups, fn({ mapKey }, { childNode }))
671
+ table.insert(childLookups, fn({ mapKey }, { childNode }, "Key"))
549
672
  indexerSpec = { index = mapKey, readresult = childNode, writeresult = childNode }
550
- add("Remove", fn({ mapKey, optBool }, { optional(element) }))
551
- add("OnKeyAdded", fn({ fn({ mapKey, element }, {}) }, { disconnectType }))
552
- add("OnKeyRemoved", fn({ fn({ mapKey, element }, {}) }, { disconnectType }))
553
- add("OnChildChanged", fn({ fn({ mapKey, optional(element), optional(element) }, {}) }, { disconnectType }))
554
- add("Clear", fn({ optBool }, {}))
673
+ if writable then
674
+ add("Remove", fn({ mapKey, optBool }, { optional(element) }, "RemoveKey"))
675
+ end
676
+ add("OnKeyAdded", fn({ fn({ mapKey, element }, {}, "KeyValue") }, { disconnectType }, "Listener"))
677
+ add("OnKeyRemoved", fn({ fn({ mapKey, element }, {}, "KeyValue") }, { disconnectType }, "Listener"))
678
+ add(
679
+ "OnChildChanged",
680
+ fn(
681
+ { fn({ mapKey, optional(element), optional(element) }, {}, "ChildChange") },
682
+ { disconnectType },
683
+ "Listener"
684
+ )
685
+ )
686
+ if writable then
687
+ add("Clear", fn({ optBool }, {}, "Replicate"))
688
+ end
555
689
  add("Count", fn({}, { ts.number }))
556
690
  end
557
691
 
@@ -562,7 +696,7 @@ export type function ValueType(T)
562
696
  if #childLookups == 1 then
563
697
  add("Child", childLookups[1])
564
698
  elseif #childLookups > 1 then
565
- add("Child", fn({ ts.unionof(ts.string, ts.number) }, { anyType }))
699
+ add("Child", fn({ ts.unionof(ts.string, ts.number) }, { anyType }, "Key"))
566
700
  end
567
701
 
568
702
  -- Common node methods.
@@ -570,7 +704,7 @@ export type function ValueType(T)
570
704
  -- The root accessor cannot be Set or Updated at runtime, so those are left off the
571
705
  -- root type. A big field declares its own wider Set and Update below; adding them
572
706
  -- here too would duplicate rather than override, as the singletons are distinct keys.
573
- if not isRoot and not isBig and not isDerived then
707
+ if not isRoot and not isBig and writable then
574
708
  -- Writes take the unbranded shape: a caller writing a plain table literal
575
709
  -- has no way to produce a map's metatable brand. Reads still hand back the
576
710
  -- branded type, which assigns freely to the plain shape.
@@ -578,39 +712,57 @@ export type function ValueType(T)
578
712
  then ts.newtable(nil, { index = mapKey, readresult = mapElement, writeresult = mapElement }, nil)
579
713
  else valueType
580
714
  local writeIn = if mapKey ~= nil then writeType else readOnlyDeep(writeType, depth + 1)
581
- add("Set", fn({ writeIn, optBool }, { valueType }))
582
- add("Update", fn({ fn({ valueType }, { writeIn }), optBool }, { valueType }))
715
+ add("Set", fn({ writeIn, optBool }, { valueType }, "Set"))
716
+ add("Update", fn({ fn({ valueType }, { writeIn }, "Value"), optBool }, { valueType }, "Update"))
583
717
  end
584
718
  add("Clone", fn({}, { valueType }))
585
719
  add("Default", fn({}, { valueType }))
586
720
  -- (new, old) on every node. On a container it reports state, coalesced to one
587
721
  -- fire per batch or received frame; which child moved is OnChildChanged's job.
588
- add("Changed", fn({ fn({ valueType, valueType }, {}) }, { disconnectType }))
589
- add("Observe", fn({ fn({ valueType }, {}) }, { disconnectType }))
722
+ add("Changed", fn({ fn({ valueType, valueType }, {}, "Change") }, { disconnectType }, "Listener"))
723
+ add("Observe", fn({ fn({ valueType }, {}, "Value") }, { disconnectType }, "Listener"))
724
+
725
+ -- Optional numbers and booleans keep their methods; Big exceeds the type budget.
726
+ local scalar = t
727
+ if t:is("union") then
728
+ local inner: type? = nil
729
+ local members = 0
730
+ for _, member in t:components() do
731
+ if not member:is("nil") then
732
+ members += 1
733
+ inner = member
734
+ end
735
+ end
736
+ if members == 1 and inner ~= nil and (inner:is("number") or inner:is("boolean")) then
737
+ scalar = inner
738
+ end
739
+ end
590
740
 
591
- if t:is("number") then
741
+ if scalar:is("number") then
592
742
  -- Min/Max read the declared bounds, so they stay on a derived field; the
593
743
  -- two mutators do not.
594
- if not isDerived then
595
- add("Increment", fn({ ts.number, anyType }, { ts.number }))
596
- add("Decrement", fn({ ts.number, anyType }, { ts.number }))
744
+ if writable then
745
+ add("Increment", fn({ ts.number, amountOptions }, { ts.number }, "Increment"))
746
+ add("Decrement", fn({ ts.number, amountOptions }, { ts.number }, "Increment"))
597
747
  end
598
748
  add("Min", fn({}, { optNumber }))
599
749
  add("Max", fn({}, { optNumber }))
600
- elseif t:is("boolean") and not isDerived then
601
- add("Toggle", fn({ optBool }, { ts.boolean }))
750
+ elseif scalar:is("boolean") and writable then
751
+ add("Toggle", fn({ optBool }, { ts.boolean }, "Replicate"))
602
752
  end
603
753
 
604
754
  if isBig then
605
755
  -- Every entry point, Set included, takes a number, a numeric string, or
606
756
  -- another big value, so the operand type is the same union everywhere.
607
- local operand = ts.unionof(ts.number, ts.string, valueType)
608
- add("Set", fn({ operand, optBool }, { valueType }))
609
- add("Update", fn({ fn({ valueType }, { operand }), optBool }, { valueType }))
610
- add("Increment", fn({ operand, anyType }, { valueType }))
611
- add("Decrement", fn({ operand, anyType }, { valueType }))
612
- add("Multiply", fn({ operand, optBool }, { valueType }))
613
- add("Divide", fn({ operand, optBool }, { valueType }))
757
+ if writable then
758
+ local operand = ts.unionof(ts.number, ts.string, valueType)
759
+ add("Set", fn({ operand, optBool }, { valueType }, "Set"))
760
+ add("Update", fn({ fn({ valueType }, { operand }, "Value"), optBool }, { valueType }, "Update"))
761
+ add("Increment", fn({ operand, amountOptions }, { valueType }, "Increment"))
762
+ add("Decrement", fn({ operand, amountOptions }, { valueType }, "Increment"))
763
+ add("Multiply", fn({ operand, optBool }, { valueType }, "Set"))
764
+ add("Divide", fn({ operand, optBool }, { valueType }, "Set"))
765
+ end
614
766
  -- A big bound past the double range is only expressible as a numeric string,
615
767
  -- so these return the same union the declarator accepts.
616
768
  local optBound = optional(ts.unionof(ts.number, ts.string))
@@ -619,29 +771,39 @@ export type function ValueType(T)
619
771
  end
620
772
 
621
773
  if isSet then
622
- -- Membership surface. Get/Set still take the whole { T }.
774
+ -- Membership uses unwrapped elements; Get/Set use the whole set.
623
775
  local setIndexer = t:indexer()
624
- local element = if setIndexer ~= nil then widen(setIndexer.readresult) else anyType
776
+ local element = if setIndexer ~= nil
777
+ then unwrapWrappers(widen(setIndexer.readresult), depth + 1)
778
+ else anyType
625
779
  local elementIn = readOnlyDeep(element, depth + 1)
626
- add("Add", fn({ elementIn, optBool }, { ts.boolean }))
627
- add("Remove", fn({ elementIn, optBool }, { ts.boolean }))
628
- add("Has", fn({ elementIn }, { ts.boolean }))
780
+ if writable then
781
+ add("Add", fn({ elementIn, optBool }, { ts.boolean }, "Set"))
782
+ add("Remove", fn({ elementIn, optBool }, { ts.boolean }, "Set"))
783
+ add("Clear", fn({ optBool }, {}, "Replicate"))
784
+ end
785
+ add("Has", fn({ elementIn }, { ts.boolean }, "Value"))
786
+ add("Find", fn({ elementIn }, { optNumber }, "Value"))
629
787
  add("Count", fn({}, { ts.number }))
630
- add("Clear", fn({ optBool }, {}))
631
788
  end
632
789
 
633
790
  if isFlags then
634
791
  -- Named-member surface. Get/Set still take the whole { string } set.
635
- add("Enable", fn({ ts.string, optBool }, {}))
636
- add("Disable", fn({ ts.string, optBool }, {}))
637
- add("Has", fn({ ts.string }, { ts.boolean }))
638
- add("Toggle", fn({ ts.string, optBool }, { ts.boolean }))
639
- add("Clear", fn({ optBool }, {}))
792
+ if writable then
793
+ add("Enable", fn({ ts.string, optBool }, {}, "FlagWrite"))
794
+ add("Disable", fn({ ts.string, optBool }, {}, "FlagWrite"))
795
+ add("Toggle", fn({ ts.string, optBool }, { ts.boolean }, "FlagWrite"))
796
+ add("Clear", fn({ optBool }, {}, "Replicate"))
797
+ end
798
+ add("Has", fn({ ts.string }, { ts.boolean }, "Flag"))
640
799
  end
641
800
 
642
801
  if isTimed then
643
- add("SetTimed", fn({ valueType, ts.number, optBool }, {}))
644
- add("ExtendTimed", fn({ ts.number, optBool }, {}))
802
+ -- Only the server changes deadlines.
803
+ if writable and mode ~= "client" then
804
+ add("SetTimed", fn({ valueType, ts.number, optBool }, {}, "SetTimed"))
805
+ add("ExtendTimed", fn({ ts.number, optBool }, {}, "ExtendTimed"))
806
+ end
645
807
  add("Active", fn({}, { ts.boolean, optNumber }))
646
808
  end
647
809
 
@@ -658,6 +820,12 @@ export type function ValueType(T)
658
820
  return build(T, true, 0)
659
821
  end
660
822
 
823
+ -- Keep the original type-function arity for existing callers.
824
+ -- selene: allow(undefined_variable)
825
+ export type function ValueType(T)
826
+ return BuildValueType(T, nil)
827
+ end
828
+
661
829
  -- Union of every static rankable leaf path in the template, dot-joined ("Coins",
662
830
  -- "Stats.Wins"), for leaderboard `Stat` and purchase cost paths. Dynamic segments cannot
663
831
  -- be enumerated at type level, so those paths must be cast to `any`; falls back to plain
@@ -682,6 +850,7 @@ export type function StatPathsType(T: type, IncludeBig: type?): type
682
850
  return hasMarker(t, "__scribeMapKey")
683
851
  end
684
852
 
853
+ local WRAPPERS = { "__scribeTimed", "__scribeServerOnly", "__scribeDerived" }
685
854
  local paths: { type } = {}
686
855
 
687
856
  local function widen(t: type): type
@@ -701,28 +870,21 @@ export type function StatPathsType(T: type, IncludeBig: type?): type
701
870
  return
702
871
  end
703
872
  local t = widen(rawType)
704
- if t:is("table") then
705
- -- Unwrap the Scribe.Timed marker; its inner value is the leaf.
706
- local inner = t:readproperty(ts.singleton("__scribeTimed"))
707
- if inner ~= nil then
708
- t = widen(inner)
709
- end
710
- end
711
- if t:is("table") then
712
- -- Same for Scribe.ServerOnly: the server is what reads leaderboard
713
- -- stats, so a server-only number is still a valid stat path.
714
- local serverOnly = t:readproperty(ts.singleton("__scribeServerOnly"))
715
- if serverOnly ~= nil then
716
- t = widen(serverOnly)
873
+ -- Unwrap markers to find server-only and derived leaderboard stats.
874
+ for _ = 1, 8 do
875
+ local inner: type? = nil
876
+ if t:is("table") then
877
+ for _, label in WRAPPERS do
878
+ inner = t:readproperty(ts.singleton(label))
879
+ if inner ~= nil then
880
+ break
881
+ end
882
+ end
717
883
  end
718
- end
719
- if t:is("table") then
720
- -- And Scribe.Derived: a board reads its stat through the accessor tree,
721
- -- which computes derived fields, so a derived number is a valid stat.
722
- local derived = t:readproperty(ts.singleton("__scribeDerived"))
723
- if derived ~= nil then
724
- t = widen(derived)
884
+ if inner == nil then
885
+ break
725
886
  end
887
+ t = widen(inner)
726
888
  end
727
889
  if t:is("table") and isMapMarker(t) then
728
890
  -- A map's entries live under dynamic keys, which cannot be enumerated at type
@@ -783,8 +945,38 @@ type function StripServerOnly(T)
783
945
  -- Matches ValueType's budget: a cyclic template must not blow the stack.
784
946
  local MAX_DEPTH = 25
785
947
 
948
+ -- ServerOnly still applies inside Timed, Derived or Optional.
786
949
  local function isServerOnly(t: type): boolean
787
- return t:is("table") and t:readproperty(MARKER) ~= nil
950
+ for _ = 1, 8 do
951
+ if t:is("union") then
952
+ local inner: type? = nil
953
+ local members = 0
954
+ for _, member in t:components() do
955
+ if not member:is("nil") then
956
+ members += 1
957
+ inner = member
958
+ end
959
+ end
960
+ if members == 1 and inner ~= nil then
961
+ t = inner
962
+ else
963
+ return false
964
+ end
965
+ end
966
+ if not t:is("table") then
967
+ return false
968
+ end
969
+ if t:readproperty(MARKER) ~= nil then
970
+ return true
971
+ end
972
+ local inner = t:readproperty(ts.singleton("__scribeTimed"))
973
+ or t:readproperty(ts.singleton("__scribeDerived"))
974
+ if inner == nil then
975
+ return false
976
+ end
977
+ t = inner
978
+ end
979
+ return false
788
980
  end
789
981
 
790
982
  local function strip(t: type, depth: number): type
@@ -802,11 +994,10 @@ type function StripServerOnly(T)
802
994
  end
803
995
  end
804
996
  end
805
- -- Element shapes live behind the indexer, not in properties: without this a
806
- -- ServerOnly field inside an ArrayOf or DictOf entry stays in the client type.
997
+ -- Strip hidden fields inside elements; wholly hidden elements become never.
807
998
  local indexer = t:indexer()
808
999
  if indexer ~= nil then
809
- local element = strip(indexer.readresult, depth + 1)
1000
+ local element = if isServerOnly(indexer.readresult) then ts.never else strip(indexer.readresult, depth + 1)
810
1001
  out:setindexer(indexer.index, element)
811
1002
  end
812
1003
  return out
@@ -818,16 +1009,89 @@ end
818
1009
  -- Grant callbacks receive the typed accessor tree when a template type is supplied,
819
1010
  -- and stay `any` for the untyped default so un-annotated configs stay clean.
820
1011
  -- selene: allow(undefined_variable)
821
- export type function GrantDataType(T)
1012
+ type function BuildGrantDataType(T, Names: type?)
822
1013
  if T:is("any") or T:is("unknown") then
823
1014
  return types.any
824
1015
  end
825
- return ValueType(T)
1016
+ return BuildValueType(T, Names)
826
1017
  end
827
1018
 
1019
+ -- selene: allow(undefined_variable)
1020
+ export type function GrantDataType(T)
1021
+ return BuildGrantDataType(T, nil)
1022
+ end
1023
+
1024
+ -- Copy parameter names into API signatures, as with NodeFunctionNames.
1025
+ type ServerApiNames = {
1026
+ Get: (player: any) -> (),
1027
+ WaitForData: (player: any, timeout: any) -> (),
1028
+ GetState: (player: any) -> (),
1029
+ Batch: (player: any, fn: any) -> (),
1030
+ Transaction: (player: any, fn: any) -> (),
1031
+ Flush: (player: any, options: any) -> (),
1032
+ GetSaveInfo: (player: any) -> (),
1033
+ GetOffline: (userId: any) -> (),
1034
+ UpdateOffline: (userId: any, fn: any, options: any) -> (),
1035
+ ListVersions: (userId: any, limit: any) -> (),
1036
+ GetVersion: (userId: any, versionId: any) -> (),
1037
+ RestoreVersion: (userId: any, versionId: any, options: any) -> (),
1038
+ Command: (name: any, specOrHandler: any, handler: any) -> (),
1039
+ GetLeaderboard: (name: any, limit: any, offset: any) -> (),
1040
+ GetMyRank: (player: any, name: any) -> (),
1041
+ GetLeaderboardRefreshIn: (name: any) -> (),
1042
+ GetLeaderboardStatus: (name: any) -> (),
1043
+ GetLeaderboardResetIn: (name: any) -> (),
1044
+ PromptGift: (buyer: any, productName: any, recipientUserId: any) -> (),
1045
+ PromptPurchase: (player: any, name: any) -> (),
1046
+ GetProductState: (player: any, name: any) -> (),
1047
+ GetGiftCredits: (player: any) -> (),
1048
+ HandleReceipt: (receiptInfo: any) -> (),
1049
+ TryHandleReceipt: (receiptInfo: any) -> (),
1050
+ Owns: (player: any, key: any) -> (),
1051
+ OwnsAsync: (player: any, key: any, timeout: any) -> (),
1052
+ ObserveOwned: (player: any, key: any, callback: any) -> (),
1053
+ GrantPerk: (player: any, key: any) -> (),
1054
+ RevokePerk: (player: any, key: any) -> (),
1055
+ Purchase: (player: any, spec: any) -> (),
1056
+ RecordPurchase: (player: any, entry: any) -> (),
1057
+ GetPurchases: (player: any, filter: any) -> (),
1058
+ OnCooldown: (player: any, key: any, seconds: any, options: any) -> (),
1059
+ PeekCooldown: (player: any, key: any) -> (),
1060
+ ClearCooldown: (player: any, key: any) -> (),
1061
+ Erase: (userId: any) -> (),
1062
+ Export: (userId: any) -> (),
1063
+ SendMessage: (userId: any, message: any) -> (),
1064
+ }
1065
+
1066
+ type ClientApiNames = {
1067
+ WaitForData: (timeout: any) -> (),
1068
+ Batch: (fn: any) -> (),
1069
+ Request: (name: any, ...any) -> (),
1070
+ RequestOnce: (name: any, key: any, ...any) -> (),
1071
+ GetLeaderboard: (name: any, limit: any) -> (),
1072
+ GetMyRank: (name: any) -> (),
1073
+ GetShared: (playerOrUserId: any) -> (),
1074
+ Owns: (key: any) -> (),
1075
+ OwnsAsync: (key: any, timeout: any) -> (),
1076
+ ObserveOwned: (key: any, callback: any) -> (),
1077
+ GetPurchases: (filter: any) -> (),
1078
+ GetProductInfo: (name: any) -> (),
1079
+ GetPrice: (name: any) -> (),
1080
+ GetProductInfoAsync: (name: any, timeout: any) -> (),
1081
+ GetPriceAsync: (name: any, timeout: any) -> (),
1082
+ ObserveProductInfo: (name: any, callback: any) -> (),
1083
+ PromptPurchase: (name: any) -> (),
1084
+ GetProductState: (name: any) -> (),
1085
+ ObserveProductState: (name: any, callback: any) -> (),
1086
+ PrefetchProductInfo: (names: any) -> (),
1087
+ RefreshProductInfo: (name: any) -> (),
1088
+ Mock: (values: any, scribeState: any) -> (),
1089
+ MockCommand: (name: any, handler: any) -> (),
1090
+ }
1091
+
828
1092
  -- Store proxies expose declared roots, without the root accessor's methods.
829
1093
  -- selene: allow(undefined_variable)
830
- type function StoreDataType(S: type): type
1094
+ type function StoreDataType(S: type, Names: type?, Mode: type?): type
831
1095
  local ts = types
832
1096
  if not S:is("table") then
833
1097
  return ts.any
@@ -846,7 +1110,7 @@ type function StoreDataType(S: type): type
846
1110
  names[key] = alias
847
1111
  end
848
1112
  end
849
- local nodes = ValueType(fields)
1113
+ local nodes = BuildValueType(fields, Names, Mode)
850
1114
  local roots = ts.newtable(nil, nodes:indexer(), nil)
851
1115
  for key, alias in names do
852
1116
  roots:setproperty(key, nodes:readproperty(alias))
@@ -858,7 +1122,7 @@ end
858
1122
  -- rather than `ValueType<T> & { ... }`, because normalizing an intersection over a
859
1123
  -- large accessor tree exceeds the solver's budget at the Scribe() call site.
860
1124
  -- selene: allow(undefined_variable)
861
- type function BuildClientDataType(T, S)
1125
+ type function BuildClientDataType(T, S, Names: type?)
862
1126
  local ts = types
863
1127
 
864
1128
  local function optional(t: type): type
@@ -903,9 +1167,18 @@ type function BuildClientDataType(T, S)
903
1167
  saveInfoProps[ts.singleton("Size")] = optional(ts.number)
904
1168
  local saveInfo = ts.newtable(saveInfoProps, nil, nil)
905
1169
 
906
- local out = ts.copy(ValueType(StripServerOnly(T)))
1170
+ local out = ts.copy(BuildValueType(StripServerOnly(T), Names, ts.singleton("client")))
1171
+ -- Read-only members avoid invariant type comparisons.
907
1172
  local function add(name: string, ty: type)
908
- out:setproperty(ts.singleton(name), ty)
1173
+ local prototype = if ty:is("function") then ClientApiNames:readproperty(ts.singleton(name)) else nil
1174
+ if prototype ~= nil then
1175
+ local named = ts.copy(prototype)
1176
+ local params, rets = ty:parameters(), ty:returns()
1177
+ named:setparameters(params.head, params.tail)
1178
+ named:setreturns(rets.head, rets.tail)
1179
+ ty = named
1180
+ end
1181
+ out:setreadproperty(ts.singleton(name), ty)
909
1182
  end
910
1183
 
911
1184
  add("IsReady", fn({}, { ts.boolean }))
@@ -954,24 +1227,24 @@ type function BuildClientDataType(T, S)
954
1227
  ts.newfunction({ head = { ts.string, ts.newfunction({ tail = ts.any }, { tail = ts.any }) } }, { head = {} })
955
1228
  )
956
1229
  add("Raw", ts.any)
957
- add("ServerStore", StoreDataType(StripServerOnly(S)))
1230
+ add("ServerStore", StoreDataType(StripServerOnly(S), Names, ts.singleton("clientstore")))
958
1231
 
959
1232
  return out
960
1233
  end
961
1234
 
962
1235
  -- selene: allow(undefined_variable)
963
1236
  export type function ClientDataType(T)
964
- return BuildClientDataType(T, types.any)
1237
+ return BuildClientDataType(T, types.any, nil)
965
1238
  end
966
1239
 
967
1240
  -- The server `Data` API. P is the Player class type, passed in as a type argument
968
1241
  -- because class types are not constructible inside a type function. A type function
969
1242
  -- for the same complexity-budget reason as ClientDataType.
970
1243
  -- selene: allow(undefined_variable)
971
- type function BuildServerDataType(T, P, S)
1244
+ type function BuildServerDataType(T, P, S, Names: type?)
972
1245
  local ts = types
973
1246
 
974
- local node = ValueType(T)
1247
+ local node = BuildValueType(T, Names)
975
1248
 
976
1249
  local function optional(t: type): type
977
1250
  return ts.unionof(t, ts.singleton(nil))
@@ -1002,7 +1275,8 @@ type function BuildServerDataType(T, P, S)
1002
1275
  )
1003
1276
  bigScoreProps[ts.singleton("ToNumber")] = ts.newfunction({ head = { ts.any } }, { head = { ts.number } })
1004
1277
  bigScoreProps[ts.singleton("Log10")] = ts.newfunction({ head = { ts.any } }, { head = { ts.number } })
1005
- entryProps[ts.singleton("Score")] = ts.unionof(ts.number, ts.newtable(bigScoreProps, nil, nil))
1278
+ local bigScore = ts.newtable(bigScoreProps, nil, nil)
1279
+ entryProps[ts.singleton("Score")] = ts.unionof(ts.number, bigScore)
1006
1280
  local leaderboardEntry = ts.newtable(entryProps, nil, nil)
1007
1281
  local entryArray =
1008
1282
  ts.newtable(nil, { index = ts.number, readresult = leaderboardEntry, writeresult = leaderboardEntry }, nil)
@@ -1046,6 +1320,14 @@ type function BuildServerDataType(T, P, S)
1046
1320
 
1047
1321
  local props: { [type]: type } = {}
1048
1322
  local function add(name: string, ty: type)
1323
+ local prototype = if ty:is("function") then ServerApiNames:readproperty(ts.singleton(name)) else nil
1324
+ if prototype ~= nil then
1325
+ local named = ts.copy(prototype)
1326
+ local params, rets = ty:parameters(), ty:returns()
1327
+ named:setparameters(params.head, params.tail)
1328
+ named:setreturns(rets.head, rets.tail)
1329
+ ty = named
1330
+ end
1049
1331
  props[ts.singleton(name)] = ty
1050
1332
  end
1051
1333
 
@@ -1135,16 +1417,18 @@ type function BuildServerDataType(T, P, S)
1135
1417
  -- Purchase spec: Cost.Path is the template's numeric-leaf path union and
1136
1418
  -- Grant receives the typed accessor tree.
1137
1419
  local costProps: { [type]: type } = {}
1138
- -- false: a cost path must be a plain number balance. Monetization refuses a
1139
- -- non-number at runtime, so this rejects a Scribe.Big path at author time.
1140
- costProps[ts.singleton("Path")] = StatPathsType(T, ts.singleton(false))
1141
- costProps[ts.singleton("Amount")] = ts.number
1420
+ -- Include Big currency paths.
1421
+ costProps[ts.singleton("Path")] = StatPathsType(T, ts.singleton(true))
1422
+ -- Validate path/amount pairs at runtime to avoid a costly per-path type union.
1423
+ costProps[ts.singleton("Amount")] = ts.unionof(ts.number, ts.string, bigScore)
1142
1424
  local purchaseProps: { [type]: type } = {}
1143
1425
  purchaseProps[ts.singleton("Cost")] = ts.newtable(costProps, nil, nil)
1144
1426
  purchaseProps[ts.singleton("Category")] = optional(ts.string)
1145
1427
  purchaseProps[ts.singleton("ItemId")] = ts.string
1146
1428
  purchaseProps[ts.singleton("Grant")] = optional(fn({ node }, {}))
1147
1429
  purchaseProps[ts.singleton("Meta")] = optAnyTable
1430
+ purchaseProps[ts.singleton("IdempotencyKey")] = optional(ts.string)
1431
+ purchaseProps[ts.singleton("PaidRandom")] = optional(ts.boolean)
1148
1432
  add("Purchase", fn({ P, ts.newtable(purchaseProps, nil, nil) }, boolAndReason))
1149
1433
  add("RecordPurchase", fn({ P, anyTable }, {}))
1150
1434
  -- OpenLeg and OpenExchange are rebuilt here: a type function cannot reach an alias.
@@ -1211,14 +1495,19 @@ type function BuildServerDataType(T, P, S)
1211
1495
  add("SendMessage", fn({ ts.number, ts.any }, { ts.boolean }))
1212
1496
  add("ProfileStore", ts.any)
1213
1497
  add("Raw", ts.any)
1214
- add("ServerStore", StoreDataType(S))
1498
+ add("ServerStore", StoreDataType(S, Names))
1215
1499
 
1216
- return ts.newtable(props, { index = P, readresult = node, writeresult = node }, nil)
1500
+ -- Read-only members avoid invariant type comparisons.
1501
+ local api = ts.newtable(nil, { index = P, readresult = node, writeresult = node }, nil)
1502
+ for key, ty in props do
1503
+ api:setreadproperty(key, ty)
1504
+ end
1505
+ return api
1217
1506
  end
1218
1507
 
1219
1508
  -- selene: allow(undefined_variable)
1220
1509
  export type function ServerDataType(T, P)
1221
- return BuildServerDataType(T, P, types.any)
1510
+ return BuildServerDataType(T, P, types.any, nil)
1222
1511
  end
1223
1512
 
1224
1513
  --------------------------------------------------------------------------------
@@ -1262,21 +1551,54 @@ export type MapKeyType = "integer" | "string"
1262
1551
  type BigFields = {
1263
1552
  M: number,
1264
1553
  E: number,
1554
+ --[[
1555
+ Formats the value with suffixes and rounded decimal places.
1556
+ ]]
1265
1557
  Short: (self: any, decimals: number?) -> string,
1558
+ --[[
1559
+ Converts to a number; values outside its range may overflow or underflow.
1560
+ ]]
1266
1561
  ToNumber: (self: any) -> number,
1267
1562
  -- Pow returns another big, typed `any` rather than BigValue: spelling the recursion
1268
1563
  -- here tips bundles in test/TypeCheck.luau past the solver's complexity budget. The
1269
1564
  -- accessor tree gets the real self-referential type from ValueType above.
1565
+ --[[
1566
+ Returns a new value raised to the given power.
1567
+ ]]
1270
1568
  Pow: (self: any, n: number) -> any,
1569
+ --[[
1570
+ Returns the base-10 logarithm.
1571
+ ]]
1271
1572
  Log10: (self: any) -> number,
1272
1573
  -- The marker stays shallow, like Pow; accessor reads gain exact recursive
1273
1574
  -- result types from bigValueType above. BigMath.Big is only the M/E shape.
1575
+ --[[
1576
+ Returns the sum as a new Big value.
1577
+ ]]
1274
1578
  Add: (self: any, other: BigMath.Big | number | string) -> any,
1579
+ --[[
1580
+ Returns the difference as a new Big value.
1581
+ ]]
1275
1582
  Subtract: (self: any, other: BigMath.Big | number | string) -> any,
1583
+ --[[
1584
+ Returns the product as a new Big value.
1585
+ ]]
1276
1586
  Multiply: (self: any, other: BigMath.Big | number | string) -> any,
1587
+ --[[
1588
+ Returns the quotient as a new Big value.
1589
+ ]]
1277
1590
  Divide: (self: any, other: BigMath.Big | number | string) -> any,
1591
+ --[[
1592
+ Returns a new Big value with the opposite sign.
1593
+ ]]
1278
1594
  Negate: (self: any) -> any,
1595
+ --[[
1596
+ Returns -1, 0 or 1 for less than, equal to or greater than the other value.
1597
+ ]]
1279
1598
  Compare: (self: any, other: BigMath.Big | number | string) -> number,
1599
+ --[[
1600
+ Returns whether both values are equal.
1601
+ ]]
1280
1602
  Equals: (self: any, other: BigMath.Big | number | string) -> boolean,
1281
1603
  }
1282
1604
  type BigMt = { __scribeBig: true }
@@ -1321,16 +1643,20 @@ export type LeaderboardConfig<T = any> = {
1321
1643
  export type ProductConfig<T = any> = {
1322
1644
  Id: number,
1323
1645
  Category: string?,
1324
- Grant: ((data: GrantDataType<T>) -> ())?,
1646
+ Grant: ((data: BuildGrantDataType<T, NodeFunctionNames>) -> ())?,
1325
1647
  Grants: string?,
1648
+ PaidRandom: boolean?,
1326
1649
  }
1327
1650
 
1328
1651
  export type PurchaseSpec<T = any> = {
1329
- Cost: { Path: StatPathsType<T, false>, Amount: number },
1652
+ -- Strings and BigValue amounts require a Big currency.
1653
+ Cost: { Path: StatPathsType<T, true>, Amount: number | string | BigValue },
1330
1654
  Category: string?,
1331
1655
  ItemId: string,
1332
- Grant: ((data: GrantDataType<T>) -> ())?,
1656
+ Grant: ((data: BuildGrantDataType<T, NodeFunctionNames>) -> ())?,
1333
1657
  Meta: { [string]: any }?,
1658
+ IdempotencyKey: string?,
1659
+ PaidRandom: boolean?,
1334
1660
  }
1335
1661
 
1336
1662
  -- Loose, read-only option shapes. They deliberately do not depend on T: inside the
@@ -1356,6 +1682,7 @@ type ProductConfigLoose = {
1356
1682
  read Category: string?,
1357
1683
  read Grant: ((data: any) -> ())?,
1358
1684
  read Grants: string?,
1685
+ read PaidRandom: boolean?,
1359
1686
  }
1360
1687
 
1361
1688
  -- Economy is loose for the same reason: a Resolve lambda's parameter would
@@ -1376,8 +1703,9 @@ type EconomyConfigLoose = {
1376
1703
 
1377
1704
  --- Passed to ImportLegacyData and OnPlayerInit for pacing legacy-store reads.
1378
1705
  export type MigrationContext = {
1379
- --- Yields until `count` requests are spare, or `timeout` passes. Returns whether
1380
- --- they were granted, and an optional release to call once they have been issued.
1706
+ --[[
1707
+ Waits for budget; returns success and a release function. Release after issuing requests.
1708
+ ]]
1381
1709
  AwaitBudget: (requestType: string, count: number?, timeout: number?) -> (boolean, () -> ()),
1382
1710
  }
1383
1711
 
@@ -1500,19 +1828,18 @@ export type ScribeOptions<T, S = any> = {
1500
1828
  StudioHook: boolean?, -- default false: the Studio debug hooks the Scribe Studio plugin reads
1501
1829
  }
1502
1830
 
1503
- export type ServerData<T, S = any> = BuildServerDataType<T, Player, S>
1831
+ export type ServerData<T, S = any> = BuildServerDataType<T, Player, S, NodeFunctionNames>
1504
1832
 
1505
- export type ClientData<T, S = any> = BuildClientDataType<T, S>
1833
+ export type ClientData<T, S = any> = BuildClientDataType<T, S, NodeFunctionNames>
1506
1834
 
1507
- -- One player's typed accessor tree: the type of `Data[player]`, `Data.Get(player)` and
1508
- -- the client's `Data.Get()`. A plain alias because a type function cannot be invoked
1509
- -- across a module boundary: `Scribe.ValueType<T>` silently resolves to `any` rather than
1510
- -- erroring, so this is the only way a consumer can name the type.
1511
- export type PlayerData<T> = ValueType<T>
1835
+ -- Server accessor tree; clients use ClientData. Export an alias because type functions
1836
+ -- cannot be called across modules: Scribe.ValueType<T> would resolve to any.
1837
+ export type PlayerData<T> = BuildValueType<T, NodeFunctionNames, "server">
1512
1838
 
1839
+ -- Read-only halves avoid invariant comparisons that exhaust the type budget.
1513
1840
  export type Bundle<T, S = any> = {
1514
- Server: ServerData<T, S>,
1515
- Client: ClientData<T, S>,
1841
+ read Server: ServerData<T, S>,
1842
+ read Client: ClientData<T, S>,
1516
1843
  }
1517
1844
 
1518
1845
  --------------------------------------------------------------------------------
@@ -1609,6 +1936,9 @@ local KNOWN_OPTION_KEYS: { [string]: boolean } = {
1609
1936
  StudioHook = true,
1610
1937
  }
1611
1938
 
1939
+ --[[
1940
+ Builds the server and client data APIs from a template and options.
1941
+ ]]
1612
1942
  local function buildBundle<T, S>(options: ScribeOptions<T, S>): Bundle<T, S>
1613
1943
  if type(options) ~= "table" then
1614
1944
  error("Scribe: options must be a table", 2)
@@ -1735,74 +2065,102 @@ local Scribe = {}
1735
2065
 
1736
2066
  Scribe.Version = require(script.Internal.Version)
1737
2067
 
1738
- -- Keeps this field and its subtree off the client.
2068
+ --[[
2069
+ Keeps this field and its subtree off the client.
2070
+ ]]
1739
2071
  function Scribe.ServerOnly<T>(value: T): ServerOnly<T>
1740
2072
  return Marker.make("ServerOnly", value) :: any
1741
2073
  end
1742
2074
 
1743
- -- Replicates a root field to every client.
2075
+ --[[
2076
+ Replicates a root field to every client.
2077
+ ]]
1744
2078
  function Scribe.Shared<T>(value: T): T
1745
2079
  return Marker.make("Shared", value) :: any
1746
2080
  end
1747
2081
 
1748
- -- Keeps a root field unsaved; its visibility wrappers still apply.
2082
+ --[[
2083
+ Keeps a root field unsaved; its visibility wrappers still apply.
2084
+ ]]
1749
2085
  function Scribe.Session<T>(value: T): T
1750
2086
  return Marker.make("Session", value) :: any
1751
2087
  end
1752
2088
 
1753
- -- Declares integer data with optional bounds.
2089
+ --[[
2090
+ Declares integer data with optional bounds.
2091
+ ]]
1754
2092
  function Scribe.Int(default: number, meta: NumberMeta?): number
1755
2093
  return Marker.make("Int", default, meta :: any) :: any
1756
2094
  end
1757
2095
 
1758
- -- Declares floating-point data with optional bounds and wire precision.
2096
+ --[[
2097
+ Declares floating-point data with optional bounds and wire precision.
2098
+ ]]
1759
2099
  function Scribe.Number(default: number, meta: FloatMeta?): number
1760
2100
  return Marker.make("Number", default, meta :: any) :: any
1761
2101
  end
1762
2102
 
1763
- -- Declares large-range numbers; numeric strings are limited to 256 bytes.
2103
+ --[[
2104
+ Declares large-range numbers; numeric strings are limited to 256 bytes.
2105
+ ]]
1764
2106
  function Scribe.Big(default: (number | string)?, meta: BigMeta?): BigValue
1765
2107
  return Marker.make("Big", if default == nil then 0 else default, meta :: any) :: any
1766
2108
  end
1767
2109
 
1768
- -- Declares string data with an optional byte limit.
2110
+ --[[
2111
+ Declares string data with an optional byte limit.
2112
+ ]]
1769
2113
  function Scribe.String(default: string, meta: StringMeta?): string
1770
2114
  return Marker.make("String", default, meta :: any) :: any
1771
2115
  end
1772
2116
 
1773
- -- Restricts a string field to the declared members.
2117
+ --[[
2118
+ Restricts a string field to the declared members.
2119
+ ]]
1774
2120
  function Scribe.Enum(default: string, members: { string }): string
1775
2121
  return Marker.make("Enum", default, { Members = members }) :: any
1776
2122
  end
1777
2123
 
1778
- -- Stores up to 32 named booleans as one field.
2124
+ --[[
2125
+ Stores up to 32 named booleans as one field.
2126
+ ]]
1779
2127
  function Scribe.Flags(members: { string }): Flags
1780
2128
  return Marker.make("Flags", {}, { Members = members }) :: any
1781
2129
  end
1782
2130
 
1783
- -- Declares a leaf reset to its default after SetTimed expires.
2131
+ --[[
2132
+ Declares a leaf reset to its default after SetTimed expires.
2133
+ ]]
1784
2134
  function Scribe.Timed<T>(default: T): Timed<T>
1785
2135
  return Marker.make("Timed", default) :: any
1786
2136
  end
1787
2137
 
1788
- -- Seeds missing profile values with a pure factory, also sampled at declaration.
1789
- -- `(...any) -> T` (not `() -> T`) so standard-library functions with optional
1790
- -- params typecheck when passed directly, e.g. `Scribe.Dynamic(os.time)`.
2138
+ -- Variadic typing accepts optional-argument factories such as os.time.
2139
+
2140
+ --[[
2141
+ Seeds missing values with a pure factory, also sampled at declaration.
2142
+ ]]
1791
2143
  function Scribe.Dynamic<T>(factory: (...any) -> T): T
1792
2144
  return Marker.make("Dynamic", factory(), { Factory = factory :: any }) :: any
1793
2145
  end
1794
2146
 
1795
- -- Declares a read-only value computed from named inputs; compute must be pure.
1796
- function Scribe.Derived<T>(output: T, inputs: { string }, compute: (...any) -> T): Derived<T>
2147
+ --[[
2148
+ Declares a read-only value computed from input paths; compute must be pure.
2149
+ ]]
2150
+ function Scribe.Derived<T>(output: T, inputs: { string }, compute: (...any) -> ...any): Derived<T>
1797
2151
  return Marker.make("Derived", output, { Inputs = inputs, Compute = compute :: any }) :: any
1798
2152
  end
1799
2153
 
1800
- -- Allows an absent leaf value; the inner default is not seeded.
2154
+ --[[
2155
+ Allows an absent leaf value; the inner default is not seeded.
2156
+ ]]
1801
2157
  function Scribe.Optional<T>(inner: T): T?
1802
2158
  return Marker.make("Optional", inner) :: any
1803
2159
  end
1804
2160
 
1805
- -- Declares a typed array with optional size and eviction limits.
2161
+ --[[
2162
+ Declares a typed array with optional size and eviction limits.
2163
+ ]]
1806
2164
  function Scribe.ArrayOf<T>(shape: T, opts: ArrayOpts?): { T }
1807
2165
  if opts ~= nil then
1808
2166
  for key in opts :: any do
@@ -1820,7 +2178,9 @@ function Scribe.ArrayOf<T>(shape: T, opts: ArrayOpts?): { T }
1820
2178
  }) :: any
1821
2179
  end
1822
2180
 
1823
- -- Declares unique scalar members with an optional size limit.
2181
+ --[[
2182
+ Declares unique scalar members with an optional size limit.
2183
+ ]]
1824
2184
  function Scribe.SetOf<T>(element: T, opts: SetOpts?): SetOf<T>
1825
2185
  if opts ~= nil then
1826
2186
  for key in opts :: any do
@@ -1842,7 +2202,9 @@ function Scribe.SetOf<T>(element: T, opts: SetOpts?): SetOf<T>
1842
2202
  }) :: any
1843
2203
  end
1844
2204
 
1845
- -- Declares a map with integer or string keys and a value schema.
2205
+ --[[
2206
+ Declares a map with integer or string keys and a value schema.
2207
+ ]]
1846
2208
  function Scribe.MapOf<K, V>(keyType: K & MapKeyType, value: V, opts: DictOpts?): MapOf<K, V>
1847
2209
  if keyType ~= "integer" and keyType ~= "string" then
1848
2210
  error(`Scribe.MapOf: keyType must be "integer" or "string", got {tostring(keyType)}`, 2)
@@ -1865,7 +2227,9 @@ function Scribe.MapOf<K, V>(keyType: K & MapKeyType, value: V, opts: DictOpts?):
1865
2227
  }) :: any
1866
2228
  end
1867
2229
 
1868
- -- Declares a string-keyed dictionary with a value schema and optional limits.
2230
+ --[[
2231
+ Declares a string-keyed dictionary with a value schema and optional limits.
2232
+ ]]
1869
2233
  function Scribe.DictOf<V>(shape: V, opts: DictOpts?): { [string]: V }
1870
2234
  if opts ~= nil then
1871
2235
  for key in opts :: any do
@@ -1888,24 +2252,37 @@ local function datatypeMarker(name: string, default: any, precision: string?): a
1888
2252
  return Marker.make("Datatype", default, { Datatype = name, Precision = precision })
1889
2253
  end
1890
2254
 
1891
- -- Declares Vector3 data, packed for storage and replication.
2255
+ --[[
2256
+ Declares Vector3 data, packed for storage and replication.
2257
+ ]]
1892
2258
  function Scribe.Vector3(default: Vector3): Vector3
1893
2259
  return datatypeMarker("Vector3", default)
1894
2260
  end
1895
2261
 
2262
+ --[[
2263
+ Declares Vector2 data, packed for storage and replication.
2264
+ ]]
1896
2265
  function Scribe.Vector2(default: Vector2): Vector2
1897
2266
  return datatypeMarker("Vector2", default)
1898
2267
  end
1899
2268
 
2269
+ --[[
2270
+ Declares Vector3int16 data, packed for storage and replication.
2271
+ ]]
1900
2272
  function Scribe.Vector3int16(default: Vector3int16): Vector3int16
1901
2273
  return datatypeMarker("Vector3int16", default)
1902
2274
  end
1903
2275
 
2276
+ --[[
2277
+ Declares Vector2int16 data, packed for storage and replication.
2278
+ ]]
1904
2279
  function Scribe.Vector2int16(default: Vector2int16): Vector2int16
1905
2280
  return datatypeMarker("Vector2int16", default)
1906
2281
  end
1907
2282
 
1908
- -- Declares packed CFrame data; Precision = "exact" preserves its f32 components.
2283
+ --[[
2284
+ Declares packed CFrame data; Precision = "exact" preserves its f32 components.
2285
+ ]]
1909
2286
  function Scribe.CFrame(default: CFrame, meta: CFrameMeta?): CFrame
1910
2287
  if meta ~= nil then
1911
2288
  for key in meta :: any do
@@ -1917,50 +2294,86 @@ function Scribe.CFrame(default: CFrame, meta: CFrameMeta?): CFrame
1917
2294
  return datatypeMarker("CFrame", default, if meta then meta.Precision else nil)
1918
2295
  end
1919
2296
 
2297
+ --[[
2298
+ Declares Color3 data, packed for storage and replication.
2299
+ ]]
1920
2300
  function Scribe.Color3(default: Color3): Color3
1921
2301
  return datatypeMarker("Color3", default)
1922
2302
  end
1923
2303
 
2304
+ --[[
2305
+ Declares BrickColor data, packed for storage and replication.
2306
+ ]]
1924
2307
  function Scribe.BrickColor(default: BrickColor): BrickColor
1925
2308
  return datatypeMarker("BrickColor", default)
1926
2309
  end
1927
2310
 
2311
+ --[[
2312
+ Declares UDim data, packed for storage and replication.
2313
+ ]]
1928
2314
  function Scribe.UDim(default: UDim): UDim
1929
2315
  return datatypeMarker("UDim", default)
1930
2316
  end
1931
2317
 
2318
+ --[[
2319
+ Declares UDim2 data, packed for storage and replication.
2320
+ ]]
1932
2321
  function Scribe.UDim2(default: UDim2): UDim2
1933
2322
  return datatypeMarker("UDim2", default)
1934
2323
  end
1935
2324
 
2325
+ --[[
2326
+ Declares Rect data, packed for storage and replication.
2327
+ ]]
1936
2328
  function Scribe.Rect(default: Rect): Rect
1937
2329
  return datatypeMarker("Rect", default)
1938
2330
  end
1939
2331
 
2332
+ --[[
2333
+ Declares NumberRange data, packed for storage and replication.
2334
+ ]]
1940
2335
  function Scribe.NumberRange(default: NumberRange): NumberRange
1941
2336
  return datatypeMarker("NumberRange", default)
1942
2337
  end
1943
2338
 
2339
+ --[[
2340
+ Declares NumberSequence data, packed for storage and replication.
2341
+ ]]
1944
2342
  function Scribe.NumberSequence(default: NumberSequence): NumberSequence
1945
2343
  return datatypeMarker("NumberSequence", default)
1946
2344
  end
1947
2345
 
2346
+ --[[
2347
+ Declares ColorSequence data, packed for storage and replication.
2348
+ ]]
1948
2349
  function Scribe.ColorSequence(default: ColorSequence): ColorSequence
1949
2350
  return datatypeMarker("ColorSequence", default)
1950
2351
  end
1951
2352
 
2353
+ --[[
2354
+ Declares DateTime data, packed for storage and replication.
2355
+ ]]
1952
2356
  function Scribe.DateTime(default: DateTime): DateTime
1953
2357
  return datatypeMarker("DateTime", default)
1954
2358
  end
1955
2359
 
2360
+ --[[
2361
+ Declares EnumItem data, packed for storage and replication.
2362
+ ]]
1956
2363
  function Scribe.EnumItem(default: EnumItem): EnumItem
1957
2364
  return datatypeMarker("EnumItem", default)
1958
2365
  end
1959
2366
 
2367
+ --[[
2368
+ Declares Font data, packed for storage and replication.
2369
+ ]]
1960
2370
  function Scribe.Font(default: Font): Font
1961
2371
  return datatypeMarker("Font", default)
1962
2372
  end
1963
2373
 
2374
+ --[[
2375
+ Declares PhysicalProperties data, packed for storage and replication.
2376
+ ]]
1964
2377
  function Scribe.PhysicalProperties(default: PhysicalProperties): PhysicalProperties
1965
2378
  return datatypeMarker("PhysicalProperties", default)
1966
2379
  end
@@ -1968,7 +2381,9 @@ end
1968
2381
  -- Codec helpers for packing and unpacking Roblox datatypes.
1969
2382
  Scribe.Datatypes = require(script.Internal.Datatypes)
1970
2383
 
1971
- -- Formats a number or Big value with suffixes and rounded decimal places.
2384
+ --[[
2385
+ Formats a number or Big value with suffixes and rounded decimal places.
2386
+ ]]
1972
2387
  function Scribe.Short(value: (number | BigValue)?, decimals: number?): string
1973
2388
  if decimals ~= nil and (type(decimals) ~= "number" or decimals < 0 or decimals % 1 ~= 0) then
1974
2389
  error(`Scribe.Short: decimals must be a non-negative whole number, got {tostring(decimals)}`, 2)
@@ -1980,12 +2395,16 @@ function Scribe.Short(value: (number | BigValue)?, decimals: number?): string
1980
2395
  return BigMath.toShort(big, decimals)
1981
2396
  end
1982
2397
 
1983
- -- Replaces suffixes used by Short; the first suffix must be empty.
2398
+ --[[
2399
+ Replaces suffixes used by Short; the first suffix must be empty.
2400
+ ]]
1984
2401
  function Scribe.SetShortSuffixes(suffixes: { string })
1985
2402
  BigMath.SetSuffixes(suffixes)
1986
2403
  end
1987
2404
 
1988
- -- Sets process-wide options before any bundle is built; conflicting calls error.
2405
+ --[[
2406
+ Sets process-wide options before any bundle is built; conflicting calls error.
2407
+ ]]
1989
2408
  function Scribe.Configure(config: { AutoSaveInterval: number? })
1990
2409
  if type(config) ~= "table" then
1991
2410
  error("Scribe.Configure: config must be a table", 2)
@@ -2058,6 +2477,7 @@ Scribe.PurchaseReason = table.freeze({
2058
2477
  InsufficientFunds = "insufficient funds" :: Types.PurchaseReason,
2059
2478
  PaidRandomRestricted = "paid random items are not available for this account" :: Types.PurchaseReason,
2060
2479
  PolicyPending = "cannot check account settings right now; try again in a moment" :: Types.PurchaseReason,
2480
+ InvalidIdempotencyKey = "invalid IdempotencyKey" :: Types.PurchaseReason,
2061
2481
  })
2062
2482
 
2063
2483
  -- Fixed gift refusals; other failures may return diagnostic text.
@@ -2163,17 +2583,23 @@ Scribe.Visibility = table.freeze({
2163
2583
  -- Alias of Reason using the matching exported type name.
2164
2584
  Scribe.LifecycleReason = Scribe.Reason
2165
2585
 
2166
- -- Returns the server bundle prefix, or PLAYER_ before setup and on clients.
2586
+ --[[
2587
+ Returns the server bundle prefix, or PLAYER_ before setup and on clients.
2588
+ ]]
2167
2589
  function Scribe.GetProfileKeyPrefix(): string
2168
2590
  return Addons.ProfileKeyPrefix()
2169
2591
  end
2170
2592
 
2171
- -- Returns current DataStore health.
2593
+ --[[
2594
+ Returns current DataStore health.
2595
+ ]]
2172
2596
  function Scribe.GetStatus(): Status
2173
2597
  return Health.GetStatus()
2174
2598
  end
2175
2599
 
2176
- -- Returns cached board health without DataStore requests; empty on clients.
2600
+ --[[
2601
+ Returns cached board health without DataStore requests; empty on clients.
2602
+ ]]
2177
2603
  function Scribe.GetLeaderboardSnapshot(): { LeaderboardSnapshotEntry }
2178
2604
  return if RunService:IsServer() then LeaderboardDiagnostics.Snapshot() else {}
2179
2605
  end
@@ -2184,37 +2610,51 @@ Scribe.OnStatusChanged = Health.OnStatusChanged
2184
2610
  -- Fires for each Error or Fatal log entry.
2185
2611
  Scribe.OnIssue = Log.OnIssue
2186
2612
 
2187
- -- Adds a filtered, bounded log sink; returns its disconnect function.
2613
+ --[[
2614
+ Adds a filtered, bounded log sink; returns its disconnect function.
2615
+ ]]
2188
2616
  function Scribe.AddLogSink(fn: (entry: LogEntry) -> (), options: LogSinkOptions?): () -> ()
2189
2617
  return Log.AddSink(fn :: any, options)
2190
2618
  end
2191
2619
 
2192
- -- Registers plugin actions; returned cleanup removes only this registration.
2620
+ --[[
2621
+ Registers plugin actions; returned cleanup removes only this registration.
2622
+ ]]
2193
2623
  function Scribe.RegisterAddon(name: string, actions: Addons.Actions): () -> ()
2194
2624
  return Addons.Register(name, actions)
2195
2625
  end
2196
2626
 
2197
- -- Returns filtered retained logs, oldest first; Limit keeps the newest entries.
2627
+ --[[
2628
+ Returns filtered retained logs, oldest first; Limit keeps the newest entries.
2629
+ ]]
2198
2630
  function Scribe.GetRecentLogs(filter: Log.LogFilter?): { LogEntry }
2199
2631
  return Log.GetRecent(filter)
2200
2632
  end
2201
2633
 
2202
- -- Returns this context's counters and distribution summaries.
2634
+ --[[
2635
+ Returns this context's counters and distribution summaries.
2636
+ ]]
2203
2637
  function Scribe.GetMetrics(): { [string]: number | { Count: number, Average: number, Max: number } }
2204
2638
  return Metrics.Get()
2205
2639
  end
2206
2640
 
2207
- -- Returns recent distribution percentiles with sample age and window size.
2641
+ --[[
2642
+ Returns recent distribution percentiles with sample age and window size.
2643
+ ]]
2208
2644
  function Scribe.GetPercentiles(): { [string]: Metrics.Percentiles }
2209
2645
  return Metrics.GetPercentiles()
2210
2646
  end
2211
2647
 
2212
- -- Reads current DataStore allowances; Available is false if the query fails.
2648
+ --[[
2649
+ Reads current DataStore allowances; Available is false if the query fails.
2650
+ ]]
2213
2651
  function Scribe.GetBudgetSnapshot(): Budget.Snapshot
2214
2652
  return Budget.Snapshot()
2215
2653
  end
2216
2654
 
2217
- -- Builds a Server/Client bundle; calling Scribe(options) uses the same function.
2655
+ --[[
2656
+ Builds a Server/Client bundle; calling Scribe(options) uses the same function.
2657
+ ]]
2218
2658
  Scribe.new = buildBundle
2219
2659
 
2220
2660
  -- The metatable is attached through a cast so it stays invisible to the type