@axpecter/lync 1.3.0

package/src/index.d.ts

@@ -0,0 +1,279 @@
+// Type declarations for Lync networking library.
+
+// -- Utility types -----------------------------------------------------
+
+// Expands mapped types in hover tooltips.
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+// -- Codec -------------------------------------------------------------
+
+// Opaque codec handle. Carries the serialized type at the type level.
+export interface Codec<T> {
+    /** @hidden @deprecated Do not use. Only for type metadata. */
+    readonly _nominal_Codec: T;
+}
+
+// Extracts the value type from a codec.
+export type InferCodec<C> = C extends Codec<infer T> ? T : never;
+
+// Maps a record of codecs to a record of their value types.
+type InferSchema<S extends Record<string, Codec<unknown>>> = Prettify<{
+    [K in keyof S]: InferCodec<S[K]>;
+}>;
+
+// Maps a tuple of codecs to a tuple of their value types.
+type InferTuple<T extends readonly Codec<unknown>[]> = {
+    [K in keyof T]: InferCodec<T[K]>;
+};
+
+// Infers the discriminated union from a tagged variant map.
+type InferTagged<
+    Tag extends string,
+    V extends Record<string, Codec<unknown>>,
+> = {
+    [K in keyof V & string]: Prettify<InferCodec<V[K]> & { [T in Tag]: K }>;
+}[keyof V & string];
+
+// -- Connection --------------------------------------------------------
+
+export interface Connection {
+    readonly connected: boolean;
+    disconnect(this: Connection): void;
+}
+
+// -- Config ------------------------------------------------------------
+
+export interface RateLimitConfig {
+    maxPerSecond: number;
+    burstAllowance?: number;
+}
+
+export interface BoolFieldSpec {
+    type: "bool";
+}
+
+export interface UintFieldSpec {
+    type: "uint";
+    width: number;
+}
+
+export interface IntFieldSpec {
+    type: "int";
+    width: number;
+}
+
+export type FieldSpec = BoolFieldSpec | UintFieldSpec | IntFieldSpec;
+
+type InferFieldSpec<F extends FieldSpec> = F extends BoolFieldSpec
+    ? boolean
+    : number;
+
+type InferBitfield<S extends Record<string, FieldSpec>> = Prettify<{
+    [K in keyof S]: InferFieldSpec<S[K]>;
+}>;
+
+// -- Packet ------------------------------------------------------------
+
+export interface PacketConfig<T> {
+    value: Codec<T>;
+    unreliable?: boolean;
+    rateLimit?: RateLimitConfig;
+    validate?: (data: T, player: Player) => LuaTuple<[boolean, string?]>;
+    maxPayloadBytes?: number;
+}
+
+// Server methods throw on client and vice versa.
+export interface Packet<T> {
+    sendTo(this: Packet<T>, data: T, player: Player): void;
+    sendToAll(this: Packet<T>, data: T): void;
+    sendToAllExcept(this: Packet<T>, data: T, except: Player): void;
+    sendToList(this: Packet<T>, data: T, players: Player[]): void;
+    sendToGroup(this: Packet<T>, data: T, groupName: string): void;
+    send(this: Packet<T>, data: T): void;
+    listen(this: Packet<T>, callback: (data: T, sender: Player | undefined) => void): Connection;
+    once(this: Packet<T>, callback: (data: T, sender: Player | undefined) => void): Connection;
+    wait(this: Packet<T>): LuaTuple<[T, Player | undefined]>;
+    disconnectAll(this: Packet<T>): void;
+}
+
+// -- Query -------------------------------------------------------------
+
+export interface QueryConfig<Req, Resp> {
+    request: Codec<Req>;
+    response: Codec<Resp>;
+    timeout?: number;
+    rateLimit?: RateLimitConfig;
+    validate?: (data: Req, player: Player) => LuaTuple<[boolean, string?]>;
+}
+
+export interface Query<Req, Resp> {
+    listen(
+        this: Query<Req, Resp>,
+        callback: (request: Req, player: Player) => Resp | undefined,
+    ): Connection;
+    invoke(this: Query<Req, Resp>, request: Req, player?: Player): Resp | undefined;
+    invokeAll(this: Query<Req, Resp>, request: Req): Map<Player, Resp | undefined>;
+    invokeList(
+        this: Query<Req, Resp>,
+        request: Req,
+        players: Player[],
+    ): Map<Player, Resp | undefined>;
+    invokeGroup(
+        this: Query<Req, Resp>,
+        request: Req,
+        groupName: string,
+    ): Map<Player, Resp | undefined>;
+}
+
+// -- Namespace ---------------------------------------------------------
+
+export interface NamespaceConfig {
+    packets?: Record<string, PacketConfig<unknown>>;
+    queries?: Record<string, QueryConfig<unknown, unknown>>;
+}
+
+type InferPackets<P extends Record<string, PacketConfig<unknown>>> = {
+    [K in keyof P]: P[K] extends PacketConfig<infer T> ? Packet<T> : never;
+};
+
+type InferQueries<Q extends Record<string, QueryConfig<unknown, unknown>>> = {
+    [K in keyof Q]: Q[K] extends QueryConfig<infer Req, infer Resp>
+        ? Query<Req, Resp>
+        : never;
+};
+
+export interface Namespace {
+    listenAll(
+        this: Namespace,
+        callback: (name: string, data: unknown, sender: Player | undefined) => void,
+    ): Connection;
+    onSend(
+        this: Namespace,
+        handler: (data: unknown, name: string, player: Player | undefined) => unknown | undefined,
+    ): () => void;
+    onReceive(
+        this: Namespace,
+        handler: (data: unknown, name: string, player: Player | undefined) => unknown | undefined,
+    ): () => void;
+    disconnectAll(this: Namespace): void;
+    destroy(this: Namespace): void;
+    packetNames(this: Namespace): string[];
+    queryNames(this: Namespace): string[];
+}
+
+// -- Lync --------------------------------------------------------------
+
+declare namespace Lync {
+    // Lifecycle
+    export const VERSION: string;
+    export const version: string;
+    export function start(): void;
+
+    // Definition
+    export function definePacket<T>(name: string, config: PacketConfig<T>): Packet<T>;
+    export function defineQuery<Req, Resp>(
+        name: string,
+        config: QueryConfig<Req, Resp>,
+    ): Query<Req, Resp>;
+    export function defineNamespace<
+        P extends Record<string, PacketConfig<unknown>> = {},
+        Q extends Record<string, QueryConfig<unknown, unknown>> = {},
+    >(
+        name: string,
+        config: { packets?: P; queries?: Q },
+    ): Namespace & InferPackets<P> & InferQueries<Q>;
+
+    // Primitives
+    export const u8: Codec<number>;
+    export const u16: Codec<number>;
+    export const u32: Codec<number>;
+    export const i8: Codec<number>;
+    export const i16: Codec<number>;
+    export const i32: Codec<number>;
+    export const f32: Codec<number>;
+    export const f64: Codec<number>;
+    export const bool: Codec<boolean>;
+    export const f16: Codec<number>;
+
+    // Datatypes
+    const string: Codec<string>;
+    export { string };
+    export const vec2: Codec<Vector2>;
+    export const vec3: Codec<Vector3>;
+    export const cframe: Codec<CFrame>;
+    export const color3: Codec<Color3>;
+    export const inst: Codec<Instance>;
+    export const buff: Codec<buffer>;
+    export const udim: Codec<UDim>;
+    export const udim2: Codec<UDim2>;
+    export const numberRange: Codec<NumberRange>;
+    export const rect: Codec<Rect>;
+    export const vec2int16: Codec<Vector2int16>;
+    export const vec3int16: Codec<Vector3int16>;
+    export const region3: Codec<Region3>;
+    export const region3int16: Codec<Region3int16>;
+    export const ray: Codec<Ray>;
+    export const numberSequence: Codec<NumberSequence>;
+    export const colorSequence: Codec<ColorSequence>;
+
+    // Composites
+    export function struct<S extends Record<string, Codec<unknown>>>(schema: S): Codec<InferSchema<S>>;
+    export function deltaStruct<S extends Record<string, Codec<unknown>>>(schema: S): Codec<InferSchema<S>>;
+    export function array<T>(element: Codec<T>, maxCount?: number): Codec<T[]>;
+    export function deltaArray<T>(element: Codec<T>, maxCount?: number): Codec<T[]>;
+    export function map<K extends defined, V>(key: Codec<K>, value: Codec<V>, maxCount?: number): Codec<Map<K, V>>;
+    export function deltaMap<K extends defined, V>(key: Codec<K>, value: Codec<V>, maxCount?: number): Codec<Map<K, V>>;
+    export function optional<T>(inner: Codec<T>): Codec<T | undefined>;
+
+    // Meta
+    function _enum<T extends string>(...values: T[]): Codec<T>;
+    export { _enum as enum };
+    export function quantizedFloat(min: number, max: number, precision: number): Codec<number>;
+    export function quantizedVec3(min: number, max: number, precision: number): Codec<Vector3>;
+    export function bitfield<S extends Record<string, FieldSpec>>(schema: S): Codec<InferBitfield<S>>;
+    export function tagged<Tag extends string, V extends Record<string, Codec<unknown>>>(
+        tagField: Tag,
+        variants: V,
+    ): Codec<InferTagged<Tag, V>>;
+    export function tuple<T extends Codec<unknown>[]>(...codecs: T): Codec<InferTuple<T>>;
+    export function custom<T>(
+        size: number,
+        write: (b: buffer, offset: number, value: T) => void,
+        read: (b: buffer, offset: number) => T,
+    ): Codec<T>;
+    export function boundedString(maxLength: number): Codec<string>;
+    export const nothing: Codec<undefined>;
+    export const unknown: Codec<unknown>;
+    export const auto: Codec<unknown>;
+
+    // Hooks
+    export function onDrop(
+        callback: (player: Player, reason: string, packetName: string, data: unknown) => void,
+    ): () => void;
+    export function onSend(
+        handler: (data: unknown, name: string, player: Player | undefined) => unknown | undefined,
+    ): () => void;
+    export function onReceive(
+        handler: (data: unknown, name: string, player: Player | undefined) => unknown | undefined,
+    ): () => void;
+
+    // Groups
+    export function createGroup(name: string): void;
+    export function destroyGroup(name: string): void;
+    export function addToGroup(name: string, player: Player): boolean;
+    export function removeFromGroup(name: string, player: Player): boolean;
+    export function hasInGroup(name: string, player: Player): boolean;
+    export function getGroupSet(name: string): ReadonlyMap<Player, true>;
+    export function groupCount(name: string): number;
+    export function forEachInGroup(name: string, fn: (player: Player) => void): void;
+
+    // Configuration
+    export function setChannelMaxSize(bytes: number): void;
+    export function setValidationDepth(depth: number): void;
+    export function setPoolSize(count: number): void;
+
+    // Introspection
+    export function queryPendingCount(): number;
+}
+
+export default Lync;

