@rbxts/scribe 2.6.1 → 2.8.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
@@ -56,6 +56,7 @@ export type LeaderboardStatusInfo = Types.LeaderboardStatusInfo
56
56
  export type LeaderboardSnapshotEntry = Types.LeaderboardSnapshotEntry
57
57
  export type PassConfig = Types.PassConfig
58
58
  export type PurchaseFilter = Types.PurchaseFilter
59
+ export type PassTrial = Types.PassTrial
59
60
  export type EconomyMeta = Types.EconomyMeta
60
61
  export type EconomyConfig = Types.EconomyConfig
61
62
  export type EconomyCurrencyConfig = Types.EconomyCurrencyConfig
@@ -130,7 +131,8 @@ type AmountTags = {
130
131
 
131
132
  -- selene: allow(undefined_variable) -- `types` is the type-function runtime library
132
133
  -- "client" omits timer writes; "clientstore" omits all writes. Defaults to server.
133
- type function BuildValueType(T, Names: type?, Mode: type?)
134
+ -- "pair" builds T and ClientT with a shared node cache.
135
+ type function BuildNodes(T, Names: type?, Mode: type?, ClientT: type?)
134
136
  local ts = types
135
137
  local mode = if Mode ~= nil and Mode:is("singleton") then Mode:value() else nil
136
138
 
@@ -160,6 +162,16 @@ type function BuildValueType(T, Names: type?, Mode: type?)
160
162
  end
161
163
 
162
164
  local disconnectType = fn({}, {})
165
+ -- Share method types so Luau compares each signature once.
166
+ local clearFn = fn({ optBool }, {}, "Replicate")
167
+ local countFn = fn({}, { ts.number })
168
+ local recordChild = fn({ ts.unionof(ts.string, ts.number) }, { anyType }, "Key")
169
+ local optAny = optional(anyType)
170
+ local wideChildChanged = fn(
171
+ { fn({ ts.string, optAny, optAny }, {}, "ChildChange") },
172
+ { disconnectType },
173
+ "Listener"
174
+ )
163
175
 
164
176
  local function widen(t: type): type
165
177
  if t:is("singleton") then
@@ -244,33 +256,46 @@ type function BuildValueType(T, Names: type?, Mode: type?)
244
256
  return hasMarker(t, "__scribeBig")
245
257
  end
246
258
 
259
+ -- Canonical subtree key and maximum depth.
260
+ local signed: (t: type) -> (string?, number)
261
+ local function fits(depth: number, reach: number): boolean
262
+ return depth + reach + 2 <= MAX_DEPTH
263
+ end
264
+
247
265
  -- Timed and ServerOnly read back as a bare T, which may not be a table, so unlike
248
266
  -- the branded declarators their label has to be an ordinary field and a
249
267
  -- whole-subtree read strips it here. This only ever removes a wrapper, which is
250
268
  -- what keeps it cheap enough to run over every node.
251
269
  -- Inputs are read-only so a narrower caller type is accepted; a mutable property is
252
270
  -- invariant. Indexers are copied as is, since the runtime cannot make one read-only.
253
- local readOnlyCache: { [type]: type } = {}
271
+ -- Separate reads of the same shape can return distinct type objects.
272
+ local readOnlyCache: { [string]: type } = {}
254
273
  local function readOnlyDeep(t: type, depth: number): type
255
274
  if depth > MAX_DEPTH or not t:is("table") then
256
275
  return t
257
276
  end
258
- local cached = readOnlyCache[t]
259
- if cached ~= nil then
260
- return cached
277
+ local shape, reach = signed(t)
278
+ local shared = shape ~= nil and fits(depth, reach)
279
+ if shared then
280
+ local cached = readOnlyCache[shape :: string]
281
+ if cached ~= nil then
282
+ return cached
283
+ end
261
284
  end
262
285
  local indexer = t:indexer()
263
286
  local spec = if indexer ~= nil
264
287
  then { index = indexer.index, readresult = indexer.readresult, writeresult = indexer.writeresult }
265
288
  else nil
266
289
  local out = ts.newtable(nil, spec, t:metatable())
267
- readOnlyCache[t] = out
268
290
  for key, prop in t:properties() do
269
291
  local childType = prop.read or prop.write
270
292
  if childType ~= nil then
271
293
  out:setreadproperty(key, readOnlyDeep(childType, depth + 1))
272
294
  end
273
295
  end
296
+ if shared then
297
+ readOnlyCache[shape :: string] = out
298
+ end
274
299
  return out
275
300
  end
276
301
 
@@ -288,7 +313,7 @@ type function BuildValueType(T, Names: type?, Mode: type?)
288
313
  return marked
289
314
  end
290
315
 
291
- local unwrapCache: { [type]: type } = {}
316
+ local unwrapCache: { [string]: type } = {}
292
317
  local function unwrapWrappers(t: type, depth: number): type
293
318
  if depth > MAX_DEPTH then
294
319
  return t
@@ -300,12 +325,18 @@ type function BuildValueType(T, Names: type?, Mode: type?)
300
325
  if not t:is("table") then
301
326
  return t
302
327
  end
303
- local cached = unwrapCache[t]
304
- if cached ~= nil then
305
- return cached
328
+ local shape, reach = signed(t)
329
+ local shared = shape ~= nil and fits(depth, reach)
330
+ if shared then
331
+ local cached = unwrapCache[shape :: string]
332
+ if cached ~= nil then
333
+ return cached
334
+ end
306
335
  end
307
336
  local function memo(result: type): type
308
- unwrapCache[t] = result
337
+ if shared then
338
+ unwrapCache[shape :: string] = result
339
+ end
309
340
  return result
310
341
  end
311
342
  local timed = t:readproperty(ts.singleton("__scribeTimed"))
@@ -324,15 +355,18 @@ type function BuildValueType(T, Names: type?, Mode: type?)
324
355
  if hasMarker(t, "__scribeBig") or hasMarker(t, "__scribeFlags") then
325
356
  return memo(t)
326
357
  end
327
- local props: { [type]: type } = {}
358
+ local props: { { key: type, ty: type, read: boolean, write: boolean } } = {}
328
359
  local rebuilt = false
360
+ local nested = false
329
361
  for key, prop in t:properties() do
330
362
  local childType = prop.read or prop.write
331
363
  if childType ~= nil then
332
364
  local mapped = unwrapWrappers(childType, depth + 1)
333
- props[key] = mapped
365
+ table.insert(props, { key = key, ty = mapped, read = prop.read ~= nil, write = prop.write ~= nil })
334
366
  if mapped ~= childType then
335
367
  rebuilt = true
368
+ elseif mapped:is("table") then
369
+ nested = true
336
370
  end
337
371
  end
338
372
  end
@@ -345,11 +379,23 @@ type function BuildValueType(T, Names: type?, Mode: type?)
345
379
  rebuilt = true
346
380
  end
347
381
  end
348
- if not rebuilt then
382
+ -- Rebuild nested records to share cached children. Rebuilding an indexed type
383
+ -- can lose its read-only indexer, so keep it unless a child changed.
384
+ if not rebuilt and (indexer ~= nil or not nested or not shared) then
349
385
  return memo(t)
350
386
  end
351
387
  -- Preserve set and map brands.
352
- return memo(ts.newtable(props, spec, t:metatable()))
388
+ local out = ts.newtable(nil, spec, t:metatable())
389
+ for _, entry in props do
390
+ if entry.read and entry.write then
391
+ out:setproperty(entry.key, entry.ty)
392
+ elseif entry.read then
393
+ out:setreadproperty(entry.key, entry.ty)
394
+ else
395
+ out:setwriteproperty(entry.key, entry.ty)
396
+ end
397
+ end
398
+ return memo(out)
353
399
  end
354
400
 
355
401
  -- A canonical key for a subtree, so two identical subtrees are built once. A template
@@ -361,12 +407,16 @@ type function BuildValueType(T, Names: type?, Mode: type?)
361
407
  -- because an unknown tag fails the whole type function.
362
408
  local opaqueIds: { [type]: string } = {}
363
409
  local opaqueCount = 0
410
+ local sigReach = 0
364
411
  local signatureOf: (type, number, { [type]: boolean }) -> string?
365
412
  signatureOf = function(t: type, depth: number, seen: { [type]: boolean }): string?
366
413
  -- A cut-short walk or a cycle cannot be keyed.
367
414
  if depth > MAX_DEPTH + 2 or seen[t] then
368
415
  return nil
369
416
  end
417
+ if depth > sigReach then
418
+ sigReach = depth
419
+ end
370
420
  if t:is("singleton") then
371
421
  local value = t:value()
372
422
  return `s<{type(value)}:{tostring(value)}>`
@@ -381,8 +431,9 @@ type function BuildValueType(T, Names: type?, Mode: type?)
381
431
  end
382
432
  local parts: { string } = {}
383
433
  for key, prop in t:properties() do
384
- -- Signed separately: a field can differ in only one.
385
- local keySig, readSig, writeSig = sub(key), sub(prop.read), sub(prop.write)
434
+ -- Distinguish read and write types. Repeating identical signatures doubles the key at each level.
435
+ local keySig, readSig = sub(key), sub(prop.read)
436
+ local writeSig = if prop.read ~= nil and prop.read == prop.write then "=" else sub(prop.write)
386
437
  if keySig == nil or readSig == nil or writeSig == nil then
387
438
  seen[t] = nil
388
439
  return nil
@@ -394,7 +445,8 @@ type function BuildValueType(T, Names: type?, Mode: type?)
394
445
  local indexerSig = "-"
395
446
  local indexer = t:indexer()
396
447
  if indexer ~= nil then
397
- local i, r, w = sub(indexer.index), sub(indexer.readresult), sub(indexer.writeresult)
448
+ local i, r = sub(indexer.index), sub(indexer.readresult)
449
+ local w = if indexer.readresult == indexer.writeresult then "=" else sub(indexer.writeresult)
398
450
  if i == nil or r == nil or w == nil then
399
451
  seen[t] = nil
400
452
  return nil
@@ -415,6 +467,18 @@ type function BuildValueType(T, Names: type?, Mode: type?)
415
467
  seen[t] = nil
416
468
  return `t<{table.concat(parts, ",")};i:{indexerSig};m:{metaSig}>`
417
469
  end
470
+ -- Rendered unions can truncate or hide a table's shape.
471
+ if t:is("union") then
472
+ local parts: { string } = {}
473
+ for _, member in t:components() do
474
+ local memberSig = signatureOf(member, depth + 1, seen)
475
+ if memberSig == nil then
476
+ return nil
477
+ end
478
+ table.insert(parts, memberSig)
479
+ end
480
+ return `u<{table.concat(parts, "|")}>`
481
+ end
418
482
  -- Not a table, so its rendering is its structure and is short enough not to
419
483
  -- truncate.
420
484
  local rendered = tostring(t)
@@ -430,30 +494,44 @@ type function BuildValueType(T, Names: type?, Mode: type?)
430
494
  end
431
495
  return id
432
496
  end
497
+ signed = function(t: type): (string?, number)
498
+ sigReach = 0
499
+ local key = signatureOf(t, 0, {})
500
+ return key, sigReach
501
+ end
433
502
 
434
503
  local buildUncached: (type, boolean, number) -> type
435
- local buildCache: { [number]: { [string]: type } } = {}
504
+ local buildCache: { [string]: type } = {}
505
+ local deepCache: { [number]: { [string]: type } } = {}
436
506
  local function build(rawType: type, isRoot: boolean, depth: number): type
437
507
  -- Roots are never cached: isRoot changes what is emitted.
438
508
  if isRoot then
439
509
  return buildUncached(rawType, isRoot, depth)
440
510
  end
441
- local key = signatureOf(rawType, 0, {})
511
+ local key, reach = signed(rawType)
442
512
  if key == nil then
443
513
  return buildUncached(rawType, isRoot, depth)
444
514
  end
445
- -- Keyed by depth too, because MAX_DEPTH truncates.
446
- local atDepth = buildCache[depth]
447
- if atDepth == nil then
448
- atDepth = {}
449
- buildCache[depth] = atDepth
515
+ -- Timed fields have different server and client methods.
516
+ if string.find(key, "__scribeTimed", 1, true) ~= nil then
517
+ key = `{mode}@{key}`
518
+ end
519
+ -- Include depth only when MAX_DEPTH can truncate the subtree.
520
+ local cache = buildCache
521
+ if not fits(depth, reach) then
522
+ local atDepth = deepCache[depth]
523
+ if atDepth == nil then
524
+ atDepth = {}
525
+ deepCache[depth] = atDepth
526
+ end
527
+ cache = atDepth
450
528
  end
451
- local hit = atDepth[key]
529
+ local hit = cache[key]
452
530
  if hit ~= nil then
453
531
  return hit
454
532
  end
455
533
  local built = buildUncached(rawType, isRoot, depth)
456
- atDepth[key] = built
534
+ cache[key] = built
457
535
  return built
458
536
  end
459
537
  buildUncached = function(rawType: type, isRoot: boolean, depth: number): type
@@ -550,7 +628,14 @@ type function BuildValueType(T, Names: type?, Mode: type?)
550
628
  -- cannot do that: two ts.singleton("Remove") calls are distinct objects.
551
629
  local props: { { key: type, ty: type } } = {}
552
630
  local indexerSpec: { index: type, readresult: type, writeresult: type }? = nil
553
- local childLookups: { type } = {}
631
+ local lookups = 0
632
+ local onlyLookup: type? = nil
633
+ local function lookup(key: type, node: type)
634
+ lookups += 1
635
+ if lookups == 1 then
636
+ onlyLookup = fn({ key }, { node }, "Key")
637
+ end
638
+ end
554
639
 
555
640
  -- Strips a nested Timed / ServerOnly label, the one thing a read should not show.
556
641
  local valueType = unwrapWrappers(t, depth)
@@ -563,37 +648,33 @@ type function BuildValueType(T, Names: type?, Mode: type?)
563
648
  -- with the declared key type, and two ts.singleton("Remove") calls are distinct
564
649
  -- keys, so letting a map through here duplicates rather than overrides.
565
650
  if t:is("table") and mapKey == nil and not isTimed and not isFlags and not isSet and not isBig then
566
- for key, prop in t:properties() do
567
- local childType = prop.read or prop.write
568
- if childType ~= nil then
569
- local childNode = build(childType, false, depth + 1)
570
- table.insert(props, { key = key, ty = childNode })
571
- table.insert(childLookups, fn({ key }, { childNode }, "Key"))
572
- end
573
- end
574
-
575
651
  -- OnChildChanged reports an existing child's value moving, once per write
576
652
  -- and never coalesced, unlike Changed.
577
653
  local childKeys: { type } = {}
578
- local childValues: { type } = {}
654
+ local childTypes: { type } = {}
579
655
  for key, prop in t:properties() do
580
656
  local childType = prop.read or prop.write
581
657
  if childType ~= nil then
658
+ local childNode = build(childType, false, depth + 1)
659
+ table.insert(props, { key = key, ty = childNode })
660
+ lookup(key, childNode)
582
661
  table.insert(childKeys, key)
583
- table.insert(childValues, unwrapWrappers(widen(childType), depth + 1))
662
+ table.insert(childTypes, childType)
584
663
  end
585
664
  end
586
665
 
587
666
  local indexer = t:indexer()
667
+ local elementValue: type? = nil
588
668
  if indexer ~= nil then
589
669
  -- Read values exclude nested markers.
590
670
  local elementType = unwrapWrappers(widen(indexer.readresult), depth + 1)
591
671
  local elementIn = readOnlyDeep(elementType, depth + 1)
672
+ local optElement = optional(elementType)
592
673
  if indexer.index:is("number") then
593
674
  -- Array node: the indexer makes `arr[i]` an accessor node, which is
594
675
  -- the only way to reach a Scribe.ArrayOf element field.
595
676
  local elemNode = build(indexer.readresult, false, depth + 1)
596
- table.insert(childLookups, fn({ indexer.index }, { elemNode }, "Key"))
677
+ lookup(indexer.index, elemNode)
597
678
  indexerSpec = {
598
679
  index = indexer.index,
599
680
  readresult = elemNode,
@@ -602,60 +683,65 @@ type function BuildValueType(T, Names: type?, Mode: type?)
602
683
  if writable then
603
684
  add("Insert", fn({ elementIn, optNumber, optBool }, {}, "Insert"))
604
685
  -- 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"))
686
+ add("Remove", fn({ optNumber, optBool }, { optElement }, "RemoveIndex"))
687
+ add("RemoveValue", fn({ elementIn, optBool }, { optElement, optNumber }, "Set"))
607
688
  end
608
689
  add("Find", fn({ elementIn }, { optNumber }, "Value"))
609
690
  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")
691
+ local onIndexed = fn(
692
+ { fn({ elementType, ts.number }, {}, "IndexedValue") },
693
+ { disconnectType },
694
+ "Listener"
617
695
  )
696
+ add("OnInsert", onIndexed)
697
+ add("OnRemove", onIndexed)
618
698
  else
619
699
  -- Dictionary node: children are accessor nodes.
620
700
  local childNode = build(indexer.readresult, false, depth + 1)
621
- table.insert(childLookups, fn({ indexer.index }, { childNode }, "Key"))
701
+ lookup(indexer.index, childNode)
622
702
  indexerSpec = {
623
703
  index = indexer.index,
624
704
  readresult = childNode,
625
705
  writeresult = childNode,
626
706
  }
627
707
  if writable then
628
- add("Remove", fn({ ts.string, optBool }, { optional(elementType) }, "RemoveKey"))
708
+ add("Remove", fn({ ts.string, optBool }, { optElement }, "RemoveKey"))
629
709
  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")
710
+ local onKey = fn(
711
+ { fn({ indexer.index, elementType }, {}, "KeyValue") },
712
+ { disconnectType },
713
+ "Listener"
637
714
  )
715
+ add("OnKeyAdded", onKey)
716
+ add("OnKeyRemoved", onKey)
638
717
  end
639
718
  if writable then
640
- add("Clear", fn({ optBool }, {}, "Replicate"))
719
+ add("Clear", clearFn)
641
720
  end
642
- add("Count", fn({}, { ts.number }))
721
+ add("Count", countFn)
643
722
  -- A dynamic container's children are homogeneous, so the key and value
644
723
  -- types here are exact rather than a union over declared fields.
645
724
  table.insert(childKeys, indexer.index)
646
- table.insert(childValues, elementType)
725
+ elementValue = elementType
647
726
  end
648
727
 
649
- if #childKeys > 0 then
728
+ if #childKeys > MAX_CHILD_UNION then
729
+ -- Past MAX_CHILD_UNION the pair is widened; a growing union is what exceeds the budget.
730
+ add("OnChildChanged", wideChildChanged)
731
+ elseif #childKeys > 0 then
650
732
  -- (key, new, old), matching Changed's new-first order. Both values are
651
733
  -- optional: an added key has no old, a removed key has no new. On a
652
734
  -- heterogeneous static table they widen to a union Luau will not narrow from
653
735
  -- the key, which is accepted; that node kind has exact per-field listeners.
654
- -- Past MAX_CHILD_UNION the pair is widened; a growing union is what exceeds the budget.
655
- local childKey = if #childKeys > MAX_CHILD_UNION then ts.string else ts.unionof(table.unpack(childKeys))
656
- local childValue = if #childValues > MAX_CHILD_UNION
657
- then optional(anyType)
658
- else optional(ts.unionof(table.unpack(childValues)))
736
+ local childValues: { type } = {}
737
+ for _, childType in childTypes do
738
+ table.insert(childValues, unwrapWrappers(widen(childType), depth + 1))
739
+ end
740
+ if elementValue ~= nil then
741
+ table.insert(childValues, elementValue)
742
+ end
743
+ local childKey = ts.unionof(table.unpack(childKeys))
744
+ local childValue = optional(ts.unionof(table.unpack(childValues)))
659
745
  add(
660
746
  "OnChildChanged",
661
747
  fn({ fn({ childKey, childValue, childValue }, {}, "ChildChange") }, { disconnectType }, "Listener")
@@ -667,40 +753,39 @@ type function BuildValueType(T, Names: type?, Mode: type?)
667
753
  -- A map's children are accessor nodes keyed by the declared type; the key
668
754
  -- events and Remove carry the element rather than the whole map.
669
755
  local element = mapElement :: type
756
+ local optElement = optional(element)
670
757
  local childNode = build(mapValue :: type, false, depth + 1)
671
- table.insert(childLookups, fn({ mapKey }, { childNode }, "Key"))
758
+ lookup(mapKey, childNode)
672
759
  indexerSpec = { index = mapKey, readresult = childNode, writeresult = childNode }
673
760
  if writable then
674
- add("Remove", fn({ mapKey, optBool }, { optional(element) }, "RemoveKey"))
761
+ add("Remove", fn({ mapKey, optBool }, { optElement }, "RemoveKey"))
675
762
  end
676
- add("OnKeyAdded", fn({ fn({ mapKey, element }, {}, "KeyValue") }, { disconnectType }, "Listener"))
677
- add("OnKeyRemoved", fn({ fn({ mapKey, element }, {}, "KeyValue") }, { disconnectType }, "Listener"))
763
+ local onKey = fn({ fn({ mapKey, element }, {}, "KeyValue") }, { disconnectType }, "Listener")
764
+ add("OnKeyAdded", onKey)
765
+ add("OnKeyRemoved", onKey)
678
766
  add(
679
767
  "OnChildChanged",
680
- fn(
681
- { fn({ mapKey, optional(element), optional(element) }, {}, "ChildChange") },
682
- { disconnectType },
683
- "Listener"
684
- )
768
+ fn({ fn({ mapKey, optElement, optElement }, {}, "ChildChange") }, { disconnectType }, "Listener")
685
769
  )
686
770
  if writable then
687
- add("Clear", fn({ optBool }, {}, "Replicate"))
771
+ add("Clear", clearFn)
688
772
  end
689
- add("Count", fn({}, { ts.number }))
773
+ add("Count", countFn)
690
774
  end
691
775
 
692
776
  -- A homogeneous container keeps the exact child type. Static records use
693
777
  -- an untyped lookup: overloads duplicate every recursive child node in the
694
778
  -- callable surface and push ordinary templates past the Luau solver budget.
695
779
  -- Direct property access remains exact; TypeScript can type this lookup too.
696
- if #childLookups == 1 then
697
- add("Child", childLookups[1])
698
- elseif #childLookups > 1 then
699
- add("Child", fn({ ts.unionof(ts.string, ts.number) }, { anyType }, "Key"))
780
+ if lookups == 1 then
781
+ add("Child", onlyLookup :: type)
782
+ elseif lookups > 1 then
783
+ add("Child", recordChild)
700
784
  end
701
785
 
702
786
  -- Common node methods.
703
- add("Get", fn({}, { valueType }))
787
+ local reader = fn({}, { valueType })
788
+ add("Get", reader)
704
789
  -- The root accessor cannot be Set or Updated at runtime, so those are left off the
705
790
  -- root type. A big field declares its own wider Set and Update below; adding them
706
791
  -- here too would duplicate rather than override, as the singletons are distinct keys.
@@ -715,8 +800,8 @@ type function BuildValueType(T, Names: type?, Mode: type?)
715
800
  add("Set", fn({ writeIn, optBool }, { valueType }, "Set"))
716
801
  add("Update", fn({ fn({ valueType }, { writeIn }, "Value"), optBool }, { valueType }, "Update"))
717
802
  end
718
- add("Clone", fn({}, { valueType }))
719
- add("Default", fn({}, { valueType }))
803
+ add("Clone", reader)
804
+ add("Default", reader)
720
805
  -- (new, old) on every node. On a container it reports state, coalesced to one
721
806
  -- fire per batch or received frame; which child moved is OnChildChanged's job.
722
807
  add("Changed", fn({ fn({ valueType, valueType }, {}, "Change") }, { disconnectType }, "Listener"))
@@ -742,11 +827,13 @@ type function BuildValueType(T, Names: type?, Mode: type?)
742
827
  -- Min/Max read the declared bounds, so they stay on a derived field; the
743
828
  -- two mutators do not.
744
829
  if writable then
745
- add("Increment", fn({ ts.number, amountOptions }, { ts.number }, "Increment"))
746
- add("Decrement", fn({ ts.number, amountOptions }, { ts.number }, "Increment"))
830
+ local step = fn({ ts.number, amountOptions }, { ts.number }, "Increment")
831
+ add("Increment", step)
832
+ add("Decrement", step)
747
833
  end
748
- add("Min", fn({}, { optNumber }))
749
- add("Max", fn({}, { optNumber }))
834
+ local bound = fn({}, { optNumber })
835
+ add("Min", bound)
836
+ add("Max", bound)
750
837
  elseif scalar:is("boolean") and writable then
751
838
  add("Toggle", fn({ optBool }, { ts.boolean }, "Replicate"))
752
839
  end
@@ -758,16 +845,18 @@ type function BuildValueType(T, Names: type?, Mode: type?)
758
845
  local operand = ts.unionof(ts.number, ts.string, valueType)
759
846
  add("Set", fn({ operand, optBool }, { valueType }, "Set"))
760
847
  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"))
848
+ local step = fn({ operand, amountOptions }, { valueType }, "Increment")
849
+ add("Increment", step)
850
+ add("Decrement", step)
851
+ local scale = fn({ operand, optBool }, { valueType }, "Set")
852
+ add("Multiply", scale)
853
+ add("Divide", scale)
765
854
  end
766
855
  -- A big bound past the double range is only expressible as a numeric string,
767
856
  -- so these return the same union the declarator accepts.
768
- local optBound = optional(ts.unionof(ts.number, ts.string))
769
- add("Min", fn({}, { optBound }))
770
- add("Max", fn({}, { optBound }))
857
+ local bound = fn({}, { optional(ts.unionof(ts.number, ts.string)) })
858
+ add("Min", bound)
859
+ add("Max", bound)
771
860
  end
772
861
 
773
862
  if isSet then
@@ -778,22 +867,24 @@ type function BuildValueType(T, Names: type?, Mode: type?)
778
867
  else anyType
779
868
  local elementIn = readOnlyDeep(element, depth + 1)
780
869
  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"))
870
+ local member = fn({ elementIn, optBool }, { ts.boolean }, "Set")
871
+ add("Add", member)
872
+ add("Remove", member)
873
+ add("Clear", clearFn)
784
874
  end
785
875
  add("Has", fn({ elementIn }, { ts.boolean }, "Value"))
786
876
  add("Find", fn({ elementIn }, { optNumber }, "Value"))
787
- add("Count", fn({}, { ts.number }))
877
+ add("Count", countFn)
788
878
  end
789
879
 
790
880
  if isFlags then
791
881
  -- Named-member surface. Get/Set still take the whole { string } set.
792
882
  if writable then
793
- add("Enable", fn({ ts.string, optBool }, {}, "FlagWrite"))
794
- add("Disable", fn({ ts.string, optBool }, {}, "FlagWrite"))
883
+ local switch = fn({ ts.string, optBool }, {}, "FlagWrite")
884
+ add("Enable", switch)
885
+ add("Disable", switch)
795
886
  add("Toggle", fn({ ts.string, optBool }, { ts.boolean }, "FlagWrite"))
796
- add("Clear", fn({ optBool }, {}, "Replicate"))
887
+ add("Clear", clearFn)
797
888
  end
798
889
  add("Has", fn({ ts.string }, { ts.boolean }, "Flag"))
799
890
  end
@@ -817,9 +908,23 @@ type function BuildValueType(T, Names: type?, Mode: type?)
817
908
  return out
818
909
  end
819
910
 
911
+ if mode == "pair" and ClientT ~= nil then
912
+ local halves = ts.newtable(nil, nil, nil)
913
+ mode = "server"
914
+ halves:setproperty(ts.singleton("Server"), build(T, true, 0))
915
+ mode = "client"
916
+ halves:setproperty(ts.singleton("Client"), build(ClientT, true, 0))
917
+ return halves
918
+ end
919
+
820
920
  return build(T, true, 0)
821
921
  end
822
922
 
923
+ -- selene: allow(undefined_variable)
924
+ type function BuildValueType(T, Names: type?, Mode: type?)
925
+ return BuildNodes(T, Names, Mode, nil)
926
+ end
927
+
823
928
  -- Keep the original type-function arity for existing callers.
824
929
  -- selene: allow(undefined_variable)
825
930
  export type function ValueType(T)
@@ -1049,6 +1154,7 @@ type ServerApiNames = {
1049
1154
  TryHandleReceipt: (receiptInfo: any) -> (),
1050
1155
  Owns: (player: any, key: any) -> (),
1051
1156
  OwnsAsync: (player: any, key: any, timeout: any) -> (),
1157
+ GetTrial: (player: any, key: any) -> (),
1052
1158
  ObserveOwned: (player: any, key: any, callback: any) -> (),
1053
1159
  GrantPerk: (player: any, key: any) -> (),
1054
1160
  RevokePerk: (player: any, key: any) -> (),
@@ -1073,6 +1179,7 @@ type ClientApiNames = {
1073
1179
  GetShared: (playerOrUserId: any) -> (),
1074
1180
  Owns: (key: any) -> (),
1075
1181
  OwnsAsync: (key: any, timeout: any) -> (),
1182
+ GetTrial: (key: any) -> (),
1076
1183
  ObserveOwned: (key: any, callback: any) -> (),
1077
1184
  GetPurchases: (filter: any) -> (),
1078
1185
  GetProductInfo: (name: any) -> (),
@@ -1122,7 +1229,7 @@ end
1122
1229
  -- rather than `ValueType<T> & { ... }`, because normalizing an intersection over a
1123
1230
  -- large accessor tree exceeds the solver's budget at the Scribe() call site.
1124
1231
  -- selene: allow(undefined_variable)
1125
- type function BuildClientDataType(T, S, Names: type?)
1232
+ type function BuildClientApi(T, S, Names: type?, Node: type?)
1126
1233
  local ts = types
1127
1234
 
1128
1235
  local function optional(t: type): type
@@ -1167,7 +1274,7 @@ type function BuildClientDataType(T, S, Names: type?)
1167
1274
  saveInfoProps[ts.singleton("Size")] = optional(ts.number)
1168
1275
  local saveInfo = ts.newtable(saveInfoProps, nil, nil)
1169
1276
 
1170
- local out = ts.copy(BuildValueType(StripServerOnly(T), Names, ts.singleton("client")))
1277
+ local out = if Node ~= nil then Node else ts.copy(BuildValueType(StripServerOnly(T), Names, ts.singleton("client")))
1171
1278
  -- Read-only members avoid invariant type comparisons.
1172
1279
  local function add(name: string, ty: type)
1173
1280
  local prototype = if ty:is("function") then ClientApiNames:readproperty(ts.singleton(name)) else nil
@@ -1198,7 +1305,10 @@ type function BuildClientDataType(T, S, Names: type?)
1198
1305
  add("OnSharedChanged", ts.any)
1199
1306
  add("Owns", fn({ ts.string }, { ts.boolean }))
1200
1307
  add("OwnsAsync", fn({ ts.string, optional(ts.number) }, { ts.boolean }))
1201
- add("ObserveOwned", fn({ ts.string, fn({ ts.boolean }, {}) }, { fn({}, {}) }))
1308
+ local passTrialProps: { [type]: type } = {}
1309
+ passTrialProps[ts.singleton("EndsAt")] = optional(ts.number)
1310
+ add("GetTrial", fn({ ts.string }, { optional(ts.newtable(passTrialProps, nil, nil)) }))
1311
+ add("ObserveOwned", fn({ ts.string, fn({ ts.boolean, ts.boolean }, {}) }, { fn({}, {}) }))
1202
1312
  add("OnOwnershipChanged", ts.any)
1203
1313
  add("GetSaveInfo", fn({}, { saveInfo }))
1204
1314
  add("GetGiftCredits", fn({}, { stringToNumber }))
@@ -1232,19 +1342,55 @@ type function BuildClientDataType(T, S, Names: type?)
1232
1342
  return out
1233
1343
  end
1234
1344
 
1345
+ -- selene: allow(undefined_variable)
1346
+ type function BuildClientDataType(T, S, Names: type?)
1347
+ return BuildClientApi(T, S, Names, nil)
1348
+ end
1349
+
1235
1350
  -- selene: allow(undefined_variable)
1236
1351
  export type function ClientDataType(T)
1237
1352
  return BuildClientDataType(T, types.any, nil)
1238
1353
  end
1239
1354
 
1355
+ -- A type alias supplies the read-only player indexer so Luau compares each node one way.
1356
+ -- Pass both halves together because separate type arguments are copied independently.
1357
+ type BundleSeed<P, Halves> = {
1358
+ Server: { read [P]: index<Halves, "Server"> },
1359
+ Client: index<Halves, "Client">,
1360
+ }
1361
+
1362
+ -- selene: allow(undefined_variable)
1363
+ type function BuildBundleSeed(P: type, Halves: type): type
1364
+ local ts = types
1365
+ local seed = BundleSeed(P, Halves)
1366
+ local server = seed:readproperty(ts.singleton("Server"))
1367
+ if server ~= nil and server:indexer() ~= nil then
1368
+ return seed
1369
+ end
1370
+ -- Older analyzers drop read-only indexers. Restore player lookup for them.
1371
+ local node = Halves:readproperty(ts.singleton("Server")) :: type
1372
+ local out = ts.newtable(nil, nil, nil)
1373
+ out:setproperty(ts.singleton("Server"), ts.newtable(nil, { index = P, readresult = node, writeresult = node }, nil))
1374
+ out:setproperty(ts.singleton("Client"), Halves:readproperty(ts.singleton("Client")))
1375
+ return out
1376
+ end
1377
+
1240
1378
  -- The server `Data` API. P is the Player class type, passed in as a type argument
1241
1379
  -- because class types are not constructible inside a type function. A type function
1242
1380
  -- for the same complexity-budget reason as ClientDataType.
1243
1381
  -- selene: allow(undefined_variable)
1244
- type function BuildServerDataType(T, P, S, Names: type?)
1382
+ type function BuildServerApi(T, P, S, Names: type?, Indexed: type?)
1245
1383
  local ts = types
1246
1384
 
1247
- local node = BuildValueType(T, Names)
1385
+ local seeded = Indexed
1386
+ if seeded == nil then
1387
+ local halves = ts.newtable(nil, nil, nil)
1388
+ halves:setproperty(ts.singleton("Server"), BuildValueType(T, Names))
1389
+ halves:setproperty(ts.singleton("Client"), ts.any)
1390
+ seeded = BuildBundleSeed(P, halves):readproperty(ts.singleton("Server"))
1391
+ end
1392
+ local api = seeded :: type
1393
+ local node = (api:indexer() :: { readresult: type }).readresult
1248
1394
 
1249
1395
  local function optional(t: type): type
1250
1396
  return ts.unionof(t, ts.singleton(nil))
@@ -1409,13 +1555,15 @@ type function BuildServerDataType(T, P, S, Names: type?)
1409
1555
  add("TryHandleReceipt", fn({ ts.any }, { optional(ts.any) }))
1410
1556
  add("Owns", fn({ P, ts.string }, { ts.boolean }))
1411
1557
  add("OwnsAsync", fn({ P, ts.string, optional(ts.number) }, { ts.boolean }))
1412
- add("ObserveOwned", fn({ P, ts.string, fn({ ts.boolean }, {}) }, { fn({}, {}) }))
1558
+ local passTrialProps: { [type]: type } = {}
1559
+ passTrialProps[ts.singleton("EndsAt")] = optional(ts.number)
1560
+ add("GetTrial", fn({ P, ts.string }, { optional(ts.newtable(passTrialProps, nil, nil)) }))
1561
+ add("ObserveOwned", fn({ P, ts.string, fn({ ts.boolean, ts.boolean }, {}) }, { fn({}, {}) }))
1413
1562
  add("OnOwnershipChanged", ts.any)
1414
1563
  add("GrantPerk", fn({ P, ts.string }, {}))
1415
1564
  add("RevokePerk", fn({ P, ts.string }, {}))
1416
1565
 
1417
- -- Purchase spec: Cost.Path is the template's numeric-leaf path union and
1418
- -- Grant receives the typed accessor tree.
1566
+ -- Cost.Path accepts numeric leaves. Grant receives the typed tree and player.
1419
1567
  local costProps: { [type]: type } = {}
1420
1568
  -- Include Big currency paths.
1421
1569
  costProps[ts.singleton("Path")] = StatPathsType(T, ts.singleton(true))
@@ -1425,11 +1573,16 @@ type function BuildServerDataType(T, P, S, Names: type?)
1425
1573
  purchaseProps[ts.singleton("Cost")] = ts.newtable(costProps, nil, nil)
1426
1574
  purchaseProps[ts.singleton("Category")] = optional(ts.string)
1427
1575
  purchaseProps[ts.singleton("ItemId")] = ts.string
1428
- purchaseProps[ts.singleton("Grant")] = optional(fn({ node }, {}))
1576
+ purchaseProps[ts.singleton("Grant")] = optional(fn({ node, P }, {}))
1429
1577
  purchaseProps[ts.singleton("Meta")] = optAnyTable
1430
1578
  purchaseProps[ts.singleton("IdempotencyKey")] = optional(ts.string)
1431
1579
  purchaseProps[ts.singleton("PaidRandom")] = optional(ts.boolean)
1432
- add("Purchase", fn({ P, ts.newtable(purchaseProps, nil, nil) }, boolAndReason))
1580
+ -- Read-only inputs avoid an invariant comparison of Grant's accessor tree.
1581
+ local purchaseSpec = ts.newtable(nil, nil, nil)
1582
+ for key, ty in purchaseProps do
1583
+ purchaseSpec:setreadproperty(key, ty)
1584
+ end
1585
+ add("Purchase", fn({ P, purchaseSpec }, boolAndReason))
1433
1586
  add("RecordPurchase", fn({ P, anyTable }, {}))
1434
1587
  -- OpenLeg and OpenExchange are rebuilt here: a type function cannot reach an alias.
1435
1588
  local openLegProps: { [type]: type } = {}
@@ -1498,18 +1651,35 @@ type function BuildServerDataType(T, P, S, Names: type?)
1498
1651
  add("ServerStore", StoreDataType(S, Names))
1499
1652
 
1500
1653
  -- Read-only members avoid invariant type comparisons.
1501
- local api = ts.newtable(nil, { index = P, readresult = node, writeresult = node }, nil)
1502
1654
  for key, ty in props do
1503
1655
  api:setreadproperty(key, ty)
1504
1656
  end
1505
1657
  return api
1506
1658
  end
1507
1659
 
1660
+ -- selene: allow(undefined_variable)
1661
+ type function BuildServerDataType(T, P, S, Names: type?)
1662
+ return BuildServerApi(T, P, S, Names, nil)
1663
+ end
1664
+
1508
1665
  -- selene: allow(undefined_variable)
1509
1666
  export type function ServerDataType(T, P)
1510
1667
  return BuildServerDataType(T, P, types.any, nil)
1511
1668
  end
1512
1669
 
1670
+ -- Sharing nodes across both APIs reduces the cost of checking a Scribe() call.
1671
+ -- selene: allow(undefined_variable)
1672
+ type function BuildBundleType(T, P, S, Names: type?)
1673
+ local ts = types
1674
+ local seed = BuildBundleSeed(P, BuildNodes(T, Names, ts.singleton("pair"), StripServerOnly(T)))
1675
+ local server = seed:readproperty(ts.singleton("Server"))
1676
+ local client = seed:readproperty(ts.singleton("Client"))
1677
+ local out = ts.newtable(nil, nil, nil)
1678
+ out:setreadproperty(ts.singleton("Server"), BuildServerApi(T, P, S, Names, server))
1679
+ out:setreadproperty(ts.singleton("Client"), BuildClientApi(T, S, Names, client))
1680
+ return out
1681
+ end
1682
+
1513
1683
  --------------------------------------------------------------------------------
1514
1684
  -- Typed field declarators
1515
1685
  --------------------------------------------------------------------------------
@@ -1541,8 +1711,9 @@ export type CFrameMeta = { Precision: "exact"? }
1541
1711
  -- Container declarator options. Not generic in the element type on purpose: an
1542
1712
  -- element-typed option would let Luau infer the element type from it rather than
1543
1713
  -- from `shape`, silently redefining the field.
1544
- export type ArrayOpts = { MaxItems: number?, Evict: ("Front" | "Back")? }
1545
- export type SetOpts = { MaxItems: number? }
1714
+ -- Read-only fields accept partial option literals.
1715
+ export type ArrayOpts = { read MaxItems: number?, read Evict: ("Front" | "Back")? }
1716
+ export type SetOpts = { read MaxItems: number? }
1546
1717
  export type CooldownOptions = { IncludeOfflineTime: boolean? }
1547
1718
  export type MapKeyType = "integer" | "string"
1548
1719
  -- What a Scribe.Big field reads back, which is also what the declarator returns.
@@ -1617,7 +1788,7 @@ type function MapShape(K, V)
1617
1788
  return out
1618
1789
  end
1619
1790
  export type MapOf<K, V> = MapShape<K, V>
1620
- export type DictOpts = { MaxKeys: number?, MaxKeyLength: number? }
1791
+ export type DictOpts = { read MaxKeys: number?, read MaxKeyLength: number? }
1621
1792
 
1622
1793
  -- Template-aware config types. Annotate a config local with one and `Stat` / `Cost.Path`
1623
1794
  -- become the template's numeric leaf-path union while `Grant` receives the typed accessor
@@ -1643,7 +1814,7 @@ export type LeaderboardConfig<T = any> = {
1643
1814
  export type ProductConfig<T = any> = {
1644
1815
  Id: number,
1645
1816
  Category: string?,
1646
- Grant: ((data: BuildGrantDataType<T, NodeFunctionNames>) -> ())?,
1817
+ Grant: ((data: BuildGrantDataType<T, NodeFunctionNames>, player: Player) -> ())?,
1647
1818
  Grants: string?,
1648
1819
  PaidRandom: boolean?,
1649
1820
  }
@@ -1653,7 +1824,7 @@ export type PurchaseSpec<T = any> = {
1653
1824
  Cost: { Path: StatPathsType<T, true>, Amount: number | string | BigValue },
1654
1825
  Category: string?,
1655
1826
  ItemId: string,
1656
- Grant: ((data: BuildGrantDataType<T, NodeFunctionNames>) -> ())?,
1827
+ Grant: ((data: BuildGrantDataType<T, NodeFunctionNames>, player: Player) -> ())?,
1657
1828
  Meta: { [string]: any }?,
1658
1829
  IdempotencyKey: string?,
1659
1830
  PaidRandom: boolean?,
@@ -1680,7 +1851,7 @@ type LeaderboardConfigLoose = {
1680
1851
  type ProductConfigLoose = {
1681
1852
  read Id: number,
1682
1853
  read Category: string?,
1683
- read Grant: ((data: any) -> ())?,
1854
+ read Grant: ((data: any, player: Player) -> ())?,
1684
1855
  read Grants: string?,
1685
1856
  read PaidRandom: boolean?,
1686
1857
  }
@@ -1717,6 +1888,7 @@ export type ScribeOptions<T, S = any> = {
1717
1888
 
1718
1889
  Migrations: { [number]: (data: { [string]: any }) -> () }?,
1719
1890
  UserOwnsGamePassAsync: ((userId: number, passId: number) -> boolean)?, -- advanced/test seam
1891
+ GetPassOwnershipAsync: ((player: Player, passId: number) -> { [string]: any })?, -- advanced/test seam
1720
1892
  GetProductInfoAsync: ((assetId: number, infoType: any) -> { [string]: any }?)?, -- advanced/test seam
1721
1893
  GetPolicyInfoAsync: ((player: Player) -> { [string]: any }?)?, -- advanced/test seam
1722
1894
  DevMode: boolean?, -- advanced/test seam: overrides the RunService:IsStudio() default
@@ -1836,11 +2008,7 @@ export type ClientData<T, S = any> = BuildClientDataType<T, S, NodeFunctionNames
1836
2008
  -- cannot be called across modules: Scribe.ValueType<T> would resolve to any.
1837
2009
  export type PlayerData<T> = BuildValueType<T, NodeFunctionNames, "server">
1838
2010
 
1839
- -- Read-only halves avoid invariant comparisons that exhaust the type budget.
1840
- export type Bundle<T, S = any> = {
1841
- read Server: ServerData<T, S>,
1842
- read Client: ClientData<T, S>,
1843
- }
2011
+ export type Bundle<T, S = any> = BuildBundleType<T, Player, S, NodeFunctionNames>
1844
2012
 
1845
2013
  --------------------------------------------------------------------------------
1846
2014
  -- Exported type reference
@@ -1863,6 +2031,7 @@ local KNOWN_OPTION_KEYS: { [string]: boolean } = {
1863
2031
  TransportChannel = true,
1864
2032
  Migrations = true,
1865
2033
  UserOwnsGamePassAsync = true,
2034
+ GetPassOwnershipAsync = true,
1866
2035
  GetProductInfoAsync = true,
1867
2036
  GetPolicyInfoAsync = true,
1868
2037
  DevMode = true,