@supersoniks/concorde 4.9.91 → 4.9.93

package/src/core/utils/api.spec.ts

@@ -0,0 +1,73 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import API, { type APIConfiguration } from "./api";
+
+const baseConfig: APIConfiguration = {
+  serviceURL: "https://api.example.test",
+  token: null,
+  userName: null,
+  password: null,
+  authToken: null,
+  tokenProvider: null,
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("API GET synchronization", () => {
+  it("deduplicates fetch while sharing the response metadata", async () => {
+    const response = new Response(JSON.stringify({ items: [1, 2] }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+    const fetchMock = vi.fn().mockResolvedValue(response);
+    vi.stubGlobal("fetch", fetchMock);
+
+    const firstApi = new API({
+      ...baseConfig,
+      serviceURL: "https://api.example.test/concurrent",
+    });
+    const secondApi = new API({
+      ...baseConfig,
+      serviceURL: "https://api.example.test/concurrent",
+    });
+
+    const [firstPayload, secondPayload] = await Promise.all([
+      firstApi.getDetailed<{ items: number[] }>("items"),
+      secondApi.getDetailed<{ items: number[] }>("items"),
+    ]);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(firstPayload?.response?.status).toBe(200);
+    expect(secondPayload?.response?.status).toBe(200);
+    expect(firstPayload?.result).toEqual({ items: [1, 2] });
+    expect(secondPayload?.result).toEqual({ items: [1, 2] });
+  });
+
+  it("permet un nouvel appel après une erreur réseau", async () => {
+    const response = new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+    const fetchMock = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("offline"))
+      .mockResolvedValueOnce(response);
+    vi.stubGlobal("fetch", fetchMock);
+
+    const api = new API({
+      ...baseConfig,
+      serviceURL: "https://api.example.test/recover",
+    });
+
+    await expect(api.getDetailed<{ ok: boolean }>("items")).resolves.toBe(
+      undefined,
+    );
+    const payload = await api.getDetailed<{ ok: boolean }>("items");
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(payload?.response?.status).toBe(200);
+    expect(payload?.result).toEqual({ ok: true });
+  });
+});

package/src/core/utils/api.ts

@@ -49,6 +49,11 @@ export type ApiResult<T> = {
 /** @deprecated Utiliser `ApiResult`. */
 export type ApiGetResult<T> = ApiResult<T>;
 
+type SharedGetResult = {
+  processed: ResultTypeInterface;
+  response?: Response;
+};
+
 /** Extrait le corps typé depuis le résultat traité par `handleResult`. */
 function extractTypedApiResult<T>(
   processed: ResultTypeInterface | null | undefined,
@@ -67,7 +72,10 @@ class API {
   /**
    * Ce tableau static permet de ne pas appeler plusieurs fois le même service lors d'appel concurrents en GET.
    */
-  private static loadingGetPromises: Map<string, Promise<unknown>> = new Map();
+  private static loadingGetPromises: Map<
+    string,
+    Promise<SharedGetResult | null>
+  > = new Map();
   /**
    * L'url de base du service sans endpoint
    */
@@ -202,10 +210,14 @@ class API {
     if (httpCode === 498 && !API.failledTokenUpdates.has(this.serviceURL)) {
       this.handleInvalidToken(this.token);
       if (lastCall.apiMethod === "get") {
-        result = await this[lastCall.apiMethod](
+        const retryResult = await this.get(
           lastCall.path,
           lastCall.additionalHeaders,
         );
+        if (retryResult == null) {
+          throw new Error("GET retry failed after token refresh");
+        }
+        result = retryResult;
       } else {
         result = await this[lastCall.apiMethod](
           lastCall.path,
@@ -384,13 +396,16 @@ class API {
     });
   }
 
-  async get<T>(path: string, additionalHeaders?: HeadersInit) {
-    await this.firstCallDone();
-    if (this.blockUntilDone) {
-      API.firstCallDoneFlags.set(this.serviceURL, "loading");
-    }
+  async get<T>(
+    path: string,
+    additionalHeaders?: HeadersInit,
+  ): Promise<(T & ResultTypeInterface) | null> {
     const regExp = /dataProvider\((.*?)\)(.*?)$/;
     if (regExp.test(path)) {
+      if (this.blockUntilDone) {
+        await this.firstCallDone();
+        API.firstCallDoneFlags.set(this.serviceURL, "loading");
+      }
       const match = path.match(regExp);
       if (!match) throw new Error("dataProvider path is not valid");
       return await this.localGet<T>(match[1], match[2]);
@@ -405,9 +420,21 @@ class API {
     const mapKey = JSON.stringify({
       url: url,
       headers: headers,
+      credentials: this.credentials,
+      cache: this.cache,
+      keepAlive: this.keepAlive,
     });
+
+    // Les GET non bloquants doivent pouvoir rejoindre une requête déjà en vol.
+    // Sinon firstCallDone() sérialise les appels avant que la map de déduplication
+    // ne soit consultée, ce qui déclenche deux fetch pour deux consommateurs.
+    if (this.blockUntilDone) {
+      await this.firstCallDone();
+      API.firstCallDoneFlags.set(this.serviceURL, "loading");
+    }
+
     if (!API.loadingGetPromises.has(mapKey)) {
-      const promise = new Promise(async (resolve) => {
+      const promise = new Promise<SharedGetResult | null>(async (resolve) => {
         try {
           const result = await fetch(url, {
             headers: headers,
@@ -416,16 +443,22 @@ class API {
             keepalive: this.keepAlive,
           });
           const handledResult = await this.handleResult(result, lastCall);
-          resolve(handledResult);
+          resolve({
+            processed: handledResult,
+            response: this.lastResult,
+          });
         } catch (e) {
+          API.firstCallDoneFlags.set(this.serviceURL, "error");
           resolve(null);
         }
       });
       API.loadingGetPromises.set(mapKey, promise);
     }
-    const result = (await API.loadingGetPromises.get(mapKey)) as T;
+    const sharedResult = await API.loadingGetPromises.get(mapKey);
     API.loadingGetPromises.delete(mapKey);
-    return result as T & ResultTypeInterface;
+    if (!sharedResult) return null;
+    this.lastResult = sharedResult.response;
+    return sharedResult.processed as T & ResultTypeInterface;
   }
 
   /**

package/src/docs/_decorators/get.md

@@ -17,6 +17,19 @@ const usersEndpoint = new Endpoint<User[]>("users");
 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
@@ -37,15 +50,36 @@ const usersGet = get(new Endpoint<User[]>("users"));
 @state()
 payload?: ApiResult<User[]>;
 
-refresh() {
-  usersGet.refetch(this);
+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.
+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";
@@ -56,12 +90,12 @@ async reload() {
 }
 ```
 
-Use `{ when: "before" }` when the GET must be scheduled before the method:
+Use `{ when: "before" }` when the GET must complete before the method runs:
 
 ```typescript
 @refetch(usersGet, { when: "before" })
 reloadBefore() {
-  // The refetch is scheduled before this method runs.
+  // The refetch has completed before this method runs.
 }
 ```
 
@@ -76,6 +110,7 @@ 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:
 
@@ -88,6 +123,7 @@ With a configuration key, use:
 - 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
@@ -109,6 +145,8 @@ import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
   <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>

package/src/docs/_decorators/patch.md

@@ -16,14 +16,27 @@ const patchUser = patch(new Endpoint<User>("users/42"), bodyKey);
 payload?: ApiResult<User>;
 ```
 
+The same decorator adapts to a method:
+
+```typescript
+@patch(new Endpoint<User>("users/42"), bodyKey)
+handlePatch(payload?: ApiResult<User>) {
+  if (payload?.response?.ok) console.log(payload.result);
+}
+```
+
 To run the operation again from the component:
 
 ```typescript
-savePatch() {
-  patchUser.send(this);
+async savePatch() {
+  await patchUser.send(this);
 }
 ```
 
+`send(component)` returns a Promise resolved after the PATCH completes. See
+[@post](#docs/_decorators/post.md/post) for the method-decorator form and the
+`when: "before"` option.
+
 The PATCH is also sent automatically when the body mutates, unless
 `autoPostOnBodyMutation: false` is set. The available options are described in
 [@post](#docs/_decorators/post.md/post):
@@ -32,6 +45,7 @@ The PATCH is also sent automatically when the body mutates, unless
 - `skipIfBodyMissing`
 - `refetchEveryMs`
 - `skipEmptyPlaceholder`
+- `triggerKey`
 
 Pass explicit API configuration as the third argument:
 

package/src/docs/_decorators/post.md

@@ -17,6 +17,15 @@ const createUser = post(new Endpoint<User>("users"), userBodyKey);
 payload?: ApiResult<User>;
 ```
 
+The same decorator adapts to a method and receives the complete payload:
+
+```typescript
+@post(new Endpoint<User>("users"), userBodyKey)
+handleCreate(payload?: ApiResult<User>) {
+  if (payload?.response?.ok) console.log(payload.result);
+}
+```
+
 The current body is read from `userBodyKey`. By default, the POST is sent when
 the component connects and after each body mutation. Mutations in the same
 frame are coalesced into one request.
@@ -32,18 +41,21 @@ Keep the decorator to access `send(component)`. The body is read again when the
 operation runs.
 
 ```typescript
-saveAgain() {
-  createUser.send(this);
+async saveAgain() {
+  const payload = await createUser.send(this);
+  console.log(payload?.result);
 }
 ```
 
-`send()` is useful for “Save” or “Retry” buttons. It can repeat an operation
-with side effects.
+`send()` returns a `Promise<ApiResult<T> | undefined>` that resolves after the
+operation completes. It is useful for “Save” or “Retry” buttons and can repeat
+an operation with side effects.
 
 ### From a method decorator
 
 The send action can decorate a local method. It runs after the method by
-default and waits for an eventual Promise to resolve:
+default, waits for an eventual Promise to resolve, and the decorated method
+call waits for the send to complete:
 
 ```typescript
 import { send } from "@supersoniks/concorde/decorators";
@@ -54,12 +66,12 @@ async save() {
 }
 ```
 
-Use `{ when: "before" }` when the body must be sent before the method runs:
+Use `{ when: "before" }` when the send must complete before the method runs:
 
 ```typescript
 @send(createUser, { when: "before" })
 saveBefore() {
-  // The POST is scheduled before this method runs.
+  // The POST has completed before this method runs.
 }
 ```
 
@@ -80,6 +92,7 @@ is provided.
   repeating the operation is intended.
 - `skipEmptyPlaceholder`: block the request when a `${...}` placeholder is
   `""`.
+- `triggerKey`: a publisher whose `invalidate()` sends the POST again.
 
 With a configuration key:
 
@@ -96,6 +109,7 @@ dynamic path details.
 - after a body mutation, unless `autoPostOnBodyMutation: false`;
 - when a property used in `${...}` changes;
 - when a configuration publisher changes;
+- when the `triggerKey` publisher is invalidated;
 - when `send()` is called;
 - after each response when `refetchEveryMs` is set.
 
@@ -115,6 +129,8 @@ import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
   <template>
     <docs-demo-sources for="demo-api-post"></docs-demo-sources>
     <demo-api-post></demo-api-post>
+    <docs-demo-sources for="demo-api-post-method"></docs-demo-sources>
+    <demo-api-post-method></demo-api-post-method>
     <docs-demo-sources for="demo-api-post-dynamic"></docs-demo-sources>
     <demo-api-post-dynamic></demo-api-post-dynamic>
   </template>

package/src/docs/_decorators/put.md

@@ -16,14 +16,27 @@ const updateUser = put(new Endpoint<User>("users/42"), bodyKey);
 payload?: ApiResult<User>;
 ```
 
+The same decorator adapts to a method:
+
+```typescript
+@put(new Endpoint<User>("users/42"), bodyKey)
+handleUpdate(payload?: ApiResult<User>) {
+  if (payload?.response?.ok) console.log(payload.result);
+}
+```
+
 To run the operation again from the component:
 
 ```typescript
-update() {
-  updateUser.send(this);
+async update() {
+  await updateUser.send(this);
 }
 ```
 
+`send(component)` returns a Promise resolved after the PUT completes. See
+[@post](#docs/_decorators/post.md/post) for the method-decorator form and the
+`when: "before"` option.
+
 The PUT is also sent automatically when the body mutates, unless
 `autoPostOnBodyMutation: false` is set. See
 [@post](#docs/_decorators/post.md/post) for the option details:
@@ -32,6 +45,7 @@ The PUT is also sent automatically when the body mutates, unless
 - `skipIfBodyMissing`
 - `refetchEveryMs`
 - `skipEmptyPlaceholder`
+- `triggerKey`
 
 Pass explicit API configuration as the third argument:
 

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

@@ -222,7 +222,7 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-publish": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 29,
+      line: 32,
       label: "demo-publish",
     },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
@@ -230,7 +230,7 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-subscribe-dynamic": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 313,
+      line: 269,
       label: "demo-subscribe-dynamic",
     },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
@@ -238,7 +238,7 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-sub-template": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 282,
+      line: 238,
       label: "demo-sub-template",
     },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
@@ -246,16 +246,23 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-api-get": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 83,
+      line: 86,
       label: "demo-api-get",
     },
     { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
     { path: "src/docs/mock-api/router.ts", label: "mock router" },
   ],
+  "demo-api-get-method": [
+    {
+      path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
+      label: "demo-api-get-method",
+    },
+    { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
+  ],
   "demo-api-get-configuration-key": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 147,
+      line: 127,
       label: "demo-api-get-configuration-key",
     },
     { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
@@ -263,7 +270,7 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-api-get-publish-subscribe": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 227,
+      line: 178,
       label: "demo-api-get-publish-subscribe",
     },
     { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
@@ -276,6 +283,13 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
     },
     { path: "src/docs/mock-api/router.ts", label: "mock router" },
   ],
+  "demo-api-post-method": [
+    {
+      path: "src/docs/example/decorators-demo-post.ts",
+      label: "demo-api-post-method",
+    },
+    { path: "src/docs/mock-api/router.ts", label: "mock router" },
+  ],
   "demo-api-post-dynamic": [
     {
       path: "src/docs/example/decorators-demo-post.ts",
@@ -295,7 +309,7 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-handle": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 360,
+      line: 316,
       label: "demo-handle",
     },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
@@ -303,7 +317,7 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-handle-dynamic": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 396,
+      line: 351,
       label: "demo-handle-dynamic",
     },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },

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

@@ -65,6 +65,12 @@ export const docsDemoPostPublishRequestKey = new DataProviderKey<RegisterRequest
 export const docsDemoPostTriggerKey = new DataProviderKey<number>(
   "docsDemoPostTrigger",
 );
+export const docsDemoPostMethodRequestKey = new DataProviderKey<RegisterRequest>(
+  "docsDemoPostMethodRequest",
+);
+export const docsDemoPostMethodTriggerKey = new DataProviderKey<number>(
+  "docsDemoPostMethodTrigger",
+);
 export const docsDemoPostDynamicRequestKey = new DataProviderKey<SessionSyncRequest>(
   "docsDemoPostDynamicRequest",
 );
@@ -140,6 +146,70 @@ export class DemoApiPost extends LitElement {
   }
 }
 
+@customElement("demo-api-post-method")
+export class DemoApiPostMethod extends LitElement {
+  static styles = [tailwind];
+
+  @state()
+  private payload?: ApiResult<RegisterResult>;
+
+  connectedCallback() {
+    super.connectedCallback();
+    set(docsDemoPostMethodRequestKey, {
+      email: "method@concorde.local",
+      password: "method-password",
+    });
+    set(docsDemoPostMethodTriggerKey, 0);
+  }
+
+  @post(
+    registerPostEndpoint,
+    docsDemoPostMethodRequestKey,
+    docsDemoReqresApiConfigurationKey,
+    { triggerKey: docsDemoPostMethodTriggerKey },
+  )
+  handlePayload(payload?: ApiResult<RegisterResult>) {
+    this.payload = payload;
+  }
+
+  private updateBody() {
+    set(docsDemoPostMethodRequestKey, {
+      email: `method-${Date.now()}@concorde.local`,
+      password: "method-password",
+    });
+  }
+
+  private resend() {
+    dp(docsDemoPostMethodTriggerKey).invalidate();
+  }
+
+  render() {
+    const result = this.payload?.result;
+    return html`
+      <div class="space-y-3">
+        <div class="flex flex-wrap items-center gap-2">
+          <span class="text-sm font-medium">✉️ POST function mode</span>
+          <sonic-button size="sm" @click=${this.updateBody}>
+            Update body &amp; POST
+          </sonic-button>
+          <sonic-button size="sm" variant="secondary" @click=${this.resend}>
+            Invalidate trigger
+          </sonic-button>
+        </div>
+        <p class="text-sm text-neutral-600 dark:text-neutral-400">
+          The <code>@post</code> decorator calls
+          <code>handlePayload</code> with the complete API payload.
+        </p>
+        <p class="text-xs text-neutral-500">
+          HTTP status:
+          <strong>${this.payload?.response?.status ?? "loading…"}</strong>
+          · email: <strong>${result?.email ?? "—"}</strong>
+        </p>
+      </div>
+    `;
+  }
+}
+
 @customElement("demo-api-post-dynamic")
 export class DemoApiPostDynamic extends LitElement {
   static styles = [tailwind];