@lunora/client 0.0.0 → 1.0.0-alpha.10

package/dist/packem_shared/offline-queue-7Wc4onA0.mjs

@@ -0,0 +1,164 @@
+const isStaleVersion = (current, stamped) => current !== void 0 && stamped !== current;
+
+let idCounter = 0;
+const nextId = () => {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  idCounter += 1;
+  const entropy = typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function" ? [...crypto.getRandomValues(new Uint8Array(8))].map((byte) => byte.toString(16).padStart(2, "0")).join("") : (
+    // eslint-disable-next-line sonarjs/pseudo-random -- non-cryptographic uniqueness entropy, not a security token; only reached when neither crypto.randomUUID nor crypto.getRandomValues exists
+    Math.random().toString(16).slice(2, 12)
+  );
+  return `m_${Date.now().toString(36)}_${idCounter.toString(36)}_${entropy}`;
+};
+const reportPersistenceError = (handler, operation, error, mutationId) => {
+  if (handler) {
+    handler({ error, mutationId, operation });
+    return;
+  }
+  console.warn(`[lunora] offline-queue persistence ${operation} failed`, error);
+};
+class OfflineQueue {
+  /** Opt-in to queueing mutations before the targeted shard's first connect. */
+  queueBeforeFirstConnect;
+  maxItems;
+  onPersistenceError;
+  persistence;
+  onEvict;
+  onSizeChange;
+  /** App/schema version stamped on persisted writes; mismatched records are purged on hydrate. */
+  version;
+  items = [];
+  constructor(options = {}, deps = {}) {
+    this.maxItems = options.maxItems ?? 1e3;
+    this.queueBeforeFirstConnect = options.queueBeforeFirstConnect ?? false;
+    this.onPersistenceError = options.onPersistenceError;
+    this.persistence = deps.persistence;
+    this.onEvict = deps.onEvict;
+    this.onSizeChange = deps.onSizeChange;
+    this.version = deps.version;
+  }
+  get size() {
+    return this.items.length;
+  }
+  enqueue(entry) {
+    const item = entry;
+    item.id ??= nextId();
+    this.items.push(item);
+    this.persistence?.append({
+      args: item.args,
+      functionPath: item.functionPath,
+      id: item.id,
+      identity: item.identity,
+      shardKey: item.shardKey,
+      ...this.version === void 0 ? {} : { version: this.version }
+    }).catch((error) => {
+      reportPersistenceError(this.onPersistenceError, "append", error, item.id);
+    });
+    while (this.items.length > this.maxItems) {
+      const dropped = this.items.shift();
+      if (dropped) {
+        if (dropped.id) {
+          this.persistence?.remove(dropped.id).catch((error2) => {
+            reportPersistenceError(this.onPersistenceError, "remove", error2, dropped.id);
+          });
+        }
+        const error = new Error("offline queue overflow");
+        error.code = "OFFLINE_QUEUE_OVERFLOW";
+        dropped.reject(error);
+        this.onEvict?.(dropped, error);
+      }
+    }
+    this.notifySize();
+  }
+  /**
+   * Restore mutations persisted in a prior session and re-queue them in FIFO
+   * order. Restored entries already live in durable storage, so they are not
+   * re-appended; they carry no-op `resolve`/`reject` (the original awaiter is
+   * gone after a reload). No-op when no persistence adapter is configured.
+   * Returns the distinct shard keys of the restored writes so the caller can
+   * open their sockets to trigger a flush.
+   */
+  async hydrate() {
+    if (!this.persistence) {
+      return [];
+    }
+    const persisted = await this.persistence.load();
+    const shardKeys = /* @__PURE__ */ new Set();
+    for (const mutation of persisted) {
+      if (this.items.some((item) => item.id === mutation.id)) {
+        continue;
+      }
+      if (isStaleVersion(this.version, mutation.version)) {
+        this.persistence.remove(mutation.id).catch((error) => {
+          reportPersistenceError(this.onPersistenceError, "remove", error, mutation.id);
+        });
+        continue;
+      }
+      this.items.push({
+        args: mutation.args,
+        functionPath: mutation.functionPath,
+        id: mutation.id,
+        identity: mutation.identity,
+        reject: () => void 0,
+        resolve: () => void 0,
+        shardKey: mutation.shardKey
+      });
+      shardKeys.add(mutation.shardKey);
+    }
+    this.notifySize();
+    return [...shardKeys];
+  }
+  /**
+   * Remove and return queued mutations. With no `predicate`, drains the whole
+   * queue. With one, drains only matching entries (preserving FIFO order) and
+   * leaves the rest queued — used to flush a single shard's writes when its
+   * socket reconnects while other shards are still down.
+   */
+  drain(predicate) {
+    if (!predicate) {
+      const drained2 = [...this.items];
+      this.items.length = 0;
+      this.notifySize();
+      return drained2;
+    }
+    const drained = [];
+    const kept = [];
+    for (const item of this.items) {
+      (predicate(item) ? drained : kept).push(item);
+    }
+    this.items.length = 0;
+    this.items.push(...kept);
+    this.notifySize();
+    return drained;
+  }
+  /**
+   * Return previously-drained mutations to the front of the queue, preserving
+   * their FIFO order, without re-persisting them — they were never unpersisted,
+   * so durable storage still holds them. Used when a flush aborts on a transient
+   * transport failure: the unreplayed writes stay queued for the next reconnect.
+   */
+  requeue(items) {
+    if (items.length === 0) {
+      return;
+    }
+    this.items.unshift(...items);
+    this.notifySize();
+  }
+  clear() {
+    for (const item of this.items) {
+      const error = new Error("CLIENT_CLOSED");
+      error.code = "CLIENT_CLOSED";
+      item.reject(error);
+    }
+    this.items.length = 0;
+    this.notifySize();
+  }
+  /** Notify the size observer (the client's pending-sync count) after any change. */
+  notifySize() {
+    this.onSizeChange?.(this.items.length);
+  }
+}
+
+export { OfflineQueue as O, isStaleVersion as i, nextId as n, reportPersistenceError as r };

