@axpecter/lync 2.2.0 → 2.3.1

package/src/api/Scope.luau

@@ -1,7 +1,6 @@
 --!strict
 --!optimize 2
--- Batched connection lifecycle. Accepts Lync Connection,
--- RBXScriptConnection, and any object with :disconnect() / :Disconnect().
+-- Batched connection lifecycle for Lync, RBXScriptConnection, and disconnect()-style objects.
 
 local Types = require(script.Parent.Parent.Types)
 
@@ -25,21 +24,29 @@ local function pushConnection(self: Scope, conn: any): ()
     self._connections[idx] = conn
 end
 
+-- Routes :on / :once through `methodName` so both call sites share insert + size bookkeeping.
+local function attach(
+    self: Scope,
+    source: any,
+    fn: (...any) -> (),
+    methodName: string
+): Types.Connection
+    local conn = source[methodName](source, fn)
+    pushConnection(self, conn)
+    return conn
+end
+
 -- Public -----------------------------------------------------------------
 
 local ScopeMeta = {}
 ScopeMeta.__index = ScopeMeta
 
 function ScopeMeta.on(self: Scope, source: any, fn: (...any) -> ()): Types.Connection
-    local conn = source:on(fn)
-    pushConnection(self, conn)
-    return conn
+    return attach(self, source, fn, "on")
 end
 
 function ScopeMeta.once(self: Scope, source: any, fn: (...any) -> ()): Types.Connection
-    local conn = source:once(fn)
-    pushConnection(self, conn)
-    return conn
+    return attach(self, source, fn, "once")
 end
 
 ScopeMeta.add = pushConnection
@@ -48,6 +55,11 @@ function ScopeMeta.size(self: Scope): number
     return self._count
 end
 
+--[[
+    Disconnect every tracked source. The shape sniff handles three kinds:
+    Roblox RBXScriptConnection (:Disconnect), Lync Connection (:disconnect),
+    and tables exposing either capitalization.
+]]
 function ScopeMeta.destroy(self: Scope): ()
     local conns = self._connections
     local count = self._count
@@ -56,8 +68,12 @@ function ScopeMeta.destroy(self: Scope): ()
         conns[i] = nil
         if typeof(conn) == "RBXScriptConnection" then
             (conn :: RBXScriptConnection):Disconnect()
-        elseif typeof(conn) == "table" and conn.disconnect then
-            conn:disconnect()
+        elseif typeof(conn) == "table" then
+            if conn.disconnect then
+                conn:disconnect()
+            elseif conn.Disconnect then
+                conn:Disconnect()
+            end
         end
     end
     self._count = 0

package/src/api/Signal.luau

@@ -1,6 +1,6 @@
 --!strict
 --!optimize 2
--- O(1) disconnect signal system with thread reuse and reentrancy-safe fire.
+-- O(1) disconnect signal with thread reuse and reentrancy-safe fire.
 
 local Types = require(script.Parent.Parent.Types)
 
@@ -12,6 +12,7 @@ local STATE_ONCE = 2
 
 -- State ------------------------------------------------------------------
 
+-- Single recyclable thread for async dispatch; saves coroutine.create per fire.
 local _freeThread: thread? = nil
 
 -- Private ----------------------------------------------------------------
@@ -41,14 +42,19 @@ type Entry = {
     fn: (...any) -> (),
     _state: number,
     connected: boolean,
-    _signalEntries: { Entry },
-    _signalCount: { number },
+    _signal: SignalFields,
     _index: number,
 }
 
+type SignalFields = {
+    _entries: { Entry },
+    _count: number,
+}
+
 local EntryImpl = {}
 EntryImpl.__index = EntryImpl
 
+-- Swap-with-last for O(1) disconnect; the moved entry's _index is patched too.
 local function disconnectEntry(entry: Entry): ()
     if entry._state == STATE_DISCONNECTED then
         return
@@ -57,9 +63,10 @@ local function disconnectEntry(entry: Entry): ()
     entry._state = STATE_DISCONNECTED
     entry.connected = false
 
-    local entries = entry._signalEntries
-    local countRef = entry._signalCount
-    local idx, last = entry._index, countRef[1]
+    local signal = entry._signal
+    local entries = signal._entries
+    local idx = entry._index
+    local last = signal._count
 
     if idx < last then
         local moved = entries[last]
@@ -67,31 +74,40 @@ local function disconnectEntry(entry: Entry): ()
         moved._index = idx
     end
     entries[last] = nil
-    countRef[1] = last - 1
+    signal._count = last - 1
 end
 
 EntryImpl.disconnect = disconnectEntry
 table.freeze(EntryImpl)
 
