@axpecter/lync 1.3.1 → 1.4.1

package/src/api/Namespace.luau

@@ -11,16 +11,16 @@ type Connection = Types.Connection
 type PacketConfig<T> = Types.PacketConfig<T>
 type QueryConfig<R, S> = Types.QueryConfig<R, S>
 
--- Constants --------------------------------------------------------------
+-- Constants ----------------------------------------------------------
 
 local MAX_NAMESPACES = 64
 
--- State ------------------------------------------------------------------
+-- State --------------------------------------------------------------
 
 local _registered = {} :: { [string]: true }
 local _count = 0
 
--- Private ----------------------------------------------------------------
+-- Private ------------------------------------------------------------
 
 type NamespaceConfig = {
     packets: { [string]: PacketConfig<any> }?,
@@ -47,8 +47,6 @@ local function scopedHandler (
     end
 end
 
--- Namespace --------------------------------------------------------------
-
 local NamespaceImpl = {}
 NamespaceImpl.__index = NamespaceImpl
 
@@ -173,7 +171,9 @@ function NamespaceImpl.queryNames (self: any): { string }
     return result
 end
 
--- Public -----------------------------------------------------------------
+table.freeze (NamespaceImpl)
+
+-- Public -------------------------------------------------------------
 
 local Namespace = {}
 
@@ -194,6 +194,8 @@ function Namespace.define (name: string, config: NamespaceConfig): any
 
     local packets = {} :: { [string]: any }
     local queries = {} :: { [string]: any }
+    local packetsByShort = {} :: { [string]: any }
+    local queriesByShort = {} :: { [string]: any }
     local fields = {} :: { [string]: any }
 
     fields._name = name
@@ -207,6 +209,7 @@ function Namespace.define (name: string, config: NamespaceConfig): any
             local fullName = prefixName (name, shortName)
             local packet = Packet.define (fullName, packetConfig)
             packets[fullName] = packet
+            packetsByShort[shortName] = packet
             fields[shortName] = packet
         end
     end
@@ -216,10 +219,14 @@ function Namespace.define (name: string, config: NamespaceConfig): any
             local fullName = prefixName (name, shortName)
             local query = Query.define (fullName, queryConfig)
             queries[fullName] = query
+            queriesByShort[shortName] = query
             fields[shortName] = query
         end
     end
 
+    fields.packets = table.freeze (packetsByShort)
+    fields.queries = table.freeze (queriesByShort)
+
     return setmetatable (fields, NamespaceImpl)
 end
 

package/src/api/Packet.luau

@@ -11,9 +11,10 @@ local Signal = require (script.Parent.Signal)
 local Types = require (script.Parent.Parent.Types)
 
 type Connection = Types.Connection
+type InternalCodec<T> = Types.InternalCodec<T>
 type PacketConfig<T> = Types.PacketConfig<T>
 
--- Constants --------------------------------------------------------------
+-- Constants ----------------------------------------------------------
 
 local IS_SERVER = RunService:IsServer ()
 
@@ -21,10 +22,13 @@ local serverWriteTo = Server.writeTo
 local serverWriteToAll = Server.writeToAll
 local serverWriteToList = Server.writeToList
 local serverWriteToAllExcept = Server.writeToAllExcept
-local serverWriteToGroup = Server.writeToGroup
+local serverWriteToSet = Server.writeToSet
 local clientWrite = Client.write
 
--- Private ----------------------------------------------------------------
+local DELTA_TARGETED = 1
+local DELTA_BROADCAST = 2
+
+-- Private ------------------------------------------------------------
 
 -- Shared methods (both contexts)
 local SharedImpl = {}
@@ -45,13 +49,10 @@ function SharedImpl.disconnectAll (self: any): ()
     self._signal:disconnectAll ()
 end
 
--- Server-only metatable . Has sendTo/sendToAll, no send().
+-- Server-only metatable. Single send() dispatches on target type.
 local ServerImpl = setmetatable ({}, { __index = SharedImpl })
 ServerImpl.__index = ServerImpl
 
-local DELTA_TARGETED = 1
-local DELTA_BROADCAST = 2
-
 local function checkDeltaMode (self: any, mode: number): ()
     if not self._isDelta then
         return
@@ -64,34 +65,55 @@ local function checkDeltaMode (self: any, mode: number): ()
     end
 end
 
-function ServerImpl.sendTo (self: any, data: any, player: Player): ()
-    checkDeltaMode (self, DELTA_TARGETED)
-    serverWriteTo (player, self._id, self._name, self._codec, data, self._isUnreliable)
-end
+function ServerImpl.send (self: any, data: any, target: any?): ()
+    if target == nil then
+        error ("[Lync] Server packet:send requires a target")
+    end
 
-function ServerImpl.sendToAll (self: any, data: any): ()
-    checkDeltaMode (self, DELTA_BROADCAST)
-    serverWriteToAll (self._id, self._name, self._codec, data, self._isUnreliable)
-end
+    local id = self._id
+    local name = self._name
+    local codec = self._codec
+    local isUnreliable = self._isUnreliable
 
-function ServerImpl.sendToList (self: any, data: any, players: { Player }): ()
-    checkDeltaMode (self, DELTA_TARGETED)
-    serverWriteToList (players, self._id, self._name, self._codec, data, self._isUnreliable)
-end
+    -- Single player
+    if typeof (target) == "Instance" then
+        checkDeltaMode (self, DELTA_TARGETED)
+        serverWriteTo (target :: Player, id, name, codec, data, isUnreliable)
+        return
+    end
 
-function ServerImpl.sendToAllExcept (self: any, data: any, except: Player): ()
-    checkDeltaMode (self, DELTA_BROADCAST)
-    serverWriteToAllExcept (except, self._id, self._name, self._codec, data, self._isUnreliable)
-end
+    -- Must be a table from here
+    local tag = target._tag
+
+    -- Lync.all sentinel
+    if tag == "all" then
+        checkDeltaMode (self, DELTA_BROADCAST)
+        serverWriteToAll (id, name, codec, data, isUnreliable)
+        return
+    end
+
+    -- Lync.except(player, ...) descriptor
+    if tag == "except" then
+        checkDeltaMode (self, DELTA_BROADCAST)
+        serverWriteToAllExcept (target._set, id, name, codec, data, isUnreliable)
+        return
+    end
+
+    -- Group object
+    if tag == "group" then
+        checkDeltaMode (self, DELTA_BROADCAST)
+        serverWriteToSet (target:getSet (), id, name, codec, data, isUnreliable)
+        return
+    end
 
-function ServerImpl.sendToGroup (self: any, data: any, groupName: string): ()
-    checkDeltaMode (self, DELTA_BROADCAST)
-    serverWriteToGroup (groupName, self._id, self._name, self._codec, data, self._isUnreliable)
+    -- Player list (array)
+    checkDeltaMode (self, DELTA_TARGETED)
+    serverWriteToList (target :: { Player }, id, name, codec, data, isUnreliable)
 end
 
 table.freeze (ServerImpl)
 
--- Client-only metatable . Has send(), no sendTo/sendToAll
+-- Client-only metatable. Has send(), no target needed.
 local ClientImpl = setmetatable ({}, { __index = SharedImpl })
 ClientImpl.__index = ClientImpl
 
@@ -101,7 +123,7 @@ end
 
 table.freeze (ClientImpl)
 
--- Public -----------------------------------------------------------------
+-- Public -------------------------------------------------------------
 
 local Packet = {}
 
@@ -115,7 +137,7 @@ function Packet.define (name: string, config: PacketConfig<any>): any
 
     local isUnreliable = config.unreliable or false
 
-    if (config.value :: any)._isDelta and isUnreliable then
+    if (config.value :: InternalCodec<any>)._isDelta and isUnreliable then
         error (`[Lync] Delta codec requires reliable delivery: "{name}"`)
     end
 
@@ -131,7 +153,7 @@ function Packet.define (name: string, config: PacketConfig<any>): any
         config.maxPayloadBytes
     )
 
-    local isDelta = (config.value :: any)._isDelta == true
+    local isDelta = (config.value :: InternalCodec<any>)._isDelta == true
 
     return setmetatable ({
         _id = reg.id,

package/src/api/Query.luau

@@ -6,7 +6,6 @@ local Players = game:GetService ("Players")
 local RunService = game:GetService ("RunService")
 
 local Client = require (script.Parent.Parent.transport.Client)
-local Group = require (script.Parent.Group)
 local Registry = require (script.Parent.Parent.internal.Registry)
 local Server = require (script.Parent.Parent.transport.Server)
 local Signal = require (script.Parent.Signal)
@@ -15,14 +14,14 @@ local Types = require (script.Parent.Parent.Types)
 type Connection = Types.Connection
 type QueryConfig<R, S> = Types.QueryConfig<R, S>
 
--- Constants --------------------------------------------------------------
+-- Constants ----------------------------------------------------------
 
 local IS_SERVER = RunService:IsServer ()
 
 -- Wire ceiling: correlationId is u16 in Channel.writeQuery / Reader.process.
 local POOL_SIZE = 65536
 
--- State ------------------------------------------------------------------
+-- State --------------------------------------------------------------
 
 type PendingQuery = {
     thread: thread?,
@@ -34,7 +33,7 @@ local _pending = {} :: { [number]: PendingQuery }
 local _nextId = 0
 local _activeCount = 0
 
--- Private ----------------------------------------------------------------
+-- Private ------------------------------------------------------------
 
 local function allocCorrelation (): number
     if _activeCount >= POOL_SIZE then
@@ -54,7 +53,9 @@ local function allocCorrelation (): number
     return id
 end
 
-local function freeCorrelation (): ()
+-- Decrements the active correlation counter. Does not free a specific slot;
+-- that is handled by nil-ing _pending[id] at the call site.
+local function releaseCorrelation (): ()
     _activeCount -= 1
 end
 
@@ -65,7 +66,7 @@ local function completeQuery (id: number, data: any): ()
     end
 
     _pending[id] = nil
-    freeCorrelation ()
+    releaseCorrelation ()
 
     if entry.timeout then
         task.cancel (entry.timeout)
@@ -82,90 +83,35 @@ local function onTimeout (correlation: number): ()
     completeQuery (correlation, nil)
 end
 
--- Query ------------------------------------------------------------------
-
-local QueryImpl = {}
-QueryImpl.__index = QueryImpl
-
-function QueryImpl.listen (self: any, callback: (...any) -> any): Connection
-    local respId = self._respReg.id
-    local respName = self._name
-    local respCodec = self._respReg.codec
-
-    if IS_SERVER then
-        return self._reqReg.signal:connect (
-            function (request: any, player: Player, correlation: number): ()
-                local ok, response = pcall (callback, request, player)
-                if not ok then
-                    warn (`[Lync] Query handler error on "{respName}": {response}`)
-                end
-
-                if ok and response ~= nil then
-                    Server.writeQuery (player, respId, respName, correlation, respCodec, response)
-                else
-                    Server.writeQueryNil (player, respId, respName, correlation)
-                end
-            end
-        )
-    else
-        return self._reqReg.signal:connect (
-            function (request: any, _player: Player?, correlation: number): ()
-                local ok, response = pcall (callback, request)
-                if not ok then
-                    warn (`[Lync] Query handler error on "{respName}": {response}`)
-                end
-
-                if ok and response ~= nil then
-                    Client.writeQuery (respId, respName, correlation, respCodec, response)
-                else
-                    Client.writeQueryNil (respId, respName, correlation)
-                end
-            end
-        )
+-- Send a query to multiple players and yield. Returns { [Player]: response? }.
+local function requestMulti (self: any, players: { Player }, data: any): { [Player]: any? }
+    if not IS_SERVER then
+        error ("[Lync] Multi-request is server-only")
     end
-end
 
-function QueryImpl.invoke (self: any, request: any, player: Player?): any
-    if IS_SERVER and not player then
-        error ("[Lync] Query:invoke on server requires a player argument")
+    local count = #players
+    if count == 0 then
+        return {}
     end
 
-    local correlation = allocCorrelation ()
-    local thread = coroutine.running ()
-
-    local entry: PendingQuery = { thread = thread, timeout = nil }
-    _pending[correlation] = entry
+    if count == 1 then
+        -- Delegate to single-player path
+        local correlation = allocCorrelation ()
+        local thread = coroutine.running ()
+        local entry: PendingQuery = { thread = thread, timeout = nil }
+        _pending[correlation] = entry
 
-    if IS_SERVER then
         Server.writeQuery (
-            player :: Player,
+            players[1],
             self._reqReg.id,
             self._name,
             correlation,
             self._reqReg.codec,
-            request
+            data
         )
-    else
-        Client.writeQuery (self._reqReg.id, self._name, correlation, self._reqReg.codec, request)
-    end
-
-    entry.timeout = task.delay (self._timeout, onTimeout, correlation)
-    return coroutine.yield ()
-end
-
--- Send a query to multiple players and yield. Returns { [Player]: response? }.
-local function invokeMulti (self: any, players: { Player }, request: any): { [Player]: any? }
-    if not IS_SERVER then
-        error ("[Lync] Multi-invoke is server-only")
-    end
-
-    local count = #players
-    if count == 0 then
-        return {}
-    end
 
-    if count == 1 then
-        local result = QueryImpl.invoke (self, request, players[1])
+        entry.timeout = task.delay (self._timeout, onTimeout, correlation)
+        local result = coroutine.yield ()
         return { [players[1]] = result }
     end
 
@@ -187,8 +133,8 @@ local function invokeMulti (self: any, players: { Player }, request: any): { [Pl
 
         local entry: PendingQuery = {
             thread = nil,
-            callback = function (data: any): ()
-                results[player] = data
+            callback = function (resp: any): ()
+                results[player] = resp
                 remaining -= 1
                 if remaining == 0 and not finished then
                     finished = true
@@ -200,7 +146,7 @@ local function invokeMulti (self: any, players: { Player }, request: any): { [Pl
 
         _pending[correlation] = entry
 
-        Server.writeQuery (player, reqId, reqName, correlation, reqCodec, request)
+        Server.writeQuery (player, reqId, reqName, correlation, reqCodec, data)
     end
 
     local timeoutThread = task.delay (timeout, function (): ()
@@ -214,7 +160,7 @@ local function invokeMulti (self: any, players: { Player }, request: any): { [Pl
             local entry = _pending[cid]
             if entry then
                 _pending[cid] = nil
-                freeCorrelation ()
+                releaseCorrelation ()
             end
         end
 
@@ -232,25 +178,105 @@ local function invokeMulti (self: any, players: { Player }, request: any): { [Pl
     return coroutine.yield ()
 end
 
-function QueryImpl.invokeAll (self: any, request: any): { [Player]: any? }
+local QueryImpl = {}
+QueryImpl.__index = QueryImpl
+
+function QueryImpl.listen (self: any, callback: (...any) -> any): Connection
+    local respId = self._respReg.id
+    local respName = self._name
+    local respCodec = self._respReg.codec
+
+    if IS_SERVER then
+        return self._reqReg.signal:connect (
+            function (request: any, player: Player, correlation: number): ()
+                local ok, response = pcall (callback, request, player)
+                if not ok then
+                    warn (`[Lync] Query handler error on "{respName}": {response}`)
+                end
+
+                if ok and response ~= nil then
+                    Server.writeQuery (player, respId, respName, correlation, respCodec, response)
+                else
+                    Server.writeQueryNil (player, respId, respName, correlation)
+                end
+            end
+        )
+    else
+        return self._reqReg.signal:connect (
+            function (request: any, _player: Player?, correlation: number): ()
+                local ok, response = pcall (callback, request)
+                if not ok then
+                    warn (`[Lync] Query handler error on "{respName}": {response}`)
+                end
+
+                if ok and response ~= nil then
+                    Client.writeQuery (respId, respName, correlation, respCodec, response)
+                else
+                    Client.writeQueryNil (respId, respName, correlation)
+                end
+            end
+        )
+    end
+end
+
+-- Client: send request to server, yield until response.
+function QueryImpl.request (self: any, data: any): any
+    if IS_SERVER then
+        error ("[Lync] query:request is client-only. Use query:requestFrom on server")
+    end
+
+    local correlation = allocCorrelation ()
+    local thread = coroutine.running ()
+    local entry: PendingQuery = { thread = thread, timeout = nil }
+    _pending[correlation] = entry
+
+    Client.writeQuery (self._reqReg.id, self._name, correlation, self._reqReg.codec, data)
+
+    entry.timeout = task.delay (self._timeout, onTimeout, correlation)
+    return coroutine.yield ()
+end
+
+-- Server: send request to one player, yield until response.
+function QueryImpl.requestFrom (self: any, player: Player, data: any): any
+    if not IS_SERVER then
+        error ("[Lync] query:requestFrom is server-only. Use query:request on client")
+    end
+
+    local correlation = allocCorrelation ()
+    local thread = coroutine.running ()
+    local entry: PendingQuery = { thread = thread, timeout = nil }
+    _pending[correlation] = entry
+
+    Server.writeQuery (player, self._reqReg.id, self._name, correlation, self._reqReg.codec, data)
+
+    entry.timeout = task.delay (self._timeout, onTimeout, correlation)
+    return coroutine.yield ()
+end
+
+-- Server: send request to all players, yield until all respond or timeout.
+function QueryImpl.requestAll (self: any, data: any): { [Player]: any? }
     local players = Players:GetPlayers ()
-    return invokeMulti (self, players, request)
+    return requestMulti (self, players, data)
 end
 
-function QueryImpl.invokeList (self: any, request: any, players: { Player }): { [Player]: any? }
-    return invokeMulti (self, players, request)
+-- Server: send request to a list of players.
+function QueryImpl.requestList (self: any, players: { Player }, data: any): { [Player]: any? }
+    return requestMulti (self, players, data)
 end
 
-function QueryImpl.invokeGroup (self: any, request: any, groupName: string): { [Player]: any? }
-    local set = Group.getSet (groupName)
+-- Server: send request to all players in a group.
+function QueryImpl.requestGroup (self: any, group: any, data: any): { [Player]: any? }
+    local set = group:getSet ()
     local players = {} :: { Player }
     for player in set do
         table.insert (players, player)
     end
-    return invokeMulti (self, players, request)
+    return requestMulti (self, players, data)
 end
 
--- Public -----------------------------------------------------------------
+table.freeze (QueryImpl)
+
+-- Public -------------------------------------------------------------
 
 local Query = {}
 

package/src/api/Scope.luau

@@ -0,0 +1,73 @@
+--!strict
+--!optimize 2
+-- Batched connection lifecycle management.
+
+-- Private ------------------------------------------------------------
+
+local ScopeImpl = {}
+ScopeImpl.__index = ScopeImpl
+
+function ScopeImpl.add (self: any, conn: any): ()
+    if not conn then
+        return
+    end
+
+    local entries = self._entries
+    local count = self._count + 1
+    self._count = count
+    entries[count] = conn
+end
+
+function ScopeImpl.listen (self: any, source: any, callback: (...any) -> ()): ()
+    local conn = source:listen (callback)
+    local entries = self._entries
+    local count = self._count + 1
+    self._count = count
+    entries[count] = conn
+end
+
+function ScopeImpl.once (self: any, source: any, callback: (...any) -> ()): ()
+    local conn = source:once (callback)
+    local entries = self._entries
+    local count = self._count + 1
+    self._count = count
+    entries[count] = conn
+end
+
+function ScopeImpl.listenAll (self: any, namespace: any, callback: (...any) -> ()): ()
+    local conn = namespace:listenAll (callback)
+    local entries = self._entries
+    local count = self._count + 1
+    self._count = count
+    entries[count] = conn
+end
+
+function ScopeImpl.destroy (self: any): ()
+    local entries = self._entries
+    local count = self._count
+
+    for i = 1, count do
+        local conn = entries[i]
+        entries[i] = nil
+
+        if typeof (conn) == "RBXScriptConnection" then
+            conn:Disconnect ()
+        elseif conn.disconnect then
+            conn:disconnect ()
+        end
+    end
+
+    self._count = 0
+end
+
+table.freeze (ScopeImpl)
+
+-- Public -------------------------------------------------------------
+
+local Scope = {}
+
+function Scope.create (): any
+    return setmetatable ({ _entries = {}, _count = 0 }, ScopeImpl)
+end
+
+return table.freeze (Scope)

package/src/api/Signal.luau

@@ -6,12 +6,13 @@ local Types = require (script.Parent.Parent.Types)
 
 type Connection = Types.Connection
 
--- Listener state: single numeric field for both connected and once checks.
+-- Constants ----------------------------------------------------------
+
 local STATE_DISCONNECTED = 0
 local STATE_CONNECTED = 1
 local STATE_ONCE = 2
 
--- Private ----------------------------------------------------------------
+-- Private ------------------------------------------------------------
 
 local _freeThread: thread? = nil
 
@@ -36,7 +37,9 @@ local function spawn (fn: (...any) -> (), ...: any): ()
     task.spawn (_freeThread :: thread, fn, ...)
 end
 
--- Entry doubles as the Connection handle , 1 alloc per listener instead of 2.
+-- Entry doubles as the Connection handle: 1 alloc per listener instead of 2.
+-- self: any — metatable typing via typeof(setmetatable) is not practical here
+-- because Entry and Signal reference each other circularly.
 local EntryImpl = {}
 EntryImpl.__index = EntryImpl
 
@@ -213,7 +216,10 @@ function SignalImpl.disconnectAll (self: any): ()
     self._count = 0
 end
 
--- Public -----------------------------------------------------------------
+table.freeze (EntryImpl)
+table.freeze (SignalImpl)
+
+-- Public -------------------------------------------------------------
 
 local Signal = {}
 

package/src/codec/Base.luau

@@ -3,9 +3,13 @@
 -- Fixed-size codec factory. Every fixed-size codec calls Base.define once.
 
 local Channel = require (script.Parent.Parent.internal.Channel)
+local Types = require (script.Parent.Parent.Types)
+
+type ChannelState = Types.ChannelState
+
 local alloc = Channel.alloc
 
--- Public -----------------------------------------------------------------
+-- Public -------------------------------------------------------------
 
 local Base = {}
 
@@ -18,7 +22,7 @@ function Base.define <T>(
         _size = size,
         _directWrite = directWrite,
         _directRead = directRead,
-        write = function (ch: any, value: T): ()
+        write = function (ch: ChannelState, value: T): ()
             local c = ch.cursor
             if c + size > ch.size then
                 alloc (ch, size)
@@ -39,7 +43,7 @@ function Base.zero (): any
         _directRead = function (_b: buffer, _offset: number): any
             return nil
         end,
-        write = function (_ch: any, _value: any): () end,
+        write = function (_ch: ChannelState, _value: any): () end,
         read = function (_src: buffer, _pos: number, _refs: { Instance }?): (any, number)
             return nil, 0
         end,