fix: adding getSubSet and clone for NestedSet

Author: Farenheith

libs/js-tuple/docs/advanced-getsubmap-example.md

@@ -99,7 +99,8 @@ console.log(subClone.get([3])); // 'z'
 - **Multi-tenant Data:**
   - Partition data by tenant/user/project, and operate on each partition via submaps for isolation and clarity.
 
-
+## About NestedSet
+NestedSet offers the equivalent methods, too, **getSubSet** and **clone**, and everything explained here is valid for them, too!
 
 ## Notes
 - Traversal from a submap yields keys relative to the base path.

libs/js-tuple/src/nested-set.ts

@@ -1,58 +1,83 @@
 import { NestedMap } from './nested-map';
-import { IterationOptions } from './types';
+import { IterationOptions, PartialKey } from './types';
 
 export interface NestedSet<K> extends Set<K> {}
 export class NestedSet<K> implements Set<K> {
-	private readonly _map = new NestedMap<K, 1>();
+	#map = new NestedMap<K, 1>();
 
 	add(value: K): this {
-		this._map.set(value, 1);
+		this.#map.set(value, 1);
 		return this;
 	}
 	clear(): void {
-		this._map.clear();
+		this.#map.clear();
 	}
 	delete(value: K): boolean {
-		return this._map.delete(value);
+		return this.#map.delete(value);
 	}
 	forEach(
 		callbackfn: (value: K, value2: K, set: Set<K>) => void,
 		thisArg?: unknown,
 	): void {
 		thisArg ??= this;
-		this._map.forEach.call(
+		this.#map.forEach.call(
 			thisArg,
 			(_, k: K) => callbackfn(k, k, this),
 			thisArg,
 		);
 	}
 	has(value: K): boolean {
-		return this._map.has(value);
+		return this.#map.has(value);
 	}
 
 	get size(): number {
-		return this._map.size;
+		return this.#map.size;
 	}
 
 	*entries(options?: IterationOptions<K>): SetIterator<[K, K]> {
-		for (const key of this._map.keys(options)) {
+		for (const key of this.#map.keys(options)) {
 			yield [key, key];
 		}
 	}
 
 	keys(options?: IterationOptions<K>): SetIterator<K> {
-		return this._map.keys(options);
+		return this.#map.keys(options);
 	}
 
 	values(options?: IterationOptions<K>): SetIterator<K> {
-		return this._map.keys(options);
+		return this.#map.keys(options);
 	}
 
 	[Symbol.iterator](): SetIterator<K> {
-		return this._map.keys();
+		return this.#map.keys();
 	}
 
 	get [Symbol.toStringTag](): string {
 		return 'NestedSet';
 	}
+
+	/**
+	 * Creates a new NestedSet instance that represents a subtree starting from the specified basePath.
+	 * The new NestedSet is a view from the same structure and values as the original map for the specified subtree.
+	 * Changes to the subtree in the new map will be reflected in the original map and vice versa.
+	 * @param basePath - The path to the subtree root
+	 * @returns A new NestedSet instance exposing the subtree
+	 */
+	getSubSet(basePath: PartialKey<K>): NestedSet<K> {
+		const map = this.#map.getSubMap(basePath);
+		const result = new NestedSet<K>();
+		result.#map = map;
+		return result;
+	}
+
+	/**
+	 * Efficiently deep clones the NestedSet or a subtree if basePath is provided (O(N)), using BFS pre-order for insertion order preservation.
+	 * @param basePath - Optional path to clone only a subtree
+	 * @returns A new NestedSet instance with the same structure and values
+	 */
+	clone(basePath?: PartialKey<K>): NestedSet<K> {
+		const result = new NestedSet<K>();
+		result.#map = this.#map.clone(basePath);
+		return result;
+	}
 }