@softsky/utils 2.1.0 → 2.3.0

package/README.md

@@ -183,6 +183,18 @@ ${\textsf{\color{CornflowerBlue}function}}$ log - Format logging
 ---
 ${\textsf{\color{CornflowerBlue}function}}$ capitalizeFirstLetter - Capitalize first letter
 
+---
+${\textsf{\color{CornflowerBlue}function}}$ pipe - pipe() can be called on one or more functions, each of which can take the return of previous value.
+
+```ts
+// Takes string, converts to int, calc sqrt, convert and return date
+pipe(
+(x: string) => Number.parseInt(x),
+(x) => Math.sqrt(x),
+(x) => new Date(x)
+)('69')
+```
+
 ---
 
 
@@ -254,6 +266,105 @@ this.registerSubclass()
 ---
 
 
+## Signals
+Reactive signals
+
+${\textsf{\color{CornflowerBlue}function}}$ signal - __SIGNALS SYSTEM__
+
+Signal can hold any data (except functions),
+when this data has changed any effects containing
+this signal will be rerun.
+
+```ts
+const $mySignal = signal<number|undefined>(1) // Create signal with initial value 1
+$mySignal(5) // Set to 5
+$mySignal(undefined) // Set to undefined
+$mySignal(prev=>prev+1) // Increment
+// Will print signal on change
+effect(()=>{
+console.log($mySignal())
+})
+```
+
+---
+${\textsf{\color{CornflowerBlue}function}}$ effect - __SIGNALS SYSTEM__
+
+Effects are simplest way to react to signal changes.
+Returned data from handler function will be passed to it on next signal change.
+Returns a function that will clear the effect.
+
+```ts
+// Will print signal on change
+effect(()=>{
+console.log($mySignal())
+})
+// Use previous state as a reference
+effect((last)=>{
+const mySignal = $mySignal()
+if(last>mySignal) console.log('Increment!')
+return mySignal;
+})
+
+---
+${\textsf{\color{CornflowerBlue}function}}$ untrack - __SIGNALS SYSTEM__
+
+Untrack helps to not react to changes in effects.
+```ts
+const $a = signal(1)
+const $b = signal(2)
+// Will only run on changes to $b
+effect(()=>{
+console.log(untrack($a)+$b())
+})
+```
+
+---
+${\textsf{\color{CornflowerBlue}function}}$ derived - __SIGNALS SYSTEM__
+
+Creates a derived reactive memoized signal.
+
+```ts
+// Sum of all changes of $a()
+const { signal: $sumOfTwo, clear: clearSum } = derived((value) => value + $a(), 0)
+```
+
+---
+${\textsf{\color{CornflowerBlue}function}}$ batch - __SIGNALS SYSTEM__
+
+Batches multiple edits, so they don't call same effects multiple times
+
+```ts
+const $a = signal(1)
+const $b = signal(2)
+effect(()=>{
+console.log($a()+$b())
+})
+$a(2); // Prints 4
+$b(3); // Prints 5
+// Prints only 10
+batch(()=>{
+$a(5);
+$b(5);
+})
+```
+
+---
+${\textsf{\color{CornflowerBlue}function}}$ when - __SIGNALS SYSTEM__
+
+Returns ImmediatePromise that is resolved when check function returns truthy value.
+If you want to, you can resolve or reject promise beforehand.
+
+```ts
+await when(() => $a()>5)
+// With timeout
+const promise = when(() => $a() > 5)
+const timeout = setTimeout(() => promise.reject('Timeout')}, 5000)
+primise.then(() => clearTimeout(timeout))
+```
+
+---
+
+
 ## Time
 Timers, CRON, etc.
 
@@ -289,6 +400,9 @@ Damn, I **love** TypeScript.
 
 ${\textsf{\color{Magenta}type}}$ Primitive - Values that are copied by value, not by reference
 
+---
+${\textsf{\color{Magenta}type}}$ AnyFunction - Function with any arguments or return type
+
 ---
 ${\textsf{\color{Magenta}type}}$ Falsy - Values that convert to false
 

package/dist/control.d.ts

@@ -31,11 +31,12 @@ export declare function createThrottledFunction<T, V extends unknown[]>(function
 /** Create debounced function. Basically create function that will be called with delay,
  * but if another call comes in, we reset the timer. */
 export declare function createDelayedFunction<T, V extends unknown[]>(function_: (...arguments_: V) => T, time: number): (...arguments_: V) => Promise<T>;
+type ResolveFunction<T> = undefined extends T ? (value?: T | PromiseLike<T>) => void : (value: T | PromiseLike<T>) => void;
 /** Promise that accepts no callback, but exposes `resolve` and `reject` methods */
 export declare class ImmediatePromise<T> extends Promise<T> {
-    resolve: (value: T | PromiseLike<T>) => void;
+    resolve: ResolveFunction<T>;
     reject: (reason?: unknown) => void;
-    constructor(execute?: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void);
+    constructor(execute?: (resolve: ResolveFunction<T>, reject: (reason?: any) => void) => void);
 }
 /** Recursively resolves promises in objects and arrays */
 export default function deepPromiseAll<T>(input: T): Promise<AwaitedObject<T>>;
@@ -45,3 +46,4 @@ export declare function wait(time: number): Promise<unknown>;
 export declare function noop(): void;
 /** Run array of async tasks concurrently */
 export declare function concurrentRun<T>(tasks: (() => Promise<T>)[], concurrency?: number): Promise<T[]>;
+export {};

package/dist/control.js

@@ -113,6 +113,7 @@ export class ImmediatePromise extends Promise {
     resolve;
     reject;
     constructor(execute) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
         if (execute)
             super(execute);
         else {

package/dist/formatting.d.ts

@@ -40,3 +40,26 @@ export declare function formatBytes(bytes: number): string;
 export declare function log(...agrs: unknown[]): void;
 /** Capitalize first letter */
 export declare function capitalizeFirstLetter(value: string): string;
+/**
+ * pipe() can be called on one or more functions, each of which can take the return of previous value.
+ *
+ * ```ts
+ * // Takes string, converts to int, calc sqrt, convert and return date
+ * pipe(
+ *  (x: string) => Number.parseInt(x),
+ *  (x) => Math.sqrt(x),
+ *  (x) => new Date(x)
+ * )('69')
+ * ```
+ */
+export declare function pipe(): <T>(x: T) => T;
+export declare function pipe<T, A>(function1: (x: T) => A): (x: T) => A;
+export declare function pipe<T, A, B>(function1: (x: T) => A, function2: (x: A) => B): (x: T) => B;
+export declare function pipe<T, A, B, C>(function1: (x: T) => A, function2: (x: A) => B, function3: (x: B) => C): (x: T) => C;
+export declare function pipe<T, A, B, C, D>(function1: (x: T) => A, function2: (x: A) => B, function3: (x: B) => C, function4: (x: C) => D): (x: T) => D;
+export declare function pipe<T, A, B, C, D, E>(function1: (x: T) => A, function2: (x: A) => B, function3: (x: B) => C, function4: (x: C) => D, function5: (x: D) => E): (x: T) => E;
+export declare function pipe<T, A, B, C, D, E, F>(function1: (x: T) => A, function2: (x: A) => B, function3: (x: B) => C, function4: (x: C) => D, function5: (x: D) => E, function6: (x: E) => F): (x: T) => F;
+export declare function pipe<T, A, B, C, D, E, F, G>(function1: (x: T) => A, function2: (x: A) => B, function3: (x: B) => C, function4: (x: C) => D, function5: (x: D) => E, function6: (x: E) => F, function7: (x: F) => G): (x: T) => G;
+export declare function pipe<T, A, B, C, D, E, F, G, H>(function1: (x: T) => A, function2: (x: A) => B, function3: (x: B) => C, function4: (x: C) => D, function5: (x: D) => E, function6: (x: E) => F, function7: (x: F) => G, function8: (x: G) => H): (x: T) => H;
+export declare function pipe<T, A, B, C, D, E, F, G, H, I>(function1: (x: T) => A, function2: (x: A) => B, function3: (x: B) => C, function4: (x: C) => D, function5: (x: D) => E, function6: (x: E) => F, function7: (x: F) => G, function8: (x: G) => H, function9: (x: H) => I): (x: T) => I;
+export declare function pipe<T, A, B, C, D, E, F, G, H>(function1: (x: T) => A, function2: (x: A) => B, function3: (x: B) => C, function4: (x: C) => D, function5: (x: D) => E, function6: (x: E) => F, function7: (x: F) => G, function8: (x: G) => H, function9: (x: H) => unknown, ...fns: ((x: unknown) => unknown)[]): (x: T) => unknown;

package/dist/formatting.js

@@ -117,3 +117,10 @@ export function log(...agrs) {
 export function capitalizeFirstLetter(value) {
     return value.charAt(0).toUpperCase() + value.slice(1);
 }
+export function pipe(...fns) {
+    return (input) => {
+        for (let index = 0; index < fns.length; index++)
+            input = fns[index](input);
+        return input;
+    };
+}

package/dist/index.d.ts

@@ -5,5 +5,6 @@ export * from './errors';
 export * from './formatting';
 export * from './numbers';
 export * from './objects';
+export * from './signals';
 export * from './time';
 export * from './types';

package/dist/index.js

@@ -5,5 +5,6 @@ export * from './errors';
 export * from './formatting';
 export * from './numbers';
 export * from './objects';
+export * from './signals';
 export * from './time';
 export * from './types';

package/dist/signals.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Reactive signals
+ */
+import { ImmediatePromise } from './control';
+import { AnyFunction } from './types';
+export type Signal<T> = (setTo?: T | ((previous: T) => T)) => T;
+/**
+ * __SIGNALS SYSTEM__
+ *
+ * Signal can hold any data (except functions),
+ * when this data has changed any effects containing
+ * this signal will be rerun.
+ *
+ * ```ts
+ * const $mySignal = signal<number|undefined>(1) // Create signal with initial value 1
+ * $mySignal(5) // Set to 5
+ * $mySignal(undefined) // Set to undefined
+ * $mySignal(prev=>prev+1) // Increment
+ * // Will print signal on change
+ * effect(()=>{
+ *   console.log($mySignal())
+ * })
+ * ```
+ */
+export declare function signal<T>(): Signal<T | undefined>;
+export declare function signal<T>(value: T): Signal<T>;
+/**
+ * __SIGNALS SYSTEM__
+ *
+ * Effects are simplest way to react to signal changes.
+ * Returned data from handler function will be passed to it on next signal change.
+ * Returns a function that will clear the effect.
+ *
+ * ```ts
+ * // Will print signal on change
+ * effect(()=>{
+ *   console.log($mySignal())
+ * })
+ * // Use previous state as a reference
+ * effect((last)=>{
+ *   const mySignal = $mySignal()
+ *   if(last>mySignal) console.log('Increment!')
+ *   return mySignal;
+ * })
+ */
+export declare function effect<T>(handler: (argument: T | undefined) => T, initialValue?: T): () => void;
+/**
+ * __SIGNALS SYSTEM__
+ *
+ * Untrack helps to not react to changes in effects.
+ * ```ts
+ * const $a = signal(1)
+ * const $b = signal(2)
+ * // Will only run on changes to $b
+ * effect(()=>{
+ *   console.log(untrack($a)+$b())
+ * })
+ * ```
+ */
+export declare function untrack<T>(handler: () => T): T;
+/**
+ * __SIGNALS SYSTEM__
+ *
+ * Creates a derived reactive memoized signal.
+ *
+ * ```ts
+ * // Sum of all changes of $a()
+ * const { signal: $sumOfTwo, clear: clearSum } = derived((value) => value + $a(), 0)
+ * ```
+ */
+export declare function derived<T>(handler: (argument: T | undefined) => T): {
+    signal: Signal<T>;
+    clear: () => void;
+};
+export declare function derived<T>(handler: (argument: T) => T, initialValue: T): {
+    signal: Signal<T>;
+    clear: () => void;
+};
+/**
+ * __SIGNALS SYSTEM__
+ *
+ * Batches multiple edits, so they don't call same effects multiple times
+ *
+ * ```ts
+ * const $a = signal(1)
+ * const $b = signal(2)
+ * effect(()=>{
+ *  console.log($a()+$b())
+ * })
+ * $a(2); // Prints 4
+ * $b(3); // Prints 5
+ * // Prints only 10
+ * batch(()=>{
+ *  $a(5);
+ *  $b(5);
+ * })
+ * ```
+ */
+export declare function batch(handler: AnyFunction): void;
+/**
+ * __SIGNALS SYSTEM__
+ *
+ * Returns ImmediatePromise that is resolved when check function returns truthy value.
+ * If you want to, you can resolve or reject promise beforehand.
+ *
+ * ```ts
+ * await when(() => $a()>5)
+ * // With timeout
+ * const promise = when(() => $a() > 5)
+ * const timeout = setTimeout(() => promise.reject('Timeout')}, 5000)
+ * primise.then(() => clearTimeout(timeout))
+ * ```
+ */
+export declare function when(check: () => unknown): ImmediatePromise<undefined>;