package/dist/packem_shared/preload.d-3XJD-2hM.d.mts

@@ -0,0 +1,20 @@
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-B5vWSgvD.mjs";
+/**
+* Run a query once on the server (during SSR) and capture its result in a
+* serializable {@link Preloaded} token. Embed the token in the rendered HTML and
+* pass it to `usePreloadedQuery` on the client: the first client render shows
+* the server value with no loading flash, then a live subscription takes over.
+*
+* The query is executed through the supplied {@link LunoraClient} over the same
+* HTTP RPC path the browser uses, so the SSR client only needs a `fetch`
+* implementation that can reach the worker — no in-process Durable Object access.
+*/
+declare const preloadQuery: <F extends FunctionReference>(client: LunoraClient, function_: F, args: ArgsOf<F>, options?: {
+  shardKey?: string;
+}) => Promise<Preloaded<ReturnOf<F>>>;
+/**
+* Read the captured value out of a {@link Preloaded} token without subscribing.
+* Useful on the server (or in tests) when you only need the data, not a live feed.
+*/
+declare const preloadedQueryResult: <T>(preloaded: Preloaded<T>) => T;
+export { preloadedQueryResult as a, preloadQuery as p };

package/dist/packem_shared/preload.d-CKZR675M.d.ts

@@ -0,0 +1,20 @@
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-B5vWSgvD.js";
+/**
+* Run a query once on the server (during SSR) and capture its result in a
+* serializable {@link Preloaded} token. Embed the token in the rendered HTML and
+* pass it to `usePreloadedQuery` on the client: the first client render shows
+* the server value with no loading flash, then a live subscription takes over.
+*
+* The query is executed through the supplied {@link LunoraClient} over the same
+* HTTP RPC path the browser uses, so the SSR client only needs a `fetch`
+* implementation that can reach the worker — no in-process Durable Object access.
+*/
+declare const preloadQuery: <F extends FunctionReference>(client: LunoraClient, function_: F, args: ArgsOf<F>, options?: {
+  shardKey?: string;
+}) => Promise<Preloaded<ReturnOf<F>>>;
+/**
+* Read the captured value out of a {@link Preloaded} token without subscribing.
+* Useful on the server (or in tests) when you only need the data, not a live feed.
+*/
+declare const preloadedQueryResult: <T>(preloaded: Preloaded<T>) => T;
+export { preloadedQueryResult as a, preloadQuery as p };

