@axpecter/lync 2.1.2 → 2.2.0

package/src/codec/meta/Custom.luau

@@ -3,29 +3,29 @@
 -- User-defined fixed-size codec.
 
 local Base = require(script.Parent.Parent.Base)
+local Types = require(script.Parent.Parent.Parent.Types)
 
--- Private -------------------------------------------------------------
+-- Private ----------------------------------------------------------------
 
 local floor = math.floor
 
--- Public --------------------------------------------------------------
+-- Public -----------------------------------------------------------------
 
 local Custom = {}
 
-function Custom.define(
+function Custom.define<T>(
     size: number,
-    writeFn: (b: buffer, offset: number, value: any) -> (),
-    readFn: (b: buffer, offset: number) -> any
-): any
+    writeFn: (b: buffer, offset: number, value: T) -> (),
+    readFn: (b: buffer, offset: number) -> T,
+    typeCheck: string?
+): Types.InternalCodec<T>
     if type(size) ~= "number" or size < 0 or floor(size) ~= size then
         error("[Lync] Lync.custom: size must be a non-negative integer")
     end
-
     if size == 0 then
-        return Base.zero()
+        return Base.constant(nil :: any) :: Types.InternalCodec<T>
     end
-
-    return Base.define(size, writeFn, readFn)
+    return Base.define(size, writeFn, readFn, if typeCheck then { _typeCheck = typeCheck } else nil)
 end
 
 return table.freeze(Custom)

package/src/codec/meta/Enum.luau

@@ -1,14 +1,15 @@
 --!strict
 --!optimize 2
--- String enum codec. Maps values to u8 indices at define time.
+-- String-keyed enum codec. Maps values to u8 indices at definition time.
 
 local Base = require(script.Parent.Parent.Base)
+local Types = require(script.Parent.Parent.Parent.Types)
 
--- Public --------------------------------------------------------------
+-- Public -----------------------------------------------------------------
 
 local EnumCodec = {}
 
-function EnumCodec.define(...: string): any
+function EnumCodec.define(...: string): Types.InternalCodec<string>
     local values = { ... }
     local count = #values
     if count == 0 then
@@ -18,10 +19,8 @@ function EnumCodec.define(...: string): any
         error("[Lync] Lync.enum: exceeds 256 variants")
     end
 
-    -- Build lookup tables
     local toIndex: { [string]: number } = {}
     local toValue = table.create(count)
-
     for i = 1, count do
         local val = values[i]
         if toIndex[val] then
@@ -30,24 +29,22 @@ function EnumCodec.define(...: string): any
         toIndex[val] = i - 1
         toValue[i] = val
     end
-
     table.freeze(toIndex)
     table.freeze(toValue)
 
     return Base.define(1, function(b: buffer, off: number, value: string): ()
         local idx = toIndex[value]
         if idx == nil then
-            error(`[Lync] Enum: invalid value "{value}"`)
+            error(`[Lync] Enum.write: invalid value "{value}"`)
         end
         buffer.writeu8(b, off, idx)
     end, function(b: buffer, off: number): string
-        local idx = buffer.readu8(b, off)
-        local val = toValue[idx + 1]
+        local val = toValue[buffer.readu8(b, off) + 1]
         if val == nil then
-            error(`[Lync] Enum: invalid index {idx}`)
+            error(`[Lync] Enum.read: invalid index`)
         end
         return val
-    end, { _typeCheck = "string" })
+    end, { _typeCheck = "string", _isEnum = true, _enumValues = toIndex })
 end
 
 return table.freeze(EnumCodec)

package/src/codec/meta/Float.luau

@@ -1,22 +1,27 @@
 --!strict
 --!native
--- Fixed-point quantization codec. Maps float ranges to integer ranges.
+-- Fixed-point quantization codec. Maps a float range to u8/u16/u32.
 
 local Base = require(script.Parent.Parent.Base)
+local Types = require(script.Parent.Parent.Parent.Types)
 
--- Private -------------------------------------------------------------
+-- Private ----------------------------------------------------------------
 
 local ceil = math.ceil
 local clamp = math.clamp
 local round = math.round
