@axpecter/lync 2.3.2 → 3.0.0

package/codec/Base.luau

@@ -0,0 +1,236 @@
+--!strict
+--!optimize 2
+-- The codec cell: one frozen value per declaration, and the four modifiers that answer another.
+
+local Log = require (script.Parent.Parent.kernel.Log)
+local Types = require (script.Parent.Parent.Types)
+
+local Base = {}
+
+--[[
+    The one metatable every codec shares, so a declaration costs one table and `table.clone`
+    carries it to every copy it makes.
+]]
+local Modifiers = {}
+Modifiers.__index = Modifiers
+
+-- Constants -----------------------------------------------------------
+
+-- Shared by every codec declaring neither, since two frozen empty tables cannot be told apart.
+const NO_PARAMS: Params = table.freeze ({})
+const NO_CHECKS = table.freeze ({} :: { Validate })
+
+-- Types ---------------------------------------------------------------
+
+export type Kind =
+    "bool"
+    | "int"
+    | "quant"
+    | "angle"
+    | "f32"
+    | "f64"
+    | "vlq"
+    | "vli"
+    | "str"
+    | "buffer"
+    | "struct"
+    | "array"
+    | "map"
+    | "optional"
+    | "tagged"
+    | "enum"
+    | "bitfield"
+    | "vec2"
+    | "vec3"
+    | "cframe"
+    | "rotation"
+    | "color3"
+    | "inst"
+
+export type Marker = "none" | "monotonic" | "newest"
+
+export type Validate = (value: any, ctx: Types.ValidateContext) -> string?
+
+--[[
+    Every parameter any constructor records, in one vocabulary. The set is closed and holds nothing
+    without exact text: the descriptor writes parameters as decimals, and two machines agreeing on
+    a schema is that text agreeing.
+]]
+export type Params = {
+    read min: number?,
+    read max: number?,
+    read step: number?,
+    read form: string?,
+    read field: string?,
+    read symbols: string?,
+    read class: string?,
+    read names: { string }?,
+    read colors: { Color3 }?,
+    read axis: Vector3?,
+}
+
+--[[
+    A declaration, frozen, as the compile path reads it. There is one codec type and it is the
+    public one, since two over one value cost more than the accessor below and neither an
+    intersection nor a flat pair survives the solver. It carries no value type either: a walk over
+    children meets a different one at every node.
+]]
+export type Cell = {
+    read kind: Kind,
+    read params: Params,
+    read children: { [string]: Cell }?,
+    read validates: { Validate },
+    read marker: Marker,
+    read newestHz: number?,
+    read lift: ((wire: any) -> any)?,
+    read lower: ((domain: any) -> any)?,
+}
+
+--[[
+    What the library builds for itself: the one or two children a composite names. A caller's own
+    table does not come through here, because a table whose properties are read-only satisfies no
+    indexer in this solver and everything in this repository is frozen.
+]]
+export type Children = { [string]: Types.Codec<any> }
+
+--[[
+    A cell mid-change, with the five facts a modifier may move writable and everything that decides
+    a layout still read-only. A modifier that tried to widen a field does not compile, which is the
+    claim `codec.modifier-free` makes from the other end.
+]]
+type Open = {
+    read kind: Kind,
+    read params: Params,
+    read children: { [string]: Cell }?,
+    validates: { Validate },
+    marker: Marker,
+    newestHz: number?,
+    lift: ((wire: any) -> any)?,
+    lower: ((domain: any) -> any)?,
+}
+
+-- Private -------------------------------------------------------------
+
+local function opened (of: Types.Codec<any>): Open return table.clone (of :: any) :: any end
+
+local function sealed (made: Open): Types.Codec<any> return table.freeze (made :: any) :: any end
+
+-- Public --------------------------------------------------------------
+
+-- A codec as its constructor declares it, before any modifier.
+function Base.make (kind: Kind, params: Params?, children: Children?): Types.Codec<any>
+    local held: any = if children == nil then nil else table.freeze (table.clone (children))
+
+    local taken: any = params
+    if taken ~= nil then
+        for name, value in taken do
+            if type (value) == "table" then taken[name] = table.freeze (table.clone (value)) end
+        end
+    end
+
+    return table.freeze (setmetatable ({
+        kind = kind,
+        params = if params == nil then NO_PARAMS else table.freeze (params),
+        children = held,
+        validates = NO_CHECKS,
+        marker = "none" :: Marker,
+    }, Modifiers)) :: any
+end
+
+--[[
+    The same value as the compile path reads it. One call rather than a cast at every field, and the
+    one place the two views of a codec meet.
+]]
+function Base.cell (of: Types.Codec<any>): Cell return of :: any end
+
+-- The other way round, which is one table read two ways and never two tables.
+function Base.codec (of: Cell): Types.Codec<any> return of :: any end
+
+-- Whether a value came from here, which is what a composite asks of every child handed to it.
+function Base.made (value: unknown): boolean return getmetatable (value :: any) == Modifiers end
+
+--[[
+    Checks run in declaration order and the first reason wins, so a chain appends rather than
+    replaces. The array is frozen with the cell: a codec is a value, and a value whose checks could
+    be appended to from outside would be two schemas under one hash.
+]]
+function Modifiers.validate <T>(
+    self: Types.Codec<T>,
+    check: (value: T, ctx: Types.ValidateContext) -> string?
+): Types.Codec<T>
+    local checks = table.clone (Base.cell (self).validates)
+    table.insert (checks, check :: Validate)
+
+    local made = opened (self)
+    made.validates = table.freeze (checks)
+    return sealed (made)
+end
+
+--[[
+    The rate goes with the marker it belonged to, so a chain never leaves one behind a marker that
+    has none and a descriptor never writes a rate onto `monotonic`.
+]]
+function Modifiers.monotonic <T>(self: Types.Codec<T>): Types.Codec<T>
+    local made = opened (self)
+    made.marker = "monotonic"
+    made.newestHz = nil
+    return sealed (made)
+end
+
+--[[
+    A rate of zero never opens its gate and a negative one always does, so both are a stream that
+    silently does not do what it says. Whether the marker belongs on this field at all is a
+    question about the shape underneath it, and is asked when the namespace starts.
+]]
+function Modifiers.newest <T>(self: Types.Codec<T>, hz: number?): Types.Codec<T>
+    if hz ~= nil and not (hz > 0 and hz < math.huge) then
+        Log.refuse (`newest takes a rate above zero, not {hz}`)
+    end
+
+    local made = opened (self)
+    made.marker = "newest"
+    made.newestHz = hz
+    return sealed (made)
+end
+
+--[[
+    A pair is adopted whole where there is none beneath it, and composed where there is. A datatype
+    is an `as` over its wire form, so the common case is the first one and a wrapper call per value
+    would tax every vector in every frame.
+]]
+function Modifiers.as <T, U>(
+    self: Types.Codec<T>,
+    to: (value: T) -> U,
+    from: (value: U) -> T
+): Types.Codec<U>
+    local held = Base.cell (self)
+    local lift, lower = held.lift, held.lower
+
+    local lifted = if lift == nil
+        then to :: any
+        else function (wire: any) return to (lift (wire)) end
+    local lowered = if lower == nil
+        then from
+        else function (domain: any) return lower (from (domain)) end
+
+    local made = opened (self)
+    made.lift = lifted
+    made.lower = lowered
+
+    local checks = held.validates
+    local reach = #checks
+    if reach == 0 then return sealed (made) end
+
+    local under = table.create (reach) :: { Validate }
+    for index = 1, reach do
+        local check = checks[index]
+        under[index] = function (value: any, ctx: Types.ValidateContext): string?
+            return check (from (value :: any), ctx)
+        end
+    end
+
+    made.validates = table.freeze (under)
+    return sealed (made)
+end
+
+return table.freeze (Base)

