spark-html-query 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# ⚡ spark-html-query
+
+Declarative async data for [spark-html](https://www.npmjs.com/package/spark-html)
+— a **self-fetching reactive store**. One dependency (`spark-html`), built
+entirely on its `store()`.
+
+A `query` runs an async function and exposes the result as reactive store state.
+Any component reads it with the same `useStore` it already knows, and re-renders
+as the request settles — no `onMount`, no manual `loading` flags, no `fetch`
+boilerplate.
+
+```js
+import { query } from 'spark-html-query';
+
+query('user', () => fetch('/api/user').then((r) => r.json()));
+```
+
+```html
+<!-- any component -->
+<script>const user = useStore('user');</script>
+
+<p :hidden="!user.loading">Loading…</p>
+<p :hidden="!user.error">Failed: {user.error.message}</p>
+<h1 :hidden="user.loading">{user.data?.name}</h1>
+<button onclick="{user.refetch}">Reload</button>
+```
+
+## Install
+
+```bash
+npm install spark-html-query
+```
+
+## State
+
+`useStore(name)` returns a reactive object:
+
+| Key | Meaning |
+|-----|---------|
+| `data` | The latest resolved value (or `initialData` / `null` before the first). |
+| `error` | The last rejection, or `null`. |
+| `loading` | `true` until the first successful result (no `data` yet). |
+| `fetching` | `true` during **any** in-flight fetch, including a refetch over existing data. |
+| `refetch()` | Re-run the fetcher. A newer call supersedes an older in-flight one. |
+| `mutate(next)` | Set `data` directly without fetching (optimistic update). Value or `(prev) => next`. |
+| `stop()` | Stop the `refetchInterval` poller, if any. |
+
+## Options
+
+```js
+query('feed', fetchFeed, {
+  initialData: [],          // seed data; skips the initial `loading` state
+  refetchInterval: 30000,   // poll every 30s
+  lazy: true,               // with initialData: wait for the first refetch()
+});
+```
+
+## Pairs with `derived`
+
+Shape a query into exactly what a component needs, memoized — the view updates
+as the request settles:
+
+```js
+import { query } from 'spark-html-query';
+import { derived } from 'spark-html';
+
+query('todos', fetchTodos);
+derived('todoStats', ['todos'], (q) => ({
+  total: q.data?.length ?? 0,
+  done: q.data?.filter((t) => t.done).length ?? 0,
+  loading: q.loading,
+}));
+```
+
+> `loading` vs `fetching`: show a **skeleton** on `loading` (first load, no data
+> yet) and a subtle **spinner** on `fetching` (background refresh that keeps the
+> stale data visible). That's the stale-while-revalidate pattern, declaratively.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "spark-html-query",
+  "version": "0.1.0",
+  "description": "Declarative async data for spark-html — a self-fetching reactive store with loading/error/refetch. One dependency.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "homepage": "https://wilkinnovo.github.io/spark",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node test/query.js"
+  },
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "spark-html": ">=0.21.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wilkinnovo/spark.git",
+    "directory": "packages/spark-html-query"
+  },
+  "keywords": [
+    "spark-html",
+    "query",
+    "fetch",
+    "async",
+    "data",
+    "store",
+    "swr"
+  ],
+  "license": "MIT"
+}

