@lunora/vue 0.0.0 → 1.0.0-alpha.2

package/dist/index.d.mts

@@ -0,0 +1,348 @@
+import { Component, Ref, InjectionKey, App, DeepReadonly, MaybeRefOrGetter, ShallowRef, ComputedRef } from 'vue';
+import { Preloaded, LunoraClient, User, ConnectionStatus, FunctionReference, ReturnOf, ArgsOf, MutationCallOptions } from '@lunora/client';
+export type { ArgsOf, FunctionReference, LunoraClient, MutationCallOptions, OptimisticLocalStore, OptimisticUpdate, Preloaded, ReturnOf, Unsubscribe, User } from '@lunora/client';
+import { PaginationStatus } from '@lunora/client/pagination';
+export type { PaginationResult, PaginationStatus } from '@lunora/client/pagination';
+import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
+/**
+* Render the default slot only after auth has settled and a token + user are
+* both present. Hides the slot on first render and when signed out.
+*/
+declare const Authenticated: Component;
+/**
+* Render the default slot only when auth has settled and no token is present
+* (the signed-out state). Hidden while the user is still loading.
+*/
+declare const Unauthenticated: Component;
+/**
+* Render the default slot while authentication is still in progress — token is
+* set but `getCurrentUser()` has not yet resolved.
+*/
+declare const AuthLoading: Component;
+/**
+* Hydrate a query from a {@link Preloaded} token produced by `preloadQuery`
+* during SSR, then keep it live — the Vue half of PLAN4's reactive-loader
+* handoff.
+*
+* The returned `ref` is seeded **synchronously** from `preloaded.value`, so the
+* very first read (during hydration) shows the server value: no loading flash,
+* no hydration mismatch. After seeding it opens a WebSocket subscription on the
+* same `(functionPath, args, shardKey)` the SSR loader used, so every later
+* server delta updates the ref exactly like `useQuery`.
+*
+* The subscription tears down with the surrounding effect scope (component
+* unmount or `effectScope().stop()`), inherited from `subscribeToQuery`.
+*/
+declare const hydratePreloaded: <T>(preloaded: Preloaded<T>) => Ref<T | undefined>;
+/**
+* Injection key carrying the {@link LunoraClient} down the component tree.
+* Exported so advanced consumers can inject it by hand; most apps use
+* {@link createLunora} or {@link provideLunora}.
+*/
+declare const LUNORA_INJECTION_KEY: InjectionKey<LunoraClient>;
+/**
+* Vue plugin form: `app.use(createLunora(client))`. Mirrors the React
+* `LunoraProvider` — establishes the single app-wide client every composable
+* resolves through {@link useLunora}.
+*
+* The client is framework-neutral (`@lunora/client`): it owns the WebSocket
+* transport, subscription registry, offline queue, and delta-merge. This plugin
+* only wires it into Vue's `provide`/`inject` graph (read it with
+* {@link useLunora}); it adds no React, no store, and no extra reactivity layer.
+*/
+declare const createLunora: (client: LunoraClient) => {
+  install: (app: App) => void;
+};
+/**
+* Composition-API form: call inside a parent component's `setup()` to provide
+* the client to its subtree. The counterpart to `app.use(createLunora(client))`
+* when you'd rather scope the client to a subtree than the whole app. Must run
+* synchronously inside `setup()` (Vue's `provide` constraint).
+*/
+declare const provideLunora: (client: LunoraClient) => void;
+/**
+* Read the {@link LunoraClient} from the nearest provider — the Vue counterpart
+* to `@lunora/react`/`@lunora/solid`'s `useLunora`. Throws with a clear message
+* when called outside a `createLunora`/`provideLunora` scope so the failure
+* points at the missing provider rather than a later `undefined` deref.
+*/
+declare const useLunora: () => LunoraClient;
+/** Options shared by the live-query composables. */
+interface UseQueryOptions {
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+interface UseAuthResult {
+  setToken: (token: string | null) => void;
+  token: DeepReadonly<Ref<string | null>>;
+  user: DeepReadonly<Ref<User | null>>;
+}
+/**
+* Token + identity plumbing for Vue. `token` is a readonly ref tracking the
+* client's auth token; `user` is a readonly ref resolved from `getCurrentUser()`
+* whenever the token changes. `setToken(jwt)` after sign-in makes subsequent
+* RPC calls carry the `Authorization` header.
+*
+* Multiple `useAuth` instances within the same effect scope share a single
+* per-client identity store (from `@lunora/client/auth`) — a `setToken` from
+* one component re-renders every watcher with the freshly-resolved user.
+*/
+declare const useAuth: () => UseAuthResult;
+/**
+* Reactive view of the client's aggregate live-socket status across all shard
+* connections, exposed as a read-only `ref`. The value transitions through
+* `idle` → `connecting` → `connected` → `offline` as sockets open and drop —
+* use it to drive a connection indicator so an operator can tell a healthy live
+* channel from a silently-dropped one. The Vue-idiomatic equivalent of
+* `@lunora/react`'s `useConnectionStatus`.
+*
+* Teardown is wired to the active effect scope (`onScopeDispose`), so the
+* status listener is released on component unmount (or `effectScope().stop()`).
+* Call inside `setup()` / an active effect scope.
+*/
+declare const useConnectionStatus: () => Readonly<Ref<ConnectionStatus>>;
+/**
+* The reactive handle returned by {@link useMutation} — the Vue counterpart to
+* React's `useMutation`, re-expressed with refs. The surface is identical across
+* the Lunora adapters (`@lunora/solid`, `/svelte`): `data`/`error`/`pending` are
+* refs you read in a template, `mutate` is an awaitable that resolves with the
+* server value (or rejects). Per-call `optimistic` / `optimisticUpdate` options
+* pass straight through to `client.mutation`.
+*/
+interface MutationHandle<F extends FunctionReference> {
+  /** The latest invocation's resolved value, or `undefined` before the first success. */
+  data: Ref<ReturnOf<F> | undefined>;
+  /** The latest invocation's error, or `undefined`. */
+  error: Ref<Error | undefined>;
+  /** Invoke the mutation. Resolves with the server value; rejects on failure. */
+  mutate: (args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
+  /** `true` while ANY invocation from this handle is in flight (ref-counted, so overlapping calls compose). */
+  pending: Ref<boolean>;
+  /** Clear the latest `data`/`error` back to idle. */
+  reset: () => void;
+}
+/**
+* Returns a reactive {@link MutationHandle} for the given mutation reference —
+* the Vue equivalent of React's `useMutation`.
+*
+* Optimistic updates stay client-owned: the `optimistic` / `optimisticUpdate`
+* call options pass straight through to `client.mutation`, which applies and
+* rolls them back against the Lunora subscription cache (Convex parity).
+*
+* `pending` is ref-counted across overlapping invocations of THIS handle, so it
+* flips back to `false` only once every concurrent call has settled. The
+* ref-counted pending + error-normalize orchestration is the shared
+* `createMutationRunner` from `@lunora/client`; only the refs are
+* adapter-specific.
+*/
+declare const useMutation: <F extends FunctionReference>(function_: F) => MutationHandle<F>;
+/** The args a paginated query exposes minus the framework-supplied page cursor. */
+type PaginatedArgs<F extends FunctionReference> = Omit<ArgsOf<F>, "paginationOpts">;
+/** The element type of the `page` array a paginated query returns. */
+type PageItemOf<F extends FunctionReference> = ReturnOf<F> extends {
+  page: (infer T)[];
+} ? T : unknown;
+interface UsePaginatedQueryOptions {
+  /** Page size for the first page (and the default for `loadMore`). */
+  initialNumItems: number;
+  shardKey?: string;
+}
+interface UsePaginatedQueryResult<T> {
+  /** `true` while the first page or a `loadMore` page is in flight. */
+  isLoading: Ref<boolean>;
+  /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
+  loadMore: (numberItems: number) => void;
+  /** Flattened items across every loaded page, in order. */
+  results: Ref<T[]>;
+  status: Ref<PaginationStatus>;
+}
+/**
+* Subscribe to a reactively-paginated query and grow the feed page by page.
+*
+* The query function must accept a `paginationOpts: { numItems, cursor,
+* endCursor }` arg and return a `PaginationResult`. Pages are tracked as an
+* ordered list of stable boundary cursors; each loaded page is a live
+* subscription over a FIXED `(lower, upper]` range. Inserting or deleting a row
+* grows/shrinks the affected page without duplicating or skipping rows across
+* boundaries.
+*
+* `loadMore` appends the next page off the open-ended tail's `continueCursor`;
+* it is a no-op unless `status === "CanLoadMore"`. Background split/join
+* maintenance keeps page sizes near `initialNumItems` as edits accumulate.
+*
+* Changing `fn`, the base `args`, `initialNumItems`, or `shardKey` resets the
+* feed to its first page.
+*
+* Call inside `setup()` (or any active effect scope).
+*/
+declare const usePaginatedQuery: <F extends FunctionReference>(function_: F, args: MaybeRefOrGetter<"skip" | PaginatedArgs<F>>, options: UsePaginatedQueryOptions) => UsePaginatedQueryResult<PageItemOf<F>>;
+interface UseInfiniteQueryOptions {
+  /** Page size for the first page (and the default for `fetchNextPage`). */
+  initialNumItems: number;
+  shardKey?: string;
+}
+interface UseInfiniteQueryResult<T> {
+  /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
+  fetchNextPage: (numberItems?: number) => void;
+  /** `true` when the loaded tail reports it can load another page. */
+  hasNextPage: Ref<boolean>;
+  /** `true` while a `fetchNextPage` page (beyond the first) is in flight. */
+  isFetchingNextPage: Ref<boolean>;
+  /** `true` while the first page is in flight. */
+  isLoading: Ref<boolean>;
+  /** One inner array per loaded page, in order; unresolved pages are omitted. */
+  pages: Ref<T[][]>;
+  status: Ref<PaginationStatus>;
+}
+/**
+* Subscribe to a reactively-paginated query and expose its pages discretely.
+*
+* Shares `usePaginatedQuery`'s reactive-pagination engine but keeps each page
+* as its own inner array rather than flattening them, and adds the
+* TanStack-Query-style `fetchNextPage` / `hasNextPage` / `isFetchingNextPage`
+* shape.
+*
+* Call inside `setup()` (or any active effect scope).
+*/
+declare const useInfiniteQuery: <F extends FunctionReference>(function_: F, args: MaybeRefOrGetter<"skip" | PaginatedArgs<F>>, options: UseInfiniteQueryOptions) => UseInfiniteQueryResult<PageItemOf<F>>;
+/**
+* `usePresence` — collaborative-awareness composable, the client half of the
+* `@lunora/server` `definePresence` preset.
+*
+* Drives the heartbeat mutation (on mount, interval, and tab re-focus) and
+* subscribes to the live `listPresent` query for the given room.
+*
+* Call inside `setup()` (or any active effect scope).
+*/
+/**
+* A heartbeat mutation reference: takes `{ roomId, sessionId, data? }`.
+*/
+type HeartbeatReference = FunctionReference<"mutation", {
+  data?: Record<string, unknown>;
+  roomId: string;
+  sessionId: string;
+}>;
+/**
+* A listPresent query reference: takes `{ roomId }` and returns the array of
+* present members.
+*/
+type ListPresentReference = FunctionReference<"query", {
+  roomId: string;
+}>;
+interface UsePresenceOptions<H extends HeartbeatReference, L extends ListPresentReference> {
+  /** Awareness blob for the first heartbeat (selection, cursor, name, color…). */
+  data?: Record<string, unknown>;
+  /** The `api.*` reference for the presence heartbeat mutation. */
+  heartbeat: H;
+  /** Heartbeat cadence in ms. Defaults to 10s. */
+  intervalMs?: number;
+  /** The `api.*` reference for the presence listPresent query. */
+  listPresent: L;
+  /**
+  * Stable id for this presence row. Defaults to a fresh per-mount id.
+  * Pass a user/connection id to control deduping across tabs.
+  */
+  sessionId?: string;
+  /** Forwarded to the heartbeat mutation / listPresent subscription when sharding by room. */
+  shardKey?: string;
+}
+interface UsePresenceResult<L extends ListPresentReference> {
+  /** The present members for the room. `undefined` until the first push. */
+  present: ShallowRef<ReturnOf<L> | undefined>;
+  /** This mount's session id (generated when not supplied). */
+  sessionId: string;
+  /** Replace the awareness `data` sent with subsequent heartbeats, and heartbeat immediately. */
+  setData: (data: Record<string, unknown> | undefined) => void;
+}
+declare const usePresence: <H extends HeartbeatReference, L extends ListPresentReference>(roomId: string, options: UsePresenceOptions<H, L>) => UsePresenceResult<L>;
+/**
+* Open a live subscription against `client` for FIXED args and stream its values
+* into a `ref`. The low-level primitive behind `hydratePreloaded` (whose args
+* come from an immutable `Preloaded` token and never change); {@link useQuery}
+* handles the reactive-args case separately.
+*
+* `client.subscribe` already dedupes by `(functionPath, args, shardKey)` and
+* replays the last value synchronously, so multiple consumers of the same query
+* ride one server-side registration. `seed` sets the ref's value synchronously
+* before the subscription attaches, so the first read shows the SSR value with
+* no loading flash.
+*
+* Teardown is wired to the active effect scope (`onScopeDispose`), so it fires
+* on component unmount or `effectScope().stop()`. Call it inside `setup()` / an
+* effect scope (as `hydratePreloaded` does); outside any scope there is nothing
+* to own the subscription, so it would leak until the process exits — the
+* `getCurrentScope` guard only avoids throwing, it does not auto-clean.
+*/
+declare const subscribeToQuery: <F extends FunctionReference, T = ReturnOf<F>>(client: LunoraClient, function_: F, args: ArgsOf<F>, options?: {
+  seed?: T;
+  shardKey?: string;
+}) => Ref<T | undefined>;
+/**
+* Subscribe to a server query and expose its latest value as a `ref`.
+*
+* The returned ref is `undefined` until the first server response lands, then
+* updates on every delta the server pushes — the Vue-idiomatic equivalent of
+* React's `useQuery`. `args` may be a plain value, a `ref`, or a getter: passing
+* a reactive source makes the subscription reactive — when the args change the
+* old subscription is torn down and a fresh one opens for the new args (matching
+* `@lunora/react`/`@lunora/solid`). Pass `"skip"` (or a source resolving to
+* `"skip"`) to short-circuit: no network call, no socket. The subscription tears
+* down automatically when the owning component unmounts (or the effect scope
+* stops).
+*
+* Call inside `setup()` (or any active effect scope). For SSR seeding with no
+* loading flash, use `hydratePreloaded` instead.
+*/
+declare const useQuery: <F extends FunctionReference>(function_: F, args: MaybeRefOrGetter<ArgsOf<F> | "skip">, options?: UseQueryOptions) => Ref<ReturnOf<F> | undefined>;
+interface UseRateLimitOptions {
+  /** Clock injection for tests. Defaults to `Date.now`. */
+  now?: () => number;
+  /**
+  * Re-render cadence in milliseconds while throttled, so `retryAfter` ticks
+  * down and `disabled` flips back automatically. Defaults to `1000`.
+  */
+  tickMs?: number;
+}
+interface UseRateLimitResult {
+  /** Would consuming `count` (default 1) succeed right now? Does not consume. */
+  check: (count?: number) => boolean;
+  /** Optimistically consume `count` (default 1) locally; mirrors the server algorithm. */
+  consume: (count?: number) => RateLimitStatus;
+  /** `true` while a single unit cannot be consumed — convenient for disabling a control. */
+  disabled: ComputedRef<boolean>;
+  /** `true` while a single unit can be consumed. */
+  ok: ComputedRef<boolean>;
+  /** Clear local accounting (e.g. after the server confirms a reset). */
+  reset: () => void;
+  /** Milliseconds until the next unit is available. `0` when `ok`. */
+  retryAfter: ComputedRef<number>;
+}
+/**
+* Client-side mirror of a rate limit for instant UX — disable a button or show
+* a countdown without a round-trip. It runs the same token-bucket / fixed-window
+* math as `@lunora/ratelimit` on the server, so the prediction agrees with the
+* authoritative check; the server remains the source of truth.
+*
+* `config` accepts a plain object, a `ref`, or a getter (`MaybeRefOrGetter`).
+* When you pass a ref/getter it is tracked reactively — changing the config
+* re-derives `status` (and the `ok` / `disabled` / `retryAfter` views) on the
+* fly. A plain object keeps working unchanged; pass a stable reference (module
+* constant) so the reactive derived values stay settled.
+*/
+declare const useRateLimit: (config: MaybeRefOrGetter<RateLimitConfig>, options?: UseRateLimitOptions) => UseRateLimitResult;
+interface UseSubscriptionResult<T> {
+  data: Ref<T | undefined>;
+  error: Ref<Error | undefined>;
+}
+/**
+* Subscribe to a reactive server push stream. Returns `{ data, error }` refs
+* that update whenever the server emits a new value. Passing `"skip"` as `args`
+* (or a ref/getter that resolves to `"skip"`) tears down the subscription
+* without unmounting.
+*
+* Unlike `useQuery`, which tracks the full reactive cache, `useSubscription`
+* owns a single lightweight subscription and is suitable for ephemeral,
+* high-frequency streams.
+*/
+declare const useSubscription: <F extends FunctionReference>(function_: F, args: MaybeRefOrGetter<ArgsOf<F> | "skip">, options?: UseQueryOptions) => UseSubscriptionResult<ReturnOf<F>>;
+export { AuthLoading, Authenticated, type HeartbeatReference, LUNORA_INJECTION_KEY, type ListPresentReference, type MutationHandle, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseSubscriptionResult, createLunora, hydratePreloaded, provideLunora, subscribeToQuery, useAuth, useConnectionStatus, useInfiniteQuery, useLunora, useMutation, usePaginatedQuery, usePresence, useQuery, useRateLimit, useSubscription };