@axpecter/lync 1.3.1 → 1.4.1

package/README.md

@@ -2,6 +2,7 @@
 <p align="center">Buffer networking for Roblox. Delta compression, XOR framing, built-in security.</p>
 <p align="center">
   <a href="https://github.com/Axp3cter/Lync/releases/latest">Releases</a> ·
+  <a href="#example">Example</a> ·
   <a href="#benchmarks">Benchmarks</a> ·
   <a href="#limits--configuration">Limits</a>
 </p>
@@ -12,17 +13,17 @@
 
 ```toml
 [dependencies]
-Lync = "axp3cter/lync@1.3.1"
+Lync = "axp3cter/lync@1.4.1"
 ```
 
 **npm (roblox-ts)**
 
 ```bash
-npm install @rbxts/lync
+npm install @axpecter/lync
 ```
 
 ```typescript
-import Lync from "@rbxts/lync";
+import Lync from "@axpecter/lync";
 ```
 
 Or grab the `.rbxm` from [releases](https://github.com/Axp3cter/Lync/releases/latest) and drop it in `ReplicatedStorage`.
@@ -30,13 +31,139 @@ Or grab the `.rbxm` from [releases](https://github.com/Axp3cter/Lync/releases/la
 > [!IMPORTANT]
 > Define everything before calling `Lync.start()`. Packets, queries, namespaces, all of it.
 
+## Example
+
+**Shared**
+
+```luau
+local Lync = require(game.ReplicatedStorage.Lync)
+
+local Net = {}
+
+Net.State = Lync.definePacket("State", {
+    value = Lync.deltaStruct({
+        position = Lync.vec3,
+        health   = Lync.quantizedFloat(0, 100, 0.5),
+        shield   = Lync.quantizedFloat(0, 100, 0.5),
+        status   = Lync.enum("idle", "moving", "attacking", "dead"),
+        alive    = Lync.bool,
+    }),
+})
+
+Net.Hit = Lync.definePacket("Hit", {
+    value = Lync.struct({
+        targetId = Lync.u16,
+        damage   = Lync.quantizedFloat(0, 200, 0.1),
+        headshot = Lync.bool,
+    }),
+    rateLimit = { maxPerSecond = 30, burstAllowance = 5 },
+    validate = function(data, player)
+        if data.damage > 200 then return false, "damage" end
+        return true
+    end,
+})
+
+Net.Chat = Lync.definePacket("Chat", {
+    value = Lync.struct({ msg = Lync.boundedString(200), channel = Lync.u8 }),
+})
+
+Net.Ping = Lync.defineQuery("Ping", {
+    request  = Lync.nothing,
+    response = Lync.f64,
+    timeout  = 3,
+})
+
+return table.freeze(Net)
+```
+
+**Server**
+
+```luau
+local Lync    = require(game.ReplicatedStorage.Lync)
+local Net     = require(game.ReplicatedStorage.Net)
+local Players = game:GetService("Players")
+
+local alive = Lync.createGroup("alive")
+
+Lync.onSend(function(data, name)
+    print("[out]", name)
+    return data
+end)
+
+Lync.onDrop(function(player, reason, name)
+    warn(player.Name, "dropped", name, reason)
+end)
+
+Lync.start()
+
+Players.PlayerAdded:Connect(function(player)
+    alive:add(player)
+end)
+
+game:GetService("RunService").Heartbeat:Connect(function()
+    Net.State:send({
+        position = Vector3.new(0, 5, 0),
+        health   = 100,
+        shield   = 50,
+        status   = "idle",
+        alive    = true,
+    }, alive)
+end)
+
+Net.Hit:listen(function(data, player)
+    local target = Players:GetPlayerByUserId(data.targetId)
+    if not target then return end
+
+    alive:remove(target)
+    Net.Chat:send({ msg = player.Name .. " eliminated " .. target.Name, channel = 0 }, Lync.all)
+    Net.State:send({
+        position = Vector3.zero,
+        health   = 0,
+        shield   = 0,
+        status   = "dead",
+        alive    = false,
+    }, Lync.except(target))
+end)
+
+Net.Ping:listen(function()
+    return os.clock()
+end)
+```
+
+**Client**
+
+```luau
+local Lync = require(game.ReplicatedStorage.Lync)
+local Net  = require(game.ReplicatedStorage.Net)
+
+Lync.start()
+
+local scope = Lync.scope()
+
+scope:listen(Net.State, function(state)
+    local character = game.Players.LocalPlayer.Character
+    if not character then return end
+    character:PivotTo(CFrame.new(state.position))
+end)
+
+scope:listen(Net.Chat, function(data)
+    print("[chat]", data.msg)
+end)
+
+Net.Hit:send({ targetId = 123, damage = 45.5, headshot = true })
+
+local serverTime = Net.Ping:request(nil)
+if serverTime then
+    print("server clock:", serverTime)
+end
+```
+
 ## Lifecycle
 
 | | What it does |
 |:---------|:------------|
 | `Lync.start()` | Sets up transport. Server creates remotes, client connects. Call once after all definitions. |
-| `Lync.version` | `"1.3.1"` |
-| `Lync.VERSION` | `"1.3.1"` |
+| `Lync.VERSION` | `"1.4.1"` |
 
 ## Packets
 
@@ -50,29 +177,30 @@ Or grab the `.rbxm` from [releases](https://github.com/Axp3cter/Lync/releases/la
 | `validate` | `(data, player) → (bool, string?)` | No | Server-side. Return `false, "reason"` to drop. Runs after NaN scan. |
 | `maxPayloadBytes` | number | No | Server-side. Max bytes a single batch of this packet can consume. Fires `onDrop` with reason `"size"` if exceeded. |
 
-**Server methods:**
+**Server, single `send` with targets:**
 
-| Method | What it does |
-|:-------|:------------|
-| `packet:sendTo(data, player)` | Send to one player. |
-| `packet:sendToAll(data)` | Send to everyone. |
-| `packet:sendToAllExcept(data, except)` | Send to everyone except one. |
-| `packet:sendToList(data, players)` | Send to a list. |
-| `packet:sendToGroup(data, groupName)` | Send to a named group. |
+```luau
+packet:send(data, player)              -- one player
+packet:send(data, Lync.all)            -- everyone
+packet:send(data, Lync.except(player)) -- everyone except one
+packet:send(data, Lync.except(p1, p2)) -- everyone except multiple
+packet:send(data, { p1, p2 })          -- list of players
+packet:send(data, group)               -- group object
+```
 
-**Client methods:**
+**Client:**
 
-| Method | What it does |
-|:-------|:------------|
-| `packet:send(data)` | Send to server. |
+```luau
+packet:send(data)  -- send to server
+```
 
-**Shared methods:**
+**Shared (both contexts):**
 
 | 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
@@ -90,17 +218,17 @@ Or grab the `.rbxm` from [releases](https://github.com/Axp3cter/Lync/releases/la
 | Method | Where | What it does |
 |:-------|:------|:-------------|
 | `query:listen(fn)` | Both | Register a handler. Server gets `fn(request, player) → response`. Client gets `fn(request) → response`. |
-| `query:invoke(request)` | Client | Send request to server, yield until response comes back or timeout. |
-| `query:invoke(request, player)` | Server | Send request to a specific client, yield until response or timeout. |
-| `query:invokeAll(request)` | Server | Send request to all players, yield until all respond or timeout. Returns `{ [Player]: response? }`. |
-| `query:invokeList(request, players)` | Server | Send request to a list of players, yield until all respond or timeout. Returns `{ [Player]: response? }`. |
-| `query:invokeGroup(request, groupName)` | Server | Send request to all players in a named group. Returns `{ [Player]: response? }`. |
+| `query:request(data)` | Client | Send request to server, yield until response or timeout. |
+| `query:requestFrom(player, data)` | Server | Send request to a specific client, yield until response or timeout. |
+| `query:requestAll(data)` | Server | Send request to all players. Returns `{ [Player]: response? }`. |
+| `query:requestList(players, data)` | Server | Send request to a list of players. Returns `{ [Player]: response? }`. |
+| `query:requestGroup(group, data)` | Server | Send request to all players in a group. Returns `{ [Player]: response? }`. |
 
 ## Namespaces
 
 `Lync.defineNamespace(name, config)` returns a Namespace. Takes a `packets` table and/or a `queries` table. All names get auto-prefixed with `"YourNamespace."` so nothing collides.
 
-Access packets and queries by their short name on the returned object: `ns.PacketName`, `ns.QueryName`.
+Access packets and queries by their short name on the returned object: `ns.PacketName`, `ns.QueryName`. Or use the typed sub-tables: `ns.packets.PacketName`, `ns.queries.QueryName`.
 
 | Method | What it does |
 |:-------|:------------|
@@ -111,6 +239,8 @@ Access packets and queries by their short name on the returned object: `ns.Packe
 | `ns:destroy()` | Kills listeners and removes scoped middleware. Full cleanup. |
 | `ns:packetNames()` | Sorted list of packet short names. |
 | `ns:queryNames()` | Sorted list of query short names. |
+| `ns.packets` | Frozen table mapping short name → Packet object. |
+| `ns.queries` | Frozen table mapping short name → Query object. |
 
 ## Connection
 
@@ -118,9 +248,90 @@ 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
+
+Batches connections for lifecycle-aligned cleanup.
+
+```luau
+local scope = Lync.scope()
+
+scope:listen(packetA, fnA)
+scope:listen(packetB, fnB)
+scope:listenAll(namespace, fnC)
+
+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)` | Also accepts RBXScriptConnection. |
+| `scope:destroy()` | Safe to call multiple times. |
+
+## Groups
+
+Named player sets. Members get removed automatically on `PlayerRemoving`. `Lync.createGroup(name)` returns a Group object.
+
+```luau
+local vips = Lync.createGroup("vips")
+
+vips:add(player)
+vips:remove(player)
+vips:has(player)
+
+packet:send(data, vips)
+```
+
+| Method | Returns | What it does |
+|:-------|:--------|:-------------|
+| `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` | 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
+
+Global intercept on all packets. Handlers run in the order you registered them. Return `Lync.DROP` from a handler to drop the packet. Return the data to pass it through.
+
+```luau
+Lync.onSend(function(data, name, player)
+    if shouldDrop(data) then
+        return Lync.DROP
+    end
+    data.timestamp = os.clock()
+    return data
+end)
+```
+
+| Function | What it does |
+|:---------|:------------|
+| `Lync.onSend(fn(data, name, player) → data \| Lync.DROP)` | Runs before a packet goes out. Returns a remover function. |
+| `Lync.onReceive(fn(data, name, player) → data \| Lync.DROP)` | Runs when a packet comes in. Returns a remover function. |
+| `Lync.onDrop(fn(player, reason, name, data))` | Fires when a packet gets rejected. Returns a remover function. Supports multiple handlers. Reason is `"nan"`, `"rate"`, `"validate"`, `"size"`, or whatever string your validate function returned. |
+| `Lync.DROP` | Frozen sentinel. Return from middleware to drop the packet. |
+
+Packets that fail validation are dropped individually. Other packets in the same frame from the same player are unaffected.
+
+## Target Descriptors
+
+Used as the second argument to `packet:send()` on the server.
+
+| Target | What it does |
+|:-------|:------------|
+| `player` | Send to one player. |
+| `Lync.all` | Send to all connected players. |
+| `Lync.except(player, ...)` | Send to everyone except the specified players. |
+| `{ p1, p2, ... }` | Send to a list of players. |
+| `group` | Send to all members of a Group object. |
+
 ## Types
 
 ### Primitives
@@ -138,7 +349,7 @@ Returned by `packet:listen()`, `packet:once()`, `query:listen()`, and `ns:listen
 | `Lync.f64` | 8 | IEEE 754 double |
 | `Lync.bool` | 1 | true/false. Gets packed into bitfields when inside structs. |
 
-### Complex
+### Datatypes
 
 | Type | Bytes | What it is |
 |:-----|------:|:-----------|
@@ -160,6 +371,7 @@ Returned by `packet:listen()`, `packet:once()`, `query:listen()`, and `ns:listen
 | `Lync.ray` | 24 | Origin Vec3 + Direction Vec3 as 6x f32. |
 | `Lync.numberSequence` | varint + N×12 | Varint count then (time f32 + value f32 + envelope f32) per keypoint. |
 | `Lync.colorSequence` | varint + N×7 | Varint count then (time f32 + R u8 + G u8 + B u8) per keypoint. |
+| `Lync.boundedString(maxLength)` | varint + N | Same wire format as `Lync.string` but rejects on read if length exceeds `maxLength`. |
 
 ### Composites
 
@@ -170,7 +382,7 @@ Returned by `packet:listen()`, `packet:once()`, `query:listen()`, and `ns:listen
 | `Lync.map(keyCodec, valueCodec, maxCount?)` | Key-value pairs with varint count. Optional `maxCount` rejects on read if exceeded. |
 | `Lync.optional(codec)` | 1 byte flag, value only if present. |
 | `Lync.tuple(codec, codec, ...)` | Ordered positional values, no keys. |
-| `Lync.boundedString(maxLength)` | Same wire format as `Lync.string` but rejects on read if length exceeds `maxLength`. |
+| `Lync.tagged(tagField, { name = codec })` | Discriminated union with a u8 variant tag. Puts `tagField` into the decoded table so you know which variant it is. |
 
 ### Delta
 
@@ -182,7 +394,7 @@ Reliable only. Lync will error if you try to use these with `unreliable = true`.
 | `Lync.deltaArray(codec, maxCount?)` | Same idea but for arrays. Dirty elements get sent with varint indices. Optional `maxCount` rejects on read if exceeded. |
 | `Lync.deltaMap(keyCodec, valueCodec, maxCount?)` | Delta compression for key-value maps. Sends only upserted and removed entries after the first frame. Optional `maxCount` rejects on read if exceeded. |
 
-### Specialized
+### Meta
 
 | Constructor | What it does |
 |:------------|:------------|
@@ -190,41 +402,11 @@ Reliable only. Lync will error if you try to use these with `unreliable = true`.
 | `Lync.quantizedFloat(min, max, precision)` | Fixed-point compression. Picks u8/u16/u32 based on your range and precision. |
 | `Lync.quantizedVec3(min, max, precision)` | Same thing but for all 3 components. |
 | `Lync.bitfield({ key = spec })` | Sub-byte packing, 1 to 32 bits total. Spec is `{ type = "bool" }` or `{ type = "uint", width = N }` or `{ type = "int", width = N }`. |
-| `Lync.tagged(tagField, { name = codec })` | Discriminated union with a u8 variant tag. Puts `tagField` into the decoded table so you know which variant it is. |
 | `Lync.custom(size, write, read)` | User-defined fixed-size codec. `write` is `(b, offset, value) → ()`, `read` is `(b, offset) → value`. Plugs into struct/array/delta specialization automatically. |
 | `Lync.nothing` | Zero bytes. Reads nil. Good for fire-and-forget signals. |
 | `Lync.unknown` | Skips serialization entirely, goes through Roblox's sidecar. Requires refs array on read (same as `Lync.inst`). Use when you dont have a codec for the value. |
 | `Lync.auto` | Self-describing. Writes a u8 type tag then the value. Handles nil, bool, all number types, string, vec2, vec3, color3, cframe, buffer, udim, udim2, numberRange, rect, vec2int16, vec3int16, region3, region3int16, ray, numberSequence, colorSequence. |
 
-## Groups
-
-Named player sets. Members get removed automatically on `PlayerRemoving`.
-
-| Function | Returns | What it does |
-|:---------|:--------|:-------------|
-| `Lync.createGroup(name)` | | Makes a new group. Errors if it already exists. |
-| `Lync.destroyGroup(name)` | | Removes the group and all memberships. |
-| `Lync.addToGroup(name, player)` | `boolean` | `true` if added, `false` if already in. |
-| `Lync.removeFromGroup(name, player)` | `boolean` | `true` if removed, `false` if wasnt in there. |
-| `Lync.hasInGroup(name, player)` | `boolean` | |
-| `Lync.groupCount(name)` | `number` | |
-| `Lync.getGroupSet(name)` | `{ [Player]: true }` | |
-| `Lync.forEachInGroup(name, fn)` | | Calls `fn(player)` for each member. |
-
-Send to a group with `packet:sendToGroup(data, groupName)`.
-
-## Middleware
-
-Global intercept on all packets. Handlers run in the order you registered them. Return `nil` from a handler to drop the packet.
-
-| Function | What it does |
-|:---------|:------------|
-| `Lync.onSend(fn(data, name, player) → data?)` | Runs before a packet goes out. Returns a remover function. |
-| `Lync.onReceive(fn(data, name, player) → data?)` | Runs when a packet comes in. Returns a remover function. |
-| `Lync.onDrop(fn(player, reason, name, data))` | Fires when a packet gets rejected. Returns a remover function. Supports multiple handlers. Reason is `"nan"`, `"rate"`, `"validate"`, `"size"`, or whatever string your validate function returned. |
-
-Packets that fail validation are dropped individually. Other packets in the same frame from the same player are unaffected.
-
 ## Benchmarks
 
 ### Lync Tests
@@ -233,10 +415,10 @@ Packets that fail validation are dropped individually. Other packets in the same
 
 | 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
 
@@ -255,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 |
@@ -265,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 |
@@ -273,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.3.1",
+    "version": "1.4.1",
     "description": "Buffer networking for Roblox. Delta compression, XOR framing, built-in security.",
     "main": "src/init.luau",
     "types": "src/index.d.ts",

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,43 +31,16 @@ end
 
 Players.PlayerRemoving:Connect (onPlayerRemoving)
 
-local function getSetOrError (name: string): { [Player]: true }
+local GroupImpl = {}
+GroupImpl.__index = GroupImpl
+
+function GroupImpl.add (self: any, player: Player): boolean
+    local name = self._name
     local set = _groups[name]
     if not set then
-        error (`[Lync] Group does not exist: \"{name}\"`)
-    end
-    return set
-end
-
--- Public -----------------------------------------------------------------
-
-local Group = {}
-
-function Group.create (name: string): ()
-    if _groups[name] then
-        error (`[Lync] Group already exists: \"{name}\"`)
-    end
-    _groups[name] = {}
-    _counts[name] = 0
-end
-
-function Group.destroy (name: string): ()
-    local set = getSetOrError (name)
-
-    for player in set do
-        local memberships = _playerGroups[player]
-        if memberships then
-            memberships[name] = nil
-        end
+        error (`[Lync] Group has been destroyed: "{name}"`)
     end
 
-    _groups[name] = nil
-    _counts[name] = nil
-end
-
-function Group.add (name: string, player: Player): boolean
-    local set = getSetOrError (name)
-
     if set[player] then
         return false
     end
@@ -85,8 +58,12 @@ function Group.add (name: string, player: Player): boolean
     return true
 end
 
-function Group.remove (name: string, player: Player): boolean
-    local set = getSetOrError (name)
+function GroupImpl.remove (self: any, player: Player): boolean
+    local name = self._name
+    local set = _groups[name]
+    if not set then
+        error (`[Lync] Group has been destroyed: "{name}"`)
+    end
 
     if not set[player] then
         return false
@@ -103,24 +80,78 @@ function Group.remove (name: string, player: Player): boolean
     return true
 end
 
-function Group.has (name: string, player: Player): boolean
-    local set = getSetOrError (name)
+function GroupImpl.has (self: any, player: Player): boolean
+    local name = self._name
+    local set = _groups[name]
+    if not set then
+        error (`[Lync] Group has been destroyed: "{name}"`)
+    end
     return set[player] == true
 end
 
-function Group.count (name: string): number
-    getSetOrError (name)
+function GroupImpl.count (self: any): number
+    local name = self._name
+    if not _groups[name] then
+        error (`[Lync] Group has been destroyed: "{name}"`)
+    end
     return _counts[name]
 end
 
-function Group.getSet (name: string): { [Player]: true }
-    return getSetOrError (name)
+function GroupImpl.forEach (self: any, fn: (player: Player) -> ()): ()
+    local name = self._name
+    local set = _groups[name]
+    if not set then
+        error (`[Lync] Group has been destroyed: "{name}"`)
+    end
+    for player in set do
+        fn (player)
+    end
+end
+
+function GroupImpl.getSet (self: any): { [Player]: true }
+    local name = self._name
+    local set = _groups[name]
+    if not set then
+        error (`[Lync] Group has been destroyed: "{name}"`)
+    end
+    return set
 end
 
-function Group.forEach (name: string, fn: (player: Player) -> ()): ()
-    for player in getSetOrError (name) do
-        fn (player)
+function GroupImpl.destroy (self: any): ()
+    local name = self._name
+    local set = _groups[name]
+    if not set then
+        error (`[Lync] Group has been destroyed: "{name}"`)
+    end
+
+    for player in set do
+        local memberships = _playerGroups[player]
+        if memberships then
+            memberships[name] = nil
+        end
     end
+
+    _groups[name] = nil
+    _counts[name] = nil
+end
+
+table.freeze (GroupImpl)
+
+-- Public -------------------------------------------------------------
+
+local Group = {}
+
+function Group.create (name: string): any
+    if _groups[name] then
+        error (`[Lync] Group already exists: "{name}"`)
+    end
+    _groups[name] = {}
+    _counts[name] = 0
+
+    return setmetatable ({
+        _tag = "group",
+        _name = name,
+    }, GroupImpl)
 end
 
 return table.freeze (Group)