@supersoniks/concorde 4.9.9 → 4.9.92

package/docs/crawl/docs/_decorators/get.html

@@ -4,8 +4,13 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>@get — Concorde</title>
-  <meta name="description" content="Loads data through API.getDetailed. The decorated property is ApiResult&lt;T&gt; | null: request, response (or null for dataProvider(...) resolution without HTTP), and typed result.">
-  <meta name="keywords" content="Concorde, supersoniks, docs/_decorators/get, get, @get, decorator, API.getDetailed, ApiResult | null, request, response, null, dataProvider(...), result, Endpoint, ApiResult">
+  <meta name="description" content="@get loads data and stores the result in an optional ApiResult&lt;T&gt; property.">
+  <meta name="keywords" content="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), 
+
+">
   <meta name="concorde-doc-id" content="docs/_decorators/get">
   <link rel="canonical" href="https://concorde.supersoniks.org/crawl/docs/_decorators/get.html">
 </head>
@@ -15,104 +20,107 @@
   </header>
   <main>
     <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @get</strong>. Loads data through API.getDetailed. The decorated property is ApiResult&lt;T&gt; | null: request, response (or null for dataProvider(...) resolution without HTTP), and typed result. <span>Doc ID: <code>docs/_decorators/get</code>. Keywords: Concorde, supersoniks, docs/_decorators/get, get, @get, decorator, API.getDetailed, ApiResult | null, request, response, null, dataProvider(...), result, Endpoint, ApiResult. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_decorators/get.html">https://concorde.supersoniks.org/crawl/docs/_decorators/get.html</a>.</span></p>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @get</strong>. @get loads data and stores the result in an optional ApiResult&lt;T&gt; property. <span>Doc ID: <code>docs/_decorators/get</code>. 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: <a href="https://concorde.supersoniks.org/crawl/docs/_decorators/get.html">https://concorde.supersoniks.org/crawl/docs/_decorators/get.html</a>.</span></p>
       <h1 id="get">@get</h1>
-<p>Loads data through <a href="../../core/utils/api.ts"><code>API.getDetailed</code></a>. The decorated property is <strong><code>ApiResult&lt;T&gt; | null</code></strong>: <code>request</code>, <code>response</code> (or <code>null</code> for <code>dataProvider(...)</code> resolution without HTTP), and typed <code>result</code>.</p>
-<p>Pass an <a href="../_misc/endpoint.html#endpoint"><code>Endpoint&lt;T&gt;</code></a> as the first argument. Import <code>get</code> and <code>ApiResult</code> from <code>@supersoniks/concorde/decorators</code>, and <code>Endpoint</code> from <code>@supersoniks/concorde/utils/endpoint</code>.</p>
-<h2 id="configuration">Configuration</h2>
+<p><code>@get</code> loads data and stores the result in an optional <code>ApiResult&lt;T&gt;</code> property.
+The property is <code>undefined</code> until a result is available.</p>
 <ul>
-<li><strong>Default:</strong> <code>HTML.getApiConfiguration(host)</code> (ancestor <code>serviceURL</code>, etc.).</li>
-<li><strong>Second argument:</strong> <code>DataProviderKey&lt;APIConfiguration&gt;</code> — config is read from the publisher at the resolved path; internal mutations trigger another GET. See <a href="../_misc/api-configuration.html#api-configuration">API configuration</a> for mock demos.</li>
+<li><code>payload.result</code>: typed data;</li>
+<li><code>payload.response</code>: the HTTP response;</li>
+<li><code>payload.request</code>: the request that was sent.</li>
 </ul>