package/codec/Composites.luau

@@ -0,0 +1,128 @@
+--!strict
+--!optimize 2
+-- The seven composites: five that record a codec under a name, and two that record names alone.
+
+local Base = require (script.Parent.Base)
+local Legality = require (script.Parent.Legality)
+local Log = require (script.Parent.Parent.kernel.Log)
+local Types = require (script.Parent.Parent.Types)
+
+local Composites = {}
+
+-- Private -------------------------------------------------------------
+
+-- A list of distinct names, answered in the one order two machines both arrive at.
+local function labelled (kind: string, names: { string }): { string }
+    if type (names) ~= "table" then
+        Log.refuse (`{kind} takes a list of names, not a {typeof (names)}`)
+    end
+    if #names == 0 then Log.refuse (`{kind} takes at least one name`) end
+
+    local seen = {}
+    for index = 1, #names do
+        local name = names[index]
+        if type (name) ~= "string" then
+            Log.refuse (`{kind} takes names, and the one at {index} is a {typeof (name)}`)
+        end
+        if seen[name] ~= nil then
+            Log.refuse (`{kind} takes each name once, and {name} is twice`)
+        end
+        seen[name] = true
+    end
+
+    local held = table.clone (names)
+    table.sort (held)
+    return held
+end
+
+-- Public --------------------------------------------------------------
+
+--[[
+    The caller's own names, which are the only child names not chosen here. The table is taken as
+    it comes, since a frozen one satisfies no indexer in this solver, so each field is asked what it
+    is rather than the type above. No field at all is a record with nothing in it.
+]]
+function Composites.struct <S>(fields: S): Types.Codec<any>
+    if type (fields) ~= "table" then
+        Log.refuse (`struct takes a table of fields, not a {typeof (fields)}`)
+    end
+
+    for name, of in fields :: any do
+        if type (name) ~= "string" then
+            Log.refuse (`struct takes named fields, and {tostring (name)} is a {typeof (name)}`)
+        end
+        Legality.codec ("struct", name, of)
+    end
+
+    return Base.make ("struct", nil, fields :: any)
+end
+
+function Composites.array <T>(element: Types.Codec<T>, min: number, max: number): Types.Codec<{ T }>
+    Legality.bare ("array", "element", element)
+    Legality.counts ("array", min, max)
+
+    return Base.make ("array", { min = min, max = max }, { element = element })
+end
+
+function Composites.map <K, V>(
+    key: Types.Codec<K>,
+    value: Types.Codec<V>,
+    min: number,
+    max: number
+): Types.Codec<{ [K]: V }>
+    Legality.bare ("map", "key", key)
+    Legality.bare ("map", "value", value)
+    Legality.counts ("map", min, max)
+
+    return Base.make ("map", { min = min, max = max }, { key = key, value = value })
+end
+
+function Composites.optional <T>(inner: Types.Codec<T>): Types.Codec<T?>
+    Legality.bare ("optional", "inner", inner)
+    return Base.make ("optional", nil, { inner = inner })
+end
+
+--[[
+    The tag rides inside the record rather than beside it, so every variant is a struct and none of
+    them may already declare the field it is written into. One that did would have its own value
+    overwritten going out and read back as the tag coming in.
+]]
+function Composites.tagged <V>(field: string, variants: V): Types.Codec<any>
+    if type (field) ~= "string" or field == "" then
+        Log.refuse (`tagged takes a field name, not {tostring (field)}`)
+    end
+    if type (variants) ~= "table" then
+        Log.refuse (`tagged takes a table of variants, not a {typeof (variants)}`)
+    end
+    if next (variants :: any) == nil then Log.refuse ("tagged takes at least one variant") end
+
+    for name, of in variants :: any do
+        if type (name) ~= "string" then
+            Log.refuse (`tagged takes named variants, and {tostring (name)} is a {typeof (name)}`)
+        end
+        Legality.codec ("tagged", name, of)
+
+        if Base.cell (of).kind ~= "struct" then
+            Log.refuse (`tagged takes a struct for {name}, not a {Base.cell (of).kind}`)
+        end
+
+        local held = Base.cell (of).children
+        if held ~= nil and held[field] ~= nil then
+            Log.refuse (`the variant {name} already declares {field}, which is the tag`)
+        end
+    end
+
+    return Base.make ("tagged", { field = field }, variants :: any)
+end
+
+-- One of the names, by its place in the canonical order rather than in the order it was written.
+function Composites.enum (names: { string }): Types.Codec<string>
+    return Base.make ("enum", { names = labelled ("enum", names) })
+end
+
+-- One bit per name, in the same order, and a record of every one of them either way.
+function Composites.bitfield (names: { string }): Types.Codec<{ [string]: boolean }>
+    return Base.make ("bitfield", { names = labelled ("bitfield", names) })
+end
+
+return table.freeze (Composites)