-local max = math.max
-local min = math.min
+local maxN = math.max
+local minN = math.min
 
--- Public --------------------------------------------------------------
+-- Public -----------------------------------------------------------------
 
 local Float = {}
 
-function Float.float(rangeMin: number, rangeMax: number, precision: number): any
+function Float.float(
+    rangeMin: number,
+    rangeMax: number,
+    precision: number
+): Types.InternalCodec<number>
     if rangeMin > rangeMax then
         error(`[Lync] Lync.float: min ({rangeMin}) must be <= max ({rangeMax})`)
     end
@@ -25,30 +30,21 @@ function Float.float(rangeMin: number, rangeMax: number, precision: number): any
     end
 
     local delta = rangeMax - rangeMin
-
-    -- Constant value: zero bytes
     if delta == 0 then
-        return Base.zero()
+        return Base.constant(rangeMin)
     end
 
-    local maxInt = min(0xFFFFFFFF, max(1, ceil(delta / precision)))
+    local maxInt = minN(0xFFFFFFFF, maxN(1, ceil(delta / precision)))
 
     local compBytes: number
     local wfn: (buffer, number, number) -> ()
     local rfn: (buffer, number) -> number
-
     if maxInt <= 0xFF then
-        compBytes = 1
-        wfn = buffer.writeu8
-        rfn = buffer.readu8
+        compBytes, wfn, rfn = 1, buffer.writeu8, buffer.readu8
     elseif maxInt <= 0xFFFF then
-        compBytes = 2
-        wfn = buffer.writeu16
-        rfn = buffer.readu16
+        compBytes, wfn, rfn = 2, buffer.writeu16, buffer.readu16
     else
-        compBytes = 4
-        wfn = buffer.writeu32
-        rfn = buffer.readu32
+        compBytes, wfn, rfn = 4, buffer.writeu32, buffer.readu32
     end
 
     local scale = maxInt / delta

package/src/codec/meta/Nothing.luau

@@ -4,10 +4,10 @@
 
 local Base = require(script.Parent.Parent.Base)
 
--- Public --------------------------------------------------------------
+-- Public -----------------------------------------------------------------
 
 local Nothing = {}
 
-Nothing.nothing = Base.zero()
+Nothing.nothing = Base.constant(nil :: nil)
 
 return table.freeze(Nothing)

package/src/codec/meta/Unknown.luau

@@ -2,47 +2,37 @@
 --!optimize 2
 -- Bypasses buffer serialization. Uses Roblox remote sidecar refs.
 
-local Base = require(script.Parent.Parent.Base)
+local Channel = require(script.Parent.Parent.Parent.internal.Channel)
 local Types = require(script.Parent.Parent.Parent.Types)
 
--- Private -------------------------------------------------------------
+-- Private ----------------------------------------------------------------
 
-local alloc = Base.alloc
-local writeu16 = buffer.writeu16
+local pushRef = Channel.pushRef
 local readu16 = buffer.readu16
 
--- Public --------------------------------------------------------------
+local function writeUnknown(ch: Types.ChannelState, value: any): ()
+    pushRef(ch, value)
+end
+
+local function readUnknown(src: buffer, pos: number, refs: { Instance }?): (any, number)
+    if not refs then
+        error("[Lync] Unknown.read: refs array is required")
+    end
+    local idx = readu16(src, pos)
+    if idx < 1 or idx > #refs then
+        error(`[Lync] Unknown.read: ref index {idx} out of bounds`)
+    end
+    return refs[idx], 2
+end
+
+-- Public -----------------------------------------------------------------
 
 local Unknown = {}
 
 Unknown.unknown = table.freeze({
     _hasUnknown = true,
-
-    write = function(ch: Types.ChannelState, value: any): ()
-        local idx = ch.refCount + 1
-        if idx > 0xFFFF then
-            error("[Lync] Unknown: ref overflow (>65535)")
-        end
-
-        ch.refs[idx] = value :: any
-        ch.refCount = idx
-
-        local cursor = ch.cursor
-        if cursor + 2 > ch.size then
-            alloc(ch, 2)
-        end
-        writeu16(ch.buff, cursor, idx)
-        ch.cursor = cursor + 2
-    end,
-
-    read = function(src: buffer, pos: number, refs: { Instance }?): (any, number)
-        if not refs then
-            error("[Lync] Unknown: read requires refs array")
-        end
-
-        local idx = readu16(src, pos)
-        return (refs :: any)[idx], 2
-    end,
-} :: any)
+    write = writeUnknown,
+    read = readUnknown,
+})
 
 return table.freeze(Unknown)

