@symbo.ls/fetch 3.14.285 → 3.14.403

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @symbo.ls/fetch
 
+## 3.14.403
+
+### Patch Changes
+
+- Auto-generated cross-repo patch release.
+
+## 3.14.402
+
+### Patch Changes
+
+- Auto-generated cross-repo patch release.
+
 ## 3.14.285
 
 ### Patch Changes

package/README.md

@@ -4,17 +4,17 @@ Declarative data fetching for DOMQL with pluggable adapters. Supports caching, s
 
 ## Setup
 
-Add `db` to `config.js`:
+Add `fetch` to `config.js` — this is the connection/adapter config (distinct from the per-element `fetch` query declaration; the runtime resolves it onto `context.fetch`):
 
 ```js
 // Supabase
-db: { adapter: 'supabase', projectId: '...', key: '...' }
+fetch: { adapter: 'supabase', projectId: '...', key: '...' }
 
 // Supabase — config from state
-db: { adapter: 'supabase', state: 'supabase' }  // merges root state.supabase
+fetch: { adapter: 'supabase', state: 'supabase' }  // merges root state.supabase
 
 // REST
-db: {
+fetch: {
   adapter: 'rest',
   url: 'https://api.example.com',
   headers: { Authorization: 'Bearer token' },
@@ -28,9 +28,14 @@ db: {
 }
 
 // Local
-db: { adapter: 'local', data: { articles: [] }, persist: true }
+fetch: { adapter: 'local', data: { articles: [] }, persist: true }
+
+// Custom/registered adapter (see Registering a named adapter)
+fetch: { adapter: 'sdk', sdk: getSDK() }
 ```
 
+> `db` is **not** a config key — it's the local name for the resolved adapter you get from `await this.getDB()` (`db.select(...)`, `db.insert(...)`, …).
+
 ## Declarative `fetch`
 
 ```js
@@ -99,6 +104,20 @@ Like TanStack's `select`, pick or reshape data before it hits state. Runs after
 }
 ```
 
+For an RPC bound to `on: 'submit'`, collected form data is used as the RPC params. Use `transformParams` to reshape the form data before it's sent:
+
+```js
+{
+  tag: 'form',
+  fetch: {
+    method: 'rpc',
+    from: 'submit_application',
+    on: 'submit',
+    transformParams: (formData, el, state) => ({ p_payload: formData })
+  }
+}
+```
+
 ### Array fetch (parallel)
 
 ```js
@@ -130,6 +149,12 @@ Like TanStack's `select`, pick or reshape data before it hits state. Runs after
 { fetch: { from: 'profile', enabled: (el, state) => !!state.userId } }
 ```
 
+`skip` is the inverse alias — `skip: true` (or a function returning `true`) suppresses the fetch:
+
+```js
+{ fetch: { from: 'profile', skip: (el, state) => !state.userId } }
+```
+
 ## Cache
 
 Default: all queries cache with `staleTime: 1m`, `gcTime: 5m`.
@@ -308,6 +333,9 @@ Prevent UI flicker during page changes — keep showing current data while the n
     page: { cursor: 'abc123', limit: 20 }
   }
 }
+
+// Top-level `cursor` is also accepted — passed through to params.cursor
+{ fetch: { from: 'articles', cursor: 'abc123' } }
 ```
 
 ## Infinite queries
@@ -504,6 +532,21 @@ queryClient.removeQueries('articles')
 queryClient.removeQueries()  // clear all
 ```
 
+### Raw cache access
+
+```js
+queryClient.getCache()  // the underlying Map of cache entries
+queryClient.clear()     // remove every entry
+```
+
+### Language eviction
+
+`dropNonLang(keepLang)` removes every cache entry whose language suffix isn't `keepLang`, leaving entries with no language suffix untouched. Used when the active language changes to flush stale-locale responses while keeping the fallback locale (typically `'en'`) warm:
+
+```js
+queryClient.dropNonLang('en')  // keep English + lang-less entries, drop the rest
+```
+
 ### Prefetch
 
 Prefetch data before it's needed (e.g. on hover):
