@rbxts/scribe 2.6.0 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/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
 
@@ -91,9 +117,22 @@ type NodeFunctionNames = {
91
117
  ExtendTimed: (seconds: any, replicate: any) -> (),
92
118
  }
93
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
+
94
131
  -- selene: allow(undefined_variable) -- `types` is the type-function runtime library
95
- type function BuildValueType(T, Names: type?)
132
+ -- "client" omits timer writes; "clientstore" omits all writes. Defaults to server.
133
+ type function BuildValueType(T, Names: type?, Mode: type?)
96
134
  local ts = types
135
+ local mode = if Mode ~= nil and Mode:is("singleton") then Mode:value() else nil
97
136
 
98
137
  local nilType = ts.singleton(nil)
99
138
 
@@ -104,6 +143,8 @@ type function BuildValueType(T, Names: type?)
104
143
  local anyType = ts.any
105
144
  local optBool = optional(ts.boolean)
106
145
  local optNumber = optional(ts.number)
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))))
107
148
 
108
149
  local function fn(params: { type }, rets: { type }, name: string?): type
109
150
  if name ~= nil and Names ~= nil then
@@ -193,8 +234,7 @@ type function BuildValueType(T, Names: type?)
193
234
  return big
194
235
  end
195
236
 
196
- -- Big, Flags and SetOf carry their label in the metatable rather than in a field,
197
- -- so each declarator's own type is already the read shape. See BigValue.
237
+ -- Big, Flags and SetOf carry their brands in the metatable.
198
238
  local function hasMarker(t: type, name: string): boolean
199
239
  local mt = t:metatable()
200
240
  return mt ~= nil and mt:readproperty(ts.singleton(name)) ~= nil
@@ -234,9 +274,30 @@ type function BuildValueType(T, Names: type?)
234
274
  return out
235
275
  end
236
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
+
237
291
  local unwrapCache: { [type]: type } = {}
238
292
  local function unwrapWrappers(t: type, depth: number): type
239
- 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
240
301
  return t
241
302
  end
242
303
  local cached = unwrapCache[t]
@@ -259,9 +320,8 @@ type function BuildValueType(T, Names: type?)
259
320
  if derived ~= nil then
260
321
  return memo(unwrapWrappers(widen(derived), depth + 1))
261
322
  end
262
- -- A marker cannot hide under one of the branded declarators: their metatable
263
- -- brand means the shape below them is already the read shape.
264
- 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
265
325
  return memo(t)
266
326
  end
267
327
  local props: { [type]: type } = {}
@@ -288,7 +348,8 @@ type function BuildValueType(T, Names: type?)
288
348
  if not rebuilt then
289
349
  return memo(t)
290
350
  end
291
- return memo(ts.newtable(props, spec, nil))
351
+ -- Preserve set and map brands.
352
+ return memo(ts.newtable(props, spec, t:metatable()))
292
353
  end
293
354
 
294
355
  -- A canonical key for a subtree, so two identical subtrees are built once. A template
@@ -410,6 +471,12 @@ type function BuildValueType(T, Names: type?)
410
471
  if inner ~= nil then
411
472
  t = widen(inner)
412
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
413
480
  end
414
481
 
415
482
  -- A Scribe.Derived node reads as V and never writes, so this only records the
@@ -449,6 +516,9 @@ type function BuildValueType(T, Names: type?)
449
516
  -- index-based Remove, neither of which a set has. `t` is already the members.
450
517
  local isSet = t:is("table") and hasMarker(t, "__scribeSet")
451
518
 
519
+ -- Derived fields and client stores are read-only.
520
+ local writable = not isDerived and mode ~= "clientstore"
521
+
452
522
  -- Second ServerOnly unwrap, for a marker nested inside another declarator
453
523
  -- rather than wrapped around one. The server reads these normally;
454
524
  -- StripServerOnly is what drops them from the client type.
@@ -471,7 +541,7 @@ type function BuildValueType(T, Names: type?)
471
541
  if indexer ~= nil then
472
542
  mapKey = indexer.index
473
543
  mapValue = indexer.readresult
474
- mapElement = widen(indexer.readresult)
544
+ mapElement = unwrapWrappers(widen(indexer.readresult), depth + 1)
475
545
  end
476
546
  end
477
547
 
@@ -510,13 +580,14 @@ type function BuildValueType(T, Names: type?)
510
580
  local childType = prop.read or prop.write
511
581
  if childType ~= nil then
512
582
  table.insert(childKeys, key)
513
- table.insert(childValues, widen(childType))
583
+ table.insert(childValues, unwrapWrappers(widen(childType), depth + 1))
514
584
  end
515
585
  end
516
586
 
517
587
  local indexer = t:indexer()
518
588
  if indexer ~= nil then
519
- local elementType = widen(indexer.readresult)
589
+ -- Read values exclude nested markers.
590
+ local elementType = unwrapWrappers(widen(indexer.readresult), depth + 1)
520
591
  local elementIn = readOnlyDeep(elementType, depth + 1)
521
592
  if indexer.index:is("number") then
522
593
  -- Array node: the indexer makes `arr[i]` an accessor node, which is
@@ -528,10 +599,12 @@ type function BuildValueType(T, Names: type?)
528
599
  readresult = elemNode,
529
600
  writeresult = elemNode,
530
601
  }
531
- add("Insert", fn({ elementIn, optNumber, optBool }, {}, "Insert"))
532
- -- Remove returns nil on an empty/missing array (matches RemoveValue).
533
- add("Remove", fn({ optNumber, optBool }, { optional(elementType) }, "RemoveIndex"))
534
- add("RemoveValue", fn({ elementIn, optBool }, { optional(elementType), optNumber }, "Set"))
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
535
608
  add("Find", fn({ elementIn }, { optNumber }, "Value"))
536
609
  add("Has", fn({ elementIn }, { ts.boolean }, "Value"))
