@kdtlabs/utils 0.0.4 → 0.0.6

package/src/arrays/operations.ts

@@ -0,0 +1,103 @@
+import type { Nullable } from '../core'
+import type { MaybeArray } from './types'
+import { toArray } from './conversions'
+
+export const merge = <T>(...arrays: Array<Nullable<MaybeArray<T>>>) => arrays.flatMap((array) => toArray(array))
+
+export const flatten = <T>(array?: Nullable<MaybeArray<T | T[]>>) => toArray(array).flat() as T[]
+
+export function shuffle<T>(array: T[]): T[] {
+    const result = [...array]
+
+    for (let i = result.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1))
+        const temp = result[i]
+
+        result[i] = result[j]!
+        result[j] = temp!
+    }
+
+    return result
+}
+
+export function groupBy<T, K extends PropertyKey>(array: T[], keyFn: (item: T) => K): Record<K, T[]> {
+    const result = {} as Record<K, T[]>
+
+    for (const item of array) {
+        const key = keyFn(item)
+        const group = result[key]
+
+        if (group) {
+            group.push(item)
+        } else {
+            result[key] = [item]
+        }
+    }
+
+    return result
+}
+
+export function keyBy<T, K extends PropertyKey>(array: T[], keyFn: (item: T) => K): Record<K, T> {
+    const result = {} as Record<K, T>
+
+    for (const item of array) {
+        result[keyFn(item)] = item
+    }
+
+    return result
+}
+
+export function chunk<T>(array: T[], size: number): T[][] {
+    if (size <= 0 || !Number.isFinite(size)) {
+        throw new RangeError(`chunk size must be a positive finite number, got ${size}`)
+    }
+
+    const step = Math.floor(size)
+    const result: T[][] = []
+
+    for (let i = 0; i < array.length; i += step) {
+        result.push(array.slice(i, i + step))
+    }
+
+    return result
+}
+
+export type SortDirection = 'asc' | 'desc'
+
+export type SortKey<T> = ((item: T) => number | string) | { fn: (item: T) => number | string, order: SortDirection }
+
+export function sortBy<T>(array: T[], ...keys: Array<SortKey<T>>): T[] {
+    const normalizedKeys = keys.map((key) => (typeof key === 'function' ? { fn: key, order: 'asc' as const } : key))
+
+    return array.toSorted((a, b) => {
+        for (const { fn, order } of normalizedKeys) {
+            const va = fn(a)
+            const vb = fn(b)
+
+            if (va < vb) {
+                return order === 'asc' ? -1 : 1
+            }
+
+            if (va > vb) {
+                return order === 'asc' ? 1 : -1
+            }
+        }
+
+        return 0
+    })
+}
+
+export function partition<T>(array: T[], predicate: (item: T) => boolean): [T[], T[]] {
+    const pass: T[] = []
+    const fail: T[] = []
+
+    for (const item of array) {
+        if (predicate(item)) {
+            pass.push(item)
+        } else {
+            fail.push(item)
+        }
+    }
+
+    return [pass, fail]
+}

package/src/arrays/set-operations.ts

@@ -0,0 +1,11 @@
+export const unique = <T>(array: T[]) => [...new Set(array)]
+
+export const uniqueBy = <T>(array: T[], equalFn: (a: T, b: T) => boolean) => (
+    array.reduce<T[]>((r, c) => (r.some((v) => equalFn(v, c)) ? r : [...r, c]), [])
+)
+
+export const intersection = <T>(a: T[], b: T[]) => a.filter((v) => b.includes(v))
+
+export const diff = <T>(a: T[], b: T[]) => a.filter((v) => !b.includes(v))
+
+export const symmetricDiff = <T>(a: T[], b: T[]) => [...diff(a, b), ...diff(b, a)]

package/src/arrays/types.ts