package/dist/packem_shared/preloadQuery-lobFkD2Z.mjs

@@ -0,0 +1,13 @@
+const preloadQuery = async (client, function_, args, options = {}) => {
+  const value = await client.query(function_, args, options);
+  return {
+    __lunoraPreloaded: true,
+    args: args ?? {},
+    functionPath: function_.__lunoraRef,
+    shardKey: options.shardKey,
+    value
+  };
+};
+const preloadedQueryResult = (preloaded) => preloaded.value;
+
+export { preloadQuery, preloadedQueryResult };

package/dist/packem_shared/subscription-C1Jy7HiF.mjs

@@ -0,0 +1,55 @@
+const compareKeys = (a, b) => {
+  if (a < b) {
+    return -1;
+  }
+  return a > b ? 1 : 0;
+};
+const stableStringify = (value) => {
+  if (value === void 0) {
+    return "null";
+  }
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const record = value;
+  const keys = Object.keys(record).toSorted(compareKeys);
+  const parts = [];
+  for (const key of keys) {
+    const raw = record[key];
+    if (raw === void 0) {
+      continue;
+    }
+    parts.push(`${JSON.stringify(key)}:${stableStringify(raw)}`);
+  }
+  return `{${parts.join(",")}}`;
+};
+
+class SubscriptionRegistry {
+  static key(functionPath, args, shardKey) {
+    return `${functionPath}::${stableStringify(args)}::${shardKey ?? ""}`;
+  }
+  byKey = /* @__PURE__ */ new Map();
+  byId = /* @__PURE__ */ new Map();
+  get(key) {
+    return this.byKey.get(key);
+  }
+  getById(id) {
+    return this.byId.get(id);
+  }
+  add(state) {
+    this.byKey.set(SubscriptionRegistry.key(state.fn.__lunoraRef, state.args, state.shardKey), state);
+    this.byId.set(state.id, state);
+  }
+  remove(state) {
+    this.byKey.delete(SubscriptionRegistry.key(state.fn.__lunoraRef, state.args, state.shardKey));
+    this.byId.delete(state.id);
+  }
+  all() {
+    return [...this.byKey.values()];
+  }
+}
+
+export { SubscriptionRegistry as S, stableStringify as s };

package/dist/pagination/index.d.mts

