effect 4.0.0-beta.101 → 4.0.0-beta.103

package/src/Newtype.ts

@@ -36,14 +36,19 @@ const TypeId = "~effect/Newtype"
  *
  * **Example** (Defining a newtype)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Newtype } from "effect"
  *
  * interface UserId extends Newtype.Newtype<"UserId", number> {}
  * interface OrderId extends Newtype.Newtype<"OrderId", number> {}
  *
+ * const userId = Newtype.makeIso<UserId>().set(1)
  * // UserId and OrderId are not assignable to each other
  * // even though both wrap `number`.
+ * // @ts-expect-error
+ * const orderId: OrderId = userId
+ *
+ * Newtype.value(userId) // => 1
  * ```
  *
  * @see {@link makeIso} — create an iso to wrap and unwrap
@@ -125,7 +130,7 @@ export declare namespace Newtype {
  *
  * **Example** (Unwrapping a newtype)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Newtype } from "effect"
  *
  * interface Label extends Newtype.Newtype<"Label", string> {}
@@ -133,7 +138,8 @@ export declare namespace Newtype {
  * const iso = Newtype.makeIso<Label>()
  * const label = iso.set("hello")
  *
- * const raw: string = Newtype.value(label) // "hello"
+ * const raw: string = Newtype.value(label)
+ * raw // => "hello"
  * ```
  *
  * @see {@link makeIso} — two-way conversion (wrap and unwrap)
@@ -158,7 +164,7 @@ export const value: <N extends Newtype.Any>(newtype: N) => Newtype.Carrier<N> =
  *
  * **Example** (Wrapping and unwrapping with an iso)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Newtype } from "effect"
  *
  * interface Label extends Newtype.Newtype<"Label", string> {}
@@ -166,7 +172,8 @@ export const value: <N extends Newtype.Any>(newtype: N) => Newtype.Carrier<N> =
  * const labelIso = Newtype.makeIso<Label>()
  *
  * const label: Label = labelIso.set("world")
- * const str: string = labelIso.get(label) // "world"
+ * const str: string = labelIso.get(label)
+ * str // => "world"
  * ```
  *
  * @see {@link value} — unwrap only
@@ -194,7 +201,7 @@ export function makeIso<N extends Newtype.Any>(): Optic.Iso<N, Newtype.Carrier<N
  *
  * **Example** (Comparing newtypes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Equivalence, Newtype } from "effect"
  *
  * interface Label extends Newtype.Newtype<"Label", string> {}
@@ -202,8 +209,8 @@ export function makeIso<N extends Newtype.Any>(): Optic.Iso<N, Newtype.Carrier<N
  * const eq = Newtype.makeEquivalence<Label>(Equivalence.String)
  * const iso = Newtype.makeIso<Label>()
  *
- * eq(iso.set("a"), iso.set("a")) // true
- * eq(iso.set("a"), iso.set("b")) // false
+ * eq(iso.set("a"), iso.set("a")) // => true
+ * eq(iso.set("a"), iso.set("b")) // => false
  * ```
  *
  * @see {@link makeOrder} — lift an `Order` for the carrier
