utilium 2.0.0-pre.1 → 2.0.0

package/src/struct.ts

@@ -1,290 +0,0 @@
-import { BufferViewArray } from './buffer.js';
-import { _debugLog } from './debugging.js';
-import * as primitive from './internal/primitives.js';
-import type {
-	DecoratorContext,
-	Instance,
-	InstanceLike,
-	Member,
-	Metadata,
-	Options,
-	Size,
-	StaticLike,
-	TypeLike,
-} from './internal/struct.js';
-import { checkStruct, initMetadata, isInstance, isStatic, isStruct } from './internal/struct.js';
-import { _throw } from './misc.js';
-import { getAllPrototypes } from './objects.js';
-export * as Struct from './internal/struct.js';
-
-/**
- * Gets the size in bytes of a type
- */
-export function sizeof<T extends TypeLike>(type: T | T[]): Size<T> {
-	if (type === undefined || type === null) return 0 as Size<T>;
-
-	if (Array.isArray(type)) {
-		let size = 0;
-
-		for (let i = 0; i < type.length; i++) {
-			size += sizeof(type[i]);
-		}
-
-		return size as Size<T>;
-	}
-
-	// primitive or character
-	if (typeof type == 'string') {
-		primitive.checkValid(type);
-
-		return primitive.types[primitive.normalize(type)].size as Size<T>;
-	}
-
-	if (primitive.isType(type)) return type.size as Size<T>;
-
-	checkStruct(type);
-
-	const constructor = isStatic(type) ? type : type.constructor;
-	const { struct, structInit } = constructor[Symbol.metadata];
-
-	if (isStatic(type) || !struct.isDynamic) return struct.staticSize as Size<T>;
-
-	const last = structInit.members.at(-1)!;
-	const length = (type as any)[last.length as keyof typeof type];
-	let dynamicSize = 0;
-
-	if (primitive.isType(last.type)) {
-		dynamicSize = last.type.size * length;
-	} else {
-		const value = type[last.name];
-
-		for (let i = 0; i < length; i++) {
-			dynamicSize += sizeof(isStruct(value[i]) ? value[i] : last.type);
-		}
-	}
-
-	return (struct.isUnion ? Math.max(struct.staticSize, dynamicSize) : struct.staticSize + dynamicSize) as Size<T>;
-}
-
-/**
- * Returns the offset (in bytes) of a member in a struct.
- */
-export function offsetof(type: StaticLike | InstanceLike, memberName: string): number {
-	checkStruct(type);
-
-	const constructor = isStatic(type) ? type : type.constructor;
-
-	const member = constructor[Symbol.metadata].struct.members.get(memberName);
-
-	if (!member) throw new Error('Struct does not have member: ' + memberName);
-
-	return member.offset;
-}
-
-/** 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<Options> = {}) {
-	return function _decorateStruct<T extends StaticLike>(
-		target: T,
-		context: ClassDecoratorContext<T> & DecoratorContext
-	): void {
-		const init = initMetadata(context);
-
-		const members = new Map<string, Member>();
-
-		for (const member of init.members) {
-			if (options.isUnion) member.offset = 0;
-
-			_debugLog('define', target.name + '.' + member.name);
-
-			members.set(member.name, member);
-		}
-
-		context.metadata.struct = {
-			options,
-			members,
-			staticSize: init.size,
-			isDynamic: init.isDynamic,
-			isUnion: options.isUnion ?? false,
-		} satisfies Metadata;
-	};
-}
-
-export interface MemberOptions {
-	bigEndian?: boolean;
-	length?: number | string;
-	align?: number;
-	typeName?: string;
-}
-
-/**
- * Decorates a class member to be serialized
- */
-export function member<V>(type: primitive.Type | StaticLike, opt: MemberOptions = {}) {
-	return function __decorateMember(value: Target<V>, context: Context<V>): Result<V> {
-		if (context.kind != 'accessor') throw new Error('Member must be an accessor');
-
-		const init = initMetadata(context);
-
-		if (init.isDynamic) throw new Error('Dynamic members must be declared at the end of the struct');
-
-		let name = context.name;
-		if (typeof name == 'symbol') {
-			console.warn('Symbol used for struct member name will be coerced to string: ' + name.toString());
-			name = name.toString();
-		}
-
-		if (!name) throw new ReferenceError('Invalid name for struct member');
-
-		if (!primitive.isType(type) && !isStatic(type)) throw new TypeError('Not a valid type: ' + type.name);
-
-		if (typeof opt.length == 'string') {
-			const countedBy = init.members.find(m => m.name == opt.length);
-
-			if (!countedBy) throw new Error(`"${opt.length}" is not declared and cannot be used to count "${name}"`);
-
-			if (!primitive.isType(countedBy.type))
-				throw new Error(`"${opt.length}" is not a number and cannot be used to count "${name}"`);
-
-			init.isDynamic = true;
-		}
-
-		const size = align(
-			sizeof(type) * (typeof opt.length == 'string' ? 0 : (opt.length ?? 1)),
-			opt.align ?? sizeof(type)
-		);
-
-		const member = {
-			name,
-			offset: init.size,
-			type,
-			length: opt.length,
-			size,
-			decl: `${opt.typeName ?? type.name} ${name}${opt.length !== undefined ? `[${JSON.stringify(opt.length)}]` : ''}`,
-			littleEndian: !opt.bigEndian,
-		} satisfies Member;
-
-		init.members.push(member);
-
-		// Apply after setting `offset`
-		init.size += size;
-
-		return {
-			get() {
-				return _get(this, member);
-			},
-			set(value) {
-				_set(this, member, value);
-			},
-		};
-	};
-}
-
-/** Gets the length of a member */
-function _memberLength<T extends Metadata>(instance: Instance<T>, length?: number | string): number {
-	if (length === undefined) return -1;
-	if (typeof length == 'string') return instance[length];
-	return Number.isSafeInteger(length) && length >= 0
-		? length
-		: _throw(new Error('Array lengths must be natural numbers'));
-}
-
-function _set(instance: Instance, member: Member, value: any, index?: number) {
-	const { name, type, length: rawLength } = member;
-	const length = _memberLength(instance, rawLength);
-
-	if (!primitive.isType(type)) {
-		if (!isInstance(value)) return _debugLog(`Tried to set "${name}" to a non-instance value`);
-
-		if (length > 0 && typeof index != 'number') {
-			for (let i = 0; i < length; i++) _set(instance, member, value[i], i);
-			return;
-		}
-
-		if (!Array.from(getAllPrototypes(value.constructor)).some(c => c === type))
-			throw new Error(`${value.constructor.name} is not a subtype of ${type.name}`);
-
-		const offset = instance.byteOffset + member.offset + (index ?? 0) * sizeof(type);
-
-		// It's already the same value
-		if (value.buffer === instance.buffer && value.byteOffset === offset) return;
-
-		const current = new Uint8Array(instance.buffer, offset, sizeof(value));
-
-		current.set(new Uint8Array(value.buffer, value.byteOffset, sizeof(value)));
-
-		return;
-	}
-
-	const view = new DataView(instance.buffer, instance.byteOffset, instance.byteLength);
-
-	if (length > 0 && typeof index != 'number') {
-		for (let i = 0; i < length; i++) {
-			const offset = member.offset + i * type.size;
-			type.set(view, offset, member.littleEndian, value[i]);
-		}
-		return;
-	}
-
-	if (typeof value == 'string') value = value.charCodeAt(0);
-
-	type.set(view, member.offset + (index ?? 0) * type.size, member.littleEndian, value);
-}
-
-function _get(instance: Instance, member: Member, index?: number) {
-	const { type, length: rawLength } = member;
-	const length = _memberLength(instance, rawLength);
-
-	if (length > 0 && typeof index != 'number') {
-		return new (primitive.isType(type) ? type.array : BufferViewArray(type, sizeof(type)))(
-			instance.buffer,
-			instance.byteOffset + member.offset,
-			length * sizeof(type)
-		);
-	}
-
-	const offset = member.offset + (index ?? 0) * sizeof(type);
-
-	if (isStatic(type)) return new type(instance.buffer, offset, sizeof(type));
-
-	const view = new DataView(instance.buffer, instance.byteOffset, instance.byteLength);
-	return type.get(view, offset, member.littleEndian);
-}
-
-// Decorator utility types
-type Target<V> = ClassAccessorDecoratorTarget<any, V>;
-type Result<V> = ClassAccessorDecoratorResult<any, V>;
-type Context<V> = ClassAccessorDecoratorContext<any, V> & DecoratorContext;
-type Decorator<V> = (value: Target<V>, context: Context<V>) => Result<V>;
-
-function _member<T extends primitive.Valid>(typeName: T) {
-	const type = primitive.types[primitive.normalize(typeName)];
-
-	function _structMemberDecorator<V>(length: number | string): Decorator<V>;
-	function _structMemberDecorator<V>(value: Target<V>, context: Context<V>): Result<V>;
-	function _structMemberDecorator<V>(
-		valueOrLength: Target<V> | number | string,
-		context?: Context<V>
-	): Decorator<V> | Result<V> {
-		return typeof valueOrLength == 'number' || typeof valueOrLength == 'string'
-			? member<V>(type, { length: valueOrLength, typeName })
-			: member<V>(type, { typeName })(valueOrLength, context!);
-	}
-
-	return _structMemberDecorator;
-}
-
-/**
- * Shortcut types
- *
- * Instead of writing `@member(type)` you can write `@types.type`, or `@types.type(length)` for arrays
- */
-export const types = Object.fromEntries(primitive.validNames.map(t => [t, _member(t)])) as {
-	[K in primitive.Valid]: ReturnType<typeof _member<K>>;
-};

