@softsky/utils 2.8.0 → 2.8.2

package/README.md

@@ -301,7 +301,7 @@ Returns a target and map of parents.
 You can use `unfoldPathfindingResult()` to get array of nodes.
 
 ---
-__function__ `dijkstra` - Dijkstra search. Like bfs but supports weight and target is required.
+__function__ `dijkstra` - Dijkstra search. Like bfs but supports weight.
 If isTarget is omitted becomes floodfill (WITH WEIGHT).
 Returns a target and map of parents.
 You can use `unfoldPathfindingResult()` to get array of nodes.
@@ -440,7 +440,7 @@ 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())
@@ -451,6 +451,7 @@ const mySignal = $mySignal()
 if(last>mySignal) console.log('Increment!')
 return mySignal;
 })
+```
 
 ---
 __function__ `untrack` - __SIGNALS SYSTEM__
@@ -466,7 +467,7 @@ console.log(untrack($a)+$b())
 ```
 
 ---
-__function__ `derived` - __SIGNALS SYSTEM__
+__function__ `computed` - __SIGNALS SYSTEM__
 
 Creates a derived reactive memoized signal.
 
@@ -509,6 +510,52 @@ const timeout = setTimeout(() => promise.reject('Timeout')}, 5000)
 primise.then(() => clearTimeout(timeout))
 ```
 
+---
+__function__ `resource` - __SIGNALS SYSTEM__
+
+Creates a async resource with outputs:
+1. value$ - return value of function
+2. isLoading$ - whether promise is still running
+3. error$ - error that happened during. Set on error, cleared on refresh
+4. refresh - force rerun handler
+
+MAKE SURE THAT ALL SIGNAL'S VALUES ARE GRABBED BEFORE NEXT TICK!!!
+
+```ts
+const userId$ = signal(1);
+
+// WRONG
+const userResource = resource(async () => {
+const res = await fetch(`/api/user`)
+const userId = userId$();  // ERROR: Will not subscribe because after Promise i.e. next tick
+return res.json().find(x=>x.id===userId);
+})
+
+// Correct
+const userResource = resource(async () => {
+const userId = userId$(); // Correctly subscribed because ran on the same tick
+const res = await fetch(`/api/user`)
+return res.json().find(x=>x.id===userId);
+})
+
+// React to changes
+effect(() => {
+if (userResource.isLoading$()) {
+console.log('loading user...')
+} else if (userResource.error$()) {
+console.error('failed to load user', userResource.error$())
+} else {
+console.log('user loaded', userResource.value$())
+}
+})
+
+// Force a refresh
+userResource.refresh()
+
+// Stop automatic updates and cleanup
+userResource.clear()
+```
+
 ---
 
 
@@ -622,3 +669,11 @@ b: "b";
 ```
 
 ---
+__type__ `Tuple` - Create a tuple of size.
+
+```ts
+type a = Tuple<number, 3>
+type b = [number, number, number]
+```
+
+---

package/dist/arrays.d.ts

@@ -29,9 +29,8 @@ export declare function permutations<T>(array: T[]): T[][];
  * If compare returns > 0 it means target is smaller.
  * If compare returns < 0 it means target is bigger.
  *