@@ -0,0 +1,82 @@
+/**
+* `@lunora/client/pagination` — the framework-agnostic pagination state machine
+* shared by every Lunora UI adapter (React, Vue, Svelte, Solid).
+*
+* Owns cursor tracking, page-size rebalancing (split/join), `initialPages`,
+* `rebalance`, and the shared types (`Page`, `PaginationResult`,
+* `PaginationStatus`, `PaginatedCoreResult`). Nothing here imports a UI
+* framework — each adapter wires the pure functions into its own reactive
+* primitives.
+*/
+/** Grow factor: a bounded page is split when it exceeds this multiple of its target size. */
+declare const SPLIT_FACTOR = 2;
+/** Shrink factor: a bounded page with a neighbour is joined when it falls below this multiple of its target size. */
+declare const JOIN_FACTOR = .5;
+/** A loaded page: a fixed `(lower, upper]` range plus the size it targets. */
+interface Page {
+  lower: null | string;
+  numItems: number;
+  upper: null | string;
+}
+/** One page returned by a paginated query — the shape `.paginate()` yields. */
+interface PaginationResult<T = unknown> {
+  continueCursor: null | string;
+  isDone: boolean;
+  page: T[];
+  /**
+  * Reactive-pagination only: the midpoint cursor of a bounded
+  * `(cursor, endCursor]` page, used to split an over-grown page into two
+  * adjacent ranges. Absent on legacy (open-ended) pages.
+  */
+  splitCursor?: null | string;
+}
+/**
+* Lifecycle of a `usePaginatedQuery` feed.
+*
+* - `LoadingFirstPage` — the first page is in flight; `results` is empty.
+* - `CanLoadMore` — the loaded tail has a cursor; calling `loadMore` fetches the next page.
+* - `LoadingMore` — a `loadMore` page is in flight; earlier results stay visible.
+* - `Exhausted` — every page has loaded and the server reported `isDone`.
+*/
+type PaginationStatus = "CanLoadMore" | "Exhausted" | "LoadingFirstPage" | "LoadingMore";
+interface PaginatedCoreResult<T> {
+  /** Request another page off the open-ended tail. A no-op unless `status === "CanLoadMore"`. */
+  loadMore: (numberItems: number) => void;
+  /** Per-page resolved results in order; entries are `undefined` until a page resolves. */
+  pageResults: (PaginationResult<T> | undefined)[];
+  status: PaginationStatus;
+}
+/** First-page seed: a single open-ended range starting at the feed head. */
+declare const initialPages: (numberItems: number) => Page[];
+/**
+* Run the SPLIT/JOIN maintenance pass over the current page list given freshly
+* resolved results. Returns a new page list when a boundary changed, or
+* `undefined` when the layout is already balanced (so the caller can skip a
+* setState).
+*
+* Only ONE structural edit is applied per pass (the first split or join found),
+* letting the subsequent re-render's resolved results drive the next pass — this
+* keeps each transition observable and avoids reasoning about several
+* simultaneous boundary moves.
+*/
+declare const rebalance: (pages: Page[], results: (PaginationResult | undefined)[]) => Page[] | undefined;
+/**
+* Derive the feed `status` and the next-page cursor from the current page list
+* and resolved page results. Framework adapters call this each render/effect to
+* compute what to expose to callers.
+*/
+declare const derivePaginationStatus: <T>(skipped: boolean, pageResults: (PaginationResult<T> | undefined)[]) => {
+  nextCursor: null | string | undefined;
+  status: PaginationStatus;
+};
+/**
+* Apply a `loadMore` to the current page list. Pins the open-ended tail at
+* `cursor` (making it a fixed bounded range) and appends a fresh open-ended
+* page starting at `cursor`. The shared boundary keeps the feed gap- and
+* dup-free.
+*
+* Returns the new page list, or `undefined` when the given `cursor` is not
+* valid (null or undefined — caller should no-op).
+*/
+declare const applyLoadMore: (pages: Page[], cursor: null | string | undefined, numberItems: number) => Page[] | undefined;
+export { JOIN_FACTOR, type Page, type PaginatedCoreResult, type PaginationResult, type PaginationStatus, SPLIT_FACTOR, applyLoadMore, derivePaginationStatus, initialPages, rebalance };

package/dist/pagination/index.d.ts