package/src/types.ts

@@ -1,277 +0,0 @@
-/**
- * Expands the type T (for intellisense and debugging)
- * @see https://stackoverflow.com/a/69288824/17637456
- */
-export type Expand<T> = T extends (...args: infer A) => infer R
-	? (...args: Expand<A>) => Expand<R>
-	: T extends infer O
-		? { [K in keyof O]: O[K] }
-		: never;
-
-/**
- * Recursivly expands the type T (for intellisense and debugging)
- * @see https://stackoverflow.com/a/69288824/17637456
- */
-export type ExpandRecursively<T> = T extends (...args: infer A) => infer R
-	? (...args: ExpandRecursively<A>) => ExpandRecursively<R>
-	: T extends object
-		? T extends infer O
-			? { [K in keyof O]: ExpandRecursively<O[K]> }
-			: never
-		: T;
-
-/**
- * Extracts an object with properties assignable to P from an object T
- * @see https://stackoverflow.com/a/71532723/17637456
- */
-export type ExtractProperties<T, P> = {
-	[K in keyof T as T[K] extends infer Prop ? (Prop extends P ? K : never) : never]: T[K];
-};
-
-/**
- * Extract the keys of T which are required
- * @see https://stackoverflow.com/a/55247867/17637456
- */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export type RequiredKeys<T> = { [K in keyof T]-?: {} extends { [P in K]: T[K] } ? never : K }[keyof T];
-
-/**
- * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
- */
-export type RequiredProperties<T extends object, K extends keyof T = keyof T> = Omit<T, K> & Required<Pick<T, K>>;
-
-/**
- * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
- */
-export type DeepRequired<T> = {
-	[K in keyof T]: Required<DeepRequired<T[K]>>;
-};
-
-/**
- * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
- */
-export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<T>;
-
-/**
- * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
- */
-export type NestedKeys<T extends object> = {
-	[P in keyof T & (string | number)]: T[P] extends Date
-		? `${P}`
-		: T[P] extends Record<string, unknown>
-			? `${P}` | `${P}.${NestedKeys<T[P]>}`
-			: `${P}`;
-}[keyof T & (string | number)];
-
-/**
- * @see https://dev.to/tmhao2005/ts-useful-advanced-types-3k5e
- */
-export type PartialRecursive<T> = {
-	[P in keyof T]?: T[P] extends (infer U)[]
-		? PartialRecursive<U>[]
-		: T[P] extends object | undefined
-			? PartialRecursive<T[P]>
-			: T[P];
-};
-
-/**
- * Get the keys of a union of objects
- * @see https://stackoverflow.com/a/65805753/17637456
- */
-export type UnionKeys<T> = T extends T ? keyof T : never;
-
-type StrictUnionHelper<T, TAll> = T extends unknown
-	? T & Partial<Record<Exclude<UnionKeys<TAll>, keyof T>, never>>
-	: never;
-
-/**
- * @see https://stackoverflow.com/a/65805753/17637456
- */
-export type StrictUnion<T> = Expand<StrictUnionHelper<T, T>>;
-
-// Tuple and array manipulation
-
-/**
- * Empty
- */
-export type Empty = [];
-
-/**
- * Removes the first element of T and shifts
- */
-export type Shift<T extends unknown[]> = T extends [unknown, ...infer Rest] ? Rest : never;
-
-/**
- * Gets the first element of T
- */
-export type First<T extends unknown[]> = T extends [infer F, ...unknown[]] ? F : never;
-
-/**
- * Inserts V into T at the start of T
- */
-export type Unshift<T extends unknown[], V> = [V, ...T];
-
-/**
- * Removes the last element of T
- */
-export type Pop<T extends unknown[]> = T extends [...infer _, unknown] ? _ : never;
-
-/**
- * Gets the last element of T
- */
-export type Last<T extends unknown[]> = T extends [...unknown[], infer Last] ? Last : never;
-
-/**
- * Appends V to T
- */
-export type Push<T extends unknown[], V> = [...T, V];
-
-/**
- * Concats A and B
- */
-export type Concat<A extends unknown[], B extends unknown[]> = Empty extends B ? A : Concat<Unshift<A, 0>, Shift<B>>;
-
-/**
- * Extracts from A what is not B
- *
- * @remarks
- * It does not remove duplicates (so Remove\<[0, 0, 0], [0, 0]\> yields [0]). This is intended and necessary behavior.
- */
-export type Remove<A extends unknown[], B extends unknown[]> = Empty extends B ? A : Remove<Shift<A>, Shift<B>>;
-
-/**
- * The length of T
- */
-export type Length<T extends { length: number }> = T['length'];
-
-type _FromLength<N extends number, R extends unknown[] = Empty> =
-	Length<R> extends N ? R : _FromLength<N, Unshift<R, 0>>;
-
-/**
- * Creates a tuple of length N
- */
-export type FromLength<N extends number> = _FromLength<N>;
-
-// compile-time math
-
-/**
- * Increments N
- */
-export type Increment<N extends number> = Length<Unshift<_FromLength<N>, 0>>;
-
-/**
- * Decrements N
- */
-export type Decrement<N extends number> = Length<Shift<_FromLength<N>>>;
-
-/**
- * Gets the sum of A and B
- */
-export type Add<A extends number, B extends number> = Length<Concat<_FromLength<A>, _FromLength<B>>>;
-
-/**
- * Subtracts B from A
- */
-export type Subtract<A extends number, B extends number> = Length<Remove<_FromLength<A>, _FromLength<B>>>;
-
-/**
- * Gets the type of an array's members
- */
-export type Member<T, D = null> = D extends 0
-	? T
-	: T extends (infer U)[]
-		? Member<U, D extends number ? Decrement<D> : null>
-		: T;
-
-/**
- * Flattens an array
- */
-export type FlattenArray<A extends unknown[], D = null> = A extends (infer U)[]
-	? Member<Exclude<U, A>, D>[]
-	: A extends unknown[]
-		? { [K in keyof A]: Member<A[K], D> }
-		: A;
-
-/**
- * Whether T is a tuple
- */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export type IsTuple<T> = T extends [] ? false : T extends [infer _Head, ...infer _Rest] ? true : false;
-
-/**
- * Flattens a tuple
- */
-export type FlattenTuple<A extends unknown[]> = A extends [infer U, ...infer Rest]
-	? U extends unknown[]
-		? [...U, ...FlattenTuple<Rest>]
-		: [U, ...FlattenTuple<Rest>]
-	: [];
-
-/**
- * Flattens an array or tuple
- */
-export type Flatten<A extends unknown[]> = IsTuple<A> extends true ? FlattenTuple<A> : FlattenArray<A>;
-
-type _Tuple<T, N extends number, R extends unknown[] = Empty> = R['length'] extends N ? R : _Tuple<T, N, [T, ...R]>;
-
-/**
- * Creates a tuple of T with length N
- */
-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 = any> = abstract new (...args: any[]) => Instance;
-
-export type Concrete<T extends ClassLike> = Pick<T, keyof T> & (new (...args: any[]) => InstanceType<T>);
-
-/**
- * Converts a union to an intersection
- * @see https://stackoverflow.com/a/55128956/17637456
- */
-export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
-
-/**
- * Gets the last element of a union
- * @see https://stackoverflow.com/a/55128956/17637456
- */
-export type LastOfUnion<T> = UnionToIntersection<T extends any ? () => T : never> extends () => infer R ? R : never;
-
-/**
- * Converts a union to a tuple
- * @see https://stackoverflow.com/a/55128956/17637456
- */
-export type UnionToTuple<T, L = LastOfUnion<T>, N = [T] extends [never] ? true : false> = true extends N
-	? []
-	: Push<UnionToTuple<Exclude<T, L>>, L>;
-
-/**
- * Makes properties with keys assignable to K in T required
- * @see https://stackoverflow.com/a/69328045/17637456
- */
-export type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] };
-
-/**
- * Makes properties with keys assignable to K in T optional
- */
-export type WithOptional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
-
-/**
- * Nothing in T
- */
-export type Never<T> = { [K in keyof T]?: never };
-
-/**
- * All of the properties in T or none of them
- */
-export type AllOrNone<T> = T | Never<T>;

