tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
151 lines (102 loc) • 3.36 kB
Markdown
# 📚 TinyArrayPaginator
A small but powerful utility for **paginating arrays or sets** 🔄.
It allows you to filter data using **objects**, **functions**, or **regular expressions**, and retrieve paginated results along with useful metadata.
## 🔍 GetFilter — Predicate Function
A predicate function used to determine whether an item should be included in the filtered results.
Works similarly to the callback function of `Array.prototype.filter`.
```js
/**
* @callback GetFilter
* @param {any} value - The current element being processed in the array.
* @param {number} index - The index of the current element within the array.
* @param {any[]} array - The full array being processed.
* @returns {boolean} - `true` to include the element, `false` to exclude it.
*/
```
## 🛠 Class: `TinyArrayPaginator`
### ✨ Features
* **Immutable source safety** — The original array/set is never modified.
* **Flexible filtering** — Supports:
* Object key-value filters
* Custom filter functions
* RegExp matching
* **Pagination metadata** — Returns total items, total pages, and navigation info.
### 🏗 Constructor
```js
new TinyArrayPaginator(data)
```
**Parameters:**
* `data` (`any[] | Set<any>`) — The data source to paginate.
**Throws:**
* `TypeError` if `data` is not an array or set.
### 📥 `.data` (Getter)
Gets the current stored array/set.
**Returns:**
`any[] | Set<any>`
### 📤 `.data` (Setter)
Replaces the current data source.
**Parameters:**
* `value` (`any[] | Set<any>`) — The new data source.
**Throws:**
* `TypeError` if the value is not an array or set.
### 📏 `.size`
Gets the total number of items in the current data source.
**Returns:**
`number`
### 📄 `.get({ page, perPage, filter })`
Filters and paginates the stored data.
**Parameters:**
* `page` (`number`) — The page number (1-based).
* `perPage` (`number`) — Number of items per page.
* `filter` (`Record<string, any> | GetFilter`, optional) — Filtering criteria:
* **Object** — Key-value pairs for exact match, substring match, or RegExp.
* **RegExp** values in the object are matched using `.test()`.
**Returns:**
```ts
{
items: any[], // Items for the current page
page: number, // Current page number (validated)
perPage: number, // Items per page
totalItems: number, // Total filtered items
totalPages: number, // Total available pages
hasPrev: boolean, // True if a previous page exists
hasNext: boolean // True if a next page exists
}
```
**Throws:**
* `RangeError` if `page` or `perPage` is not a positive integer.
* `TypeError` if `filter` is neither an object nor a function.
### 📌 Example Usage
```js
import TinyArrayPaginator from './TinyArrayPaginator.js';
const paginator = new TinyArrayPaginator([
{ id: 1, category: 'fruit' },
{ id: 2, category: 'vegetable' },
{ id: 3, category: 'fruit' },
{ id: 4, category: 'grain' }
]);
// Example: Filter only fruits and get the first page
const result = paginator.get({
page: 1,
perPage: 2,
filter: { category: 'fruit' }
});
console.log(result);
// {
// items: [{ id: 1, category: 'fruit' }, { id: 3, category: 'fruit' }],
// page: 1,
// perPage: 2,
// totalItems: 2,
// totalPages: 1,
// hasPrev: false,
// hasNext: false
// }
```