@just-io/utils 1.5.0 → 2.0.1

package/README.md

@@ -1,12 +1,245 @@
-Utils
-=====
+@just-io/utils
+==============
 
-This package contains some utilities.
+Lightweight TypeScript utility functions.
 
 ## Installation
 
-This is a Typescript module so you need to use Typescript.
+```bash
+npm install @just-io/utils
+```
 
-## Documentation
+## Utilities
 
-See tests.
+### debounce / debounceByKey
+
+Debounce function calls with optional key-based grouping.
+
+```typescript
+import { debounce, debounceByKey } from '@just-io/utils';
+
+// Basic debounce - executes after delay with last arguments
+function setFilterValue(values: string[]): void {
+    console.log('Filter:', values);
+}
+
+const debouncedSetFilterValue = debounce(setFilterValue, 1000);
+
+debouncedSetFilterValue(['first']);
+// wait 300ms...
+debouncedSetFilterValue(['second']); // Only ['second'] executes after 1000ms
+
+// Cancel pending execution
+debouncedSetFilterValue.teardown();
+
+// Key-based debounce - separate timers per extracted key
+function notify(event: { type: string; at: number }): void {
+    console.log(event.type, event.at);
+}
+
+const debouncedNotify = debounceByKey(notify, (event) => event.type, 1000);
+
+debouncedNotify({ type: 'change', at: 0 });
+debouncedNotify({ type: 'update', at: 0 }); // Both execute - different keys
+debouncedNotify({ type: 'change', at: 10 }); // Replaces first 'change', only at:10 executes
+
+// Cancel by key or all
+debouncedNotify.teardown({ type: 'change', at: 0 });
+debouncedNotify.teardownAll();
+```
+
+### memo / memoByKey
+
+Memoize function calls - skip execution if arguments haven't changed.
+
+```typescript
+import { memo, memoByKey } from '@just-io/utils';
+
+// Basic memo - only calls when extracted values change
+function notify(event: { type: string; at: number }): void {
+    console.log(event.type, event.at);
+}
+
+const memoNotify = memo(notify, (event) => [event.type, event.at]);
+
+memoNotify({ type: 'change', at: 0 }); // Executes
+memoNotify({ type: 'change', at: 0 }); // Skipped - same values
+memoNotify({ type: 'change', at: 1 }); // Executes - 'at' changed
+
+// Only trigger on changes (skip first call)
+function setFilterValue(values: string[]): void {
+    console.log('Filters changed:', values);
+}
+
+const memoSetFilterValue = memo(setFilterValue, (values) => values, true);
+
+memoSetFilterValue([]); // Skipped (initial call)
+memoSetFilterValue(['first']); // Executes (values changed)
+
+// Key-based memo - separate memo state per key
+function notifyChannel(channel: string, event: { type: string; at: number }): void {
+    console.log(channel, event);
+}
+
+const memoNotifyChannel = memoByKey(
+    notifyChannel,
+    (channel) => channel,
+    (channel, event) => [event.type, event.at],
+);
+
+memoNotifyChannel('channel1', { type: 'change', at: 0 }); // Executes
+memoNotifyChannel('channel2', { type: 'change', at: 0 }); // Executes (different key)
+memoNotifyChannel('channel1', { type: 'change', at: 0 }); // Skipped
+memoNotifyChannel('channel1', { type: 'change', at: 10 }); // Executes (values changed)
+
+// Key-based with onlyChanges
+function setFilter(filter: string, values: string[]): void {
+    console.log(filter, values);
+}
+
+const memoSetFilter = memoByKey(
+    setFilter,
+    (filter) => filter,
+    (filter, values) => values,
+    true,
+);
+
+memoSetFilter('filter1', []); // Skipped (initial)
+memoSetFilter('filter1', ['1']); // Executes (changed)
+```
+
+### DeepMap
+
+Map with array keys (nested key paths). Useful for hierarchical data.
+
+```typescript
+import { DeepMap } from '@just-io/utils';
+
+// Create empty or with initial entries
+const deepMap = new DeepMap<string, string>();
+const withEntries = new DeepMap<string, string>([
+    [['one'], 'str'],
+    [['one', 'two'], 'str'],
+]);
+
+// Copy from another DeepMap
+const copy = new DeepMap(withEntries);
+
+// Set and get with array keys
+deepMap.set([], 'root'); // Empty key path
+deepMap.set(['one'], 'first');
+deepMap.set(['one', 'two'], 'nested');
+
+deepMap.get(['one']); // 'first'
+deepMap.get(['one', 'two']); // 'nested'
+deepMap.get(['missing']); // undefined
+
+// Check existence
+deepMap.has(['one']); // true
+deepMap.has(['missing']); // false
+
+// Delete entries
+deepMap.delete(['one', 'two']); // returns true
+deepMap.delete(['missing']); // returns false
+
+// Take: get and delete in one operation
+const value = deepMap.take(['one']); // 'first', now deleted
+deepMap.take(['missing']); // undefined
+
+// Size and clear
+deepMap.size; // number of entries
+deepMap.clear(); // remove all
+
+// Iteration
+deepMap.forEach((value, key) => console.log(key, value));
+
+for (const [key, value] of deepMap) {
+    console.log(key, value);
+}
+
+Array.from(deepMap.entries()); // [[key, value], ...]
+Array.from(deepMap.keys()); // [key, ...]
+Array.from(deepMap.values()); // [value, ...]
+
+// Clone subtree (non-destructive)
+deepMap.set(['one'], 'str');
+deepMap.set(['one', 'two'], 'str');
+const cloned = deepMap.clone(['one']);
+// cloned: [[], 'str'], [['two'], 'str']
+
+// Extract subtree (removes from original)
+const extracted = deepMap.extract(['one']);
+// extracted has the subtree, deepMap no longer has it
+
+// Append entries under a prefix
+deepMap.append(['one'], [[['two'], 'str']]);
+// Result: [['one', 'two'], 'str']
+```
+
+### EventEmitter / Notifier
+
+Type-safe event handling.
+
+```typescript
+import { EventEmitter, EventTuple, Notifier } from '@just-io/utils';
+
+// Notifier - single event type
+type Event = [first: string, second: string];
+
+const notifier = new Notifier<Event>();
+
+const handler = (first: string, second: string) => console.log(first, second);
+notifier.subscribe(handler);
+notifier.notify('a', 'b'); // logs: a b
+
+// One-time subscription
+notifier.subscribe((a, b) => console.log('once:', a, b), { once: true });
+notifier.notify('x', 'y'); // Both handlers called
+notifier.notify('x', 'y'); // Only permanent handler
+
+notifier.unsubscribe(handler); // Remove specific
+notifier.unsubscribeAll(); // Remove all
+
+// EventEmitter - multiple named events
+type EventMap = {
+    one: [first: number];
+    two: [first: string, second: number];
+};
+
+const emitter = new EventEmitter<EventMap>();
+
+emitter.on('one', (first) => console.log('one:', first));
+emitter.on('two', (first, second) => console.log('two:', first, second));
+
+emitter.emit('one', 1);
+emitter.emit('two', '1', 2);
+
+// One-time listener
+emitter.once('one', (first) => console.log('once:', first));
+
+// Emit from tuple (useful for batching)
+type ETuple = EventTuple<EventMap>;
+const events: ETuple[] = [
+    ['one', 1],
+    ['two', '2', 1],
+];
+for (const event of events) {
+  emitter.emit(...event);
+}
+
+// Unsubscribe
+emitter.off('one', handler);
+emitter.unsubscribeAll('one'); // Remove all 'one' handlers
+emitter.unsubscribeAll(); // Remove all handlers
+
+// Event store - batch events and emit later
+const store = emitter.makeStore();
+store.add('one', 1);
+store.add('one', 2);
+store.emit(); // Emits both events
+store.emit(); // Does nothing (already emitted)
+```
+
+## License
+
+MIT

