@kdtlabs/utils 0.0.4 → 0.0.5

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)
+}

package/src/common/guards.ts

@@ -0,0 +1,58 @@
+import { isArray, isEmptyArray } from '../arrays'
+import { isCollectionLike, isEmptyCollection } from '../collections'
+import { isNullish, isPrimitive, isString } from '../core'
+import { isEmptyObject, isPlainObject } from '../objects'
+
+export function isEmpty(value: unknown) {
+    if (isNullish(value)) {
+        return true
+    }
+
+    if (isArray(value)) {
+        return isEmptyArray(value)
+    }
+
+    if (isPrimitive(value)) {
+        if (isString(value)) {
+            return value.length === 0
+        }
+
+        return false
+    }
+
+    if (isPlainObject(value)) {
+        return isEmptyObject(value)
+    }
+
+    if (isCollectionLike(value)) {
+        return isEmptyCollection(value)
+    }
+
+    return false
+}
+
+export function isDeepEqual(a: unknown, b: unknown): boolean {
+    if (a === b) {
+        return true
+    }
+
+    if (isArray(a) && isArray(b)) {
+        if (a.length !== b.length) {
+            return false
+        }
+
+        return a.every((item, i) => isDeepEqual(item, b[i]))
+    }
+
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const keysA = Object.keys(a)
+
+        if (keysA.length !== Object.keys(b).length) {
+            return false
+        }
+
+        return keysA.every((key) => isDeepEqual(a[key], b[key]))
+    }
+
+    return Object.is(a, b)
+}

package/src/common/index.ts

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

package/src/common/transformations.ts

@@ -0,0 +1,20 @@
+import type { NullToUndefined } from './types'
+import { isArray } from '../arrays'
+import { isNullish } from '../core'
+import { isPlainObject, map } from '../objects'
+
+export function nullToUndefined<T>(value: T): NullToUndefined<T> {
+    if (isNullish(value)) {
+        return undefined as NullToUndefined<T>
+    }
+
+    if (isArray(value)) {
+        return value.map(nullToUndefined) as NullToUndefined<T>
+    }
+
+    if (isPlainObject(value)) {
+        return map(value, (k, v) => [k, nullToUndefined(v)]) as NullToUndefined<T>
+    }
+
+    return value as NullToUndefined<T>
+}

package/src/common/types.ts

@@ -0,0 +1,3 @@
+import type { AnyObject } from '../objects'
+
+export type NullToUndefined<T> = T extends null ? undefined : T extends Array<infer U> ? Array<NullToUndefined<U>> : T extends AnyObject ? { [K in keyof T]: NullToUndefined<T[K]> } : T

package/src/core/constants.ts

@@ -0,0 +1 @@
+export const DEFAULT_TRUE_STRINGS = new Set(['1', 'on', 'true', 'yes'])

package/src/core/conversions.ts

@@ -0,0 +1,9 @@
+export const toString = (value: unknown) => Object.prototype.toString.call(value)
+
+export function typeOf(value: unknown): string {
+    if (value === null) {
+        return 'null'
+    }
+
+    return typeof value === 'object' || typeof value === 'function' ? toString(value).slice(8, -1).toLowerCase() : typeof value
+}

package/src/core/guards.ts

@@ -0,0 +1,57 @@
+import type { JsonablePrimitive, Primitive } from './types'
+import { DEFAULT_TRUE_STRINGS } from './constants'
+
+export const isNull = (value: unknown): value is null => value === null
+export const isUndefined = (value: unknown): value is undefined => value === undefined
+export const isNullish = (value: unknown): value is null | undefined => isNull(value) || isUndefined(value)
+
+export const notNull = <T>(value: T): value is Exclude<T, null> => !isNull(value)
+export const notUndefined = <T>(value: T): value is Exclude<T, undefined> => !isUndefined(value)
+export const notNullish = <T>(value: T): value is NonNullable<T> => !isNullish(value)
+
+export const isBoolean = (value: unknown): value is boolean => typeof value === 'boolean'
+export const isSymbol = (value: unknown): value is symbol => typeof value === 'symbol'
+export const isBigInt = (value: unknown): value is bigint => typeof value === 'bigint'
+export const isNumber = (value: unknown): value is number => typeof value === 'number'
+export const isString = (value: unknown): value is string => typeof value === 'string'
+export const isDate = (value: unknown): value is Date => value instanceof Date
+
+export const isPrimitive = (value: unknown): value is Primitive => value === null || (typeof value !== 'object' && typeof value !== 'function')
+
+export const isJsonablePrimitive = (value: unknown): value is JsonablePrimitive => (
+    isNull(value) || isString(value) || isBoolean(value) || (isNumber(value) && Number.isFinite(value))
+)
+
+export interface IsTrueLikeOptions {
+    anyNonZeroNumber?: boolean
+    trueStrings?: Set<string>
+}
+
+export function isTrueLike(value: unknown, options: IsTrueLikeOptions = {}) {
+    const { anyNonZeroNumber = false, trueStrings = DEFAULT_TRUE_STRINGS } = options
+
+    if (isBoolean(value)) {
+        return value
+    }
+
+    if (isString(value)) {
+        return trueStrings.has(value.toLowerCase())
+    }
+
+    if (isNumber(value)) {
+        return anyNonZeroNumber ? value !== 0 && Number.isFinite(value) : value === 1
+    }
+
+    if (isBigInt(value)) {
+        return anyNonZeroNumber ? value !== 0n : value === 1n
+    }
+
+    return false
+}
+
+export const isGenerator = (value: unknown): boolean => (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as Record<PropertyKey, unknown>).next === 'function' &&
+    typeof (value as Record<PropertyKey, unknown>)[Symbol.iterator] === 'function'
+)

package/src/core/index.ts

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