537
610
  add(
@@ -551,7 +624,9 @@ type function BuildValueType(T, Names: type?)
551
624
  readresult = childNode,
552
625
  writeresult = childNode,
553
626
  }
554
- add("Remove", fn({ ts.string, optBool }, { optional(elementType) }, "RemoveKey"))
627
+ if writable then
628
+ add("Remove", fn({ ts.string, optBool }, { optional(elementType) }, "RemoveKey"))
629
+ end
555
630
  add(
556
631
  "OnKeyAdded",
557
632
  fn({ fn({ indexer.index, elementType }, {}, "KeyValue") }, { disconnectType }, "Listener")
@@ -561,12 +636,14 @@ type function BuildValueType(T, Names: type?)
561
636
  fn({ fn({ indexer.index, elementType }, {}, "KeyValue") }, { disconnectType }, "Listener")
562
637
  )
563
638
  end
564
- add("Clear", fn({ optBool }, {}, "Replicate"))
639
+ if writable then
640
+ add("Clear", fn({ optBool }, {}, "Replicate"))
641
+ end
565
642
  add("Count", fn({}, { ts.number }))
566
643
  -- A dynamic container's children are homogeneous, so the key and value
567
644
  -- types here are exact rather than a union over declared fields.
568
645
  table.insert(childKeys, indexer.index)
569
- table.insert(childValues, widen(indexer.readresult))
646
+ table.insert(childValues, elementType)
570
647
  end
571
648
 
572
649
  if #childKeys > 0 then
@@ -593,7 +670,9 @@ type function BuildValueType(T, Names: type?)
593
670
  local childNode = build(mapValue :: type, false, depth + 1)
594
671
  table.insert(childLookups, fn({ mapKey }, { childNode }, "Key"))
595
672
  indexerSpec = { index = mapKey, readresult = childNode, writeresult = childNode }
596
- add("Remove", fn({ mapKey, optBool }, { optional(element) }, "RemoveKey"))
673
+ if writable then
674
+ add("Remove", fn({ mapKey, optBool }, { optional(element) }, "RemoveKey"))
675
+ end
597
676
  add("OnKeyAdded", fn({ fn({ mapKey, element }, {}, "KeyValue") }, { disconnectType }, "Listener"))
598
677
  add("OnKeyRemoved", fn({ fn({ mapKey, element }, {}, "KeyValue") }, { disconnectType }, "Listener"))
599
678
  add(
@@ -604,7 +683,9 @@ type function BuildValueType(T, Names: type?)
604
683
  "Listener"
605
684
  )
606
685
  )
607
- add("Clear", fn({ optBool }, {}, "Replicate"))
686
+ if writable then
687
+ add("Clear", fn({ optBool }, {}, "Replicate"))
688
+ end
608
689
  add("Count", fn({}, { ts.number }))
609
690
  end
610
691
 
@@ -623,7 +704,7 @@ type function BuildValueType(T, Names: type?)
623
704
  -- The root accessor cannot be Set or Updated at runtime, so those are left off the
624
705
  -- root type. A big field declares its own wider Set and Update below; adding them
625
706
  -- here too would duplicate rather than override, as the singletons are distinct keys.
626
- if not isRoot and not isBig and not isDerived then
707
+ if not isRoot and not isBig and writable then
627
708
  -- Writes take the unbranded shape: a caller writing a plain table literal
628
709
  -- has no way to produce a map's metatable brand. Reads still hand back the
629
710
  -- branded type, which assigns freely to the plain shape.
@@ -641,29 +722,47 @@ type function BuildValueType(T, Names: type?)
641
722
  add("Changed", fn({ fn({ valueType, valueType }, {}, "Change") }, { disconnectType }, "Listener"))
642
723
  add("Observe", fn({ fn({ valueType }, {}, "Value") }, { disconnectType }, "Listener"))
643
724
 
644
- if t:is("number") then
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
740
+
741
+ if scalar:is("number") then
645
742
  -- Min/Max read the declared bounds, so they stay on a derived field; the
646
743
  -- two mutators do not.
647
- if not isDerived then
648
- add("Increment", fn({ ts.number, anyType }, { ts.number }, "Increment"))
649
- add("Decrement", fn({ ts.number, anyType }, { ts.number }, "Increment"))
744
+ if writable then
745
+ add("Increment", fn({ ts.number, amountOptions }, { ts.number }, "Increment"))
746
+ add("Decrement", fn({ ts.number, amountOptions }, { ts.number }, "Increment"))
650
747
  end
651
748
  add("Min", fn({}, { optNumber }))
652
749
  add("Max", fn({}, { optNumber }))
653
- elseif t:is("boolean") and not isDerived then
750
+ elseif scalar:is("boolean") and writable then
654
751
  add("Toggle", fn({ optBool }, { ts.boolean }, "Replicate"))
655
752
  end
656
753
 
657
754
  if isBig then
658
755
  -- Every entry point, Set included, takes a number, a numeric string, or
659
756
  -- another big value, so the operand type is the same union everywhere.
660
- local operand = ts.unionof(ts.number, ts.string, valueType)
661
- add("Set", fn({ operand, optBool }, { valueType }, "Set"))
662
- add("Update", fn({ fn({ valueType }, { operand }, "Value"), optBool }, { valueType }, "Update"))
663
- add("Increment", fn({ operand, anyType }, { valueType }, "Increment"))
664
- add("Decrement", fn({ operand, anyType }, { valueType }, "Increment"))
665
- add("Multiply", fn({ operand, optBool }, { valueType }, "Set"))
666
- add("Divide", fn({ operand, optBool }, { valueType }, "Set"))
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
667
766
  -- A big bound past the double range is only expressible as a numeric string,
668
767
  -- so these return the same union the declarator accepts.
669
768
  local optBound = optional(ts.unionof(ts.number, ts.string))
@@ -672,29 +771,39 @@ type function BuildValueType(T, Names: type?)
672
771
  end
673
772
 
674
773
  if isSet then