@@ -0,0 +1,21 @@
+export type MaybeArray<T> = Iterable<T> | T | T[]
+
+export type EmptyArray = []
+
+export type NonEmptyArray<T> = [T, ...T[]]
+
+export type ElementOf<T> = T extends Array<infer E> ? E : never
+
+export type Head<T extends readonly unknown[]> = T extends readonly [infer H, ...unknown[]] ? H : never
+
+export type Tail<T extends readonly unknown[]> = T extends readonly [unknown, ...infer R] ? R : []
+
+export type Last<T extends readonly unknown[]> = T extends readonly [...unknown[], infer L] ? L : never
+
+export type Flatten<T extends readonly unknown[]> = T extends ReadonlyArray<infer U> ? U extends ReadonlyArray<infer V> ? V[] : U[] : never
+
+export type TupleToUnion<T extends readonly unknown[]> = T[number]
+
+export type FixedLength<T, N extends number, R extends T[] = []> = R['length'] extends N ? R : FixedLength<T, N, [...R, T]>
+
+export type ReadonlyNonEmptyArray<T> = readonly [T, ...T[]]

package/src/buffers/conversions.ts

@@ -0,0 +1,26 @@
+import type { BufferLike } from './types'
+import { isArrayBuffer, isBuffer, isSharedArrayBuffer } from './guards'
+
+export function bufferToString(buffer: BufferLike, encoding: BufferEncoding = 'utf8') {
+    if (isBuffer(buffer)) {
+        return buffer.toString(encoding)
+    }
+
+    if (isArrayBuffer(buffer) || isSharedArrayBuffer(buffer)) {
+        return Buffer.from(buffer).toString(encoding)
+    }
+
+    return Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength).toString(encoding)
+}
+
+export function toUint8Array(input: BufferLike) {
+    if (input instanceof Uint8Array) {
+        return input
+    }
+
+    if (input instanceof ArrayBuffer || input instanceof SharedArrayBuffer) {
+        return new Uint8Array(input)
+    }
+
+    return new Uint8Array(input.buffer, input.byteOffset, input.byteLength)
+}

package/src/buffers/guards.ts

@@ -0,0 +1,13 @@
+import type { BufferLike } from './types'
+
+export const isBuffer = (value: unknown): value is Buffer => Buffer.isBuffer(value)
+
+export const isArrayBuffer = (value: unknown): value is ArrayBuffer => value instanceof ArrayBuffer
+
+export const isSharedArrayBuffer = (value: unknown): value is SharedArrayBuffer => value instanceof SharedArrayBuffer
+
+export const isArrayBufferView = (value: unknown): value is ArrayBufferView => ArrayBuffer.isView(value)
+
+export const isBufferLike = (value: unknown): value is BufferLike => (
+    isBuffer(value) || isArrayBuffer(value) || isSharedArrayBuffer(value) || isArrayBufferView(value)
+)

package/src/buffers/index.ts

@@ -0,0 +1,5 @@
+export * from './conversions'
+export * from './guards'
+export * from './operations'
+
+export type * from './types'

package/src/buffers/operations.ts

@@ -0,0 +1,44 @@
+import type { BufferLike } from './types'
+import { toUint8Array } from './conversions'
+
+export function concatBuffers(buffers: BufferLike[]) {
+    if (buffers.length === 0) {
+        return new Uint8Array(0)
+    }
+
+    const normalized = buffers.map(toUint8Array)
+
+    let totalLength = 0
+    let offset = 0
+
+    for (const buf of normalized) {
+        totalLength += buf.byteLength
+    }
+
+    const result = new Uint8Array(totalLength)
+
+    for (const buf of normalized) {
+        result.set(buf, offset)
+        offset += buf.byteLength
+    }
+
+    return result
+}
+
+export function bufferEquals(a: BufferLike, b: BufferLike) {
+    if (a === b) {
+        return true
+    }
+
+    const u8a = toUint8Array(a)
+    const u8b = toUint8Array(b)
+
+    if (u8a.byteLength !== u8b.byteLength) {
+        return false
+    }
+
+    const bufA = Buffer.from(u8a.buffer, u8a.byteOffset, u8a.byteLength)
+    const bufB = Buffer.from(u8b.buffer, u8b.byteOffset, u8b.byteLength)
+
+    return bufA.equals(bufB)
+}

package/src/buffers/types.ts

@@ -0,0 +1 @@
+export type BufferLike = ArrayBuffer | ArrayBufferView | Buffer | SharedArrayBuffer