package/src/init.luau

@@ -0,0 +1,161 @@
+--!strict
+--!optimize 2
+-- Public API.
+
+local RunService = game:GetService ("RunService")
+
+-- Codec: primitive
+local BoolCodec = require (script.codec.primitive.Bool)
+local Float16 = require (script.codec.primitive.Float16)
+local Number = require (script.codec.primitive.Number)
+
+-- Codec: datatype
+local Buffer = require (script.codec.datatype.Buffer)
+local CFrameCodec = require (script.codec.datatype.CFrame)
+local Color = require (script.codec.datatype.Color)
+local InstanceCodec = require (script.codec.datatype.Instance)
+local IntVector = require (script.codec.datatype.IntVector)
+local NumberRangeCodec = require (script.codec.datatype.NumberRange)
+local RayCodec = require (script.codec.datatype.Ray)
+local RectCodec = require (script.codec.datatype.Rect)
+local Region = require (script.codec.datatype.Region)
+local Sequence = require (script.codec.datatype.Sequence)
+local String = require (script.codec.datatype.String)
+local UDimCodec = require (script.codec.datatype.UDim)
+local Vector = require (script.codec.datatype.Vector)
+
+-- Codec: composite
+local Array = require (script.codec.composite.Array)
+local Map = require (script.codec.composite.Map)
+local Optional = require (script.codec.composite.Optional)
+local Struct = require (script.codec.composite.Struct)
+local Tagged = require (script.codec.composite.Tagged)
+local Tuple = require (script.codec.composite.Tuple)
+
+-- Codec: meta
+local Auto = require (script.codec.meta.Auto)
+local Bitfield = require (script.codec.meta.Bitfield)
+local Custom = require (script.codec.meta.Custom)
+local EnumCodec = require (script.codec.meta.Enum)
+local Nothing = require (script.codec.meta.Nothing)
+local Quantized = require (script.codec.meta.Quantized)
+local Unknown = require (script.codec.meta.Unknown)
+
+-- Internal
+local Channel = require (script.internal.Channel)
+local Gate = require (script.transport.Gate)
+local Middleware = require (script.internal.Middleware)
+local Pool = require (script.internal.Pool)
+
+-- API
+local Group = require (script.api.Group)
+local Namespace = require (script.api.Namespace)
+local Packet = require (script.api.Packet)
+local Query = require (script.api.Query)
+
+-- Transport
+local Client = require (script.transport.Client)
+local Server = require (script.transport.Server)
+
+-- Public -----------------------------------------------------------------
+
+local function start (): ()
+    if RunService:IsServer () then
+        Server.start ()
+    else
+        Client.start ()
+    end
+end
+
+local Lync = {
+    VERSION = "1.3.0",
+    version = "1.3.0",
+
+    -- Lifecycle
+    start = start,
+
+    -- Definition
+    definePacket = Packet.define,
+    defineQuery = Query.define,
+    defineNamespace = Namespace.define,
+
+    -- Primitives
+    u8 = Number.u8,
+    u16 = Number.u16,
+    u32 = Number.u32,
+    i8 = Number.i8,
+    i16 = Number.i16,
+    i32 = Number.i32,
+    f32 = Number.f32,
+    f64 = Number.f64,
+    bool = BoolCodec.bool,
+    f16 = Float16.f16,
+
+    -- Datatypes
+    string = String.string,
+    boundedString = String.bounded,
+    vec2 = Vector.vec2,
+    vec3 = Vector.vec3,
+    cframe = CFrameCodec.cframe,
+    color3 = Color.color3,
+    inst = InstanceCodec.inst,
+    buff = Buffer.buff,
+    udim = UDimCodec.udim,
+    udim2 = UDimCodec.udim2,
+    numberRange = NumberRangeCodec.numberRange,
+    rect = RectCodec.rect,
+    vec2int16 = IntVector.vec2int16,
+    vec3int16 = IntVector.vec3int16,
+    region3 = Region.region3,
+    region3int16 = Region.region3int16,
+    ray = RayCodec.ray,
+    numberSequence = Sequence.numberSequence,
+    colorSequence = Sequence.colorSequence,
+
+    -- Composites
+    struct = Struct.struct,
+    deltaStruct = Struct.deltaStruct,
+    deltaArray = Array.deltaArray,
+    deltaMap = Map.deltaMap,
+    array = Array.array,
+    map = Map.map,
+    optional = Optional.optional,
+    tuple = Tuple.define,
+    tagged = Tagged.define,
+
+    -- Meta
+    enum = EnumCodec.define,
+    quantizedFloat = Quantized.float,
+    quantizedVec3 = Quantized.vec3,
+    bitfield = Bitfield.define,
+    custom = Custom.define,
+
+    nothing = Nothing.nothing,
+    unknown = Unknown.unknown,
+    auto = Auto.auto,
+
+    -- Hooks
+    onDrop = Gate.onDrop,
+    onSend = Middleware.addSend,
+    onReceive = Middleware.addReceive,
+
+    -- Groups
+    createGroup = Group.create,
+    destroyGroup = Group.destroy,
+    addToGroup = Group.add,
+    removeFromGroup = Group.remove,
+    hasInGroup = Group.has,
+    getGroupSet = Group.getSet,
+    groupCount = Group.count,
+    forEachInGroup = Group.forEach,
+
+    -- Configuration (call before start)
+    setChannelMaxSize = Channel.setMaxSize,
+    setValidationDepth = Gate.setMaxDepth,
+    setPoolSize = Pool.setMaxSize,
+
+    -- Introspection
+    queryPendingCount = Query.pendingCount,
+}
+
+return table.freeze (Lync)

package/src/internal/Baseline.luau

@@ -0,0 +1,41 @@
+--!strict
+--!optimize 2
+-- Read-side baseline cache keyed by source (player or client sentinel).
+
+-- State ------------------------------------------------------------------
+
+local _readKey = false :: any
+local _readCaches = {} :: { [any]: { [number]: any } }
+
+-- Public -----------------------------------------------------------------
+
+local Baseline = {}
+
+Baseline.hasDelta = false
+
+function Baseline.setReadKey (key: any): ()
+    _readKey = key
+end
+
+function Baseline.getCache (deltaId: number): any
+    local map = _readCaches[_readKey]
+    return map and map[deltaId]
+end
+
+function Baseline.setCache (deltaId: number, data: any): ()
+    if not Baseline.hasDelta then
+        Baseline.hasDelta = true
+    end
+    local map = _readCaches[_readKey]
+    if not map then
+        map = {}
+        _readCaches[_readKey] = map
+    end
+    map[deltaId] = data
+end
+
+function Baseline.clearSource (key: any): ()
+    _readCaches[key] = nil
+end
+
+return Baseline