675
- -- Membership surface. Get/Set still take the whole { T }.
774
+ -- Membership uses unwrapped elements; Get/Set use the whole set.
676
775
  local setIndexer = t:indexer()
677
- 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
678
779
  local elementIn = readOnlyDeep(element, depth + 1)
679
- add("Add", fn({ elementIn, optBool }, { ts.boolean }, "Set"))
680
- add("Remove", fn({ elementIn, optBool }, { ts.boolean }, "Set"))
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
681
785
  add("Has", fn({ elementIn }, { ts.boolean }, "Value"))
786
+ add("Find", fn({ elementIn }, { optNumber }, "Value"))
682
787
  add("Count", fn({}, { ts.number }))
683
- add("Clear", fn({ optBool }, {}, "Replicate"))
684
788
  end
685
789
 
686
790
  if isFlags then
687
791
  -- Named-member surface. Get/Set still take the whole { string } set.
688
- add("Enable", fn({ ts.string, optBool }, {}, "FlagWrite"))
689
- add("Disable", fn({ ts.string, optBool }, {}, "FlagWrite"))
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
690
798
  add("Has", fn({ ts.string }, { ts.boolean }, "Flag"))
691
- add("Toggle", fn({ ts.string, optBool }, { ts.boolean }, "FlagWrite"))
692
- add("Clear", fn({ optBool }, {}, "Replicate"))
693
799
  end
694
800
 
695
801
  if isTimed then
696
- add("SetTimed", fn({ valueType, ts.number, optBool }, {}, "SetTimed"))
697
- add("ExtendTimed", fn({ ts.number, optBool }, {}, "ExtendTimed"))
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
698
807
  add("Active", fn({}, { ts.boolean, optNumber }))
699
808
  end
700
809
 
@@ -741,6 +850,7 @@ export type function StatPathsType(T: type, IncludeBig: type?): type
741
850
  return hasMarker(t, "__scribeMapKey")
742
851
  end
743
852
 
853
+ local WRAPPERS = { "__scribeTimed", "__scribeServerOnly", "__scribeDerived" }
744
854
  local paths: { type } = {}
745
855
 
746
856
  local function widen(t: type): type
@@ -760,28 +870,21 @@ export type function StatPathsType(T: type, IncludeBig: type?): type
760
870
  return
761
871
  end
762
872
  local t = widen(rawType)
763
- if t:is("table") then
764
- -- Unwrap the Scribe.Timed marker; its inner value is the leaf.
765
- local inner = t:readproperty(ts.singleton("__scribeTimed"))
766
- if inner ~= nil then
767
- t = widen(inner)
768
- end
769
- end
770
- if t:is("table") then
771
- -- Same for Scribe.ServerOnly: the server is what reads leaderboard
772
- -- stats, so a server-only number is still a valid stat path.
773
- local serverOnly = t:readproperty(ts.singleton("__scribeServerOnly"))
774
- if serverOnly ~= nil then
775
- 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
776
883
  end
777
- end
778
- if t:is("table") then
779
- -- And Scribe.Derived: a board reads its stat through the accessor tree,
780
- -- which computes derived fields, so a derived number is a valid stat.
781
- local derived = t:readproperty(ts.singleton("__scribeDerived"))
782
- if derived ~= nil then
783
- t = widen(derived)
884
+ if inner == nil then
885
+ break
784
886
  end
887
+ t = widen(inner)
785
888
  end
786
889
  if t:is("table") and isMapMarker(t) then
787
890
  -- A map's entries live under dynamic keys, which cannot be enumerated at type
@@ -842,8 +945,38 @@ type function StripServerOnly(T)
842
945
  -- Matches ValueType's budget: a cyclic template must not blow the stack.
843
946
  local MAX_DEPTH = 25
844
947
 
948
+ -- ServerOnly still applies inside Timed, Derived or Optional.
845
949
  local function isServerOnly(t: type): boolean
846
- 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
847
980
  end
848
981
 
849
982
  local function strip(t: type, depth: number): type
@@ -861,11 +994,10 @@ type function StripServerOnly(T)
861
994
  end
862
995
  end
863
996
  end
864
- -- Element shapes live behind the indexer, not in properties: without this a
865
- -- ServerOnly field inside an ArrayOf or DictOf entry stays in the client type.
997
+ -- Strip hidden fields inside elements; wholly hidden elements become never.
866
998
  local indexer = t:indexer()
867
999
  if indexer ~= nil then
868
- local element = strip(indexer.readresult, depth + 1)
1000
+ local element = if isServerOnly(indexer.readresult) then ts.never else strip(indexer.readresult, depth + 1)
869
1001
  out:setindexer(indexer.index, element)
870
1002
  end
871
1003
  return out
@@ -889,9 +1021,77 @@ export type function GrantDataType(T)
889
1021
  return BuildGrantDataType(T, nil)
890
1022
  end
891
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
+
892
1092
  -- Store proxies expose declared roots, without the root accessor's methods.
893
1093
  -- selene: allow(undefined_variable)
894
- type function StoreDataType(S: type, Names: type?): type
1094
+ type function StoreDataType(S: type, Names: type?, Mode: type?): type
895
1095
  local ts = types
896
1096
  if not S:is("table") then
897
1097
  return ts.any
@@ -910,7 +1110,7 @@ type function StoreDataType(S: type, Names: type?): type
910
1110
  names[key] = alias
911
1111
  end
912
1112
  end
913
- local nodes = BuildValueType(fields, Names)
1113
+ local nodes = BuildValueType(fields, Names, Mode)
914
1114
  local roots = ts.newtable(nil, nodes:indexer(), nil)
915
1115
  for key, alias in names do
916
1116
  roots:setproperty(key, nodes:readproperty(alias))
@@ -967,9 +1167,18 @@ type function BuildClientDataType(T, S, Names: type?)
967
1167
  saveInfoProps[ts.singleton("Size")] = optional(ts.number)
968
1168
  local saveInfo = ts.newtable(saveInfoProps, nil, nil)
969
1169
 