package/src/collections/fifo-map.ts

@@ -0,0 +1,33 @@
+import { LinkedMap } from './linked-map'
+
+export class FifoMap<K, V> extends LinkedMap<K, V> {
+    public override peekNewest(): [K, V] | undefined {
+        return this.tail ? [this.tail.key, this.tail.value] : undefined
+    }
+
+    public override peekOldest(): [K, V] | undefined {
+        return this.head ? [this.head.key, this.head.value] : undefined
+    }
+
+    public set(key: K, value: V): this {
+        const existingNode = this.nodeMap.get(key)
+
+        if (existingNode) {
+            existingNode.value = value
+
+            return this
+        }
+
+        const newNode = this.createNode(key, value)
+
+        this.nodeMap.set(key, newNode)
+        this.addToTail(newNode)
+        this.currentSize++
+
+        if (this.maxSize && this.currentSize > this.maxSize) {
+            this.removeHead()
+        }
+
+        return this
+    }
+}

package/src/collections/fifo-set.ts

@@ -0,0 +1,29 @@
+import { LinkedSet } from './linked-set'
+
+export class FifoSet<T> extends LinkedSet<T> {
+    public add(value: T): this {
+        if (this.nodeMap.has(value)) {
+            return this
+        }
+
+        const newNode = this.createNode(value)
+
+        this.nodeMap.set(value, newNode)
+        this.addToTail(newNode)
+        this.currentSize++
+
+        if (this.maxSize && this.currentSize > this.maxSize) {
+            this.removeHead()
+        }
+
+        return this
+    }
+
+    public override peekOldest(): T | undefined {
+        return this.head?.value
+    }
+
+    public override peekNewest(): T | undefined {
+        return this.tail?.value
+    }
+}

package/src/collections/guards.ts

@@ -0,0 +1,11 @@
+import type { CollectionLike, MapLike, SetLike } from './types'
+
+export const isIterable = <T>(value: unknown): value is Iterable<T> => value != null && typeof value === 'object' && Symbol.iterator in value && typeof value[Symbol.iterator] === 'function'
+
+export const isCollectionLike = <T>(value: unknown): value is CollectionLike<T> => isIterable(value) && 'size' in value && typeof value.size === 'number'
+
+export const isEmptyCollection = (value: CollectionLike) => value.size === 0
+
+export const isSetLike = <T>(value: unknown): value is SetLike<T> => isCollectionLike(value) && 'has' in value && typeof value.has === 'function'
+
+export const isMapLike = <K, V>(value: unknown): value is MapLike<K, V> => isCollectionLike(value) && 'get' in value && typeof value.get === 'function' && 'entries' in value && typeof value.entries === 'function'

package/src/collections/index.ts

@@ -0,0 +1,10 @@
+export * from './fifo-map'
+export * from './fifo-set'
+export * from './guards'
+export * from './linked-base'
+export * from './linked-map'
+export * from './linked-set'
+export * from './lru-map'
+export * from './lru-set'
+
+export type * from './types'

package/src/collections/linked-base.ts

