@axpecter/lync 2.1.2 → 2.2.1

package/src/index.d.ts

@@ -141,7 +141,7 @@ interface LyncModule {
 
     configure(this: void, options: Lync.ConfigureOptions): void;
     start(this: void): void;
-    readonly started: boolean;
+    isStarted(this: void): boolean;
 
     // ── Definitions ─────────────────────────────────────────────────
 
@@ -253,7 +253,13 @@ interface LyncModule {
 
     enum<T extends string[]>(this: void, ...values: T): Lync.Codec<T[number]>;
     bitfield(this: void, schema: Record<string, { type: "bool" } | { type: "uint"; width: number } | { type: "int"; width: number }>): Lync.Codec<Record<string, boolean | number>>;
-    custom<T>(this: void, size: number, write: (b: buffer, offset: number, value: T) => void, read: (b: buffer, offset: number) => T): Lync.Codec<T>;
+    custom<T>(
+        this: void,
+        size: number,
+        write: (b: buffer, offset: number, value: T) => void,
+        read: (b: buffer, offset: number) => T,
+        typeCheck?: string,
+    ): Lync.Codec<T>;
     readonly nothing: Lync.Codec<undefined>;
     readonly unknown: Lync.Codec<unknown>;
     readonly auto: Lync.Codec<unknown>;

package/src/init.luau

@@ -15,8 +15,8 @@ local Query = require(script.api.Query)
 local Registry = require(script.internal.Registry)
 local Scope = require(script.api.Scope)
 local Types = require(script.Types)
+local Util = require(script.internal.Util)
 
--- Codecs
 local ArrayC = require(script.codec.composite.Array)
 local AutoC = require(script.codec.meta.Auto)
 local BitfieldC = require(script.codec.meta.Bitfield)
@@ -48,108 +48,138 @@ local UDimC = require(script.codec.datatype.UDim)
 local UnknownC = require(script.codec.meta.Unknown)
 local VectorC = require(script.codec.datatype.Vector)
 
--- Constants -----------------------------------------------------------
+-- Public types (re-exported so users can write `Lync.Packet<MyData>`) ---
 
-local IS_SERVER = RunService:IsServer()
-
--- State ---------------------------------------------------------------
+export type Codec<T> = Types.Codec<T>
+export type Connection = Types.Connection
+export type Packet<T> = Packet.PacketHandle<T>
+export type Query<Req, Resp> = Query.QueryHandle<Req, Resp>
+export type Group = Group.GroupHandle
+export type Scope = Scope.ScopeHandle
+export type PacketOptions = Types.PacketOptions
+export type QueryOptions = Types.QueryOptions
+export type ConfigureOptions = Types.ConfigureOptions
+export type RateLimitConfig = Types.RateLimitConfig
+export type PacketStats = Types.PacketStats
+export type PlayerStats = Types.PlayerStats
 
-local _started = false
-local _flushRate = 60
-local _flushAccum = 0
-local _flushConn: RBXScriptConnection? = nil
+-- Constants --------------------------------------------------------------
 
--- Private -------------------------------------------------------------
+local IS_SERVER = RunService:IsServer()
 
 local DROP = table.freeze({ _lyncDrop = true })
 local ALL = table.freeze({ _lyncAll = true })
 
+local CHANNEL_MAX_MIN, CHANNEL_MAX_MAX = 4096, 1048576
+local DEPTH_MIN, DEPTH_MAX = 4, 32
+local POOL_MIN, POOL_MAX = 2, 128
+local FLUSH_HZ_MIN, FLUSH_HZ_MAX = 1, 60
+
+-- State ------------------------------------------------------------------
+
+--[[
+    Wrap mutable flush state in one table so the Heartbeat closure
+    captures a single LCT_VAL upvalue instead of separate LCT_REF
+    upvalues for each field.
+]]
+local _flushState = {
+    started = false,
+    rate = FLUSH_HZ_MAX,
+    accum = 0,
+    conn = nil :: RBXScriptConnection?,
+    transport = nil :: { flush: () -> () }?,
+}
+
+-- Private ----------------------------------------------------------------
+
+local isPlayer = Util.isPlayer
+
 local function except(...: any): any
     local excluded: { [Player]: boolean } = {}
 
     for i = 1, select("#", ...) do
         local arg = select(i, ...)
-        if typeof(arg) == "Instance" and (arg :: Instance):IsA("Player") then
+        if isPlayer(arg) then
             excluded[arg :: Player] = true
-        elseif typeof(arg) == "table" and (arg :: any)._lyncGroup then
-            for player in (arg :: any)._members do
+        elseif typeof(arg) == "table" and arg._lyncGroup then
+            for player in arg._members :: { [Player]: boolean } do
                 excluded[player] = true
             end
         else
-            error("[Lync] except: argument must be a Player or Group")
+            error("[Lync] Lync.except: argument must be a Player or Group")
         end
     end
 
-    return table.freeze({ _lyncExcept = true, _excluded = excluded })
+    return table.freeze({
+        _lyncExcept = true,
+        _excluded = table.freeze(excluded),
+    })
 end
 
 local function setupFlush(): ()
-    local flushFn: () -> ()
-
+    local transport: { flush: () -> () }
     if IS_SERVER then
         local Server = require(script.transport.Server)
-        flushFn = function(): ()
-            Server.flush()
-        end
+        transport = { flush = Server.flush }
     else
         local Client = require(script.transport.Client)
-        flushFn = function(): ()
-            Client.flush()
-        end
+        transport = { flush = Client.flush }
     end
+    _flushState.transport = transport
 
-    _flushConn = RunService.Heartbeat:Connect(function(dt: number)
-        if _flushRate >= 60 then
-            flushFn()
-        else
-            _flushAccum += dt
-            local interval = 1 / _flushRate
-            if _flushAccum >= interval then
-                _flushAccum -= interval
-                -- Prevent drift accumulation
-                if _flushAccum >= interval then
-                    _flushAccum = 0
-                end
-                flushFn()
-            end
+    _flushState.conn = RunService.Heartbeat:Connect(function(dt: number)
+        local rate = _flushState.rate
+        if rate >= FLUSH_HZ_MAX then
+            transport.flush()
+            return
+        end
+
+        local accum = _flushState.accum + dt
+        local interval = 1 / rate
+        if accum >= interval then
+            -- Drift guard: if we're more than one interval behind (frame
+            -- stall) zero the accumulator instead of catching up.
+            accum = if accum >= 2 * interval then 0 else accum - interval
+            transport.flush()
         end
+        _flushState.accum = accum
     end)
 end
 
--- Public --------------------------------------------------------------
-
-local Lync: any = {}
+-- Public -----------------------------------------------------------------
 
--- Lifecycle -----------------------------------------------------------
+local Lync = {}
 
 function Lync.configure(options: Types.ConfigureOptions): ()
-    if _started then
+    if _flushState.started then
         error("[Lync] Lync.configure: must be called before Lync.start()")
     end
 
-    if options.channelMaxSize then
-        local size = options.channelMaxSize
-        if size < 4096 or size > 1048576 then
-            error("[Lync] Lync.configure: channelMaxSize must be 4096-1048576")
+    local size = options.channelMaxSize
+    if size then
+        if size < CHANNEL_MAX_MIN or size > CHANNEL_MAX_MAX then
+            error(
+                `[Lync] Lync.configure: channelMaxSize must be {CHANNEL_MAX_MIN}-{CHANNEL_MAX_MAX}`
+            )
         end
         Channel.setMaxSize(size)
         Base.setMaxSize(size)
     end
 
-    if options.validationDepth then
-        local depth = options.validationDepth
-        if depth < 4 or depth > 32 then
-            error("[Lync] Lync.configure: validationDepth must be 4-32")
+    local depth = options.validationDepth
+    if depth then
+        if depth < DEPTH_MIN or depth > DEPTH_MAX then
+            error(`[Lync] Lync.configure: validationDepth must be {DEPTH_MIN}-{DEPTH_MAX}`)
         end
         Gate.setDepth(depth)
     end
 
-    if options.poolSize then
-        local size = options.poolSize
-        if size < 2 or size > 128 then
-            error("[Lync] Lync.configure: poolSize must be 2-128")
+    local poolSize = options.poolSize
+    if poolSize then
+        if poolSize < POOL_MIN or poolSize > POOL_MAX then
+            error(`[Lync] Lync.configure: poolSize must be {POOL_MIN}-{POOL_MAX}`)
         end
-        Pool.setMaxSize(size)
+        Pool.setMaxSize(poolSize)
     end
 
     if options.bandwidthLimit then
@@ -170,10 +200,10 @@ function Lync.configure(options: Types.ConfigureOptions): ()
 end
 
 function Lync.start(): ()
-    if _started then
+    if _flushState.started then
         error("[Lync] Lync.start: already started")
     end
-    _started = true
+    _flushState.started = true
 
     if IS_SERVER then
         local Server = require(script.transport.Server)
@@ -186,57 +216,40 @@ function Lync.start(): ()
     setupFlush()
 end
 
--- `Lync.started` is a read-only property backed by _started
-Lync.started = false
+function Lync.flush(): ()
+    if not _flushState.started then
+        error("[Lync] Lync.flush: must call Lync.start() first")
+    end
+    -- start() is the only path that sets transport, so it's non-nil here.
+    (_flushState.transport :: { flush: () -> () }).flush()
+    _flushState.accum = 0
+end
+
+function Lync.flushRate(hz: number): ()
+    if hz < FLUSH_HZ_MIN or hz > FLUSH_HZ_MAX then
+        error(`[Lync] Lync.flushRate: hz must be {FLUSH_HZ_MIN}-{FLUSH_HZ_MAX}`)
+    end
+    _flushState.rate = hz
+    _flushState.accum = 0
+end
 
--- Definitions ---------------------------------------------------------
+function Lync.isStarted(): boolean
+    return _flushState.started
+end
 
 Lync.packet = Packet.define
 Lync.query = Query.define
 Lync.group = Group.create
 Lync.scope = Scope.create
 
--- Targeting -----------------------------------------------------------
-
 Lync.all = ALL
 Lync.except = except
 Lync.DROP = DROP
 
--- Middleware ----------------------------------------------------------
-
 Lync.onSend = Middleware.onSend
 Lync.onReceive = Middleware.onReceive
 Lync.onDrop = Middleware.onDrop
 
--- Runtime control -----------------------------------------------------
-
-function Lync.flush(): ()
-    if not _started then
-        error("[Lync] Lync.flush: must call Lync.start() first")
-    end
-
-    if IS_SERVER then
-        local Server = require(script.transport.Server)
-        Server.flush()
-    else
-        local Client = require(script.transport.Client)
-        Client.flush()
-    end
-
-    -- Reset accumulator to prevent double-flush
-    _flushAccum = 0
-end
-
-function Lync.flushRate(hz: number): ()
-    if hz < 1 or hz > 60 then
-        error("[Lync] Lync.flushRate: hz must be 1-60")
-    end
-    _flushRate = hz
-    _flushAccum = 0
-end
-
--- Stats ---------------------------------------------------------------
-
 Lync.stats = table.freeze({
     player = function(player: Player): Types.PlayerStats?
         if not IS_SERVER then
@@ -251,56 +264,48 @@ Lync.stats = table.freeze({
             local Server = require(script.transport.Server)
             Server.resetStats()
         end
-
-        -- Reset per-registration stats
-        for _, reg in Registry.all() do
-            reg.bytesSent = 0
-            reg.bytesReceived = 0
-            reg.fires = 0
-            reg.recvFires = 0
-            reg.drops = 0
+        for i = 1, Registry.count() do
+            local reg = Registry.get(i)
+            if reg then
+                reg.bytesSent = 0
+                reg.bytesReceived = 0
+                reg.fires = 0
+                reg.recvFires = 0
+                reg.drops = 0
+            end
         end
     end,
 })
 
--- Debug ---------------------------------------------------------------
-
 Lync.debug = table.freeze({
-    capture = function(_label: string?): ()
-        -- TODO: Implement capture recording
-    end,
-
-    stop = function(): ()
-        -- TODO: Implement capture stop
-    end,
-
-    dump = function(): ()
-        -- TODO: Implement capture dump
-    end,
+    capture = function(_label: string?): () end,
+    stop = function(): () end,
+    dump = function(): () end,
 
     pending = function(): number
         return Query.pendingCount()
     end,
 
     registrations = function(): { any }
-        local regs = Registry.all()
-        local result = table.create(#regs)
-
-        for i, reg in regs do
-            result[i] = table.freeze({
-                name = reg.name,
-                id = reg.id,
-                kind = reg.kind,
-                isUnreliable = reg.isUnreliable,
-            })
+        local count = Registry.count()
+        local result = table.create(count)
+        local n = 0
+        for i = 1, count do
+            local reg = Registry.get(i)
+            if reg then
+                n += 1
+                result[n] = table.freeze({
+                    name = reg.name,
+                    id = reg.id,
+                    kind = reg.kind,
+                    isUnreliable = reg.isUnreliable,
+                })
+            end
         end
-
         return table.freeze(result)
     end,
 })
 
--- Codecs --------------------------------------------------------------
-
 Lync.int = IntC.int
 Lync.float = FloatC.float
 Lync.f16 = Float16C.f16
@@ -341,19 +346,4 @@ Lync.nothing = NothingC.nothing
 Lync.unknown = UnknownC.unknown
 Lync.auto = AutoC.auto
 
--- Wrap in metatable for `Lync.started` property -----------------------
-
-local LyncProxy = setmetatable({}, {
-    __index = function(_self: any, key: string): any
-        if key == "started" then
-            return _started
-        end
-        return Lync[key]
-    end,
-
-    __newindex = function(): ()
-        error("[Lync] Lync: module table is read-only")
-    end,
-})
-
-return LyncProxy
+return table.freeze(Lync)

package/src/internal/Baseline.luau

@@ -2,40 +2,39 @@
 --!optimize 2
 -- Read-side delta cache for delta codecs.
 
--- State ---------------------------------------------------------------
+local Types = require(script.Parent.Parent.Types)
 
-local _caches: { [number]: { [any]: any } } = {}
-local _currentKey: any = false
+-- State ------------------------------------------------------------------
+
+local _caches: { [number]: { [Types.BaselineKey]: any } } = {}
+local _currentKey: Types.BaselineKey = false
 local _hasDelta = false
 
--- Public --------------------------------------------------------------
+-- Public -----------------------------------------------------------------
 
 local Baseline = {}
 
-function Baseline.setReadKey(key: any): ()
+function Baseline.setReadKey(key: Types.BaselineKey): ()
     _currentKey = key
 end
 
 function Baseline.getCache(deltaId: number): any?
-    local perPlayer = _caches[deltaId]
-    if not perPlayer then
-        return nil
-    end
-    return perPlayer[_currentKey]
+    local perKey = _caches[deltaId]
+    return if perKey then perKey[_currentKey] else nil
 end
 
 function Baseline.setCache(deltaId: number, value: any): ()
-    local perPlayer = _caches[deltaId]
-    if not perPlayer then
-        perPlayer = {}
-        _caches[deltaId] = perPlayer
+    local perKey = _caches[deltaId]
+    if not perKey then
+        perKey = {}
+        _caches[deltaId] = perKey
     end
-    perPlayer[_currentKey] = value
+    perKey[_currentKey] = value
 end
 
-function Baseline.clearPlayer(key: any): ()
-    for _, perPlayer in _caches do
-        perPlayer[key] = nil
+function Baseline.clearPlayer(key: Types.BaselineKey): ()
+    for _, perKey in _caches do
+        perKey[key] = nil
     end
 end