@nativewrappers/common 0.0.49 → 0.0.51

package/Kvp.d.ts

@@ -1,91 +1,77 @@
-export declare class Kvp {
+interface Schema {
+    [key: string]: "string" | "number" | "float" | object;
+}
+export declare class Kvp<T extends Schema> {
+    private schema;
+    constructor(schema: T);
     /**
-     * Sets the resource key to the specified value this is a blocking operation, if you're doing large write operations you should use [[setKvpAsync]] instead.
-     * @param key the key string
-     * @param value the value to set the key to
+     * Returns the type associated with a schema key.
      */
-    setKvp<T = number | string>(key: string, value: T): void;
+    getType(key: keyof T): "string" | "number" | "float" | "object";
     /**
-     * Sets the resource key to the specified value, this doesn't immediately write to disk and needs [[flush]] called afterwards.
-     * @param key the key string
-     * @param value the value to set the key to
+     * Returns the value associated with a key as a number.
      */
-    setKvpAsync<T = number | string>(key: string, value: T): void;
+    getNumber(key: string): number;
     /**
-     * Sets the specified key to the specified json value
-     * This can error if given an invalid object
-     * @param key the key string
-     * @param value the value to set the key to
+     * Returns the value associated with a key as a float.
      */
-    setKvpJson(key: string, value: any): void;
+    getFloat(key: string): number;
     /**
-     * Gets the specified value for key
-     * @param key the key of the value to get
-     * @returns a string, or null if there is no value
+     * Returns the value associated with a key as a string.
      */
-    getKvpString(key: string): string | null;
+    getString(key: string): string | null;
     /**
-     * Gets the specified value for key
-     * @param key the key of the value to get
-     * @returns the value stored, as a number, or 0 if there is no value
+     * Returns the value associated with a key as a parsed JSON string.
      */
-    getKvpNumber(key: string): number;
+    getJson<T>(key: string): T | null;
     /**
-     * Gets the specified value for key
-     * @param key the key of the value to get
-     * @returns the value stored as a float, or 0.0 if there is no value
+     * Sets the value associated with a key as a number.
+     * @param async set the value using an async operation.
      */
-    getKvpFloat(key: string): number;
-    getKvpJson<T>(key: string): T;
+    setNumber(key: string, value: number, async?: boolean): void;
     /**
-     * Deletes the specified value for key, this is a blocking operation, if you're deleting a bunch of keys you should use [[deleteAsync]]
-     * @param key the key of the value to delete
+     * Sets the value associated with a key as a float.
+     * @param async set the value using an async operation.
      */
-    delete(key: string): void;
+    setFloat(key: string, value: number, async?: boolean): void;
     /**
-     * Deletes the specified resource keys value, this doesn't immediately write to disk and needs [[flush]] called afterwards.
-     * @param key the key to delete
+     * Sets the value associated with a key as a string.
+     * @param async set the value using an async operation.
      */
-    deleteAsync(key: string): void;
+    setString(key: string, value: string, async?: boolean): void;
     /**
-     * Ensures that any previous async call is flushed to disk
+     * Sets the value associated with a key as a JSON string.
+     * @param async set the value using an async operation.
      */
-    flush(): void;
-    private handleKvp;
+    setJson(key: string, value: object, async?: boolean): void;
     /**
-     * enumerates over any kvp prefixed with the prefix
-     *
-     * ```typescript
-     * for (const value of Kvp.getKvpsAsString("native:")) {
-     *		console.log(value);
-     * }
-     * ```
-     *
-     * @param prefix the prefix to search for
+     * Returns the value associated with a key, determining the type using the declared Kvp schema.
      */
-    getKvpsAsString(prefix: string): IterableIterator<string>;
+    get<K extends keyof T>(key: K): T[K] extends "number" | "float" ? number : T[K] extends object ? T[K] | null : string | null;
     /**
-     * enumerates over any kvp prefixed with the prefix
-     *
-     * ```typescript
-     * for (const value of Kvp.getKvpsAsNumber("native:")) {
-     *		console.log(value);
-     * }
-     * ```
-     *
-     * @param prefix the prefix to search for
+     * Sets the value associated with a key as a value, using its type from the declared Kvp stricture.
+     * @param async set the value using an async operation.
      */
-    getKvpsAsNumber(prefix: string): IterableIterator<number>;
+    set<K extends string>(key: K extends keyof T ? K : never, value: T[K] extends "number" | "float" ? number : T[K] extends object ? T[K] | null : string | null, async?: boolean): void;
     /**
-     * enumerates over any kvp prefixed with the prefix
-     *
-     * ```typescript
-     * for (const value of Kvp.getKvpsAsFloat("native:")) {
-     *		console.log(value);
-     * }
-     * ```
+     * Deletes the specified value for key.
+     * @param async remove the value using an async operation
+     */
+    delete(key: string, async?: boolean): void;
+    /**
+     * Commits pending asynchronous operations to disk, ensuring data consistency.
      *
-     * @param prefix the prefix to search for
+     * Should be called after calling set methods using the async flag.
+     */
+    flush(): void;
+    private getAllKeys;
+    /**
+     * Returns an array of keys which match or contain the given keys.
+     */
+    getKeys(prefix: string | string[]): string[];
+    /**
+     * Get all values from keys in an array as the specified type.
      */
-    getKvpsAsFloat(prefix: string): IterableIterator<number>;
+    getValuesAsType(prefix: string[], type: "string" | "number" | "float" | "object"): unknown[];
 }
+export {};

package/Kvp.js

@@ -1,161 +1,167 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 export class Kvp {
-    // TODO: Find a way to do this without casting to any
+    schema;
+    constructor(schema) {
+        this.schema = { ...schema };
+        for (const key in this.schema) {
+            if (typeof this.schema[key] === "object")
+                this.schema[key] = Object;
+        }
+    }
     /**
-     * Sets the resource key to the specified value this is a blocking operation, if you're doing large write operations you should use [[setKvpAsync]] instead.
-     * @param key the key string
-     * @param value the value to set the key to
+     * Returns the type associated with a schema key.
      */
-    setKvp(key, value) {
-        const type = typeof value;
-        if (type === "string") {
-            SetResourceKvp(key, value);
-        }
-        else {
-            if (Number.isInteger(value)) {
-                SetResourceKvpInt(key, value);
-            }
-            else {
-                SetResourceKvpFloat(key, value);
-            }
-        }
+    getType(key) {
+        return typeof this.schema[key] === "object" ? "object" : this.schema[key];
     }
     /**
-     * Sets the resource key to the specified value, this doesn't immediately write to disk and needs [[flush]] called afterwards.
-     * @param key the key string
-     * @param value the value to set the key to
+     * Returns the value associated with a key as a number.
      */
-    setKvpAsync(key, value) {
-        const type = typeof value;
-        if (type === "string") {
-            SetResourceKvpNoSync(key, value);
-        }
-        else {
-            if (Number.isInteger(value)) {
-                SetResourceKvpIntNoSync(key, value);
-            }
-            else {
-                SetResourceKvpFloatNoSync(key, value);
-            }
-        }
+    getNumber(key) {
+        return GetResourceKvpInt(key);
     }
     /**
-     * Sets the specified key to the specified json value
-     * This can error if given an invalid object
-     * @param key the key string
-     * @param value the value to set the key to
+     * Returns the value associated with a key as a float.
      */
-    setKvpJson(key, value) {
-        const stringified = JSON.stringify(value);
-        this.setKvp(key, stringified);
+    getFloat(key) {
+        return GetResourceKvpFloat(key);
     }
     /**
-     * Gets the specified value for key
-     * @param key the key of the value to get
-     * @returns a string, or null if there is no value
+     * Returns the value associated with a key as a string.
      */
-    getKvpString(key) {
+    getString(key) {
         return GetResourceKvpString(key);
     }
     /**
-     * Gets the specified value for key
-     * @param key the key of the value to get
-     * @returns the value stored, as a number, or 0 if there is no value
+     * Returns the value associated with a key as a parsed JSON string.
      */
-    getKvpNumber(key) {
-        return GetResourceKvpInt(key);
+    getJson(key) {
+        const str = GetResourceKvpString(key);
+        return str ? JSON.parse(str) : null;
     }
     /**
-     * Gets the specified value for key
-     * @param key the key of the value to get
-     * @returns the value stored as a float, or 0.0 if there is no value
+     * Sets the value associated with a key as a number.
+     * @param async set the value using an async operation.
      */
-    getKvpFloat(key) {
-        return GetResourceKvpFloat(key);
+    setNumber(key, value, async = false) {
+        return async
+            ? SetResourceKvpIntNoSync(key, value)
+            : SetResourceKvpInt(key, value);
+    }
+    /**
+     * Sets the value associated with a key as a float.
+     * @param async set the value using an async operation.
+     */
+    setFloat(key, value, async = false) {
+        return async
+            ? SetResourceKvpFloatNoSync(key, value)
+            : SetResourceKvpFloat(key, value);
     }
-    getKvpJson(key) {
-        const kvp = this.getKvpString(key);
-        return JSON.parse(kvp || "{}");
+    /**
+     * Sets the value associated with a key as a string.
+     * @param async set the value using an async operation.
+     */
+    setString(key, value, async = false) {
+        return async
+            ? SetResourceKvpNoSync(key, value)
+            : SetResourceKvp(key, value);
     }
     /**
-     * Deletes the specified value for key, this is a blocking operation, if you're deleting a bunch of keys you should use [[deleteAsync]]
-     * @param key the key of the value to delete
+     * Sets the value associated with a key as a JSON string.
+     * @param async set the value using an async operation.
      */
-    delete(key) {
-        DeleteResourceKvp(key);
+    setJson(key, value, async = false) {
+        const str = JSON.stringify(value);
+        return async ? SetResourceKvpNoSync(key, str) : SetResourceKvp(key, str);
     }
     /**
-     * Deletes the specified resource keys value, this doesn't immediately write to disk and needs [[flush]] called afterwards.
-     * @param key the key to delete
+     * Returns the value associated with a key, determining the type using the declared Kvp schema.
      */
-    deleteAsync(key) {
-        DeleteResourceKvpNoSync(key);
+    get(key) {
+        const type = this.getType(key);
+        switch (type) {
+            case "number":
+                return this.getNumber(key);
+            case "float":
+                return this.getFloat(key);
+            case "object":
+                return this.getJson(key);
+            default:
+                return this.getString(key);
+        }
     }
     /**
-     * Ensures that any previous async call is flushed to disk
+     * Sets the value associated with a key as a value, using its type from the declared Kvp stricture.
+     * @param async set the value using an async operation.
+     */
+    set(key, value, async = false) {
+        const type = this.getType(key);
+        const valueType = typeof value;
+        if (valueType !== type && type !== "float" && valueType === "number")
+            throw new Error(`Expected '${key}' to be type '${type}' but received '${valueType}'`);
+        switch (type) {
+            case "number":
+                return this.setNumber(key, value, async);
+            case "float":
+                return this.setFloat(key, value, async);
+            case "object":
+                return this.setJson(key, value, async);
+            default:
+                return this.setString(key, value, async);
+        }
+    }
+    /**
+     * Deletes the specified value for key.
+     * @param async remove the value using an async operation
+     */
+    delete(key, async = false) {
+        return async ? DeleteResourceKvpNoSync(key) : DeleteResourceKvp(key);
+    }
+    /**
+     * Commits pending asynchronous operations to disk, ensuring data consistency.
+     *
+     * Should be called after calling set methods using the async flag.
      */
     flush() {
         FlushResourceKvp();
     }
-    *handleKvp(prefix, iterType) {
+    getAllKeys(prefix) {
+        const keys = [];
         const handle = StartFindKvp(prefix);
         if (handle === -1)
-            return;
+            return keys;
         let key;
         do {
             key = FindKvp(handle);
-            if (iterType === "string") {
-                yield GetResourceKvpString(key);
-            }
-            else if (iterType === "number") {
-                yield GetResourceKvpInt(key);
-            }
-            else if (iterType === "float") {
-                yield GetResourceKvpFloat(key);
-            }
+            if (key)
+                keys.push(key);
         } while (key);
         EndFindKvp(handle);
+        return keys;
     }
     /**
-     * enumerates over any kvp prefixed with the prefix
-     *
-     * ```typescript
-     * for (const value of Kvp.getKvpsAsString("native:")) {
-     *		console.log(value);
-     * }
-     * ```
-     *
-     * @param prefix the prefix to search for
-     */
-    getKvpsAsString(prefix) {
-        return this.handleKvp(prefix, "string");
-    }
-    /**
-     * enumerates over any kvp prefixed with the prefix
-     *
-     * ```typescript
-     * for (const value of Kvp.getKvpsAsNumber("native:")) {
-     *		console.log(value);
-     * }
-     * ```
-     *
-     * @param prefix the prefix to search for
+     * Returns an array of keys which match or contain the given keys.
      */
-    getKvpsAsNumber(prefix) {
-        return this.handleKvp(prefix, "number");
+    getKeys(prefix) {
+        return typeof prefix === "string"
+            ? this.getAllKeys(prefix)
+            : prefix.flatMap((key) => this.getAllKeys(key));
     }
     /**
-     * enumerates over any kvp prefixed with the prefix
-     *
-     * ```typescript
-     * for (const value of Kvp.getKvpsAsFloat("native:")) {
-     *		console.log(value);
-     * }
-     * ```
-     *
-     * @param prefix the prefix to search for
+     * Get all values from keys in an array as the specified type.
      */
-    getKvpsAsFloat(prefix) {
-        return this.handleKvp(prefix, "float");
+    getValuesAsType(prefix, type) {
+        const values = this.getKeys(prefix);
+        return values.map((key) => {
+            switch (type) {
+                case "number":
+                    return this.getNumber(key);
+                case "float":
+                    return this.getFloat(key);
+                case "object":
+                    return this.getJson(key);
+                default:
+                    return this.getString(key);
+            }
+        });
     }
 }

package/package.json

@@ -4,7 +4,7 @@
   "author": "Remco Troost <d0p3t>",
   "license": "MIT",
   "type": "module",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "repository": {
     "type": "git",
     "url": "https://github.com/nativewrappers/fivem.git"

package/utils/Vector.d.ts

@@ -50,20 +50,20 @@ type InferVector<T> = T extends Vec4 | VectorN<4> ? Vector4 : T extends Vec3 | V
 /**
  * A base vector class inherited by all vector classes.
  */
-declare class Vector {
-    protected static create(x: number | Vec, y?: number, z?: number, w?: number): Vector;
+declare abstract class Vector {
+    protected static create<T>(this: T, x: number | Vec, y?: number, z?: number, w?: number): Vector4 | Vector3 | Vector2;
+    /**
+     * Creates a deep copy of the provided vector.
+     * @param obj The vector to clone.
+     * @returns A new vector instance that is a copy of the provided vector.
+     */
+    static clone<T extends VectorType, U extends VectorLike>(this: T, obj: U): Vector4 | Vector3 | Vector2;
     /**
      * Creates a vector from binary data in a MsgpackBuffer.
      * @param msgpackBuffer The buffer containing binary data.
      * @returns A new vector instance.
      */
     static fromBuffer<T extends VectorType>(this: T, { buffer, type }: MsgpackBuffer): InstanceType<T>;
-    /**
-     * Creates a deep copy of the provided vector.
-     * @param obj The vector to clone.
-     * @returns A new vector instance that is a copy of the provided vector.
-     */
-    static clone<T extends VectorType, U extends VectorLike>(this: T, obj: U): InstanceType<T>;
     /**
      * Performs an operation between a vector and either another vector or scalar value.
      * @param a - The first vector.
@@ -92,21 +92,21 @@ declare class Vector {
      * @param y - The value to add to the y-component.
      * @returns A new vector with the y-component incremented.
      */
-    static addY<T extends VectorType, U extends VectorLike>(this: T, obj: U, y: number): Vector;
+    static addY<T extends VectorType, U extends VectorLike>(this: T, obj: U, y: number): U;
     /**
      * Adds a scalar value to the z-component of a vector.
      * @param obj - The vector.
      * @param z - The value to add to the z-component.
      * @returns A new vector with the z-component incremented.
      */
-    static addZ<T extends VectorType, U extends Vec3 | Vec4>(this: T, obj: U, z: number): Vector;
+    static addZ<T extends VectorType, U extends Vec3 | Vec4>(this: T, obj: U, z: number): U;
     /**
      * Adds a scalar value to the w-component of a vector.
      * @param obj - The vector.
      * @param w - The value to add to the w-component.
      * @returns A new vector with the w-component incremented.
      */
-    static addW<T extends VectorType, U extends Vec4>(this: T, obj: U, w: number): Vector;
+    static addW<T extends VectorType, U extends Vec4>(this: T, obj: U, w: number): U;
     /**
      * Subtracts one vector from another or subtracts a scalar value from a vector.
      * @param a - The vector.
@@ -205,8 +205,8 @@ declare class Vector {
      * @returns The magnitude of the vector.
      */
     static Length<T extends VectorType, U extends VectorLike>(this: T, obj: U): number;
-    readonly type: unknown;
-    readonly [size]: number;
+    type: unknown;
+    [size]: number;
     x: number;
     y: number;
     z: number | undefined;
@@ -259,7 +259,7 @@ declare class Vector {
     /**
      * @see Vector.addY
      */
-    addY(y: number): Vector;
+    addY(y: number): this;
     /**
      * @see Vector.subtract
      */
@@ -308,6 +308,7 @@ declare class Vector {
  */
 export declare class Vector2 extends Vector {
     readonly type = ClassTypes.Vector2;
+    readonly [size]: number;
     static readonly Zero: Vector2;
     /**
      * Constructs a new 2D vector.
@@ -328,6 +329,7 @@ export declare class Vector2 extends Vector {
  */
 export declare class Vector3 extends Vector implements Vec3 {
     readonly type = ClassTypes.Vector3;
+    readonly [size]: number;
     z: number;
     static readonly Zero: Vector3;
     static readonly UnitX: Vector3;
@@ -361,7 +363,7 @@ export declare class Vector3 extends Vector implements Vec3 {
     /**
      * @see Vector.addZ
      */
-    addZ(z: number): Vector;
+    addZ(z: number): this;
     /**
      * @see Vector.crossProduct
      */
@@ -376,6 +378,7 @@ export declare class Vector3 extends Vector implements Vec3 {
  */
 export declare class Vector4 extends Vector {
     readonly type = ClassTypes.Vector4;
+    readonly [size]: number;
     z: number;
     w: number;
     static readonly Zero: Vector4;
@@ -399,11 +402,11 @@ export declare class Vector4 extends Vector {
     /**
      * @see Vector.addZ
      */
-    addZ(z: number): Vector;
+    addZ(z: number): this;
     /**
      * @see Vector.addW
      */
-    addW(w: number): Vector;
+    addW(w: number): this;
     /**
      * @see Vector.crossProduct
      */

package/utils/Vector.js

@@ -10,8 +10,28 @@ const size = Symbol("size");
 class Vector {
     static create(x, y = x, z, w) {
         if (typeof x === "object")
-            ({ x, y, z = y, w = z } = x);
-        return new this(x, y, z, w);
+            ({ x, y, z, w } = x);
+        const size = (this instanceof Vector && this.size) ||
+            [x, y, z, w].filter((arg) => arg !== undefined).length;
+        switch (size) {
+            case 1:
+            case 2:
+                return new Vector2(x, y);
+            case 3:
+                return new Vector3(x, y, z);
+            case 4:
+                return new Vector4(x, y, z, w);
+            default:
+                throw new Error(`Cannot instantiate Vector with size of ${size}.`);
+        }
+    }
+    /**
+     * Creates a deep copy of the provided vector.
+     * @param obj The vector to clone.
+     * @returns A new vector instance that is a copy of the provided vector.
+     */
+    static clone(obj) {
+        return this.create(obj);
     }
     /**
      * Creates a vector from binary data in a MsgpackBuffer.
@@ -26,14 +46,6 @@ class Vector {
             arr[i] = Number(buffer.readFloatLE(i * 4).toPrecision(7));
         return this.fromArray(arr);
     }
-    /**
-     * Creates a deep copy of the provided vector.
-     * @param obj The vector to clone.
-     * @returns A new vector instance that is a copy of the provided vector.
-     */
-    static clone(obj) {
-        return this.create(obj);
-    }
     /**
      * Performs an operation between a vector and either another vector or scalar value.
      * @param a - The first vector.
@@ -286,14 +298,6 @@ class Vector {
         }
         this.x = x;
         this.y = y;
-        if (z !== undefined) {
-            this.z = z;
-            ++this[size];
-        }
-        if (w !== undefined) {
-            this.w = w;
-            ++this[size];
-        }
     }
     *[Symbol.iterator]() {
         yield this.x;
@@ -440,6 +444,7 @@ export class Vector2 extends Vector {
     // DO NOT USE, ONLY EXPOSED BECAUSE TS IS TRASH, THIS TYPE IS NOT GUARANTEED
     // TO EXIST, CHANGING IT WILL BREAK STUFF
     type = ClassTypes.Vector2;
+    [size] = 2;
     static Zero = new Vector2(0, 0);
     /**
      * Constructs a new 2D vector.
@@ -468,6 +473,7 @@ export class Vector3 extends Vector {
     // DO NOT USE, ONLY EXPOSED BECAUSE TS IS TRASH, THIS TYPE IS NOT GUARANTEED
     // TO EXIST, CHANGING IT WILL BREAK STUFF
     type = ClassTypes.Vector3;
+    [size] = 3;
     z = 0;
     static Zero = new Vector3(0, 0, 0);
     static UnitX = new Vector3(1.0, 0.0, 0.0);
@@ -491,6 +497,7 @@ export class Vector3 extends Vector {
      */
     constructor(x, y = x, z = y) {
         super(x, y, z);
+        this.z = z;
     }
     /**
      * Creates a new vector based on the provided parameters.
@@ -530,6 +537,7 @@ export class Vector4 extends Vector {
     // DO NOT USE, ONLY EXPOSED BECAUSE TS IS TRASH, THIS TYPE IS NOT GUARANTEED
     // TO EXIST, CHANGING IT WILL BREAK STUFF
     type = ClassTypes.Vector4;
+    [size] = 4;
     z = 0;
     w = 0;
     static Zero = new Vector4(0, 0, 0, 0);
@@ -542,6 +550,8 @@ export class Vector4 extends Vector {
      */
     constructor(x, y = x, z = y, w = z) {
         super(x, y, z, w);
+        this.z = w;
+        this.w = w;
     }
     /**
      * Creates a new vector based on the provided parameters.