Set of utils methods and features
npm install @axanc/ts-utilsLightweight TypeScript utility library offering a collection of essential functions to simplify common coding tasks. Designed for a maximized type-safety, efficiency, readability, and maintainability.
```
npm install --save @axanc/ts-utils
Components from browser/ and node/ directory only works in their related environment.
- Obj – Utility functions for Object manipulation.Array
- Seq – Enhanced Enum
- Match – Type-safe pattern matching for and string unions.
- GroupsBy – Groups an array of objects by multiple criteria and maps the results.
- Chunkify – Processes an array in batches with an asynchronous function, supporting concurrency control.
- Lazy – Caches function results to prevent redundant calls.
- Gzip – Compress and decompress files (Node.js only).
- FileSplitter – Splits a large file into smaller chunks (Node.js only).
TypeScript refuses to infer types from Object constructor functions. Obj implements the same method but infer keys and value to prevent annoying and unnecessary type casting.
`ts
// Get union string from keys
const input = {a: 1, b: 2}
Object.keys(input) // → string[]
Obj.keys(input) // → ('a' | 'b')[]
// Handle enum
enum Status { OK = 'Ok', ERROR = 'Error' }
Obj.values(Status) // → Status[]
`
Additionally, it includes helper functions and can be used as a class constructor to enable method chaining.
`ts`
const res = new Obj({ironman: 2, barman: 1, catwoman: 4, batman: 3})
.sortManual(['catwoman', 'barman', 'ironman', 'batman']) // Values are inferred
.mapKeys(_ => _.toUpperCase())
.mapValues(_ => _ + 1)
.get() // → {BARMAN: 2, IRONMAN: 3, BATMAN: 4, CATWOMAN: 5}
Enhance poor JavaScript Array.
`ts`
const a = seq([
{name: 'Dave', age: 35},
{name: 'Charlie', age: 25},
{name: 'Alice', age: 25},
])
a.distinct(_ => _.age) // → [{name: 'Dave', age: 35}, {name: 'Bob', age: 30}]
a.sortByString(_ => _.name, 'z-a') // → [{name: 'Alice', age: 25}, {name: 'Charlie', age: 25}, {name: 'Dave', age: 35}]
a.sortByNumber(_ => _.age, '0-9') // → [{name: 'Charlie', age: 25}, {name: 'Alice', age: 25}, {name: 'Dave', age: 35}]
a.count(_ => _.age > 26) // → 1
a.groupBy(_ => _.age) // → {25: [{name: 'Charlie', age: 25}, {name: 'Alice', age: 25}], 35: [{name: 'Dave', age: 35}]}
a.groupByFirst(_ => _.age) // → {25: {name: 'Charlie', age: 25}, 35: {name: 'Dave', age: 35}}
a.groupByFirstAndApply(_ => _.age, _ => _.length) // → {25: 2, 35: 1}
a.sum(_ => _.age) // → 85
a.head() // → {name: 'Dave', age: 35}
a.last() // → {name: 'Alice', age: 25}
a.reduceObject(_ => [_.name, _.age]) // → {Dave: 35, Charlie: 25, Alice: 25}
a.percent(_ => _.age === 35) // → 33.33..%
[1, 2].difference([1, 2, 3]) // → [3]
[1, 2].intersect([1, 2, 3]) // → [1, 2]
Simple and type-safe pattern matching. Fully infer Enum and strings union.
`ts
enum Enum {
yes = 'yes',
no = 'no',
unknown = 'unknown',
}
const value = Enum.yes
const res: number = match(value)
.cases({
[Enum.yes]: 0,
})
.default(() => -1) // → number
match(value)
.cases({
// Cases can only contains keys of related type
[Enum.yes]: () => 1,
[Enum.no]: () => 2,
[Enum.unknown]: () => 3,
})
.exhaustive() // .exhaustive can only be called if all cases are defined
`
Groups an array of objects by multiple criteria and maps the results.
`ts
const students = [
{name: 'Emma', class: 'Grade 9', subject: 'Math', score: 80},
{name: 'Liam', class: 'Grade 9', subject: 'English', score: 70},
{name: 'Olivia', class: 'Grade 9', subject: 'English', score: 90},
{name: 'Noah', class: 'Grade 10', subject: 'Math', score: 85},
{name: 'Ava', class: 'Grade 10', subject: 'Math', score: 75},
]
const result = groupsBy({
data: students,
groups: [
{by: s => s.class},
{by: s => s.subject},
],
finalTransform: items =>
items.reduce((sum, s) => sum + s.score, 0),
})
// result → {
// "Grade 9": { Math: 80, English: 160 },
// "Grade 10": { Math: 160 },
// }
`
Processes an array of items in batches, applying an asynchronous function fn to each chunk.
It supports optional concurrency control for optimized parallel execution.
`ts`
await chunkify({
size: 10,
data: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
fn: async chunk => {
await db.insert(chunk) // Simulate a database with a batch insert limit
return chunk.map(_ => _ * 2)
},
})
// → [[2, 4, 6, 8, 10], [12, 14, 16, 18, 20], [22, 24]]
Caches function results based on parameters to avoid redundant calls.
`ts`
const findByUserId = lazy((id: number) => {
return users.find(_ => _.id === id)
})
findByUserId(1) // Actual call
findByUserId(1) // Retrieved from cache
findByUserId(2) // Actual call
> [!IMPORTANT]
> Note: Only available on Node environment.
`ts${fixturePath}/zipped.gz
await gunzipFile()${fixturePath}/notzipped
await gzipFile()`
> [!IMPORTANT]
> Note: Only available on Node environment.
`ts``
const splitFiles = await fileSplitter({
filepath: 'large.txt',
maxFileSizeMB: 5,
outputDirPath: '.', // Optional
})