970
- local out = ts.copy(BuildValueType(StripServerOnly(T), Names))
1170
+ local out = ts.copy(BuildValueType(StripServerOnly(T), Names, ts.singleton("client")))
1171
+ -- Read-only members avoid invariant type comparisons.
971
1172
  local function add(name: string, ty: type)
972
- 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)
973
1182
  end
974
1183
 
975
1184
  add("IsReady", fn({}, { ts.boolean }))
@@ -1018,7 +1227,7 @@ type function BuildClientDataType(T, S, Names: type?)
1018
1227
  ts.newfunction({ head = { ts.string, ts.newfunction({ tail = ts.any }, { tail = ts.any }) } }, { head = {} })
1019
1228
  )
1020
1229
  add("Raw", ts.any)
1021
- add("ServerStore", StoreDataType(StripServerOnly(S), Names))
1230
+ add("ServerStore", StoreDataType(StripServerOnly(S), Names, ts.singleton("clientstore")))
1022
1231
 
1023
1232
  return out
1024
1233
  end
@@ -1111,6 +1320,14 @@ type function BuildServerDataType(T, P, S, Names: type?)
1111
1320
 
1112
1321
  local props: { [type]: type } = {}
1113
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
1114
1331
  props[ts.singleton(name)] = ty
1115
1332
  end
1116
1333
 
@@ -1197,8 +1414,7 @@ type function BuildServerDataType(T, P, S, Names: type?)
1197
1414
  add("GrantPerk", fn({ P, ts.string }, {}))
1198
1415
  add("RevokePerk", fn({ P, ts.string }, {}))
1199
1416
 
1200
- -- Purchase spec: Cost.Path is the template's numeric-leaf path union and
1201
- -- Grant receives the typed accessor tree.
1417
+ -- Cost.Path accepts numeric leaves. Grant receives the typed tree and player.
1202
1418
  local costProps: { [type]: type } = {}
1203
1419
  -- Include Big currency paths.
1204
1420
  costProps[ts.singleton("Path")] = StatPathsType(T, ts.singleton(true))
@@ -1208,8 +1424,10 @@ type function BuildServerDataType(T, P, S, Names: type?)
1208
1424
  purchaseProps[ts.singleton("Cost")] = ts.newtable(costProps, nil, nil)
1209
1425
  purchaseProps[ts.singleton("Category")] = optional(ts.string)
1210
1426
  purchaseProps[ts.singleton("ItemId")] = ts.string
1211
- purchaseProps[ts.singleton("Grant")] = optional(fn({ node }, {}))
1427
+ purchaseProps[ts.singleton("Grant")] = optional(fn({ node, P }, {}))
1212
1428
  purchaseProps[ts.singleton("Meta")] = optAnyTable
1429
+ purchaseProps[ts.singleton("IdempotencyKey")] = optional(ts.string)
1430
+ purchaseProps[ts.singleton("PaidRandom")] = optional(ts.boolean)
1213
1431
  add("Purchase", fn({ P, ts.newtable(purchaseProps, nil, nil) }, boolAndReason))
1214
1432
  add("RecordPurchase", fn({ P, anyTable }, {}))
1215
1433
  -- OpenLeg and OpenExchange are rebuilt here: a type function cannot reach an alias.
@@ -1278,7 +1496,12 @@ type function BuildServerDataType(T, P, S, Names: type?)
1278
1496
  add("Raw", ts.any)
1279
1497
  add("ServerStore", StoreDataType(S, Names))
1280
1498
 
1281
- return ts.newtable(props, { index = P, readresult = node, writeresult = node }, nil)
1499
+ -- Read-only members avoid invariant type comparisons.
1500
+ local api = ts.newtable(nil, { index = P, readresult = node, writeresult = node }, nil)
1501
+ for key, ty in props do
1502
+ api:setreadproperty(key, ty)
1503
+ end
1504
+ return api
1282
1505
  end
1283
1506
 
1284
1507
  -- selene: allow(undefined_variable)
@@ -1317,8 +1540,9 @@ export type CFrameMeta = { Precision: "exact"? }
1317
1540
  -- Container declarator options. Not generic in the element type on purpose: an
1318
1541
  -- element-typed option would let Luau infer the element type from it rather than
1319
1542
  -- from `shape`, silently redefining the field.
1320
- export type ArrayOpts = { MaxItems: number?, Evict: ("Front" | "Back")? }
1321
- export type SetOpts = { MaxItems: number? }
1543
+ -- Read-only fields accept partial option literals.
1544
+ export type ArrayOpts = { read MaxItems: number?, read Evict: ("Front" | "Back")? }
1545
+ export type SetOpts = { read MaxItems: number? }
1322
1546
  export type CooldownOptions = { IncludeOfflineTime: boolean? }
1323
1547
  export type MapKeyType = "integer" | "string"
1324
1548
  -- What a Scribe.Big field reads back, which is also what the declarator returns.
@@ -1327,21 +1551,54 @@ export type MapKeyType = "integer" | "string"
1327
1551
  type BigFields = {
1328
1552
  M: number,
1329
1553
  E: number,
1554
+ --[[
1555
+ Formats the value with suffixes and rounded decimal places.
1556
+ ]]
1330
1557
  Short: (self: any, decimals: number?) -> string,
1558
+ --[[
1559
+ Converts to a number; values outside its range may overflow or underflow.
1560
+ ]]
1331
1561
  ToNumber: (self: any) -> number,
1332
1562
  -- Pow returns another big, typed `any` rather than BigValue: spelling the recursion
1333
1563
  -- here tips bundles in test/TypeCheck.luau past the solver's complexity budget. The
1334
1564
  -- accessor tree gets the real self-referential type from ValueType above.
1565
+ --[[
1566
+ Returns a new value raised to the given power.
1567
+ ]]
1335
1568
  Pow: (self: any, n: number) -> any,
1569
+ --[[
1570
+ Returns the base-10 logarithm.
1571
+ ]]
1336
1572
  Log10: (self: any) -> number,
1337
1573
  -- The marker stays shallow, like Pow; accessor reads gain exact recursive
1338
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
+ ]]
1339
1578
  Add: (self: any, other: BigMath.Big | number | string) -> any,
