@monstermann/set 0.2.0 → 0.3.0

package/dist/Set/add.d.mts

@@ -1,24 +1,32 @@
 //#region src/Set/add.d.ts
 /**
+ * # add
+ *
  * ```ts
- * function Set.add(target, value)
+ * function Set.add<T>(
+ *     target: ReadonlySet<T>,
+ *     value: NoInfer<T>,
+ * ): ReadonlySet<T>
  * ```
  *
- * Example
+ * Returns a set with the value added. If the value already exists in the set, returns the original set unchanged.
  *
- * ```ts
+ * ## Example
+ *
+ * ```ts [data-first]
  * import { Set } from "@monstermann/set";
  *
  * Set.add(Set.create([1, 2]), 3); // Set([1, 2, 3])
  * Set.add(Set.create([1, 2]), 2); // Set([1, 2])
  * ```
  *
- * ```ts
+ * ```ts [data-last]
  * import { Set } from "@monstermann/set";
  *
  * pipe(Set.create([1, 2]), Set.add(3)); // Set([1, 2, 3])
  * pipe(Set.create([1, 2]), Set.add(2)); // Set([1, 2])
  * ```
+ *
  */
 declare const add: {
   <T>(value: NoInfer<T>): (target: Set<T>) => Set<T>;

package/dist/Set/add.mjs

@@ -3,25 +3,33 @@ import { cloneSet } from "@monstermann/remmi";
 
 //#region src/Set/add.ts
 /**
+* # add
+*
 * ```ts
-* function Set.add(target, value)
+* function Set.add<T>(
+*     target: ReadonlySet<T>,
+*     value: NoInfer<T>,
+* ): ReadonlySet<T>
 * ```
 *
-* Example
+* Returns a set with the value added. If the value already exists in the set, returns the original set unchanged.
 *
-* ```ts
+* ## Example
+*
+* ```ts [data-first]
 * import { Set } from "@monstermann/set";
 *
 * Set.add(Set.create([1, 2]), 3); // Set([1, 2, 3])
 * Set.add(Set.create([1, 2]), 2); // Set([1, 2])
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Set } from "@monstermann/set";
 *
 * pipe(Set.create([1, 2]), Set.add(3)); // Set([1, 2, 3])
 * pipe(Set.create([1, 2]), Set.add(2)); // Set([1, 2])
 * ```
+*
 */
 const add = dfdlT((target, value) => {
 	if (target.has(value)) return target;

package/dist/Set/addAll.d.mts

@@ -1,24 +1,32 @@
 //#region src/Set/addAll.d.ts
 /**
+ * # addAll
+ *
  * ```ts
- * function Set.addAll(target, values)
+ * function Set.addAll<T>(
+ *     target: ReadonlySet<T>,
+ *     values: Iterable<NoInfer<T>>,
+ * ): ReadonlySet<T>
  * ```
  *
- * Example
+ * Returns a set with all values from the iterable added. Values that already exist in the set are skipped.
  *
- * ```ts
+ * ## Example
+ *
+ * ```ts [data-first]
  * import { Set } from "@monstermann/set";
  *
  * Set.addAll(Set.create([1, 2]), [3, 4]); // Set([1, 2, 3, 4])
  * Set.addAll(Set.create([1, 2]), [2, 3]); // Set([1, 2, 3])
  * ```
  *
- * ```ts
+ * ```ts [data-last]
  * import { Set } from "@monstermann/set";
  *
  * pipe(Set.create([1, 2]), Set.addAll([3, 4])); // Set([1, 2, 3, 4])
  * pipe(Set.create([1, 2]), Set.addAll([2, 3])); // Set([1, 2, 3])
  * ```
+ *
  */
 declare const addAll: {
   <T>(values: Iterable<NoInfer<T>>): (target: Set<T>) => Set<T>;

package/dist/Set/addAll.mjs

@@ -3,25 +3,33 @@ import { cloneSet } from "@monstermann/remmi";
 
 //#region src/Set/addAll.ts
 /**
+* # addAll
+*
 * ```ts
-* function Set.addAll(target, values)
+* function Set.addAll<T>(
+*     target: ReadonlySet<T>,
+*     values: Iterable<NoInfer<T>>,
+* ): ReadonlySet<T>
 * ```
 *
-* Example
+* Returns a set with all values from the iterable added. Values that already exist in the set are skipped.
 *
-* ```ts
+* ## Example
+*
+* ```ts [data-first]
 * import { Set } from "@monstermann/set";
 *
 * Set.addAll(Set.create([1, 2]), [3, 4]); // Set([1, 2, 3, 4])
 * Set.addAll(Set.create([1, 2]), [2, 3]); // Set([1, 2, 3])
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Set } from "@monstermann/set";
 *
 * pipe(Set.create([1, 2]), Set.addAll([3, 4])); // Set([1, 2, 3, 4])
 * pipe(Set.create([1, 2]), Set.addAll([2, 3])); // Set([1, 2, 3])
 * ```
+*
 */
 const addAll = dfdlT((target, values) => {
 	let result;

package/dist/Set/clone.d.mts

@@ -1,24 +1,29 @@
 //#region src/Set/clone.d.ts
 /**
+ * # clone
+ *
  * ```ts
- * function Set.clone(target)
+ * function Set.clone<T>(target: ReadonlySet<T>): Set<T>
  * ```
  *
- * Example
+ * Returns a shallow copy of the set, unless marked as mutable with `markAsMutable` inside a mutation context (see [@monstermann/remmi](https://michaelostermann.github.io/remmi/#clonearray-array)).
  *
- * ```ts
+ * ## Example
+ *
+ * ```ts [data-first]
  * import { Set } from "@monstermann/set";
  *
  * const original = Set.create([1, 2, 3]);
  * const copy = Set.clone(original); // Set { 1, 2, 3 }
  * ```
  *
- * ```ts
+ * ```ts [data-last]
  * import { Set } from "@monstermann/set";
  *
  * const original = Set.create([1, 2, 3]);
  * const copy = pipe(original, Set.clone()); // Set { 1, 2, 3 }
  * ```
+ *
  */
 declare const clone: {
   (): <T>(target: ReadonlySet<T>) => Set<T>;

package/dist/Set/clone.mjs

@@ -3,25 +3,30 @@ import { cloneSet } from "@monstermann/remmi";
 
 //#region src/Set/clone.ts
 /**
+* # clone
+*
 * ```ts
-* function Set.clone(target)
+* function Set.clone<T>(target: ReadonlySet<T>): Set<T>
 * ```
 *
-* Example
+* Returns a shallow copy of the set, unless marked as mutable with `markAsMutable` inside a mutation context (see [@monstermann/remmi](https://michaelostermann.github.io/remmi/#clonearray-array)).
 *
-* ```ts
+* ## Example
+*
+* ```ts [data-first]
 * import { Set } from "@monstermann/set";
 *
 * const original = Set.create([1, 2, 3]);
 * const copy = Set.clone(original); // Set { 1, 2, 3 }
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Set } from "@monstermann/set";
 *
 * const original = Set.create([1, 2, 3]);
 * const copy = pipe(original, Set.clone()); // Set { 1, 2, 3 }
 * ```
+*
 */
 const clone = dfdlT(cloneSet, 1);
 

package/dist/Set/compact.d.mts

@@ -3,25 +3,32 @@ import { NonNil } from "./internals/types.mjs";
 //#region src/Set/compact.d.ts
 
 /**
+ * # compact
+ *
  * ```ts
- * function Set.compact(target)
+ * function Set.compact<T>(
+ *     target: ReadonlySet<T>,
+ * ): ReadonlySet<NonNil<T>>
  * ```
  *
- * Example
+ * Returns a set with all `null` and `undefined` values removed.
  *
- * ```ts
+ * ## Example
+ *
+ * ```ts [data-first]
  * import { Set } from "@monstermann/set";
  *
  * Set.compact(Set.create([1, null, 2, undefined])); // Set([1, 2])
  * Set.compact(Set.create([1, 2, 3])); // Set([1, 2, 3])
  * ```
  *
- * ```ts
+ * ```ts [data-last]
  * import { Set } from "@monstermann/set";
  *
  * pipe(Set.create([1, null, 2, undefined]), Set.compact()); // Set([1, 2])
  * pipe(Set.create([1, 2, 3]), Set.compact()); // Set([1, 2, 3])
  * ```
+ *
  */
 declare const compact: {
   <T>(): (target: Set<T>) => Set<NonNil<T>>;

package/dist/Set/compact.mjs

@@ -3,25 +3,32 @@ import { cloneSet } from "@monstermann/remmi";
 
 //#region src/Set/compact.ts
 /**
+* # compact
+*
 * ```ts
-* function Set.compact(target)
+* function Set.compact<T>(
+*     target: ReadonlySet<T>,
+* ): ReadonlySet<NonNil<T>>
 * ```
 *
-* Example
+* Returns a set with all `null` and `undefined` values removed.
 *
-* ```ts
+* ## Example
+*
+* ```ts [data-first]
 * import { Set } from "@monstermann/set";
 *
 * Set.compact(Set.create([1, null, 2, undefined])); // Set([1, 2])
 * Set.compact(Set.create([1, 2, 3])); // Set([1, 2, 3])
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Set } from "@monstermann/set";
 *
 * pipe(Set.create([1, null, 2, undefined]), Set.compact()); // Set([1, 2])
 * pipe(Set.create([1, 2, 3]), Set.compact()); // Set([1, 2, 3])
 * ```
+*
 */
 const compact = dfdlT((target) => {
 	if (!target.has(null) && !target.has(void 0)) return target;

package/dist/Set/create.d.mts

@@ -1,16 +1,23 @@
 //#region src/Set/create.d.ts
 /**
+ * # create
+ *
  * ```ts
- * function Set.create(iterable?)
+ * function Set.create<T>(
+ *     iterable?: Iterable<T> | null | undefined,
+ * ): Set<T>
  * ```
  *
- * Example
+ * Creates a new set from an optional iterable.
+ *
+ * ## Example
  *
  * ```ts
  * import { Set } from "@monstermann/set";
  *
  * Set.create([1, 2, 3]); // Set([1, 2, 3])
  * ```
+ *
  */
 declare function create<T>(iterable?: Iterable<T> | null | undefined): Set<T>;
 //#endregion

package/dist/Set/create.mjs

@@ -1,16 +1,23 @@
 //#region src/Set/create.ts
 /**
+* # create
+*
 * ```ts
-* function Set.create(iterable?)
+* function Set.create<T>(
+*     iterable?: Iterable<T> | null | undefined,
+* ): Set<T>
 * ```
 *
-* Example
+* Creates a new set from an optional iterable.
+*
+* ## Example
 *
 * ```ts
 * import { Set } from "@monstermann/set";
 *
 * Set.create([1, 2, 3]); // Set([1, 2, 3])
 * ```
+*
 */
 function create(iterable) {
 	return new globalThis.Set(iterable);

package/dist/Set/difference.d.mts

@@ -1,24 +1,32 @@
 //#region src/Set/difference.d.ts
 /**
+ * # difference
+ *
  * ```ts
- * function Set.difference(target, source)
+ * function Set.difference<T, U>(
+ *     target: Set<T>,
+ *     source: Set<U>,
+ * ): Set<T>
  * ```
  *
- * Example
+ * Returns a set containing all values from the target set that are not in the source set.
  *
- * ```ts
+ * ## Example
+ *
+ * ```ts [data-first]
  * import { Set } from "@monstermann/set";
  *
  * Set.difference(Set.create([1, 2, 3]), Set.create([2, 3, 4])); // Set([1])
  * Set.difference(Set.create([1, 2]), Set.create([3, 4])); // Set([1, 2])
  * ```
  *
- * ```ts
+ * ```ts [data-last]
  * import { Set } from "@monstermann/set";
  *
  * pipe(Set.create([1, 2, 3]), Set.difference(Set.create([2, 3, 4]))); // Set([1])
  * pipe(Set.create([1, 2]), Set.difference(Set.create([3, 4]))); // Set([1, 2])
  * ```
+ *
  */
 declare const difference: {
   <T, U>(source: Set<U>): (target: Set<T>) => Set<T>;

package/dist/Set/difference.mjs

@@ -2,25 +2,33 @@ import { dfdlT } from "@monstermann/dfdl";
 
 //#region src/Set/difference.ts
 /**
+* # difference
+*
 * ```ts
-* function Set.difference(target, source)
+* function Set.difference<T, U>(
+*     target: Set<T>,
+*     source: Set<U>,
+* ): Set<T>
 * ```
 *
-* Example
+* Returns a set containing all values from the target set that are not in the source set.
 *
-* ```ts
+* ## Example
+*
+* ```ts [data-first]
 * import { Set } from "@monstermann/set";
 *
 * Set.difference(Set.create([1, 2, 3]), Set.create([2, 3, 4])); // Set([1])
 * Set.difference(Set.create([1, 2]), Set.create([3, 4])); // Set([1, 2])
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Set } from "@monstermann/set";
 *
 * pipe(Set.create([1, 2, 3]), Set.difference(Set.create([2, 3, 4]))); // Set([1])
 * pipe(Set.create([1, 2]), Set.difference(Set.create([3, 4]))); // Set([1, 2])
 * ```
+*
 */
 const difference = dfdlT((target, source) => {
 	if (source.size === 0) return target;

package/dist/Set/forEach.d.mts

@@ -1,18 +1,28 @@
 //#region src/Set/forEach.d.ts
 /**
+ * # forEach
+ *
  * ```ts
- * function Set.forEach(target, fn)
+ * function Set.forEach<T>(
+ *     target: ReadonlySet<T>,
+ *     fn: (
+ *         value: NoInfer<T>,
+ *         target: ReadonlySet<NoInfer<T>>,
+ *     ) => unknown,
+ * ): ReadonlySet<T>
  * ```
  *
- * Example
+ * Executes a function for each value in the set and returns the set unchanged.
  *
- * ```ts
+ * ## Example
+ *
+ * ```ts [data-first]
  * import { Set } from "@monstermann/set";
  *
  * Set.forEach(Set.create([1, 2, 3]), (value) => console.log(value)); // Set([1, 2, 3])
  * ```
  *
- * ```ts
+ * ```ts [data-last]
  * import { Set } from "@monstermann/set";
  *
  * pipe(
@@ -20,6 +30,7 @@
  *     Set.forEach((value) => console.log(value)),
  * ); // Set([1, 2, 3])
  * ```
+ *
  */
 declare const forEach: {
   <T>(fn: (value: NoInfer<T>, target: ReadonlySet<NoInfer<T>>) => unknown): (target: Set<T>) => Set<T>;

package/dist/Set/forEach.mjs

@@ -2,19 +2,29 @@ import { dfdlT } from "@monstermann/dfdl";
 
 //#region src/Set/forEach.ts
 /**
+* # forEach
+*
 * ```ts
-* function Set.forEach(target, fn)
+* function Set.forEach<T>(
+*     target: ReadonlySet<T>,
+*     fn: (
+*         value: NoInfer<T>,
+*         target: ReadonlySet<NoInfer<T>>,
+*     ) => unknown,
+* ): ReadonlySet<T>
 * ```
 *
-* Example
+* Executes a function for each value in the set and returns the set unchanged.
 *
-* ```ts
+* ## Example
+*
+* ```ts [data-first]
 * import { Set } from "@monstermann/set";
 *
 * Set.forEach(Set.create([1, 2, 3]), (value) => console.log(value)); // Set([1, 2, 3])
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Set } from "@monstermann/set";
 *
 * pipe(
@@ -22,6 +32,7 @@ import { dfdlT } from "@monstermann/dfdl";
 *     Set.forEach((value) => console.log(value)),
 * ); // Set([1, 2, 3])
 * ```
+*
 */
 const forEach = dfdlT((target, fn) => {
 	for (const value of target) fn(value, target);

package/dist/Set/has.d.mts

@@ -1,24 +1,32 @@
 //#region src/Set/has.d.ts
 /**
+ * # has
+ *
  * ```ts
- * function Set.has(target, value)
+ * function Set.has<T>(
+ *     target: ReadonlySet<T>,
+ *     value: NoInfer<T>,
+ * ): boolean
  * ```
  *
- * Example
+ * Returns `true` if the set contains the value, `false` otherwise.
  *
- * ```ts
+ * ## Example
+ *
+ * ```ts [data-first]
  * import { Set } from "@monstermann/set";
  *
  * Set.has(Set.create([1, 2, 3]), 2); // true
  * Set.has(Set.create([1, 2, 3]), 4); // false
  * ```
  *
- * ```ts
+ * ```ts [data-last]
  * import { Set } from "@monstermann/set";
  *
  * pipe(Set.create([1, 2, 3]), Set.has(2)); // true
  * pipe(Set.create([1, 2, 3]), Set.has(4)); // false
  * ```
+ *
  */
 declare const has: {
   <T>(value: NoInfer<T>): (target: ReadonlySet<T>) => boolean;

package/dist/Set/has.mjs

@@ -2,25 +2,33 @@ import { dfdlT } from "@monstermann/dfdl";
 
 //#region src/Set/has.ts
 /**
+* # has
+*
 * ```ts
-* function Set.has(target, value)
+* function Set.has<T>(
+*     target: ReadonlySet<T>,
+*     value: NoInfer<T>,
+* ): boolean
 * ```
 *
-* Example
+* Returns `true` if the set contains the value, `false` otherwise.
 *
-* ```ts
+* ## Example
+*
+* ```ts [data-first]
 * import { Set } from "@monstermann/set";
 *
 * Set.has(Set.create([1, 2, 3]), 2); // true
 * Set.has(Set.create([1, 2, 3]), 4); // false
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Set } from "@monstermann/set";
 *
 * pipe(Set.create([1, 2, 3]), Set.has(2)); // true
 * pipe(Set.create([1, 2, 3]), Set.has(4)); // false
 * ```
+*
 */
 const has = dfdlT((target, value) => {
 	return target.has(value);

package/dist/Set/hasAll.d.mts

@@ -1,24 +1,32 @@
 //#region src/Set/hasAll.d.ts
 /**
+ * # hasAll
+ *
  * ```ts
- * function Set.hasAll(target, values)
+ * function Set.hasAll<T>(
+ *     target: ReadonlySet<T>,
+ *     values: Iterable<NoInfer<T>>,
+ * ): boolean
  * ```
  *
- * Example
+ * Returns `true` if the set contains all values from the iterable, `false` otherwise.
  *
- * ```ts
+ * ## Example
+ *
+ * ```ts [data-first]
  * import { Set } from "@monstermann/set";
  *
  * Set.hasAll(Set.create([1, 2, 3]), [1, 2]); // true
  * Set.hasAll(Set.create([1, 2, 3]), [1, 4]); // false
  * ```
  *
- * ```ts
+ * ```ts [data-last]
  * import { Set } from "@monstermann/set";
  *
  * pipe(Set.create([1, 2, 3]), Set.hasAll([1, 2])); // true
  * pipe(Set.create([1, 2, 3]), Set.hasAll([1, 4])); // false
  * ```
+ *
  */
 declare const hasAll: {
   <T>(values: Iterable<NoInfer<T>>): (target: ReadonlySet<T>) => boolean;

package/dist/Set/hasAll.mjs

@@ -2,25 +2,33 @@ import { dfdlT } from "@monstermann/dfdl";
 
 //#region src/Set/hasAll.ts
 /**
+* # hasAll
+*
 * ```ts
-* function Set.hasAll(target, values)
+* function Set.hasAll<T>(
+*     target: ReadonlySet<T>,
+*     values: Iterable<NoInfer<T>>,
+* ): boolean
 * ```
 *
-* Example
+* Returns `true` if the set contains all values from the iterable, `false` otherwise.
 *
-* ```ts
+* ## Example
+*
+* ```ts [data-first]
 * import { Set } from "@monstermann/set";
 *
 * Set.hasAll(Set.create([1, 2, 3]), [1, 2]); // true
 * Set.hasAll(Set.create([1, 2, 3]), [1, 4]); // false
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Set } from "@monstermann/set";
 *
 * pipe(Set.create([1, 2, 3]), Set.hasAll([1, 2])); // true
 * pipe(Set.create([1, 2, 3]), Set.hasAll([1, 4])); // false
 * ```
+*
 */
 const hasAll = dfdlT((target, values) => {
 	for (const value of values) if (!target.has(value)) return false;