@@ -636,9 +679,13 @@ db.update({ from, data, params, method, headers, baseUrl })  // method: 'PUT' |
 db.delete({ from, params, headers, baseUrl })
 db.rpc({ from, params, headers, baseUrl })
 
+// Supabase select/insert/update/upsert also accept `schema` to target a
+// non-public Postgres schema: db.select({ from: 'users', schema: 'auth' })
+
 // Auth
 db.getSession()
-db.signIn({ email, password })
+db.getUser()                        // Supabase
+db.signIn({ email, password })      // also: { provider } (OAuth) | { token } (id token)
 db.signOut()
 db.setToken(jwt)                    // REST
 db.signUp({ email, password })      // Supabase
@@ -682,6 +729,32 @@ const db = createAdapter({
 })
 ```
 
+### Registering a named adapter
+
+For adapters with optional/peer deps (so they aren't bundled until used), register a lazy loader by name. A registered loader can then be selected with `db: { adapter: 'name', ... }`:
+
+```js
+import { registerAdapter } from '@symbo.ls/fetch'
+
+// loader resolves to a module exporting `setup(options) => adapter`
+registerAdapter('sdk', () => import('./adapters/sdk.js'))
+
+// elsewhere
+db: { adapter: 'sdk', /* ...options passed to setup() */ }
+```
+
+The registry lives on `globalThis` (`Symbol.for`-keyed) so a registration from any bundle copy is visible to every resolver — and resolution tolerates a boot-time race: an element created before its custom adapter registers waits briefly (up to 5s) for the registration rather than throwing. Custom registrations shadow the built-ins (`supabase`, `rest`, `local`), so `registerAdapter('supabase', …)` overrides the bundled one.
+
+### Direct adapter imports
+
+The built-in adapters are also exposed as subpath exports — import a `setup` directly to build an adapter without going through `db.adapter`:
+
+```js
+import { setup as supabase } from '@symbo.ls/fetch/supabase'
+import { setup as rest } from '@symbo.ls/fetch/rest'
+import { setup as local } from '@symbo.ls/fetch/local'
+```
+
 ## Language / i18n
 
 Fetch automatically injects the current language into every request — both as a `lang` query parameter and as an `Accept-Language` header.
@@ -756,10 +829,12 @@ When used as a plugin, fetch hooks into the `create` lifecycle to auto-execute f
 | `as` | string | — | Target state key |
 | `on` | string | `'create'` | Trigger: `create`, `click`, `submit`, `stateChange` |
 | `enabled` | boolean/function | `true` | Enable/disable query |
+| `skip` | boolean/function | `false` | Inverse of `enabled` — suppress the query |
 | `placeholderData` | any/function | — | Temporary data while loading |
 | `initialData` | any/function | — | Pre-populate cache |
 | `keepPreviousData` | boolean | `false` | Keep current data during refetch |
 | `page` | number/object | — | Pagination: page number or `{ offset, limit, cursor }` |
+| `cursor` | string | — | Cursor passed through to `params.cursor` |
 | `pageSize` | number | `limit` or `20` | Items per page |
 | `infinite` | boolean | `false` | Enable infinite query mode |
 | `getNextPageParam` | function | — | `(lastPage, allPages) => cursor \| null` |
@@ -776,6 +851,9 @@ When used as a plugin, fetch hooks into the `create` lifecycle to auto-execute f
 | `onSettled` | function | — | After mutation completes (success or error) |
 | `auth` | boolean | `false` | Require authentication |
 | `fields` | boolean/array | — | Collect form fields for mutations |
+| `transformParams` | function | — | Reshape collected form data for `on: 'submit'` RPC |
+| `subscribeOn` | string | `'*'` | Realtime event filter for `method: 'subscribe'` (`INSERT`, `UPDATE`, `DELETE`) |
+| `schema` | string | `'public'` | Postgres schema (Supabase) |
 | `single` | boolean | `false` | Return single row |
 | `limit` | number | — | Row limit |
 | `offset` | number | — | Row offset |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbo.ls/fetch",
-  "version": "3.14.285",
+  "version": "3.14.403",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "module": "./dist/esm/index.js",