1579
+ --[[
1580
+ Returns the difference as a new Big value.
1581
+ ]]
1340
1582
  Subtract: (self: any, other: BigMath.Big | number | string) -> any,
1583
+ --[[
1584
+ Returns the product as a new Big value.
1585
+ ]]
1341
1586
  Multiply: (self: any, other: BigMath.Big | number | string) -> any,
1587
+ --[[
1588
+ Returns the quotient as a new Big value.
1589
+ ]]
1342
1590
  Divide: (self: any, other: BigMath.Big | number | string) -> any,
1591
+ --[[
1592
+ Returns a new Big value with the opposite sign.
1593
+ ]]
1343
1594
  Negate: (self: any) -> any,
1595
+ --[[
1596
+ Returns -1, 0 or 1 for less than, equal to or greater than the other value.
1597
+ ]]
1344
1598
  Compare: (self: any, other: BigMath.Big | number | string) -> number,
1599
+ --[[
1600
+ Returns whether both values are equal.
1601
+ ]]
1345
1602
  Equals: (self: any, other: BigMath.Big | number | string) -> boolean,
1346
1603
  }
1347
1604
  type BigMt = { __scribeBig: true }
@@ -1360,7 +1617,7 @@ type function MapShape(K, V)
1360
1617
  return out
1361
1618
  end
1362
1619
  export type MapOf<K, V> = MapShape<K, V>
1363
- export type DictOpts = { MaxKeys: number?, MaxKeyLength: number? }
1620
+ export type DictOpts = { read MaxKeys: number?, read MaxKeyLength: number? }
1364
1621
 
1365
1622
  -- Template-aware config types. Annotate a config local with one and `Stat` / `Cost.Path`
1366
1623
  -- become the template's numeric leaf-path union while `Grant` receives the typed accessor
@@ -1386,8 +1643,9 @@ export type LeaderboardConfig<T = any> = {
1386
1643
  export type ProductConfig<T = any> = {
1387
1644
  Id: number,
1388
1645
  Category: string?,
1389
- Grant: ((data: BuildGrantDataType<T, NodeFunctionNames>) -> ())?,
1646
+ Grant: ((data: BuildGrantDataType<T, NodeFunctionNames>, player: Player) -> ())?,
1390
1647
  Grants: string?,
1648
+ PaidRandom: boolean?,
1391
1649
  }
1392
1650
 
1393
1651
  export type PurchaseSpec<T = any> = {
@@ -1395,8 +1653,10 @@ export type PurchaseSpec<T = any> = {
1395
1653
  Cost: { Path: StatPathsType<T, true>, Amount: number | string | BigValue },
1396
1654
  Category: string?,
1397
1655
  ItemId: string,
1398
- Grant: ((data: BuildGrantDataType<T, NodeFunctionNames>) -> ())?,
1656
+ Grant: ((data: BuildGrantDataType<T, NodeFunctionNames>, player: Player) -> ())?,
1399
1657
  Meta: { [string]: any }?,
1658
+ IdempotencyKey: string?,
1659
+ PaidRandom: boolean?,
1400
1660
  }
1401
1661
 
1402
1662
  -- Loose, read-only option shapes. They deliberately do not depend on T: inside the
@@ -1420,8 +1680,9 @@ type LeaderboardConfigLoose = {
1420
1680
  type ProductConfigLoose = {
1421
1681
  read Id: number,
1422
1682
  read Category: string?,
1423
- read Grant: ((data: any) -> ())?,
1683
+ read Grant: ((data: any, player: Player) -> ())?,
1424
1684
  read Grants: string?,
1685
+ read PaidRandom: boolean?,
1425
1686
  }
1426
1687
 
1427
1688
  -- Economy is loose for the same reason: a Resolve lambda's parameter would
@@ -1442,8 +1703,9 @@ type EconomyConfigLoose = {
1442
1703
 
1443
1704
  --- Passed to ImportLegacyData and OnPlayerInit for pacing legacy-store reads.
1444
1705
  export type MigrationContext = {
1445
- --- Yields until `count` requests are spare, or `timeout` passes. Returns whether
1446
- --- 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
+ ]]
1447
1709
  AwaitBudget: (requestType: string, count: number?, timeout: number?) -> (boolean, () -> ()),
1448
1710
  }
1449
1711
 
@@ -1570,15 +1832,14 @@ export type ServerData<T, S = any> = BuildServerDataType<T, Player, S, NodeFunct
1570
1832
 
1571
1833
  export type ClientData<T, S = any> = BuildClientDataType<T, S, NodeFunctionNames>
1572
1834
 
1573
- -- One player's typed accessor tree: the type of `Data[player]`, `Data.Get(player)` and
1574
- -- the client's `Data.Get()`. A plain alias because a type function cannot be invoked
1575
- -- across a module boundary: `Scribe.ValueType<T>` silently resolves to `any` rather than
1576
- -- erroring, so this is the only way a consumer can name the type.
1577
- export type PlayerData<T> = BuildValueType<T, NodeFunctionNames>
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">
1578
1838
 
1839
+ -- Read-only halves avoid invariant comparisons that exhaust the type budget.
1579
1840
  export type Bundle<T, S = any> = {
1580
- Server: ServerData<T, S>,
1581
- Client: ClientData<T, S>,
1841
+ read Server: ServerData<T, S>,
1842
+ read Client: ClientData<T, S>,
1582
1843
  }
1583
1844
 
1584
1845
  --------------------------------------------------------------------------------
@@ -1675,6 +1936,9 @@ local KNOWN_OPTION_KEYS: { [string]: boolean } = {
1675
1936
  StudioHook = true,
1676
1937
  }
1677
1938
 
1939
+ --[[
1940
+ Builds the server and client data APIs from a template and options.
1941
+ ]]
1678
1942
  local function buildBundle<T, S>(options: ScribeOptions<T, S>): Bundle<T, S>
1679
1943
  if type(options) ~= "table" then
1680
1944
  error("Scribe: options must be a table", 2)
@@ -1801,74 +2065,102 @@ local Scribe = {}
1801
2065
 
1802
2066
  Scribe.Version = require(script.Internal.Version)
1803
2067
 
1804
- -- Keeps this field and its subtree off the client.
2068
+ --[[
2069
+ Keeps this field and its subtree off the client.
2070
+ ]]
1805
2071
  function Scribe.ServerOnly<T>(value: T): ServerOnly<T>
1806
2072
  return Marker.make("ServerOnly", value) :: any
1807
2073
  end
1808
2074
 
1809
- -- Replicates a root field to every client.
2075
+ --[[
2076
+ Replicates a root field to every client.
2077
+ ]]
1810
2078
  function Scribe.Shared<T>(value: T): T
1811
2079
  return Marker.make("Shared", value) :: any
1812
2080
  end
1813
2081
 
1814
- -- Keeps a root field unsaved; its visibility wrappers still apply.
2082
+ --[[
2083
+ Keeps a root field unsaved; its visibility wrappers still apply.
2084
+ ]]
1815
2085
  function Scribe.Session<T>(value: T): T
1816
2086
  return Marker.make("Session", value) :: any
1817
2087
  end
1818
2088
 
1819
- -- Declares integer data with optional bounds.
2089
+ --[[
2090
+ Declares integer data with optional bounds.
2091
+ ]]
1820
2092
  function Scribe.Int(default: number, meta: NumberMeta?): number
1821
2093
  return Marker.make("Int", default, meta :: any) :: any
1822
2094
  end
1823
2095
 
1824
- -- Declares floating-point data with optional bounds and wire precision.
2096
+ --[[
2097
+ Declares floating-point data with optional bounds and wire precision.
2098
+ ]]
1825
2099
  function Scribe.Number(default: number, meta: FloatMeta?): number
1826
2100
  return Marker.make("Number", default, meta :: any) :: any
1827
2101
  end
1828
2102
 
1829
- -- 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
+ ]]
1830
2106
  function Scribe.Big(default: (number | string)?, meta: BigMeta?): BigValue