-type SignalFields = {
-    _entries: { Entry },
-    _count: { number },
-}
+-- Auto-disconnects ONCE entries before invoking; chooses sync vs spawned thread.
+local function invokeEntry(entry: Entry, sync: boolean, ...: any): ()
+    local state = entry._state
+    if state == STATE_DISCONNECTED then
+        return
+    end
+    if state == STATE_ONCE then
+        disconnectEntry(entry)
+    end
+    if sync then
+        entry.fn(...)
+    else
+        spawnCallback(entry.fn, ...)
+    end
+end
 
 local SignalImpl = {}
 SignalImpl.__index = SignalImpl
 
 local function newEntry(self: SignalFields, callback: (...any) -> (), state: number): Entry
-    local countRef = self._count
-    local idx = countRef[1] + 1
-    countRef[1] = idx
+    local idx = self._count + 1
+    self._count = idx
 
     local entry: Entry = setmetatable({
         fn = callback,
         _state = state,
         connected = true,
-        _signalEntries = self._entries,
-        _signalCount = countRef,
+        _signal = self,
         _index = idx,
     }, EntryImpl) :: any
 
@@ -118,53 +134,28 @@ function SignalImpl.wait(self: SignalFields): ...any
 end
 
 local function dispatch(self: SignalFields, sync: boolean, ...: any): ()
-    local count = self._count[1]
+    local count = self._count
     if count == 0 then
         return
     end
 
     local entries = self._entries
 
+    -- Single-listener fast path skips the snapshot allocation.
     if count == 1 then
-        local entry = entries[1]
-        local state = entry._state
-        if state == STATE_ONCE then
-            disconnectEntry(entry)
-            if sync then
-                entry.fn(...)
-            else
-                spawnCallback(entry.fn, ...)
-            end
-        elseif state == STATE_CONNECTED then
-            if sync then
-                entry.fn(...)
-            else
-                spawnCallback(entry.fn, ...)
-            end
-        end
+        invokeEntry(entries[1], sync, ...)
         return
     end
 
+    --[[
+        Re-entrancy: a handler may disconnect or add others mid-fire.
+        Snapshot the entry list so the iteration view is stable.
+    ]]
     local snapshot = table.create(count)
     table.move(entries, 1, count, 1, snapshot)
 
     for i = 1, count do
-        local entry = snapshot[i]
-        local state = entry._state
-        if state == STATE_ONCE then
-            disconnectEntry(entry)
-            if sync then
-                entry.fn(...)
-            else
-                spawnCallback(entry.fn, ...)
-            end
-        elseif state == STATE_CONNECTED then
-            if sync then
-                entry.fn(...)
-            else
-                spawnCallback(entry.fn, ...)
-            end
-        end
+        invokeEntry(snapshot[i], sync, ...)
     end
 end
 
@@ -177,11 +168,11 @@ function SignalImpl.fireSync(self: SignalFields, ...: any): ()
 end
 
 function SignalImpl.count(self: SignalFields): number
-    return self._count[1]
+    return self._count
 end
 
 function SignalImpl.hasListeners(self: SignalFields): boolean
-    return self._count[1] > 0
+    return self._count > 0
 end
 
 table.freeze(SignalImpl)
@@ -191,7 +182,7 @@ table.freeze(SignalImpl)
 local SignalModule = {}
 
 function SignalModule.create(): Types.SignalLike
-    return (setmetatable({ _entries = {}, _count = { 0 } }, SignalImpl) :: any) :: Types.SignalLike
+    return (setmetatable({ _entries = {}, _count = 0 }, SignalImpl) :: any) :: Types.SignalLike
 end
 
 return table.freeze(SignalModule)

package/src/codec/Base.luau

@@ -1,7 +1,8 @@
 --!strict
 --!optimize 2
--- Fixed-size codec factory and channel buffer-grow primitive.
+-- Fixed-size codec factory + channel buffer-grow primitive.
 
+local Log = require(script.Parent.Parent.util.Log)
 local Types = require(script.Parent.Parent.Types)
 
 -- Constants --------------------------------------------------------------
@@ -19,9 +20,9 @@ local countlz = bit32.countlz
 local lshift = bit32.lshift
 
 --[[
-    Grow `ch.buff` so `ch.cursor + bytes` fits. New size is the next
-    power of two >= needed, capped by _maxSize. Caller MUST re-read
-    `ch.buff` after this returns: the buffer reference is replaced.
+    Grow `ch.buff` so cursor + bytes fits. New size is the next power of two
+    >= needed, capped by _maxSize. Callers MUST re-read `ch.buff` after
+    return: the buffer reference is replaced.
 ]]
 local function alloc(ch: Types.ChannelState, bytes: number): ()
     if bytes == 0 then
