utilium 0.2.1 → 0.3.1

package/dist/index.d.ts

@@ -2,4 +2,6 @@ export * from './misc.js';
 export * from './numbers.js';
 export * from './objects.js';
 export * from './random.js';
+export * from './string.js';
+export * from './struct.js';
 export * from './types.js';

package/dist/index.js

@@ -2,4 +2,6 @@ export * from './misc.js';
 export * from './numbers.js';
 export * from './objects.js';
 export * from './random.js';
+export * from './string.js';
+export * from './struct.js';
 export * from './types.js';

package/dist/objects.d.ts

@@ -1,4 +1,4 @@
-/// <reference types="node" />
+/// <reference types="node" resolution-mode="require"/>
 import type * as FS from 'fs';
 export declare function filterObject<O extends object, R extends object>(object: O, predicate: (key: keyof O, value: O[keyof O]) => boolean): R;
 export declare function pick<T extends object, K extends keyof T>(object: T, ...keys: readonly K[]): Pick<T, K>;

package/dist/string.d.ts

@@ -0,0 +1,2 @@
+export declare function capitalize<T extends string>(value: T): Capitalize<T>;
+export declare function uncapitalize<T extends string>(value: T): Uncapitalize<T>;

package/dist/string.js

@@ -0,0 +1,6 @@
+export function capitalize(value) {
+    return (value.at(0).toUpperCase() + value.slice(1));
+}
+export function uncapitalize(value) {
+    return (value.at(0).toLowerCase() + value.slice(1));
+}

package/dist/struct.d.ts