1831
2107
  return Marker.make("Big", if default == nil then 0 else default, meta :: any) :: any
1832
2108
  end
1833
2109
 
1834
- -- Declares string data with an optional byte limit.
2110
+ --[[
2111
+ Declares string data with an optional byte limit.
2112
+ ]]
1835
2113
  function Scribe.String(default: string, meta: StringMeta?): string
1836
2114
  return Marker.make("String", default, meta :: any) :: any
1837
2115
  end
1838
2116
 
1839
- -- Restricts a string field to the declared members.
2117
+ --[[
2118
+ Restricts a string field to the declared members.
2119
+ ]]
1840
2120
  function Scribe.Enum(default: string, members: { string }): string
1841
2121
  return Marker.make("Enum", default, { Members = members }) :: any
1842
2122
  end
1843
2123
 
1844
- -- Stores up to 32 named booleans as one field.
2124
+ --[[
2125
+ Stores up to 32 named booleans as one field.
2126
+ ]]
1845
2127
  function Scribe.Flags(members: { string }): Flags
1846
2128
  return Marker.make("Flags", {}, { Members = members }) :: any
1847
2129
  end
1848
2130
 
1849
- -- Declares a leaf reset to its default after SetTimed expires.
2131
+ --[[
2132
+ Declares a leaf reset to its default after SetTimed expires.
2133
+ ]]
1850
2134
  function Scribe.Timed<T>(default: T): Timed<T>
1851
2135
  return Marker.make("Timed", default) :: any
1852
2136
  end
1853
2137
 
1854
- -- Seeds missing profile values with a pure factory, also sampled at declaration.
1855
- -- `(...any) -> T` (not `() -> T`) so standard-library functions with optional
1856
- -- 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
+ ]]
1857
2143
  function Scribe.Dynamic<T>(factory: (...any) -> T): T
1858
2144
  return Marker.make("Dynamic", factory(), { Factory = factory :: any }) :: any
1859
2145
  end
1860
2146
 
1861
- -- Declares a read-only value computed from named inputs; compute must be pure.
1862
- 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>
1863
2151
  return Marker.make("Derived", output, { Inputs = inputs, Compute = compute :: any }) :: any
1864
2152
  end
1865
2153
 
1866
- -- 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
+ ]]
1867
2157
  function Scribe.Optional<T>(inner: T): T?
1868
2158
  return Marker.make("Optional", inner) :: any
1869
2159
  end
1870
2160
 
1871
- -- Declares a typed array with optional size and eviction limits.
2161
+ --[[
2162
+ Declares a typed array with optional size and eviction limits.
2163
+ ]]
1872
2164
  function Scribe.ArrayOf<T>(shape: T, opts: ArrayOpts?): { T }
1873
2165
  if opts ~= nil then
1874
2166
  for key in opts :: any do
@@ -1886,7 +2178,9 @@ function Scribe.ArrayOf<T>(shape: T, opts: ArrayOpts?): { T }
1886
2178
  }) :: any
1887
2179
  end
1888
2180
 
1889
- -- Declares unique scalar members with an optional size limit.
2181
+ --[[
2182
+ Declares unique scalar members with an optional size limit.
2183
+ ]]
1890
2184
  function Scribe.SetOf<T>(element: T, opts: SetOpts?): SetOf<T>
1891
2185
  if opts ~= nil then
1892
2186
  for key in opts :: any do
@@ -1908,7 +2202,9 @@ function Scribe.SetOf<T>(element: T, opts: SetOpts?): SetOf<T>
1908
2202
  }) :: any
1909
2203
  end
1910
2204
 
1911
- -- 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
+ ]]
1912
2208
  function Scribe.MapOf<K, V>(keyType: K & MapKeyType, value: V, opts: DictOpts?): MapOf<K, V>
