funky-array/README.md

68 lines
1.9 KiB
Markdown
Raw Permalink Normal View History

2024-07-02 10:22:53 +01:00
# FunkyArray
2024-07-02 09:33:12 +01:00
2024-07-02 10:22:53 +01:00
An array that supports both iteration and key value indexing.
## Usage
Create a new instance of FunkyArray
#### JavaScript
```js
const funkyArray = new FunkyArray();
```
#### TypeScript
```ts
const funkyArray = new FunkyArray<key_type, value_type>();
```
From here you can `set` or `remove` items by an a key of `key_type`
For example:
```ts
const users = new FunkyArray<string, User>();
const user = new User(1, "Username", crypto.randomUUID());
users.set(user.uuid, user);
```
## General concepts
FunkyArray uses an internal "itteration array" which is really just a regular js array with all the keys. Whenever you see a `regenerate:boolean` in a method, this is so you can not regenerate the "itteration array" if you are bulk inserting things. In general you want to be very careful when turning this off and it can break itteration.
## Methods
- `set(key:T, item:TT, regenerate:boolean = true) : TT`
Sets the corrosponding key in the array to the given value. If an existing array key is provided the existing value is overwritten.
- `remove(key:T, regenerate:boolean = true) : boolean`
Removes an item from the array by key.<br>
Returns a boolean of remove success.
- `removeFirst(regenerate:boolean = true)`
Removes the first item in the array<br>
Returns a boolean of remove success.
- `first() : TT`
Returns the first item in the array.
- `get(key:T) : TT | undefined`
Returns the item with the given key, if it does not exist it returns undefined.
- `has(key:T) : boolean`
Returns a boolean for if a value exists for the given key.
- `forEach(callback: (value:TT) => void) : Promise<boolean>`
Functionally equivilent to `Array.forEach`
Returns a boolean promise that resolves once the forEach itteration is complete.
## Getters
- `length : number`
Returns the number of key values in the FunkyArray.
- `keys : Array<T>`
Returns an array of the FunkyArray's keys.