package/codec/Datatypes.luau

@@ -0,0 +1,162 @@
+--!strict
+--!optimize 2
+-- The six Roblox datatypes: what each one declares, and never how it converts.
+
+local Base = require (script.Parent.Base)
+local Legality = require (script.Parent.Legality)
+local Log = require (script.Parent.Parent.kernel.Log)
+local Scalars = require (script.Parent.Scalars)
+local Types = require (script.Parent.Parent.Types)
+
+local Datatypes = {}
+
+-- Private -------------------------------------------------------------
+
+--[[
+    A form is recorded wherever a name carries more than one, because a form is a different wire
+    object rather than a different parameter. The lowering then reads one field and branches,
+    instead of working out which parameters happen to be absent.
+]]
+local function turning (_: any, component: Types.Codec<any>?): Types.Codec<Vector3>
+    if component == nil then return Base.make ("vec3", { form = "components" }) end
+
+    Legality.bare ("vec3", "component", component)
+    return Base.make ("vec3", { form = "components" }, { component = component })
+end
+
+local function unit (precision: number): Types.Codec<Vector3>
+    Scalars.precise ("vec3.unit", precision)
+    return Base.make ("vec3", { form = "unit", step = precision })
+end
+
+local function bounded (max: number, step: number): Types.Codec<Vector3>
+    if not (Legality.finite (max) and max > 0) then
+        Log.refuse (`vec3.bounded takes a radius above zero, not {max}`)
+    end
+    if not (Legality.finite (step) and step > 0) then
+        Log.refuse (`vec3.bounded takes a step above zero, not {step}`)
+    end
+
+    return Base.make ("vec3", { form = "bounded", max = max, step = step })
+end
+
+local function still (): Types.Codec<CFrame> return Base.make ("rotation", { form = "none" }) end
+
+--[[
+    The axis is recorded as it was given rather than normalised. Any positive multiple of it is the
+    same turn and would lower the same way, so canonicalising it would change what a caller wrote to
+    make two descriptors agree that no two builds can disagree about.
+]]
+local function about (axis: Vector3, precision: number): Types.Codec<CFrame>
+    if typeof (axis) ~= "Vector3" then
+        Log.refuse (`rotation.axis takes a Vector3 to turn about, not a {typeof (axis)}`)
+    end
+    if not (Legality.finite (axis.Magnitude) and axis.Magnitude > 0) then
+        Log.refuse (`rotation.axis takes an axis with a direction, not {tostring (axis)}`)
+    end
+    Scalars.precise ("rotation.axis", precision)
+
+    return Base.make ("rotation", { form = "axis", axis = axis, step = precision })
+end
+
+local function facing (precision: number): Types.Codec<CFrame>
+    Scalars.precise ("rotation.direction", precision)
+    return Base.make ("rotation", { form = "direction", step = precision })
+end
+
+local function quat (precision: number): Types.Codec<CFrame>
+    Scalars.precise ("rotation.quat", precision)
+    return Base.make ("rotation", { form = "quat", step = precision })
+end
+
+local function packed (): Types.Codec<Color3> return Base.make ("color3", { form = "rgb565" }) end
+
+--[[
+    Read by their components rather than by identity, because a colour is a userdata and two of them
+    equal by value are two keys in a table. A repeat costs the same here as a repeated symbol in
+    an alphabet does, which is an index nothing can ever be encoded as.
+]]
+local function palette (colors: { Color3 }): Types.Codec<Color3>
+    if type (colors) ~= "table" then
+        Log.refuse (`color3.palette takes a list of colours, not a {typeof (colors)}`)
+    end
+    if #colors == 0 then Log.refuse ("color3.palette takes at least one colour") end
+
+    local seen = {}
+    for index = 1, #colors do
+        local color = colors[index]
+        if typeof (color) ~= "Color3" then
+            Log.refuse (`color3.palette takes a colour at {index}, not a {typeof (color)}`)
+        end
+
+        local at = `{color.R} {color.G} {color.B}`
+        if seen[at] ~= nil then
+            Log.refuse (`color3.palette takes each colour once, and the one at {index} is twice`)
+        end
+        seen[at] = true
+    end
+
+    return Base.make ("color3", { form = "palette", colors = colors })
+end
+
+-- Three floats, which is what a colour is where nothing narrower was asked for.
+local function coloured (_: any): Types.Codec<Color3>
+    return Base.make ("color3", { form = "components" })
+end
+
+-- Public --------------------------------------------------------------
+
+-- Two components in the codec given, or two floats where none was.
+function Datatypes.vec2 (component: Types.Codec<any>?): Types.Codec<Vector2>
+    if component == nil then return Base.make ("vec2") end
+
+    Legality.bare ("vec2", "component", component)
+    return Base.make ("vec2", nil, { component = component })
+end
+
+Datatypes.vec3 = table.freeze (setmetatable ({ unit = unit, bounded = bounded }, {
+    __call = turning,
+}))
+
+--[[
+    A position codec and a rotation codec, and neither is held to a kind. `as` is how a caller
+    reaches a datatype this vocabulary does not name, so a position built out of a struct is a
+    position, and what it lifts to is the caller's promise rather than something a kind can say.
+]]
+function Datatypes.cframe (
+    position: Types.Codec<any>,
+    rotation: Types.Codec<any>
+): Types.Codec<CFrame>
+    Legality.bare ("cframe", "position", position)
+    Legality.bare ("cframe", "rotation", rotation)
+
+    return Base.make ("cframe", nil, { position = position, rotation = rotation })
+end
+
+-- Four ways to spell a turn and no default among them, so the name itself answers nothing.
+Datatypes.rotation = table.freeze ({
+    none = still,
+    axis = about,
+    direction = facing,
+    quat = quat,
+})
+
+Datatypes.color3 = table.freeze (setmetatable ({ rgb565 = packed, palette = palette }, {
+    __call = coloured,
+}))
+
+--[[
+    Always optional, since a receiver that cannot see the instance is handed nothing and that is a
+    normal outcome rather than a drop. The class is a name to check against on the way in and
+    nothing here can tell a real one from a typo, so it is only held.
+]]
+function Datatypes.inst (class: string?): Types.Codec<Instance?>
+    if class == nil then return Base.make ("inst") end
+    if type (class) ~= "string" or class == "" then
+        Log.refuse (`inst takes a class name, not {tostring (class)}`)
+    end
+
+    return Base.make ("inst", { class = class })
+end
+
+return table.freeze (Datatypes)