package/src/codec/primitive/Bool.luau

@@ -1,18 +1,22 @@
 --!strict
 --!optimize 2
--- Boolean codec with bitpacking flag for struct and array codecs.
+-- Single-byte boolean codec. _isBool flag enables struct/array bit packing.
 
 local Base = require(script.Parent.Parent.Base)
 
--- Public --------------------------------------------------------------
+-- Public -----------------------------------------------------------------
 
 local Bool = {}
 
-Bool.bool = Base.define(1, function(b: buffer, off: number, value: boolean): ()
+local function writeBool(b: buffer, off: number, value: boolean): ()
     buffer.writeu8(b, off, if value then 1 else 0)
-end, function(b: buffer, off: number): boolean
+end
+
+local function readBool(b: buffer, off: number): boolean
     return buffer.readu8(b, off) ~= 0
-end, {
+end
+
+Bool.bool = Base.define(1, writeBool, readBool, {
     _isBool = true,
     _typeCheck = "boolean",
 })

package/src/codec/primitive/Float16.luau

@@ -1,10 +1,16 @@
 --!strict
 --!native
--- Half-precision float codec. 2 bytes, ±65504, ~3 decimal digits.
+-- IEEE 754 binary16 codec. 2 bytes, +/- 65504, ~3 decimal digits of precision.
 
 local Base = require(script.Parent.Parent.Base)
 
--- Private -------------------------------------------------------------
+-- Constants --------------------------------------------------------------
+
+local MAX_FINITE = 65504
+local NAN_BITS = 0x7E00
+local INF_BITS = 0x7C00
+
+-- Private ----------------------------------------------------------------
 
 local band = bit32.band
 local bor = bit32.bor
@@ -16,37 +22,29 @@ local round = math.round
 local huge = math.huge
 
 local function encode(value: number): number
-    -- NaN
     if value ~= value then
-        return 0x7E00
+        return NAN_BITS
     end
-
-    -- Zero (both +0 and -0 map to positive zero)
     if value == 0 then
         return 0
     end
 
-    -- Sign extraction
     local sign = 0
     if value < 0 then
         sign = 0x8000
         value = -value
     end
 
-    -- Overflow to infinity
-    if value > 65504 then
-        return bor(sign, 0x7C00)
+    if value > MAX_FINITE then
+        return bor(sign, INF_BITS)
     end
 
-    -- Decompose via frexp: value = mantissa * 2^exponent, mantissa in [0.5, 1)
     local mantissa, exponent = frexp(value)
     local biasedExp = exponent + 14
 
     if biasedExp <= 0 then
-        -- Subnormal: frac = round(mantissa * 2^(biasedExp + 10))
         local frac = round(ldexp(mantissa, biasedExp + 10))
         if frac >= 1024 then
-            -- Rounds to minimum normal
             return bor(sign, 0x0400)
         end
         if frac <= 0 then
@@ -55,18 +53,14 @@ local function encode(value: number): number
         return bor(sign, frac)
     end
 
-    -- Normal: frac = round((mantissa * 2 - 1) * 1024)
     local frac = round((mantissa * 2 - 1) * 1024)
-
-    -- Carry: mantissa rounding overflows into exponent
     if frac >= 1024 then
         frac = 0
         biasedExp += 1
     end
 
-    -- Overflow after carry
     if biasedExp >= 31 then
-        return bor(sign, 0x7C00)
+        return bor(sign, INF_BITS)
     end
 
     return bor(sign, lshift(biasedExp, 10), frac)
@@ -78,22 +72,18 @@ local function decode(raw: number): number
     local frac = band(raw, 0x03FF)
 
     local value: number
-
     if exp == 0 then
-        -- Zero or subnormal
         value = if frac == 0 then 0 else ldexp(frac, -24)
     elseif exp == 31 then
-        -- Infinity or NaN
         value = if frac == 0 then huge else 0 / 0
     else
-        -- Normal: (frac + 1024) * 2^(exp - 25)
         value = ldexp(frac + 1024, exp - 25)
     end
 
     return if sign ~= 0 then -value else value
 end
 
--- Public --------------------------------------------------------------
+-- Public -----------------------------------------------------------------
 
 local Float16 = {}
 

package/src/codec/primitive/Int.luau

@@ -1,18 +1,23 @@
 --!strict
 --!optimize 2
--- Smart integer codec. Auto-selects u8/u16/u32/i8/i16/i32 from range.
+-- Range-typed integer codec. Picks the narrowest u8/u16/u32/i8/i16/i32 wire form.
 
 local Base = require(script.Parent.Parent.Base)
+local Signed = require(script.Parent.Signed)
+local Types = require(script.Parent.Parent.Parent.Types)
 
--- Private -------------------------------------------------------------
+-- Private ----------------------------------------------------------------
 
 local floor = math.floor
+local writeI8 = Signed.writeI8
+local writeI16 = Signed.writeI16
+local writeI32 = Signed.writeI32
 
--- Public --------------------------------------------------------------
+-- Public -----------------------------------------------------------------
 
 local Int = {}
 
-function Int.int(min: number, max: number): any
+function Int.int(min: number, max: number): Types.InternalCodec<number>
     if min > max then
         error(`[Lync] Lync.int: min ({min}) must be <= max ({max})`)
     end
@@ -28,37 +33,24 @@ function Int.int(min: number, max: number): any
     }
 
     if min >= 0 then
-        -- Unsigned path
         if max <= 0xFF then
             return Base.define(1, buffer.writeu8, buffer.readu8, meta)
-        elseif max <= 0xFFFF then
+        end
+        if max <= 0xFFFF then
             return Base.define(2, buffer.writeu16, buffer.readu16, meta)
-        elseif max <= 0xFFFFFFFF then
+        end
+        if max <= 0xFFFFFFFF then
             return Base.define(4, buffer.writeu32, buffer.readu32, meta)
         end
     else
-        -- Signed path: use unsigned write/read, interpret as signed
         if min >= -0x80 and max <= 0x7F then
-            return Base.define(1, function(b: buffer, off: number, v: number): ()
-                buffer.writeu8(b, off, if v < 0 then v + 0x100 else v)
-            end, function(b: buffer, off: number): number
-                local raw = buffer.readu8(b, off)
-                return if raw >= 0x80 then raw - 0x100 else raw
-            end, meta)
-        elseif min >= -0x8000 and max <= 0x7FFF then
-            return Base.define(2, function(b: buffer, off: number, v: number): ()
-                buffer.writeu16(b, off, if v < 0 then v + 0x10000 else v)
-            end, function(b: buffer, off: number): number
-                local raw = buffer.readu16(b, off)
-                return if raw >= 0x8000 then raw - 0x10000 else raw
-            end, meta)
-        elseif min >= -0x80000000 and max <= 0x7FFFFFFF then
-            return Base.define(4, function(b: buffer, off: number, v: number): ()
-                buffer.writeu32(b, off, if v < 0 then v + 0x100000000 else v)
-            end, function(b: buffer, off: number): number
-                local raw = buffer.readu32(b, off)
-                return if raw >= 0x80000000 then raw - 0x100000000 else raw
-            end, meta)
+            return Base.define(1, writeI8, buffer.readi8, meta)
+        end
+        if min >= -0x8000 and max <= 0x7FFF then
+            return Base.define(2, writeI16, buffer.readi16, meta)
+        end
+        if min >= -0x80000000 and max <= 0x7FFFFFFF then
+            return Base.define(4, writeI32, buffer.readi32, meta)
         end
     end
 

package/src/codec/primitive/Number.luau

@@ -4,23 +4,19 @@
 
 local Base = require(script.Parent.Parent.Base)
 
--- Constants -----------------------------------------------------------
+-- Constants --------------------------------------------------------------
 
+-- Shared scratch for Auto codec's f32 round-trip test. Roblox is
+-- single-threaded so a module-level scratch cannot be aliased.
 local F32_SCRATCH = buffer.create(4)
 
--- Public --------------------------------------------------------------
+-- Public -----------------------------------------------------------------
 
 local Number = {}
 
-Number.f32 = Base.define(4, buffer.writef32, buffer.readf32, {
-    _typeCheck = "number",
-})
+Number.f32 = Base.define(4, buffer.writef32, buffer.readf32, { _typeCheck = "number" })
+Number.f64 = Base.define(8, buffer.writef64, buffer.readf64, { _typeCheck = "number" })
 
-Number.f64 = Base.define(8, buffer.writef64, buffer.readf64, {
-    _typeCheck = "number",
-})
-
--- Shared scratch buffer for Auto codec f32 round-trip test
 Number._f32Scratch = F32_SCRATCH
 
 return table.freeze(Number)

package/src/codec/primitive/Signed.luau

@@ -0,0 +1,32 @@
+--!strict
+--!native
+-- Signed integer buffer helpers. Reads use FASTCALL2 readi*; writes
+-- emulate via writeu* + two's complement (writei* is not FASTCALL).
+
+-- Private ----------------------------------------------------------------
+
+local writeu8 = buffer.writeu8
+local writeu16 = buffer.writeu16
+local writeu32 = buffer.writeu32
+
+-- Public -----------------------------------------------------------------
+
+local Signed = {}
+
+function Signed.writeI8(b: buffer, off: number, value: number): ()
+    writeu8(b, off, if value < 0 then value + 0x100 else value)
+end
+
+function Signed.writeI16(b: buffer, off: number, value: number): ()
+    writeu16(b, off, if value < 0 then value + 0x10000 else value)
+end
+
+function Signed.writeI32(b: buffer, off: number, value: number): ()
+    writeu32(b, off, if value < 0 then value + 0x100000000 else value)
+end
+
+Signed.readI8 = buffer.readi8
+Signed.readI16 = buffer.readi16
+Signed.readI32 = buffer.readi32
+
+return table.freeze(Signed)

package/src/codec/primitive/Varint.luau

@@ -1,15 +1,26 @@
 --!strict
 --!native
--- Dense prefix-varint encoding with single-branch decode.
+-- Dense prefix varint. Single-branch decode, range up to 2^32 - 1.
 
 local Base = require(script.Parent.Parent.Base)
 local Types = require(script.Parent.Parent.Parent.Types)
 
--- Constants -----------------------------------------------------------
+-- Constants --------------------------------------------------------------
 
+--[[
+    Wire layout (first byte determines length):
+      0x00..0xBF  1 byte   value = b0                         [0..191]
+      0xC0..0xDF  2 bytes  value = (b0 & 0x1F)<<8 | b1 + 192  [192..8383]
+      0xE0..0xEF  3 bytes  value = (b0 & 0x0F)<<16 | u16 + 8384 [8384..1056959]
+      0xF0..0xFF  5 bytes  value = u32                        [..0xFFFFFFFF]
+]]
 local INLINE_MAX = 0xBF
+local TWO_MAX = 8383
+local THREE_MAX = 1056959
+local TWO_BIAS = 192
+local THREE_BIAS = 8384
 
--- Private -------------------------------------------------------------
+-- Private ----------------------------------------------------------------
 
 local alloc = Base.alloc
 local band = bit32.band
@@ -22,7 +33,7 @@ local readu8 = buffer.readu8
 local readu16 = buffer.readu16
 local readu32 = buffer.readu32
 
--- Public --------------------------------------------------------------
+-- Public -----------------------------------------------------------------
 
 local Varint = {}
 
@@ -30,61 +41,68 @@ Varint.INLINE_MAX = INLINE_MAX
 
 function Varint.write(ch: Types.ChannelState, value: number): ()
     if value < 0 or value > 0xFFFFFFFF or value % 1 ~= 0 then
-        error(`[Lync] Varint: value must be an integer in [0, 4294967295], got {value}`)
+        error(`[Lync] Varint.write: value must be an integer in [0, 4294967295], got {value}`)
     end
 
     local cursor = ch.cursor
-    local b = ch.buff
 
     if value <= INLINE_MAX then
         if cursor + 1 > ch.size then
             alloc(ch, 1)
         end
-        writeu8(b, cursor, value)
+        writeu8(ch.buff, cursor, value)
         ch.cursor = cursor + 1
-    elseif value <= 8383 then
+        return
+    end
+
+    if value <= TWO_MAX then
         if cursor + 2 > ch.size then
             alloc(ch, 2)
         end
-        local adjusted = value - 192
-        b = ch.buff -- alloc may have replaced the buffer
+        local adjusted = value - TWO_BIAS
+        local b = ch.buff
         writeu8(b, cursor, bor(0xC0, rshift(adjusted, 8)))
         writeu8(b, cursor + 1, band(adjusted, 0xFF))
         ch.cursor = cursor + 2
-    elseif value <= 1056959 then
+        return
+    end
+
+    if value <= THREE_MAX then
         if cursor + 3 > ch.size then
             alloc(ch, 3)
         end
-        local adjusted = value - 8384
-        b = ch.buff
+        local adjusted = value - THREE_BIAS
+        local b = ch.buff
         writeu8(b, cursor, bor(0xE0, rshift(adjusted, 16)))
         writeu16(b, cursor + 1, band(adjusted, 0xFFFF))
         ch.cursor = cursor + 3
-    else
-        if cursor + 5 > ch.size then
-            alloc(ch, 5)
-        end
-        b = ch.buff
-        writeu8(b, cursor, 0xF0)
-        writeu32(b, cursor + 1, value)
-        ch.cursor = cursor + 5
+        return
+    end
+
+    if cursor + 5 > ch.size then
+        alloc(ch, 5)
     end
+    local b = ch.buff
+    writeu8(b, cursor, 0xF0)
+    writeu32(b, cursor + 1, value)
+    ch.cursor = cursor + 5
 end
 
 function Varint.read(src: buffer, pos: number): (number, number)
     local b0 = readu8(src, pos)
-
     if b0 <= INLINE_MAX then
         return b0, 1
-    elseif b0 <= 0xDF then
-        return band(b0, 0x1F) * 256 + readu8(src, pos + 1) + 192, 2
-    elseif b0 <= 0xEF then
-        return band(b0, 0x0F) * 65536 + readu16(src, pos + 1) + 8384, 3
-    else
-        return readu32(src, pos + 1), 5
     end
+    if b0 <= 0xDF then
+        return band(b0, 0x1F) * 256 + readu8(src, pos + 1) + TWO_BIAS, 2
+    end
+    if b0 <= 0xEF then
+        return band(b0, 0x0F) * 65536 + readu16(src, pos + 1) + THREE_BIAS, 3
+    end
+    return readu32(src, pos + 1), 5
 end
 
+-- Encode a value already known to fit in INLINE_MAX (single byte).
 function Varint.writeInline(ch: Types.ChannelState, value: number): ()
     local cursor = ch.cursor
     if cursor + 1 > ch.size then
@@ -94,4 +112,17 @@ function Varint.writeInline(ch: Types.ChannelState, value: number): ()
     ch.cursor = cursor + 1
 end
 
+--[[
+    Decode a length prefix that uses the single-byte fast path for
+    lengths in [0, INLINE_MAX] and the full varint encoding above that.
+    Used by Buffer, String, and Auto's string branch.
+]]
+function Varint.readLengthPrefix(src: buffer, pos: number): (number, number)
+    local b0 = readu8(src, pos)
+    if b0 <= INLINE_MAX then
+        return b0, 1
+    end
+    return Varint.read(src, pos)
+end
+
 return table.freeze(Varint)