package/src/version.ts

@@ -1,54 +0,0 @@
-import { capitalize } from './string.js';
-
-export type Sep = '_' | '-';
-
-export type Part = `${number}.${number}.${number}`;
-
-export type WithPre = `${Part}${Sep}${string}${Sep | '.'}${Part | number}`;
-
-export type Full = Part | WithPre;
-
-type Type<S extends string, Acc extends string = ''> = S extends `${infer First}${infer Rest}`
-	? First extends Sep | '.'
-		? Acc
-		: Type<Rest, `${Acc}${First}`>
-	: Acc;
-
-export type Parse<T extends Full, StripCore extends boolean> = T extends `${infer Core}${Sep}${infer Rest}`
-	? Rest extends `${infer U}`
-		? {
-				full: T;
-				core: Core;
-				type: Type<U>;
-				pre: U extends `${Type<U>}${Sep | '.'}${infer Pre}` ? Pre : '';
-				display: `${StripCore extends true
-					? Core extends '1.0.0'
-						? ''
-						: `${Core} `
-					: `${Core} `}${Capitalize<Type<U>>}${U extends `${Type<U>}${Sep | '.'}${infer Pre}` ? ` ${Pre}` : ''}`;
-			}
-		: never
-	: T extends Part
-		? {
-				full: T;
-				core: T;
-				display: T;
-			}
-		: never;
-
-export const regex = /^(?<core>\d+\.\d+\.\d+)(?:[-_](?<type>[^-_.]+)[-_.](?<pre>\d*(?:\.\d+)*))?/;
-
-/**
- * Parses a semver version, including compile-time results
- * @param full the full version to parse
- * @param stripCore Whether to strip the leading core version in the display version when the core version is 1.0.0 (default false)
- */
-export function parse<const T extends Full>(full: T): Parse<T, false>;
-export function parse<const T extends Full, const S extends boolean>(full: T, stripCore: S): Parse<T, S>;
-export function parse<const T extends Full, const S extends boolean>(full: T, stripCore?: S): Parse<T, S> {
-	const { type, pre, core } = regex.exec(full)!.groups!;
-	const display = type
-		? `${stripCore && core == '1.0.0' ? '' : core + ' '}${capitalize(type)}${pre ? ` ${pre}` : ''}`
-		: core;
-	return { full, core, pre, type, display } as Parse<T, S>;
-}

package/tsconfig.json

@@ -1,21 +0,0 @@
-{
-	"compilerOptions": {
-		"lib": ["ESNext"],
-		"module": "NodeNext",
-		"target": "ES2022",
-		"moduleResolution": "NodeNext",
-		"outDir": "dist",
-		"typeRoots": ["node_modules/@types"],
-		"resolveJsonModule": true,
-		"esModuleInterop": true,
-		"noImplicitThis": true,
-		"declaration": true,
-		"strict": true
-	},
-	"typedocOptions": {
-		"entryPoints": ["src/index.ts"],
-		"out": "docs"
-	},
-	"include": ["./src/**/*.ts"],
-	"exclude": ["node_modules"]
-}