- * ```ts
+ * @example
  * pushToSorted(numArray, 10,  x => x - 10);
- * ```
  */
 export declare function pushToSorted<T>(array: T[], element: T, compare: (x: T) => number): void;
 /**

package/dist/arrays.js

@@ -101,9 +101,8 @@ export function permutations(array) {
  * If compare returns > 0 it means target is smaller.
  * If compare returns < 0 it means target is bigger.
  *
- * ```ts
+ * @example
  * pushToSorted(numArray, 10,  x => x - 10);
- * ```
  */
 export function pushToSorted(array, element, compare) {
     const index = binarySearch(array.length, (x) => compare(array[x]), true);

package/dist/control.d.ts

@@ -80,7 +80,7 @@ export declare class SimpleEventSource<EVENTS extends Record<string, unknown>> {
 /**
  * Semaphore is used to limit concurrent tasks by delaying promise.
  *
- * ```ts
+ * @example
  * const semaphore = new Semaphore(2);
  *
  * async function task() {
@@ -103,7 +103,6 @@ export declare class SimpleEventSource<EVENTS extends Record<string, unknown>> {
  *    // Your code
  * })
  * // ...
- * ```
  */
 export declare class Semaphore {
     /** The maximum number of concurrent operations allowed.*/

package/dist/control.js

@@ -225,7 +225,7 @@ export class SimpleEventSource {
 /**
  * Semaphore is used to limit concurrent tasks by delaying promise.
  *
- * ```ts
+ * @example
  * const semaphore = new Semaphore(2);
  *
  * async function task() {
@@ -248,7 +248,6 @@ export class SimpleEventSource {
  *    // Your code
  * })
  * // ...
- * ```
  */
 export class Semaphore {
     capacity;

package/dist/formatting.d.ts

@@ -43,14 +43,13 @@ 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
+ * @example
  * // 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;

package/dist/graphs.d.ts

@@ -60,7 +60,7 @@ export declare function dfs<T>(options: {
     target?: T;
 };
 /**
- * Dijkstra search. Like bfs but supports weight and target is required.
+ * Dijkstra search. Like bfs but supports weight.
  * If isTarget is omitted becomes floodfill (WITH WEIGHT).
  * Returns a target and map of parents.
  * You can use `unfoldPathfindingResult()` to get array of nodes.

package/dist/graphs.js

@@ -110,7 +110,7 @@ export function dfs(options) {
     };
 }
 /**
- * Dijkstra search. Like bfs but supports weight and target is required.
+ * Dijkstra search. Like bfs but supports weight.
  * If isTarget is omitted becomes floodfill (WITH WEIGHT).
  * Returns a target and map of parents.
  * You can use `unfoldPathfindingResult()` to get array of nodes.

package/dist/numbers.d.ts

@@ -17,11 +17,10 @@ export declare function mean(array: number[]): number;
 /**
  * Round with precision.
  *
- * ```ts
+ * @example
  * round(1.2345); // 1
  * round(1.2345, 2); // 1.23
  * round(1.2345, 10); // 1.2345
- * ```
  */
 export declare function round(value: number, precision?: number): number;
 /** Sum of array of numbers */

package/dist/numbers.js

@@ -66,11 +66,10 @@ export function mean(array) {
 /**
  * Round with precision.
  *
- * ```ts
+ * @example
  * round(1.2345); // 1
  * round(1.2345, 2); // 1.23
  * round(1.2345, 10); // 1.2345
- * ```
  */
 export function round(value, precision = 0) {
     const mult = 10 ** precision;

package/dist/signals.d.ts

@@ -11,7 +11,7 @@ export type Signal<T> = (setTo?: T | ((previous: T) => T)) => T;
  * when this data has changed any effects containing
  * this signal will be rerun.
  *
- * ```ts
+ * @example
  * const $mySignal = signal<number|undefined>(1) // Create signal with initial value 1
  * $mySignal(5) // Set to 5
  * $mySignal(undefined) // Set to undefined
@@ -20,7 +20,6 @@ export type Signal<T> = (setTo?: T | ((previous: T) => T)) => T;
  * effect(()=>{
  *   console.log($mySignal())
  * })
- * ```
  */
 export declare function signal<T>(): Signal<T | undefined>;
 export declare function signal<T>(value: T): Signal<T>;
@@ -31,7 +30,7 @@ export declare function signal<T>(value: T): Signal<T>;
  * Returned data from handler function will be passed to it on next signal change.
  * Returns a function that will clear the effect.
  *
- *
+ * @example
  * // Will print signal on change
  * effect(()=>{
  *   console.log($mySignal())
@@ -48,14 +47,13 @@ export declare function effect<T>(handler: (argument: T | undefined) => T, initi
  * __SIGNALS SYSTEM__
  *
  * Untrack helps to not react to changes in effects.
- * ```ts
+ * @example
  * 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;
 /**
@@ -63,16 +61,15 @@ export declare function untrack<T>(handler: () => T): T;
  *
  * Creates a derived reactive memoized signal.
  *
- * ```ts
+ * @example
  * // 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): {
+export declare function computed<T>(handler: (argument: T | undefined) => T): {
     signal: Signal<T>;
     clear: () => void;
 };
-export declare function derived<T>(handler: (argument: T) => T, initialValue: T): {
+export declare function computed<T>(handler: (argument: T) => T, initialValue: T): {
     signal: Signal<T>;
     clear: () => void;
 };
@@ -81,7 +78,7 @@ export declare function derived<T>(handler: (argument: T) => T, initialValue: T)
  *
  * Batches multiple edits, so they don't call same effects multiple times
  *
- * ```ts
+ * @example
  * const $a = signal(1)
  * const $b = signal(2)
  * effect(()=>{
@@ -94,7 +91,6 @@ export declare function derived<T>(handler: (argument: T) => T, initialValue: T)
  *  $a(5);
  *  $b(5);
  * })
- * ```
  */
 export declare function batch(handler: AnyFunction): void;
 /**
@@ -103,12 +99,65 @@ export declare function batch(handler: AnyFunction): void;
  * Returns ImmediatePromise that is resolved when check function returns truthy value.
  * If you want to, you can resolve or reject promise beforehand.
  *
- * ```ts
+ * @example
  * 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>;
+export type ResourceReturnType<T> = {
+    value$: Signal<T>;
+    isLoading$: Signal<boolean>;
+    error$: Signal<unknown>;
+    refresh: () => Promise<T | undefined>;
+    clear: () => void;
+};
+/**
+ * __SIGNALS SYSTEM__
+ *
+ * Creates a async resource with outputs:
+ * 1. value$ - return value of function
+ * 2. isLoading$ - whether promise is still running
+ * 3. error$ - error that happened during. Set on error, cleared on refresh
+ * 4. refresh - force rerun handler
+ *
+ * MAKE SURE THAT ALL SIGNAL'S VALUES ARE GRABBED BEFORE NEXT TICK!!!
+ *
+ * @example
+ * const userId$ = signal(1);
+ *
+ * // WRONG
+ * const userResource = resource(async () => {
+ *   const res = await fetch(`/api/user`)
+ *   const userId = userId$();  // ERROR: Will not subscribe because after Promise i.e. next tick
+ *   return res.json().find(x=>x.id===userId);
+ * })
+ *
+ * // Correct
+ * const userResource = resource(async () => {
+ *   const userId = userId$(); // Correctly subscribed because ran on the same tick
+ *   const res = await fetch(`/api/user`)
+ *   return res.json().find(x=>x.id===userId);
+ * })
+ *
+ * // React to changes
+ * effect(() => {
+ *   if (userResource.isLoading$()) {
+ *     console.log('loading user...')
+ *   } else if (userResource.error$()) {
+ *     console.error('failed to load user', userResource.error$())
+ *   } else {
+ *     console.log('user loaded', userResource.value$())
+ *   }
+ * })
+ *
+ * // Force a refresh
+ * userResource.refresh()
+ *
+ * // Stop automatic updates and cleanup
+ * userResource.clear()
+ */
+export declare function resource<T>(handler: (argument: T | undefined) => Promise<T>): ResourceReturnType<T | undefined>;
+export declare function resource<T>(handler: (argument: T) => Promise<T>, initialValue: T): ResourceReturnType<T>;

package/dist/signals.js

@@ -47,7 +47,7 @@ function clearEffect(handler) {
  * Returned data from handler function will be passed to it on next signal change.
  * Returns a function that will clear the effect.
  *
- *
+ * @example
  * // Will print signal on change
  * effect(()=>{
  *   console.log($mySignal())
@@ -75,14 +75,13 @@ export function effect(handler, initialValue) {
  * __SIGNALS SYSTEM__
  *
  * Untrack helps to not react to changes in effects.
- * ```ts
+ * @example
  * 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;
@@ -91,7 +90,7 @@ export function untrack(handler) {
     currentEffect = lastEffect;
     return data;
 }
-export function derived(handler, initialValue) {
+export function computed(handler, initialValue) {
     const signal$ = signal(initialValue);
     const wrappedHandler = () => signal$((value) => handler(value));
     currentEffect = wrappedHandler;
@@ -109,7 +108,7 @@ export function derived(handler, initialValue) {
  *
  * Batches multiple edits, so they don't call same effects multiple times
  *
- * ```ts
+ * @example
  * const $a = signal(1)
  * const $b = signal(2)
  * effect(()=>{
@@ -122,7 +121,6 @@ export function derived(handler, initialValue) {
  *  $a(5);
  *  $b(5);
  * })
- * ```
  */
 export function batch(handler) {
     batchedEffects = new Set();
@@ -137,13 +135,12 @@ export function batch(handler) {
  * Returns ImmediatePromise that is resolved when check function returns truthy value.
  * If you want to, you can resolve or reject promise beforehand.
  *
- * ```ts
+ * @example
  * 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();
@@ -156,3 +153,42 @@ export function when(check) {
     });
     return promise;
 }
+export function resource(handler, initialValue) {
+    const value$ = signal(initialValue);
+    const isLoading$ = signal(false);
+    const error$ = signal();
+    const wrappedHandler = async () => {
+        batch(() => {
+            isLoading$(true);
+            error$(undefined);
+        });
+        let value;
+        let error;
+        try {
+            value = await handler(untrack(value$));
+        }
+        catch (newError) {
+            error = newError;
+        }
+        batch(() => {
+            if (error)
+                error$(error);
+            else
+                value$(value);
+            isLoading$(false);
+        });
+        return value;
+    };
+    currentEffect = wrappedHandler;
+    void wrappedHandler();
+    currentEffect = undefined;
+    return {
+        value$,
+        isLoading$,
+        error$,
+        refresh: wrappedHandler,
+        clear: () => {
+            clearEffect(wrappedHandler);
+        },
+    };
+}

package/dist/types.d.ts

@@ -8,9 +8,9 @@ export type AnyFunction = (...data: any[]) => any;
 /** Values that convert to false */
 export type Falsy = false | '' | 0 | null | undefined;
 /** Make keys in object optional */
-export type Optional<T, K extends keyof T> = Omit<T, K & keyof T> & Partial<Pick<T, K & keyof T>>;
+export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 /** Make keys in object required */
-export type RequiredKey<T, K extends keyof T> = Omit<T, K & keyof T> & Required<Pick<T, K & keyof T>>;
+export type RequiredKey<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
 /** Get contructor type of an instance */
 export type Constructor<T> = new (..._arguments: any[]) => T;
 /** Recursively resolves promises in objects and arrays */
@@ -42,7 +42,7 @@ export type Concat<T, U> = T extends any[] ? U extends any[] ? [...T, ...U] : ne
 /**
  * Visual only overhaul. Shows final type result on hover.
  *
- * ```ts
+ * @example
  * type a = {a: '1'}
  * type b = Prettify<a & { b: 'b' }>
  * // On hovering b it will show
@@ -54,8 +54,15 @@ export type Concat<T, U> = T extends any[] ? U extends any[] ? [...T, ...U] : ne
  * type b = a & {
  *   b: "b";
  * }
- * ```
  * */
 export type Prettify<T extends object> = {
     [k in keyof T]: T[k];
 } & {};
+/**
+ * Create a tuple of size.
+ *
+ * @example
+ * type a = Tuple<number, 3>
+ * type b = [number, number, number]
+ */
+export type Tuple<T, N extends number, R extends readonly T[] = []> = R['length'] extends N ? R : Tuple<T, N, [...R, T]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softsky/utils",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "description": "JavaScript/TypeScript utilities",
   "main": "dist/index.js",
   "scripts": {
@@ -20,8 +20,8 @@
   },
   "homepage": "https://github.com/SoundOfTheSky/utils#readme",
   "devDependencies": {
-    "@softsky/configs": "^1.3.4",
-    "@types/bun": "^1.2.23"
+    "@softsky/configs": "^1.3.5",
+    "@types/bun": "^1.3.2"
   },
   "files": ["dist/**/*"]
 }