-<h2 id="dynamic-path">Dynamic path</h2>
-<p><code>${prop}</code> on the endpoint or config key is resolved on the host. While a placeholder is <code>null</code> or <code>undefined</code>, no GET runs. Optional <code>skipEmptyPlaceholder: true</code> also blocks <code>&quot;&quot;</code> (empty string only). Details: <a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path placeholders</a>.</p>
-<h2 id="options-getoptions">Options (<code>GetOptions</code>)</h2>
-<p>Pass as the <strong>second</strong> argument (scoped config) or <strong>third</strong> (with a configuration key). Same shape as send decorators where applicable:</p>
-<table>
-<thead>
-<tr>
-<th>Option</th>
-<th>Description</th>
-</tr>
-</thead>
-<tbody><tr>
-<td><code>skipEmptyPlaceholder</code></td>
-<td>Treat <code>&quot;&quot;</code> as not ready (see <a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path</a>).</td>
-</tr>
-<tr>
-<td><code>refetchEveryMs</code></td>
-<td>Automatic polling interval (ms). <code>0</code> or omitted = no polling.</td>
-</tr>
-<tr>
-<td><code>triggerKey</code></td>
-<td><code>DataProviderKey</code> — <code>PublisherManager.get(...).invalidate()</code> on that publisher re-runs the GET.</td>
-</tr>
-</tbody></table>
-<h3 id="manual-refetch-triggerkey">Manual refetch (<code>triggerKey</code>)</h3>
-<p>Same pattern as <a href="./post.html#post">@post</a>: a publisher acts as a <strong>signal</strong>, independent of the response payload.</p>
-<pre><code class="language-typescript">import { get, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
-import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
-import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
-import { dp } from &quot;@supersoniks/concorde/core/utils/PublisherProxy&quot;;
+<h2 id="minimal-usage">Minimal usage</h2>
+<pre><code class="language-typescript">const usersEndpoint = new Endpoint&lt;User[]&gt;(&quot;users&quot;);
 
-const geoCommunesEndpoint = new Endpoint&lt;GeoCommuneRow[]&gt;(
-  &quot;communes?limit=5&amp;fields=nom,code&quot;,
-);
-const geoCommunesRefreshKey = new DataProviderKey&lt;void&gt;(
-  &quot;docsDemoGeoCommunesRefresh&quot;,
-);
+@get(usersEndpoint)
+@state()
+payload?: ApiResult&lt;User[]&gt;;
+</code></pre>
+<p>The first argument is always an
+<a href="../_misc/endpoint.html#endpoint"><code>Endpoint&lt;T&gt;</code></a>. API configuration is read
+from the HTML scope (<code>serviceURL</code>, token, etc.), so the component is usually
+placed below an element that provides this configuration.</p>
+<h2 id="refetching-a-get">Refetching a GET</h2>
+<h3 id="from-the-component">From the component</h3>
+<p>Keep the decorator in a constant to access <code>refetch(component)</code>. Refetch only
+targets the instance passed as the argument, even before it has received a
+result.</p>
+<pre><code class="language-typescript">const usersGet = get(new Endpoint&lt;User[]&gt;(&quot;users&quot;));
 
-@get(geoCommunesEndpoint, apiConfigurationKey, {
-  triggerKey: geoCommunesRefreshKey,
-})
+@usersGet
 @state()
-payload: ApiResult&lt;GeoCommuneRow[]&gt; | null = null;
+payload?: ApiResult&lt;User[]&gt;;
 
-// Same component or anywhere else:
-dp(geoCommunesRefreshKey).invalidate();
+async refresh() {
+  const payload = await usersGet.refetch(this);
+  console.log(payload?.result);
+}
+</code></pre>
+<p><code>refetch(component)</code> returns a <code>Promise&lt;ApiResult&lt;T&gt; | undefined&gt;</code> that resolves
+after the GET has completed.</p>
+<h3 id="from-a-method-decorator">From a method decorator</h3>
+<p>The refetch can decorate a local method. The default is <code>after</code>; if the
+method returns a Promise, the GET waits for its resolution. The decorated method
+call also waits for the refetch to complete.</p>
+<pre><code class="language-typescript">import { refetch } from &quot;@supersoniks/concorde/decorators&quot;;
+
+@refetch(usersGet)
+async reload() {
+  this.userId = &quot;42&quot;;
+}
+</code></pre>
+<p>Use <code>{ when: &quot;before&quot; }</code> when the GET must complete before the method runs:</p>
+<pre><code class="language-typescript">@refetch(usersGet, { when: &quot;before&quot; })
+reloadBefore() {
+  // The refetch has completed before this method runs.
+}
+</code></pre>
+<p>The method decorator adds an explicit trigger; changes to dynamic endpoint
+properties and configuration publishers keep their existing automatic behavior.</p>
+<h2 id="options-getoptions">Options (<code>GetOptions</code>)</h2>
+<p>Options are the second argument, or the third argument when an API
+configuration key is provided.</p>
+<ul>
+<li><code>skipEmptyPlaceholder</code>: blocks the GET when <code>${prop}</code> is <code>&quot;&quot;</code>.</li>
+<li><code>refetchEveryMs</code>: automatically runs the GET again after this interval
+(milliseconds). Omit the option, or use <code>0</code>, to disable polling.</li>
+<li><code>triggerKey</code>: a publisher whose <code>invalidate()</code> runs the GET again.</li>
+</ul>
+<p>With a configuration key, use:</p>
+<pre><code class="language-typescript">@get(usersEndpoint, apiConfigurationKey)
 </code></pre>
-<p>Prefer <code>triggerKey</code> over mutating the API configuration publisher when you only want to <strong>reload the same URL</strong> — no need to touch <code>serviceURL</code>, tokens, etc.</p>
-<p>The docs mock adds an <strong><code>X-Fetched-At</code></strong> response header on <code>/docs-mock-api/geo/communes</code> so live demos can show when the last fetch happened (<code>response.headers.get(&quot;X-Fetched-At&quot;)</code>).</p>
 <h2 id="when-the-get-runs-again">When the GET runs again</h2>
 <ul>
-<li>A referenced Lit property changes (endpoint path and/or config key contains <code>${...}</code>).</li>
-<li><code>set</code> on the active configuration publisher (<code>onInternalMutation</code>).</li>
-<li><code>triggerKey</code> publisher <code>invalidate()</code>.</li>
-<li><code>refetchEveryMs</code> polling (after each successful fetch).</li>
+<li>when the component connects and configuration is available;</li>
+<li>when a property used in <code>${...}</code> changes;</li>
+<li>when a configuration publisher changes;</li>
+<li>when the <code>triggerKey</code> publisher is invalidated;</li>
+<li>after each response when <code>refetchEveryMs</code> is set.</li>
 </ul>
+<p>See <a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path placeholders</a> for
+dynamic path details.</p>
 <h2 id="import">Import</h2>
 <pre><code class="language-typescript">import { get, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
-import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
 import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
 </code></pre>
-<h2 id="minimal-example">Minimal example</h2>
-<p>Same demo service as <a href="../../core/components/functional/queue/queue.demo.ts"><code>sonic-queue</code></a> (<code>/docs-mock-api/geo/</code>). Publisher setup lives in <code>decorators-demo-geo.ts</code> and <code>decorators-demo-subscribe-publish-get-demos.ts</code>.</p>
-<pre><code class="language-typescript">@get(new Endpoint&lt;User&gt;(&quot;users/${userId}&quot;))
-@state()
-payload: ApiResult&lt;User&gt; | null = null;
-</code></pre>
-<h2 id="live-demos">Live demos</h2>
-<p><code>@get</code> with <strong><code>triggerKey</code></strong> — refresh button + <code>X-Fetched-At</code> timestamp in the UI:</p>
+<h2 id="demos">Demos</h2>
 <pre><code>&lt;docs-demo-sources for=&quot;demo-api-get&quot;&gt;&lt;/docs-demo-sources&gt;
     &lt;demo-api-get&gt;&lt;/demo-api-get&gt;
-</code></pre>
-<p>Dynamic config and endpoint path. Manual refetch is triggered <strong>from a separate component</strong> (same <code>triggerKey</code> publisher):</p>
-<pre><code>&lt;docs-demo-sources for=&quot;demo-api-get-configuration-key&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;docs-demo-sources for=&quot;demo-api-get-configuration-key&quot;&gt;&lt;/docs-demo-sources&gt;
     &lt;demo-api-get-configuration-key&gt;&lt;/demo-api-get-configuration-key&gt;
-    &lt;demo-api-get-refresh-remote&gt;&lt;/demo-api-get-refresh-remote&gt;
 </code></pre>
-<p>Scoped <code>@get</code> with <code>@publish</code> / <code>@subscribe</code> on the payload (see <a href="./publish.html#publish">@publish</a> and <a href="./subscribe.html#subscribe">@subscribe</a>) — wrap under an ancestor with <code>serviceURL=&quot;/docs-mock-api/geo/&quot;</code>:</p>
-<pre><code>&lt;div serviceURL=&quot;/docs-mock-api/geo/&quot;&gt;
-  &lt;docs-demo-sources for=&quot;demo-api-get-publish-subscribe&quot;&gt;&lt;/docs-demo-sources&gt;
-  &lt;demo-api-get-publish-subscribe&gt;&lt;/demo-api-get-publish-subscribe&gt;
-&lt;/div&gt;
-</code></pre>
-<p>Stale responses are ignored if the path or generation changed before the request finished.</p>
-<h2 id="see-also">See also</h2>
-<ul>
-<li><a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path placeholders</a></li>
-<li><a href="./post.html#post">@post</a> · <a href="./put.html#put">@put</a> · <a href="./patch.html#patch">@patch</a> — send decorators (same path rules)</li>
-</ul>
+<p>See <a href="./post.html#post">@post</a>,
+<a href="./put.html#put">@put</a>, and
+<a href="./patch.html#patch">@patch</a> for write operations.</p>
+<h2 id="advanced">Advanced</h2>
+<p>External invalidation is currently available through <code>triggerKey</code>; it is kept
+out of the main usage examples.</p>
 
     </article>
   </main>

package/docs/crawl/docs/_decorators/patch.html

@@ -4,8 +4,10 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>@patch — Concorde</title>
-  <meta name="description" content="Sends data through API.patchDetailed. Same model as @post: decorated property is ApiResult&lt;T&gt; | null (request, response, result).">
-  <meta name="keywords" content="Concorde, supersoniks, docs/_decorators/patch, patch, @patch, decorator, API.patchDetailed, ApiResult | null, request, response, result, Endpoint, DataProviderKey, ApiResult, @supersoniks/concorde/decorators">
+  <meta name="description" content="@patch applies a partial update with the body from a publisher. It uses the">
+  <meta name="keywords" content="Concorde, supersoniks, docs/_decorators/patch, patch, @patch, decorator, Endpoint, DataProviderKey, ApiResult, send(component), 
+
+, when: &quot;before&quot;, autoPostOnBodyMutation: false, autoPostOnBodyMutation, skipIfBodyMissing">
   <meta name="concorde-doc-id" content="docs/_decorators/patch">
   <link rel="canonical" href="https://concorde.supersoniks.org/crawl/docs/_decorators/patch.html">
 </head>
@@ -15,34 +17,52 @@
   </header>
   <main>
     <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @patch</strong>. Sends data through API.patchDetailed. Same model as @post: decorated property is ApiResult&lt;T&gt; | null (request, response, result). <span>Doc ID: <code>docs/_decorators/patch</code>. Keywords: Concorde, supersoniks, docs/_decorators/patch, patch, @patch, decorator, API.patchDetailed, ApiResult | null, request, response, result, Endpoint, DataProviderKey, ApiResult, @supersoniks/concorde/decorators. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_decorators/patch.html">https://concorde.supersoniks.org/crawl/docs/_decorators/patch.html</a>.</span></p>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @patch</strong>. @patch applies a partial update with the body from a publisher. It uses the <span>Doc ID: <code>docs/_decorators/patch</code>. Keywords: Concorde, supersoniks, docs/_decorators/patch, patch, @patch, decorator, Endpoint, DataProviderKey, ApiResult, send(component), 
+
+, when: &quot;before&quot;, autoPostOnBodyMutation: false, autoPostOnBodyMutation, skipIfBodyMissing. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_decorators/patch.html">https://concorde.supersoniks.org/crawl/docs/_decorators/patch.html</a>.</span></p>
       <h1 id="patch">@patch</h1>
-<p>Sends data through <a href="../../core/utils/api.ts"><code>API.patchDetailed</code></a>. Same model as <a href="./post.html#post">@post</a>: decorated property is <strong><code>ApiResult&lt;T&gt; | null</code></strong> (<code>request</code>, <code>response</code>, <code>result</code>).</p>
-<p>Pass an <a href="../_misc/endpoint.html#endpoint"><code>Endpoint&lt;T&gt;</code></a> and a <code>DataProviderKey</code> for the <strong>request body</strong>. Import <code>patch</code> and <code>ApiResult</code> from <code>@supersoniks/concorde/decorators</code>.</p>
-<h2 id="configuration">Configuration</h2>
-<p>Same as <a href="./post.html#post">@post</a> / <a href="./get.html#get">@get</a>: scoped <code>HTML.getApiConfiguration(host)</code> or <code>DataProviderKey&lt;APIConfiguration&gt;</code> as third argument.</p>
-<h2 id="options-patchoptions">Options (<code>PatchOptions</code>)</h2>
-<p>Same shape as <code>PostOptions</code> on <a href="./post.html#post">@post</a> (<code>ApiSendOptions</code>): <code>refetchEveryMs</code>, <code>skipIfBodyMissing</code>, <code>autoPostOnBodyMutation</code>, <code>triggerKey</code>, <code>skipEmptyPlaceholder</code>. See <a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path placeholders</a> for <code>${sessionId}</code> and empty-string behaviour.</p>
+<p><code>@patch</code> applies a partial update with the body from a publisher. It uses the
+same model as <a href="./post.html#post">@post</a>:
+<code>Endpoint&lt;T&gt;</code>, <code>DataProviderKey&lt;B&gt;</code>, <code>ApiResult&lt;T&gt;</code>, options, and the
+<code>send(component)</code> handle.</p>
+<h2 id="minimal-usage">Minimal usage</h2>
+<pre><code class="language-typescript">const bodyKey = new DataProviderKey&lt;Partial&lt;User&gt;&gt;(&quot;users.patch&quot;);
+const patchUser = patch(new Endpoint&lt;User&gt;(&quot;users/42&quot;), bodyKey);
+
+@patchUser
+@state()
+payload?: ApiResult&lt;User&gt;;
+</code></pre>
+<p>To run the operation again from the component:</p>
+<pre><code class="language-typescript">async savePatch() {
+  await patchUser.send(this);
+}
+</code></pre>
+<p><code>send(component)</code> returns a Promise resolved after the PATCH completes. See
+<a href="./post.html#post">@post</a> for the method-decorator form and the
+<code>when: &quot;before&quot;</code> option.</p>
+<p>The PATCH is also sent automatically when the body mutates, unless
+<code>autoPostOnBodyMutation: false</code> is set. The available options are described in
+<a href="./post.html#post">@post</a>:</p>
+<ul>
+<li><code>autoPostOnBodyMutation</code></li>
+<li><code>skipIfBodyMissing</code></li>
+<li><code>refetchEveryMs</code></li>
+<li><code>skipEmptyPlaceholder</code></li>
+<li><code>triggerKey</code></li>
+</ul>
+<p>Pass explicit API configuration as the third argument:</p>
+<pre><code class="language-typescript">@patch(endpoint, bodyKey, apiConfigurationKey)
+</code></pre>
 <h2 id="import">Import</h2>
 <pre><code class="language-typescript">import { patch, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
-import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
 import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
-</code></pre>
-<h2 id="example">Example</h2>
-<pre><code class="language-typescript">const patchBodyKey = new DataProviderKey&amp;lt;Partial&amp;lt;Resource&amp;gt;&amp;gt;(&quot;resourcePatch&quot;);
-
-@patch(
-  new Endpoint&amp;lt;Resource, { resourceId: string }&amp;gt;(&quot;resources/${resourceId}&quot;),
-  patchBodyKey,
-  { skipEmptyPlaceholder: true },
-)
-@state()
-payload?: ApiResult&amp;lt;Resource&amp;gt; | null;
+import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
 </code></pre>
 <h2 id="see-also">See also</h2>
 <ul>
-<li><a href="./post.html#post">@post</a> — POST (live demos)</li>
-<li><a href="./put.html#put">@put</a> — full replacement (PUT)</li>
+<li><a href="./post.html#post">@post</a> — options and triggers</li>
+<li><a href="./put.html#put">@put</a> — full replacement</li>
 <li><a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path placeholders</a></li>
 </ul>
 

package/docs/crawl/docs/_decorators/post.html

@@ -4,8 +4,14 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>@post — Concorde</title>
-  <meta name="description" content="Sends data through API.postDetailed. The decorated property is ApiResult&lt;T&gt; | null: request, response, and typed result.">
-  <meta name="keywords" content="Concorde, supersoniks, docs/_decorators/post, post, @post, decorator, API.postDetailed, ApiResult | null, request, response, result, Endpoint, DataProviderKey, ApiResult, @supersoniks/concorde/decorators">
+  <meta name="description" content="@post sends the contents of a publisher and stores the response in an">
+  <meta name="keywords" content="Concorde, supersoniks, docs/_decorators/post, post, @post, decorator, ApiResult, undefined, Endpoint, DataProviderKey, 
+
+The current body is read from , send(component), 
+
+,  returns a , 
+
+Use ">
   <meta name="concorde-doc-id" content="docs/_decorators/post">
   <link rel="canonical" href="https://concorde.supersoniks.org/crawl/docs/_decorators/post.html">
 </head>
@@ -15,86 +21,109 @@
   </header>
   <main>
     <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @post</strong>. Sends data through API.postDetailed. The decorated property is ApiResult&lt;T&gt; | null: request, response, and typed result. <span>Doc ID: <code>docs/_decorators/post</code>. Keywords: Concorde, supersoniks, docs/_decorators/post, post, @post, decorator, API.postDetailed, ApiResult | null, request, response, result, Endpoint, DataProviderKey, ApiResult, @supersoniks/concorde/decorators. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_decorators/post.html">https://concorde.supersoniks.org/crawl/docs/_decorators/post.html</a>.</span></p>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @post</strong>. @post sends the contents of a publisher and stores the response in an <span>Doc ID: <code>docs/_decorators/post</code>. Keywords: Concorde, supersoniks, docs/_decorators/post, post, @post, decorator, ApiResult, undefined, Endpoint, DataProviderKey, 
+
+The current body is read from , send(component), 
+
+,  returns a , 
+
+Use . URL: <a href="https://concorde.supersoniks.org/crawl/docs/_decorators/post.html">https://concorde.supersoniks.org/crawl/docs/_decorators/post.html</a>.</span></p>
       <h1 id="post">@post</h1>
-<p>Sends data through <a href="../../core/utils/api.ts"><code>API.postDetailed</code></a>. The decorated property is <strong><code>ApiResult&lt;T&gt; | null</code></strong>: <code>request</code>, <code>response</code>, and typed <code>result</code>.</p>
-<p>Pass an <a href="../_misc/endpoint.html#endpoint"><code>Endpoint&lt;T&gt;</code></a> as the first argument and a <code>DataProviderKey</code> for the <strong>request body</strong> as the second. Import <code>post</code> and <code>ApiResult</code> from <code>@supersoniks/concorde/decorators</code>, and <code>Endpoint</code> from <code>@supersoniks/concorde/utils/endpoint</code>.</p>
-<h2 id="configuration">Configuration</h2>
-<p>Same as <a href="./get.html#get">@get</a>: scoped <code>HTML.getApiConfiguration(host)</code> by default, or <code>DataProviderKey&lt;APIConfiguration&gt;</code> as third argument. See <a href="../_misc/api-configuration.html#api-configuration">API configuration</a> for mock demos.</p>
-<h2 id="optional-postoptions-third-or-fourth-argument">Optional <code>PostOptions</code> (third or fourth argument)</h2>
-<table>
-<thead>
-<tr>
-<th>Option</th>
-<th>Description</th>
-</tr>
-</thead>
-<tbody><tr>
-<td><code>refetchEveryMs</code></td>
-<td>Re-post on an interval (ms).</td>
-</tr>
-<tr>
-<td><code>skipIfBodyMissing</code></td>
-<td>Skip when body publisher is <code>null</code>/<code>undefined</code> (default: <code>true</code>).</td>
-</tr>
-<tr>
-<td><code>autoPostOnBodyMutation</code></td>
-<td>Re-post when the body publisher mutates (default: <code>true</code>). <code>false</code> = manual via <code>triggerKey.invalidate()</code>.</td>
-</tr>
-<tr>
-<td><code>skipEmptyPlaceholder</code></td>
-<td>If <code>true</code>, a placeholder resolved to <code>&#39;&#39;</code> blocks the request (empty string only — not <code>0</code> or <code>false</code>). See <a href="../_misc/dynamic-path.html#dynamic-path">Dynamic paths</a>.</td>
-</tr>
-<tr>
-<td><code>triggerKey</code></td>
-<td><code>DataProviderKey</code> — <code>invalidate()</code> re-runs the POST with the current body.</td>
-</tr>
-</tbody></table>
-<h2 id="when-the-post-runs-again">When the POST runs again</h2>
+<p><code>@post</code> sends the contents of a publisher and stores the response in an
+optional <code>ApiResult&lt;T&gt;</code> property. The property is <code>undefined</code> until a result
+is available.</p>
+<h2 id="minimal-usage">Minimal usage</h2>
+<p>Pass an <code>Endpoint&lt;T&gt;</code> and a <code>DataProviderKey&lt;B&gt;</code> for the request body.</p>
+<pre><code class="language-typescript">const userBodyKey = new DataProviderKey&lt;CreateUser&gt;(&quot;users.form&quot;);
+const createUser = post(new Endpoint&lt;User&gt;(&quot;users&quot;), userBodyKey);
+
+@createUser
+@state()
+payload?: ApiResult&lt;User&gt;;
+</code></pre>
+<p>The current body is read from <code>userBodyKey</code>. 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.</p>
+<p>API configuration is read from the HTML scope, as with
+<a href="./get.html#get">@get</a>.</p>
+<h2 id="sending-the-post-again">Sending the POST again</h2>
+<h3 id="from-the-component">From the component</h3>
+<p>Keep the decorator to access <code>send(component)</code>. The body is read again when the
+operation runs.</p>
+<pre><code class="language-typescript">async saveAgain() {
+  const payload = await createUser.send(this);
+  console.log(payload?.result);
+}
+</code></pre>
+<p><code>send()</code> returns a <code>Promise&lt;ApiResult&lt;T&gt; | undefined&gt;</code> that resolves after the
+operation completes. It is useful for “Save” or “Retry” buttons and can repeat
+an operation with side effects.</p>
+<h3 id="from-a-method-decorator">From a method decorator</h3>
+<p>The send action can decorate a local method. It runs after the method by
+default, waits for an eventual Promise to resolve, and the decorated method
+call waits for the send to complete:</p>
+<pre><code class="language-typescript">import { send } from &quot;@supersoniks/concorde/decorators&quot;;
+
+@send(createUser)
+async save() {
+  // Prepare local state or validate the form.
+}
+</code></pre>
+<p>Use <code>{ when: &quot;before&quot; }</code> when the send must complete before the method runs:</p>
+<pre><code class="language-typescript">@send(createUser, { when: &quot;before&quot; })
+saveBefore() {
+  // The POST has completed before this method runs.
+}
+</code></pre>
+<p>The method decorator adds an explicit send. If the method also mutates the body
+publisher, set <code>autoPostOnBodyMutation: false</code> when the decorated method must
+be the only trigger.</p>
+<h2 id="options-postoptions">Options (<code>PostOptions</code>)</h2>
+<p>Options are the third argument, or the fourth argument when a configuration key
+is provided.</p>
 <ul>
-<li>Body publisher <code>onInternalMutation</code> when <code>autoPostOnBodyMutation</code> is <code>true</code> (default). Plusieurs mutations synchrones dans la même frame sont regroupées en <strong>un seul POST</strong> via <code>requestAnimationFrame</code>.</li>
-<li>Endpoint path dependency changes (<code>${sessionId}</code> on the host).</li>
-<li>Configuration publisher mutation.</li>
-<li><code>triggerKey</code> publisher <code>invalidate()</code>.</li>
-<li><code>refetchEveryMs</code> timer (if set).</li>
+<li><code>autoPostOnBodyMutation</code>: send after a body mutation (default: <code>true</code>). Set
+it to <code>false</code> to use <code>send()</code>.</li>
+<li><code>skipIfBodyMissing</code>: skip when the body is <code>null</code> or <code>undefined</code> (default:
+<code>true</code>).</li>
+<li><code>refetchEveryMs</code>: repeat the POST at this interval. Use it only when
+repeating the operation is intended.</li>
+<li><code>skipEmptyPlaceholder</code>: block the request when a <code>${...}</code> placeholder is
+<code>&quot;&quot;</code>.</li>
+<li><code>triggerKey</code>: a publisher whose <code>invalidate()</code> sends the POST again.</li>
+</ul>
+<p>With a configuration key:</p>
+<pre><code class="language-typescript">@post(endpoint, userBodyKey, apiConfigurationKey)
+</code></pre>
+<p>See <a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path placeholders</a> for
+dynamic path details.</p>
+<h2 id="when-the-post-is-sent">When the POST is sent</h2>
+<ul>
+<li>when the component connects and the body and configuration are available;</li>
+<li>after a body mutation, unless <code>autoPostOnBodyMutation: false</code>;</li>
+<li>when a property used in <code>${...}</code> changes;</li>
+<li>when a configuration publisher changes;</li>
+<li>when the <code>triggerKey</code> publisher is invalidated;</li>
+<li>when <code>send()</code> is called;</li>
+<li>after each response when <code>refetchEveryMs</code> is set.</li>
 </ul>
 <h2 id="import">Import</h2>
-<pre><code class="language-typescript">import { post, publish, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
-import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
+<pre><code class="language-typescript">import { post, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
 import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
 </code></pre>
-<h2 id="minimal-example">Minimal example</h2>
-<p>Mock service: <code>POST /docs-mock-api/api/register</code> (same route as <a href="../../core/components/functional/submit/submit.html#submit"><code>sonic-submit</code></a> demos). Publisher setup lives in <code>decorators-demo-post.ts</code>.</p>
-<pre><code class="language-typescript">const syncRequest = new DataProviderKey&amp;lt;SyncRequest&amp;gt;(&quot;syncRequest&quot;);
-const syncTrigger = new DataProviderKey&amp;lt;number&amp;gt;(&quot;syncTrigger&quot;);
-
-@post(
-  new Endpoint&amp;lt;SyncResponse, { sessionId: string }&amp;gt;(&quot;sessions/${sessionId}/sync&quot;),
-  syncRequest,
-  { triggerKey: syncTrigger },
-)
-@state()
-payload?: ApiResult&amp;lt;SyncResponse&amp;gt; | null;
-</code></pre>
-<h2 id="live-demos">Live demos</h2>
+<h2 id="demos">Demos</h2>
 <pre><code>&lt;docs-demo-sources for=&quot;demo-api-post&quot;&gt;&lt;/docs-demo-sources&gt;
     &lt;demo-api-post&gt;&lt;/demo-api-post&gt;
-</code></pre>
-<p>Dynamic endpoint path — changing <code>sessionId</code> on the host re-runs the POST (<code>POST /docs-mock-api/api/sessions/{id}/sync</code>):</p>
-<pre><code>&lt;docs-demo-sources for=&quot;demo-api-post-dynamic&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;docs-demo-sources for=&quot;demo-api-post-dynamic&quot;&gt;&lt;/docs-demo-sources&gt;
     &lt;demo-api-post-dynamic&gt;&lt;/demo-api-post-dynamic&gt;
 </code></pre>
-<p><code>@post</code> + <code>@publish</code> on the same property (see <a href="./publish.html#publish">@publish</a>):</p>
-<pre><code>&lt;docs-demo-sources for=&quot;demo-api-post-publish&quot;&gt;&lt;/docs-demo-sources&gt;
-    &lt;demo-api-post-publish&gt;&lt;/demo-api-post-publish&gt;
-</code></pre>
-<p>Stale responses are ignored if the path or generation changed before the request finished.</p>
-<p><strong>Note:</strong> plusieurs composants <code>@post</code> sur la même page qui partagent le même <code>bodyKey</code> enverront chacun une requête à chaque mutation du body — utiliser une clé par composant (voir les deux démos live ci-dessus).</p>
-<p>Path placeholders (<code>${sessionId}</code>, …): <a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path placeholders</a>.</p>
-<h2 id="see-also">See also</h2>
-<ul>
-<li><a href="./put.html#put">@put</a> · <a href="./patch.html#patch">@patch</a> — same decorator model, <code>PUT</code> / <code>PATCH</code> via <code>putDetailed</code> / <code>patchDetailed</code></li>
-</ul>
+<p>See <a href="./put.html#put">@put</a> and
+<a href="./patch.html#patch">@patch</a>: they use the same model with a
+different HTTP method.</p>
+<h2 id="advanced">Advanced</h2>
+<p>External invalidation is currently available through <code>triggerKey</code>; it is kept
+out of the main usage examples.</p>
 
     </article>
   </main>