utilium 1.10.0 → 2.0.0-pre.1

package/src/buffer.ts

@@ -1,7 +1,10 @@
 /* eslint-disable @typescript-eslint/no-unused-expressions */
 
+import { _throw } from './misc.js';
+import type { Mutable } from './objects.js';
+
 /**
- * A generic ArrayBufferView (typed array) constructor
+ * A generic constructor for an `ArrayBufferView`
  */
 export interface ArrayBufferViewConstructor {
 	readonly prototype: ArrayBufferView<ArrayBufferLike>;
@@ -15,6 +18,274 @@ export interface ArrayBufferViewConstructor {
 	new (array: ArrayLike<number> | ArrayBuffer): ArrayBufferView<ArrayBuffer>;
 }
 
+/**
+ * A generic typed array.
+ */
+export interface TypedArray<TArrayBuffer extends ArrayBufferLike = ArrayBuffer, TValue = number | bigint>
+	extends ArrayBufferView<TArrayBuffer> {
+	/**
+	 * The size in bytes of each element in the array.
+	 */
+	readonly BYTES_PER_ELEMENT: number;
+
+	/**
+	 * Returns the this object after copying a section of the array identified by start and end
+	 * to the same array starting at position target
+	 * @param target If target is negative, it is treated as length+target where length is the
+	 * length of the array.
+	 * @param start If start is negative, it is treated as length+start. If end is negative, it
+	 * is treated as length+end.
+	 * @param end If not specified, length of the this object is used as its default value.
+	 */
+	copyWithin(target: number, start: number, end?: number): this;
+
+	/**
+	 * Determines whether all the members of an array satisfy the specified test.
+	 * @param predicate A function that accepts up to three arguments. The every method calls
+	 * the predicate function for each element in the array until the predicate returns a value
+	 * which is coercible to the Boolean value false, or until the end of the array.
+	 * @param thisArg An object to which the this keyword can refer in the predicate function.
+	 * If thisArg is omitted, undefined is used as the this value.
+	 */
+	every(predicate: (value: TValue, index: number, array: this) => unknown, thisArg?: any): boolean;
+
+	/**
+	 * Changes all array elements from `start` to `end` index to a static `value` and returns the modified array
+	 * @param value value to fill array section with
+	 * @param start index to start filling the array at. If start is negative, it is treated as
+	 * length+start where length is the length of the array.
+	 * @param end index to stop filling the array at. If end is negative, it is treated as
+	 * length+end.
+	 */
+	fill(value: TValue, start?: number, end?: number): this;
+
+	/**
+	 * Returns the elements of an array that meet the condition specified in a callback function.
+	 * @param predicate A function that accepts up to three arguments. The filter method calls
+	 * the predicate function one time for each element in the array.
+	 * @param thisArg An object to which the this keyword can refer in the predicate function.
+	 * If thisArg is omitted, undefined is used as the this value.
+	 */
+	filter(
+		predicate: (value: TValue, index: number, array: this) => any,
+		thisArg?: any
+	): TypedArray<TArrayBuffer, TValue>;
+
+	/**
+	 * Returns the value of the first element in the array where predicate is true, and undefined
+	 * otherwise.
+	 * @param predicate find calls predicate once for each element of the array, in ascending
+	 * order, until it finds one where predicate returns true. If such an element is found, find
+	 * immediately returns that element value. Otherwise, find returns undefined.
+	 * @param thisArg If provided, it will be used as the this value for each invocation of
+	 * predicate. If it is not provided, undefined is used instead.
+	 */
+	find(predicate: (value: TValue, index: number, obj: this) => boolean, thisArg?: any): TValue | undefined;
+
+	/**
+	 * Returns the index of the first element in the array where predicate is true, and -1
+	 * otherwise.
+	 * @param predicate find calls predicate once for each element of the array, in ascending
+	 * order, until it finds one where predicate returns true. If such an element is found,
+	 * findIndex immediately returns that element index. Otherwise, findIndex returns -1.
+	 * @param thisArg If provided, it will be used as the this value for each invocation of
+	 * predicate. If it is not provided, undefined is used instead.
+	 */
+	findIndex(predicate: (value: TValue, index: number, obj: this) => boolean, thisArg?: any): number;
+
+	/**
+	 * Performs the specified action for each element in an array.
+	 * @param callbackfn  A function that accepts up to three arguments. forEach calls the
+	 * callbackfn function one time for each element in the array.
+	 * @param thisArg  An object to which the this keyword can refer in the callbackfn function.
+	 * If thisArg is omitted, undefined is used as the this value.
+	 */
+	forEach(callbackfn: (value: TValue, index: number, array: this) => void, thisArg?: any): void;
+
+	/**
+	 * Returns the index of the first occurrence of a value in an array.
+	 * @param searchElement The value to locate in the array.
+	 * @param fromIndex The array index at which to begin the search. If fromIndex is omitted, the
+	 *  search starts at index 0.
+	 */
+	indexOf(searchElement: TValue, fromIndex?: number): number;
+
+	/**
+	 * Adds all the elements of an array separated by the specified separator string.
+	 * @param separator A string used to separate one element of an array from the next in the
+	 * resulting String. If omitted, the array elements are separated with a comma.
+	 */
+	join(separator?: string): string;
+
+	/**
+	 * Returns the index of the last occurrence of a value in an array.
+	 * @param searchElement The value to locate in the array.
+	 * @param fromIndex The array index at which to begin the search. If fromIndex is omitted, the
+	 * search starts at index 0.
+	 */
+	lastIndexOf(searchElement: TValue, fromIndex?: number): number;
+
+	/**
+	 * The length of the array.
+	 */
+	readonly length: number;
+
+	/**
+	 * Calls a defined callback function on each element of an array, and returns an array that
+	 * contains the results.
+	 * @param callbackfn A function that accepts up to three arguments. The map method calls the
+	 * callbackfn function one time for each element in the array.
+	 * @param thisArg An object to which the this keyword can refer in the callbackfn function.
+	 * If thisArg is omitted, undefined is used as the this value.
+	 */
+	map(
+		callbackfn: (value: TValue, index: number, array: this) => TValue,
+		thisArg?: any
+	): TypedArray<TArrayBuffer, TValue>;
+
+	/**
+	 * Calls the specified callback function for all the elements in an array. The return value of
+	 * the callback function is the accumulated result, and is provided as an argument in the next
+	 * call to the callback function.
+	 * @param callbackfn A function that accepts up to four arguments. The reduce method calls the
+	 * callbackfn function one time for each element in the array.
+	 * @param initialValue If initialValue is specified, it is used as the initial value to start
+	 * the accumulation. The first call to the callbackfn function provides this value as an argument
+	 * instead of an array value.
+	 */
+	reduce(
+		callbackfn: (previousValue: TValue, currentValue: TValue, currentIndex: number, array: this) => number
+	): number;
+	reduce(
+		callbackfn: (previousValue: TValue, currentValue: TValue, currentIndex: number, array: this) => number,
+		initialValue: number
+	): number;
+
+	/**
+	 * Calls the specified callback function for all the elements in an array. The return value of
+	 * the callback function is the accumulated result, and is provided as an argument in the next
+	 * call to the callback function.
+	 * @param callbackfn A function that accepts up to four arguments. The reduce method calls the
+	 * callbackfn function one time for each element in the array.
+	 * @param initialValue If initialValue is specified, it is used as the initial value to start
+	 * the accumulation. The first call to the callbackfn function provides this value as an argument
+	 * instead of an array value.
+	 */
+	reduce<U>(
+		callbackfn: (previousValue: U, currentValue: TValue, currentIndex: number, array: this) => U,
+		initialValue: U
+	): U;
+
+	/**
+	 * Calls the specified callback function for all the elements in an array, in descending order.
+	 * The return value of the callback function is the accumulated result, and is provided as an
+	 * argument in the next call to the callback function.
+	 * @param callbackfn A function that accepts up to four arguments. The reduceRight method calls
+	 * the callbackfn function one time for each element in the array.
+	 * @param initialValue If initialValue is specified, it is used as the initial value to start
+	 * the accumulation. The first call to the callbackfn function provides this value as an
+	 * argument instead of an array value.
+	 */
+	reduceRight(
+		callbackfn: (previousValue: TValue, currentValue: TValue, currentIndex: number, array: this) => number
+	): number;
+	reduceRight(
+		callbackfn: (previousValue: TValue, currentValue: TValue, currentIndex: number, array: this) => number,
+		initialValue: number
+	): number;
+
+	/**
+	 * Calls the specified callback function for all the elements in an array, in descending order.
+	 * The return value of the callback function is the accumulated result, and is provided as an
+	 * argument in the next call to the callback function.
+	 * @param callbackfn A function that accepts up to four arguments. The reduceRight method calls
+	 * the callbackfn function one time for each element in the array.
+	 * @param initialValue If initialValue is specified, it is used as the initial value to start
+	 * the accumulation. The first call to the callbackfn function provides this value as an argument
+	 * instead of an array value.
+	 */
+	reduceRight<U>(
+		callbackfn: (previousValue: U, currentValue: TValue, currentIndex: TValue, array: this) => U,
+		initialValue: U
+	): U;
+
+	/**
+	 * Reverses the elements in an Array.
+	 */
+	reverse(): this;
+
+	/**
+	 * Sets a value or an array of values.
+	 * @param array A typed or untyped array of values to set.
+	 * @param offset The index in the current array at which the values are to be written.
+	 */
+	set(array: ArrayLike<TValue>, offset?: number): void;
+
+	/**
+	 * Returns a section of an array.
+	 * @param start The beginning of the specified portion of the array.
+	 * @param end The end of the specified portion of the array. This is exclusive of the element at the index 'end'.
+	 */
+	slice(start?: number, end?: number): TypedArray<TArrayBuffer, TValue>;
+
+	/**
+	 * Determines whether the specified callback function returns true for any element of an array.
+	 * @param predicate A function that accepts up to three arguments. The some method calls
+	 * the predicate function for each element in the array until the predicate returns a value
+	 * which is coercible to the Boolean value true, or until the end of the array.
+	 * @param thisArg An object to which the this keyword can refer in the predicate function.
+	 * If thisArg is omitted, undefined is used as the this value.
+	 */
+	some(predicate: (value: TValue, index: number, array: this) => unknown, thisArg?: any): boolean;
+
+	/**
+	 * Sorts an array.
+	 * @param compareFn Function used to determine the order of the elements. It is expected to return
+	 * a negative value if first argument is less than second argument, zero if they're equal and a positive
+	 * value otherwise. If omitted, the elements are sorted in ascending order.
+	 * ```ts
+	 * [11,2,22,1].sort((a, b) => a - b)
+	 * ```
+	 */
+	sort(compareFn?: (a: TValue, b: TValue) => number): this;
+
+	/**
+	 * Gets a new Int8Array view of the ArrayBuffer store for this array, referencing the elements
+	 * at begin, inclusive, up to end, exclusive.
+	 * @param begin The index of the beginning of the array.
+	 * @param end The index of the end of the array.
+	 */
+	subarray(begin?: number, end?: number): TypedArray<TArrayBuffer, TValue>;
+
+	/**
+	 * Converts a number to a string by using the current locale.
+	 */
+	toLocaleString(): string;
+
+	/**
+	 * Returns a string representation of an array.
+	 */
+	toString(): string;
+
+	/** Returns the primitive value of the specified object. */
+	valueOf(): this;
+
+	[index: number]: TValue;
+}
+
+export interface TypedArrayConstructor {
+	readonly prototype: TypedArray<ArrayBufferLike>;
+	new (length: number): TypedArray<ArrayBuffer>;
+	new (array: ArrayLike<number>): TypedArray<ArrayBuffer>;
+	new <TArrayBuffer extends ArrayBufferLike = ArrayBuffer>(
+		buffer: TArrayBuffer,
+		byteOffset?: number,
+		length?: number
+	): TypedArray<TArrayBuffer>;
+	new (array: ArrayLike<number> | ArrayBuffer): TypedArray<ArrayBuffer>;
+	readonly BYTES_PER_ELEMENT: number;
+}
+
 /**
  * Grows a buffer if it isn't large enough
  * @returns The original buffer if resized successfully, or a newly created buffer
@@ -55,3 +326,94 @@ export function toUint8Array(buffer: ArrayBufferLike | ArrayBufferView): Uint8Ar
 	if (!ArrayBuffer.isView(buffer)) return new Uint8Array(buffer);
 	return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
 }
+
+export function initView<T extends ArrayBufferLike = ArrayBuffer>(
+	view: Mutable<ArrayBufferView<T> & { BYTES_PER_ELEMENT?: number }>,
+	buffer?: T | ArrayBufferView<T> | ArrayLike<number> | number,
+	byteOffset?: number,
+	byteLength?: number
+) {
+	if (typeof buffer == 'number') {
+		const per = view.BYTES_PER_ELEMENT ?? _throw('BYTES_PER_ELEMENT is not set');
+		view.buffer = new ArrayBuffer(buffer * per) as T;
+		view.byteOffset = 0;
+		view.byteLength = buffer * per;
+		return;
+	}
+
+	if (
+		!buffer
+		|| buffer instanceof ArrayBuffer
+		|| (globalThis.SharedArrayBuffer && buffer instanceof globalThis.SharedArrayBuffer)
+	) {
+		const { staticSize = 0 } = (view.constructor as any)?.[Symbol.metadata]?.struct ?? {};
+		view.buffer = buffer ?? (new ArrayBuffer(staticSize) as T);
+		view.byteOffset = byteOffset ?? 0;
+		view.byteLength = byteLength ?? staticSize;
+		return;
+	}
+
+	if (ArrayBuffer.isView(buffer)) {
+		view.buffer = buffer.buffer;
+		view.byteOffset = buffer.byteOffset;
+		view.byteLength = buffer.byteLength;
+		return;
+	}
+
+	const array = buffer as ArrayLike<number>;
+
+	view.buffer = new ArrayBuffer(array.length) as T;
+	view.byteOffset = 0;
+	view.byteLength = array.length;
+
+	const data = new Uint8Array(view.buffer);
+	for (let i = 0; i < array.length; i++) {
+		data[i] = array[i];
+	}
+}
+
+/** Creates a view of an array buffer */
+export class BufferView<T extends ArrayBufferLike = ArrayBufferLike> implements ArrayBufferView<T> {
+	declare public readonly buffer: T;
+	declare public readonly byteOffset: number;
+	declare public readonly byteLength: number;
+
+	public constructor(buffer?: T | ArrayBufferView<T> | ArrayLike<number>, byteOffset?: number, byteLength?: number) {
+		initView<T>(this, buffer, byteOffset, byteLength);
+	}
+}
+
+BufferView satisfies ArrayBufferViewConstructor;
+
+/** Creates an array of a buffer view type */
+export function BufferViewArray<T extends ArrayBufferViewConstructor>(element: T, size: number) {
+	return class BufferViewArray<TArrayBuffer extends ArrayBufferLike = ArrayBuffer> extends Array {
+		public readonly BYTES_PER_ELEMENT: number = size;
+
+		declare public readonly buffer: TArrayBuffer;
+		declare public readonly byteOffset: number;
+		declare public readonly byteLength: number;
+
+		public constructor(
+			buffer?: TArrayBuffer | ArrayBufferView<TArrayBuffer> | ArrayLike<number>,
+			byteOffset?: number,
+			byteLength?: number
+		) {
+			const t_size = size;
+
+			const length = (byteLength ?? t_size) / t_size;
+
+			if (!Number.isSafeInteger(length)) throw new Error('Invalid array length: ' + length);
+
+			super(length);
+
+			initView(this, buffer, byteOffset, byteLength);
+
+			for (let i = 0; i < length; i++) {
+				this[i] = new element(this.buffer, this.byteOffset + i * t_size, t_size);
+			}
+		}
+	};
+}
+
+BufferView satisfies ArrayBufferViewConstructor;

package/src/internal/primitives.ts

@@ -1,61 +1,135 @@
+import type { ArrayBufferViewConstructor } from '../buffer.js';
 import { capitalize } from '../string.js';
+import type { UnionToTuple } from '../types.js';
 
-type BitsToBytes = {
-	'8': 1;
-	'16': 2;
-	'32': 4;
-	'64': 8;
-	'128': 16;
-};
-
-export type Size<T extends string> = T extends `${'int' | 'uint' | 'float'}${infer bits}`
-	? bits extends keyof BitsToBytes
-		? BitsToBytes[bits]
-		: never
-	: never;
-
-export const typeNames = [
-	'int8',
-	'uint8',
-	'int16',
-	'uint16',
-	'int32',
-	'uint32',
-	'int64',
-	'uint64',
-	'int128',
-	'uint128',
-	'float32',
-	'float64',
-	'float128',
-] as const;
-
-export type Typename = (typeof typeNames)[number];
-
-export type Valid = Typename | Capitalize<Typename> | 'char';
+/** A definition for a primitive type */
+export interface Type<T = any> {
+	readonly name: string;
+	readonly size: number;
+	readonly array: ArrayBufferViewConstructor;
+	get(this: void, view: DataView, offset: number, littleEndian: boolean): T;
+	set(this: void, view: DataView, offset: number, littleEndian: boolean, value: T): void;
+}
 
-export const validNames = [...typeNames, ...typeNames.map(t => capitalize(t)), 'char'] satisfies Valid[];
+export function isType<T = any>(type: unknown): type is Type<T> {
+	return (
+		typeof type == 'object'
+		&& type != null
+		&& 'size' in type
+		&& 'get' in type
+		&& 'set' in type
+		&& typeof type.size == 'number'
+		&& typeof type.get == 'function'
+		&& typeof type.set == 'function'
+	);
+}
 
-export const regex = /^(u?int|float)(8|16|32|64|128)$/i;
+export const types = {
+	int8: {
+		name: 'int8',
+		size: 1,
+		array: Int8Array,
+		get: (view, offset) => view.getInt8(offset),
+		set: (view, offset, _le, value) => view.setInt8(offset, value),
+	},
 
-export type Normalize<T extends Valid> = T extends 'char' ? 'uint8' : Uncapitalize<T>;
+	uint8: {
+		name: 'uint8',
+		size: 1,
+		array: Uint8Array,
+		get: (view, offset) => view.getUint8(offset),
+		set: (view, offset, _le, value) => view.setUint8(offset, value),
+	},
 
-export function normalize<T extends Valid>(type: T): Normalize<T> {
-	return (type == 'char' ? 'uint8' : type.toLowerCase()) as Normalize<T>;
-}
+	int16: {
+		name: 'int16',
+		size: 2,
+		array: Int16Array,
+		get: (view, offset, le) => view.getInt16(offset, le),
+		set: (view, offset, le, value) => view.setInt16(offset, value, le),
+	},
+
+	uint16: {
+		name: 'uint16',
+		size: 2,
+		array: Uint16Array,
+		get: (view, offset, le) => view.getUint16(offset, le),
+		set: (view, offset, le, value) => view.setUint16(offset, value, le),
+	},
+
+	int32: {
+		name: 'int32',
+		size: 4,
+		array: Int32Array,
+		get: (view, offset, le) => view.getInt32(offset, le),
+		set: (view, offset, le, value) => view.setInt32(offset, value, le),
+	},
+
+	uint32: {
+		name: 'uint32',
+		size: 4,
+		array: Uint32Array,
+		get: (view, offset, le) => view.getUint32(offset, le),
+		set: (view, offset, le, value) => view.setUint32(offset, value, le),
+	},
+
+	int64: {
+		name: 'int64',
+		size: 8,
+		array: BigInt64Array,
+		get: (view, offset, le) => view.getBigInt64(offset, le),
+		set: (view, offset, le, value) => view.setBigInt64(offset, value, le),
+	},
+
+	uint64: {
+		name: 'uint64',
+		size: 8,
+		array: BigUint64Array,
+		get: (view, offset, le) => view.getBigUint64(offset, le),
+		set: (view, offset, le, value) => view.setBigUint64(offset, value, le),
+	},
+
+	float32: {
+		name: 'float32',
+		size: 4,
+		array: Float32Array,
+		get: (view, offset, le) => view.getFloat32(offset, le),
+		set: (view, offset, le, value) => view.setFloat32(offset, value, le),
+	},
 
-export function isType(type: { toString(): string }): type is Typename {
-	return regex.test(type.toString());
+	float64: {
+		name: 'float64',
+		size: 8,
+		array: Float64Array,
+		get: (view, offset, le) => view.getFloat64(offset, le),
+		set: (view, offset, le, value) => view.setFloat64(offset, value, le),
+	},
+} as const satisfies Record<string, Type>;
+
+export type TypeName = keyof typeof types;
+
+export const typeNames = Object.keys(types) as UnionToTuple<TypeName>;
+
+export function isTypeName(type: { toString(): string }): type is TypeName {
+	return typeNames.includes(type.toString() as TypeName);
 }
 
+export type Valid = TypeName | Capitalize<TypeName> | 'char';
+
+export const validNames = [...typeNames, ...typeNames.map(t => capitalize(t)), 'char'] satisfies Valid[];
+
 export function isValid(type: { toString(): string }): type is Valid {
-	return type == 'char' || regex.test(type.toString().toLowerCase());
+	return validNames.includes(type.toString() as Valid);
 }
 
 export function checkValid(type: { toString(): string }): asserts type is Valid {
-	if (!isValid(type)) {
-		throw new TypeError('Not a valid primitive type: ' + type);
-	}
+	if (!isValid(type)) throw new TypeError('Not a valid primitive type: ' + type);
+}
+
+export type Normalize<T extends Valid> = (T extends 'char' ? 'uint8' : Uncapitalize<T>) & TypeName;
+
+export function normalize<T extends Valid>(type: T): Normalize<T> {
+	return (type == 'char' ? 'uint8' : type.toLowerCase()) as Normalize<T>;
 }
 
-export const mask64 = BigInt('0xffffffffffffffff');
+export type Size<T extends Valid | Type> = (T extends Valid ? (typeof types)[Normalize<T>] : T)['size'];