@lunora/solid 0.0.0 → 1.0.0-alpha.10

package/dist/index.d.mts

@@ -0,0 +1,408 @@
+import { LunoraClient, User, ConnectionStatus, FunctionReference, ArgsOf, MutationCallOptions, ReturnOf, MutatorHandle, Preloaded } from '@lunora/client';
+export type { ArgsOf, FunctionReference, MutatorHandle, MutatorTransaction, OptimisticUpdate, Preloaded, ReturnOf, Unsubscribe } from '@lunora/client';
+import { Context, JSX, Accessor } from 'solid-js';
+import { PaginationStatus } from '@lunora/client/pagination';
+import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
+/**
+* Solid context carrying the framework-neutral {@link LunoraClient}. Every
+* reactive primitive in this adapter (`createQuery`, `createMutation`,
+* `hydratePreloaded`) reads the client from here, so a single
+* `<LunoraProvider client={…}>` at the root of the tree wires the whole app.
+*
+* Defaults to `undefined` so {@link useLunora} can throw a helpful error when a
+* primitive is used outside a provider rather than dereferencing it.
+*/
+declare const LunoraContext: Context<LunoraClient | undefined>;
+/**
+* Read the {@link LunoraClient} from the nearest `&lt;LunoraProvider>`.
+*
+* Throws when called outside a provider — the client is required to open the
+* HTTP/WS transport, so there is no sensible fallback. The React adapter's
+* `useLunora` has the same contract.
+*/
+declare const useLunora: () => LunoraClient;
+interface UseAuthResult {
+  setToken: (token: string | null) => void;
+  token: Accessor<string | null>;
+  user: Accessor<User | null>;
+}
+/**
+* Token + identity plumbing for Solid. Returns `{ token, user, setToken }`
+* where `token` and `user` are fine-grained signals. `setToken(jwt)` after
+* sign-in updates the shared client token; `user` resolves asynchronously via
+* `client.getCurrentUser()` and updates on every token change.
+*/
+declare const createAuth: () => UseAuthResult;
+interface AuthGateProps {
+  children: JSX.Element;
+}
+/**
+* Render `children` only after authentication has settled and a token + user
+* are both present.
+*/
+declare const Authenticated: (props: AuthGateProps) => JSX.Element;
+/**
+* Render `children` while authentication is still in progress — token is set
+* but the user has not yet resolved.
+*/
+declare const AuthLoading: (props: AuthGateProps) => JSX.Element;
+/**
+* Render `children` only when auth has settled and no token is present (the
+* signed-out state).
+*/
+declare const Unauthenticated: (props: AuthGateProps) => JSX.Element;
+/**
+* Reactive accessor of the client's aggregate live-socket status across all
+* shard connections. Reads the current status synchronously and updates on
+* every transition (`idle` → `connecting` → `connected` → `offline`) — Solid's
+* fine-grained signals mean only the components that read the accessor
+* re-render. The Solid equivalent of `@lunora/react`'s `useConnectionStatus`.
+*
+* The status listener is torn down via `onCleanup` when the owning reactive
+* scope disposes (component unmount). Call inside a component / reactive root.
+*/
+declare const createConnectionStatus: () => Accessor<ConnectionStatus>;
+/** A targeting context merged on top of the app's default (`defineFlags({ identify })`). */
+type FlagContext = Record<string, unknown>;
+/** The value kinds a flag resolves to — OpenFeature's boolean / number / string / structured (JSON) flags. */
+type FlagValue = boolean | number | string | {
+  [key: string]: unknown;
+} | unknown[] | null;
+/** A plain value or a Solid accessor of it — matching `createQuery`'s reactive-args contract. */
+type MaybeAccessor<T> = Accessor<T> | T;
+/**
+* Subscribe to a single feature flag and return a reactive accessor of its value.
+*
+* The accessor reads `defaultValue` until the first evaluation lands, then the
+* server's resolved value — re-pushed whenever the provider re-evaluates (e.g. a
+* flag is toggled in Cloudflare Flagship). The flag's kind is inferred from
+* `defaultValue`'s runtime type, so `createFlag("dark", false)` reads a boolean
+* and `createFlag("hero", "control")` a string.
+*
+* `key` and `context` may be plain values or accessors; passing an accessor makes
+* the subscription reactive — when it changes the old subscription is torn down
+* (via `onCleanup`) and a fresh one opens. `context` supplies a per-call targeting
+* context merged on top of the app's default `identify` targeting key.
+*
+* Evaluation runs through whatever OpenFeature provider the app wired in
+* `lunora/flags.ts`; the read never throws — a provider error resolves the
+* default (the same fail-open contract as server-side `ctx.flags`).
+*/
+declare const createFlag: <T extends FlagValue>(key: MaybeAccessor<string>, defaultValue: T, context?: MaybeAccessor<FlagContext | undefined>) => Accessor<T>;
+/**
+* Subscribe to several feature flags at once and return a reactive accessor of
+* the resolved record.
+*
+* Pass a record of `key → defaultValue`; each flag's kind is inferred from its
+* default, and the accessor reads the same-shaped record with resolved values
+* (the defaults until each evaluation lands). A single `context` applies to every
+* flag and may be an accessor. This is the batched form of {@link createFlag}.
+*/
+declare const createFlags: <T extends Record<string, FlagValue>>(flags: T, context?: MaybeAccessor<FlagContext | undefined>) => Accessor<T>;
+interface MutationHandle<F extends FunctionReference> {
+  /** The latest invocation's resolved value, or `undefined` before the first success. */
+  data: Accessor<ReturnOf<F> | undefined>;
+  /** The latest invocation's error, or `undefined`. */
+  error: Accessor<Error | undefined>;
+  /** Invoke the mutation. Resolves with the server result; 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: Accessor<boolean>;
+  /** Clear `data`/`error` back to idle. */
+  reset: () => void;
+}
+/**
+* The transport surface {@link createMutation} actually needs — just
+* `client.mutation`. Narrowed so the primitive can be exercised against a stub
+* in tests without constructing a full `LunoraClient`.
+*/
+interface MutationClient<F extends FunctionReference> {
+  mutation: (function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
+}
+/**
+* Build a mutation handle bound to an explicit client. Internal seam used by the
+* provider-bound {@link createMutation}; exported for tests that inject a stub.
+* The ref-counted pending + error-normalize orchestration is the shared
+* `createMutationRunner` from `@lunora/client`; only the reactive sinks (Solid
+* signals) are adapter-specific.
+*/
+declare const createMutationForClient: <F extends FunctionReference>(client: MutationClient<F>, function_: F) => MutationHandle<F>;
+/**
+* Returns a reactive handle `{ mutate, pending, data, error, reset }` for the
+* given mutation reference, bound to the `LunoraClient` from the nearest
+* `&lt;LunoraProvider>`.
+*
+* Optimistic updates stay client-owned: the `optimistic` / `optimisticUpdate`
+* call options pass straight through to `client.mutation`, which applies and
+* rolls them back against the live Lunora subscription cache — the same
+* machinery `createQuery`/`hydratePreloaded` subscribe to, so an optimistic
+* write reflects in those accessors immediately and reverts on failure.
+*
+* `pending` is ref-counted across overlapping invocations of *this* handle, so
+* it only flips back to `false` once every concurrent call has settled. The
+* mutation also engages `@lunora/client`'s offline queue when the socket is
+* down, so `mutate` stays durable across reconnects.
+*/
+declare const createMutation: <F extends FunctionReference>(function_: F) => MutationHandle<F>;
+/**
+* The reactive handle returned by {@link createMutator} — the Solid counterpart
+* to `@lunora/react`'s `useMutator`, re-expressed with signals.
+* `error`/`isError`/`pending` are accessors and `mutate` is an awaitable that
+* resolves once the write is persisted (or rejects).
+*/
+interface MutatorHook<TArgs> {
+  /** The latest invocation's error, or `undefined`. */
+  error: Accessor<Error | undefined>;
+  /** `true` when the latest invocation rejected. */
+  isError: Accessor<boolean>;
+  /** Run the mutator; resolves once the write is persisted, rejects on failure. */
+  mutate: (args: TArgs) => Promise<void>;
+  /** `true` while ANY invocation from this handle is in flight (ref-counted, so overlapping calls compose). */
+  pending: Accessor<boolean>;
+  /** Clear the latest `error` back to idle. */
+  reset: () => void;
+}
+/**
+* Ergonomic `{ mutate, pending, error, isError, reset }` wrapper over a bound
+* custom-mutator handle from `@lunora/db`'s `bindMutators` — the Solid
+* equivalent of `@lunora/react`'s `useMutator`. The optimistic overlay and
+* server-authoritative push are owned by the bound handle (and TanStack DB's
+* optimistic-transaction layer rebases pending overlays on every sync tick);
+* this primitive only surfaces signal state for the in-flight/error lifecycle.
+* Reads stay on the existing TanStack `useLiveQuery`; no new query primitive is
+* needed.
+*
+* `pending` is ref-counted across overlapping invocations of THIS handle, so it
+* clears only once every concurrent call has settled.
+*/
+declare const createMutator: <TArgs = Record<string, unknown>>(handle: MutatorHandle<TArgs>) => MutatorHook<TArgs>;
+/** 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 CreatePaginatedQueryOptions {
+  /** Page size for the first page (and the default for `loadMore`). */
+  initialNumItems: number;
+  shardKey?: string;
+}
+interface CreatePaginatedQueryResult<T> {
+  /** `true` while the first page or a `loadMore` page is in flight. */
+  isLoading: Accessor<boolean>;
+  /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
+  loadMore: (numberItems: number) => void;
+  /** Flattened items across every loaded page, in order. */
+  results: Accessor<T[]>;
+  status: Accessor<PaginationStatus>;
+}
+interface CreateInfiniteQueryOptions {
+  /** Page size for the first page (and the default for `fetchNextPage`). */
+  initialNumItems: number;
+  shardKey?: string;
+}
+interface CreateInfiniteQueryResult<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: Accessor<boolean>;
+  /** `true` while a `fetchNextPage` page (beyond the first) is in flight. */
+  isFetchingNextPage: Accessor<boolean>;
+  /** `true` while the first page is in flight. */
+  isLoading: Accessor<boolean>;
+  /** One inner array per loaded page, in order; unresolved pages are omitted. */
+  pages: Accessor<T[][]>;
+  status: Accessor<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`. `loadMore` appends the next
+* page off the open-ended tail's `continueCursor`; it is a no-op unless
+* `status === "CanLoadMore"`.
+*
+* Call inside a reactive context (component / `createRoot`).
+*/
+declare const createPaginatedQuery: <F extends FunctionReference>(function_: F, args: "skip" | Accessor<"skip" | PaginatedArgs<F>> | PaginatedArgs<F>, options: CreatePaginatedQueryOptions) => CreatePaginatedQueryResult<PageItemOf<F>>;
+/**
+* Subscribe to a reactively-paginated query and expose its pages discretely.
+*
+* Shares `createPaginatedQuery`'s pagination engine but keeps each page as its
+* own inner array (TanStack-Query-style `fetchNextPage` / `hasNextPage` shape).
+*
+* Call inside a reactive context (component / `createRoot`).
+*/
+declare const createInfiniteQuery: <F extends FunctionReference>(function_: F, args: "skip" | Accessor<"skip" | PaginatedArgs<F>> | PaginatedArgs<F>, options: CreateInfiniteQueryOptions) => CreateInfiniteQueryResult<PageItemOf<F>>;
+/**
+* `createPresence` — collaborative-awareness primitive, 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 a reactive context (component / `createRoot`).
+*/
+/**
+* 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 CreatePresenceOptions<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 CreatePresenceResult<L extends ListPresentReference> {
+  /** The present members for the room. `undefined` until the first push. */
+  present: () => 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 createPresence: <H extends HeartbeatReference, L extends ListPresentReference>(roomId: string, options: CreatePresenceOptions<H, L>) => CreatePresenceResult<L>;
+interface CreateQueryOptions {
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+/**
+* Subscribe to a server query and return a reactive accessor of its value.
+*
+* The accessor reads `undefined` until the first server frame lands, then
+* updates on every delta the WebSocket pushes — Solid's fine-grained signals
+* mean only the components that read the accessor re-render, which maps cleanly
+* onto Lunora's per-subscription delta model.
+*
+* `args` may be a plain value or an accessor; passing an accessor makes the
+* subscription reactive — when the args change the old subscription is torn down
+* (via `onCleanup`) and a fresh one opens for the new args. Pass `"skip"` (or an
+* accessor returning `"skip"`) to short-circuit: no network call, no socket.
+*
+* ```tsx
+* const messages = createQuery(api.messages.list, () => ({ channelId: channelId() }));
+* return &lt;For each={messages()?.messages}>{(m) => &lt;li>{m.text}&lt;/li>}&lt;/For>;
+* ```
+*/
+declare const createQuery: <F extends FunctionReference>(function_: F, args: (ArgsOf<F> | "skip") | Accessor<ArgsOf<F> | "skip">, options?: CreateQueryOptions) => Accessor<ReturnOf<F> | undefined>;
+interface CreateRateLimitOptions {
+  /** Clock injection for tests. Defaults to `Date.now`. */
+  now?: () => number;
+  /**
+  * Re-evaluation cadence in milliseconds while throttled, so `retryAfter`
+  * ticks down and `disabled` flips back automatically. Defaults to `1000`.
+  */
+  tickMs?: number;
+}
+interface CreateRateLimitResult {
+  /** 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;
+  /** Signal: `true` while a single unit cannot be consumed. */
+  disabled: () => boolean;
+  /** Signal: `true` while a single unit can be consumed. */
+  ok: () => boolean;
+  /** Clear local accounting (e.g. after the server confirms a reset). */
+  reset: () => void;
+  /** Signal: milliseconds until the next unit is available. `0` when `ok`. */
+  retryAfter: () => 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` is read on every call; pass a stable reference (module constant) so
+* the derived memos stay settled.
+*/
+declare const createRateLimit: (config: RateLimitConfig, options?: CreateRateLimitOptions) => CreateRateLimitResult;
+interface CreateSubscriptionResult<T> {
+  data: Accessor<T | undefined>;
+  error: Accessor<Error | undefined>;
+}
+/**
+* Subscribe to a reactive server push stream. Returns `{ data, error }`
+* accessors that update whenever the server emits. Passing `"skip"` as `args`
+* (or an accessor that resolves to `"skip"`) tears down the subscription.
+*/
+declare const createSubscription: <F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip" | Accessor<ArgsOf<F> | "skip">, options?: {
+  shardKey?: string;
+}) => CreateSubscriptionResult<ReturnOf<F>>;
+/**
+* Hydrate a query from a {@link Preloaded} token produced by `preloadQuery`
+* during SSR, then keep it live.
+*
+* This is the client half of PLAN4's "your loaders are live" handoff. The
+* returned accessor is seeded **synchronously** from `preloaded.value`, so the
+* very first read — during hydration — returns the server-rendered value with
+* no loading flash and no `Suspense` fallback (unlike `createResource`, which
+* always starts pending). After the component mounts, a WebSocket subscription
+* attaches in an effect and every subsequent server delta flows into the same
+* signal, so the UI goes live with zero refetch.
+*
+* ```tsx
+* // route loader (server): const preloaded = await preloadQuery(client, api.messages.list, args);
+* const messages = hydratePreloaded(preloaded); // seeded from SSR, then live
+* return &lt;pre>{JSON.stringify(messages())}&lt;/pre>;
+* ```
+*
+* Effects do not run on the server during SSR (Solid only runs them after
+* hydration), so the subscription is strictly client-side — the seed is the
+* only value the server render ever sees.
+*/
+declare const hydratePreloaded: <T>(preloaded: Preloaded<T>) => Accessor<T>;
+interface LunoraProviderProps {
+  children: JSX.Element;
+  /**
+  * The framework-neutral transport. Build it once at the app root with
+  * `new LunoraClient({ url })` (or `createServerClient` during SSR) and pass
+  * it here — the provider does not own its lifecycle, so the same instance
+  * survives across route navigations.
+  */
+  client: LunoraClient;
+}
+/**
+* Provides a {@link LunoraClient} to the Solid tree via {@link LunoraContext}.
+*
+* Solid's context is reactive-graph scoped rather than render scoped, so unlike
+* the React provider there is no QueryClient to detect or lazily create — the
+* adapter's reactive primitives (`createQuery`, `createMutation`,
+* `hydratePreloaded`) own their own signals and read the client straight from
+* context. Drop one of these at the root of your app:
+*
+* ```tsx
+* const client = new LunoraClient({ url: window.location.origin });
+*
+* render(() => (
+*     &lt;LunoraProvider client={client}>
+*         &lt;App />
+*     &lt;/LunoraProvider>
+* ), root);
+* ```
+*/
+declare const LunoraProvider: (props: LunoraProviderProps) => JSX.Element;
+export { AuthLoading, Authenticated, type CreateInfiniteQueryOptions, type CreateInfiniteQueryResult, type CreatePaginatedQueryOptions, type CreatePaginatedQueryResult, type CreatePresenceOptions, type CreatePresenceResult, type CreateQueryOptions, type CreateRateLimitOptions, type CreateRateLimitResult, type CreateSubscriptionResult, type FlagContext, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraContext, LunoraProvider, type LunoraProviderProps, type MutationClient, type MutationHandle, type MutatorHook, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, createAuth, createConnectionStatus, createFlag, createFlags, createInfiniteQuery, createMutation, createMutationForClient, createMutator, createPaginatedQuery, createPresence, createQuery, createRateLimit, createSubscription, hydratePreloaded, useLunora };