package/src/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * spark-html-query — declarative async data for spark-html.
+ *
+ * `query(name, fetcher, options?)` creates a self-fetching store. Read it with
+ * `useStore(name)` from any component; it re-renders as the request settles.
+ */
+
+export interface QueryState<T> {
+  /** The latest resolved value, or `initialData` / `null` before the first one. */
+  data: T | null;
+  /** The last rejection, or `null`. */
+  error: unknown;
+  /** True until the first successful result (no `data` yet). */
+  loading: boolean;
+  /** True during ANY in-flight fetch, including a refetch over existing data. */
+  fetching: boolean;
+  /** Re-run the fetcher. A newer call supersedes an older in-flight one. */
+  refetch: () => Promise<void>;
+  /** Set `data` directly without fetching (optimistic update). Accepts a value or updater. */
+  mutate: (next: T | ((prev: T | null) => T)) => void;
+  /** Stop the `refetchInterval` poller, if any. */
+  stop: () => void;
+}
+
+export interface QueryOptions<T> {
+  /** Seed `data` before the first fetch (skips the initial `loading` state). */
+  initialData?: T | null;
+  /** Poll the fetcher on this interval (ms). */
+  refetchInterval?: number;
+  /** With `initialData`, don't fetch on creation — wait for the first `refetch()`. */
+  lazy?: boolean;
+}
+
+/**
+ * Create a named, self-fetching reactive store.
+ *
+ * ```ts
+ * query('user', () => fetch('/api/user').then((r) => r.json()));
+ * // component: const user = useStore('user'); → {user.data?.name}
+ * ```
+ */
+export function query<T = unknown>(
+  name: string,
+  fetcher: () => Promise<T> | T,
+  options?: QueryOptions<T>,
+): QueryState<T>;
+
+declare const _default: { query: typeof query };
+export default _default;

package/src/index.js

@@ -0,0 +1,80 @@
+/**
+ * spark-html-query — declarative async data for spark-html.
+ *
+ * A `query` is a named store that fetches itself. It runs an async function and
+ * exposes the result as reactive store state — `{ data, error, loading,
+ * fetching, refetch, mutate, stop }` — so any component reads it with the same
+ * `useStore` it already knows, and re-renders as the request settles. Built
+ * entirely on `spark-html`'s `store()`: zero extra runtime, one dependency.
+ *
+ *   import { query } from 'spark-html-query';
+ *
+ *   query('user', () => fetch('/api/user').then((r) => r.json()), {
+ *     refetchInterval: 30000,   // optional: poll every 30s
+ *     initialData: null,        // optional: seed before the first fetch
+ *   });
+ *
+ *   // any component:
+ *   //   <script>const user = useStore('user');</script>
+ *   //   <p :hidden="!user.loading">Loading…</p>
+ *   //   <p :hidden="!user.error">Failed: {user.error.message}</p>
+ *   //   <h1 :hidden="user.loading">{user.data?.name}</h1>
+ *   //   <button onclick="{user.refetch}">Reload</button>
+ *
+ * Pairs with `derived()` — derive a shaped view from a query store, and the view
+ * updates as the request settles, memoized.
+ */
+import { store } from 'spark-html';
+
+export function query(name, fetcher, options = {}) {
+  const s = store(name, {
+    data: options.initialData ?? null,
+    error: null,
+    loading: options.initialData == null, // loading until the first result
+    fetching: false,                       // true during ANY fetch (incl. refetch)
+  });
+  // Tag for tooling (spark-html-devtools) — non-enumerable, never in state dumps.
+  try {
+    Object.defineProperty(s, Symbol.for('spark.storeKind'), { value: 'query', configurable: true });
+  } catch { /* ignore */ }
+
+  let runId = 0;
+  async function run() {
+    const id = ++runId;
+    s.fetching = true;
+    if (s.data == null) s.loading = true;
+    try {
+      const data = await fetcher();
+      if (id !== runId) return; // superseded by a newer refetch — drop
+      s.data = data;
+      s.error = null;
+    } catch (e) {
+      if (id !== runId) return;
+      s.error = e;
+    } finally {
+      if (id === runId) { s.loading = false; s.fetching = false; }
+    }
+  }
+
+  // Imperatively set data without a fetch (optimistic updates / cache writes).
+  function mutate(next) {
+    s.data = typeof next === 'function' ? next(s.data) : next;
+    s.error = null;
+  }
+
+  s.refetch = run;
+  s.mutate = mutate;
+
+  let timer = null;
+  if (options.refetchInterval > 0 && typeof setInterval === 'function') {
+    timer = setInterval(run, options.refetchInterval);
+  }
+  s.stop = () => { if (timer) { clearInterval(timer); timer = null; } };
+
+  // Kick off the first fetch (unless seeded with initialData and told to wait).
+  if (!(options.initialData != null && options.lazy)) run();
+
+  return s;
+}
+
+export default { query };