@@ -36,9 +37,9 @@ local function alloc(ch: Types.ChannelState, bytes: number): ()
     if needed > _maxSize then
         local name = ch.currentPacket
         if name then
-            error(`[Lync] Channel.alloc("{name}"): buffer overflow ({needed}B, max {_maxSize}B)`)
+            Log.error(`packet "{name}" overflowed at {needed}B (max {_maxSize}B)`)
         end
-        error(`[Lync] Channel.alloc: buffer overflow ({needed}B, max {_maxSize}B)`)
+        Log.error(`overflowed at {needed}B (max {_maxSize}B)`)
     end
 
     local newSize = lshift(1, 32 - countlz(needed - 1))
@@ -53,18 +54,24 @@ end
 local Base = {}
 
 Base.INITIAL_BUF = INITIAL_BUF
-
 Base.alloc = alloc
 
+-- Floor is INITIAL_BUF: anything smaller errors on the very first write.
 function Base.setMaxSize(bytes: number): ()
+    if bytes < INITIAL_BUF then
+        Log.error(`bytes ({bytes}) must be >= {INITIAL_BUF}`)
+    end
     _maxSize = bytes
 end
 
+function Base.reset(): ()
+    _maxSize = DEFAULT_MAX
+end
+
 --[[
-    Build a fixed-size codec. The codec exposes channel-level write/read
-    (which handles buffer growth and cursor bookkeeping) plus the raw
-    _directWrite / _directRead primitives composite codecs use in their
-    pre-sized fast paths.
+    Build a fixed-size codec. Exposes channel-level write/read (handles
+    buffer growth + cursor) plus raw _directWrite/_directRead for composite
+    fast paths that pre-size the channel themselves.
 ]]
 function Base.define<T>(
     size: number,
@@ -101,9 +108,9 @@ function Base.define<T>(
 end
 
 --[[
-    Constant codec: zero bytes wire, decode always returns `value`. Used
-    by quantizers when min == max so the wire emits nothing yet decode
-    still produces a type-faithful value.
+    Zero-byte codec: writes nothing, reads always return `value`. Used by
+    quantizers when min == max so the wire emits nothing yet decode produces
+    a type-faithful value.
 ]]
 function Base.constant<T>(value: T): Types.InternalCodec<T>
     return table.freeze({

package/src/codec/composite/Array.luau

@@ -1,98 +1,62 @@
 --!strict
 --!native
--- Array and deltaArray codecs. Bool elements are bit-packed.
+-- array() and deltaArray(). Bool elements are bit-packed.
 
 local Base = require(script.Parent.Parent.Base)
-local Channel = require(script.Parent.Parent.Parent.internal.Channel)
-local Shared = require(script.Parent.Shared)
+local Baseline = require(script.Parent.Parent.Parent.internal.Baseline)
+local Log = require(script.Parent.Parent.Parent.util.Log)
+local Shared = require(script.Parent.Parent.composite.Shared)
 local Types = require(script.Parent.Parent.Parent.Types)
 local Varint = require(script.Parent.Parent.primitive.Varint)
 
 -- Private ----------------------------------------------------------------
 
 local alloc = Base.alloc
-local writeByte = Channel.writeByte
-local writeu8 = buffer.writeu8
-local readu8 = buffer.readu8
-local band = bit32.band
-local bor = bit32.bor
-local lshift = bit32.lshift
-
-local acquireScratch = Shared.acquireScratch
-local releaseScratch = Shared.releaseScratch
-local rangeEqual = Shared.rangeEqual
-local snapshot = Shared.snapshot
 local allocDeltaId = Shared.allocDeltaId
-local DELTA_UNCHANGED = Shared.DELTA_UNCHANGED
-local DELTA_FULL = Shared.DELTA_FULL
+local boolBytes = Shared.boolBytes
+local packBoolArray = Shared.packBoolArray
+local unpackBoolArray = Shared.unpackBoolArray
+local varintRead = Varint.read
+local varintWrite = Varint.write
 
+-- Bit-packed bool element fast path: 1 bit per entry instead of 1 byte.
 local function makeBoolArray(
     element: Types.InternalCodec<any>,
     maxCount: number?
 ): Types.InternalCodec<any>
-    return table.freeze({
+    return {
         _isArray = true,
         _element = element,
         _maxCount = maxCount,
 
         write = function(ch: Types.ChannelState, value: { boolean }): ()
             local len = #value
-            Varint.write(ch, len)
-            if len == 0 then
-                return
-            end
-
-            local byteCount = (len + 7) // 8
-            local cursor = ch.cursor
-            if cursor + byteCount > ch.size then
-                alloc(ch, byteCount)
-            end
-            local b = ch.buff
-
-            local idx = 1
-            for byteIdx = 0, byteCount - 1 do
-                local packed = 0
-                local remaining = len - idx + 1
-                local limit = if remaining >= 8 then 8 else remaining
-                for bit = 0, limit - 1 do
-                    if value[idx] then
-                        packed = bor(packed, lshift(1, bit))
-                    end
-                    idx += 1
-                end
-                writeu8(b, cursor + byteIdx, packed)
-            end
-            ch.cursor = cursor + byteCount
+            varintWrite(ch, len)
+            packBoolArray(ch, value, len)
         end,
 
         read = function(src: buffer, pos: number, _refs: { Instance }?): ({ boolean }, number)
-            local len, lenBytes = Varint.read(src, pos)
+            local len, lenBytes = varintRead(src, pos)
             if maxCount and len > maxCount then
-                error(`[Lync] Array.read: count {len} exceeds max {maxCount}`)
+                Log.error(`count {len} exceeds max {maxCount}`)
             end
             if len == 0 then
                 return {}, lenBytes
             end
 
-            local byteCount = (len + 7) // 8
+            local byteCount = boolBytes(len)
             local dataStart = pos + lenBytes
-            local result = table.create(len)
-
-            local idx = 1
-            for byteIdx = 0, byteCount - 1 do
-                local byte = readu8(src, dataStart + byteIdx)
-                local remaining = len - idx + 1
-                local limit = if remaining >= 8 then 8 else remaining
-                for bit = 0, limit - 1 do
-                    result[idx] = band(byte, lshift(1, bit)) ~= 0
-                    idx += 1
-                end
+            if dataStart + byteCount > buffer.len(src) then
+                Log.error(`payload {byteCount}B exceeds remaining buffer`)
             end
+            local result = table.create(len, false)
+            unpackBoolArray(src, dataStart, len, result)
             return result, lenBytes + byteCount
         end,
-    })
+    }
 end
 
+-- Fixed-size element fast path: single alloc + tight loop calling _direct fns.
 local function makeDirectArray(
     element: Types.InternalCodec<any>,
     elemSize: number,
@@ -100,14 +64,14 @@ local function makeDirectArray(
     elemDR: (b: buffer, off: number) -> any,
     maxCount: number?
 ): Types.InternalCodec<any>
-    return table.freeze({
+    return {
         _isArray = true,
         _element = element,
         _maxCount = maxCount,
 
         write = function(ch: Types.ChannelState, value: { any }): ()
             local len = #value
-            Varint.write(ch, len)
+            varintWrite(ch, len)
             if len == 0 then
                 return
             end
@@ -118,7 +82,6 @@ local function makeDirectArray(
                 alloc(ch, payloadBytes)
             end
             local b = ch.buff
-
             local off = cursor
             for i = 1, len do
                 elemDW(b, off, value[i])
@@ -128,9 +91,9 @@ local function makeDirectArray(
         end,
 
         read = function(src: buffer, pos: number, _refs: { Instance }?): ({ any }, number)
-            local len, lenBytes = Varint.read(src, pos)
+            local len, lenBytes = varintRead(src, pos)
             if maxCount and len > maxCount then
-                error(`[Lync] Array.read: count {len} exceeds max {maxCount}`)
+                Log.error(`count {len} exceeds max {maxCount}`)
             end
             if len == 0 then
                 return {}, lenBytes
@@ -138,10 +101,8 @@ local function makeDirectArray(
 
             local payloadBytes = len * elemSize
             local dataStart = pos + lenBytes
-            local remaining = buffer.len(src) - dataStart
-            if payloadBytes > remaining then
-                len = remaining // elemSize
-                payloadBytes = len * elemSize
+            if payloadBytes > buffer.len(src) - dataStart then
+                Log.error(`payload {payloadBytes}B exceeds remaining buffer`)
             end
 
             local result = table.create(len)
@@ -152,30 +113,31 @@ local function makeDirectArray(
             end
             return result, lenBytes + payloadBytes
         end,
-    })
+    }
 end
 
+-- Generic fallback: variable-size or composite element codec.
 local function makeGenericArray(
     element: Types.InternalCodec<any>,
     maxCount: number?
 ): Types.InternalCodec<any>
-    return table.freeze({
+    return {
         _isArray = true,
         _element = element,
         _maxCount = maxCount,
 
         write = function(ch: Types.ChannelState, value: { any }): ()
             local len = #value
-            Varint.write(ch, len)
+            varintWrite(ch, len)
             for i = 1, len do
                 element.write(ch, value[i])
             end
         end,
 
         read = function(src: buffer, pos: number, refs: { Instance }?): ({ any }, number)
-            local len, lenBytes = Varint.read(src, pos)
+            local len, lenBytes = varintRead(src, pos)
             if maxCount and len > maxCount then
-                error(`[Lync] Array.read: count {len} exceeds max {maxCount}`)
+                Log.error(`count {len} exceeds max {maxCount}`)
             end
             if len == 0 then
                 return {}, lenBytes
@@ -186,14 +148,14 @@ local function makeGenericArray(
             for i = 1, len do
                 local v, consumed = element.read(src, pos + total, refs)
                 if consumed == 0 then
-                    error(`[Lync] Array.read: element codec consumed 0 bytes at index {i}`)
+                    Log.error(`element codec consumed 0 bytes at index {i}`)
                 end
                 result[i] = v
                 total += consumed
             end
             return result, total
         end,
-    })
+    }
 end
 
 -- Public -----------------------------------------------------------------
@@ -201,75 +163,35 @@ end
 local Array = {}
 
 function Array.array(element: Types.InternalCodec<any>, maxCount: number?): Types.InternalCodec<any>
+    local codec: Types.InternalCodec<any>
     if element._isBool then
-        return makeBoolArray(element, maxCount)
+        codec = makeBoolArray(element, maxCount)
+    else
+        local elemSize = element._size
+        local elemDW = element._directWrite
+        local elemDR = element._directRead
+        if elemSize and elemDW and elemDR then
+            codec = makeDirectArray(element, elemSize, elemDW, elemDR, maxCount)
+        else
+            codec = makeGenericArray(element, maxCount)
+        end
     end
-
-    local elemSize = element._size
-    local elemDW = element._directWrite
-    local elemDR = element._directRead
-    if elemSize and elemDW and elemDR then
-        return makeDirectArray(element, elemSize, elemDW, elemDR, maxCount)
+    if element._hasUnknown then
+        codec._hasUnknown = true
     end
-
-    return makeGenericArray(element, maxCount)
+    return table.freeze(codec)
 end
 
+--[[
+    UNCHANGED-or-FULL delta. Useful only when contents AND order are stable
+    across frames; for unstable lists, plain array() avoids a 1-byte tax on
+    every frame the byte-equality cache misses.
+]]
 function Array.deltaArray(
     element: Types.InternalCodec<any>,
     maxCount: number?
 ): Types.InternalCodec<any>
-    local deltaId = allocDeltaId()
-    local innerArray = Array.array(element, maxCount)
-
-    return table.freeze({
-        _isDelta = true,
-
-        write = function(ch: Types.ChannelState, value: { any }): ()
-            local cache = ch.deltas[deltaId]
-
-            if not cache then
-                writeByte(ch, DELTA_FULL)
-
-                local scratch = acquireScratch()
-                innerArray.write(scratch, value)
-                local snapLen = scratch.cursor
-
-                ch.deltas[deltaId] = { raw = snapshot(scratch.buff, snapLen), len = snapLen }
-                innerArray.write(ch, value)
-                releaseScratch()
-                return
-            end
-
-            local scratch = acquireScratch()
-            innerArray.write(scratch, value)
-            local scratchLen = scratch.cursor
-
-            if
-                scratchLen == cache.len
-                and rangeEqual(scratch.buff, 0, cache.raw, 0, scratchLen)
-            then
-                writeByte(ch, DELTA_UNCHANGED)
-                releaseScratch()
-                return
-            end
-
-            writeByte(ch, DELTA_FULL)
-            innerArray.write(ch, value)
-
-            cache.raw = snapshot(scratch.buff, scratchLen)
-            cache.len = scratchLen
-            releaseScratch()
-        end,
-
-        read = function(src: buffer, pos: number, refs: { Instance }?): ({ any }, number)
-            if readu8(src, pos) == DELTA_UNCHANGED then
-                return {}, 1
-            end
-            local value, consumed = innerArray.read(src, pos + 1, refs)
-            return value, 1 + consumed
-        end,
-    })
+    return Shared.makeUnchangedOrFullDelta(Array.array(element, maxCount), allocDeltaId(), Baseline)
 end
 
 return table.freeze(Array)