@avstantso/core 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -1,6 +1,30 @@
 # Changelog
 
 
+## [1.3.0] - 2026-07-04
+
+### Added
+
+- `DeepOps.freeze`
+- `DeepOps.clone`
+- `DeepOps.merge`
+
+## [1.2.4] - 2026-07-04
+
+### Added
+
+- `TS.Func.Type`
+- `Func.Types`
+- `Func.determineType`
+
+
+## [1.2.3] - 2026-06-19
+
+### Changed
+
+- Makes singleton idempotent for VM-reload. Like it need for Jest
+
+
 ## [1.2.2] - 2026-02-04
 
 ### Changed

package/README.md

@@ -45,11 +45,12 @@ avstantso.Catch(error); // Handle errors using centralized error handling
 You can also import specific members directly without relying on the global singleton:
 
 ```typescript
-import { Func, Generic, X } from '@avstantso/core';
+import { Func, Generic, X, DeepOps } from '@avstantso/core';
 
 // Use imported members directly
 const isExtended = Func.isExt(myFunction);
 const casted = Generic.Cast<MyType>(value);
+const cloned = DeepOps.clone(someValue);
 
 // X is a no-op function useful for Promise chains
 promise.then(X).catch(X); // Ignore both success and error
@@ -59,6 +60,7 @@ promise.then(X).catch(X); // Ignore both success and error
 - `Func` - Function utilities (same as `avstantso.Func`)
 - `Generic` - Generic type utilities (same as `avstantso.Generic`)
 - `X` - No-op function for ignoring Promise results
+- `DeepOps` - Deep freeze/clone/merge utilities (same as `avstantso.DeepOps`)
 
 ## API Reference
 
@@ -356,6 +358,82 @@ const cloned = deepClone(original);
 // Custom Date instance is properly cloned using registered clone method
 ```
 