package/dist/signals.js

@@ -0,0 +1,158 @@
+/**
+ * Reactive signals
+ */
+import { ImmediatePromise } from './control';
+let currentEffect;
+const effectsMap = new WeakMap();
+let batchedEffects;
+export function signal(value) {
+    const subscribers = new Set();
+    return (...arguments_) => {
+        if (arguments_.length === 1) {
+            const argument = arguments_[0];
+            value =
+                typeof argument === 'function'
+                    ? argument(value)
+                    : argument;
+            if (batchedEffects)
+                for (const subscriber of subscribers)
+                    batchedEffects.add(subscriber);
+            else
+                for (const subscriber of subscribers)
+                    subscriber();
+        }
+        else if (currentEffect) {
+            subscribers.add(currentEffect);
+            // This is for clear() of effects
+            let effectSubscribers = effectsMap.get(currentEffect);
+            if (!effectSubscribers) {
+                effectSubscribers = new Set();
+                effectsMap.set(currentEffect, effectSubscribers);
+            }
+            effectSubscribers.add(subscribers);
+        }
+        return value;
+    };
+}
+function clearEffect(handler) {
+    const signalSubscribers = effectsMap.get(handler);
+    if (signalSubscribers)
+        for (const subscribers of signalSubscribers)
+            subscribers.delete(handler);
+}
+/**
+ * __SIGNALS SYSTEM__
+ *
+ * Effects are simplest way to react to signal changes.
+ * Returned data from handler function will be passed to it on next signal change.
+ * Returns a function that will clear the effect.
+ *
+ * ```ts
+ * // Will print signal on change
+ * effect(()=>{
+ *   console.log($mySignal())
+ * })
+ * // Use previous state as a reference
+ * effect((last)=>{
+ *   const mySignal = $mySignal()
+ *   if(last>mySignal) console.log('Increment!')
+ *   return mySignal;
+ * })
+ */
+export function effect(handler, initialValue) {
+    let lastValue = initialValue;
+    const wrappedHandler = () => {
+        lastValue = handler(lastValue);
+    };
+    currentEffect = wrappedHandler;
+    wrappedHandler();
+    currentEffect = undefined;
+    return () => {
+        clearEffect(wrappedHandler);
+    };
+}
+/**
+ * __SIGNALS SYSTEM__
+ *
+ * Untrack helps to not react to changes in effects.
+ * ```ts
+ * const $a = signal(1)
+ * const $b = signal(2)
+ * // Will only run on changes to $b
+ * effect(()=>{
+ *   console.log(untrack($a)+$b())
+ * })
+ * ```
+ */
+export function untrack(handler) {
+    const lastEffect = currentEffect;
+    currentEffect = undefined;
+    const data = handler();
+    currentEffect = lastEffect;
+    return data;
+}
+export function derived(handler, initialValue) {
+    const signal$ = signal(initialValue);
+    const wrappedHandler = () => signal$((value) => handler(value));
+    currentEffect = wrappedHandler;
+    wrappedHandler();
+    currentEffect = undefined;
+    return {
+        signal: signal$,
+        clear: () => {
+            clearEffect(wrappedHandler);
+        },
+    };
+}
+/**
+ * __SIGNALS SYSTEM__
+ *
+ * Batches multiple edits, so they don't call same effects multiple times
+ *
+ * ```ts
+ * const $a = signal(1)
+ * const $b = signal(2)
+ * effect(()=>{
+ *  console.log($a()+$b())
+ * })
+ * $a(2); // Prints 4
+ * $b(3); // Prints 5
+ * // Prints only 10
+ * batch(()=>{
+ *  $a(5);
+ *  $b(5);
+ * })
+ * ```
+ */
+export function batch(handler) {
+    batchedEffects = new Set();
+    handler();
+    for (const effect of batchedEffects)
+        effect();
+    batchedEffects = undefined;
+}
+/**
+ * __SIGNALS SYSTEM__
+ *
+ * Returns ImmediatePromise that is resolved when check function returns truthy value.
+ * If you want to, you can resolve or reject promise beforehand.
+ *
+ * ```ts
+ * await when(() => $a()>5)
+ * // With timeout
+ * const promise = when(() => $a() > 5)
+ * const timeout = setTimeout(() => promise.reject('Timeout')}, 5000)
+ * primise.then(() => clearTimeout(timeout))
+ * ```
+ */
+export function when(check) {
+    const promise = new ImmediatePromise();
+    const clear = effect(() => {
+        if (check())
+            promise.resolve();
+    });
+    void promise.finally(() => {
+        clear();
+    });
+    return promise;
+}

package/dist/types.d.ts

@@ -3,6 +3,8 @@
  */
 /** Values that are copied by value, not by reference */
 export type Primitive = string | number | bigint | boolean | symbol | null | undefined;
+/** Function with any arguments or return type */
+export type AnyFunction = (...arguments_: any[]) => any;
 /** Values that convert to false */
 export type Falsy = false | '' | 0 | null | undefined;
 /** Make keys in object optional */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softsky/utils",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "JavaScript/TypeScript utilities",
   "main": "dist/index.js",
   "scripts": {