1913
2209
  if keyType ~= "integer" and keyType ~= "string" then
1914
2210
  error(`Scribe.MapOf: keyType must be "integer" or "string", got {tostring(keyType)}`, 2)
@@ -1931,7 +2227,9 @@ function Scribe.MapOf<K, V>(keyType: K & MapKeyType, value: V, opts: DictOpts?):
1931
2227
  }) :: any
1932
2228
  end
1933
2229
 
1934
- -- 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
+ ]]
1935
2233
  function Scribe.DictOf<V>(shape: V, opts: DictOpts?): { [string]: V }
1936
2234
  if opts ~= nil then
1937
2235
  for key in opts :: any do
@@ -1954,24 +2252,37 @@ local function datatypeMarker(name: string, default: any, precision: string?): a
1954
2252
  return Marker.make("Datatype", default, { Datatype = name, Precision = precision })
1955
2253
  end
1956
2254
 
1957
- -- Declares Vector3 data, packed for storage and replication.
2255
+ --[[
2256
+ Declares Vector3 data, packed for storage and replication.
2257
+ ]]
1958
2258
  function Scribe.Vector3(default: Vector3): Vector3
1959
2259
  return datatypeMarker("Vector3", default)
1960
2260
  end
1961
2261
 
2262
+ --[[
2263
+ Declares Vector2 data, packed for storage and replication.
2264
+ ]]
1962
2265
  function Scribe.Vector2(default: Vector2): Vector2
1963
2266
  return datatypeMarker("Vector2", default)
1964
2267
  end
1965
2268
 
2269
+ --[[
2270
+ Declares Vector3int16 data, packed for storage and replication.
2271
+ ]]
1966
2272
  function Scribe.Vector3int16(default: Vector3int16): Vector3int16
1967
2273
  return datatypeMarker("Vector3int16", default)
1968
2274
  end
1969
2275
 
2276
+ --[[
2277
+ Declares Vector2int16 data, packed for storage and replication.
2278
+ ]]
1970
2279
  function Scribe.Vector2int16(default: Vector2int16): Vector2int16
1971
2280
  return datatypeMarker("Vector2int16", default)
1972
2281
  end
1973
2282
 
1974
- -- Declares packed CFrame data; Precision = "exact" preserves its f32 components.
2283
+ --[[
2284
+ Declares packed CFrame data; Precision = "exact" preserves its f32 components.
2285
+ ]]
1975
2286
  function Scribe.CFrame(default: CFrame, meta: CFrameMeta?): CFrame
1976
2287
  if meta ~= nil then
1977
2288
  for key in meta :: any do
@@ -1983,50 +2294,86 @@ function Scribe.CFrame(default: CFrame, meta: CFrameMeta?): CFrame
1983
2294
  return datatypeMarker("CFrame", default, if meta then meta.Precision else nil)
1984
2295
  end
1985
2296
 
2297
+ --[[
2298
+ Declares Color3 data, packed for storage and replication.
2299
+ ]]
1986
2300
  function Scribe.Color3(default: Color3): Color3
1987
2301
  return datatypeMarker("Color3", default)
1988
2302
  end
1989
2303
 
2304
+ --[[
2305
+ Declares BrickColor data, packed for storage and replication.
2306
+ ]]
1990
2307
  function Scribe.BrickColor(default: BrickColor): BrickColor
1991
2308
  return datatypeMarker("BrickColor", default)
1992
2309
  end
1993
2310
 
2311
+ --[[
2312
+ Declares UDim data, packed for storage and replication.
2313
+ ]]
1994
2314
  function Scribe.UDim(default: UDim): UDim
1995
2315
  return datatypeMarker("UDim", default)
1996
2316
  end
1997
2317
 
2318
+ --[[
2319
+ Declares UDim2 data, packed for storage and replication.
2320
+ ]]
1998
2321
  function Scribe.UDim2(default: UDim2): UDim2
1999
2322
  return datatypeMarker("UDim2", default)
2000
2323
  end
2001
2324
 
2325
+ --[[
2326
+ Declares Rect data, packed for storage and replication.
2327
+ ]]
2002
2328
  function Scribe.Rect(default: Rect): Rect
2003
2329
  return datatypeMarker("Rect", default)
2004
2330
  end
2005
2331
 
2332
+ --[[
2333
+ Declares NumberRange data, packed for storage and replication.
2334
+ ]]
2006
2335
  function Scribe.NumberRange(default: NumberRange): NumberRange
2007
2336
  return datatypeMarker("NumberRange", default)
2008
2337
  end
2009
2338
 
2339
+ --[[
2340
+ Declares NumberSequence data, packed for storage and replication.
2341
+ ]]
2010
2342
  function Scribe.NumberSequence(default: NumberSequence): NumberSequence
2011
2343
  return datatypeMarker("NumberSequence", default)
2012
2344
  end
2013
2345
 
2346
+ --[[
2347
+ Declares ColorSequence data, packed for storage and replication.
2348
+ ]]
2014
2349
  function Scribe.ColorSequence(default: ColorSequence): ColorSequence
2015
2350
  return datatypeMarker("ColorSequence", default)
2016
2351
  end
2017
2352
 
2353
+ --[[
2354
+ Declares DateTime data, packed for storage and replication.
2355
+ ]]
2018
2356
  function Scribe.DateTime(default: DateTime): DateTime
2019
2357
  return datatypeMarker("DateTime", default)
2020
2358
  end
2021
2359
 
2360
+ --[[
2361
+ Declares EnumItem data, packed for storage and replication.
2362
+ ]]
2022
2363
  function Scribe.EnumItem(default: EnumItem): EnumItem
2023
2364
  return datatypeMarker("EnumItem", default)
2024
2365
  end
2025
2366
 
2367
+ --[[
2368
+ Declares Font data, packed for storage and replication.
2369
+ ]]
2026
2370
  function Scribe.Font(default: Font): Font
2027
2371
  return datatypeMarker("Font", default)
