ts-utils !npm

About

Lightweight TypeScript utility library offering a collection of essential functions to simplify common coding tasks. Designed for a maximized type-safety, efficiency, readability, and maintainability.

Install

``
npm install --save @axanc/ts-utils
`

Examples

Components from browser/ and node/ directory only works in their related environment.

- Obj – Utility functions for Object manipulation.
- Seq – Enhanced Array
- Match – Type-safe pattern matching for Enum 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).

$3

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}
`

$3

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]
`

$3

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
`

$3

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 },
// }
`

$3

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]]
`

$3

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
`

$3

> [!IMPORTANT]
> Note: Only available on Node environment.

`ts
await gunzipFile(${fixturePath}/zipped.gz)
await gzipFile(${fixturePath}/notzipped)
`

$3

> [!IMPORTANT]
> Note: Only available on Node environment.

`ts
const splitFiles = await fileSplitter({
filepath: 'large.txt',
maxFileSizeMB: 5,
outputDirPath: '.', // Optional
})
``