@supersoniks/concorde 4.9.0 → 4.9.1

package/src/docs/_decorators/get.md

@@ -13,10 +13,53 @@ Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) as the first argument.
 
 `${prop}` on the endpoint or config key is resolved on the host. While a placeholder is `null` or `undefined`, no GET runs. Optional `skipEmptyPlaceholder: true` also blocks `""` (empty string only). Details: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
 
+## Options (`GetOptions`)
+
+Pass as the **second** argument (scoped config) or **third** (with a configuration key). Same shape as send decorators where applicable:
+
+| Option | Description |
+|--------|-------------|
+| `skipEmptyPlaceholder` | Treat `""` as not ready (see [Dynamic path](#docs/_misc/dynamic-path.md/dynamic-path)). |
+| `refetchEveryMs` | Automatic polling interval (ms). `0` or omitted = no polling. |
+| `triggerKey` | `DataProviderKey` — `PublisherManager.get(...).invalidate()` on that publisher re-runs the GET. |
+
+### Manual refetch (`triggerKey`)
+
+Same pattern as [@post](#docs/_decorators/post.md/post): a publisher acts as a **signal**, independent of the response payload.
+
+```typescript
+import { get, type ApiResult } from "@supersoniks/concorde/decorators";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { dp } from "@supersoniks/concorde/core/utils/PublisherProxy";
+
+const geoCommunesEndpoint = new Endpoint<GeoCommuneRow[]>(
+  "communes?limit=5&fields=nom,code",
+);
+const geoCommunesRefreshKey = new DataProviderKey<void>(
+  "docsDemoGeoCommunesRefresh",
+);
+
+@get(geoCommunesEndpoint, apiConfigurationKey, {
+  triggerKey: geoCommunesRefreshKey,
+})
+@state()
+payload: ApiResult<GeoCommuneRow[]> | null = null;
+
+// Same component or anywhere else:
+dp(geoCommunesRefreshKey).invalidate();
+```
+
+Prefer `triggerKey` over mutating the API configuration publisher when you only want to **reload the same URL** — no need to touch `serviceURL`, tokens, etc.
+
+The docs mock adds an **`X-Fetched-At`** response header on `/docs-mock-api/geo/communes` so live demos can show when the last fetch happened (`response.headers.get("X-Fetched-At")`).
+
 ## When the GET runs again
 
 - A referenced Lit property changes (endpoint path and/or config key contains `${...}`).
 - `set` on the active configuration publisher (`onInternalMutation`).
+- `triggerKey` publisher `invalidate()`.
+- `refetchEveryMs` polling (after each successful fetch).
 
 ## Import
 
@@ -42,6 +85,8 @@ payload: ApiResult<User> | null = null;
 
 ## Live demos
 
+`@get` with **`triggerKey`** — refresh button + `X-Fetched-At` timestamp in the UI:
+
 <sonic-code>
   <template>
     <docs-demo-sources for="demo-api-get"></docs-demo-sources>
@@ -49,12 +94,13 @@ payload: ApiResult<User> | null = null;
   </template>
 </sonic-code>
 
-Dynamic config and endpoint path (`demo-api-get-configuration-key` in doc sources):
+Dynamic config and endpoint path. Manual refetch is triggered **from a separate component** (same `triggerKey` publisher):
 
 <sonic-code>
   <template>
     <docs-demo-sources for="demo-api-get-configuration-key"></docs-demo-sources>
     <demo-api-get-configuration-key></demo-api-get-configuration-key>
+    <demo-api-get-refresh-remote></demo-api-get-refresh-remote>
   </template>
 </sonic-code>
 

package/src/docs/components/docs-demo-sources.ts

@@ -255,10 +255,15 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-api-get-configuration-key": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 126,
+      line: 147,
       label: "demo-api-get-configuration-key",
     },
-    { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
+    {
+      path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
+      line: 239,
+      label: "demo-api-get-refresh-remote",
+    },
+    { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API + triggerKey" },
   ],
   "demo-api-get-publish-subscribe": [
     {

package/src/docs/example/decorators-demo-geo.ts

@@ -49,3 +49,8 @@ export const geoCommunesApiGetEndpointDynamic = new Endpoint<GeoCommuneRow[]>(
 export const geoCommunesApiGetPublishKey = new DataProviderKey<
   ApiResult<GeoCommuneRow[]>
 >(geoCommunesApiGetEndpoint.path);
+
+/** Signal de refetch manuel pour les démos `@get` (voir `triggerKey`). */
+export const docsDemoGeoCommunesRefreshKey = new DataProviderKey<void>(
+  "docsDemoGeoCommunesRefresh",
+);

package/src/docs/example/decorators-demo-subscribe-publish-get-demos.ts

@@ -1,32 +1,37 @@
 import { html, LitElement } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
 import { get, handle, publish, subscribe } from "@supersoniks/concorde/decorators";
-import type {
-  APIConfiguration,
-  ApiResult,
-} from "@supersoniks/concorde/core/utils/api";
+import type { ApiResult } from "@supersoniks/concorde/core/utils/api";
 import { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
 import { sub } from "@supersoniks/concorde/directives";
 import {
+  dp,
   get as storeGet,
   set,
 } from "@supersoniks/concorde/core/utils/PublisherProxy";
 import { publishDemoKey } from "./docs-provider-keys";
-import {
-  docsDemoDynApiConfAKey,
-  docsDemoDynApiConfBKey,
-} from "./decorators-demo-geo";
 import { tailwind } from "../tailwind";
 import "./decorators-demo-init";
 import {
   docsDemoDynApiConfKeyTemplate,
   docsDemoGeoApiConfigurationKey,
+  docsDemoGeoCommunesRefreshKey,
   geoCommunesApiGetEndpoint,
   geoCommunesApiGetEndpointDynamic,
   geoCommunesApiGetPublishKey,
   type GeoCommuneRow,
 } from "./decorators-demo-geo";
 
+function formatFetchedAt(response: Response | null | undefined): string {
+  const raw = response?.headers.get("X-Fetched-At");
+  if (!raw) return "—";
+  try {
+    return new Date(raw).toLocaleTimeString();
+  } catch {
+    return raw;
+  }
+}
+
 type PublishDemoData = {
   email: string;
   message: string;
@@ -90,22 +95,35 @@ export class DemoPublish extends LitElement {
 export class DemoApiGet extends LitElement {
   static styles = [tailwind];
 
-  @get(geoCommunesApiGetEndpoint, docsDemoGeoApiConfigurationKey)
+  @get(geoCommunesApiGetEndpoint, docsDemoGeoApiConfigurationKey, {
+    triggerKey: docsDemoGeoCommunesRefreshKey,
+  })
   @state()
   geoApiPayload?: ApiResult<GeoCommuneRow[]>;
 
+  private refresh() {
+    dp(docsDemoGeoCommunesRefreshKey).invalidate();
+  }
+
   render() {
     const rows = this.geoApiPayload?.result;
     const status = this.geoApiPayload?.response?.status;
+    const fetchedAt = formatFetchedAt(this.geoApiPayload?.response ?? null);
     return html`
       <div class="space-y-2">
         <p class="text-sm text-neutral-600 dark:text-neutral-400">
           <code>@get</code> — même service que
           <code>sonic-queue</code> (<code>/docs-mock-api/geo/</code>).
           Propriété typée <code>ApiResult&lt;T&gt;</code>.
+          Refetch via <code>triggerKey</code> (<code
+            >docsDemoGeoCommunesRefresh</code
+          >).
         </p>
+        <sonic-button size="sm" @click=${this.refresh}>Rafraîchir</sonic-button>
         ${status != null
-          ? html`<p class="text-xs text-neutral-500">HTTP ${status}</p>`
+          ? html`<p class="text-xs text-neutral-500">
+              HTTP ${status} · fetch ${fetchedAt}
+            </p>`
           : ""}
         ${this.geoApiPayload === null
           ? html`<p class="text-neutral-500">Chargement…</p>`
@@ -139,29 +157,23 @@ export class DemoApiGetConfigurationKey extends LitElement {
   @property({ type: Number })
   communeLimit = 5;
 
-  @get(geoCommunesApiGetEndpointDynamic, docsDemoDynApiConfKeyTemplate)
+  @get(geoCommunesApiGetEndpointDynamic, docsDemoDynApiConfKeyTemplate, {
+    triggerKey: docsDemoGeoCommunesRefreshKey,
+  })
   @state()
   geoApiPayloadDyn?: ApiResult<GeoCommuneRow[]>;
 
-  private touchCurrentConfigPublisher() {
-    const key =
-      this.configSlot === "A" ? docsDemoDynApiConfAKey : docsDemoDynApiConfBKey;
-    const cur = storeGet(key) as APIConfiguration;
-    set(key, {
-      ...cur,
-      blockUntilDone: !cur.blockUntilDone,
-    });
-  }
-
   render() {
     const rows = this.geoApiPayloadDyn?.result;
     const status = this.geoApiPayloadDyn?.response?.status;
+    const fetchedAt = formatFetchedAt(this.geoApiPayloadDyn?.response ?? null);
     return html`
       <div class="space-y-3">
         <p class="text-sm text-neutral-600 dark:text-neutral-400">
           Config dynamique (<code>docsDemoDynApiConf\${configSlot}</code>) +
-          path d’endpoint avec <code>communeLimit</code>. « Toucher la config »
-          déclenche un nouveau GET.
+          path d’endpoint avec <code>communeLimit</code>. Le refetch manuel
+          passe par <code>triggerKey</code> — voir le bouton « ailleurs »
+          ci-dessous dans la doc.
         </p>
         <div class="flex flex-wrap gap-2 items-center">
           <span class="text-xs text-neutral-500">Limite API :</span>
@@ -196,16 +208,11 @@ export class DemoApiGetConfigurationKey extends LitElement {
             }}
             >docsDemoDynApiConfB</sonic-button
           >
-          <sonic-button
-            size="sm"
-            @click=${() => this.touchCurrentConfigPublisher()}
-            >Toucher la config</sonic-button
-          >
         </div>
         ${status != null
           ? html`<p class="text-xs text-neutral-500">
-              HTTP ${status} · limit=${this.communeLimit} · conf=
-              docsDemoDynApiConf${this.configSlot}
+              HTTP ${status} · fetch ${fetchedAt} · limit=${this.communeLimit} ·
+              conf=docsDemoDynApiConf${this.configSlot}
             </p>`
           : ""}
         ${this.geoApiPayloadDyn === null
@@ -230,6 +237,35 @@ export class DemoApiGetConfigurationKey extends LitElement {
   }
 }
 
+/** Déclenche le refetch d’un `@get` distant via `triggerKey` (sans toucher la config). */
+@customElement("demo-api-get-refresh-remote")
+export class DemoApiGetRefreshRemote extends LitElement {
+  static styles = [tailwind];
+
+  private refreshFromElsewhere() {
+    dp(docsDemoGeoCommunesRefreshKey).invalidate();
+  }
+
+  render() {
+    return html`
+      <div
+        class="rounded border border-dashed border-neutral-300 dark:border-neutral-600 p-3 space-y-2"
+      >
+        <p class="text-sm text-neutral-600 dark:text-neutral-400">
+          Composant séparé — même publisher
+          <code>docsDemoGeoCommunesRefresh</code> :
+        </p>
+        <pre
+          class="text-xs bg-neutral-100 dark:bg-neutral-800 p-2 rounded overflow-x-auto"
+        ><code>dp(docsDemoGeoCommunesRefreshKey).invalidate();</code></pre>
+        <sonic-button size="sm" variant="secondary" @click=${this.refreshFromElsewhere}>
+          Rafraîchir le GET (depuis ailleurs)
+        </sonic-button>
+      </div>
+    `;
+  }
+}
+
 @customElement("demo-api-get-publish-subscribe")
 export class DemoApiGetPublishSubscribe extends LitElement {
   static styles = [tailwind];
@@ -247,6 +283,9 @@ export class DemoApiGetPublishSubscribe extends LitElement {
     const rows =
       this.geoCommunesFromSubscribe ?? this.geoApiPayloadPublished?.result;
     const status = this.geoApiPayloadPublished?.response?.status;
+    const fetchedAt = formatFetchedAt(
+      this.geoApiPayloadPublished?.response ?? null,
+    );
     return html`
       <div class="space-y-2">
         <p class="text-sm text-neutral-600 dark:text-neutral-400">
@@ -255,7 +294,9 @@ export class DemoApiGetPublishSubscribe extends LitElement {
           rendu que <code>&lt;demo-api-get&gt;</code> (doc @get).
         </p>
         ${status != null
-          ? html`<p class="text-xs text-neutral-500">HTTP ${status}</p>`
+          ? html`<p class="text-xs text-neutral-500">
+              HTTP ${status} · fetch ${fetchedAt}
+            </p>`
           : ""}
         ${this.geoApiPayloadPublished === null
           ? html`<p class="text-neutral-500">Chargement…</p>`

package/src/docs/mock-api/router.ts

@@ -242,7 +242,9 @@ export async function handleDocsMockApiRequest(
   }
 
   if (subPath === "/geo/communes" || subPath.startsWith("/geo/communes")) {
-    return json(geoCommunes(url));
+    return json(geoCommunes(url), {
+      headers: { "X-Fetched-At": new Date().toISOString() },
+    });
   }
 
   const jokeMatch = subPath.match(/^\/jokes\/joke\/([^/]+)$/);

package/src/docs/search/docs-search.json

@@ -4030,7 +4030,22 @@
     }
   },
   {
-    "search": "Use { dynamic: true } when the decorated property must follow the DOM. The live demo below shows only the resolved attribute value — no store, no reparenting.\n",
+    "search": "Use { dynamic: true } when the decorated property must follow the DOM. With Lit, add @state() on the same property so template updates are visible when the observer assigns a new value.\n",
+    "files": {
+      "docs/_decorators/ancestor-attribute.md": {
+        "title": "@ancestorAttribute",
+        "hashes": {
+          "dynamic-mode": {
+            "count": 1,
+            "title": "Dynamic mode",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "The live demo below shows only the resolved attribute value — no store, no reparenting.\n",
     "files": {
       "docs/_decorators/ancestor-attribute.md": {
         "title": "@ancestorAttribute",
@@ -4729,6 +4744,21 @@
       }
     }
   },
+  {
+    "search": "Pass as the second argument (scoped config) or third (with a configuration key). Same shape as send decorators where applicable:\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "options-getoptions": {
+            "count": 1,
+            "title": "Options (`GetOptions`)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "Same demo service as sonic-queue (/docs-mock-api/geo/). Publisher setup lives in decorators-demo-geo.ts and decorators-demo-subscribe-publish-get-demos.ts.\n",
     "files": {