Add toWeakRef util method

docs/archive/current/packages/support/misc.md

@@ -131,4 +131,20 @@ isset('foo', { name: 'Jane' }, [ 1, 2, 3 ]); // true
 
 isset('foo', null, [ 1, 2, 3 ]); // false
 isset('foo', { name: 'Jane' }, undefined); // false
+```
+
+## `toWeakRef`
+
+Wraps a target object into a [`WeakRef`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef), if not already instance of a weak reference.
+
+```js
+import { toWeakRef } from "@aedart/support/misc";
+
+const person = { name: 'Sine' };
+
+const a = toWeakRef(person); // new WeakRef of "person"
+const b = toWeakRef(a); // same WeakRef instance as "a"
+
+toWeakRef(null); // undefined
+toWeakRef(undefined); // undefined
 ```

packages/support/src/misc/index.ts

@@ -2,3 +2,4 @@ export * from './empty';
 export * from './isPrimitive';
 export * from './isset';
 export * from './descTag';
+export * from './toWeakRef'

packages/support/src/misc/toWeakRef.ts

@@ -0,0 +1,25 @@
+import { isset } from "./isset";
+
+/**
+ * Wraps target into a {@link WeakRef}, if target is not already a weak reference
+ * 
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef
+ *
+ * @template {WeakKey} T
+ * 
+ * @param {WeakRef<T> | T | undefined} target
+ * 
+ * @return {WeakRef<T> | undefined} Returns undefined if given target is undefined
+ */
+export function toWeakRef<T extends WeakKey>(target: WeakRef<T> | T | undefined): WeakRef<T> | undefined
+{
+    if (!isset(target)) {
+        return undefined;
+    }
+
+    if (target instanceof WeakRef) {
+        return target;
+    }
+
+    return new WeakRef<T>(target);
+}

tests/browser/packages/support/misc/toWeakRef.test.js

@@ -0,0 +1,45 @@
+import { toWeakRef } from "@aedart/support/misc";
+
+describe('@aedart/support/misc', () => {
+   describe('toWeakRef', () => {
+
+       it('returns undefined when target is null or undefined', () => {
+           const targets = [
+               null,
+               undefined
+           ];
+
+           targets.forEach((target, index) => {
+               expect(toWeakRef(target))
+                   .withContext(`Target at index ${index} should be undefined`)
+                   .toBeUndefined();
+           });
+       });
+
+       it('returns weak reference when target already a weak reference', () => {
+
+           const obj = { name: 'John' };
+
+           const target = new WeakRef(obj);
+
+           expect(toWeakRef(target))
+               .withContext('Invalid target returned')
+               .toBe(target);
+       });
+
+       it('wraps target into weak reference', () => {
+
+           const obj = { name: 'John' };
+
+           const result = toWeakRef(obj); 
+
+           expect(result)
+               .withContext('No weak reference returned')
+               .toBeInstanceOf(WeakRef);
+
+           expect(result?.deref())
+               .withContext('Dereference failed')
+               .toBe(obj);
+       });
+   });
+});