Usage

The simplest way to use @sheepdog/svelte is the following

<script>
  import { task, timeout } from '@sheepdog/svelte';

  const myTask = task(async () => {
    // async stuff
  });
</script>

<button
  on:click={() => {
    myTask.perform();
  }}
>
  do async stuff
</button>

This will run your async function when the user presses the button. “But why not use a normal async function?” I hear you ask.

Because the myTask variable that you used to call perform is also a svelte store that contains a lot of useful information about your task!

Task structure

• isRunning: whether the task is currently running or not
• last: the last task instance, regardless of whether it errored, was canceled, or was successful
• lastCanceled: the last canceled task instance
• lastErrored: the last errored task instance
• lastRunning: the last running task instance, as soon as the task stops running, this will be undefined
• lastSuccessful: the last successful task instance
• performCount: the number of times the task has been run,

type Task = {
  /**
   * whether the task is currently running or not
   */
  isRunning: boolean;
  /**
   * the last task instance, regardless of whether it errored, was canceled, or was successful
   */
  last?: TaskInstance;
  /**
   * the last canceled task instance
   */
  lastCanceled?: TaskInstance;
  /**
   * the last errored task instance
   */
  lastErrored?: TaskInstance;
  /**
   * the last running task instance, as soon as the task stops running, this will be undefined
   */
  lastRunning?: TaskInstance;
  /**
   * the last successful task instance
   */
  lastSuccessful?: TaskInstance;
  /**
   * number of times the task has been run,
   */
  performCount: number;
};

TaskInstance structure

• error: if an error is thrown inside the task instance, it will be found here
• isCanceled: whether the task instance was canceled
• isError: whether the task instance throw an error before completing
• isRunning: whether the task instance is currently running
• isSuccessful: whether the task instance completed successfully
• value: if the task instance completed successfully, this will be the return value

type TaskInstance<TReturn> = {
  /**
   * If an error is thrown inside the task instance, it will be found here.
   */
  error?: Error;

  /**
   * Indicates whether the task instance was canceled.
   */
  isCanceled: boolean;

  /**
   * Indicates whether the task instance threw an error before completing.
   */
  isError: boolean;

  /**
   * Indicates whether the task instance is currently running.
   */
  isRunning: boolean;

  /**
   * Indicates whether the task instance completed successfully.
   */
  isSuccessful: boolean;

  /**
   * If the task instance completed successfully, this will be the return value.
   */
  value?: TReturn;
};

Task modifiers

@sheepdog/svelte allows you to specify a task modifier that changes the behavior of the perform function. By default when you call perform the task will be executed immediately regardless if there are other instances of the same task in execution. For example, you could use the enqueue modifier to instruct @sheepdog/svelte to execute the task instances one after another (in a queue - who would’ve thought)

Here’s how you can specify the modifier:

Dot notation

<script>
  import { task, timeout } from '@sheepdog/svelte';

  const myTask = task.enqueue(async () => {
    // async stuff
  });
</script>

<button on:click={()=>{
  myTask.perform();
}}>
  do async stuff one by one
</button>

Option notation

<script>
  import { task, timeout } from '@sheepdog/svelte';

  const myTask = task(async () => {
    // async stuff
  }, { kind: "enqueue" });
</script>

<button on:click={()=>{
  myTask.perform();
}}>
  do async stuff one by one
</button>

Task modifiers Read everything about task modifiers in our guide

There are currently five task modifiers that you can apply to your task.

• default: the default behavior, every task will run immediately
• drop: if other tasks are already running the new instance will be immediately canceled
• enqueue: every task instance is stored in a queue and executed with a FIFO strategy
• keepLatest: like drop but the last instance will actually be kept around and executed as soon as the current running instance finishes
• restart: the oldest running task instance is canceled and the new one will start running immediately