Interface OnceAsync<T>

Readonly[toStringTag]

get

• get(): Option<Awaited<T>>

  Gets the reference to the underlying value.

  Returns Option<Awaited<T>>

  Some(value) if initialized, None otherwise.

  Example

  const once = OnceAsync<number>();
  console.log(once.get()); // None
  
  await once.getOrInit(async () => 42);
  console.log(once.get()); // Some(42)
  Copy

getOrInit

• getOrInit(fn: () => Awaited<T> | PromiseLike<Awaited<T>>): Promise<Awaited<T>>

  Gets the contents, initializing it with async fn if empty.

  If multiple calls occur concurrently, only the first one will run the initialization function. Other calls will wait for it to complete.

  Parameters

  • fn: () => Awaited<T> | PromiseLike<Awaited<T>>

    A function that returns PromiseLike<Awaited<T>> or Awaited<T> to initialize.

  Returns Promise<Awaited<T>>

  A promise that resolves to the stored value (Awaited<T>).

  Example

  const db = OnceAsync<Database>();
  
  // Multiple concurrent calls - only one connection happens
  const [db1, db2, db3] = await Promise.all([
      db.getOrInit(() => Database.connect(url)),
      db.getOrInit(() => Database.connect(url)),
      db.getOrInit(() => Database.connect(url)),
  ]);
  // db1 === db2 === db3
  Copy

getOrTryInit

• getOrTryInit<E>(
      fn: () => AsyncLikeResult<Awaited<T>, E> | Result<Awaited<T>, E>,
  ): AsyncResult<Awaited<T>, E>

  Gets the contents, initializing it with async fn if empty. If fn returns Err, remains uninitialized.

  If multiple calls occur concurrently, only the first one will run the initialization function. Other calls will wait for it to complete.

  Type Parameters

  • E

    The error type.

  Parameters

  • fn: () => AsyncLikeResult<Awaited<T>, E> | Result<Awaited<T>, E>

    A function that returns PromiseLike<Result<Awaited<T>, E>> or Result<Awaited<T>, E>.

  Returns AsyncResult<Awaited<T>, E>

  A promise that resolves to Ok(value) or Err(error).

  Example

  const config = OnceAsync<Config>();
  
  const result = await config.getOrTryInit(async () => {
      try {
          const response = await fetch('/api/config');
          return Ok(await response.json());
      } catch (e) {
          return Err(e as Error);
      }
  });
  Copy

isInitialized

• isInitialized(): boolean

  Returns true if initialized.

  Returns boolean

  Example

  const once = OnceAsync<number>();
  console.log(once.isInitialized()); // false
  
  await once.getOrInit(async () => 42);
  console.log(once.isInitialized()); // true
  Copy

set

• set(value: Awaited<T>): VoidResult<Awaited<T>>

  Sets the contents to value.

  Parameters

  • value: Awaited<T>

    The value to store.

  Returns VoidResult<Awaited<T>>

  Ok(undefined) if empty, Err(value) if already initialized.

  Example

  const once = OnceAsync<number>();
  
  console.log(once.set(42)); // Ok(undefined)
  console.log(once.set(100)); // Err(100) - value returned back
  console.log(once.get()); // Some(42)
  Copy

take

• take(): Option<Awaited<T>>

  Takes the value out, leaving it uninitialized.

  Returns Option<Awaited<T>>

  Some(value) if initialized, None otherwise.

  Example

  const once = OnceAsync<number>();
  await once.getOrInit(async () => 42);
  
  console.log(once.take()); // Some(42)
  console.log(once.get()); // None - now empty
  console.log(once.take()); // None
  Copy

toString

• toString(): string

  Custom toString implementation.

  Returns string

  Example

  const once = OnceAsync<number>();
  console.log(once.toString()); // 'OnceAsync(<uninitialized>)'
  
  await once.getOrInit(async () => 42);
  console.log(once.toString()); // 'OnceAsync(42)'
  Copy

tryInsert

• tryInsert(value: Awaited<T>): Result<Awaited<T>, [Awaited<T>, Awaited<T>]>

  Sets the contents to value if empty, returning a reference to the value.

  Unlike set(), this method returns the stored value on success, and returns both the current and passed values on failure.

  Parameters

  • value: Awaited<T>

    The value to store.

  Returns Result<Awaited<T>, [Awaited<T>, Awaited<T>]>

  Ok(value) if empty, Err([currentValue, passedValue]) if already initialized.

  Example

  const once = OnceAsync<number>();
  
  // First insert succeeds, returns the stored value
  const result1 = once.tryInsert(42);
  console.log(result1.unwrap()); // 42
  
  // Second insert fails, returns [current, passed]
  const result2 = once.tryInsert(100);
  console.log(result2.unwrapErr()); // [42, 100]
  Copy

wait

• wait(): Promise<Awaited<T>>

  Waits for the cell to be initialized, then returns the value.

  If the cell is already initialized, returns immediately. If initialization is in progress, waits for it to complete. If the cell is uninitialized and no initialization is in progress, the returned promise will resolve when another caller initializes the cell.

  Returns Promise<Awaited<T>>

  A promise that resolves to the stored value once initialized.

  Example

  const once = OnceAsync<number>();
  
  // Start waiting in background
  const waitPromise = once.wait();
  
  // Later, initialize the value
  once.set(42);
  
  // waitPromise resolves with 42
  console.log(await waitPromise); // 42
  Copy