package/codec/Legality.luau

@@ -0,0 +1,61 @@
+--!strict
+--!optimize 2
+-- What a constructor will take: the tests every one of them makes of a parameter or a child.
+
+local Base = require (script.Parent.Base)
+local Log = require (script.Parent.Parent.kernel.Log)
+local Types = require (script.Parent.Parent.Types)
+
+local Legality = {}
+
+-- Public --------------------------------------------------------------
+
+--[[
+    The annotation is erased at run time, so a numeric string would be coerced downstream and
+    recorded as a parameter. A NaN answers false to both comparisons, which is the whole test.
+]]
+function Legality.finite (value: number): boolean
+    return type (value) == "number" and value > -math.huge and value < math.huge
+end
+
+-- Whole, and on the line with it: an infinity and a NaN both leave a NaN behind in the modulo.
+function Legality.whole (value: number): boolean
+    if type (value) ~= "number" then return false end
+    return value % 1 == 0
+end
+
+--[[
+    A count range, which every counted kind takes and none of them takes differently. Zero is a
+    legal floor and a legal ceiling, so an empty string and an empty list are both declarable, and
+    the bounds may meet, which is a count of no bits.
+]]
+function Legality.counts (kind: string, min: number, max: number)
+    if not (Legality.whole (min) and Legality.whole (max)) then
+        Log.refuse (`{kind} takes whole bounds, not {min} to {max}`)
+    end
+    if min < 0 then Log.refuse (`{kind} takes bounds from zero up, not {min}`) end
+    if min > max then Log.refuse (`{kind} takes its bounds in order, not {min} to {max}`) end
+end
+
+--[[
+    A child, refused where it is anything else. Every composite takes one and the mistake a caller
+    makes is handing over the value they meant to describe, so the refusal names what arrived as
+    well as where it was wanted.
+]]
+function Legality.codec (kind: string, at: string, of: Types.Codec<any>)
+    if not Base.made (of) then Log.refuse (`{kind} takes a codec for {at}, not a {typeof (of)}`) end
+end
+
+--[[
+    A child, and the one place an optional may not be. Two slots cannot tell an absent value from an
+    absent slot: a list element and a map entry are read back by their presence, so an optional
+    there decodes as a hole, and an optional inside an optional is one absence written twice.
+]]
+function Legality.bare (kind: string, at: string, of: Types.Codec<any>)
+    Legality.codec (kind, at, of)
+    if Base.cell (of).kind == "optional" then
+        Log.refuse (`{kind} takes no optional for {at}, since an absent slot is already absent`)
+    end
+end
+
+return table.freeze (Legality)

