@sapphire/string-store 1.0.0

package/dist/esm/index.d.mts

@@ -0,0 +1,630 @@
+/**
+ * A pointer to a position in a buffer.
+ *
+ * This is used to keep track of the current position in a buffer while allowing
+ * the position to be updated by multiple different functions.
+ *
+ * @privateRemarks
+ *
+ * This class draws inspiration from the following constructs:
+ * - `int*` in C/C++
+ * - `ref int` in C#
+ * - `*mut i32` in Rust
+ */
+declare class Pointer {
+    #private;
+    get value(): number;
+    add(value: number): this;
+    static from(pointer: PointerLike): Pointer;
+}
+type PointerLike = Pointer | {
+    valueOf(): number;
+} | {
+    [Symbol.toPrimitive](hint: 'number'): number;
+};
+
+declare class UnalignedUint16Array {
+    #private;
+    constructor(maxLength: number);
+    get maxLength(): number;
+    get maxBitLength(): number;
+    get length(): number;
+    get bitLength(): number;
+    writeBit(value: number): void;
+    writeInt2(value: number): void;
+    writeInt4(value: number): void;
+    writeInt8(value: number): void;
+    writeInt16(value: number): void;
+    writeInt32(value: number): void;
+    writeInt64(value: number): void;
+    writeBigInt32(value: bigint): void;
+    writeBigInt64(value: bigint): void;
+    writeFloat32(value: number): void;
+    writeFloat64(value: number): void;
+    readBit(offset: PointerLike): 0 | 1;
+    readInt2(offset: PointerLike): number;
+    readUint2(offset: PointerLike): number;
+    readInt4(offset: PointerLike): number;
+    readUint4(offset: PointerLike): number;
+    readInt8(offset: PointerLike): number;
+    readUint8(offset: PointerLike): number;
+    readInt16(offset: PointerLike): number;
+    readUint16(offset: PointerLike): number;
+    readInt32(offset: PointerLike): number;
+    readUint32(offset: PointerLike): number;
+    readInt64(offset: PointerLike): number;
+    readUint64(offset: PointerLike): number;
+    readBigInt32(offset: PointerLike): bigint;
+    readBigUint32(offset: PointerLike): bigint;
+    readBigInt64(offset: PointerLike): bigint;
+    readBigUint64(offset: PointerLike): bigint;
+    readFloat32(offset: PointerLike): number;
+    readFloat64(offset: PointerLike): number;
+    toString(): string;
+    toArray(): Uint16Array;
+    static from(value: string | UnalignedUint16Array): UnalignedUint16Array;
+}
+
+interface IType<ValueType, BitSize extends number | null> {
+    /**
+     * Serialize a value to a buffer.
+     *
+     * @param buffer The buffer to write to
+     * @param value The value to write
+     */
+    serialize(buffer: UnalignedUint16Array, value: Readonly<ValueType>): void;
+    /**
+     * Deserialize a value from a buffer.
+     *
+     * @param buffer The buffer to read from
+     * @param pointer The pointer indicating the current position in the buffer
+     */
+    deserialize(buffer: UnalignedUint16Array, pointer: Pointer): ValueType;
+    /**
+     * The size of the value in bits, or `null` if the size is variable.
+     */
+    readonly BIT_SIZE: BitSize;
+}
+
+declare function ArrayType<ValueType, ValueBitSize extends number | null>(type: IType<ValueType, ValueBitSize>): IType<ValueType[], null>;
+
+declare const BigInt32Type: IType<bigint, 32>;
+
+declare const BigInt64Type: IType<bigint, 64>;
+
+declare const BigUint32Type: IType<bigint, 32>;
+
+declare const BigUint64Type: IType<bigint, 64>;
+
+declare const BitType: IType<number, 1>;
+
+declare const BooleanType: IType<boolean, 1>;
+
+declare function FixedLengthArrayType<ValueType, ValueBitSize extends number | null>(type: IType<ValueType, ValueBitSize>, length: number): IType<ValueType[], ValueBitSize extends null ? null : number>;
+
+declare const Float32Type: IType<number, 32>;
+
+declare const Float64Type: IType<number, 64>;
+
+declare const Int16Type: IType<number, 16>;
+
+declare const Int2Type: IType<number, 2>;
+
+declare const Int32Type: IType<number, 32>;
+
+declare const Int4Type: IType<number, 4>;
+
+declare const Int64Type: IType<number, 64>;
+
+declare const Int8Type: IType<number, 8>;
+
+declare const SnowflakeType: {
+    readonly serialize: (buffer: UnalignedUint16Array, value: bigint | string) => void;
+    readonly deserialize: (buffer: UnalignedUint16Array, offset: Pointer) => bigint;
+    readonly BIT_SIZE: 64;
+};
+
+declare const StringType: IType<string, null>;
+
+declare const Uint16Type: IType<number, 16>;
+
+declare const Uint2Type: IType<number, 2>;
+
+declare const Uint32Type: IType<number, 32>;
+
+declare const Uint4Type: IType<number, 4>;
+
+declare const Uint64Type: IType<number, 64>;
+
+declare const Uint8Type: IType<number, 8>;
+
+declare const t: {
+    array: typeof ArrayType;
+    bigInt32: IType<bigint, 32>;
+    bigInt64: IType<bigint, 64>;
+    bigUint32: IType<bigint, 32>;
+    bigUint64: IType<bigint, 64>;
+    bit: IType<number, 1>;
+    boolean: IType<boolean, 1>;
+    fixedLengthArray: typeof FixedLengthArrayType;
+    float32: IType<number, 32>;
+    float64: IType<number, 64>;
+    int16: IType<number, 16>;
+    int2: IType<number, 2>;
+    int32: IType<number, 32>;
+    int4: IType<number, 4>;
+    int64: IType<number, 64>;
+    int8: IType<number, 8>;
+    snowflake: {
+        readonly serialize: (buffer: UnalignedUint16Array, value: string | bigint) => void;
+        readonly deserialize: (buffer: UnalignedUint16Array, offset: Pointer) => bigint;
+        readonly BIT_SIZE: 64;
+    };
+    string: IType<string, null>;
+    uint16: IType<number, 16>;
+    uint2: IType<number, 2>;
+    uint32: IType<number, 32>;
+    uint4: IType<number, 4>;
+    uint64: IType<number, 64>;
+    uint8: IType<number, 8>;
+};
+
+declare class Schema<Id extends number = number, Entries extends object = object> {
+    #private;
+    /**
+     * Creates a new schema.
+     *
+     * @param id The id of the schema
+     */
+    constructor(id: Id);
+    /**
+     * The id of the schema.
+     */
+    get id(): Id;
+    /**
+     * The total bit size of the schema.
+     *
+     * @remarks
+     *
+     * If any of the entries have a bit size of `null`, the bit size of the
+     * schema will also be `null`.
+     */
+    get bitSize(): number | null;
+    /**
+     * Get a property from the schema.
+     *
+     * @param name The name of the property
+     * @returns The specified property
+     *
+     * @remarks
+     *
+     * If the property does not exist, an error will be thrown.
+     */
+    get<const Name extends keyof Entries & string>(name: Name): Entries[Name];
+    /**
+     * Serialize a value into a buffer.
+     *
+     * @param buffer The buffer to serialize
+     * @param value The value to serialize into the buffer
+     *
+     * @remarks
+     *
+     * The schema's ID is written to the buffer first, followed by each property
+     * in the schema.
+     */
+    serialize(buffer: UnalignedUint16Array, value: Readonly<UnwrapSchemaEntries<Entries>>): void;
+    /**
+     * Deserialize a value from a buffer.
+     *
+     * @param buffer The buffer to deserialize
+     * @param pointer The pointer to where the buffer should be read from
+     * @returns The deserialized value
+     *
+     * @remarks
+     *
+     * Unlike {@link Schema.serialize}, this method does not read the schema's ID
+     * from the buffer, that is reserved for the {@link SchemaStore}.
+     */
+    deserialize(buffer: UnalignedUint16Array, pointer: PointerLike): UnwrapSchemaEntries<Entries>;
+    /**
+     * Adds an array property to the schema.
+     *
+     * @seealso {@link Schema.fixedLengthArray} for a fixed length array
+     *
+     * @param name The name of the property
+     * @param type The type of the entry in the array
+     * @returns The modified schema
+     */
+    array<const Name extends string, const ValueType, const ValueBitSize extends number | null>(name: Name, type: IType<ValueType, ValueBitSize>): Merge$1<Id, Entries, Name, IType<ValueType[], null>>;
+    /**
+     * Adds a fixed length array property to the schema.
+     *
+     * @seealso {@link Schema.array} for a dynamic length array
+     *
+     * @param name The name of the property
+     * @param type The type of the entry in the array
+     * @param length The length of the array
+     * @returns The modified schema
+     */
+    fixedLengthArray<const Name extends string, const ValueType, const ValueBitSize extends number | null>(name: Name, type: IType<ValueType, ValueBitSize>, length: number): Merge$1<Id, Entries, Name, IType<ValueType[], ValueBitSize extends null ? null : number>>;
+    /**
+     * Adds a string property to the schema.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    string<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<string, null>>;
+    /**
+     * Adds a boolean property to the schema.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    boolean<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<boolean, 1>>;
+    /**
+     * Adds a bit property to the schema.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    bit<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 1>>;
+    /**
+     * Adds a 2-bit integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from -2 to 1, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    int2<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 2>>;
+    /**
+     * Adds a 2-bit unsigned integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from 0 to 3, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    uint2<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 2>>;
+    /**
+     * Adds a 4-bit integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from -8 to 7, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    int4<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 4>>;
+    /**
+     * Adds a 4-bit unsigned integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from 0 to 15, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    uint4<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 4>>;
+    /**
+     * Adds a 8-bit integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from -128 to 127, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    int8<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 8>>;
+    /**
+     * Adds a 8-bit unsigned integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from 0 to 255, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    uint8<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 8>>;
+    /**
+     * Adds a 16-bit integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from -32768 to 32767, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    int16<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 16>>;
+    /**
+     * Adds a 16-bit unsigned integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from 0 to 65535, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    uint16<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 16>>;
+    /**
+     * Adds a 32-bit integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from -2_147_483_648 to 2_147_483_647, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    int32<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 32>>;
+    /**
+     * Adds a 32-bit unsigned integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from 0 to 4_294_967_295, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    uint32<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 32>>;
+    /**
+     * Adds a 64-bit integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from -9_223_372_036_854_775_808 to 9_223_372_036_854_775_807, inclusive.
+     *
+     * However, it may run into precision issues past the range of `-9_007_199_254_740_991` to `9_007_199_254_740_991`
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    int64<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 64>>;
+    /**
+     * Adds a 64-bit unsigned integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from 0 to 18_446_744_073_709_551_615, inclusive.
+     *
+     * However, it may run into precision issues past `9_007_199_254_740_991`
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    uint64<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 64>>;
+    /**
+     * Adds a 32-bit big integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from -2_147_483_648n to 2_147_483_647n, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    bigInt32<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<bigint, 32>>;
+    /**
+     * Adds a 32-bit big integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from 0n to 4_294_967_295n, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    bigUint32<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<bigint, 32>>;
+    /**
+     * Adds a 64-bit big integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from -9_223_372_036_854_775_808n to 9_223_372_036_854_775_807n, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    bigInt64<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<bigint, 64>>;
+    /**
+     * Adds a 64-bit big integer property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from 0n to 18_446_744_073_709_551_615n, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    bigUint64<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<bigint, 64>>;
+    /**
+     * Adds a 32-bit floating point number property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from -3.4028234663852886e+38 to 3.4028234663852886e+38, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    float32<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 32>>;
+    /**
+     * Adds a 64-bit floating point number property to the schema.
+     *
+     * @remarks
+     *
+     * The range of values is from -1.7976931348623157e+308 to 1.7976931348623157e+308, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    float64<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<number, 64>>;
+    /**
+     * Adds a 64-bit big integer property to the schema, similar to {@link Schema.bigUint64}.
+     *
+     * @remarks
+     *
+     * The range of values is from 0n to 18_446_744_073_709_551_615n, inclusive.
+     *
+     * @param name The name of the property
+     * @returns The modified schema
+     */
+    snowflake<const Name extends string>(name: Name): Merge$1<Id, Entries, Name, IType<bigint, 64>>;
+    /**
+     * Iterates over the schema's property names.
+     *
+     * @returns An iterator for the schema's property names
+     */
+    keys(): IterableIterator<KeyOfSchema<this>>;
+    /**
+     * Iterates over the schema's property values
+     *
+     * @returns An iterator for the schema's property values
+     */
+    values(): IterableIterator<ValueOfSchema<this>>;
+    /**
+     * Iterates over the schema's property entries
+     *
+     * @returns An iterator for the schema's property entries
+     */
+    entries(): IterableIterator<EntryOfSchema<this>>;
+    /**
+     * Iterates over the schema's property entries
+     *
+     * @returns An iterator for the schema's property entries
+     */
+    [Symbol.iterator](): IterableIterator<EntryOfSchema<this>>;
+}
+type Merge$1<Id extends number, Entries extends object, EntryName extends string, EntryType extends IType<any, number | null>> = EntryName extends keyof Entries ? never : Schema<Id, {
+    [K in EntryName | keyof Entries]: K extends keyof Entries ? Entries[K] : EntryType;
+}>;
+type KeyOfSchema<SchemaValue extends object> = SchemaValue extends Schema<infer _, infer Type> ? keyof Type & string : never;
+type ValueOfSchema<SchemaValue extends object> = SchemaValue extends Schema<infer _, infer Type> ? {
+    [K in keyof Type]: Type[K];
+}[keyof Type] : never;
+type EntryOfSchema<SchemaValue extends object> = SchemaValue extends Schema<infer _, infer Type> ? {
+    [K in keyof Type]: readonly [K, Type[K]];
+}[keyof Type] : never;
+type UnwrapSchemaType<Type extends object> = Type extends IType<infer T, infer _> ? T : never;
+type UnwrapSchemaEntries<Entries extends object> = {
+    [K in keyof Entries]: UnwrapSchemaType<Entries[K] & object>;
+} & object;
+type UnwrapSchema<SchemaValue extends object> = SchemaValue extends Schema<infer _, infer Type> ? UnwrapSchemaEntries<Type> : never;
+
+declare class SchemaStore<Entries extends object = object> {
+    #private;
+    /**
+     * The default maximum array length for schemas
+     */
+    defaultMaximumArrayLength: number;
+    /**
+     * Creates a new schema store
+     *
+     * @param defaultMaximumArrayLength The default maximum array length for schemas
+     */
+    constructor(defaultMaximumArrayLength?: number);
+    /**
+     * Adds a schema to the store
+     *
+     * @param schema The schema to add to the store
+     * @returns The modified store
+     *
+     * @remarks
+     *
+     * An error will be thrown if a schema with the same id already exists in the store.
+     */
+    add<const Id extends number, const SchemaType extends object>(schema: Schema<Id, SchemaType>): Merge<Entries, Id, typeof schema>;
+    /**
+     * Gets a schema from the store
+     *
+     * @param id The id of the schema to get
+     * @returns The schema with the given id
+     *
+     * @remarks
+     *
+     * An error will be thrown if a schema with the given id does not exist in the store.
+     */
+    get<const Id extends KeyOfStore<this>>(id: Id): Entries[Id];
+    /**
+     * Serializes a value using the schema with the given id
+     *
+     * @param id The id of the schema to use for serialization
+     * @param value The value to serialize
+     * @returns The serialized buffer
+     */
+    serialize<const Id extends KeyOfStore<this>>(id: Id, value: Readonly<UnwrapSchema<Entries[Id] & object>>): UnalignedUint16Array;
+    /**
+     * Deserializes a buffer
+     *
+     * @param buffer The buffer to deserialize
+     * @returns The resolved value, including the id of the schema used for deserialization
+     */
+    deserialize(buffer: string | UnalignedUint16Array): DeserializationResult<Entries>;
+    /**
+     * Iterates over the stores's schema identifiers.
+     *
+     * @returns An iterator for the stores's schema identifiers
+     */
+    keys(): IterableIterator<KeyOfStore<this>>;
+    /**
+     * Iterates over the stores's schemas.
+     *
+     * @returns An iterator for the stores's schemas
+     */
+    values(): IterableIterator<ValueOfStore<this>>;
+    /**
+     * Iterates over the stores's schema entries.
+     *
+     * @returns An iterator for the stores's schema entries
+     */
+    entries(): IterableIterator<EntryOfStore<this>>;
+    /**
+     * Iterates over the stores's schema entries.
+     *
+     * @returns An iterator for the stores's schema entries
+     */
+    [Symbol.iterator](): IterableIterator<EntryOfStore<this>>;
+}
+type Merge<Entries extends object, Id extends number, Type extends object> = Id extends keyof Entries ? never : SchemaStore<{
+    [K in Id | keyof Entries]: K extends keyof Entries ? Entries[K] : Type;
+}>;
+type KeyOfStore<SchemaStoreValue extends object> = SchemaStoreValue extends SchemaStore<infer Schemas> ? keyof Schemas & number : never;
+type ValueOfStore<SchemaStoreValue extends object> = SchemaStoreValue extends SchemaStore<infer Schemas> ? Schemas[keyof Schemas & number] : never;
+type EntryOfStore<SchemaStoreValue extends object> = SchemaStoreValue extends SchemaStore<infer Schemas> ? {
+    [K in keyof Schemas]: readonly [K & number, Schemas[K]];
+}[keyof Schemas] : never;
+type DeserializationResult<SchemaStoreEntries extends object> = {
+    [K in keyof SchemaStoreEntries]: {
+        id: K;
+        data: UnwrapSchema<SchemaStoreEntries[K] & object>;
+    };
+}[keyof SchemaStoreEntries];
+
+type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
+/**
+ * Converts a {@link TypedArray} to a string.
+ *
+ * @param buffer The buffer to convert
+ * @returns The generated UTF16 string
+ */
+declare function toUTF16(buffer: TypedArray): string;
+/**
+ * Converts a string to a {@link Uint16Array}.
+ *
+ * @param buffer The string to convert
+ * @returns The generated {@link Uint16Array}
+ */
+declare function fromUTF16(buffer: string): Uint16Array;
+
+export { ArrayType, BigInt32Type, BigInt64Type, BigUint32Type, BigUint64Type, BitType, BooleanType, type DeserializationResult, type EntryOfSchema, type EntryOfStore, FixedLengthArrayType, Float32Type, Float64Type, type IType, Int16Type, Int2Type, Int32Type, Int4Type, Int64Type, Int8Type, type KeyOfSchema, type KeyOfStore, Pointer, type PointerLike, Schema, SchemaStore, SnowflakeType, StringType, type TypedArray, Uint16Type, Uint2Type, Uint32Type, Uint4Type, Uint64Type, Uint8Type, UnalignedUint16Array, type UnwrapSchema, type UnwrapSchemaEntries, type UnwrapSchemaType, type ValueOfSchema, type ValueOfStore, fromUTF16, t, toUTF16 };