injectQubeeList

function@qubeejs/angularsrc/lib/lists/inject-qubee-list.ts

A list’s state as a reactive handle, read from the URL and written back to it

Takes a list declared once with the core’s defineList() and returns its typed state, the request to fetch it with, and the functions that change it. The URL is the source of truth; the adapter provided under QUBEE_LIST_ADAPTER decides which URL — the Angular Router’s, the browser history’s or one kept in memory.

• state updates as soon as set() is called, so an input never lags behind a debounce or a navigation.
• set() navigates at most once per call. Defaults stay out of the URL, a change to anything but the page returns to page 1, and parameters the list does not own are kept.
• request changes once per navigation, never per keystroke, and only when the URI or the headers differ.
• Back, Forward or a link elsewhere drop anything not yet in the URL and cancel a pending debounce; so does destroying the injection context. A click on a link while a debounce waits commits it first.

Signature

injectQubeeList<TList extends ListDefinition<ListParams, object>>(list: TList, ...args: QubeeListArgs<TList>): QubeeList<TList>

Parameter	Type	Description
list	TList	The list, as defineList() returned it — a module-level constant.
...args	QubeeListArgs<TList>	Options: input (required for a list that declares one), adapter and injector

Returns — The list handle

Throws MissingRouterAdapterError — If no adapter is passed and none is provided.
Throws — If called outside an injection context without an injector.

Usage

@Component({
  template: `
    <input [value]="list.state().q ?? ''" (input)="search($event)" />
    @for (article of articles.value()?.data; track article.id) { <p>{{ article.title }}</p> }
  `
})
export class ArticlesComponent {
  protected readonly list = injectQubeeList(articleList);

  // qubeeHttpResource() from '@qubeejs/angular/http' sends the list's headers
  // and hands the response headers to paginate(), as header-driven drivers need.
  protected readonly articles = qubeeHttpResource<Article>(this.list.request);

  protected search(event: Event): void {
    this.list.set({ q: (event.target as HTMLInputElement).value }, { debounce: 300, replace: true });
  }
}

A list that declares an input — a project id from the route path, say — takes it as input, as a value or a signal; null means “not ready yet” and makes request null:

readonly projectId = input.required<string>();
readonly tasks = injectQubeeList(taskList, { input: () => ({ projectId: this.projectId() }) });