+### AVStantso.DeepOps - Deep Freeze / Clone / Merge
+
+Deep, recursive `freeze`/`clone`/`merge` operations over plain objects, `Array`/`Set`/`Map`, functions, atomic objects (`Date`/`Buffer`, see [`AtomicObjects`](#avstantsoatomicobjects---custom-object-registry)), and scalars. Each operation walks a value's node types (`scalar`, `atomic`, `plain`, `rich`, `func`) and can be tuned per-call via `walk{NodeType}Inc`/`walk{NodeType}Exc` options; sensible defaults are applied for each operation (see method docs below).
+
+**Members:**
+
+- `avstantso.DeepOps.NodeTypes` - `Key2Key` record of the node type names (`scalar`, `atomic`, `plain`, `rich`, `func`)
+- `avstantso.DeepOps.is.options.*` - Typeguards for the various options shapes
+- `avstantso.DeepOps.freeze(obj, options?)` - Recursively `Object.freeze` a value
+- `avstantso.DeepOps.clone(obj, options?)` - Recursively clone a value
+- `avstantso.DeepOps.merge(target, ...sources, options)` - Recursively merge one or more sources into a clone of `target`
+
+##### `avstantso.DeepOps.freeze(obj, options?)`
+
+Recursively `Object.freeze`s `obj` in place and returns the same reference. By default, walks plain objects, `Array`/`Set`/`Map`/class instances, and functions (except `class` and `generator` functions, which are left unfrozen) — scalars and atomic objects (`Date`/`Buffer`) are **not** walked/frozen by default.
+
+**Options:**
+- `ownProps?: boolean` - If `true`, also walks own non-enumerable properties (not just enumerable ones)
+- `walk{Scalar|Atomic|Plain|Rich|Func}{Inc|Exc}` - Fine-tune which node types are walked, optionally per sub-kind (JS type, class, or function kind) or via a custom walker function
+
+**Custom per-object behavior:** an object with a method at `avstantso.DeepOps.freeze.symbol` (same symbol as `avstantso.symbolFreeze`) has that method called instead of the default freeze logic for that object.
+
+**Example:**
+```typescript
+const config = { db: { host: 'localhost', port: 5432 }, tags: ['a', 'b'] };
+avstantso.DeepOps.freeze(config);
+
+config.db.port = 5433; // throws TypeError: Cannot assign to read only property
+```
+
+##### `avstantso.DeepOps.clone(obj, options?)`
+
+Recursively clones `obj` into a brand-new structure. By default, walks scalars, atomic objects (cloned via their registered `AtomicObjects` descriptor), plain objects, `Array`/`Set`/`Map` (**not** arbitrary class instances), and functions (except `class`/`generator`, which are omitted from the clone entirely).
+
+**Options:**
+- `copyFuncs?: boolean` - If `true`, copies function references as-is instead of wrapping them in a new delegating function
+- `ownProps?: boolean` / `walk{NodeType}{Inc|Exc}` - Same as `freeze`
+
+**Custom per-object behavior:** an object with a method at `avstantso.DeepOps.clone.symbol` has that method called, and its return value used as the clone, bypassing default clone logic for that object.
+
+**Example:**
+```typescript
+const original = { name: 'John', birthDate: new Date('1990-01-01'), tags: ['dev', 'ts'] };
+const cloned = avstantso.DeepOps.clone(original);
+
+cloned.tags.push('new'); // does not affect original.tags
+cloned.birthDate.setFullYear(2000); // does not affect original.birthDate
+```
+
+##### `avstantso.DeepOps.merge(target, ...sources, options)`
+
+Recursively merges one or more `sources` into a **clone** of `target` (returned as a new object — `target` itself is never mutated) and returns the result. Options are always the last argument. Uses the same default node walking as `clone`.
+
+Merge behavior by node type:
+- **Plain objects** - keys are merged recursively; keys only in a source are added (unless `onlyExists`)
+- **Arrays** - merged **by index** by default (source overwrites overlapping indices, extra source items are appended); pass `concatArrays: true` to concatenate instead (`[...target, ...source]`)
+- **Sets** - source items are added if not already present
+- **Maps** - existing keys are merged recursively / overwritten, new keys added (unless `onlyExists`)
+- **Scalars/atomics, or a type mismatch between target/source** - the source always wins (cloned)
+
+**Options** (each may be a value or a `(node, key?) => value` callback, e.g. to target specific keys):
+- `onlyExists?: Common.Option<boolean>` - If truthy, only merges into keys/indices that already exist in the target
+- `isUniqueArrItems?: Common.Option<boolean>` - If truthy, dedupes the resulting array (`[...new Set(arr)]`)
+- `nullAsDelete?: Common.Option<boolean>` - If truthy, a `null` source value deletes the corresponding target key instead of setting it to `null`
+- `concatArrays?: Common.Option<boolean>` - If truthy, arrays are merged by concatenation instead of by index
+
+**Example:**
+```typescript
+const result = avstantso.DeepOps.merge(
+  { a: 1, tags: ['x'], history: [1, 2] },
+  { a: 2, tags: ['x', 'y'], history: [3] },
+  { isUniqueArrItems: (arr, key) => key === 'tags' }
+);
+// { a: 2, tags: ['x', 'y'], history: [1, 3] }
+```
+
 ### AVStantso.Generic - Generic Type Utilities
 
 Utilities for working with generic types.
@@ -380,12 +458,57 @@ Runtime utilities for working with functions.
 
 **Members:**
 
+- `avstantso.Func.Types` - `Key2Key` record of runtime function type names
+- `avstantso.Func.determineType(func)` - Determines the runtime type of a function
 - `avstantso.Func.OwnPropertyDescriptors` - Property descriptors of the base Function prototype
 - `avstantso.Func.isPropAllowed(key)` - Check if a property name can be used for function extension
 - `avstantso.Func.isPropAllowed.Not(key)` - Check if property name is reserved
 - `avstantso.Func.isExt(func)` - Check if function has extended properties
 - `avstantso.Func.Dynamic<N, F>(name, func)` - Creates a named function wrapper for better debugging in development environments
 
+##### `avstantso.Func.determineType(func)`
+
+Determines the runtime type of a function: `'plain'`, `'async'`, `'generator'`, `'class'`, `'arrow'`, or `'bound'`.
+
+**Parameters:**
+- `func` - Function to inspect
+
+**Returns:** `AVStantso.TS.Func.Type` - one of the runtime function type names
+
+**Example:**
+```typescript
+function plain() {}
+avstantso.Func.determineType(plain); // 'plain'
+
+const arrow = () => {};
+avstantso.Func.determineType(arrow); // 'arrow'
+
+const bound = plain.bind(null);
+avstantso.Func.determineType(bound); // 'bound'
+
+class MyClass {}
+avstantso.Func.determineType(MyClass); // 'class'
+
+async function asyncFn() {}
+avstantso.Func.determineType(asyncFn); // 'async'
+
+function* genFn() {}
+avstantso.Func.determineType(genFn); // 'generator'
+
+async function* asyncGenFn() {}
+avstantso.Func.determineType(asyncGenFn); // 'generator'
+```
+
+##### `avstantso.Func.Types`
+
+A `Key2Key` record (each key mapped to itself) listing all runtime function type names recognized by `determineType`: `plain`, `async`, `generator`, `class`, `arrow`, `bound`.
+
+**Example:**
+```typescript
+avstantso.Func.Types.plain; // 'plain'
+avstantso.Func.Types.async; // 'async'
+```
+
 **Example - Type Guard Function Factory:**
 ```typescript
 const Types = ['insert', 'update', 'delete'] as const;

package/dist/_global/_register.d.ts

@@ -123,7 +123,8 @@ declare namespace AVStantso {
              */
             freeze?(): void;
             /**
-             * @summary `symbol` for custom freeze
+             * @summary `symbol` for custom freeze.\
+             * Same symbol of {@link Code.DeepOps.Freeze.symbol}
              * @see freeze
              */
             symbolFreeze: symbol;