nytra 0.0.3 → 0.0.4

package/README.md

@@ -0,0 +1,107 @@
+# Nytra
+
+Fast binary serialization for JavaScript/TypeScript with decorator-based DTO support.
+
+Nytra helps you encode/decode plain values, arrays, objects, and class instances into compact binary buffers.
+
+## Features
+
+- Binary encode/decode for primitives, arrays, objects, bigint, and nested data
+- Decorator-based class schema registration
+- Nullable fields support in DTOs
+- Custom type IDs for compact class payloads
+- ESM package output with TypeScript declarations
+
+## Installation
+
+```bash
+npm install nytra
+```
+
+## Quick Start
+
+```ts
+import { Nytra, Types } from "nytra";
+
+@Nytra.registerClass(2000)
+class Player {
+  @Nytra.registerField(0, Types.TYPE_STRING)
+  name: string;
+
+  @Nytra.registerField(1, Types.TYPE_UINT16)
+  level: number;
+
+  @Nytra.registerField(2, Types.TYPE_STRING, { nullable: true })
+  guild: string | null = null;
+
+  constructor(name: string, level: number) {
+    this.name = name;
+    this.level = level;
+  }
+}
+
+const original = new Player("Ari", 42);
+const encoded = Nytra.encode(original);
+const decoded = Nytra.decode(encoded) as Player;
+
+console.log(decoded.name, decoded.level, decoded.guild);
+```
+
+## API Overview
+
+- `Nytra.encode(data, typeId?)` -> `Uint8Array`
+- `Nytra.decode(buffer)` -> decoded value
+- `Nytra.autoguessType(data)` -> internal type id
+- `Nytra.getTypeIdForClass(ClassCtor)` -> registered class type id
+- `Nytra.registerClass(typeId)` -> class decorator
+- `Nytra.registerField(position, typeOrClass, options?)` -> field decorator
+
+### `registerField` options
+
+- `nullable?: boolean` - marks a field as nullable in class schema
+
+## Supported Built-in Types
+
+Use constants from `Types`, for example:
+
+- `TYPE_NULL`, `TYPE_BOOLEAN`
+- `TYPE_UINT8`, `TYPE_UINT16`, `TYPE_UINT32`, `TYPE_UINT64`
+- `TYPE_INT8`, `TYPE_INT16`, `TYPE_INT32`, `TYPE_INT64`
+- `TYPE_FLOAT32`, `TYPE_FLOAT64`
+- `TYPE_STRING`, `TYPE_ARRAY`, `TYPE_OBJECT`, `TYPE_JSON`, `TYPE_BIGINT`
+
+## Development
+
+Build:
+
+```bash
+npm run build
+```
+
+Run tests (Bun):
+
+```bash
+bun test
+```
+
+## TypeScript Decorators Setup
+
+If you see decorator typing/runtime issues, enable modern decorators + metadata in your TS setup:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "lib": ["ES2022", "esnext.decorators", "esnext.decorators.metadata"]
+  }
+}
+```
+
+> Nytra decorators use the new standard decorator context APIs (`ClassDecoratorContext`, `ClassFieldDecoratorContext`).
+
+## License
+
+MIT
+

package/dist/Nytra.d.ts

@@ -0,0 +1,14 @@
+import { Reader } from "./Reader.ts";
+import { Writer } from "./Writer.ts";
+export type RegisterFieldOptions = {
+    nullable?: boolean;
+};
+export declare class Nytra {
+    #private;
+    static registerField(position: number, targetTypeId?: number | Function, options?: RegisterFieldOptions): (v: undefined, ctx: ClassFieldDecoratorContext) => void;
+    static registerClass(typeId: number): <T extends Function>(decoratedClass: T, ctx: ClassDecoratorContext) => void;
+    static autoguessType(data: unknown): number;
+    static getTypeIdForClass(ctor: Function): number;
+    static encode(data: unknown, type?: number | null, withType?: boolean, writer?: Writer | null): Uint8Array;
+    static decode(data: Uint8Array | Reader, type?: number | null): unknown;
+}

package/dist/Nytra.js

@@ -0,0 +1,468 @@
+import { Reader } from "./Reader.js";
+import { Registry } from "./Registry.js";
+import { Writer } from "./Writer.js";
+import { TYPE_ARRAY, TYPE_BIGINT, TYPE_BOOLEAN, TYPE_EXTENSION, TYPE_FLOAT32, TYPE_FLOAT64, TYPE_INT16, TYPE_INT32, TYPE_INT64, TYPE_INT8, TYPE_JSON, TYPE_NULL, TYPE_OBJECT, TYPE_STRING, TYPE_STRING_16_INTERNAL, TYPE_STRING_32_INTERNAL, TYPE_UINT16, TYPE_UINT32, TYPE_UINT64, TYPE_UINT8 } from "./Types.js";
+const MAX_UINT_32 = 2 ** 32;
+const MAX_UINT_16 = 2 ** 16;
+const MAX_UINT_8 = 2 ** 8;
+const MIN_INT_32 = -(2 ** 31);
+const MIN_INT_16 = -(2 ** 15);
+const MIN_INT_8 = -(2 ** 8);
+function createDecoder(cls) {
+    const meta = classMetaStore.get(cls);
+    const fields = meta?.fields;
+    return function (reader) {
+        let obj = {};
+        const nullableFields = fields.filter(([_name, meta]) => meta.options.nullable).map(([name, _meta]) => name);
+        const nullableBytes = Math.ceil(nullableFields.length / 8);
+        const nullableBitfield = nullableBytes > 0 ? reader.readBytes(nullableBytes) : [];
+        const isFieldNull = (index) => {
+            const byteIndex = Math.floor(index / 8);
+            const bitOffset = index % 8;
+            return (nullableBitfield[byteIndex] & (1 << bitOffset)) !== 0;
+        };
+        for (let [name, meta] of fields) {
+            if (nullableBytes > 0 && meta.options.nullable) {
+                const nullIndex = nullableFields.indexOf(name);
+                if (nullIndex !== -1 && isFieldNull(nullIndex)) {
+                    obj[name] = null;
+                    continue;
+                }
+            }
+            if (typeof meta.targetTypeId === "function") {
+                const found = classMetaStore.get(meta.targetTypeId);
+                meta.targetTypeId = found ? found.typeId : TYPE_JSON;
+            }
+            let type = meta.targetTypeId;
+            if (type === TYPE_STRING) {
+                type = reader.readType();
+            }
+            obj[name] = Nytra.decode(reader, type);
+        }
+        Object.setPrototypeOf(obj, cls.prototype);
+        return obj;
+    };
+}
+function createEncoder(cls) {
+    const meta = classMetaStore.get(cls);
+    const cachedEncoders = [];
+    const nullableFields = [];
+    let nullableBytes = 0;
+    return function (data, writer) {
+        if (writer === null) {
+            writer = new Writer();
+        }
+        if (cachedEncoders.length == 0) {
+            meta.fields.forEach(([name, fieldMeta]) => {
+                if (fieldMeta.options.nullable) {
+                    nullableFields.push(name);
+                }
+                let typeId = fieldMeta.targetTypeId;
+                if (!typeId) {
+                    cachedEncoders.push({ name: name, encode: null, options: fieldMeta.options });
+                    return;
+                }
+                // Resolve Function → typeId hier, nicht im Loop!
+                if (typeof typeId === 'function') {
+                    const found = classMetaStore.get(typeId);
+                    typeId = found ? found.typeId : TYPE_JSON;
+                }
+                // Encoder-Funktion vorgebunden
+                let encodeFn;
+                if (typeId < 255) {
+                    encodeFn = (value, writer) => Nytra.encode(value, typeId, false, writer);
+                }
+                else {
+                    encodeFn = CustomRegistry.getEncoder(typeId);
+                }
+                cachedEncoders.push({ name: name, encode: encodeFn, options: fieldMeta.options });
+            });
+            nullableBytes = Math.ceil(nullableFields.length / 8);
+        }
+        if (nullableBytes > 0) {
+            const nullableBitfield = new Uint8Array(nullableBytes);
+            for (let i = 0; i < nullableFields.length; i++) {
+                const field = nullableFields[i];
+                if (data[field] === null) {
+                    const byteIndex = Math.floor(i / 8);
+                    const bitOffset = i % 8;
+                    nullableBitfield[byteIndex] |= (1 << bitOffset);
+                }
+            }
+            writer.writeBytes(nullableBitfield);
+        }
+        for (const encodeInfo of cachedEncoders) {
+            const value = data[encodeInfo.name];
+            if (value === null && encodeInfo.options.nullable) {
+                continue;
+            }
+            encodeInfo.encode ?
+                encodeInfo.encode(data[encodeInfo.name], writer) :
+                Nytra.encode(data[encodeInfo.name], null, true, writer);
+        }
+        return writer.toUint8Array();
+    };
+}
+const classMetaStore = new WeakMap();
+const SYMBOL_FIELDS = Symbol('Nytra:fields');
+const CustomRegistry = new Registry();
+export class Nytra {
+    static registerField(position, targetTypeId, options = {}) {
+        const defaultOpts = {
+            nullable: false
+        };
+        Object.assign(defaultOpts, options);
+        return function (v, ctx) {
+            if (ctx.private) {
+                throw new Error('Only public fields can be registered');
+            }
+            const metadata = ctx.metadata;
+            if (typeof metadata[SYMBOL_FIELDS] === 'undefined') {
+                metadata[SYMBOL_FIELDS] = new Map();
+            }
+            const fieldMeta = {
+                position,
+                targetTypeId,
+                options: defaultOpts
+            };
+            metadata[SYMBOL_FIELDS].set(ctx.name, fieldMeta);
+        };
+    }
+    static registerClass(typeId) {
+        if (typeId < 256 || typeId > 65535) {
+            throw new Error('typeId must be in range of 256 and 65535');
+        }
+        return function (decoratedClass, ctx) {
+            const metadata = ctx.metadata;
+            const fields = metadata[SYMBOL_FIELDS] ?
+                [...metadata[SYMBOL_FIELDS].entries()].sort(([_aName, aMeta], [_bName, bMeta]) => aMeta.position - bMeta.position)
+                : [];
+            classMetaStore.set(decoratedClass, { typeId, fields });
+            CustomRegistry.register(typeId, {
+                encoder: createEncoder(decoratedClass),
+                decoder: createDecoder(decoratedClass)
+            });
+        };
+    }
+    static autoguessType(data) {
+        if (data === null) {
+            return TYPE_NULL;
+        }
+        if (typeof data === 'object') {
+            const ctor = data.constructor;
+            const found = classMetaStore.get(ctor);
+            if (found) {
+                return found.typeId;
+            }
+        }
+        if (Array.isArray(data)) {
+            return TYPE_ARRAY;
+        }
+        if (typeof data === 'object') {
+            return TYPE_OBJECT;
+        }
+        if (typeof data === 'string') {
+            return TYPE_STRING;
+        }
+        if (typeof data === 'boolean') {
+            return TYPE_BOOLEAN;
+        }
+        if (typeof data === 'number') {
+            if (Number.isInteger(data)) {
+                if (data >= 0) {
+                    //unsigned possible
+                    if (data <= MAX_UINT_8) {
+                        return TYPE_UINT8;
+                    }
+                    if (data <= MAX_UINT_16) {
+                        return TYPE_UINT16;
+                    }
+                    if (data <= MAX_UINT_32) {
+                        return TYPE_UINT32;
+                    }
+                    return TYPE_UINT64;
+                }
+                else {
+                    if (data >= MIN_INT_8) {
+                        return TYPE_INT8;
+                    }
+                    if (data >= MIN_INT_16) {
+                        return TYPE_INT16;
+                    }
+                    if (data >= MIN_INT_32) {
+                        return TYPE_INT32;
+                    }
+                    return TYPE_INT64;
+                }
+            }
+            if (Math.fround(data) === data) {
+                return TYPE_FLOAT32;
+            }
+            return TYPE_FLOAT64;
+        }
+        if (typeof data === 'bigint') {
+            return TYPE_BIGINT;
+        }
+        return TYPE_JSON;
+    }
+    static getTypeIdForClass(ctor) {
+        const found = classMetaStore.get(ctor);
+        return found ? found.typeId : TYPE_JSON;
+    }
+    static #TEXT_ENCODER = new TextEncoder();
+    static encode(data, type = null, withType = true, writer = null) {
+        if (writer === null) {
+            writer = new Writer();
+        }
+        if (type === null) {
+            type = this.autoguessType(data);
+        }
+        if (type >= 256) {
+            const encodeFunction = CustomRegistry.getEncoder(type);
+            if (typeof encodeFunction !== 'function') {
+                throw new Error('Unknown type:' + type);
+            }
+            if (withType) {
+                writer.writeUint8(TYPE_EXTENSION);
+                writer.writeUint16(type);
+            }
+            encodeFunction(data, writer);
+            return writer.toUint8Array();
+        }
+        if (type >= TYPE_STRING) { //automatically
+            const str = data;
+            const bytes = this.#TEXT_ENCODER.encode(str);
+            const len = bytes.length;
+            if (len <= 127) {
+                writer.writeUint8(128 + len);
+                writer.writeBytes(bytes);
+                return writer.toUint8Array();
+            }
+            if (len <= 65535) {
+                writer.writeUint8(TYPE_STRING_16_INTERNAL);
+                writer.writeUint16(len);
+                writer.writeBytes(bytes);
+                return writer.toUint8Array();
+            }
+            writer.writeUint8(TYPE_STRING_32_INTERNAL);
+            writer.writeUint32(len);
+            writer.writeBytes(bytes);
+            return writer.toUint8Array();
+        }
+        switch (type) {
+            case TYPE_NULL:
+                writer.writeUint8(TYPE_NULL);
+                return writer.toUint8Array();
+            case TYPE_ARRAY: {
+                if (!Array.isArray(data)) {
+                    throw new Error('Data must be an array');
+                }
+                const arr = data;
+                if (withType)
+                    writer.writeUint8(TYPE_ARRAY);
+                const startIndex = writer.offset;
+                writer.setOffset(startIndex + 4); // reserve space for length
+                for (let value of arr) {
+                    this.encode(value, null, true, writer);
+                }
+                const endIndex = writer.offset;
+                writer.setOffset(startIndex);
+                writer.writeUint32(endIndex - startIndex - 4);
+                writer.setOffset(endIndex);
+                return writer.toUint8Array();
+            }
+            case TYPE_OBJECT: {
+                if (typeof data !== 'object') {
+                    throw new Error('Data must be an array');
+                }
+                const obj = data;
+                if (withType)
+                    writer.writeUint8(TYPE_OBJECT);
+                const startIndex = writer.offset;
+                writer.setOffset(startIndex + 4);
+                let keys = Object.keys(obj);
+                for (let key of keys) {
+                    this.encode(key, TYPE_STRING, true, writer);
+                    this.encode(obj[key], null, true, writer);
+                }
+                const endIndex = writer.offset;
+                writer.setOffset(startIndex);
+                writer.writeUint32(endIndex - startIndex - 4);
+                writer.setOffset(endIndex);
+                return writer.toUint8Array();
+            }
+            case TYPE_UINT8: {
+                if (withType)
+                    writer.writeUint8(TYPE_UINT8);
+                writer.writeUint8(data);
+                return writer.toUint8Array();
+            }
+            case TYPE_UINT16: {
+                if (withType)
+                    writer.writeUint8(TYPE_UINT16);
+                writer.writeUint16(data);
+                return writer.toUint8Array();
+            }
+            case TYPE_UINT32: {
+                if (withType)
+                    writer.writeUint8(TYPE_UINT32);
+                writer.writeUint32(data);
+                return writer.toUint8Array();
+            }
+            case TYPE_UINT64: {
+                if (withType)
+                    writer.writeUint8(TYPE_UINT64);
+                writer.writeUint64(BigInt(data));
+                return writer.toUint8Array();
+            }
+            case TYPE_INT8: {
+                if (withType)
+                    writer.writeUint8(TYPE_INT8);
+                writer.writeInt8(data);
+                return writer.toUint8Array();
+            }
+            case TYPE_INT16: {
+                if (withType)
+                    writer.writeUint8(TYPE_INT16);
+                writer.writeInt16(data);
+                return writer.toUint8Array();
+            }
+            case TYPE_INT32: {
+                if (withType)
+                    writer.writeUint8(TYPE_INT32);
+                writer.writeInt32(data);
+                return writer.toUint8Array();
+            }
+            case TYPE_INT64: {
+                if (withType)
+                    writer.writeUint8(TYPE_INT64);
+                writer.writeInt64(BigInt(data));
+                return writer.toUint8Array();
+            }
+            case TYPE_BOOLEAN: {
+                if (withType)
+                    writer.writeUint8(TYPE_BOOLEAN);
+                writer.writeUint8(data ? 1 : 0);
+                return writer.toUint8Array();
+            }
+            case TYPE_JSON: {
+                return this.encode(JSON.stringify(data), TYPE_STRING, withType, writer);
+            }
+            case TYPE_FLOAT32: {
+                if (withType)
+                    writer.writeUint8(TYPE_FLOAT32);
+                writer.writeFloat32(data);
+                return writer.toUint8Array();
+            }
+            case TYPE_FLOAT64: {
+                if (withType)
+                    writer.writeUint8(TYPE_FLOAT64);
+                writer.writeFloat64(data);
+                return writer.toUint8Array();
+            }
+            case TYPE_BIGINT: {
+                if (withType)
+                    writer.writeUint8(TYPE_BIGINT);
+                writer.writeBigInt(BigInt(data));
+                return writer.toUint8Array();
+            }
+        }
+        throw new Error('Type unknown: ' + type);
+    }
+    static decode(data, type = null) {
+        let reader = data instanceof Reader ? data : new Reader(data);
+        if (type === null)
+            type = reader.readType();
+        if (type > 255) {
+            const decodeFunction = CustomRegistry.getDecoder(type);
+            if (typeof decodeFunction !== 'function') {
+                throw new Error('Unknown type:' + type);
+            }
+            return decodeFunction(reader);
+        }
+        if (type >= TYPE_STRING) {
+            let length = type & 0b01111111;
+            return reader.readString(length);
+        }
+        switch (type) {
+            case TYPE_STRING_16_INTERNAL: {
+                const length = reader.readUINT16();
+                return reader.readString(length);
+            }
+            case TYPE_STRING_32_INTERNAL: {
+                const length = reader.readUINT32();
+                return reader.readString(length);
+            }
+            case TYPE_BOOLEAN: {
+                return reader.readUINT8() !== 0;
+            }
+            case TYPE_JSON: {
+                const json = this.decode(reader);
+                return JSON.parse(json);
+            }
+            case TYPE_UINT8: {
+                return reader.readUINT8();
+            }
+            case TYPE_UINT16: {
+                return reader.readUINT16();
+            }
+            case TYPE_UINT32: {
+                return reader.readUINT32();
+            }
+            case TYPE_UINT64: {
+                return bigintToSafeNumber(reader.readUINT64());
+            }
+            case TYPE_INT8: {
+                return reader.readINT8();
+            }
+            case TYPE_INT16: {
+                return reader.readINT16();
+            }
+            case TYPE_INT32: {
+                return reader.readINT32();
+            }
+            case TYPE_INT64: {
+                return bigintToSafeNumber(reader.readINT64());
+            }
+            case TYPE_FLOAT64: {
+                return reader.readFloat64();
+            }
+            case TYPE_FLOAT32: {
+                return reader.readFloat32();
+            }
+            case TYPE_ARRAY: {
+                const len = reader.readUINT32();
+                const end = reader.offset + len;
+                const targetArray = [];
+                while (reader.offset < end) {
+                    targetArray.push(this.decode(reader));
+                }
+                return targetArray;
+            }
+            case TYPE_OBJECT: {
+                const len = reader.readUINT32();
+                const end = reader.offset + len;
+                const targetObj = {};
+                while (reader.offset < end) {
+                    const key = this.decode(reader);
+                    targetObj[key] = this.decode(reader);
+                }
+                return targetObj;
+            }
+            case TYPE_BIGINT: {
+                return reader.readBigInt();
+            }
+            case TYPE_NULL: {
+                return null;
+            }
+        }
+        throw new Error('Unknown type:' + type);
+    }
+}
+function bigintToSafeNumber(value) {
+    if (value > BigInt(Number.MAX_SAFE_INTEGER) ||
+        value < BigInt(Number.MIN_SAFE_INTEGER)) {
+        return value;
+    }
+    return Number(value);
+}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { Binson } from "./Binson.js";
+export { Nytra } from "./Nytra.ts";
 export * as Types from "./Types.ts";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { Binson } from "./Binson.js";
+export { Nytra } from "./Nytra.js";
 export * as Types from "./Types.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "private": false,
   "name": "nytra",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "A javascript ES6 Decorator driven library to encode/decode javascript objects to/from binary optimized buffers to reduce payload on network",
   "license": "MIT",
   "author": "",
@@ -12,7 +12,10 @@
     "build": "tsc",
     "prepublishOnly": "npm run build"
   },
-  "files": ["dist"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "devDependencies": {
     "@msgpack/msgpack": "^3.1.3",
     "@types/bun": "^1.3.13",