effect 4.0.0 → 4.0.2

package/src/cluster/internal/resourceRef.ts

@@ -1,133 +1,226 @@
-import type * as Cause from "../../Cause.ts"
+import * as Deferred from "../../Deferred.ts"
 import * as Effect from "../../Effect.ts"
 import * as Exit from "../../Exit.ts"
-import * as Latch from "../../Latch.ts"
-import * as MutableRef from "../../MutableRef.ts"
-import * as Option from "../../Option.ts"
+import * as Fiber from "../../Fiber.ts"
 import * as Scope from "../../Scope.ts"
 import type { EntityAddress } from "../EntityAddress.ts"
-import { acquireEntity, releaseEntity } from "./interruptors.ts"
+import { aroundEntity } from "./interruptors.ts"
 
-/**
- * @internal
- */
-export type State<A, E> = {
-  readonly _tag: "Closed"
-} | {
-  readonly _tag: "Acquiring"
-  readonly scope: Scope.Closeable
-} | {
-  readonly _tag: "Acquired"
-  readonly scope: Scope.Closeable
-  readonly value: A
-} | {
-  readonly _tag: "Failed"
+type Pending<A> = {
+  readonly _tag: "Pending"
   readonly scope: Scope.Closeable
-  readonly cause: Cause.Cause<E>
+  /** Predecessor scope or ongoing release to await before acquisition. */
+  readonly releases: Scope.Closeable | Fiber.Fiber<void> | undefined
+  releasing: boolean
+  /** Shared with waiters across superseded rebuilds. */
+  readonly ready: Deferred.Deferred<A>
+  value: A | undefined
+  work: Fiber.Fiber<void> | undefined
 }
 
+type State<A> =
+  | { readonly _tag: "Closed" }
+  | { readonly _tag: "Ready"; readonly scope: Scope.Closeable; readonly value: A }
+  | Pending<A>
+  | {
+    readonly _tag: "Failed"
+    readonly ready: Deferred.Deferred<A>
+    readonly releasing: Fiber.Fiber<void> | undefined
+  }
+
 /**
+ * A replaceable resource whose acquired value identifies its generation.
+ *
  * @internal
  */
-export class ResourceRef<A, E = never> {
-  static from = Effect.fnUntraced(function*<A, E>(
+export class ResourceRef<A> {
+  static from = Effect.fnUntraced(function*<A>(
     parentScope: Scope.Scope,
-    acquire: (scope: Scope.Scope) => Effect.Effect<A, E>,
+    acquire: (scope: Scope.Scope) => Effect.Effect<A>,
     teardownAddress?: EntityAddress
   ) {
-    const state = MutableRef.make<State<A, E>>({ _tag: "Closed" })
-
-    yield* Scope.addFinalizerExit(parentScope, (exit) => {
-      const s = MutableRef.get(state)
-      if (s._tag === "Closed") {
-        return Effect.void
-      }
-      const scope = s.scope
-      MutableRef.set(state, { _tag: "Closed" })
-      return Scope.close(scope, exit)
-    })
-
-    const scope = yield* Scope.make()
-    MutableRef.set(state, { _tag: "Acquiring", scope })
-    const value = yield* acquire(scope)
-    MutableRef.set(state, { _tag: "Acquired", scope, value })
-
-    return new ResourceRef(state, acquire, teardownAddress)
+    // Close the ref before joining releases, so waiters wake even if release stalls.
+    const releaseScope = Scope.forkUnsafe(parentScope)
+    const ref = new ResourceRef(releaseScope, acquire, teardownAddress)
+    yield* Scope.addFinalizerExit(parentScope, (exit) => ref.close(exit))
+    const pending = ref.pending(undefined, Deferred.makeUnsafe())
+    const value = yield* acquire(pending.scope)
+    if (ref.state === pending) ref.publish(pending, value)
+    return ref
   })
 
-  readonly state: MutableRef.MutableRef<State<A, E>>
-  readonly acquire: (scope: Scope.Scope) => Effect.Effect<A, E>
-  readonly teardownAddress: EntityAddress | undefined
-  constructor(
-    state: MutableRef.MutableRef<State<A, E>>,
-    acquire: (scope: Scope.Scope) => Effect.Effect<A, E>,
-    teardownAddress?: EntityAddress
+  private state: State<A> = { _tag: "Closed" }
+  private readonly releaseScope: Scope.Scope
+  private readonly acquire: (scope: Scope.Scope) => Effect.Effect<A>
+  private readonly teardownAddress: EntityAddress | undefined
+  private constructor(
+    releaseScope: Scope.Scope,
+    acquire: (scope: Scope.Scope) => Effect.Effect<A>,
+    teardownAddress: EntityAddress | undefined
   ) {
-    this.state = state
+    this.releaseScope = releaseScope
     this.acquire = acquire
     this.teardownAddress = teardownAddress
   }
 
-  latch = Latch.makeUnsafe(true)
+  /** Returns the value only after acquisition and preparation complete. */
+  getUnsafe(): A | undefined {
+    return this.state._tag === "Ready" ? this.state.value : undefined
+  }
+
+  /** Waits for a ready value; interrupts when the ref closes. */
+  readonly await: Effect.Effect<A> = Effect.suspend(() => {
+    const s = this.state
+    switch (s._tag) {
+      case "Closed":
+        return Effect.interrupt
+      case "Ready":
+        return Effect.succeed(s.value)
+      case "Pending":
+      case "Failed":
+        return Deferred.await(s.ready)
+    }
+  })
 
-  getUnsafe(): Option.Option<A> {
-    if (this.state.current._tag === "Acquired") {
-      return Option.some(this.state.current.value)
+  /**
+   * Replaces the generation, holding waiters until acquisition and `prepare` finish.
+   * Returns `undefined` if closed, if `from` differs from the ready or preparing
+   * value, or if `from` is omitted while a rebuild is pending.
+   *
+   * Acceptance immediately blocks waiters; run the returned effect to release
+   * the predecessor and build its replacement. Closing or superseding the ref
+   * interrupts the rebuild. Failure wakes waiters with its cause; the next
+   * rebuild must omit `from` and await cleanup. Interruption during predecessor
+   * release instead carries waiters forward without awaiting that release again.
+   */
+  rebuildUnsafe(options?: {
+    readonly from?: A | undefined
+    readonly prepare?: ((value: A) => Effect.Effect<void>) | undefined
+  }): Effect.Effect<void> | undefined {
+    const s = this.state
+    const from = options?.from
+    let pending: Pending<A>
+    switch (s._tag) {
+      case "Closed":
+        return undefined
+      case "Ready": {
+        if (from !== undefined && from !== s.value) return undefined
+        pending = this.pending(s.scope, Deferred.makeUnsafe())
+        break
+      }
+      case "Failed": {
+        if (from !== undefined) return undefined
+        pending = this.pending(s.releasing, s.ready)
+        break
+      }
+      case "Pending": {
+        if (from === undefined || s.value !== from) return undefined
+        s.work?.interruptUnsafe()
+        pending = this.pending(s.scope, s.ready)
+        break
+      }
     }
-    return Option.none()
+    return this.run(pending, options?.prepare)
   }
 
-  rebuildUnsafe(): Effect.Effect<void, E> {
-    const s = this.state.current
-    if (s._tag === "Closed") {
-      return Effect.interrupt
+  private pending(
+    releases: Scope.Closeable | Fiber.Fiber<void> | undefined,
+    ready: Deferred.Deferred<A>
+  ): Pending<A> {
+    const pending: Pending<A> = {
+      _tag: "Pending",
+      scope: Scope.makeUnsafe(),
+      releases,
+      releasing: false,
+      ready,
+      value: undefined,
+      work: undefined
     }
-    const prevScope = s.scope
-    const scope = Scope.makeUnsafe()
-    this.latch.closeUnsafe()
-    MutableRef.set(this.state, { _tag: "Acquiring", scope })
-    const teardownAddress = this.teardownAddress
-    return Effect.suspend(() => {
-      const close = Scope.close(prevScope, Exit.void)
-      if (!teardownAddress) return close
-      acquireEntity(teardownAddress)
-      return Effect.ensuring(close, Effect.sync(() => releaseEntity(teardownAddress)))
+    this.state = pending
+    return pending
+  }
+
+  private publish(pending: Pending<A>, value: A): void {
+    this.state = { _tag: "Ready", scope: pending.scope, value }
+    Deferred.doneUnsafe(pending.ready, Exit.succeed(value))
+  }
+
+  private run(pending: Pending<A>, prepare: ((value: A) => Effect.Effect<void>) | undefined): Effect.Effect<void> {
+    const work = Effect.suspend(() => {
+      if (this.state !== pending) return Effect.interrupt
+      const releases = pending.releases
+      if (!releases) return Effect.void
+      pending.releasing = true
+      return Effect.andThen(
+        Fiber.isFiber(releases) ? Fiber.join(releases) : Effect.flatMap(this.release(releases), Fiber.join),
+        Effect.sync(() => {
+          pending.releasing = false
+        })
+      )
     }).pipe(
-      Effect.andThen(this.acquire(scope)),
+      Effect.andThen(Effect.suspend(() => this.acquire(pending.scope))),
+      Effect.tap((value) => {
+        if (this.state !== pending) return Effect.interrupt
+        pending.value = value
+        return prepare ? prepare(value) : Effect.void
+      }),
       Effect.flatMap((value) => {
-        if (this.state.current._tag === "Closed") {
-          return Effect.interrupt
-        }
-        MutableRef.set(this.state, { _tag: "Acquired", scope, value })
-        return this.latch.open
-      })
-    ).pipe(
+        if (this.state !== pending) return Effect.interrupt
+        this.publish(pending, value)
+        return Effect.void
+      }),
       Effect.onExit((exit) => {
-        if (Exit.isSuccess(exit)) {
+        if (Exit.isSuccess(exit) || this.state !== pending) {
+          return Effect.void
+        }
+        if (pending.releasing) {
+          // No resource was acquired. Carry waiters forward without rejoining the stalled release.
+          this.state = { _tag: "Failed", ready: pending.ready, releasing: undefined }
           return Effect.void
         }
-        return Scope.close(scope, exit).pipe(
-          Effect.ensuring(Effect.sync(() => {
-            const state = this.state.current
-            if (state._tag === "Acquiring" && state.scope === scope) {
-              MutableRef.set(this.state, { _tag: "Failed", scope, cause: exit.cause })
-              this.latch.openUnsafe()
-            }
-          }))
-        )
+        return Effect.map(this.release(pending.scope), (releasing) => {
+          if (this.state !== pending) return
+          this.state = { _tag: "Failed", ready: Deferred.makeUnsafe(), releasing }
+          Deferred.doneUnsafe(pending.ready, Exit.failCause(exit.cause))
+        })
       })
     )
+    return Effect.flatMap(Effect.forkChild(work, { startImmediately: true }), (fiber) => {
+      pending.work = fiber
+      // Replaced or closed before the fiber handle existed.
+      if (this.state !== pending) fiber.interruptUnsafe()
+      return Fiber.join(fiber)
+    })
   }
 
-  await: Effect.Effect<A, E> = Effect.suspend(() => {
-    const s = this.state.current
-    if (s._tag === "Closed") {
-      return Effect.interrupt
-    } else if (s._tag === "Acquired") {
-      return Effect.succeed(s.value)
-    } else if (s._tag === "Failed") {
-      return Effect.failCause(s.cause)
+  // A stalled release must not prevent rebuild interruption.
+  private release(scope: Scope.Closeable): Effect.Effect<Fiber.Fiber<void>> {
+    const close = Scope.close(scope, Exit.void)
+    return Effect.forkIn(
+      this.teardownAddress ? aroundEntity(this.teardownAddress, close) : close,
+      this.releaseScope,
+      { startImmediately: true }
+    )
+  }
+
+  private close(exit: Exit.Exit<unknown, unknown>): Effect.Effect<void> {
+    const s = this.state
+    this.state = { _tag: "Closed" }
+    switch (s._tag) {
+      case "Closed":
+        return Effect.void
+      case "Ready":
+        return Scope.close(s.scope, exit)
+      case "Failed": {
+        Deferred.doneUnsafe(s.ready, Effect.interrupt)
+        return Effect.void
+      }
+      case "Pending": {
+        Deferred.doneUnsafe(s.ready, Effect.interrupt)
+        s.work?.interruptUnsafe()
+        const close = Scope.close(s.scope, exit)
+        return s.releases && !Fiber.isFiber(s.releases) ? Effect.andThen(Scope.close(s.releases, exit), close) : close
+      }
     }
-    return Effect.flatMap(this.latch.await, () => this.await)
-  })
+  }
 }

package/src/encoding/Base64.ts

@@ -1,6 +1,7 @@
 /**
  * Base64 encoding and decoding helpers.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import * as Result from "../Result.ts"
@@ -34,6 +35,7 @@ import { EncodingError } from "./EncodingError.ts"
  * @see {@link decode} for decoding standard Base64 to bytes
  * @see {@link decodeString} for decoding standard Base64 to UTF-8 text
  *
+ * @stability stable
  * @category encoding
  * @since 4.0.0
  */
@@ -62,6 +64,7 @@ export const encode: (input: Uint8Array | string) => string = (input) =>
  * Base64.decode("SGVsbG8=") // => Result.succeed(new Uint8Array([72, 101, 108, 108, 111]))
  * ```
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */
@@ -138,6 +141,7 @@ export const decode = (str: string): Result.Result<Uint8Array, EncodingError> =>
  * Base64.decodeString("aGVsbG8=") // => Result.succeed("hello")
  * ```
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */

package/src/encoding/Base64Url.ts

@@ -1,6 +1,7 @@
 /**
  * URL-safe Base64 encoding and decoding helpers.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import * as Result from "../Result.ts"
@@ -34,6 +35,7 @@ import { EncodingError } from "./EncodingError.ts"
  * @see {@link decode} for decoding URL-safe Base64 to bytes
  * @see {@link decodeString} for decoding URL-safe Base64 to UTF-8 text
  *
+ * @stability stable
  * @category encoding
  * @since 4.0.0
  */
@@ -62,6 +64,7 @@ export const encode: (input: Uint8Array | string) => string = (input) =>
  * Base64Url.decode("SGVsbG8_") // => Result.succeed(new Uint8Array([72, 101, 108, 108, 111, 63]))
  * ```
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */
@@ -116,6 +119,7 @@ export const decode = (str: string): Result.Result<Uint8Array, EncodingError> =>
  * Base64Url.decodeString("aGVsbG8_") // => Result.succeed("hello?")
  * ```
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */

package/src/encoding/EncodingError.ts

@@ -1,6 +1,7 @@
 /**
  * Shared error type for encoding and decoding operations.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import * as Data from "../Data.ts"
@@ -22,6 +23,7 @@ import { hasProperty } from "../Predicate.ts"
  *
  * @see {@link isEncodingError} for the public guard that checks this marker
  *
+ * @stability stable
  * @category type IDs
  * @since 4.0.0
  */
@@ -34,6 +36,7 @@ export const EncodingErrorTypeId = "~effect/encoding/EncodingError" as const
  *
  * Use to type the marker carried by `EncodingError` values.
  *
+ * @stability stable
  * @category type IDs
  * @since 4.0.0
  */
@@ -55,6 +58,7 @@ export type EncodingErrorTypeId = typeof EncodingErrorTypeId
  *
  * @see {@link isEncodingError} for checking whether a value is an EncodingError
  *
+ * @stability stable
  * @category errors
  * @since 4.0.0
  */
@@ -92,6 +96,7 @@ export class EncodingError extends Data.TaggedError("EncodingError")<{
  * @see {@link EncodingError} for the structured error produced by failed
  * encoding and decoding operations
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */

package/src/encoding/Hex.ts

@@ -1,6 +1,7 @@
 /**
  * Hexadecimal encoding, decoding, and random value helpers.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import * as Result from "../Result.ts"
@@ -26,6 +27,7 @@ import { EncodingError } from "./EncodingError.ts"
  * Hex.encode(bytes) // => "48656c6c6f"
  * ```
  *
+ * @stability stable
  * @category encoding
  * @since 4.0.0
  */
@@ -47,6 +49,7 @@ export const encode: (input: Uint8Array | string) => string = (input) =>
  * security-sensitive values, use the `Crypto.Crypto` service's `randomBytes`
  * method and encode the result with {@link encode}.
  *
+ * @stability stable
  * @category encoding
  * @since 4.0.0
  */
@@ -173,6 +176,7 @@ const random32 = (): string => {
  * Hex.decode("48656c6c6f") // => Result.succeed(new Uint8Array([72, 101, 108, 108, 111]))
  * ```
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */
@@ -233,6 +237,7 @@ export const decode = (str: string): Result.Result<Uint8Array, EncodingError> =>
  * Hex.decodeString("68656c6c6f") // => Result.succeed("hello")
  * ```
  *
+ * @stability stable
  * @category decoding
  * @since 4.0.0
  */

package/src/encoding/Toml.ts

@@ -283,7 +283,7 @@ class TomlParser {
     if (multiline) {
       this.expect("\"")
       this.expect("\"")
-      if (this.peek() === "\n") this.advance()
+      this.advance(this.input.startsWith("\r\n", this.index) ? 2 : this.peek() === "\n" ? 1 : 0)
     }
     let output = ""
     while (!this.done) {
@@ -347,7 +347,7 @@ class TomlParser {
     if (multiline) {
       this.expect("'")
       this.expect("'")
-      if (this.peek() === "\n") this.advance()
+      this.advance(this.input.startsWith("\r\n", this.index) ? 2 : this.peek() === "\n" ? 1 : 0)
     }
     const start = this.index
     while (!this.done) {

package/src/encoding/Yaml.ts

@@ -523,6 +523,12 @@ class YamlParser {
     }
     this.index = end
 
+    let contentEnd = content.length
+    while (contentEnd > 0 && content[contentEnd - 1].length === 0) contentEnd--
+    const trailingBreaks = Math.max(0, content.length - contentEnd - (end === this.lines.length ? 1 : 0)) +
+      (contentEnd > 0 && start + contentEnd < this.lines.length ? 1 : 0)
+    content.length = contentEnd
+
     let output = ""
     if (style === "|") {
       output = content.join("\n")
@@ -543,11 +549,9 @@ class YamlParser {
           previousMoreIndented = moreIndented
         }
       }
-      output += "\n".repeat(blankLines)
     }
-    if (chomp === "keep") return output.endsWith("\n") ? output : `${output}\n`
-    output = output.replace(/\n+$/, "")
-    return chomp === "strip" ? output : `${output}\n`
+    if (chomp === "keep") return output + "\n".repeat(trailingBreaks)
+    return chomp === "clip" && contentEnd > 0 && trailingBreaks > 0 ? `${output}\n` : output
   }
 
   private skipBlankLines(): number {

package/src/encoding/index.ts

@@ -6,21 +6,25 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
+ * @stability stable
  * @since 4.0.0
  */
 export * as Base64 from "./Base64.ts"
 
 /**
+ * @stability stable
  * @since 4.0.0
  */
 export * as Base64Url from "./Base64Url.ts"
 
 /**
+ * @stability stable
  * @since 4.0.0
  */
 export * as EncodingError from "./EncodingError.ts"
 
 /**
+ * @stability stable
  * @since 4.0.0
  */
 export * as Hex from "./Hex.ts"

package/src/eventlog/SqlEventJournal.ts

@@ -56,7 +56,7 @@ export const make = (options?: {
       pg: () =>
         sql`
           CREATE TABLE IF NOT EXISTS ${entryTableSql} (
-            id UUID PRIMARY KEY,
+            id BYTEA PRIMARY KEY,
             event TEXT NOT NULL,
             primary_key TEXT NOT NULL,
             payload BYTEA NOT NULL,
@@ -95,8 +95,8 @@ export const make = (options?: {
       pg: () =>
         sql`
           CREATE TABLE IF NOT EXISTS ${remotesTableSql} (
-            remote_id UUID NOT NULL,
-            entry_id UUID NOT NULL,
+            remote_id BYTEA NOT NULL,
+            entry_id BYTEA NOT NULL,
             sequence INT NOT NULL,
             PRIMARY KEY (remote_id, entry_id)
           )`,
@@ -343,12 +343,26 @@ const SqlUint8Array = Schema.Union([Schema.Uint8Array, ArrayBuffer]).pipe(
 
 const SqlEntryId = SqlUint8Array.pipe(Schema.decodeTo(EventJournal.EntryId))
 
+const SqlNatural = Schema.Union([
+  Schema.Natural,
+  Schema.FiniteFromString.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0)),
+  Schema.BigInt.pipe(
+    Schema.decodeTo(
+      Schema.Natural,
+      SchemaTransformation.transform({
+        decode: Number,
+        encode: BigInt
+      })
+    )
+  )
+])
+
 const EntryRow = Schema.Struct({
   id: SqlEntryId,
   event: Schema.String,
   primary_key: Schema.String,
   payload: SqlUint8Array,
-  timestamp: Schema.Int
+  timestamp: SqlNatural
 })
 
 const EntryRowArray = Schema.Array(EntryRow)