@furystack/utils 8.1.6 → 8.1.8

package/CHANGELOG.md

@@ -1,42 +1,15 @@
-# Change Log
+# Changelog
 
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+## [8.1.8] - 2026-01-22
 
-### [2.0.3](https://github.com/furystack/furystack/compare/@furystack/utils@2.0.2...@furystack/utils@2.0.3) (2022-02-16)
+### ⬆️ Dependencies
 
-**Note:** Version bump only for package @furystack/utils
+- Dependency updates
 
-### [2.0.2](https://github.com/furystack/furystack/compare/@furystack/utils@2.0.0...@furystack/utils@2.0.2) (2022-01-10)
+### 📚 Documentation
 
-**Note:** Version bump only for package @furystack/utils
+- Revamped README with improved utility documentation and examples
 
-### [2.0.1](https://github.com/furystack/furystack/compare/@furystack/utils@2.0.0...@furystack/utils@2.0.1) (2022-01-10)
+### 🔧 Chores
 
-**Note:** Version bump only for package @furystack/utils
-
-## [2.0.0](https://github.com/furystack/furystack/compare/@furystack/utils@1.2.46...@furystack/utils@2.0.0) (2021-12-08)
-
-### ⚠ BREAKING CHANGES
-
-- **@furystack/shades:** Disposable resources on Shade Components (#165)
-
-### 🚀 What's new
-
-- **@furystack/shades:** Disposable resources on Shade Components ([#165](https://github.com/furystack/furystack/issues/165)) ([8567e7e](https://github.com/furystack/furystack/commit/8567e7e2e01cec232a5f4448dfc0833c1f183229))
-
-### [1.2.46](https://github.com/furystack/furystack/compare/@furystack/utils@1.2.45...@furystack/utils@1.2.46) (2021-11-19)
-
-**Note:** Version bump only for package @furystack/utils
-
-### [1.2.45](https://github.com/furystack/furystack/compare/@furystack/utils@1.2.44...@furystack/utils@1.2.45) (2021-10-05)
-
-**Note:** Version bump only for package @furystack/utils
-
-### [1.2.44](https://github.com/furystack/furystack/compare/@furystack/utils@1.2.14...@furystack/utils@1.2.44) (2021-08-19)
-
-**Note:** Version bump only for package @furystack/utils
-
-### [1.2.43](https://github.com/furystack/furystack/compare/@furystack/utils@1.2.14...@furystack/utils@1.2.43) (2021-07-30)
-
-**Note:** Version bump only for package @furystack/utils
+- Migrated to centralized changelog management system

package/README.md

@@ -2,13 +2,23 @@
 
 General utilities for FuryStack.
 
-### Disposable
+## Installation
 
-You can implement disposable resources and use them with `using()` or `usingAsync()` syntax. Example:
+```bash
+npm install @furystack/utils
+# or
+yarn add @furystack/utils
+```
+
+## Disposable
+
+You can implement disposable resources and use them with `using()` or `usingAsync()` syntax:
 
 ```ts
-class Resource implements IDisposable {
-  dispose() {
+import { using, usingAsync } from '@furystack/utils'
+
+class Resource implements Disposable {
+  [Symbol.dispose]() {
     // cleanup logic
   }
 }
@@ -17,18 +27,18 @@ using(new Resource(), (resource) => {
   // do something with the resource
 })
 
-usingAsync(new Resource(), async (resource) => {
+await usingAsync(new Resource(), async (resource) => {
   // do something with the resource, allows awaiting promises
 })
 ```
 
-### ObservableValue and ValueObservers
-
-You can track value changes using this simple Observable implementation.
+## ObservableValue
 
-Example:
+You can track value changes using this simple Observable implementation:
 
 ```ts
+import { ObservableValue } from '@furystack/utils'
+
 const observableValue = new ObservableValue<number>(0)
 const observer = observableValue.subscribe((newValue) => {
   console.log('Value changed:', newValue)
@@ -42,51 +52,157 @@ observer[Symbol.dispose]()
 observableValue[Symbol.dispose]()
 ```
 
-### PathHelper
+## PathHelper
+
+Helper class for path-related functions and methods:
+
+```ts
+import { PathHelper } from '@furystack/utils'
+
+PathHelper.joinPaths('api', 'users', '123') // 'api/users/123'
+PathHelper.getSegments('/api/users/123') // ['api', 'users', '123']
+PathHelper.getParentPath('/api/users/123') // 'api/users'
+PathHelper.trimSlashes('/api/') // 'api'
+PathHelper.joinUrl('http://example.com', '/api') // 'http://example.com/api'
+```
+
+## deepMerge
 
-This class contains helper methods for path transformation and manipulation.
+Deep merge objects together:
 
-### Retrier
+```ts
+import { deepMerge } from '@furystack/utils'
 
-Retrier is a utility that can keep trying an operation until it succeeds, times out or reach a specified retry limit.
+const target = { a: 1, b: { c: 2 } }
+const source = { b: { d: 3 } }
+const result = deepMerge(target, source) // { a: 1, b: { c: 2, d: 3 } }
+```
+
+## sleepAsync
+
+Simple promise-based sleep utility:
 
 ```ts
-const funcToRetry: () => Promise<boolean> = async () => {
-  const hasSucceeded = false
-  // ...
-  // custom logic
-  // ...
-  return hasSucceeded
-}
-const retrierSuccess = await Retrier.create(funcToRetry)
-  .setup({
-    Retries: 3,
-    RetryIntervalMs: 1,
-    timeoutMs: 1000,
-  })
-  .run()
+import { sleepAsync } from '@furystack/utils'
+
+await sleepAsync(1000) // wait 1 second
 ```
 
-### Trace
+## debounce
 
-Trace is an utility that can be used to track method calls, method returns and errors
+Debounce a function to limit how often it can be called:
 
 ```ts
-const methodTracer: IDisposable = Trace.method({
-  object: myObjectInstance, // You can define an object constructor for static methods as well
-  method: myObjectInstance.method, // The method to be tracked
-  isAsync: true, // if you set to async, method finished will be *await*-ed
-  onCalled: (traceData) => {
-    console.log('Method called:', traceData)
-  },
-  onFinished: (traceData) => {
-    console.log('Method call finished:', traceData)
-  },
-  onError: (traceData) => {
-    console.log('Method throwed an error:', traceData)
-  },
+import { debounce } from '@furystack/utils'
+
+const debouncedSearch = debounce((query: string) => {
+  console.log('Searching for:', query)
+}, 300)
+
+debouncedSearch('hello') // Will only execute after 300ms of no calls
+```
+
+## EventHub
+
+A typed event emitter:
+
+```ts
+import { EventHub } from '@furystack/utils'
+
+type MyEvents = {
+  userLoggedIn: { userId: string }
+  userLoggedOut: { userId: string }
+}
+
+const hub = new EventHub<MyEvents>()
+
+hub.subscribe('userLoggedIn', (event) => {
+  console.log('User logged in:', event.userId)
 })
 
-// if you want to stop receiving events
-methodTracer[Symbol.dispose]()
+hub.emit('userLoggedIn', { userId: '123' })
+```
+
+## sortBy
+
+Array prototype extension for convenient sorting by field name:
+
+```ts
+import '@furystack/utils' // Adds sortBy to Array prototype
+
+const users = [
+  { name: 'Charlie', age: 30 },
+  { name: 'Alice', age: 25 },
+  { name: 'Bob', age: 35 },
+]
+
+// Sort by name ascending (default)
+const byName = users.sortBy('name')
+// [{ name: 'Alice', ... }, { name: 'Bob', ... }, { name: 'Charlie', ... }]
+
+// Sort by age descending
+const byAgeDesc = users.sortBy('age', 'desc')
+// [{ name: 'Bob', age: 35 }, { name: 'Charlie', age: 30 }, { name: 'Alice', age: 25 }]
+```
+
+You can also use the `compareBy` function directly for custom sorting:
+
+```ts
+import { compareBy } from '@furystack/utils'
+
+const users = [{ name: 'Charlie' }, { name: 'Alice' }]
+users.sort((a, b) => compareBy(a, b, 'name', 'asc'))
+```
+
+## tuple
+
+Helper function for creating typed tuples from string literals:
+
+```ts
+import { tuple } from '@furystack/utils'
+
+// Creates a tuple type ['admin', 'user', 'guest'] instead of string[]
+const roles = tuple('admin', 'user', 'guest')
+
+// TypeScript knows the exact values
+type Role = (typeof roles)[number] // 'admin' | 'user' | 'guest'
+```
+
+## Type Guards
+
+Check if a value is disposable:
+
+```ts
+import { isDisposable, isAsyncDisposable } from '@furystack/utils'
+
+if (isDisposable(value)) {
+  value[Symbol.dispose]()
+}
+
+if (isAsyncDisposable(value)) {
+  await value[Symbol.asyncDispose]()
+}
+```
+
+## DeepPartial
+
+A utility type for deep partial objects:
+
+```ts
+import type { DeepPartial } from '@furystack/utils'
+
+type Config = {
+  server: {
+    host: string
+    port: number
+  }
+  database: {
+    url: string
+  }
+}
+
+// All nested properties are optional
+const partialConfig: DeepPartial<Config> = {
+  server: { port: 8080 }, // host is optional
+}
 ```

package/esm/event-hub.d.ts

@@ -1,4 +1,31 @@
 type ListenerFunction<EventTypeMap extends object, T extends keyof EventTypeMap> = (arg: EventTypeMap[T]) => void | PromiseLike<void>;
+/**
+ * A typed event emitter that provides type-safe event subscription and emission.
+ * Use this to create strongly-typed pub/sub patterns in your application.
+ *
+ * @typeParam EventTypeMap - An object type where keys are event names and values are event payload types
+ * @example
+ * ```ts
+ * type MyEvents = {
+ *   userLoggedIn: { userId: string }
+ *   userLoggedOut: { userId: string }
+ *   dataUpdated: { items: string[] }
+ * }
+ *
+ * const hub = new EventHub<MyEvents>()
+ *
+ * // Subscribe to events
+ * hub.subscribe('userLoggedIn', (event) => {
+ *   console.log('User logged in:', event.userId)
+ * })
+ *
+ * // Emit events
+ * hub.emit('userLoggedIn', { userId: '123' })
+ *
+ * // Clean up when done
+ * hub[Symbol.dispose]()
+ * ```
+ */
 export declare class EventHub<EventTypeMap extends object> implements Disposable {
     private listeners;
     addListener<TEvent extends keyof EventTypeMap>(event: TEvent, listener: ListenerFunction<EventTypeMap, TEvent>): void;

package/esm/event-hub.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-hub.d.ts","sourceRoot":"","sources":["../src/event-hub.ts"],"names":[],"mappings":"AAAA,KAAK,gBAAgB,CAAC,YAAY,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,YAAY,IAAI,CACjF,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,KACjB,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAA;AAE7B,qBAAa,QAAQ,CAAC,YAAY,SAAS,MAAM,CAAE,YAAW,UAAU;IACtE,OAAO,CAAC,SAAS,CAAyF;IAEnG,WAAW,CAAC,MAAM,SAAS,MAAM,YAAY,EAClD,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,gBAAgB,CAAC,YAAY,EAAE,MAAM,CAAC;IAQ3C,cAAc,CAAC,MAAM,SAAS,MAAM,YAAY,EACrD,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,gBAAgB,CAAC,YAAY,EAAE,MAAM,CAAC;IAO3C,SAAS,CAAC,MAAM,SAAS,MAAM,YAAY,EAChD,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,gBAAgB,CAAC,YAAY,EAAE,MAAM,CAAC,GAC/C,UAAU;IAKN,IAAI,CAAC,MAAM,SAAS,MAAM,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC;IAMhF,CAAC,MAAM,CAAC,OAAO,CAAC;CAGxB"}
+{"version":3,"file":"event-hub.d.ts","sourceRoot":"","sources":["../src/event-hub.ts"],"names":[],"mappings":"AAAA,KAAK,gBAAgB,CAAC,YAAY,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,YAAY,IAAI,CACjF,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,KACjB,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAA;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,QAAQ,CAAC,YAAY,SAAS,MAAM,CAAE,YAAW,UAAU;IACtE,OAAO,CAAC,SAAS,CAAyF;IAEnG,WAAW,CAAC,MAAM,SAAS,MAAM,YAAY,EAClD,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,gBAAgB,CAAC,YAAY,EAAE,MAAM,CAAC;IAQ3C,cAAc,CAAC,MAAM,SAAS,MAAM,YAAY,EACrD,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,gBAAgB,CAAC,YAAY,EAAE,MAAM,CAAC;IAO3C,SAAS,CAAC,MAAM,SAAS,MAAM,YAAY,EAChD,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,gBAAgB,CAAC,YAAY,EAAE,MAAM,CAAC,GAC/C,UAAU;IAKN,IAAI,CAAC,MAAM,SAAS,MAAM,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC;IAMhF,CAAC,MAAM,CAAC,OAAO,CAAC;CAGxB"}

package/esm/event-hub.js

@@ -1,3 +1,30 @@
+/**
+ * A typed event emitter that provides type-safe event subscription and emission.
+ * Use this to create strongly-typed pub/sub patterns in your application.
+ *
+ * @typeParam EventTypeMap - An object type where keys are event names and values are event payload types
+ * @example
+ * ```ts
+ * type MyEvents = {
+ *   userLoggedIn: { userId: string }
+ *   userLoggedOut: { userId: string }
+ *   dataUpdated: { items: string[] }
+ * }
+ *
+ * const hub = new EventHub<MyEvents>()
+ *
+ * // Subscribe to events
+ * hub.subscribe('userLoggedIn', (event) => {
+ *   console.log('User logged in:', event.userId)
+ * })
+ *
+ * // Emit events
+ * hub.emit('userLoggedIn', { userId: '123' })
+ *
+ * // Clean up when done
+ * hub[Symbol.dispose]()
+ * ```
+ */
 export class EventHub {
     listeners = new Map();
     addListener(event, listener) {

package/esm/event-hub.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-hub.js","sourceRoot":"","sources":["../src/event-hub.ts"],"names":[],"mappings":"AAIA,MAAM,OAAO,QAAQ;IACX,SAAS,GAAG,IAAI,GAAG,EAA+E,CAAA;IAEnG,WAAW,CAChB,KAAa,EACb,QAAgD;QAEhD,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,CAAA;QACtC,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,GAAG,CAAC,QAA8D,CAAC,CAAA;IAChG,CAAC;IAEM,cAAc,CACnB,KAAa,EACb,QAAgD;QAEhD,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,MAAM,CAAC,QAA8D,CAAC,CAAA;QACnG,CAAC;IACH,CAAC;IAEM,SAAS,CACd,KAAa,EACb,QAAgD;QAEhD,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;QACjC,OAAO,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAA;IACzE,CAAC;IAEM,IAAI,CAAoC,KAAa,EAAE,GAAyB;QACrF,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;QACtE,CAAC;IACH,CAAC;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC;QACrB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAA;IACxB,CAAC;CACF"}
+{"version":3,"file":"event-hub.js","sourceRoot":"","sources":["../src/event-hub.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,OAAO,QAAQ;IACX,SAAS,GAAG,IAAI,GAAG,EAA+E,CAAA;IAEnG,WAAW,CAChB,KAAa,EACb,QAAgD;QAEhD,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,CAAA;QACtC,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,GAAG,CAAC,QAA8D,CAAC,CAAA;IAChG,CAAC;IAEM,cAAc,CACnB,KAAa,EACb,QAAgD;QAEhD,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,MAAM,CAAC,QAA8D,CAAC,CAAA;QACnG,CAAC;IACH,CAAC;IAEM,SAAS,CACd,KAAa,EACb,QAAgD;QAEhD,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;QACjC,OAAO,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAA;IACzE,CAAC;IAEM,IAAI,CAAoC,KAAa,EAAE,GAAyB;QACrF,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;QACtE,CAAC;IACH,CAAC;IAEM,CAAC,MAAM,CAAC,OAAO,CAAC;QACrB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAA;IACxB,CAAC;CACF"}

package/esm/sort-by.js

@@ -10,7 +10,6 @@ export const compareBy = (entity1, entity2, field, direction) => {
     return 0;
 };
 Array.prototype.sortBy = function (key, direction = 'asc') {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
     return this.sort((a, b) => compareBy(a, b, key, direction));
 };
 //# sourceMappingURL=sort-by.js.map

package/esm/sort-by.js.map

@@ -1 +1 @@
-{"version":3,"file":"sort-by.js","sourceRoot":"","sources":["../src/sort-by.ts"],"names":[],"mappings":"AAeA,MAAM,CAAC,MAAM,SAAS,GAAG,CAAuB,OAAU,EAAE,OAAU,EAAE,KAAQ,EAAE,SAAyB,EAAE,EAAE;IAC7G,MAAM,CAAC,GAAG,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAA;IACjD,MAAM,CAAC,GAAG,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAA;IACjD,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,CAAC,CAAA;IACX,CAAC;IACD,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,CAAA;IACV,CAAC;IACD,OAAO,CAAC,CAAA;AACV,CAAC,CAAA;AAED,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,UAAU,GAAG,EAAE,SAAS,GAAG,KAAK;IACvD,+DAA+D;IAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC,CAAA;AAC7D,CAAC,CAAA"}
+{"version":3,"file":"sort-by.js","sourceRoot":"","sources":["../src/sort-by.ts"],"names":[],"mappings":"AAeA,MAAM,CAAC,MAAM,SAAS,GAAG,CAAuB,OAAU,EAAE,OAAU,EAAE,KAAQ,EAAE,SAAyB,EAAE,EAAE;IAC7G,MAAM,CAAC,GAAG,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAA;IACjD,MAAM,CAAC,GAAG,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAA;IACjD,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,CAAC,CAAA;IACX,CAAC;IACD,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,CAAA;IACV,CAAC;IACD,OAAO,CAAC,CAAA;AACV,CAAC,CAAA;AAED,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,UAAgC,GAAM,EAAE,YAA4B,KAAK;IAChG,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC,CAAA;AAC7D,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furystack/utils",
-  "version": "8.1.6",
+  "version": "8.1.8",
   "description": "General utilities",
   "type": "module",
   "scripts": {
@@ -35,6 +35,6 @@
   "homepage": "https://github.com/furystack/furystack",
   "devDependencies": {
     "typescript": "^5.9.3",
-    "vitest": "^4.0.15"
+    "vitest": "^4.0.17"
   }
 }

package/src/event-hub.ts

@@ -2,6 +2,33 @@ type ListenerFunction<EventTypeMap extends object, T extends keyof EventTypeMap>
   arg: EventTypeMap[T],
 ) => void | PromiseLike<void>
 
+/**
+ * A typed event emitter that provides type-safe event subscription and emission.
+ * Use this to create strongly-typed pub/sub patterns in your application.
+ *
+ * @typeParam EventTypeMap - An object type where keys are event names and values are event payload types
+ * @example
+ * ```ts
+ * type MyEvents = {
+ *   userLoggedIn: { userId: string }
+ *   userLoggedOut: { userId: string }
+ *   dataUpdated: { items: string[] }
+ * }
+ *
+ * const hub = new EventHub<MyEvents>()
+ *
+ * // Subscribe to events
+ * hub.subscribe('userLoggedIn', (event) => {
+ *   console.log('User logged in:', event.userId)
+ * })
+ *
+ * // Emit events
+ * hub.emit('userLoggedIn', { userId: '123' })
+ *
+ * // Clean up when done
+ * hub[Symbol.dispose]()
+ * ```
+ */
 export class EventHub<EventTypeMap extends object> implements Disposable {
   private listeners = new Map<keyof EventTypeMap, Set<ListenerFunction<EventTypeMap, keyof EventTypeMap>>>()
 

package/src/sort-by.ts

@@ -25,7 +25,6 @@ export const compareBy = <T, K extends keyof T>(entity1: T, entity2: T, field: K
   return 0
 }
 
-Array.prototype.sortBy = function (key, direction = 'asc') {
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+Array.prototype.sortBy = function <T, K extends keyof T>(key: K, direction: 'asc' | 'desc' = 'asc'): T[] {
   return this.sort((a, b) => compareBy(a, b, key, direction))
 }