package/dist/cjs/deep-map.js

@@ -33,7 +33,7 @@ class DeepMap extends Map {
     }
     set(keys, value) {
         let node = __classPrivateFieldGet(this, _DeepMap_rootNode, "f");
-        for (const key of (Array.isArray(keys) ? keys : [keys])) {
+        for (const key of Array.isArray(keys) ? keys : [keys]) {
             if (!node.children.has(key)) {
                 node.children.set(key, {
                     children: new Map(),
@@ -50,7 +50,7 @@ class DeepMap extends Map {
     }
     has(keys) {
         let node = __classPrivateFieldGet(this, _DeepMap_rootNode, "f");
-        for (const key of (Array.isArray(keys) ? keys : [keys])) {
+        for (const key of Array.isArray(keys) ? keys : [keys]) {
             if (!node.children.has(key)) {
                 return false;
             }
@@ -61,7 +61,7 @@ class DeepMap extends Map {
     delete(keys) {
         let node = __classPrivateFieldGet(this, _DeepMap_rootNode, "f");
         const entries = [[undefined, __classPrivateFieldGet(this, _DeepMap_rootNode, "f")]];
-        for (const key of (Array.isArray(keys) ? keys : [keys])) {
+        for (const key of Array.isArray(keys) ? keys : [keys]) {
             if (!node.children.has(key)) {
                 return false;
             }
@@ -129,7 +129,7 @@ class DeepMap extends Map {
     }
     [(_DeepMap_rootNode = new WeakMap(), _DeepMap_instances = new WeakSet(), _DeepMap_node = function _DeepMap_node(keys) {
         let node = __classPrivateFieldGet(this, _DeepMap_rootNode, "f");
-        for (const key of (Array.isArray(keys) ? keys : [keys])) {
+        for (const key of Array.isArray(keys) ? keys : [keys]) {
             if (!node.children.has(key)) {
                 return undefined;
             }

package/dist/cjs/event-emitter.js

@@ -10,9 +10,9 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
-var _Notifier_subscribers, _Notifier_onceSubscribers, _EventEmitter_subscribers, _EventEmitter_onceSubscribers;
+var _Notifier_subscribers, _Notifier_onceSubscribers, _EventStore_eventEmitter, _EventStore_eventTuples, _EventEmitter_subscribers, _EventEmitter_onceSubscribers;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventEmitter = exports.Notifier = void 0;
+exports.EventEmitter = exports.EventStore = exports.Notifier = void 0;
 class Notifier {
     constructor() {
         _Notifier_subscribers.set(this, new Set());
@@ -40,12 +40,38 @@ class Notifier {
             }
         });
     }
-    clear() {
+    unsubscribeAll() {
         __classPrivateFieldSet(this, _Notifier_subscribers, new Set(), "f");
+        __classPrivateFieldSet(this, _Notifier_onceSubscribers, new WeakSet(), "f");
     }
 }
 exports.Notifier = Notifier;
 _Notifier_subscribers = new WeakMap(), _Notifier_onceSubscribers = new WeakMap();
+class EventStore {
+    constructor(eventEmitter) {
+        _EventStore_eventEmitter.set(this, void 0);
+        _EventStore_eventTuples.set(this, []);
+        __classPrivateFieldSet(this, _EventStore_eventEmitter, eventEmitter, "f");
+    }
+    add(event, ...args) {
+        __classPrivateFieldGet(this, _EventStore_eventTuples, "f").push([event, ...args]);
+    }
+    emit() {
+        for (const eventTuple of __classPrivateFieldGet(this, _EventStore_eventTuples, "f")) {
+            __classPrivateFieldGet(this, _EventStore_eventEmitter, "f").emit(...eventTuple);
+        }
+        __classPrivateFieldSet(this, _EventStore_eventTuples, [], "f");
+    }
+    consume(eventStore) {
+        __classPrivateFieldGet(this, _EventStore_eventTuples, "f").push(...__classPrivateFieldGet(eventStore, _EventStore_eventTuples, "f"));
+        __classPrivateFieldSet(eventStore, _EventStore_eventTuples, [], "f");
+    }
+    clean() {
+        __classPrivateFieldSet(this, _EventStore_eventTuples, [], "f");
+    }
+}
+exports.EventStore = EventStore;
+_EventStore_eventEmitter = new WeakMap(), _EventStore_eventTuples = new WeakMap();
 class EventEmitter {
     constructor() {
         _EventEmitter_subscribers.set(this, {});
@@ -86,9 +112,18 @@ class EventEmitter {
             }
         });
     }
-    clear() {
-        __classPrivateFieldSet(this, _EventEmitter_subscribers, {}, "f");
-        __classPrivateFieldSet(this, _EventEmitter_onceSubscribers, {}, "f");
+    unsubscribeAll(event) {
+        if (event) {
+            __classPrivateFieldGet(this, _EventEmitter_subscribers, "f")[event] = new Set();
+            __classPrivateFieldGet(this, _EventEmitter_onceSubscribers, "f")[event] = new WeakSet();
+        }
+        else {
+            __classPrivateFieldSet(this, _EventEmitter_subscribers, {}, "f");
+            __classPrivateFieldSet(this, _EventEmitter_onceSubscribers, {}, "f");
+        }
+    }
+    makeStore() {
+        return new EventStore(this);
     }
 }
 exports.EventEmitter = EventEmitter;

package/dist/mjs/deep-map.js

@@ -12,7 +12,7 @@ export class DeepMap extends Map {
     }
     #node(keys) {
         let node = this.#rootNode;
-        for (const key of (Array.isArray(keys) ? keys : [keys])) {
+        for (const key of Array.isArray(keys) ? keys : [keys]) {
             if (!node.children.has(key)) {
                 return undefined;
             }
@@ -35,7 +35,7 @@ export class DeepMap extends Map {
     }
     set(keys, value) {
         let node = this.#rootNode;
-        for (const key of (Array.isArray(keys) ? keys : [keys])) {
+        for (const key of Array.isArray(keys) ? keys : [keys]) {
             if (!node.children.has(key)) {
                 node.children.set(key, {
                     children: new Map(),
@@ -51,7 +51,7 @@ export class DeepMap extends Map {
     }
     has(keys) {
         let node = this.#rootNode;
-        for (const key of (Array.isArray(keys) ? keys : [keys])) {
+        for (const key of Array.isArray(keys) ? keys : [keys]) {
             if (!node.children.has(key)) {
                 return false;
             }
@@ -62,7 +62,7 @@ export class DeepMap extends Map {
     delete(keys) {
         let node = this.#rootNode;
         const entries = [[undefined, this.#rootNode]];
-        for (const key of (Array.isArray(keys) ? keys : [keys])) {
+        for (const key of Array.isArray(keys) ? keys : [keys]) {
             if (!node.children.has(key)) {
                 return false;
             }

package/dist/mjs/event-emitter.js

@@ -23,8 +23,32 @@ export class Notifier {
             }
         });
     }
-    clear() {
+    unsubscribeAll() {
         this.#subscribers = new Set();
+        this.#onceSubscribers = new WeakSet();
+    }
+}
+export class EventStore {
+    #eventEmitter;
+    #eventTuples = [];
+    constructor(eventEmitter) {
+        this.#eventEmitter = eventEmitter;
+    }
+    add(event, ...args) {
+        this.#eventTuples.push([event, ...args]);
+    }
+    emit() {
+        for (const eventTuple of this.#eventTuples) {
+            this.#eventEmitter.emit(...eventTuple);
+        }
+        this.#eventTuples = [];
+    }
+    consume(eventStore) {
+        this.#eventTuples.push(...eventStore.#eventTuples);
+        eventStore.#eventTuples = [];
+    }
+    clean() {
+        this.#eventTuples = [];
     }
 }
 export class EventEmitter {
@@ -63,8 +87,17 @@ export class EventEmitter {
             }
         });
     }
-    clear() {
-        this.#subscribers = {};
-        this.#onceSubscribers = {};
+    unsubscribeAll(event) {
+        if (event) {
+            this.#subscribers[event] = new Set();
+            this.#onceSubscribers[event] = new WeakSet();
+        }
+        else {
+            this.#subscribers = {};
+            this.#onceSubscribers = {};
+        }
+    }
+    makeStore() {
+        return new EventStore(this);
     }
 }

package/dist/types/event-emitter.d.ts

@@ -13,7 +13,7 @@ export declare class Notifier<E extends unknown[]> implements Notifiable<E> {
     }): this;
     unsubscribe(subscriber: Subscriber<E>): boolean;
     notify(...args: E): void;
-    clear(): void;
+    unsubscribeAll(): void;
 }
 export type EventMap = Record<string, unknown[]>;
 export interface Eventable<E extends EventMap> {
@@ -21,9 +21,18 @@ export interface Eventable<E extends EventMap> {
     once<K extends keyof E>(event: K, subscriber: Subscriber<E[K]>): this;
     off<K extends keyof E>(event: K, subscriber: Subscriber<E[K]>): boolean;
 }
-export type EventList<E extends EventMap> = {
+export type EventTuple<E extends EventMap> = {
     [K in keyof E]: [K, ...E[K]];
 }[keyof E];
+export declare class EventStore<E extends EventMap> {
+    #private;
+    constructor(eventEmitter: EventEmitter<E>);
+    add<K extends keyof E>(event: K, ...args: E[K]): void;
+    add(...eventTuple: EventTuple<E>): void;
+    emit(): void;
+    consume(eventStore: EventStore<E>): void;
+    clean(): void;
+}
 export declare class EventEmitter<E extends EventMap> implements Eventable<E> {
     #private;
     getSuscribers<K extends keyof E>(event: K): Set<Subscriber<E[K]>>;
@@ -31,6 +40,8 @@ export declare class EventEmitter<E extends EventMap> implements Eventable<E> {
     once<K extends keyof E>(event: K, subscriber: Subscriber<E[K]>): this;
     off<K extends keyof E>(event: K, subscriber: Subscriber<E[K]>): boolean;
     emit<K extends keyof E>(event: K, ...args: E[K]): void;
-    emit(...eventList: EventList<E>): void;
-    clear(): void;
+    emit(...eventTuple: EventTuple<E>): void;
+    unsubscribeAll(): void;
+    unsubscribeAll<K extends keyof E>(event: K): void;
+    makeStore(): EventStore<E>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@just-io/utils",
-  "version": "1.5.0",
+  "version": "2.0.1",
   "description": "Utility functional",
   "types": "dist/types",
   "main": "dist/cjs/index.js",