package/codec/Scalars.luau

@@ -0,0 +1,72 @@
+--!strict
+--!optimize 2
+-- The eight scalar constructors, and the parameters each of them will take.
+
+local Base = require (script.Parent.Base)
+local Legality = require (script.Parent.Legality)
+local Log = require (script.Parent.Parent.kernel.Log)
+local Types = require (script.Parent.Parent.Types)
+
+local Scalars = {}
+
+-- Constants -----------------------------------------------------------
+
+-- A whole turn, in the degrees every angle is stated in, and the one home of that number.
+Scalars.TURN = 360
+
+-- Public --------------------------------------------------------------
+
+-- An angular precision, in the degrees every one of them is spelled in.
+function Scalars.precise (kind: string, degrees: number)
+    if not (Legality.finite (degrees) and degrees > 0 and degrees <= Scalars.TURN) then
+        Log.refuse (`{kind} takes a precision from zero to {Scalars.TURN}, not {degrees}`)
+    end
+end
+
+function Scalars.bool (): Types.Codec<boolean> return Base.make ("bool") end
+
+--[[
+    Bounds are inclusive and may meet, which is a field of no bits carrying one value. How wide
+    the range may be is left alone here for the same reason a count is, since what a frame holds is
+    a fact about the wire, and a refusal at start carries a declaration site this cannot name.
+]]
+function Scalars.int (min: number, max: number): Types.Codec<number>
+    if not (Legality.whole (min) and Legality.whole (max)) then
+        Log.refuse (`int takes whole bounds, not {min} to {max}`)
+    end
+    if min > max then Log.refuse (`int takes its bounds in order, not {min} to {max}`) end
+
+    return Base.make ("int", { min = min, max = max })
+end
+
+--[[
+    A step need not divide the range. The grid keeps the points it has and the nearest one to the
+    top is the last, so a range holding two and a half steps is three points and not four.
+]]
+function Scalars.quant (min: number, max: number, step: number): Types.Codec<number>
+    if not (Legality.finite (min) and Legality.finite (max)) then
+        Log.refuse (`quant takes bounds on the line, not {min} to {max}`)
+    end
+    if min > max then Log.refuse (`quant takes its bounds in order, not {min} to {max}`) end
+    if not (Legality.finite (step) and step > 0) then
+        Log.refuse (`quant takes a step above zero, not {step}`)
+    end
+
+    return Base.make ("quant", { min = min, max = max, step = step })
+end
+
+-- One parameter, since the rest of an angle is what an angle is: zero to a turn, and cyclic.
+function Scalars.angle (precision: number): Types.Codec<number>
+    Scalars.precise ("angle", precision)
+    return Base.make ("angle", { step = precision })
+end
+
+function Scalars.f32 (): Types.Codec<number> return Base.make ("f32") end
+
+function Scalars.f64 (): Types.Codec<number> return Base.make ("f64") end
+
+function Scalars.vlq (): Types.Codec<number> return Base.make ("vlq") end
+
+function Scalars.vli (): Types.Codec<number> return Base.make ("vli") end
+
+return table.freeze (Scalars)