@@ -0,0 +1,117 @@
+export interface LinkedBaseNode {
+    next: LinkedBaseNode | null
+    prev: LinkedBaseNode | null
+}
+
+export abstract class LinkedBase<NodeKey, N extends LinkedBaseNode> {
+    protected readonly nodeMap = new Map<NodeKey, N>()
+
+    protected currentSize = 0
+    protected head: N | null = null
+    protected tail: N | null = null
+
+    public constructor(public readonly maxSize?: number) {
+        if (maxSize != null && (maxSize < 1 || !Number.isInteger(maxSize))) {
+            throw new RangeError('maxSize must be a positive integer')
+        }
+    }
+
+    public get size() {
+        return this.currentSize
+    }
+
+    public get [Symbol.toStringTag]() {
+        return this.constructor.name
+    }
+
+    public clear() {
+        this.nodeMap.clear()
+        this.head = null
+        this.tail = null
+        this.currentSize = 0
+    }
+
+    protected abstract getNodeKey(node: N): NodeKey
+
+    protected addToHead(node: N) {
+        node.prev = null
+        node.next = this.head
+
+        if (this.head) {
+            this.head.prev = node
+        } else {
+            this.tail = node
+        }
+
+        this.head = node
+    }
+
+    protected addToTail(node: N) {
+        node.next = null
+        node.prev = this.tail
+
+        if (this.tail) {
+            this.tail.next = node
+        } else {
+            this.head = node
+        }
+
+        this.tail = node
+    }
+
+    protected deleteByKey(key: NodeKey) {
+        const node = this.nodeMap.get(key)
+
+        if (!node) {
+            return false
+        }
+
+        this.nodeMap.delete(key)
+        this.removeNode(node)
+        this.currentSize--
+
+        return true
+    }
+
+    protected moveToHead(node: N) {
+        this.removeNode(node)
+        this.addToHead(node)
+    }
+
+    protected removeHead() {
+        if (!this.head) {
+            return
+        }
+
+        this.nodeMap.delete(this.getNodeKey(this.head))
+        this.removeNode(this.head)
+        this.currentSize--
+    }
+
+    protected removeNode(node: N) {
+        if (node.prev) {
+            node.prev.next = node.next
+        } else {
+            this.head = node.next as N | null
+        }
+
+        if (node.next) {
+            node.next.prev = node.prev
+        } else {
+            this.tail = node.prev as N | null
+        }
+
+        node.prev = null
+        node.next = null
+    }
+
+    protected removeTail() {
+        if (!this.tail) {
+            return
+        }
+
+        this.nodeMap.delete(this.getNodeKey(this.tail))
+        this.removeNode(this.tail)
+        this.currentSize--
+    }
+}

package/src/collections/linked-map.ts

@@ -0,0 +1,82 @@
+import type { MapLike } from './types'
+import { LinkedBase, type LinkedBaseNode } from './linked-base'
+
+export interface LinkedMapNode<K, V> extends LinkedBaseNode {
+    key: K
+    next: LinkedMapNode<K, V> | null
+    prev: LinkedMapNode<K, V> | null
+    value: V
+}
+
+export abstract class LinkedMap<K, V> extends LinkedBase<K, LinkedMapNode<K, V>> implements MapLike<K, V> {
+    public delete(key: K) {
+        return this.deleteByKey(key)
+    }
+
+    public * entries(): IterableIterator<[K, V]> {
+        let current = this.head
+
+        while (current) {
+            yield [current.key, current.value]
+            current = current.next
+        }
+    }
+
+    public forEach(callback: (value: V, key: K, map: this) => void) {
+        for (const [key, value] of this.entries()) {
+            callback(value, key, this)
+        }
+    }
+
+    public get(key: K) {
+        return this.nodeMap.get(key)?.value
+    }
+
+    public has(key: K) {
+        return this.nodeMap.has(key)
+    }
+
+    public * keys(): IterableIterator<K> {
+        let current = this.head
+
+        while (current) {
+            yield current.key
+            current = current.next
+        }
+    }
+
+    public peekNewest(): [K, V] | undefined {
+        return this.head ? [this.head.key, this.head.value] : undefined
+    }
+
+    public peekOldest(): [K, V] | undefined {
+        return this.tail ? [this.tail.key, this.tail.value] : undefined
+    }
+
+    public abstract set(key: K, value: V): this
+
+    public [Symbol.iterator](): IterableIterator<[K, V]> {
+        return this.entries()
+    }
+
+    public toJSON(): Array<[K, V]> {
+        return [...this.entries()]
+    }
+
+    public * values(): IterableIterator<V> {
+        let current = this.head
+
+        while (current) {
+            yield current.value
+            current = current.next
+        }
+    }
+
+    protected createNode(key: K, value: V): LinkedMapNode<K, V> {
+        return { key, next: null, prev: null, value }
+    }
+
+    protected getNodeKey(node: LinkedMapNode<K, V>) {
+        return node.key
+    }
+}

package/src/collections/linked-set.ts

