@supersoniks/concorde 5.1.0 → 5.1.2

package/docs/src/docs/_decorators/get.md

@@ -1,162 +0,0 @@
-# @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
-
-```typescript
-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:
-
-```typescript
-@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>`](#docs/_misc/endpoint.md/endpoint). 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.
-
-```typescript
-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:
-
-```typescript
-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.
-
-```typescript
-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:
-
-```typescript
-@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:
-
-```typescript
-@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](#docs/_misc/dynamic-path.md/dynamic-path) for
-dynamic path details.
-
-## Import
-
-<sonic-code language="typescript">
-  <template>
-import { get, type ApiResult } from "@supersoniks/concorde/decorators";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
-  </template>
-</sonic-code>
-
-## Demos
-
-<sonic-code>
-  <template>
-    <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>
-  </template>
-</sonic-code>
-
-See [@post](#docs/_decorators/post.md/post),
-[@put](#docs/_decorators/put.md/put), and
-[@patch](#docs/_decorators/patch.md/patch) for write operations.
-
-## Advanced
-
-External invalidation is currently available through `triggerKey`; it is kept
-out of the main usage examples.

package/docs/src/docs/_decorators/handle.md

@@ -1,175 +0,0 @@
-# @handle
-
-Typed callback on one or more `DataProviderKey<T>` paths: invokes the decorated **method** when a publisher assigns a value (calculations, side effects, updating other `@state` properties, etc.).
-
-Unlike [@subscribe](#docs/_decorators/subscribe.md/subscribe), nothing is bound to the decorated member — only your method runs. `@handle` is typed and accepts up to **3 keys** plus an optional trailing `HandleOptions` object. It supersedes the string-based [@onAssign](#docs/_decorators/on-assign.md/on-assign).
-
-By default the method is called on **every** assignment, even when the value is `null` / `undefined`. Use the options below to restrict that.
-
-## Import
-
-<sonic-code language="typescript">
-  <template>
-import { handle, Skip } from "@supersoniks/concorde/decorators";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-import { get, set } from "@supersoniks/concorde/utils";
-  </template>
-</sonic-code>
-
-## Basic example
-
-<sonic-code language="typescript">
-  <template>
-type DemoCounterData = { count: number };
-const demoDataKey = new DataProviderKey&lt;DemoCounterData&gt;("demoData");
-
-@customElement("demo-handle")
-export class DemoHandle extends LitElement {
-  @state() doubled = 0;
-  @state() lastUpdate = "";
-
-  @handle(demoDataKey.count)
-  onCountChange(count: number) {
-    this.doubled = count * 2;
-    this.lastUpdate = new Date().toLocaleTimeString();
-  }
-
-  incrementCount() {
-    const data = get(demoDataKey);
-    set(demoDataKey, { ...data, count: data.count + 1 });
-  }
-
-  render() {
-    return html`
-      &lt;p&gt;Doubled count: ${this.doubled}&lt;/p&gt;
-      &lt;p&gt;&lt;small&gt;Last update: ${this.lastUpdate}&lt;/small&gt;&lt;/p&gt;
-      &lt;sonic-button @click=${this.incrementCount}&gt;Increment&lt;/sonic-button&gt;
-    `;
-  }
-}
-  </template>
-</sonic-code>
-
-<sonic-code>
-  <template>
-    <docs-demo-sources for="demo-handle"></docs-demo-sources>
-    <demo-handle></demo-handle>
-  </template>
-</sonic-code>
-
-## Dynamic path
-
-Placeholders in `DataProviderKey` resolve from the host component’s properties (same rules as `@bind` / `@subscribe`).
-
-<sonic-code language="typescript">
-  <template>
-type User = { firstName: string; lastName: string; email: string };
-
-@customElement("demo-handle-dynamic")
-export class DemoHandleDynamic extends LitElement {
-  @property({ type: Number })
-  userIndex = 0;
-
-  @state() displayName = "";
-  @state() lastUpdate = "";
-
-  @handle(new DataProviderKey&lt;User, { userIndex: number }&gt;("demoUsers.${userIndex}"))
-  onUserAssigned(user: User) {
-    this.displayName = `${user.firstName} ${user.lastName}`;
-    this.lastUpdate = new Date().toLocaleTimeString();
-  }
-
-  render() {
-    return html`...`;
-  }
-}
-  </template>
-</sonic-code>
-
-<sonic-code>
-  <template>
-    <docs-demo-sources for="demo-handle-dynamic"></docs-demo-sources>
-    <demo-handle-dynamic></demo-handle-dynamic>
-  </template>
-</sonic-code>
-
-## Multiple paths
-
-`@handle` accepts up to **3 keys**; the method receives one strongly-typed argument per key, in order. Each assignment triggers the method, so make your method safe against partial values (or use `waitForAllDefined`, see below).
-
-<sonic-code language="typescript">
-  <template>
-type QueueConfig = { onInactivity: { stillHere: { show: boolean } } };
-const config = new DataProviderKey&lt;QueueConfig&gt;("sessionQueueConfig");
-const idle = new DataProviderKey&lt;{ isIdle: boolean }&gt;("idleStatus");
-
-@customElement("demo-handle-multi")
-export class DemoHandleMulti extends LitElement {
-
-  // show: boolean, isIdle: boolean — fully typed from the keys
-  @handle(config.onInactivity.stillHere.show, idle.isIdle)
-  onInactivity(show: boolean, isIdle: boolean) {
-    if (show === true && isIdle === true) this.openModal();
-    else this.closeModal();
-  }
-}
-  </template>
-</sonic-code>
-
-## Options (`HandleOptions`)
-
-Pass an options object as the **last** argument. The names map to real situations seen in the apps.
-
-### `waitForAllDefined`
-
-Only call the method once **all** watched keys are defined (non `null` / `undefined`). This reproduces the historical `@onAssign` semantics — use it when the logic only makes sense with every source ready (e.g. building a date from `date` + `timeZone` + `direction`).
-
-<sonic-code language="typescript">
-  <template>
-@handle(trip.departureDate, trip.event.timeZone, form.direction, {
-  waitForAllDefined: true,
-})
-updateDepartureDate(date: number, timeZone: string, direction: string) {
-  // called only when the three values are all available
-  this.formDate = formatDate(date, timeZone, direction);
-}
-  </template>
-</sonic-code>
-
-### `skip`
-
-Do **not** call the method when a received value belongs to one of the listed **categories** (the `Skip` enum). Each entry is a named category — not a value — so there is no value/pattern ambiguity (e.g. `{}` is `Skip.EmptyObject`, an explicit "empty object" category, never a value comparison).
-
-| Category | Matches |
-| --- | --- |
-| `Skip.Nullish` | `null` or `undefined` (a publisher always emits `null`, never `undefined`) |
-| `Skip.EmptyString` | `""` |
-| `Skip.EmptyObject` | object with no keys (`{}`), arrays excluded |
-| `Skip.EmptyArray` | empty array (`[]`) |
-
-Useful when a not-yet-initialized publisher emits `{}` as a "loading" state. For a **specific value** (e.g. a particular string), guard inside the method instead.
-
-<sonic-code language="typescript">
-  <template>
-@handle(user.profile, { skip: [Skip.Nullish, Skip.EmptyObject] })
-onProfile(profile: Profile) {
-  // not called while the publisher still holds {} (not loaded yet)
-  this.displayName = profile.firstName;
-}
-  </template>
-</sonic-code>
-
-> Options can be combined, e.g. `@handle(a, b, { waitForAllDefined: true, skip: [Skip.Nullish] })`. For any **arbitrary** validation on a specific value, just guard inside the method (`if (!isValid(v)) return;`) — that is exactly what an `accept`-style predicate would do, since `@handle` only runs your method.
-
-### `skipEmptyPlaceholder`
-
-On a **dynamic key path** (`"items.${itemId}"`), if `true`, a placeholder resolved to `''` is treated as not ready (no subscription) — **empty string only**, not `0` or `false`. See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
-
-## Highlights
-
-- Strict typing: the method receives one argument per key, in order.
-- Up to 3 keys; for 4+ keys (rare), keep [@onAssign](#docs/_decorators/on-assign.md/on-assign) for now.
-- By default the method runs on **every** assignment, even with `null` / `undefined` (unlike `@onAssign`, which waits for all values). Opt back into that behavior with `waitForAllDefined`.
-- `skip` filters out values by **named category** (e.g. `[Skip.Nullish, Skip.EmptyObject]`); for arbitrary checks on a specific value, guard inside the method.
-
-See also [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) and [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).