npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@lit/task

v1.0.1

Published

A controller for Lit that renders asynchronous tasks.

Downloads

117,705

Readme

@lit/task

A controller for Lit that renders asynchronous tasks.

Overview

Often a Lit element needs to request, process, and render remote data, for example when querying a REST API for data to be displayed. The Task controller provides a simple pattern for encapsulating this behavior in an easily reusable way. The controller integrates with a host Lit element. The user provides a task function and an arguments function. Whenever the element updates, the arguments are checked and if any have changed, the task is initiated.

Sometimes it's important to control exactly when a task runs. For example, task arguments may have changed, but it should not run until an interaction event like a button click. For these types of use cases, the autoRun option can be set to false. This setting can be passed in the task configuration and/or be set on the Task itself. It defaults to true, but when autoRun is false, the task does not run automatically when arguments change. Instead, it can be run explicitly by calling run(arg?). By default, run() uses the task's configured arguments function, but a custom array of arguments may be optionally passed.

The controller requests an update of the element whenever the task status changes. Task status is provided via the TaskStatus object which has values for INITIAL, PENDING, COMPLETE, and ERROR. The task result is available via its value property, or via the error property when an error occurs. The task render method may also be used to easily render different task states. It accepts an object which optionally can implement methods for initial, pending, complete(value), and error(error). These methods typically return a Lit TemplateResult to render.

Installation

From inside your project folder, run:

$ npm install @lit/task

Usage

Here's an example:

import {Task, TaskStatus} from '@lit/task';
// ...

class MyElement extends LitElement {
  @state()
  private _userId: number = -1;

  private _apiTask = new Task(
    this,
    ([userId]) =>
      fetch(`//example.com/api/userInfo?${userId}`).then((response) =>
        response.json()
      ),
    () => [this._userId]
  );

  render() {
    return html`
      <div>User Info</div>
      ${this._apiTask.render({
        pending: () => html`Loading user info...`,
        complete: (user) => html`${user.name}`,
      })}
      <!-- ... -->
    `;
  }
}

Argument equality

Task accepts an argsEqual to determine if a task should auto-run by testing a new arguments array for equality against the previous run's arguments array.

The default equality function is shallowArrayEquals, which compares each argument in the array against the previous array with notEqual from @lit/reactive-element (which itself uses ===). This works well if your arguments are primitive values like strings.

If your arguments are objects, you will want to use a more sophisticated equality function. Task provides deepArrayEquals in the deep-equals.js module, which compares each argument with a deepEquals function that can handle primitives, objects, Arrays, Maps, Sets, RegExps, or objects that implement toString() or toValue().

Contributing

Please see CONTRIBUTING.md.