@axpecter/lync 1.4.0 → 1.4.3

package/README.md

@@ -13,7 +13,7 @@
 
 ```toml
 [dependencies]
-Lync = "axp3cter/lync@1.4.0"
+Lync = "axp3cter/lync@1.4.2"
 ```
 
 **npm (roblox-ts)**
@@ -33,7 +33,7 @@ Or grab the `.rbxm` from [releases](https://github.com/Axp3cter/Lync/releases/la
 
 ## Example
 
-**Shared** (ReplicatedStorage, required by both)
+**Shared**
 
 ```luau
 local Lync = require(game.ReplicatedStorage.Lync)
@@ -163,7 +163,7 @@ end
 | | What it does |
 |:---------|:------------|
 | `Lync.start()` | Sets up transport. Server creates remotes, client connects. Call once after all definitions. |
-| `Lync.VERSION` | `"1.4.0"` |
+| `Lync.VERSION` | `"1.4.2"` |
 
 ## Packets
 
@@ -198,9 +198,9 @@ packet:send(data)  -- send to server
 
 | Method | What it does |
 |:-------|:------------|
-| `packet:listen(fn(data, sender))` | Listen for incoming. Returns a Connection. Sender is `Player` on server, `nil` on client. |
-| `packet:once(fn(data, sender))` | Same as listen but auto-disconnects after one fire. |
-| `packet:wait()` | Yields until next fire. Returns `(data, sender)`. |
+| `packet:listen(fn(data, sender))` | Sender is `Player` on server, `nil` on client. Returns a Connection. |
+| `packet:once(fn(data, sender))` | Auto-disconnects after one fire. |
+| `packet:wait()` | Returns `(data, sender)`. |
 | `packet:disconnectAll()` | Kills all listeners on this packet. |
 
 ## Queries
@@ -248,7 +248,7 @@ Returned by `packet:listen()`, `packet:once()`, `query:listen()`, and `ns:listen
 
 | | What it does |
 |:-------|:------------|
-| `connection.connected` | `true` if still connected, `false` after disconnect. |
+| `connection.connected` | `boolean` |
 | `connection:disconnect()` | Stops the listener. |
 
 ## Scope
@@ -267,11 +267,11 @@ scope:destroy()  -- disconnects everything
 
 | Method | What it does |
 |:-------|:------------|
-| `scope:listen(source, fn)` | Calls source:listen(fn) and tracks the connection. |
-| `scope:once(source, fn)` | Calls source:once(fn) and tracks the connection. |
-| `scope:listenAll(namespace, fn)` | Calls namespace:listenAll(fn) and tracks the connection. |
-| `scope:add(connection)` | Track a raw Connection or RBXScriptConnection. |
-| `scope:destroy()` | Disconnects all tracked connections. Safe to call multiple times. |
+| `scope:listen(source, fn)` | Calls `source:listen(fn)` and tracks the connection. |
+| `scope:once(source, fn)` | Calls `source:once(fn)` and tracks the connection. |
+| `scope:listenAll(namespace, fn)` | Calls `namespace:listenAll(fn)` and tracks the connection. |
+| `scope:add(connection)` | Also accepts RBXScriptConnection. |
+| `scope:destroy()` | Safe to call multiple times. |
 
 ## Groups
 
@@ -291,11 +291,11 @@ packet:send(data, vips)
 |:-------|:--------|:-------------|
 | `group:add(player)` | `boolean` | `true` if added, `false` if already in. |
 | `group:remove(player)` | `boolean` | `true` if removed, `false` if wasnt in there. |
-| `group:has(player)` | `boolean` | |
-| `group:count()` | `number` | |
-| `group:getSet()` | `{ [Player]: true }` | |
-| `group:forEach(fn)` | | Calls `fn(player)` for each member. |
-| `group:destroy()` | | Removes the group and all memberships. |
+| `group:has(player)` | `boolean` | Whether the player is in the group. |
+| `group:count()` | `number` | Number of members. |
+| `group:getSet()` | `{ [Player]: true }` | Snapshot of the internal set. |
+| `group:forEach(fn)` | `()` | Calls `fn(player)` for each member. |
+| `group:destroy()` | `()` | Removes the group and all memberships. |
 
 ## Middleware
 
@@ -415,10 +415,10 @@ Reliable only. Lync will error if you try to use these with `unreliable = true`.
 
 | Scenario | Without Lync | With Lync | FPS |
 |:---------|------------:|---------:|----:|
-| Static booleans (1B) | 480 Kbps | **2.45 Kbps** | 59.98 |
-| Static entities (34B) | 16,320 Kbps | **2.52 Kbps** | 60.00 |
-| Moving entities | 16,320 Kbps | **3.51 Kbps** | 59.99 |
-| Chaotic entities | 16,320 Kbps | **4.66 Kbps** | 59.99 |
+| Static booleans (1B) | 480 Kbps | **2.34 Kbps** | 60.00 |
+| Static entities (34B) | 16,320 Kbps | **2.62 Kbps** | 60.00 |
+| Moving entities | 16,320 Kbps | **3.14 Kbps** | 60.00 |
+| Chaotic entities | 16,320 Kbps | **4.76 Kbps** | 59.99 |
 
 ### Cross-Library Comparison
 
@@ -437,7 +437,7 @@ Same data shapes and methodology as [Blink's benchmark suite](https://github.com
 | Tool (Kbps) | Median | P0 | P80 | P90 | P95 | P100 |
 |:------------|-------:|---:|----:|----:|----:|-----:|
 | roblox | 559,364 | 559,364 | 676,715 | 676,715 | 676,715 | 784,081 |
-| **lync** | **3.59** | 3.50 | 3.61 | 3.62 | 3.62 | 4.86 |
+| **lync** | **3.61** | 3.53 | 3.63 | 3.64 | 3.64 | 4.64 |
 | blink | 41.81 | 26.30 | 42.40 | 42.48 | 42.48 | 42.62 |
 | zap | 41.71 | 25.46 | 42.19 | 42.32 | 42.32 | 42.93 |
 | bytenet | 41.64 | 22.84 | 42.36 | 42.82 | 42.82 | 43.24 |
@@ -447,7 +447,7 @@ Same data shapes and methodology as [Blink's benchmark suite](https://github.com
 | Tool (FPS) | Median | P0 | P80 | P90 | P95 | P100 |
 |:-----------|-------:|---:|----:|----:|----:|-----:|
 | roblox | 21.00 | 22.00 | 20.00 | 19.00 | 19.00 | 19.00 |
-| **lync** | **60.00** | 61.00 | 60.00 | 59.00 | 59.00 | 58.00 |
+| **lync** | **60.00** | 61.00 | 60.00 | 60.00 | 60.00 | 59.00 |
 | blink | 97.00 | 98.00 | 97.00 | 96.00 | 96.00 | 96.00 |
 | zap | 52.00 | 53.00 | 51.00 | 51.00 | 51.00 | 49.00 |
 | bytenet | 35.00 | 37.00 | 35.00 | 35.00 | 35.00 | 34.00 |
@@ -455,7 +455,7 @@ Same data shapes and methodology as [Blink's benchmark suite](https://github.com
 | Tool (Kbps) | Median | P0 | P80 | P90 | P95 | P100 |
 |:------------|-------:|---:|----:|----:|----:|-----:|
 | roblox | 353,107 | 196,826 | 690,747 | 842,240 | 842,240 | 1,124,176 |
-| **lync** | **4.31** | 3.77 | 4.33 | 4.34 | 4.34 | 4.43 |
+| **lync** | **4.31** | 3.85 | 4.36 | 4.38 | 4.38 | 4.44 |
 | blink | 7.91 | 7.41 | 7.93 | 7.99 | 7.99 | 8.00 |
 | zap | 8.10 | 5.75 | 8.17 | 8.22 | 8.22 | 8.27 |
 | bytenet | 8.11 | 5.07 | 8.35 | 8.46 | 8.46 | 8.47 |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@axpecter/lync",
-    "version": "1.4.0",
+    "version": "1.4.3",
     "description": "Buffer networking for Roblox. Delta compression, XOR framing, built-in security.",
     "main": "src/init.luau",
     "types": "src/index.d.ts",
@@ -28,7 +28,8 @@
         "luau"
     ],
     "files": [
-        "src"
+        "src",
+        "README.md"
     ],
     "devDependencies": {
         "@rbxts/compiler-types": "^3.0.0-types.0",

package/src/Types.luau

@@ -1,6 +1,6 @@
 --!strict
 --!optimize 2
--- Shared type definitions.
+-- Shared type definitions for the Lync networking library.
 
 export type ChannelState = {
     buff: buffer,
@@ -10,7 +10,7 @@ export type ChannelState = {
     lastId: number,
     countPos: number,
     itemCount: number,
-    deltas: { [number]: any },
+    deltas: { [number]: any }, -- per-codec delta caches; shape varies by codec kind
     prevDump: buffer?,
 }
 
@@ -19,6 +19,17 @@ export type Codec<T> = {
     read: (src: buffer, pos: number, refs: { Instance }?) -> (T, number),
 }
 
+-- Extended codec exposing internal fast-path metadata used by composite codecs.
+export type InternalCodec<T> = {
+    write: (ch: ChannelState, value: T) -> (),
+    read: (src: buffer, pos: number, refs: { Instance }?) -> (T, number),
+    _size: number?,
+    _directWrite: ((b: buffer, offset: number, value: T) -> ())?,
+    _directRead: ((b: buffer, offset: number) -> T)?,
+    _isDelta: boolean?,
+    _isBool: boolean?,
+}
+
 export type RateLimitConfig = {
     maxPerSecond: number,
     burstAllowance: number?,

package/src/api/Group.luau

@@ -4,13 +4,13 @@
 
 local Players = game:GetService ("Players")
 
--- State ------------------------------------------------------------------
+-- State --------------------------------------------------------------
 
 local _groups = {} :: { [string]: { [Player]: true } }
 local _counts = {} :: { [string]: number }
 local _playerGroups = {} :: { [Player]: { [string]: true } }
 
--- Private ----------------------------------------------------------------
+-- Private ------------------------------------------------------------
 
 local function onPlayerRemoving (player: Player): ()
     local memberships = _playerGroups[player]
@@ -31,8 +31,6 @@ end
 
 Players.PlayerRemoving:Connect (onPlayerRemoving)
 
--- GroupImpl ---------------------------------------------------------------
-
 local GroupImpl = {}
 GroupImpl.__index = GroupImpl
 
@@ -139,7 +137,7 @@ end
 
 table.freeze (GroupImpl)
 
--- Public -----------------------------------------------------------------
+-- Public -------------------------------------------------------------
 
 local Group = {}
 

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 = {}
 

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 ()
 
@@ -24,7 +25,10 @@ local serverWriteToAllExcept = Server.writeToAllExcept
 local serverWriteToSet = Server.writeToSet
 local clientWrite = Client.write
 
--- Private ----------------------------------------------------------------
+local DELTA_TARGETED = 1
+local DELTA_BROADCAST = 2
+
+-- Private ------------------------------------------------------------
 
 -- Shared methods (both contexts)
 local SharedImpl = {}
@@ -49,9 +53,6 @@ end
 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
@@ -122,7 +123,7 @@ end
 
 table.freeze (ClientImpl)
 
--- Public -----------------------------------------------------------------
+-- Public -------------------------------------------------------------
 
 local Packet = {}
 
@@ -136,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
 
@@ -152,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

@@ -14,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?,
@@ -33,7 +33,7 @@ local _pending = {} :: { [number]: PendingQuery }
 local _nextId = 0
 local _activeCount = 0
 
--- Private ----------------------------------------------------------------
+-- Private ------------------------------------------------------------
 
 local function allocCorrelation (): number
     if _activeCount >= POOL_SIZE then
@@ -53,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
 
@@ -64,7 +66,7 @@ local function completeQuery (id: number, data: any): ()
     end
 
     _pending[id] = nil
-    freeCorrelation ()
+    releaseCorrelation ()
 
     if entry.timeout then
         task.cancel (entry.timeout)
@@ -158,7 +160,7 @@ local function requestMulti (self: any, players: { Player }, data: any): { [Play
             local entry = _pending[cid]
             if entry then
                 _pending[cid] = nil
-                freeCorrelation ()
+                releaseCorrelation ()
             end
         end
 
@@ -176,8 +178,6 @@ local function requestMulti (self: any, players: { Player }, data: any): { [Play
     return coroutine.yield ()
 end
 
--- Query ------------------------------------------------------------------
-
 local QueryImpl = {}
 QueryImpl.__index = QueryImpl
 
@@ -274,7 +274,9 @@ function QueryImpl.requestGroup (self: any, group: any, data: any): { [Player]:
     return requestMulti (self, players, data)
 end
 
--- Public -----------------------------------------------------------------
+table.freeze (QueryImpl)
+
+-- Public -------------------------------------------------------------
 
 local Query = {}
 

package/src/api/Scope.luau

@@ -2,7 +2,7 @@
 --!optimize 2
 -- Batched connection lifecycle management.
 
--- Private ----------------------------------------------------------------
+-- Private ------------------------------------------------------------
 
 local ScopeImpl = {}
 ScopeImpl.__index = ScopeImpl
@@ -62,7 +62,7 @@ end
 
 table.freeze (ScopeImpl)
 
--- Public -----------------------------------------------------------------
+-- Public -------------------------------------------------------------
 
 local 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,

package/src/codec/composite/Array.luau

@@ -4,14 +4,15 @@
 
 local Baseline = require (script.Parent.Parent.Parent.internal.Baseline)
 local Channel = require (script.Parent.Parent.Parent.internal.Channel)
-local alloc = Channel.alloc
 local Shared = require (script.Parent.Shared)
 local Types = require (script.Parent.Parent.Parent.Types)
+local Varint = require (script.Parent.Parent.primitive.Varint)
 
 type ChannelState = Types.ChannelState
 type Codec<T> = Types.Codec<T>
-local Varint = require (script.Parent.Parent.primitive.Varint)
+type InternalCodec<T> = Types.InternalCodec<T>
 
+local alloc = Channel.alloc
 local rangeEqual = Shared.rangeEqual
 local acquireScratch = Shared.acquireScratch
 local releaseScratch = Shared.releaseScratch
@@ -20,7 +21,7 @@ local FLAG_DELTA = Shared.FLAG_DELTA
 local FLAG_FULL = Shared.FLAG_FULL
 local FLAG_UNCHANGED = Shared.FLAG_UNCHANGED
 
--- Public -----------------------------------------------------------------
+-- Public -------------------------------------------------------------
 
 local Array = {}
 
@@ -30,9 +31,10 @@ function Array.deltaArray (element: Codec<any>, maxCount: number?): Codec<{ any
     local writeElement = element.write
     local readElement = element.read
 
-    local elemSize = (element :: any)._size :: number?
-    local elemDirect = (element :: any)._directWrite
-    local elemDRead = (element :: any)._directRead
+    local internal = element :: InternalCodec<any>
+    local elemSize = internal._size
+    local elemWrite = internal._directWrite
+    local elemRead = internal._directRead
 
     return table.freeze ({
         _isDelta = true,
@@ -45,13 +47,13 @@ function Array.deltaArray (element: Codec<any>, maxCount: number?): Codec<{ any
             local bounds = table.create (len + 1)
             bounds[1] = 0
 
-            if elemDirect and elemSize then
+            if elemWrite and elemSize then
                 local totalBytes = len * elemSize
                 alloc (scratch, totalBytes)
                 local b = scratch.buff
                 local c = 0
                 for i = 1, len do
-                    elemDirect (b, c, value[i])
+                    elemWrite (b, c, value[i])
                     c += elemSize
                     bounds[i + 1] = c
                 end
@@ -147,9 +149,9 @@ function Array.deltaArray (element: Codec<any>, maxCount: number?): Codec<{ any
 
                 local result = table.create (len)
 
-                if elemDRead and elemSize then
+                if elemRead and elemSize then
                     for i = 1, len do
-                        result[i] = elemDRead (src, absPos)
+                        result[i] = elemRead (src, absPos)
                         absPos += elemSize
                     end
                 else
@@ -174,8 +176,8 @@ function Array.deltaArray (element: Codec<any>, maxCount: number?): Codec<{ any
                 local idx, idxBytes = Varint.read (src, absPos)
                 absPos += idxBytes
 
-                if elemDRead and elemSize then
-                    result[idx + 1] = elemDRead (src, absPos)
+                if elemRead and elemSize then
+                    result[idx + 1] = elemRead (src, absPos)
                     absPos += elemSize
                 else
                     local val, n = readElement (src, absPos, refs)
@@ -191,9 +193,10 @@ function Array.deltaArray (element: Codec<any>, maxCount: number?): Codec<{ any
 end
 
 function Array.array (element: Codec<any>, maxCount: number?): Codec<{ any }>
-    local elementSize = (element :: any)._size :: number?
-    local directWrite = (element :: any)._directWrite
-    local directRead = (element :: any)._directRead
+    local internal = element :: InternalCodec<any>
+    local elementSize = internal._size
+    local directWrite = internal._directWrite
+    local directRead = internal._directRead
 
     if elementSize and directWrite and directRead then
         return table.freeze ({