@@ -0,0 +1,82 @@
+/**
+* `@lunora/client/pagination` — the framework-agnostic pagination state machine
+* shared by every Lunora UI adapter (React, Vue, Svelte, Solid).
+*
+* Owns cursor tracking, page-size rebalancing (split/join), `initialPages`,
+* `rebalance`, and the shared types (`Page`, `PaginationResult`,
+* `PaginationStatus`, `PaginatedCoreResult`). Nothing here imports a UI
+* framework — each adapter wires the pure functions into its own reactive
+* primitives.
+*/
+/** Grow factor: a bounded page is split when it exceeds this multiple of its target size. */
+declare const SPLIT_FACTOR = 2;
+/** Shrink factor: a bounded page with a neighbour is joined when it falls below this multiple of its target size. */
+declare const JOIN_FACTOR = .5;
+/** A loaded page: a fixed `(lower, upper]` range plus the size it targets. */
+interface Page {
+  lower: null | string;
+  numItems: number;
+  upper: null | string;
+}
+/** One page returned by a paginated query — the shape `.paginate()` yields. */
+interface PaginationResult<T = unknown> {
+  continueCursor: null | string;
+  isDone: boolean;
+  page: T[];
+  /**
+  * Reactive-pagination only: the midpoint cursor of a bounded
+  * `(cursor, endCursor]` page, used to split an over-grown page into two
+  * adjacent ranges. Absent on legacy (open-ended) pages.
+  */
+  splitCursor?: null | string;
+}
+/**
+* Lifecycle of a `usePaginatedQuery` feed.
+*
+* - `LoadingFirstPage` — the first page is in flight; `results` is empty.
+* - `CanLoadMore` — the loaded tail has a cursor; calling `loadMore` fetches the next page.
+* - `LoadingMore` — a `loadMore` page is in flight; earlier results stay visible.
+* - `Exhausted` — every page has loaded and the server reported `isDone`.
+*/
+type PaginationStatus = "CanLoadMore" | "Exhausted" | "LoadingFirstPage" | "LoadingMore";
+interface PaginatedCoreResult<T> {
+  /** Request another page off the open-ended tail. A no-op unless `status === "CanLoadMore"`. */
+  loadMore: (numberItems: number) => void;
+  /** Per-page resolved results in order; entries are `undefined` until a page resolves. */
+  pageResults: (PaginationResult<T> | undefined)[];
+  status: PaginationStatus;
+}
+/** First-page seed: a single open-ended range starting at the feed head. */
+declare const initialPages: (numberItems: number) => Page[];
+/**
+* Run the SPLIT/JOIN maintenance pass over the current page list given freshly
+* resolved results. Returns a new page list when a boundary changed, or
+* `undefined` when the layout is already balanced (so the caller can skip a
+* setState).
+*
+* Only ONE structural edit is applied per pass (the first split or join found),
+* letting the subsequent re-render's resolved results drive the next pass — this
+* keeps each transition observable and avoids reasoning about several
+* simultaneous boundary moves.
+*/
+declare const rebalance: (pages: Page[], results: (PaginationResult | undefined)[]) => Page[] | undefined;
+/**
+* Derive the feed `status` and the next-page cursor from the current page list
+* and resolved page results. Framework adapters call this each render/effect to
+* compute what to expose to callers.
+*/
+declare const derivePaginationStatus: <T>(skipped: boolean, pageResults: (PaginationResult<T> | undefined)[]) => {
+  nextCursor: null | string | undefined;
+  status: PaginationStatus;
+};
+/**
+* Apply a `loadMore` to the current page list. Pins the open-ended tail at
+* `cursor` (making it a fixed bounded range) and appends a fresh open-ended
+* page starting at `cursor`. The shared boundary keeps the feed gap- and
+* dup-free.
+*
+* Returns the new page list, or `undefined` when the given `cursor` is not
+* valid (null or undefined — caller should no-op).
+*/
+declare const applyLoadMore: (pages: Page[], cursor: null | string | undefined, numberItems: number) => Page[] | undefined;
+export { JOIN_FACTOR, type Page, type PaginatedCoreResult, type PaginationResult, type PaginationStatus, SPLIT_FACTOR, applyLoadMore, derivePaginationStatus, initialPages, rebalance };

package/dist/pagination/index.mjs

@@ -0,0 +1,61 @@
+const SPLIT_FACTOR = 2;
+const JOIN_FACTOR = 0.5;
+const initialPages = (numberItems) => [
+  // eslint-disable-next-line unicorn/no-null -- `lower: null` is the feed head, `upper: null` the open-ended tail — both are wire-shape cursors.
+  { lower: null, numItems: numberItems, upper: null }
+];
+const rebalance = (pages, results) => {
+  for (const [index, page] of pages.entries()) {
+    if (page.upper === null) {
+      continue;
+    }
+    const result = results[index];
+    if (!result) {
+      continue;
+    }
+    const size = result.page.length;
+    if (size > SPLIT_FACTOR * page.numItems && result.splitCursor) {
+      const split = result.splitCursor;
+      const next = [...pages];
+      next.splice(index, 1, { lower: page.lower, numItems: page.numItems, upper: split }, { lower: split, numItems: page.numItems, upper: page.upper });
+      return next;
+    }
+    if (size < JOIN_FACTOR * page.numItems && index + 1 < pages.length) {
+      const neighbour = pages[index + 1];
+      if (!neighbour) {
+        continue;
+      }
+      const next = [...pages];
+      next.splice(index, 2, { lower: page.lower, numItems: page.numItems, upper: neighbour.upper });
+      return next;
+    }
+  }
+  return void 0;
+};
+const derivePaginationStatus = (skipped, pageResults) => {
+  if (skipped || !pageResults[0]) {
+    return { nextCursor: void 0, status: "LoadingFirstPage" };
+  }
+  const tail = pageResults.at(-1);
+  if (!tail) {
+    return { nextCursor: void 0, status: "LoadingMore" };
+  }
+  if (tail.isDone || tail.continueCursor === null) {
+    return { nextCursor: void 0, status: "Exhausted" };
+  }
+  return { nextCursor: tail.continueCursor, status: "CanLoadMore" };
+};
+const applyLoadMore = (pages, cursor, numberItems) => {
+  if (cursor === void 0 || cursor === null) {
+    return void 0;
+  }
+  const next = [...pages];
+  const tail = next.at(-1);
+  if (tail) {
+    next[next.length - 1] = { lower: tail.lower, numItems: tail.numItems, upper: cursor };
+  }
+  next.push({ lower: cursor, numItems: numberItems, upper: null });
+  return next;
+};
+
+export { JOIN_FACTOR, SPLIT_FACTOR, applyLoadMore, derivePaginationStatus, initialPages, rebalance };

