Concorde decorator — @get. @get loads data and stores the result in an optional ApiResult<T> property. Doc ID: docs/_decorators/get. Keywords: Concorde, supersoniks, docs/_decorators/get, get, @get, decorator, ApiResult, undefined, payload.result, payload.response, payload.request, The first argument is always an [, serviceURL, refetch(component). URL: https://concorde.supersoniks.org/crawl/docs/_decorators/get.html.

@get

@get loads data and stores the result in an optional ApiResult<T> property. The property is undefined until a result is available.

• payload.result: typed data;
• payload.response: the HTTP response;
• payload.request: the request that was sent.

Minimal usage

const usersEndpoint = new Endpoint<User[]>("users");

@get(usersEndpoint)
@state()
payload?: ApiResult<User[]>;

The same decorator adapts to a method. The method receives the complete ApiResult<T> payload after each GET:

@get(usersEndpoint)
handleUsers(payload?: ApiResult<User[]>) {
  if (!payload) return;

  console.log(payload.response?.status);
  console.log(payload.result);
}

The first argument is always an Endpoint<T>. API configuration is read from the HTML scope (serviceURL, token, etc.), so the component is usually placed below an element that provides this configuration.

Refetching a GET

From the component

Keep the decorator in a constant to access refetch(component). Refetch only targets the instance passed as the argument, even before it has received a result.

const usersGet = get(new Endpoint<User[]>("users"));

@usersGet
@state()
payload?: ApiResult<User[]>;

async refresh() {
  const payload = await usersGet.refetch(this);
  console.log(payload?.result);
}

refetch(component) returns a Promise<ApiResult<T> | undefined> that resolves after the GET has completed.

The named handle can also decorate a method and be reused for refetching:

const usersGet = get(new Endpoint<User[]>("users"));

@usersGet
handleUsers(payload?: ApiResult<User[]>) {
  // ...
}

@refetch(usersGet)
reloadUsers() {
  // The GET runs and handleUsers receives its payload.
}

From a method decorator

The refetch can decorate a local method. The default is after; if the method returns a Promise, the GET waits for its resolution. The decorated method call also waits for the refetch to complete.

import { refetch } from "@supersoniks/concorde/decorators";

@refetch(usersGet)
async reload() {
  this.userId = "42";
}

Use { when: "before" } when the GET must complete before the method runs:

@refetch(usersGet, { when: "before" })
reloadBefore() {
  // The refetch has completed before this method runs.
}

The method decorator adds an explicit trigger; changes to dynamic endpoint properties and configuration publishers keep their existing automatic behavior.

Options (GetOptions)

Options are the second argument, or the third argument when an API configuration key is provided.

• skipEmptyPlaceholder: blocks the GET when ${prop} is "".
• refetchEveryMs: automatically runs the GET again after this interval (milliseconds). Omit the option, or use 0, to disable polling.
• triggerKey: a publisher whose invalidate() runs the GET again.

With a configuration key, use:

@get(usersEndpoint, apiConfigurationKey)

When the GET runs again

• when the component connects and configuration is available;
• when a property used in ${...} changes;
• when a configuration publisher changes;
• when the triggerKey publisher is invalidated;
• after each response when refetchEveryMs is set.

See Dynamic path placeholders for dynamic path details.

Import

import { get, type ApiResult } from "@supersoniks/concorde/decorators";
import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
import { Endpoint } from "@supersoniks/concorde/utils/endpoint";

Demos

<docs-demo-sources for="demo-api-get"></docs-demo-sources>
    <demo-api-get></demo-api-get>
    <docs-demo-sources for="demo-api-get-method"></docs-demo-sources>
    <demo-api-get-method></demo-api-get-method>
    <docs-demo-sources for="demo-api-get-configuration-key"></docs-demo-sources>
    <demo-api-get-configuration-key></demo-api-get-configuration-key>

See @post, @put, and @patch for write operations.

Advanced

External invalidation is currently available through triggerKey; it is kept out of the main usage examples.