@@ -0,0 +1,125 @@
+import { ClassLike } from './types.js';
+export type PrimitiveType = `${'int' | 'uint'}${8 | 16 | 32 | 64}` | `float${32 | 64}`;
+export type ValidPrimitiveType = PrimitiveType | Capitalize<PrimitiveType> | 'char';
+/**
+ * Options for struct initialization
+ */
+export interface StructOptions {
+    align: number;
+    bigEndian: boolean;
+}
+/**
+ * Gets the size in bytes of a type
+ */
+export declare function sizeof(type: ValidPrimitiveType | ClassLike | object): number;
+/**
+ * Aligns a number
+ */
+export declare function align(value: number, alignment: number): number;
+/**
+ * Decorates a class as a struct
+ */
+export declare function struct(options?: Partial<StructOptions>): (target: ClassLike, _?: ClassDecoratorContext) => void;
+/**
+ * Decorates a class member to be serialized
+ */
+export declare function member(type: ValidPrimitiveType | ClassLike, length?: number): (target: object, context?: ClassMemberDecoratorContext | string | symbol) => void;
+/**
+ * Serializes a struct into a Uint8Array
+ */
+export declare function serialize(instance: unknown): Uint8Array;
+/**
+ * Deserializes a struct from a Uint8Array
+ */
+export declare function deserialize(instance: unknown, _buffer: ArrayBuffer | ArrayBufferView): void;
+/**
+ * Shortcut types
+ *
+ * Instead of writing `@member(type)` you can write `@types.type`, or `@types.type(length)` for arrays
+ */
+export declare const types: {
+    int8: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    int16: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    int32: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    int64: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    uint8: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    uint16: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    uint32: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    uint64: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    float32: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    float64: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    Int8: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    Int16: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    Int32: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    Int64: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    Uint8: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    Uint16: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    Uint32: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    Uint64: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    Float32: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    Float64: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+    char: {
+        (length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+        (target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+    };
+};

package/dist/struct.js

@@ -0,0 +1,180 @@
+import { capitalize } from './string.js';
+const primitiveTypes = ['int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'int64', 'uint64', 'float32', 'float64'];
+const validPrimitiveTypes = [...primitiveTypes, ...primitiveTypes.map(t => capitalize(t)), 'char'];
+const numberRegex = /^(u?int)(8|16|32|64)|(float)(32|64)$/i;
+function normalizePrimitive(type) {
+    return type == 'char' ? 'uint8' : type.toLowerCase();
+}
+function isPrimitiveType(type) {
+    return numberRegex.test(type.toString());
+}
+function isValidPrimitive(type) {
+    return type == 'char' || numberRegex.test(type.toString().toLowerCase());
+}
+const init = Symbol('struct_init');
+const metadata = Symbol('struct');
+function isStatic(arg) {
+    return typeof arg == 'function' && metadata in arg;
+}
+function isInstance(arg) {
+    return metadata in (arg?.constructor || {});
+}
+function isStruct(arg) {
+    return isInstance(arg) || isStatic(arg);
+}
+/**
+ * Gets the size in bytes of a type
+ */
+export function sizeof(type) {
+    // primitive
+    if (typeof type == 'string') {
+        if (!isValidPrimitive(type)) {
+            throw new TypeError('Invalid primitive type: ' + type);
+        }
+        return +normalizePrimitive(type).match(numberRegex)[2] / 8;
+    }
+    if (!isStruct(type)) {
+        throw new TypeError('Not a struct');
+    }
+    const meta = metadata in type ? type[metadata] : type.constructor[metadata];
+    return meta.size;
+}
+/**
+ * Aligns a number
+ */
+export function align(value, alignment) {
+    return Math.ceil(value / alignment) * alignment;
+}
+/**
+ * Decorates a class as a struct
+ */
+export function struct(options = {}) {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    return function (target, _) {
+        target[init] || (target[init] = []);
+        let size = 0;
+        const members = new Map();
+        for (const { name, type, length } of target[init]) {
+            if (!isValidPrimitive(type) && !isStatic(type)) {
+                throw new TypeError('Not a valid type: ' + type);
+            }
+            members.set(name, {
+                offset: size,
+                type: isValidPrimitive(type) ? normalizePrimitive(type) : type,
+                length,
+            });
+            size += sizeof(type) * (length || 1);
+            size = align(size, options.align || 1);
+        }
+        target[metadata] = { options, members, size };
+        delete target[init];
+    };
+}
+/**
+ * Decorates a class member to be serialized
+ */
+export function member(type, length) {
+    return function (target, context) {
+        var _a;
+        let name = typeof context == 'object' ? context.name : context;
+        if (typeof name == 'symbol') {
+            console.warn('Symbol used for struct member name will be coerced to string: ' + name.toString());
+            name = name.toString();
+        }
+        (_a = target.constructor)[init] || (_a[init] = []);
+        target.constructor[init].push({ name, type, length });
+    };
+}
+/**
+ * Serializes a struct into a Uint8Array
+ */
+export function serialize(instance) {
+    if (!isInstance(instance)) {
+        throw new TypeError('Can not serialize, not a struct instance');
+    }
+    const { options, members } = instance.constructor[metadata];
+    const buffer = new Uint8Array(sizeof(instance));
+    const view = new DataView(buffer.buffer);
+    for (const [name, { type, length, offset }] of members) {
+        for (let i = 0; i < (length || 1); i++) {
+            const iOff = offset + sizeof(type) * i;
+            let value = length > 0 ? instance[name][i] : instance[name];
+            if (typeof value == 'string') {
+                value = value.charCodeAt(0);
+            }
+            if (!isPrimitiveType(type)) {
+                buffer.set(value ? serialize(value) : new Uint8Array(sizeof(type)), iOff);
+                continue;
+            }
+            const Type = capitalize(type);
+            const fn = ('set' + Type);
+            if (fn == 'setInt64') {
+                view.setBigInt64(iOff, BigInt(value), !options.bigEndian);
+                continue;
+            }
+            if (fn == 'setUint64') {
+                view.setBigUint64(iOff, BigInt(value), !options.bigEndian);
+                continue;
+            }
+            view[fn](iOff, Number(value), !options.bigEndian);
+        }
+    }
+    return buffer;
+}
+/**
+ * Deserializes a struct from a Uint8Array
+ */
+export function deserialize(instance, _buffer) {
+    if (!isInstance(instance)) {
+        throw new TypeError('Can not deserialize, not a struct instance');
+    }
+    const { options, members } = instance.constructor[metadata];
+    const buffer = new Uint8Array('buffer' in _buffer ? _buffer.buffer : _buffer);
+    const view = new DataView(buffer.buffer);
+    for (const [name, { type, offset, length }] of members) {
+        for (let i = 0; i < (length || 1); i++) {
+            let object = length > 0 ? instance[name] : instance;
+            const key = length > 0 ? i : name, iOff = offset + sizeof(type) * i;
+            if (typeof instance[name] == 'string') {
+                instance[name] = instance[name].slice(0, i) + String.fromCharCode(view.getUint8(iOff)) + instance[name].slice(i + 1);
+                continue;
+            }
+            if (!isPrimitiveType(type)) {
+                if (object[key] === null || object[key] === undefined) {
+                    continue;
+                }
+                deserialize(object[key], new Uint8Array(buffer.slice(iOff, sizeof(type))));
+                continue;
+            }
+            if (length > 0) {
+                object || (object = []);
+            }
+            const Type = capitalize(type);
+            const fn = ('get' + Type);
+            if (fn == 'getInt64') {
+                object[key] = view.getBigInt64(iOff, !options.bigEndian);
+                continue;
+            }
+            if (fn == 'getUint64') {
+                object[key] = view.getBigUint64(iOff, !options.bigEndian);
+                continue;
+            }
+            object[key] = view[fn](iOff, !options.bigEndian);
+        }
+    }
+}
+function _member(type) {
+    function _(targetOrLength, context) {
+        if (typeof targetOrLength == 'number') {
+            return member(type, targetOrLength);
+        }
+        return member(type)(targetOrLength, context);
+    }
+    return _;
+}
+/**
+ * Shortcut types
+ *
+ * Instead of writing `@member(type)` you can write `@types.type`, or `@types.type(length)` for arrays
+ */
+export const types = Object.fromEntries(validPrimitiveTypes.map(t => [t, _member(t)]));

package/dist/types.d.ts

@@ -170,4 +170,9 @@ export type Tuple<T, N extends number> = _Tuple<T, N>;
  * Makes all members of the tuple T optional
  */
 export type OptionalTuple<T extends unknown[]> = T extends [infer Head, ...infer Tail] ? [Head?, ...OptionalTuple<Tail>] : T;
+/**
+ * Keys of a Map
+ */
+export type MapKeys<T> = T extends Map<infer K, any> ? K : never;
+export type ClassLike<Instance = unknown> = abstract new (...args: unknown[]) => Instance;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "utilium",
-	"version": "0.2.1",
+	"version": "0.3.1",
 	"description": "Typescript utilies",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/src/index.ts

@@ -2,4 +2,6 @@ export * from './misc.js';
 export * from './numbers.js';
 export * from './objects.js';
 export * from './random.js';
+export * from './string.js';
+export * from './struct.js';
 export * from './types.js';

package/src/string.ts

@@ -0,0 +1,7 @@
+export function capitalize<T extends string>(value: T): Capitalize<T> {
+	return <Capitalize<T>>(value.at(0).toUpperCase() + value.slice(1));
+}
+
+export function uncapitalize<T extends string>(value: T): Uncapitalize<T> {
+	return <Uncapitalize<T>>(value.at(0).toLowerCase() + value.slice(1));
+}

package/src/struct.ts

@@ -0,0 +1,264 @@
+import { capitalize } from './string.js';
+import { ClassLike } from './types.js';
+
+export type PrimitiveType = `${'int' | 'uint'}${8 | 16 | 32 | 64}` | `float${32 | 64}`;
+export type ValidPrimitiveType = PrimitiveType | Capitalize<PrimitiveType> | 'char';
+
+const primitiveTypes = ['int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'int64', 'uint64', 'float32', 'float64'] satisfies PrimitiveType[];
+
+const validPrimitiveTypes = [...primitiveTypes, ...primitiveTypes.map(t => capitalize(t)), 'char'] satisfies ValidPrimitiveType[];
+
+const numberRegex = /^(u?int)(8|16|32|64)|(float)(32|64)$/i;
+
+function normalizePrimitive(type: ValidPrimitiveType): PrimitiveType {
+	return type == 'char' ? 'uint8' : <PrimitiveType>type.toLowerCase();
+}
+
+function isPrimitiveType(type: unknown): type is PrimitiveType {
+	return numberRegex.test(type.toString());
+}
+
+function isValidPrimitive(type: unknown): type is ValidPrimitiveType {
+	return type == 'char' || numberRegex.test(type.toString().toLowerCase());
+}
+
+interface MemberInit {
+	name: string;
+	type: string | ClassLike;
+	length?: number;
+}
+
+const init = Symbol('struct_init');
+
+/**
+ * Options for struct initialization
+ */
+export interface StructOptions {
+	align: number;
+	bigEndian: boolean;
+}
+
+interface Member {
+	type: PrimitiveType | Static;
+	offset: number;
+	length?: number;
+}
+
+interface Metadata {
+	options: Partial<StructOptions>;
+	members: Map<string, Member>;
+	size: number;
+}
+
+const metadata = Symbol('struct');
+
+interface Static {
+	[metadata]?: Metadata;
+	new (): Instance;
+	prototype: Instance;
+}
+
+function isStatic(arg: unknown): arg is Static {
+	return typeof arg == 'function' && metadata in arg;
+}
+
+interface Instance {
+	constructor: Static;
+}
+
+function isInstance(arg: unknown): arg is Instance {
+	return metadata in (arg?.constructor || {});
+}
+
+function isStruct(arg: unknown): arg is Instance | Static {
+	return isInstance(arg) || isStatic(arg);
+}
+
+/**
+ * Gets the size in bytes of a type
+ */
+export function sizeof(type: ValidPrimitiveType | ClassLike | object): number {
+	// primitive
+	if (typeof type == 'string') {
+		if (!isValidPrimitive(type)) {
+			throw new TypeError('Invalid primitive type: ' + type);
+		}
+
+		return +normalizePrimitive(type).match(numberRegex)[2] / 8;
+	}
+
+	if (!isStruct(type)) {
+		throw new TypeError('Not a struct');
+	}
+
+	const meta: Metadata = metadata in type ? type[metadata] : type.constructor[metadata];
+	return meta.size;
+}
+
+/**
+ * Aligns a number
+ */
+export function align(value: number, alignment: number): number {
+	return Math.ceil(value / alignment) * alignment;
+}
+
+/**
+ * Decorates a class as a struct
+ */
+export function struct(options: Partial<StructOptions> = {}) {
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	return function (target: ClassLike, _?: ClassDecoratorContext) {
+		target[init] ||= [];
+		let size = 0;
+		const members = new Map();
+		for (const { name, type, length } of target[init] as MemberInit[]) {
+			if (!isValidPrimitive(type) && !isStatic(type)) {
+				throw new TypeError('Not a valid type: ' + type);
+			}
+			members.set(name, {
+				offset: size,
+				type: isValidPrimitive(type) ? normalizePrimitive(type) : type,
+				length,
+			});
+			size += sizeof(type) * (length || 1);
+			size = align(size, options.align || 1);
+		}
+
+		target[metadata] = { options, members, size } satisfies Metadata;
+		delete target[init];
+	};
+}
+
+/**
+ * Decorates a class member to be serialized
+ */
+export function member(type: ValidPrimitiveType | ClassLike, length?: number) {
+	return function (target: object, context?: ClassMemberDecoratorContext | string | symbol) {
+		let name = typeof context == 'object' ? context.name : context;
+		if (typeof name == 'symbol') {
+			console.warn('Symbol used for struct member name will be coerced to string: ' + name.toString());
+			name = name.toString();
+		}
+
+		target.constructor[init] ||= [];
+		target.constructor[init].push({ name, type, length } satisfies MemberInit);
+	};
+}
+
+/**
+ * Serializes a struct into a Uint8Array
+ */
+export function serialize(instance: unknown): Uint8Array {
+	if (!isInstance(instance)) {
+		throw new TypeError('Can not serialize, not a struct instance');
+	}
+	const { options, members } = instance.constructor[metadata];
+
+	const buffer = new Uint8Array(sizeof(instance));
+	const view = new DataView(buffer.buffer);
+
+	for (const [name, { type, length, offset }] of members) {
+		for (let i = 0; i < (length || 1); i++) {
+			const iOff = offset + sizeof(type) * i;
+
+			let value = length > 0 ? instance[name][i] : instance[name];
+			if (typeof value == 'string') {
+				value = value.charCodeAt(0);
+			}
+
+			if (!isPrimitiveType(type)) {
+				buffer.set(value ? serialize(value) : new Uint8Array(sizeof(type)), iOff);
+				continue;
+			}
+
+			const Type = capitalize(type);
+			const fn = <`set${typeof Type}`>('set' + Type);
+			if (fn == 'setInt64') {
+				view.setBigInt64(iOff, BigInt(value), !options.bigEndian);
+				continue;
+			}
+
+			if (fn == 'setUint64') {
+				view.setBigUint64(iOff, BigInt(value), !options.bigEndian);
+				continue;
+			}
+
+			view[fn](iOff, Number(value), !options.bigEndian);
+		}
+	}
+
+	return buffer;
+}
+
+/**
+ * Deserializes a struct from a Uint8Array
+ */
+export function deserialize(instance: unknown, _buffer: ArrayBuffer | ArrayBufferView) {
+	if (!isInstance(instance)) {
+		throw new TypeError('Can not deserialize, not a struct instance');
+	}
+	const { options, members } = instance.constructor[metadata];
+
+	const buffer = new Uint8Array('buffer' in _buffer ? _buffer.buffer : _buffer);
+
+	const view = new DataView(buffer.buffer);
+
+	for (const [name, { type, offset, length }] of members) {
+		for (let i = 0; i < (length || 1); i++) {
+			let object = length > 0 ? instance[name] : instance;
+			const key = length > 0 ? i : name,
+				iOff = offset + sizeof(type) * i;
+
+			if (typeof instance[name] == 'string') {
+				instance[name] = instance[name].slice(0, i) + String.fromCharCode(view.getUint8(iOff)) + instance[name].slice(i + 1);
+				continue;
+			}
+
+			if (!isPrimitiveType(type)) {
+				if (object[key] === null || object[key] === undefined) {
+					continue;
+				}
+				deserialize(object[key], new Uint8Array(buffer.slice(iOff, sizeof(type))));
+				continue;
+			}
+
+			if (length > 0) {
+				object ||= [];
+			}
+
+			const Type = capitalize(type);
+			const fn = <`get${typeof Type}`>('get' + Type);
+			if (fn == 'getInt64') {
+				object[key] = view.getBigInt64(iOff, !options.bigEndian);
+				continue;
+			}
+
+			if (fn == 'getUint64') {
+				object[key] = view.getBigUint64(iOff, !options.bigEndian);
+				continue;
+			}
+
+			object[key] = view[fn](iOff, !options.bigEndian);
+		}
+	}
+}
+
+function _member<T extends ValidPrimitiveType>(type: T) {
+	function _(length?: number): (target: object, context?: string | symbol | ClassMemberDecoratorContext) => void;
+	function _(target: object, context?: string | symbol | ClassMemberDecoratorContext): void;
+	function _(targetOrLength: object | number, context?: string | symbol | ClassMemberDecoratorContext) {
+		if (typeof targetOrLength == 'number') {
+			return member(type, targetOrLength);
+		}
+
+		return member(type)(targetOrLength, context);
+	}
+	return _;
+}
+
+/**
+ * Shortcut types
+ *
+ * Instead of writing `@member(type)` you can write `@types.type`, or `@types.type(length)` for arrays
+ */
+export const types = Object.fromEntries(validPrimitiveTypes.map(t => [t, _member(t)])) as { [K in ValidPrimitiveType]: ReturnType<typeof _member<K>> };

package/src/types.ts

@@ -195,3 +195,10 @@ export type Tuple<T, N extends number> = _Tuple<T, N>;
  * Makes all members of the tuple T optional
  */
 export type OptionalTuple<T extends unknown[]> = T extends [infer Head, ...infer Tail] ? [Head?, ...OptionalTuple<Tail>] : T;
+
+/**
+ * Keys of a Map
+ */
+export type MapKeys<T> = T extends Map<infer K, any> ? K : never;
+
+export type ClassLike<Instance = unknown> = abstract new (...args: unknown[]) => Instance;