@supersoniks/concorde 4.9.7 → 4.9.91

package/docs/crawl/hubs/remote-data.html

@@ -153,138 +153,210 @@ dp(c</pre>
 <section id="docs-_decorators-get" data-doc-id="docs/_decorators/get">
   <h2><a href="../docs/_decorators/get.html">@get</a></h2>
   <p><strong>Doc ID:</strong> <code>docs/_decorators/get</code> · <a href="../docs/_decorators/get.html">full page</a></p>
-  <p>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.</p>
+  <p>@get loads data and stores the result in an ApiResult&lt;T&gt; | null property.</p>
   <pre class="doc-excerpt">@get
 
-Loads data through API.getDetailed. The decorated property is ApiResult  | null: request, response (or null for dataProvider(...) resolution without HTTP), and typed result.
+@get loads data and stores the result in an ApiResult  | null property.
 
-Pass an Endpoint  as the first argument. Import get and ApiResult from @supersoniks/concorde/decorators, and Endpoint from @supersoniks/concorde/utils/endpoint.
+- payload.result: typed data;
+- payload.response: the HTTP response;
+- payload.request: the request that was sent.
 
-Configuration
+Minimal usage
 
-- Default: HTML.getApiConfiguration(host) (ancestor serviceURL, etc.).
-- Second argument: DataProviderKey  — config is read from the publisher at the resolved path; internal mutations trigger another GET. See API configuration for mock demos.
+const usersEndpoint = new Endpoint (&quot;users&quot;);
 
-Dynamic path
+@get(usersEndpoint)
+@state()
+payload: ApiResult  | null = null;
+
+The first argument is always an
+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.
 
-${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 &quot;&quot; (empty string only). Details: Dynamic path placeholders.
+const usersGet = get(new Endpoint (&quot;users&quot;));
+
+@usersGet
+@state()
+payload: ApiResult  | null = null;
+
+refresh() {
+  usersGet.refetch(this);
+}
 
 Options (GetOptions)
 
-Pass as the second argument (scoped config) or third (with a configuration key). Same shape as send decorators where applicable:
+Options are the second argument, or the third argument when an API
+configuration key is provided.
 
-| Option | Description |
-|--------|-------------|
-| skipEmptyPlaceholder | Treat &quot;&quot; as not ready (see Dynamic path). |
-| refetchEveryMs | Automatic polling interval (ms). 0 or omitted = no polling. |
-| tri</pre>
+- skipEmptyPlaceholder: blocks the GET when ${prop} is &quot;&quot;.
+- refetchEveryMs: automatically runs the GET again after this interval
+  (milliseconds). Omit the option, or use 0, to disable polling.
+
+With a configurat</pre>
 </section>
 <section id="docs-_decorators-patch" data-doc-id="docs/_decorators/patch">
   <h2><a href="../docs/_decorators/patch.html">@patch</a></h2>
   <p><strong>Doc ID:</strong> <code>docs/_decorators/patch</code> · <a href="../docs/_decorators/patch.html">full page</a></p>
-  <p>Sends data through API.patchDetailed. Same model as @post: decorated property is ApiResult&lt;T&gt; | null (request, response, result).</p>
+  <p>@patch applies a partial update with the body from a publisher. It uses the</p>
   <pre class="doc-excerpt">@patch
 
-Sends data through API.patchDetailed. Same model as @post: decorated property is ApiResult  | null (request, response, result).
+@patch applies a partial update with the body from a publisher. It uses the
+same model as @post:
+Endpoint , DataProviderKey , ApiResult , options, and the
+send(component) handle.
 
-Pass an Endpoint  and a DataProviderKey for the request body. Import patch and ApiResult from @supersoniks/concorde/decorators.
+Minimal usage
 
-Configuration
+const bodyKey = new DataProviderKey &gt;(&quot;users.patch&quot;);
+const patchUser = patch(new Endpoint (&quot;users/42&quot;), bodyKey);
 
-Same as @post / @get: scoped HTML.getApiConfiguration(host) or DataProviderKey  as third argument.
+@patchUser
+@state()
+payload: ApiResult  | null = null;
 
-Options (PatchOptions)
+To run the operation again from the component:
 
-Same shape as PostOptions on @post (ApiSendOptions): refetchEveryMs, skipIfBodyMissing, autoPostOnBodyMutation, triggerKey, skipEmptyPlaceholder. See Dynamic path placeholders for ${sessionId} and empty-string behaviour.
+savePatch() {
+  patchUser.send(this);
+}
 
-Import
+The PATCH is also sent automatically when the body mutates, unless
+autoPostOnBodyMutation: false is set. The available options are described in
+@post:
 
-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;;
+- autoPostOnBodyMutation
+- skipIfBodyMissing
+- refetchEveryMs
+- skipEmptyPlaceholder
 
-Example
+Pass explicit API configuration as the third argument:
 
-const patchBodyKey = new DataProviderKey&amp;lt;Partial&amp;lt;Resource&amp;gt;&amp;gt;(&quot;resourcePatch&quot;);
+@patch(endpoint, bodyKey, apiConfigurationKey)
 
-@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
+
+import { patch, 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;;
 
 See also
 
-- @post — POST (live demos)
-- @put — full rep</pre>
+- @post — options and triggers
+- @put — full replacement
+- Dynamic path placeholders</pre>
 </section>
 <section id="docs-_decorators-post" data-doc-id="docs/_decorators/post">
   <h2><a href="../docs/_decorators/post.html">@post</a></h2>
   <p><strong>Doc ID:</strong> <code>docs/_decorators/post</code> · <a href="../docs/_decorators/post.html">full page</a></p>
-  <p>Sends data through API.postDetailed. The decorated property is ApiResult&lt;T&gt; | null: request, response, and typed result.</p>
+  <p>@post sends the contents of a publisher and stores the response in an</p>
   <pre class="doc-excerpt">@post
 
-Sends data through API.postDetailed. The decorated property is ApiResult  | null: request, response, and typed result.
+@post sends the contents of a publisher and stores the response in an
+ApiResult  | null property.
+
+Minimal usage
+
+Pass an Endpoint  and a DataProviderKey  for the request body.
+
+const userBodyKey = new DataProviderKey (&quot;users.form&quot;);
+const createUser = post(new Endpoint (&quot;users&quot;), userBodyKey);
+
+@createUser
+@state()
+payload: ApiResult  | null = null;
+
+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.
+
+API configuration is read from the HTML scope, as with
+@get.
 
-Pass an Endpoint  as the first argument and a DataProviderKey for the request body as the second. Import post and ApiResult from @supersoniks/concorde/decorators, and Endpoint from @supersoniks/concorde/utils/endpoint.
+Sending the POST again
 
-Configuration
+From the component
 
-Same as @get: scoped HTML.getApiConfiguration(host) by default, or DataProviderKey  as third argument. See API configuration for mock demos.
+Keep the decorator to access send(component). The body is read again when the
+operation runs.
 
-Optional PostOptions (third or fourth argument)
+saveAgain() {
+  createUser.send(this);
+}
 
-| Option | Description |
-|--------|-------------|
-| refetchEveryMs | Re-post on an interval (ms). |
-| skipIfBodyMissing | Skip when body publisher is null/undefined (default: true). |
-| autoPostOnBodyMutation | Re-post when the body publisher mutates (default: true). false = manual via triggerKey.invalidate(). |
-| skipEmptyPlaceholder | If true, a placeholder resolved to '' blocks the request (empty string only — not 0 or false). See Dynamic paths. |
-| triggerKey | DataProviderKey — invalidate() re-runs the POST with the current body. |
+send() is useful for “Save” or “Retry” buttons. It can repeat an operation
+with side effects.
 
-When the POST runs again
+Options (PostOptions)
 
-- Body publisher onInternalMutation when autoPostOnBodyMutation is true (defa</pre>
+Options are the third argument, or the fourth argument when a configuration key
+is provided.
+
+- autoPostOnBodyMutation: send after a body mutation (default: true). Set
+  it to false to use send().
+- skipIfBodyMissing: skip when the body is null or undefined (default:
+  true).
+- refetchE</pre>
 </section>
 <section id="docs-_decorators-put" data-doc-id="docs/_decorators/put">
   <h2><a href="../docs/_decorators/put.html">@put</a></h2>
   <p><strong>Doc ID:</strong> <code>docs/_decorators/put</code> · <a href="../docs/_decorators/put.html">full page</a></p>
-  <p>Sends data through API.putDetailed. Same model as @post: decorated property is ApiResult&lt;T&gt; | null (request, response, result).</p>
+  <p>@put replaces a resource with the body from a publisher. It uses exactly the</p>
   <pre class="doc-excerpt">@put
 
-Sends data through API.putDetailed. Same model as @post: decorated property is ApiResult  | null (request, response, result).
+@put replaces a resource with the body from a publisher. It uses exactly the
+same model as @post:
+Endpoint , DataProviderKey , ApiResult , options, and the
+send(component) handle.
 
-Pass an Endpoint  and a DataProviderKey for the request body. Import put and ApiResult from @supersoniks/concorde/decorators.
+Minimal usage
 
-Configuration
+const bodyKey = new DataProviderKey (&quot;users.form&quot;);
+const updateUser = put(new Endpoint (&quot;users/42&quot;), bodyKey);
 
-Same as @post / @get: scoped HTML.getApiConfiguration(host) or DataProviderKey  as third argument.
+@updateUser
+@state()
+payload: ApiResult  | null = null;
 
-Options (PutOptions)
+To run the operation again from the component:
 
-Same shape as PostOptions on @post (ApiSendOptions): refetchEveryMs, skipIfBodyMissing, autoPostOnBodyMutation, triggerKey, skipEmptyPlaceholder. See Dynamic path placeholders for ${sessionId} and empty-string behaviour.
+update() {
+  updateUser.send(this);
+}
 
-Import
+The PUT is also sent automatically when the body mutates, unless
+autoPostOnBodyMutation: false is set. See
+@post for the option details:
 
-import { put, 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;;
+- autoPostOnBodyMutation
+- skipIfBodyMissing
+- refetchEveryMs
+- skipEmptyPlaceholder
 
-Example
+Pass explicit API configuration as the third argument:
 
-const bodyKey = new DataProviderKey&amp;lt;UpdatePayload&amp;gt;(&quot;resourceBody&quot;);
+@put(endpoint, bodyKey, apiConfigurationKey)
 
-@put(new Endpoint&amp;lt;Resource, { resourceId: string }&amp;gt;(&quot;resources/${resourceId}&quot;), bodyKey)
-@state()
-payload?: ApiResult&amp;lt;Resource&amp;gt; | null;
+Import
 
-Changing resourceId on the host re-runs the PUT when the path becomes ready — see Dynamic path placeholders.
+import { put, 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;;
 
 See also
 
-- @post —</pre>
+- @post — options and triggers
+- @patch — partial update
+- Dynamic path placeholders</pre>
 </section>
 <section id="docs-_misc-api-configuration" data-doc-id="docs/_misc/api-configuration">
   <h2><a href="../docs/_misc/api-configuration.html">API configuration</a></h2>

package/docs/index.html

@@ -10,8 +10,8 @@
     <!-- <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
      -->
     <script src="https://cdn.jsdelivr.net/npm/marked@13.0.3"></script>
-    <script type="module" crossorigin src="./assets/index-hElUgV9_.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-Bnp7gVaA.css">
+    <script type="module" crossorigin src="./assets/index-DVn8AeyA.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-BL6WVF7g.css">
   </head>
   <body class="px-6 lg:px-20">
     <sonic-theme