@avstantso/concepts 1.0.4 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.1.0] - 2026-01-18
+
+### Added
+
+- `AbortSignal.Safe` - stub for functions that should not be called when signal is aborted
+
+### Changed
+
+- Updated all dependencies
+
 ## [1.0.4] - 2026-01-16
 
 ### Changed

package/README.md

@@ -20,6 +20,7 @@ AVStantso framework concepts providing reusable design patterns and abstractions
 - **Value Wrapper** - Value wrapping patterns with type preservation
 - **Async Tasks** - Asynchronous task management utilities
 - **Classic Enum** - Enhanced enum implementation with type safety
+- **AbortSignal.Safe** - Extension for safe function execution with abort signals
 
 ## Installation
 
@@ -84,6 +85,7 @@ import type { Provider, Compare, Switch } from '@avstantso/concepts';
 - [Value Wrap](#value-wrap)
 - [Async Tasks](#async-tasks)
 - [Classic Enum](#classic-enum)
+- [AbortSignal.Safe](#abortsignalsafe)
 
 ---
 
@@ -1641,6 +1643,102 @@ _Note: TypeScript numeric enums automatically create reverse mappings. For `enum
 
 ---
 
+## AbortSignal.Safe
+
+Extension for the native `AbortSignal` interface that provides safe function execution. Wraps functions to prevent their execution when the signal is aborted, returning `undefined` instead.
+
+### `signal.Safe`
+
+A property on `AbortSignal` that returns a `Stub` for wrapping functions. Wrapped functions will not execute if the signal is aborted or if the function is undefined.
+
+**Type Definition:**
+
+```typescript
+interface AbortSignal {
+  Safe: AVStantso.Stub.One & AVStantso.Stub.Multiple;
+}
+```
+
+**Example:**
+
+```typescript
+import '@avstantso/concepts';
+
+const controller = new AbortController();
+const { signal } = controller;
+
+// Wrap a single function
+const fetchData = () => 'data';
+const safeFetch = signal.Safe(fetchData);
+
+safeFetch(); // 'data' - executes normally
+
+controller.abort();
+
+safeFetch(); // undefined - signal is aborted, function not called
+
+// Wrap multiple functions
+const controller2 = new AbortController();
+const { signal: signal2 } = controller2;
+
+const [fn1, fn2, fn3] = signal2.Safe(
+  () => 'first',
+  (x: number) => x * 2,
+  () => 'third'
+);
+
+fn1();   // 'first'
+fn2(21); // 42
+fn3();   // 'third'
+
+controller2.abort();
+
+fn1();   // undefined
+fn2(21); // undefined
+fn3();   // undefined
+
+// Handles undefined functions safely
+let maybeHandler: (() => void) | undefined;
+const safeHandler = signal.Safe(maybeHandler);
+safeHandler(); // undefined - no error even though function is undefined
+
+// Practical use case: React effect cleanup
+useEffect(() => {
+  const controller = new AbortController();
+  const { signal } = controller;
+
+  fetchData({ signal }).then(signal.Safe(setState));
+
+  return () => controller.abort();
+}, []);
+
+// Practical use case: cancelable async operations
+async function loadWithCancel(signal: AbortSignal) {
+  const data = await fetchAPI('/data', { signal });
+
+  // Only update UI if not aborted
+  signal.Safe(updateUI)(data);
+  signal.Safe(showNotification)('Data loaded');
+}
+```
+
+**Behavior:**
+
+- Returns `undefined` if `signal.aborted` is `true`
+- Returns `undefined` if the wrapped function is `undefined` or falsy
+- Otherwise executes the function normally and returns its result
+- Works with both single functions and multiple functions (array destructuring)
+- Re-evaluates `signal.aborted` on each call (not cached at wrap time)
+
+**Use Cases:**
+
+- **React Effects**: Prevent state updates after component unmount
+- **Async Operations**: Skip callbacks when operation is canceled
+- **Event Handlers**: Safely ignore events after cleanup
+- **Timeout/Interval Callbacks**: Prevent execution after cancellation
+
+---
+
 ## Requirements
 
 - TypeScript >= 5.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@avstantso/concepts",
   "license": "MIT",
   "author": "avstantso",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "AVStantso framework concepts",
   "keywords": [
     "Perform",
@@ -34,11 +34,11 @@
     "test": "NODE_ENV=test jest --coverage"
   },
   "dependencies": {
-    "@avstantso/core": "1.0.4",
-    "@avstantso/errors": "1.0.5",
-    "@avstantso/js": "1.0.4",
-    "@avstantso/std-ext": "1.0.2",
-    "@avstantso/ts": "1.0.4"
+    "@avstantso/core": "1.1.0",
+    "@avstantso/errors": "1.1.0",
+    "@avstantso/js": "1.1.0",
+    "@avstantso/std-ext": "1.1.0",
+    "@avstantso/ts": "1.1.0"
   },
   "devDependencies": {
     "@avstantso/dev-basic": "1.0.0"

package/dist/_global/async-tasks.d.ts

@@ -1,134 +0,0 @@
-declare namespace AVStantso {
-    /**
-     * @summary Async tasks manager with gracefully finalization: for async tasks, intervals & timers
-     */
-    namespace AsyncTasksManager {
-        /**
-         * @summary Finalization options
-         */
-        type FinalOptions = {
-            /**
-             * @summary If not `quiet` send all errors to `console.error`
-             */
-            quiet?: boolean;
-        };
-        /**
-         * @summary Timeouts types
-         */
-        namespace Timeout {
-            /**
-             * @summary Timeout options
-             */
-            type Options = {
-                /**
-                 * @summary Call interval/timeout callback on finalize
-                 */
-                callOnFinal?: boolean;
-            };
-            /**
-             * @summary Timeout callback
-             */
-            type CallBack = (final?: boolean) => unknown;
-            /**
-             * @summary Timeout delay
-             */
-            type Delay = Parameters<typeof setInterval>[1];
-            /**
-             * @summary Timeout internal map value
-             */
-            type Value = [CallBack, Options];
-            /**
-             * @summary Timeout internal map
-             */
-            type Map = globalThis.Map<NodeJS.Timeout, Value>;
-        }
-        /**
-         * @summary AsyncTasksManager option for external usage
-         */
-        type Option = {
-            /**
-             * @summary Async manager for register tasks.\
-             * - if falsy — not used
-             * - if `AsyncTasksManager` instance — use it
-             * - if truthy — use global `AsyncTasksManager`
-             */
-            manager?: AsyncTasksManager | boolean;
-        };
-    }
-    interface AsyncTasksManager {
-        /**
-         * @summary Gracefully finalization for async tasks, intervals & timers
-         * @param options Finalization options
-         */
-        final(options?: AsyncTasksManager.FinalOptions): Promise<void>;
-        /**
-         * @summary All errors that was thrown inside `final`.\
-         * Accessible only after final is called
-         */
-        readonly errors?: unknown[];
-        /**
-         * @summary Wrap of standard `setInterval`
-         * @param callback Callback for interval
-         * @param delay Interval delay
-         * @param options Interval finalization options
-         * @returns Interval id
-         */
-        setInterval(callback: AsyncTasksManager.Timeout.CallBack, delay: AsyncTasksManager.Timeout.Delay, options: AsyncTasksManager.Timeout.Options): ReturnType<typeof setInterval>;
-        /**
-         * @summary Wrap of standard `clearInterval`
-         * @param timeout Timeout id
-         */
-        clearInterval: typeof clearInterval;
-        /**
-         * @summary Wrap of standard `setTimeout`
-         * @param callback Callback for timeout
-         * @param delay Timeout delay
-         * @param options Timeout finalization options
-         * @returns Timeout id
-         */
-        setTimeout(callback: AsyncTasksManager.Timeout.CallBack, delay: AsyncTasksManager.Timeout.Delay, options: AsyncTasksManager.Timeout.Options): ReturnType<typeof setTimeout>;
-        /**
-         * @summary Wrap of standard `clearTimeout`
-         * @param timeout Timeout id
-         */
-        clearTimeout: typeof clearTimeout;
-        /**
-         * @summary Register async task
-         * @template T Task result type
-         * @param task Async task
-         * @returns Async task (registered in  manager)
-         */
-        regTask<T>(task: Promise<T>): Promise<T>;
-    }
-    namespace Code {
-        /**
-         * @summary Global Async tasks manager and utilities
-        */
-        namespace AsyncTasksManager {
-            type ExtenderCallback = (instance: AVStantso.AsyncTasksManager) => void;
-            type Utilities = {
-                /**
-                 * @summary Register on create extender.\
-                 * Unavailable after call `AVStantso.freeze` method
-                 */
-                _RegOnCreate?(extenderCallback: AsyncTasksManager.ExtenderCallback): void;
-                /**
-                 * @summary Create new instance of `AsyncTasksManager`
-                 */
-                Factory(): AVStantso.AsyncTasksManager;
-                /**
-                 * @summary Check `candidate` is `AsyncTasksManager`
-                 */
-                is(candidate: unknown): candidate is AVStantso.AsyncTasksManager;
-            };
-        }
-        type AsyncTasksManager = AVStantso.AsyncTasksManager & AsyncTasksManager.Utilities;
-    }
-    interface Code {
-        /**
-         * @summary Global Async tasks manager and utilities
-         */
-        AsyncTasksManager: Code.AsyncTasksManager;
-    }
-    const AsyncTasksManager: Code.AsyncTasksManager;
-}

package/dist/_global/classic-enum.d.ts

@@ -1,29 +0,0 @@
-declare namespace AVStantso {
-    /**
-     * @summary Classic TypeScript `enum` helpers
-     */
-    namespace ClassicEnum {
-        /**
-         * @summary `enum` `[key, value]` pairs
-         */
-        type Entry<T, K extends keyof T = Extract<keyof T, string>> = T extends object ? [K, T[K]] : never;
-    }
-    namespace Code {
-        /**
-         * @summary ClassicEnum utilities
-         */
-        interface ClassicEnum {
-            /**
-             * @summary Get enum entries without `[value, key]` pairs
-             */
-            entries<T>(enumType: T): AVStantso.ClassicEnum.Entry<T>[];
-        }
-    }
-    interface Code {
-        /**
-         * @summary ClassicEnum utilities
-         */
-        ClassicEnum: Code.ClassicEnum;
-    }
-    const ClassicEnum: Code.ClassicEnum;
-}

package/dist/_global/compare/_register.d.ts

@@ -1,32 +0,0 @@
-declare namespace AVStantso {
-    namespace Code {
-        /**
-         * @summary Compare helpers utility
-         */
-        interface Compare {
-            /**
-             * @summary Low-lewel extend compare function. Add `Compare.Extended<TBase>`
-             * @param compareFunc Function to extend
-             */
-            Extend<TBase>(compareFunc: AVStantso.Compare.Func<TBase>): AVStantso.Compare<TBase>;
-            /**
-             * @summary Create low-lewel sort-part function for `undefined`, `null`, 'NaN'
-             * @param allowNaN Allow check 'NaN'
-             * @param nullsFirst If `true` — `undefined`, `null`, 'NaN' has higher priority
-             */
-            ToNulls(allowNaN?: boolean, nullsFirst?: boolean): (x: unknown) => number;
-            /**
-             * @summary Select first non-zero comparison
-             * @returns First non-zero comparison or `0` if its`s not found
-             */
-            Select(...comparisons: AVStantso.Perform<number>[]): number;
-        }
-    }
-    interface Code {
-        /**
-         * @summary Compare helpers utility
-         */
-        Compare: Code.Compare;
-    }
-    const Compare: Code.Compare;
-}

package/dist/_global/compare/combination.d.ts

@@ -1,41 +0,0 @@
-declare namespace AVStantso {
-    namespace Compare {
-        type _Combination<TCompares extends readonly Union[], R = unknown> = TCompares extends readonly [infer C extends Union, ...infer Rest extends readonly Union[]] ? _Combination<Rest, R & Extract<Value<C>[__BASE_TYPE__], object>> : Compare<{
-            [K in keyof R]: R[K];
-        }>;
-        /**
-         * @summary Create combined structural `Compare` by array of structural compares
-         * @template TCompares Array of structural compares
-         * @returns Combined structural `Compare`
-         * @example
-         * type cmpId = AVStantso.Provider.Compare.Make<'id', string>;
-         * type cmpName = AVStantso.Provider.Compare.Make<'name', string>;
-         * type cmpVersion = AVStantso.Provider.Compare.Make<'version', number>;
-         * 
-         * type c = Combination<[cmpId, cmpName, cmpVersion]>;
-         * 
-         * type t = CheckType<c, Compare<{ id: string; name: string; version: number; }>>;
-         */
-        export type Combination<TCompares extends Union[]> = _Combination<TCompares>;
-        export {};
-    }
-    namespace Code {
-        interface Compare {
-            /**
-             * @summary Create combined structural `Compare` by array of structural compares
-             * @template R Result
-             * @template TCompares Array of structural compares
-             * @returns Combined structural `Compare` as `R`
-             * @example
-             * const cmpId = Provider.Compare('id', 'string');
-             * const cmpName = Provider.Compare('name', 'string');
-             * const cmpVersion = Provider.Compare('version', 'number');
-             * 
-             * const c = Compare.Combine(cmpId, cmpName, cmpVersion);
-             * 
-             * type t = CheckType<typeof c, Compare<{ id: string; name: string; version: number; }>>;
-             */
-            Combine<R extends AVStantso.Compare.Combination<TCompares>, TCompares extends AVStantso.Compare.Union[] = AVStantso.Compare.Union[]>(...compares: TCompares): R;
-        }
-    }
-}

package/dist/_global/compare/compare.d.ts

@@ -1,39 +0,0 @@
-declare namespace AVStantso {
-    /**
-     *  @summary Compare two values function
-     */
-    type Compare<TBase = unknown> = Compare.Func<TBase> & Compare.Extended<TBase> & {
-        __BASE_TYPE__?: TBase;
-    };
-    namespace Compare {
-        /**
-         *  @summary Compare two values atomic function
-         */
-        type Func<TBase = unknown> = <A extends TBase = TBase, B extends TBase = TBase>(a: A, b: B) => number;
-        /**
-         * @summary `Compare` extended properties & methods
-         */
-        type Extended<TBase = unknown> = {
-            /**
-             * @summary Cast `Compare` function basetype
-             */
-            as?<R extends TBase>(): Compare<R>;
-            /**
-             * @summary Create descending `Compare` function
-             */
-            desc?: Compare<TBase>;
-        };
-        /**
-         *  @summary Compare provider
-         */
-        type Provider = AVStantso.Provider.Strict.KeyValue<'Compare', Compare>;
-        /**
-         *  @summary Compare union
-         */
-        type Union = AVStantso.Provider.Union<Provider>;
-        /**
-         *  @summary Compare value of `U`
-         */
-        type Value<U extends Union> = AVStantso.Provider.Value<U, Provider>;
-    }
-}

package/dist/_global/compare/index.d.ts

@@ -1,4 +0,0 @@
-import './_register';
-import './compare';
-import './combination';
-import './structures';

package/dist/_global/compare/structures.d.ts

@@ -1,10 +0,0 @@
-declare namespace AVStantso {
-    namespace Code {
-        interface Compare {
-            /**
-             * @summary Structures objects compare
-             */
-            Structures: AVStantso.Compare<object>;
-        }
-    }
-}

package/dist/_global/conveyor.d.ts

@@ -1,18 +0,0 @@
-declare namespace AVStantso {
-    /**
-     * @summary Conveyor of handling
-     */
-    namespace Conveyor {
-        /**
-         * @summary Conveyor transformer
-         */
-        type Transformer<T> = (from: T) => T;
-    }
-    interface Code {
-        /**
-         * @summary Conveyor of handling. Ignore empty stages
-         */
-        Conveyor<T>(original: T, ...transformers: Conveyor.Transformer<T>[]): T;
-    }
-    const Conveyor: Code['Conveyor'];
-}

package/dist/_global/equality/_register.d.ts

@@ -1,35 +0,0 @@
-declare namespace AVStantso {
-    namespace Code {
-        namespace Equality {
-            /**
-             * @summary `AVStantso.Equality.Predicate` utility
-             */
-            interface Predicate {
-                /**
-                 * @summary Factory function for `AVStantso.Equality.Predicate`
-                 */
-                Factory<T = unknown>(equality: AVStantso.Equality<T>): AVStantso.Equality.Predicate.Factory<T>;
-            }
-        }
-        /**
-         * @summary `AVStantso.Equality` utility
-         */
-        interface Equality {
-            /**
-             * @summary `AVStantso.Equality.Predicate` utility
-             */
-            Predicate: Equality.Predicate;
-            /**
-             * @summary Create equality from compare
-             */
-            From<T = unknown>(compare: AVStantso.Compare<T>): AVStantso.Equality<T>;
-        }
-    }
-    interface Code {
-        /**
-         * @summary `AVStantso.Equality` utility
-         */
-        Equality: Code.Equality;
-    }
-    const Equality: Code.Equality;
-}

package/dist/_global/equality/equality.d.ts

@@ -1,32 +0,0 @@
-declare namespace AVStantso {
-    /**
-     * @summary Equality function for two values
-     */
-    type Equality<TBase = unknown> = Equality.Func<TBase> & {
-        __BASE_TYPE__?: TBase;
-        /**
-         * @summary Cast `Equality` function basetype
-         */
-        as?<T extends TBase>(): Equality<T>;
-    };
-    namespace Equality {
-        /**
-         * @summary Equality atomic function for two values
-         */
-        type Func<TBase = unknown> = <A extends TBase = TBase, B extends TBase = TBase>(a: A, b: B) => boolean;
-        /**
-         * @summary Equality function from compare function
-         */
-        type From<C extends Compare> = Equality<C[__BASE_TYPE__]>;
-        /**
-         * @summary Predicate of equality function
-         */
-        type Predicate<T = unknown> = (b: T) => boolean;
-        namespace Predicate {
-            /**
-             * @summary Factory function for `AVStantso.Equality.Predicate`
-             */
-            type Factory<T = unknown> = (a: T, notEquals?: boolean) => Predicate<T>;
-        }
-    }
-}

package/dist/_global/equality/index.d.ts

@@ -1,2 +0,0 @@
-import './_register';
-import './equality';

package/dist/_global/extend/_register.d.ts

@@ -1,76 +0,0 @@
-declare namespace AVStantso {
-    namespace Extend {
-        namespace ByRecord {
-            type Original = object | Function;
-            type Extender<TOriginal extends Original, TExtensionKey extends TS.Key, TExtensionItem, TExtensionValue = TExtensionKey> = (value: TExtensionValue, original?: TOriginal, key?: TExtensionKey) => TExtensionItem;
-            type Func<TExtensionKey extends TS.Key, TExtensionValue, TCustomKey extends TS.Key = TExtensionKey> = <TOriginal extends Extend.ByRecord.Original, TExtensionItem, TExtension extends Record<TCustomKey, TExtensionItem>>(original: TOriginal, extender: Extend.ByRecord.Extender<TOriginal, TExtensionKey, TExtensionItem, TExtensionValue>) => TOriginal & TExtension;
-            type Methods<TExtensionKey extends TS.Key, TExtensionValue, TCustomKey extends TS.Key = TExtensionKey> = Func<TExtensionKey, TExtensionValue, TCustomKey> & {
-                static: Func<TExtensionKey, TExtensionValue, TCustomKey>;
-            };
-        }
-        /**
-         * @summary Add fields by record
-         * @param original Entity for extend
-         * @param extender Addition item by key
-         * @returns Extended entity
-         */
-        type ByRecord<TExtensionKey extends TS.Key, TExtensionValue> = Extend.ByRecord.Methods<TExtensionKey, TExtensionValue> & {
-            /**
-             * @summary Add fields by record with capitalized keys
-             * @param original Entity for extend
-             * @param extender Addition item by key
-             * @returns Extended entity
-             */
-            Capitalized: Extend.ByRecord.Methods<TExtensionKey, TExtensionValue, Capitalize<Extract<TExtensionKey, string>>>;
-            /**
-             * @summary Add fields by record with uncapitalized keys
-             * @param original Entity for extend
-             * @param extender Addition item by key
-             * @returns Extended entity
-             */
-            Uncapitalized: Extend.ByRecord.Methods<TExtensionKey, TExtensionValue, Uncapitalize<Extract<TExtensionKey, string>>>;
-        };
-        /**
-         * @summary Add arbitrary properties
-         * @param original Entity for extend
-         * @param extention properties
-         * @returns Extended entity
-         */
-        type Arbitrary = <TOriginal, TExtension extends object>(original: TOriginal, extention: TExtension | (() => TExtension)) => TOriginal & TExtension;
-    }
-    namespace Code {
-        /**
-         * @summary `AVStantso.Extend` utility
-         */
-        interface Extend {
-            /**
-             * @summary Add fields by record
-             * @param keys Keys for add
-             * @param getValue Value by key. If empty, "value"="key"
-             * @param original Entity for extend
-             * @param extender Addition item by key
-             * @returns (original, extender) => <Extended_Entity>
-             */
-            ByRecord<TExtensionKey extends AVStantso.TS.Key, TExtensionValue = TExtensionKey>(keys: TExtensionKey[] | (() => TExtensionKey[]), getValue?: (key: TExtensionKey) => TExtensionValue): Extend.ByRecord<TExtensionKey, TExtensionValue>;
-            /**
-             * @summary Add arbitrary properties
-             * @param original Entity for extend
-             * @param extention properties
-             * @returns Extended entity
-             */
-            Arbitrary: Extend.Arbitrary;
-        }
-    }
-    interface Code {
-        /**
-         * @summary `AVStantso.Extend` utility
-         */
-        Extend: Code.Extend;
-    }
-    /**
-     * @summary Cast object or function for add extended fields
-     * @param from as TFrom
-     * @returns from as TTo
-     */
-    const Extend: Code.Extend;
-}

package/dist/_global/extend/index.d.ts

@@ -1 +0,0 @@
-import './_register';

package/dist/_global/index.d.ts

@@ -1,15 +0,0 @@
-import './perform';
-import './compare';
-import './provider';
-import './equality';
-import './extend';
-import './switch';
-import './stub';
-import './mock';
-import './mapping';
-import './conveyor';
-import './override';
-import './transition';
-import './value-wrap';
-import './async-tasks';
-import './classic-enum';