/**
 * The `ScopedRef` module provides a mutable reference for values that are tied
 * to scoped resources. Each value stored in a `ScopedRef` is acquired within its
 * own `Scope`, and replacing the value safely releases the resources associated
 * with the previous value.
 *
 * Use `ScopedRef` when an application needs to keep a current resource-backed
 * value, such as a live client, connection, subscription, or cached handle, and
 * later swap it for a newly acquired value without leaking the old resources.
 * Reads are simple, while updates are synchronized and resource-safe.
 *
 * **Gotchas**
 *
 * - A `ScopedRef` must itself be created and used within a `Scope`; when that
 *   scope closes, the currently stored value is finalized.
 * - Use {@link fromAcquire} or {@link set} for resourceful values so acquisition
 *   and finalization are tracked correctly.
 * - Use {@link make} only for values that do not acquire resources.
 * - Updating a `ScopedRef` waits for the replacement acquisition and old
 *   finalization to complete before returning.
 *
 * @since 2.0.0
 */
import * as Effect from "./Effect.ts"
import * as Exit from "./Exit.ts"
import { dual, type LazyArg } from "./Function.ts"
import { PipeInspectableProto } from "./internal/core.ts"
import type { Pipeable } from "./Pipeable.ts"
import * as Scope from "./Scope.ts"
import * as Synchronized from "./SynchronizedRef.ts"

const TypeId = "~effect/ScopedRef"

/**
 * A `ScopedRef` is a reference whose value is associated with resources,
 * which must be released properly. You can both get the current value of any
 * `ScopedRef`, as well as set it to a new value (which may require new
 * resources). The reference itself takes care of properly releasing resources
 * for the old value whenever a new value is obtained.
 *
 * **When to use**
 *
 * Use when an application needs to keep a current resource-backed value and
 * later replace it with another acquired value while ensuring the previous
 * value is released.
 *
 * @category models
 * @since 2.0.0
 */
export interface ScopedRef<in out A> extends Pipeable {
  readonly [TypeId]: typeof TypeId
  readonly backing: Synchronized.SynchronizedRef<readonly [Scope.Closeable, A]>
}

const Proto = {
  ...PipeInspectableProto,
  [TypeId]: TypeId,
  toJSON(this: ScopedRef<any>) {
    return {
      _id: "ScopedRef",
      value: this.backing.backing.ref.current[1]
    }
  }
}

const makeUnsafe = <A>(
  scope: Scope.Closeable,
  value: A
): ScopedRef<A> => {
  const self = Object.create(Proto)
  self.backing = Synchronized.makeUnsafe([scope, value] as const)
  return self
}

/**
 * Creates a new `ScopedRef` from an effect that resourcefully produces a
 * value.
 *
 * **When to use**
 *
 * Use when creating a `ScopedRef` whose initial value requires acquiring
 * resources that must be released.
 *
 * @see {@link make} for creating a `ScopedRef` from a value that does not require resource acquisition
 * @category constructors
 * @since 2.0.0
 */
export const fromAcquire: <A, E, R>(
  acquire: Effect.Effect<A, E, R>
) => Effect.Effect<ScopedRef<A>, E, Scope.Scope | R> = Effect.fnUntraced(function*<A, E, R>(
  acquire: Effect.Effect<A, E, R>
) {
  const scope = Scope.makeUnsafe()
  const value = yield* acquire.pipe(
    Scope.provide(scope),
    Effect.tapCause((cause) => Scope.close(scope, Exit.failCause(cause)))
  )
  const self = makeUnsafe(scope, value)
  yield* Effect.addFinalizer((exit) => Scope.close(self.backing.backing.ref.current[0], exit))
  return self
}, Effect.uninterruptible)

/**
 * Retrieves the current value of the scoped reference synchronously.
 *
 * **When to use**
 *
 * Use when you need immediate synchronous access to the current `ScopedRef`
 * value and can guarantee that reading outside the `Effect` API is safe.
 *
 * @see {@link get} for Effect-wrapped access in Effect programs
 *
 * @category getters
 * @since 4.0.0
 */
export const getUnsafe = <A>(self: ScopedRef<A>): A => self.backing.backing.ref.current[1]