package/dist/query/index.d.mts

@@ -0,0 +1,62 @@
+import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-B5vWSgvD.mjs";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-B5vWSgvD.mjs";
+import '@lunora/runtime';
+/**
+* The sentinel a framework adapter resolves its reactive args to when it wants
+* to short-circuit a query — no network call, no socket.
+*/
+declare const SKIP: "skip";
+/** Args after a framework has resolved its reactivity primitive, or the skip sentinel. */
+type ResolvedArgs<F extends FunctionReference> = ArgsOf<F> | typeof SKIP;
+/**
+* The framework-neutral sinks a {@link createQuerySubscription} call drives. A
+* framework adapter supplies these, wiring each into its own reactivity
+* primitive (a TanStack cache write, a Vue `ref`, a Svelte store `set`, a Solid
+* signal setter).
+*
+* `onData` fires when a fresh server value lands (the initial frame or a delta).
+* `onError` fires when the subscription attach threw, or the server pushed a
+* subscription-scoped error — it is optional, and when omitted an attach throw
+* propagates to the caller (preserving the "no error channel" behaviour of
+* adapters like Solid/Vue that never had one) rather than being swallowed.
+* `onReset` fires when the resolved args are `"skip"`: clear any prior value.
+*/
+interface QuerySubscriptionSinks<T> {
+  onData: (value: T) => void;
+  onError?: (error: SubscriptionError) => void;
+  onReset?: () => void;
+}
+interface QuerySubscriptionOptions {
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+/** Normalise an unknown thrown value into the client's {@link SubscriptionError} shape. */
+declare const toSubscriptionError: (error: unknown) => SubscriptionError;
+/**
+* The subscribe → snapshot → error/reset → cleanup state machine shared by
+* every Lunora framework adapter's live-query hook.
+*
+* Given a `client`, a function reference, the already-resolved `args` (a
+* framework reads its own reactive source first, then hands the plain value in),
+* and a set of {@link QuerySubscriptionSinks}, this opens one `client.subscribe`
+* registration and returns the {@link Unsubscribe} to tear it down. Each
+* framework owns *when* to call this (a React effect, a Vue `watch`, a Svelte
+* store start callback, a Solid `createEffect(on(...))`) and *where* to stash
+* the value — this owns the lifecycle in between, so the skip-handling, the
+* value/error fan-out, the attach-throw normalisation, and the
+* cancellation-guarded teardown live in exactly one place.
+*
+* Behaviour. When `args === "skip"` it calls `sinks.onReset?.()` and returns a
+* no-op teardown; no `client.subscribe` is issued. Otherwise it opens
+* `client.subscribe(fn, args, …, { shardKey, onError })`: server pushes route to
+* `sinks.onData`, and the client's own `onError` channel (a server-rejected
+* subscription) routes to `sinks.onError` when present. The attach is wrapped —
+* if `client.subscribe` itself throws, the error is normalised to a
+* {@link SubscriptionError} and delivered to `sinks.onError` when present; with
+* no `onError` sink the throw is rethrown so adapters without an error channel
+* behave exactly as before. The returned teardown is idempotent and
+* cancellation-guarded: once it runs, no further `onData`/`onError` from an
+* in-flight push reaches the sinks.
+*/
+declare const createQuerySubscription: <F extends FunctionReference, T = ReturnOf<F>>(client: LunoraClient, function_: F, args: ResolvedArgs<F>, sinks: QuerySubscriptionSinks<T>, options?: QuerySubscriptionOptions) => Unsubscribe;
+export { type ArgsOf, type FunctionReference, type QuerySubscriptionOptions, type QuerySubscriptionSinks, type ResolvedArgs, type ReturnOf, SKIP, type SubscriptionError, type Unsubscribe, createQuerySubscription, toSubscriptionError };

package/dist/query/index.d.ts

@@ -0,0 +1,62 @@
+import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-B5vWSgvD.js";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-B5vWSgvD.js";
+import '@lunora/runtime';
+/**
+* The sentinel a framework adapter resolves its reactive args to when it wants
+* to short-circuit a query — no network call, no socket.
+*/
+declare const SKIP: "skip";
+/** Args after a framework has resolved its reactivity primitive, or the skip sentinel. */
+type ResolvedArgs<F extends FunctionReference> = ArgsOf<F> | typeof SKIP;
+/**
+* The framework-neutral sinks a {@link createQuerySubscription} call drives. A
+* framework adapter supplies these, wiring each into its own reactivity
+* primitive (a TanStack cache write, a Vue `ref`, a Svelte store `set`, a Solid
+* signal setter).
+*
+* `onData` fires when a fresh server value lands (the initial frame or a delta).
+* `onError` fires when the subscription attach threw, or the server pushed a
+* subscription-scoped error — it is optional, and when omitted an attach throw
+* propagates to the caller (preserving the "no error channel" behaviour of
+* adapters like Solid/Vue that never had one) rather than being swallowed.
+* `onReset` fires when the resolved args are `"skip"`: clear any prior value.
+*/
+interface QuerySubscriptionSinks<T> {
+  onData: (value: T) => void;
+  onError?: (error: SubscriptionError) => void;
+  onReset?: () => void;
+}
+interface QuerySubscriptionOptions {
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+/** Normalise an unknown thrown value into the client's {@link SubscriptionError} shape. */
+declare const toSubscriptionError: (error: unknown) => SubscriptionError;
+/**
+* The subscribe → snapshot → error/reset → cleanup state machine shared by
+* every Lunora framework adapter's live-query hook.
+*
+* Given a `client`, a function reference, the already-resolved `args` (a
+* framework reads its own reactive source first, then hands the plain value in),
+* and a set of {@link QuerySubscriptionSinks}, this opens one `client.subscribe`
+* registration and returns the {@link Unsubscribe} to tear it down. Each
+* framework owns *when* to call this (a React effect, a Vue `watch`, a Svelte
+* store start callback, a Solid `createEffect(on(...))`) and *where* to stash
+* the value — this owns the lifecycle in between, so the skip-handling, the
+* value/error fan-out, the attach-throw normalisation, and the
+* cancellation-guarded teardown live in exactly one place.
+*
+* Behaviour. When `args === "skip"` it calls `sinks.onReset?.()` and returns a
+* no-op teardown; no `client.subscribe` is issued. Otherwise it opens
+* `client.subscribe(fn, args, …, { shardKey, onError })`: server pushes route to
+* `sinks.onData`, and the client's own `onError` channel (a server-rejected
+* subscription) routes to `sinks.onError` when present. The attach is wrapped —
+* if `client.subscribe` itself throws, the error is normalised to a
+* {@link SubscriptionError} and delivered to `sinks.onError` when present; with
+* no `onError` sink the throw is rethrown so adapters without an error channel
+* behave exactly as before. The returned teardown is idempotent and
+* cancellation-guarded: once it runs, no further `onData`/`onError` from an
+* in-flight push reaches the sinks.
+*/
+declare const createQuerySubscription: <F extends FunctionReference, T = ReturnOf<F>>(client: LunoraClient, function_: F, args: ResolvedArgs<F>, sinks: QuerySubscriptionSinks<T>, options?: QuerySubscriptionOptions) => Unsubscribe;
+export { type ArgsOf, type FunctionReference, type QuerySubscriptionOptions, type QuerySubscriptionSinks, type ResolvedArgs, type ReturnOf, SKIP, type SubscriptionError, type Unsubscribe, createQuerySubscription, toSubscriptionError };

package/dist/query/index.mjs

@@ -0,0 +1 @@
+export { SKIP, createQuerySubscription, toSubscriptionError } from '../packem_shared/SKIP-vItZChkw.mjs';