@data-vegle/serial 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 datax-e
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# @rbxts/serial
+
+Serialize roblox-ts types into buffers.
+
+> **Status:** scaffolding only. The toolchain is set up and verified; the serializer
+> itself is not written yet.
+
+## Toolchain
+
+| Piece                                                                      | Why it's here                                                                  |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| [roblox-ts](https://roblox-ts.com) 3.0                                     | TypeScript → Luau compiler                                                     |
+| [Flamework](https://flamework.fireboltofdeath.dev) 1.3                     | its transformer exposes compile-time type metadata (user macros)               |
+| [Rojo](https://rojo.space) 7                                               | syncs the compiled output into Studio                                          |
+| [Prettier](https://prettier.io)                                            | formatting, enforced in CI                                                     |
+
+Flamework is the reason this project isn't a plain roblox-ts package. Its
+transformer can hand you a type's identity, a printed form of the type, and a
+generated runtime guard — all derived from a TypeScript type at build time. That
+is what the serializer templates will be generated from, instead of asking
+callers to hand-write a schema next to every interface.
+
+## Setup
+
+```sh
+npm install
+npm run build
+```
+
+Studio-side tooling is pinned in `rokit.toml`:
+
+```sh
+rokit install   # installs Rojo
+```
+
+## Scripts
+
+| Script                | What it does                                                            |
+| --------------------- | ----------------------------------------------------------------------- |
+| `npm run build`       | compile `src/` → `out/` as a package                                    |
+| `npm run watch`       | same, in watch mode                                                     |
+| `npm run build:place` | compile as a game instead, emitting the `include/` runtime              |
+| `npm run place`       | build the place and pack it into `serial-test.rbxl` for Studio          |
+| `npm run clean`       | remove `out/` and `include/`                                            |
+| `npm run format`      | run Prettier over `src/`                                                |
+
+`build` and `build:place` write to the same `out/` directory, so `build:place`
+cleans first. Run `npm run build` again before publishing.
+
+## Layout
+
+```
+src/                  library source, compiled to out/
+default.project.json  Rojo project for the package itself
+test.project.json     Rojo place used to try the library in Studio
+flamework.build       Flamework's identifier table — commit it, don't edit it
+```
+
+`flamework.build` holds the stable ids the transformer hands out. It is tracked
+in git and shipped in the published package on purpose; deleting it makes
+previously generated ids drift.
+
+## Writing a type macro
+
+Flamework user macros need two things: the `plugins` entry in `tsconfig.json`
+(already there), and a `@metadata macro` JSDoc tag on the function. Without the
+tag the transformer silently skips the call and the parameter arrives as
+`undefined`.
+
+`src/index.ts` has the minimal working example:
+
+```ts
+/** @metadata macro */
+export function typeIdOf<T>(id?: Modding.Generic<T, "id">): string {
+	assert(id !== undefined, "typeIdOf<T>() was called without the Flamework transformer");
+	return id;
+}
+```
+
+Callers just write `typeIdOf<PlayerState>()` and the transformer rewrites it to
+`typeIdOf("@rbxts/serial:src/index@PlayerState")`. Swapping `"id"` for `"text"`
+or `"guard"` in `Modding.Generic` gives the printed type or a runtime type guard
+instead — those are the hooks the buffer serializer will be built from.
+
+## License
+
+MIT

package/flamework.build

@@ -0,0 +1,11 @@
+{
+	"version": 1,
+	"flameworkVersion": "1.3.2",
+	"identifiers": {
+		"@data-vegle/serial:out/lib/BufferReader@BufferReader": "@data-vegle/serial:lib/BufferReader@BufferReader",
+		"@data-vegle/serial:out/lib/BufferWriter@BufferWriter": "@data-vegle/serial:lib/BufferWriter@BufferWriter",
+		"@data-vegle/serial:out/lib/Serializer@Serializer": "@data-vegle/serial:lib/Serializer@Serializer"
+	},
+	"metadata": {},
+	"identifierPrefix": "@data-vegle/serial"
+}

package/out/index.d.ts

@@ -0,0 +1,3 @@
+export { Serializer } from "./lib/Serializer";
+export type { SerializedData } from "./lib/Serializer";
+export type { SerializerMetadata } from "./lib/SerializerMetadata";

package/out/init.luau

@@ -0,0 +1,5 @@
+
+local a=_G[script]
+local b={}
+b.Serializer=a.import(script,script,"lib","Serializer").Serializer
+return b

package/out/lib/BufferReader.d.ts

@@ -0,0 +1,19 @@
+export declare class BufferReader {
+    private readonly data;
+    private readonly blobs;
+    private cursor;
+    constructor(data: buffer, blobs: ReadonlyArray<defined>);
+    readBool(): boolean;
+    readU8(): number;
+    readU16(): number;
+    readU32(): number;
+    readI8(): number;
+    readI16(): number;
+    readI32(): number;
+    readF32(): number;
+    readF64(): number;
+    readVarUint(): number;
+    readString(): string;
+    readBuffer(): buffer;
+    readBlob<T>(): T;
+}

package/out/lib/BufferReader.luau

@@ -0,0 +1,97 @@
+
+local a=128
+local b
+do
+b=setmetatable({},{
+__tostring=function()
+return"BufferReader"
+end,
+})
+b.__index=b
+function b.new(...)
+local c=setmetatable({},b)
+return c:constructor(...)or c
+end
+function b.constructor(c,d,e)
+c.data=d
+c.blobs=e
+c.cursor=0
+end
+function b.readBool(c)
+local d=c:readU8()
+return d==1
+end
+function b.readU8(c)
+local d=buffer.readu8(c.data,c.cursor)
+c.cursor=c.cursor+1
+return d
+end
+function b.readU16(c)
+local d=buffer.readu16(c.data,c.cursor)
+c.cursor=c.cursor+2
+return d
+end
+function b.readU32(c)
+local d=buffer.readu32(c.data,c.cursor)
+c.cursor=c.cursor+4
+return d
+end
+function b.readI8(c)
+local d=buffer.readi8(c.data,c.cursor)
+c.cursor=c.cursor+1
+return d
+end
+function b.readI16(c)
+local d=buffer.readi16(c.data,c.cursor)
+c.cursor=c.cursor+2
+return d
+end
+function b.readI32(c)
+local d=buffer.readi32(c.data,c.cursor)
+c.cursor=c.cursor+4
+return d
+end
+function b.readF32(c)
+local d=buffer.readf32(c.data,c.cursor)
+c.cursor=c.cursor+4
+return d
+end
+function b.readF64(c)
+local d=buffer.readf64(c.data,c.cursor)
+c.cursor=c.cursor+8
+return d
+end
+function b.readVarUint(c)
+local d=0
+local e=1
+local f=c:readU8()
+while f>=a do
+local g=f-a
+d=d+g*e
+e=e*a
+f=c:readU8()
+end
+d=d+f*e
+return d
+end
+function b.readString(c)
+local d=c:readVarUint()
+local e=buffer.readstring(c.data,c.cursor,d)
+c.cursor=c.cursor+d
+return e
+end
+function b.readBuffer(c)
+local d=c:readVarUint()
+local e=buffer.create(d)
+buffer.copy(e,0,c.data,c.cursor,d)
+c.cursor=c.cursor+d
+return e
+end
+function b.readBlob(c)
+local d=c:readVarUint()
+return c.blobs[d+1]
+end
+end
+return{
+BufferReader=b,
+}

package/out/lib/BufferWriter.d.ts

@@ -0,0 +1,22 @@
+export declare class BufferWriter {
+    private data;
+    private capacity;
+    private cursor;
+    private readonly blobs;
+    writeBool(value: boolean): void;
+    writeU8(value: number): void;
+    writeU16(value: number): void;
+    writeU32(value: number): void;
+    writeI8(value: number): void;
+    writeI16(value: number): void;
+    writeI32(value: number): void;
+    writeF32(value: number): void;
+    writeF64(value: number): void;
+    writeVarUint(value: number): void;
+    writeString(value: string): void;
+    writeBuffer(value: buffer): void;
+    writeBlob(value: defined): void;
+    getBuffer(): buffer;
+    getBlobs(): Array<defined>;
+    private reserve;
+}

package/out/lib/BufferWriter.luau

@@ -0,0 +1,122 @@
+
+local a=64
+local b=128
+local c
+do
+c=setmetatable({},{
+__tostring=function()
+return"BufferWriter"
+end,
+})
+c.__index=c
+function c.new(...)
+local d=setmetatable({},c)
+return d:constructor(...)or d
+end
+function c.constructor(d)
+d.data=buffer.create(a)
+d.capacity=a
+d.cursor=0
+d.blobs={}
+end
+function c.writeBool(d,e)
+local f=if e then 1 else 0
+d:writeU8(f)
+end
+function c.writeU8(d,e)
+d:reserve(1)
+buffer.writeu8(d.data,d.cursor,e)
+d.cursor=d.cursor+1
+end
+function c.writeU16(d,e)
+d:reserve(2)
+buffer.writeu16(d.data,d.cursor,e)
+d.cursor=d.cursor+2
+end
+function c.writeU32(d,e)
+d:reserve(4)
+buffer.writeu32(d.data,d.cursor,e)
+d.cursor=d.cursor+4
+end
+function c.writeI8(d,e)
+d:reserve(1)
+buffer.writei8(d.data,d.cursor,e)
+d.cursor=d.cursor+1
+end
+function c.writeI16(d,e)
+d:reserve(2)
+buffer.writei16(d.data,d.cursor,e)
+d.cursor=d.cursor+2
+end
+function c.writeI32(d,e)
+d:reserve(4)
+buffer.writei32(d.data,d.cursor,e)
+d.cursor=d.cursor+4
+end
+function c.writeF32(d,e)
+d:reserve(4)
+buffer.writef32(d.data,d.cursor,e)
+d.cursor=d.cursor+4
+end
+function c.writeF64(d,e)
+d:reserve(8)
+buffer.writef64(d.data,d.cursor,e)
+d.cursor=d.cursor+8
+end
+function c.writeVarUint(d,e)
+local f=e
+while f>=b do
+local g=f%b
+local h=g+b
+d:writeU8(h)
+f=math.floor(f/b)
+end
+d:writeU8(f)
+end
+function c.writeString(d,e)
+local f=#e
+d:writeVarUint(f)
+d:reserve(f)
+buffer.writestring(d.data,d.cursor,e,f)
+d.cursor=d.cursor+f
+end
+function c.writeBuffer(d,e)
+local f=buffer.len(e)
+d:writeVarUint(f)
+d:reserve(f)
+buffer.copy(d.data,d.cursor,e,0,f)
+d.cursor=d.cursor+f
+end
+function c.writeBlob(d,e)
+local f=#d.blobs
+local g=d.blobs
+local h=e
+table.insert(g,h)
+d:writeVarUint(f)
+end
+function c.getBuffer(d)
+local e=buffer.create(d.cursor)
+buffer.copy(e,0,d.data,0,d.cursor)
+return e
+end
+function c.getBlobs(d)
+return d.blobs
+end
+function c.reserve(d,e)
+local f=d.cursor+e
+if f<=d.capacity then
+return nil
+end
+local g=d.capacity*2
+while g<f do
+g=g*2
+end
+local h=buffer.create(g)
+buffer.copy(h,0,d.data,0,d.cursor)
+d.data=h
+d.capacity=g
+end
+end
+return{
+BufferWriter=c,
+}

package/out/lib/Codec.d.ts

@@ -0,0 +1,7 @@
+import type { BufferReader } from "./BufferReader";
+import type { BufferWriter } from "./BufferWriter";
+export interface Codec<T> {
+    write(writer: BufferWriter, value: T): void;
+    read(reader: BufferReader): T;
+}
+export type AnyCodec = Codec<unknown>;

package/out/lib/Codec.luau

@@ -0,0 +1,2 @@
+
+return nil

package/out/lib/CodecCompiler.d.ts

@@ -0,0 +1,5 @@
+import type { AnyCodec } from "./Codec";
+type SimpleKind = "bool" | "f64" | "string" | "buffer" | "blob" | "vector3" | "vector2" | "vector3int16" | "vector2int16" | "cframe" | "color3" | "brickcolor" | "udim" | "udim2" | "rect" | "ray" | "region3" | "region3int16" | "numberrange" | "numbersequence" | "colorsequence" | "physicalproperties" | "datetime" | "tweeninfo" | "font" | "axes" | "faces";
+export type Metadata = [SimpleKind] | ["optional", Metadata] | ["literal", Array<defined>, number] | ["list", Metadata] | ["tuple", Array<Metadata>] | ["set", Metadata] | ["map", Metadata, Metadata] | ["object", Array<[string, Metadata]>] | ["enum", string] | ["union", string, Array<[defined, Metadata]>];
+export declare function compileCodec(meta: Metadata): AnyCodec;
+export {};

package/out/lib/CodecCompiler.luau

@@ -0,0 +1,164 @@
+
+local a=_G[script]
+local b=a.import(script,script.Parent,"CollectionCodecs")
+local c=b.list
+local d=b.map
+local e=b.object
+local f=b.optional
+local g=b.set
+local h=b.tuple
+local i=b.variant
+local j=a.import(script,script.Parent,"PrimitiveCodecs")
+local k=j.blobCodec
+local l=j.boolCodec
+local m=j.bufferCodec
+local n=j.f64Codec
+local o=j.literal
+local p=j.literalUnion
+local q=j.stringCodec
+local r=a.import(script,script.Parent,"RobloxCodecs")
+local s=r.axesCodec
+local t=r.brickColorCodec
+local u=r.cframeCodec
+local v=r.color3Codec
+local w=r.colorSequenceCodec
+local x=r.createEnumCodecByName
+local y=r.dateTimeCodec
+local z=r.facesCodec
+local A=r.fontCodec
+local B=r.numberRangeCodec
+local C=r.numberSequenceCodec
+local D=r.physicalPropertiesCodec
+local E=r.rayCodec
+local F=r.rectCodec
+local G=r.region3Codec
+local H=r.region3int16Codec
+local I=r.tweenInfoCodec
+local J=r.udim2Codec
+local K=r.udimCodec
+local L=r.vector2Codec
+local M=r.vector2int16Codec
+local N=r.vector3Codec
+local O=r.vector3int16Codec
+local P=-1
+local Q=1
+local R={
+bool=l,
+f64=n,
+string=q,
+buffer=m,
+blob=k,
+vector3=N,
+vector2=L,
+vector3int16=O,
+vector2int16=M,
+cframe=u,
+color3=v,
+brickcolor=t,
+udim=K,
+udim2=J,
+rect=F,
+ray=E,
+region3=G,
+region3int16=H,
+numberrange=B,
+numbersequence=C,
+colorsequence=w,
+physicalproperties=D,
+datetime=y,
+tweeninfo=I,
+font=A,
+axes=s,
+faces=z,
+}
+local S
+local function compileEach(T)
+local U={}
+for V,W in T do
+local X=S(W)
+table.insert(U,X)
+end
+return U
+end
+local function compileFields(T)
+local U={}
+for V,W in T do
+local X=W[1]
+local Y=W[2]
+local Z=S(Y)
+local _={X,Z}
+table.insert(U,_)
+end
+return U
+end
+local function compileVariants(T)
+local U={}
+for V,W in T do
+local X=W[1]
+local Y=W[2]
+local Z=S(Y)
+local _={X,Z}
+table.insert(U,_)
+end
+return U
+end
+function S(T)
+local U=T[1]
+repeat
+if U=="optional"then
+local V=S(T[2])
+return f(V)
+end
+if U=="literal"then
+local V=T[2]
+local W=T[3]
+if W==P then
+local X=V[1]
+return o(X)
+end
+local X=W==Q
+return p(V,X)
+end
+if U=="list"then
+local V=S(T[2])
+return c(V)
+end
+if U=="tuple"then
+local V=compileEach(T[2])
+return h(V)
+end
+if U=="set"then
+local V=S(T[2])
+return g(V)
+end
+if U=="map"then
+local V=S(T[2])
+local W=S(T[3])
+return d(V,W)
+end
+if U=="object"then
+local V=compileFields(T[2])
+return e(V)
+end
+if U=="enum"then
+local V=T[2]
+return x(V)
+end
+if U=="union"then
+local V=T[2]
+local W=compileVariants(T[3])
+return i(V,W)
+end
+do
+local V=T[1]
+local W=R[V]
+if W==nil then
+error(string.format('[Serialization] the schema contains an unsupported kind: %s', tostring(V)))
+end
+return W
+end
+until true
+end
+return{
+compileCodec=S,
+}

package/out/lib/CollectionCodecs.d.ts

@@ -0,0 +1,10 @@
+import type { AnyCodec } from "./Codec";
+export type ObjectField = [name: string, codec: AnyCodec];
+export type VariantEntry = [tag: defined, codec: AnyCodec];
+export declare function optional(inner: AnyCodec): AnyCodec;
+export declare function list(inner: AnyCodec): AnyCodec;
+export declare function tuple(members: ReadonlyArray<AnyCodec>): AnyCodec;
+export declare function set(inner: AnyCodec): AnyCodec;
+export declare function map(keyCodec: AnyCodec, valueCodec: AnyCodec): AnyCodec;
+export declare function object(fields: ReadonlyArray<ObjectField>): AnyCodec;
+export declare function variant(discriminator: string, entries: ReadonlyArray<VariantEntry>): AnyCodec;