@@ -229,7 +236,7 @@ export const makeEquivalence: <N extends Newtype.Any>(
  *
  * **Example** (Ordering newtypes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Newtype, Order } from "effect"
  *
  * interface Score extends Newtype.Newtype<"Score", number> {}
@@ -237,7 +244,7 @@ export const makeEquivalence: <N extends Newtype.Any>(
  * const ord = Newtype.makeOrder<Score>(Order.Number)
  * const iso = Newtype.makeIso<Score>()
  *
- * ord(iso.set(1), iso.set(2)) // -1
+ * ord(iso.set(1), iso.set(2)) // => -1
  * ```
  *
  * @see {@link makeEquivalence} — lift an `Equivalence` for the carrier
@@ -261,7 +268,7 @@ export const makeOrder: <N extends Newtype.Any>(order: Order.Order<Newtype.Carri
  *
  * **Example** (Combining newtypes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Combiner, Newtype } from "effect"
  *
  * interface Amount extends Newtype.Newtype<"Amount", number> {}
@@ -271,7 +278,7 @@ export const makeOrder: <N extends Newtype.Any>(order: Order.Order<Newtype.Carri
  * const iso = Newtype.makeIso<Amount>()
  *
  * const total = combiner.combine(iso.set(10), iso.set(20))
- * Newtype.value(total) // 30
+ * Newtype.value(total) // => 30
  * ```
  *
  * @see {@link makeReducer} — lift a `Reducer` for the carrier
@@ -297,7 +304,7 @@ export const makeCombiner: <N extends Newtype.Any>(
  *
  * **Example** (Reducing newtypes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Newtype, Reducer } from "effect"
  *
  * interface Score extends Newtype.Newtype<"Score", number> {}
@@ -307,7 +314,7 @@ export const makeCombiner: <N extends Newtype.Any>(
  * const iso = Newtype.makeIso<Score>()
  *
  * const total = reducer.combineAll([iso.set(1), iso.set(2), iso.set(3)])
- * Newtype.value(total) // 6
+ * Newtype.value(total) // => 6
  * ```
  *
  * @see {@link makeCombiner} — lift a `Combiner` for the carrier

package/src/NonEmptyIterable.ts

@@ -44,48 +44,6 @@ export declare const nonEmpty: unique symbol
  * The type is branded with a unique symbol to ensure type safety while maintaining
  * full compatibility with JavaScript's iteration protocol.
  *
- * **Example** (Working with non-empty iterables)
- *
- * ```ts
- * import { Array, Chunk, NonEmptyIterable } from "effect"
- *
- * // Function that requires non-empty data
- * function getFirst<A>(data: NonEmptyIterable.NonEmptyIterable<A>): A {
- *   // Safe - guaranteed to have at least one element
- *   const [first] = NonEmptyIterable.unprepend(data)
- *   return first
- * }
- *
- * // Works with any non-empty iterable
- * const numbers = Array.make(
- *   1,
- *   2,
- *   3
- * ) as unknown as NonEmptyIterable.NonEmptyIterable<number>
- * const firstNumber = getFirst(numbers) // 1
- *
- * const chars = "hello" as unknown as NonEmptyIterable.NonEmptyIterable<string>
- * const firstChar = getFirst(chars) // "h"
- *
- * const entries = new Map([["a", 1], [
- *   "b",
- *   2
- * ]]) as unknown as NonEmptyIterable.NonEmptyIterable<[string, number]>
- * const firstEntry = getFirst(entries) // ["a", 1]
- *
- * // Custom generator
- * function* countdown(): Generator<number> {
- *   yield 3
- *   yield 2
- *   yield 1
- * }
- * const firstCount = getFirst(
- *   Chunk.fromIterable(
- *     countdown()
- *   ) as unknown as NonEmptyIterable.NonEmptyIterable<number>
- * ) // 3
- * ```
- *
  * @category models
  * @since 2.0.0
  */
@@ -109,101 +67,13 @@ export interface NonEmptyIterable<out A> extends Iterable<A> {
  *
  * **Example** (Extracting first and remaining elements)
  *
- * ```ts
- * import { Array, Chunk, NonEmptyIterable } from "effect"
- *
- * // Helper to make iterator iterable for Array.from
- * const iteratorToIterable = <T>(iterator: Iterator<T>): Iterable<T> => ({
- *   [Symbol.iterator]() {
- *     return iterator
- *   }
- * })
- *
- * // With NonEmptyArray from Array.make (cast to NonEmptyIterable)
- * const numbers = Array.make(
- *   1,
- *   2,
- *   3,
- *   4,
- *   5
- * ) as unknown as NonEmptyIterable.NonEmptyIterable<number>
- * const [first, rest] = NonEmptyIterable.unprepend(numbers)
- * console.log(first) // 1
- * console.log(globalThis.Array.from(iteratorToIterable(rest))) // [2, 3, 4, 5]
- *
- * // With strings (assert when known to be non-empty)
- * const text = "hello" as unknown as NonEmptyIterable.NonEmptyIterable<string>
- * const [firstChar, restChars] = NonEmptyIterable.unprepend(text)
- * console.log(firstChar) // "h"
- * console.log(globalThis.Array.from(iteratorToIterable(restChars)).join("")) // "ello"
- *
- * // With Sets (assert when known to be non-empty)
- * const uniqueNumbers = new Set([
- *   10,
- *   20,
- *   30
- * ]) as unknown as NonEmptyIterable.NonEmptyIterable<number>
- * const [firstUnique, restUnique] = NonEmptyIterable.unprepend(uniqueNumbers)
- * console.log(firstUnique) // 10 (or any element, Set order is not guaranteed)
- * console.log(globalThis.Array.from(iteratorToIterable(restUnique))) // [20, 30] (in some order)
- *
- * // With Maps (assert when known to be non-empty)
- * const keyValuePairs = new Map([["a", 1], ["b", 2], [
- *   "c",
- *   3
- * ]]) as unknown as NonEmptyIterable.NonEmptyIterable<[string, number]>
- * const [firstPair, restPairs] = NonEmptyIterable.unprepend(keyValuePairs)
- * console.log(firstPair) // ["a", 1]
- * console.log(globalThis.Array.from(iteratorToIterable(restPairs))) // [["b", 2], ["c", 3]]
- *
- * // With custom generators
- * function* fibonacci(): Generator<number> {
- *   let a = 1, b = 1
- *   yield a
- *   for (let i = 0; i < 10; i++) {
- *     yield b
- *     const next = a + b
- *     a = b
- *     b = next
- *   }
- * }
- *
- * const generator = Chunk.fromIterable(
- *   fibonacci()
- * ) as unknown as NonEmptyIterable.NonEmptyIterable<number>
- * const [firstFib, restFib] = NonEmptyIterable.unprepend(generator)
- * console.log(firstFib) // 1
- * console.log(globalThis.Array.from(iteratorToIterable(restFib))) // [1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
- *
- * // Practical usage: implementing reduce for non-empty iterables
- * function reduceNonEmpty<A, B>(
- *   data: NonEmptyIterable.NonEmptyIterable<A>,
- *   f: (acc: B, current: A) => B,
- *   initial: B
- * ): B {
- *   const [first, rest] = NonEmptyIterable.unprepend(data)
- *   let result = f(initial, first)
- *
- *   // Convert iterator to iterable for iteration
- *   const iterable = {
- *     [Symbol.iterator]() {
- *       return rest
- *     }
- *   }
- *   for (const item of iterable) {
- *     result = f(result, item)
- *   }
- *
- *   return result
- * }
- *
- * const data = Array.make(
- *   1,
- *   2,
- *   3,
- *   4
- * ) as unknown as NonEmptyIterable.NonEmptyIterable<number>
- * const sum = reduceNonEmpty(data, (acc, x) => acc + x, 0) // 10
+ * ```ts import.meta.vitest
+ * import { Chunk, NonEmptyIterable } from "effect"
+ *
+ * const [first, rest] = NonEmptyIterable.unprepend(Chunk.make(1, 2, 3))
+ *
+ * first // => 1
+ * globalThis.Array.from({ [Symbol.iterator]: () => rest }) // => [2, 3]
  * ```
  *
  * @category getters