lit · justinfagnani · Jul 8, 2023 · Jul 8, 2023 · Jul 8, 2023
@@ -0,0 +1,5 @@
+---
+'@lit-labs/task': minor
+---
+
+Allow tasks to have an initial value
@@ -49,6 +49,16 @@ export interface TaskConfig<T extends ReadonlyArray<unknown>, R> {
   task: TaskFunction<T, R>;
   args?: ArgsFunction<T>;
   autoRun?: boolean;
+
+  /**
+   * If initialValue is provided, the task is initialized to the COMPLETE
+   * status and the value is set to initialData.
+   *
+   * Initial args should be coherent with the initialValue, since they are
+   * assumed to be the args that would produce that value. When autoRun is
+   * `true` the task will not auto-run again until the args change.
+   */
+  initialValue?: R;
   onComplete?: (value: R) => unknown;
   onError?: (error: unknown) => unknown;
 }
@@ -185,6 +195,13 @@ export class Task<
     if (taskConfig.autoRun !== undefined) {
       this.autoRun = taskConfig.autoRun;
     }
+    // Providing initialValue puts the task in COMPLETE state and stores the
+    // args immediately so it only runs when they change again.
+    if ('initialValue' in taskConfig) {
+      this._value = taskConfig.initialValue;
+      this.status = TaskStatus.COMPLETE;
+      this._previousArgs = this._getArgs?.();
+    }
   }
 
   hostUpdated() {

@@ -225,6 +225,42 @@ suite('Task', () => {
     assert.equal(el.taskValue, `a1,b1`);
   });
 
+  test('tasks can have initialValue', async () => {
+    // The test helpers make it hard to write proper args callbacks
+    // `args: () => [this.a, this.b]` would work, but `[el.a]` doesn't
+    // since `el` isn't initialized yet. This little hack works:
+    let initializing = true;
+    const el = getTestElement({
+      initialValue: 'initial',
+      args: () => [initializing ? 'a' : el.a, initializing ? 'b' : el.b],
+    });
+    initializing = false;
+    await renderElement(el);
+    assert.equal(el.task.status, TaskStatus.COMPLETE);
+    assert.equal(el.task.value, 'initial');
+    assert.equal(el.taskValue, 'initial');
+
+    // The task is complete, so waiting for it shouldn't change anything
+    await tasksUpdateComplete();
+    assert.equal(el.task.status, TaskStatus.COMPLETE);
+    assert.equal(el.task.value, 'initial');
+
+    // An element update (which checks args again) should not cause a rerun
+    el.requestUpdate();
+    await tasksUpdateComplete();
+    assert.equal(el.task.status, TaskStatus.COMPLETE);
+    assert.equal(el.task.value, 'initial');
+
+    // The task still reruns when arguments change
+    el.a = 'a1';
+    await tasksUpdateComplete();
+    assert.equal(el.task.status, TaskStatus.PENDING);
+    el.resolveTask();
+    await tasksUpdateComplete();
+    assert.equal(el.task.status, TaskStatus.COMPLETE);
+    assert.equal(el.taskValue, `a1,b`);
+  });
+
   test('task error is not reset on rerun', async () => {
     const el = getTestElement({args: () => [el.a, el.b]});
     await renderElement(el);