@@ -0,0 +1,69 @@
+import type { SetLike } from './types'
+import { LinkedBase, type LinkedBaseNode } from './linked-base'
+
+export interface LinkedSetNode<T> extends LinkedBaseNode {
+    next: LinkedSetNode<T> | null
+    prev: LinkedSetNode<T> | null
+    value: T
+}
+
+export abstract class LinkedSet<T> extends LinkedBase<T, LinkedSetNode<T>> implements SetLike<T> {
+    public abstract add(value: T): this
+
+    public delete(value: T) {
+        return this.deleteByKey(value)
+    }
+
+    public * entries(): IterableIterator<[T, T]> {
+        for (const value of this.values()) {
+            yield [value, value]
+        }
+    }
+
+    public forEach(callback: (value: T, value2: T, set: this) => void) {
+        for (const value of this.values()) {
+            callback(value, value, this)
+        }
+    }
+
+    public has(value: T) {
+        return this.nodeMap.has(value)
+    }
+
+    public keys() {
+        return this.values()
+    }
+
+    public peekNewest(): T | undefined {
+        return this.head?.value
+    }
+
+    public peekOldest(): T | undefined {
+        return this.tail?.value
+    }
+
+    public [Symbol.iterator]() {
+        return this.values()
+    }
+
+    public toJSON(): T[] {
+        return [...this.values()]
+    }
+
+    public * values(): IterableIterator<T> {
+        let current = this.head
+
+        while (current) {
+            yield current.value
+            current = current.next
+        }
+    }
+
+    protected createNode(value: T): LinkedSetNode<T> {
+        return { next: null, prev: null, value }
+    }
+
+    protected getNodeKey(node: LinkedSetNode<T>) {
+        return node.value
+    }
+}

package/src/collections/lru-map.ts

@@ -0,0 +1,36 @@
+import { LinkedMap } from './linked-map'
+
+export class LruMap<K, V> extends LinkedMap<K, V> {
+    public override get(key: K) {
+        const node = this.nodeMap.get(key)
+
+        if (node) {
+            this.moveToHead(node)
+        }
+
+        return node?.value
+    }
+
+    public set(key: K, value: V): this {
+        const existingNode = this.nodeMap.get(key)
+
+        if (existingNode) {
+            existingNode.value = value
+            this.moveToHead(existingNode)
+
+            return this
+        }
+
+        const newNode = this.createNode(key, value)
+
+        this.nodeMap.set(key, newNode)
+        this.addToHead(newNode)
+        this.currentSize++
+
+        if (this.maxSize && this.currentSize > this.maxSize) {
+            this.removeTail()
+        }
+
+        return this
+    }
+}

package/src/collections/lru-set.ts

@@ -0,0 +1,25 @@
+import { LinkedSet } from './linked-set'
+
+export class LruSet<T> extends LinkedSet<T> {
+    public add(value: T): this {
+        const existingNode = this.nodeMap.get(value)
+
+        if (existingNode) {
+            this.moveToHead(existingNode)
+
+            return this
+        }
+
+        const newNode = this.createNode(value)
+
+        this.nodeMap.set(value, newNode)
+        this.addToHead(newNode)
+        this.currentSize++
+
+        if (this.maxSize && this.currentSize > this.maxSize) {
+            this.removeTail()
+        }
+
+        return this
+    }
+}

package/src/collections/types.ts

@@ -0,0 +1,12 @@
+export type CollectionLike<T = unknown> = Iterable<T> & {
+    readonly size: number
+}
+
+export type SetLike<T = unknown> = CollectionLike<T> & {
+    has(value: T): boolean
+}
+
+export type MapLike<K = unknown, V = unknown> = CollectionLike<[K, V]> & {
+    entries(): Iterable<[K, V]>
+    get(key: K): V | undefined
+}

package/src/common/assertions.ts

@@ -0,0 +1,11 @@
+import { ensureError, type Errorable, type ErrorCtor } from '../errors'
+
+export function assert(condition: unknown, message: Errorable, ctor?: ErrorCtor): asserts condition {
+    if (!condition) {
+        throw ensureError(message, ctor)
+    }
+}
+
+export function assertParam(condition: unknown, message: Errorable, ctor?: ErrorCtor): asserts condition {
+    assert(condition, message, ctor ?? TypeError)
+}