2028
2372
  end
2029
2373
 
2374
+ --[[
2375
+ Declares PhysicalProperties data, packed for storage and replication.
2376
+ ]]
2030
2377
  function Scribe.PhysicalProperties(default: PhysicalProperties): PhysicalProperties
2031
2378
  return datatypeMarker("PhysicalProperties", default)
2032
2379
  end
@@ -2034,7 +2381,9 @@ end
2034
2381
  -- Codec helpers for packing and unpacking Roblox datatypes.
2035
2382
  Scribe.Datatypes = require(script.Internal.Datatypes)
2036
2383
 
2037
- -- 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
+ ]]
2038
2387
  function Scribe.Short(value: (number | BigValue)?, decimals: number?): string
2039
2388
  if decimals ~= nil and (type(decimals) ~= "number" or decimals < 0 or decimals % 1 ~= 0) then
2040
2389
  error(`Scribe.Short: decimals must be a non-negative whole number, got {tostring(decimals)}`, 2)
@@ -2046,12 +2395,16 @@ function Scribe.Short(value: (number | BigValue)?, decimals: number?): string
2046
2395
  return BigMath.toShort(big, decimals)
2047
2396
  end
2048
2397
 
2049
- -- 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
+ ]]
2050
2401
  function Scribe.SetShortSuffixes(suffixes: { string })
2051
2402
  BigMath.SetSuffixes(suffixes)
2052
2403
  end
2053
2404
 
2054
- -- 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
+ ]]
2055
2408
  function Scribe.Configure(config: { AutoSaveInterval: number? })
2056
2409
  if type(config) ~= "table" then
2057
2410
  error("Scribe.Configure: config must be a table", 2)
@@ -2124,6 +2477,7 @@ Scribe.PurchaseReason = table.freeze({
2124
2477
  InsufficientFunds = "insufficient funds" :: Types.PurchaseReason,
2125
2478
  PaidRandomRestricted = "paid random items are not available for this account" :: Types.PurchaseReason,
2126
2479
  PolicyPending = "cannot check account settings right now; try again in a moment" :: Types.PurchaseReason,
2480
+ InvalidIdempotencyKey = "invalid IdempotencyKey" :: Types.PurchaseReason,
2127
2481
  })
2128
2482
 
2129
2483
  -- Fixed gift refusals; other failures may return diagnostic text.
@@ -2229,17 +2583,23 @@ Scribe.Visibility = table.freeze({
2229
2583
  -- Alias of Reason using the matching exported type name.
2230
2584
  Scribe.LifecycleReason = Scribe.Reason
2231
2585
 
2232
- -- 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
+ ]]
2233
2589
  function Scribe.GetProfileKeyPrefix(): string
2234
2590
  return Addons.ProfileKeyPrefix()
2235
2591
  end
2236
2592
 
2237
- -- Returns current DataStore health.
2593
+ --[[
2594
+ Returns current DataStore health.
2595
+ ]]
2238
2596
  function Scribe.GetStatus(): Status
2239
2597
  return Health.GetStatus()
2240
2598
  end
2241
2599
 
2242
- -- Returns cached board health without DataStore requests; empty on clients.
2600
+ --[[
2601
+ Returns cached board health without DataStore requests; empty on clients.
2602
+ ]]
2243
2603
  function Scribe.GetLeaderboardSnapshot(): { LeaderboardSnapshotEntry }
2244
2604
  return if RunService:IsServer() then LeaderboardDiagnostics.Snapshot() else {}
2245
2605
  end
@@ -2250,37 +2610,51 @@ Scribe.OnStatusChanged = Health.OnStatusChanged
2250
2610
  -- Fires for each Error or Fatal log entry.
2251
2611
  Scribe.OnIssue = Log.OnIssue
2252
2612
 
2253
- -- Adds a filtered, bounded log sink; returns its disconnect function.
2613
+ --[[
2614
+ Adds a filtered, bounded log sink; returns its disconnect function.
2615
+ ]]
2254
2616
  function Scribe.AddLogSink(fn: (entry: LogEntry) -> (), options: LogSinkOptions?): () -> ()
2255
2617
  return Log.AddSink(fn :: any, options)
2256
2618
  end
2257
2619
 
2258
- -- Registers plugin actions; returned cleanup removes only this registration.
2620
+ --[[
2621
+ Registers plugin actions; returned cleanup removes only this registration.
2622
+ ]]
2259
2623
  function Scribe.RegisterAddon(name: string, actions: Addons.Actions): () -> ()
2260
2624
  return Addons.Register(name, actions)
2261
2625
  end
2262
2626
 
2263
- -- 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
+ ]]
2264
2630
  function Scribe.GetRecentLogs(filter: Log.LogFilter?): { LogEntry }
2265
2631
  return Log.GetRecent(filter)
2266
2632
  end
2267
2633
 
2268
- -- Returns this context's counters and distribution summaries.
2634
+ --[[
2635
+ Returns this context's counters and distribution summaries.
2636
+ ]]
2269
2637
  function Scribe.GetMetrics(): { [string]: number | { Count: number, Average: number, Max: number } }
2270
2638
  return Metrics.Get()
2271
2639
  end
2272
2640
 
2273
- -- Returns recent distribution percentiles with sample age and window size.
2641
+ --[[
2642
+ Returns recent distribution percentiles with sample age and window size.
2643
+ ]]
2274
2644
  function Scribe.GetPercentiles(): { [string]: Metrics.Percentiles }
2275
2645
  return Metrics.GetPercentiles()
2276
2646
  end
2277
2647
 
2278
- -- 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
+ ]]
2279
2651
  function Scribe.GetBudgetSnapshot(): Budget.Snapshot
2280
2652
  return Budget.Snapshot()
2281
2653
  end
2282
2654
 
2283
- -- 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
+ ]]
2284
2658
  Scribe.new = buildBundle
2285
2659
 
2286
2660
  -- The metatable is attached through a cast so it stays invisible to the type