const INTERNAL_DEFAULT_DUPLICATE_RELEASE_MESSAGE = "Permit release was called more than once."

/**
 * @description 表示 `Permit` 在检测到重复 `release()` 误用时使用的处理函数。
 */
export type PermitDuplicateReleaseHandler = (message: string) => void

/**
 * @description 表示构造 `Permit` 时的可选元信息。
 */
export interface PermitOptions<Details> {
  /**
   * @description `Permit` 被正常释放时的回调。
   */
  onRelease: () => void

  /**
   * @description 释放句柄附带的只读细节。
   */
  details?: Details | undefined

  /**
   * @description 重复释放时的可选处理器。
   */
  onDuplicateRelease?: PermitDuplicateReleaseHandler | undefined

  /**
   * @description 重复释放时的提示信息。
   */
  duplicateReleaseMessage?: string | undefined
}

/**
 * @description 表示与某个协调原语关联的 permit 细节。
 */
export interface CoordinationPermitDetails<Coordination extends string = string> {
  coordination: Coordination
}

/**
 * @description 表示带有模式信息的 permit 细节。
 */
export interface ModePermitDetails<
  Coordination extends string,
  Mode extends string,
> extends CoordinationPermitDetails<Coordination> {
  mode: Mode
}

/**
 * @description 表示带有 key 信息的 permit 细节。
 */
export interface KeyedPermitDetails<
  Coordination extends string,
  Key,
> extends CoordinationPermitDetails<Coordination> {
  key: Key
}

/**
 * @description 表示一次已成功获取的协调资源占用句柄。
 *
 * `Permit` 本身不负责排队或调度，它只是对“当前持有一次资源”的显式表达，
 * 并把释放动作和调试元信息封装在一起。
 */
export class Permit<Details = undefined> implements Disposable {
  /**
   * @description 创建该 permit 时附带的只读元信息。
   */
  readonly details: Details | undefined

  private isReleasedValue: boolean

  private readonly onRelease: () => void

  private readonly onDuplicateRelease: PermitDuplicateReleaseHandler | undefined

  private readonly duplicateReleaseMessage: string

  /**
   * @description 创建一个 permit，并绑定释放时需要执行的回调。
   */
  constructor(options: PermitOptions<Details>) {
    this.details = options.details
    this.isReleasedValue = false
    this.onRelease = options.onRelease
    this.onDuplicateRelease = options.onDuplicateRelease
    this.duplicateReleaseMessage =
      options.duplicateReleaseMessage ?? INTERNAL_DEFAULT_DUPLICATE_RELEASE_MESSAGE
  }

  /**
   * @description 读取当前 `Permit` 是否已经释放。
   */
  isReleased(): boolean {
    return this.isReleasedValue
  }

  /**
   * @description 读取当前 `Permit` 是否仍然有效。
   */
  isActive(): boolean {
    return this.isReleasedValue === false
  }

  /**
   * @description 主动释放本次占用。
   */
  release(): void {
    if (this.isReleasedValue === true) {
      this.onDuplicateRelease?.(this.duplicateReleaseMessage)
      return
    }

    this.isReleasedValue = true
    this.onRelease()
  }

  /**
   * @description 与其他模块保持一致的显式释放别名。
   */
  dispose(): void {
    this.release()
  }

  /**
   * @description 支持 `using` 语法自动释放。
   */
  [Symbol.dispose](): void {
    this.release()
  }
}