/**
 * Retrieves the current value of the scoped reference effectfully.
 *
 * **When to use**
 *
 * Use to read the value currently stored in a `ScopedRef` inside an `Effect`
 * workflow.
 *
 * @see {@link getUnsafe} for reading the current value synchronously when an unsafe read is acceptable
 *
 * @category getters
 * @since 2.0.0
 */
export const get = <A>(self: ScopedRef<A>): Effect.Effect<A> => Effect.sync(() => getUnsafe(self))

/**
 * Creates a new `ScopedRef` from the specified value.
 *
 * **When to use**
 *
 * Use to create a `ScopedRef` when the initial value is already available or
 * can be produced without acquiring resources.
 *
 * **Details**
 *
 * The `evaluate` function runs when the returned effect runs. The returned
 * effect requires a `Scope`, and the reference closes the currently stored
 * value's scope when that outer scope closes.
 *
 * **Gotchas**
 *
 * Do not use `make` for an initial value whose creation acquires resources; use
 * `fromAcquire` so acquisition and finalization are tracked.
 *
 * @see {@link fromAcquire} for creating a `ScopedRef` from an effect that acquires the initial value
 * @see {@link set} for replacing the current value with a resourcefully acquired value
 *
 * @category constructors
 * @since 2.0.0
 */
export const make = <A>(evaluate: LazyArg<A>): Effect.Effect<ScopedRef<A>, never, Scope.Scope> =>
  Effect.suspend(() => {
    const scope = Scope.makeUnsafe()
    const value = evaluate()
    const self = makeUnsafe(scope, value)
    return Effect.as(Effect.addFinalizer((exit) => Scope.close(self.backing.backing.ref.current[0], exit)), self)
  })

/**
 * Sets the value of this reference to the specified resourcefully-created
 * value, releasing any resources associated with the old value.
 *
 * **When to use**
 *
 * Use to replace the current value of an existing `ScopedRef` with a
 * resourcefully acquired value while releasing resources for the previous
 * value.
 *
 * **Details**
 *
 * This method will not return until either the reference is successfully
 * changed to the new value, with old resources released, or until the attempt
 * to acquire a new value fails.
 *
 * @category setters
 * @since 2.0.0
 */
export const set: {
  /**
   * Sets the value of this reference to the specified resourcefully-created
   * value, releasing any resources associated with the old value.
   *
   * **When to use**
   *
   * Use to replace the current value of an existing `ScopedRef` with a
   * resourcefully acquired value while releasing resources for the previous
   * value.
   *
   * **Details**
   *
   * This method will not return until either the reference is successfully
   * changed to the new value, with old resources released, or until the attempt
   * to acquire a new value fails.
   *
   * @category setters
   * @since 2.0.0
   */
  <A, R, E>(acquire: Effect.Effect<A, E, R>): (self: ScopedRef<A>) => Effect.Effect<void, E, Exclude<R, Scope.Scope>>
  /**
   * Sets the value of this reference to the specified resourcefully-created
   * value, releasing any resources associated with the old value.
   *
   * **When to use**
   *
   * Use to replace the current value of an existing `ScopedRef` with a
   * resourcefully acquired value while releasing resources for the previous
   * value.
   *
   * **Details**
   *
   * This method will not return until either the reference is successfully
   * changed to the new value, with old resources released, or until the attempt
   * to acquire a new value fails.
   *
   * @category setters
   * @since 2.0.0
   */
  <A, R, E>(self: ScopedRef<A>, acquire: Effect.Effect<A, E, R>): Effect.Effect<void, E, Exclude<R, Scope.Scope>>
} = dual(
  2,
  Effect.fnUntraced(
    function*<A, R, E>(
      self: ScopedRef<A>,
      acquire: Effect.Effect<A, E, R>
    ) {
      yield* Scope.close(self.backing.backing.ref.current[0], Exit.void)
      const scope = Scope.makeUnsafe()
      const value = yield* acquire.pipe(
        Scope.provide(scope),
        Effect.tapCause((cause) => Scope.close(scope, Exit.failCause(cause)))
      )
      self.backing.backing.ref.current = [scope, value]
    },
    Effect.uninterruptible,
    (effect, self) => self.backing.semaphore.withPermit(effect)
  )
)