syncorejs 0.2.1 → 0.2.3

package/dist/_vendor/react/index.d.ts

@@ -1,20 +1,64 @@
 import { ReactNode } from "react";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
-import { FunctionReference, SyncoreClient } from "../core/index.d.mts";
+import { FunctionArgs, FunctionReference, FunctionResult, PaginationOptions, PaginationResult, SyncoreClient, SyncoreQueryState, SyncoreRuntimeStatus, UsePaginatedQueryResult } from "../core/index.d.mts";
 
 //#region src/index.d.ts
 type OptionalArgsTuple<TArgs> = Record<never, never> extends TArgs ? [args?: TArgs] : [args: TArgs];
+type QueryRequestInput<TReference extends FunctionReference<"query"> = FunctionReference<"query">> = Record<never, never> extends FunctionArgs<TReference> ? {
+  query: TReference;
+  args?: FunctionArgs<TReference> | Skip;
+} : {
+  query: TReference;
+  args: FunctionArgs<TReference> | Skip;
+};
+type QueriesRequestInput = Record<string, QueryRequestInput>;
+type QueryStateForEntry<TEntry> = TEntry extends QueryRequestInput<infer TReference> ? SyncoreQueryState<FunctionResult<TReference>> : never;
+type UseQueriesResult<TEntries extends QueriesRequestInput> = { [TKey in keyof TEntries]: QueryStateForEntry<TEntries[TKey]> };
+type PaginatedQueryReference = FunctionReference<"query", Record<string, unknown>, PaginationResult<unknown>>;
+type PaginatedQueryArgs<TReference extends FunctionReference<"query">> = FunctionArgs<TReference> extends {
+  paginationOpts: PaginationOptions;
+} ? Omit<FunctionArgs<TReference>, "paginationOpts"> : never;
+type PaginatedQueryItem<TReference extends FunctionReference<"query">> = FunctionResult<TReference> extends PaginationResult<infer TItem> ? TItem : never;
 /**
- * Pass `"skip"` as the args argument to `useQuery` to suppress the subscription
- * entirely and return `undefined` without contacting the runtime.
+ * Pass `skip` as the `args` argument to any Syncore React hook to suppress
+ * that subscription entirely.
+ *
+ * Useful when the query arguments depend on state that is not yet available
+ * (e.g. a selected item ID) — instead of conditionally calling the hook
+ * (which violates the Rules of Hooks), pass `skip` to deactivate it:
+ *
+ * ```tsx
+ * const task = useQuery(api.tasks.get, selectedId ? { id: selectedId } : skip);
+ * // task is `undefined` while selectedId is null/undefined
+ * ```
+ *
+ * Skipped queries return `undefined` for `data`, `"skipped"` for `status`,
+ * and `false` for `isLoading`.
  */
 declare const skip: "skip";
 type Skip = typeof skip;
 /**
- * Provide a Syncore client to React descendants.
+ * Provides a Syncore client to all React descendants via context.
+ *
+ * Wrap your app (or any subtree that uses Syncore hooks) with
+ * `SyncoreProvider`. All `useQuery`, `useMutation`, `useAction`, and
+ * `useQueries` calls inside the tree will automatically use the client you
+ * supply.
+ *
+ * ```tsx
+ * // For a browser worker setup
+ * const client = createBrowserWorkerClient();
  *
- * Wrap your app with this component to use Syncore hooks like `useQuery` and
- * `useMutation`.
+ * function App() {
+ *   return (
+ *     <SyncoreProvider client={client}>
+ *       <TaskList />
+ *     </SyncoreProvider>
+ *   );
+ * }
+ * ```
+ *
+ * For Next.js apps use `SyncoreNextProvider` which also handles service worker
+ * and worker URL configuration.
  */
 declare function SyncoreProvider({
   client,
@@ -22,37 +66,192 @@ declare function SyncoreProvider({
 }: {
   client: SyncoreClient;
   children: ReactNode;
-}): react_jsx_runtime0.JSX.Element;
+}): import("react/jsx-runtime").JSX.Element;
 /**
- * Read the active Syncore client from React context.
+ * Returns the active `SyncoreClient` from the nearest {@link SyncoreProvider}
+ * in the React tree.
+ *
+ * Throws if called outside of a `SyncoreProvider`. Prefer the higher-level
+ * hooks (`useQuery`, `useMutation`, etc.) for common operations — use
+ * `useSyncore` only when you need direct access to the client object.
  *
- * Throws if used outside of {@link SyncoreProvider}.
+ * ```ts
+ * const client = useSyncore();
+ * const tasks = await client.query(api.tasks.list);
+ * ```
  */
 declare function useSyncore(): SyncoreClient;
 /**
- * Load a reactive Syncore query within a React component.
+ * Subscribe to the runtime’s lifecycle status.
+ *
+ * Returns a {@link SyncoreRuntimeStatus} that updates whenever the underlying
+ * runtime changes state (e.g. starting, ready, error). Use it to gate your UI
+ * on the runtime being ready or to display an error boundary:
+ *
+ * ```tsx
+ * function TaskList() {
+ *   const status = useSyncoreStatus();
+ *   if (status.kind === "starting") return <Spinner />;
+ *   if (status.kind === "error")    return <ErrorScreen error={status.error} />;
+ *   return <Tasks />;
+ * }
+ * ```
+ *
+ * Most components do not need this — `useQuery` already incorporates runtime
+ * status into the `SyncoreQueryState.runtimeStatus` field.
+ */
+declare function useSyncoreStatus(): SyncoreRuntimeStatus;
+/**
+ * Subscribe to a reactive Syncore query and return the current data.
+ *
+ * The component re-renders automatically whenever the query result changes.
+ * If the query throws, `useQuery` re-throws the error so a React error
+ * boundary can catch it — use {@link useQueryState} if you need to handle
+ * errors inline.
+ *
+ * ```tsx
+ * // Basic usage
+ * const tasks = useQuery(api.tasks.list);
+ *
+ * // With arguments
+ * const task = useQuery(api.tasks.get, { id: taskId });
  *
- * The hook subscribes automatically and re-renders whenever the local query
- * result changes. Pass `"skip"` as the second argument to suppress the
- * subscription entirely and return `undefined` without contacting the runtime.
+ * // Conditionally skip when arguments are not yet available
+ * const task = useQuery(api.tasks.get, taskId ? { id: taskId } : skip);
+ * ```
+ *
+ * @param reference - A typed function reference (from the generated `api` object).
+ * @param args      - The query’s arguments, or `skip` to suppress the subscription.
+ * @returns The current query result, or `undefined` while loading.
  */
 declare function useQuery<TArgs, TResult>(reference: FunctionReference<"query", TArgs, TResult>, ...args: OptionalArgsTuple<TArgs> | [Skip]): TResult | undefined;
 /**
- * Construct a stable function that executes a Syncore mutation.
+ * Subscribe to a reactive Syncore query and return the full
+ * {@link SyncoreQueryState} including loading, error, and runtime status.
+ *
+ * Use this instead of {@link useQuery} when you need to:
+ * - Differentiate between `undefined` data and an error.
+ * - React to `isLoading` / `isError` without relying on error boundaries.
+ * - Inspect `runtimeStatus` for the underlying runtime’s health.
+ *
+ * ```tsx
+ * const { data, isLoading, isError, error } = useQueryState(api.tasks.list);
+ *
+ * if (isLoading) return <Spinner />;
+ * if (isError)   return <ErrorBanner message={error.message} />;
+ * return <TaskList tasks={data} />;
+ * ```
+ */
+declare function useQueryState<TArgs, TResult>(reference: FunctionReference<"query", TArgs, TResult>, ...args: OptionalArgsTuple<TArgs> | [Skip]): SyncoreQueryState<TResult>;
+/**
+ * Returns a stable callback for executing a Syncore mutation.
+ *
+ * The returned function is type-safe: its parameter types are inferred from
+ * the mutation definition and remain stable across re-renders (no need to
+ * wrap in `useCallback`).
+ *
+ * ```tsx
+ * const createTask = useMutation(api.tasks.create);
+ *
+ * return (
+ *   <button onClick={() => createTask({ title: "New task" })}>
+ *     Add task
+ *   </button>
+ * );
+ * ```
+ *
+ * @param reference - A typed mutation reference from the generated `api` object.
+ * @returns A function that, when called, executes the mutation and returns a
+ *   promise that resolves to the mutation’s return value.
  */
 declare function useMutation<TArgs, TResult>(reference: FunctionReference<"mutation", TArgs, TResult>): (...args: OptionalArgsTuple<TArgs>) => Promise<TResult>;
 /**
- * Construct a stable function that executes a Syncore action.
+ * Returns a stable callback for executing a Syncore action.
+ *
+ * Identical to {@link useMutation} but for actions. Use this when the work you
+ * need to do cannot run inside a transaction (external API calls, long-running
+ * tasks, etc.).
+ *
+ * ```tsx
+ * const importTasks = useAction(api.tasks.importFromCsv);
+ *
+ * return (
+ *   <button onClick={() => importTasks({ url: csvUrl })}>
+ *     Import
+ *   </button>
+ * );
+ * ```
+ *
+ * @param reference - A typed action reference from the generated `api` object.
+ * @returns A function that, when called, executes the action and returns a
+ *   promise that resolves to the action’s return value.
  */
 declare function useAction<TArgs, TResult>(reference: FunctionReference<"action", TArgs, TResult>): (...args: OptionalArgsTuple<TArgs>) => Promise<TResult>;
 /**
- * Load several Syncore queries at once using explicit keys.
+ * Subscribe to multiple Syncore queries simultaneously and receive per-entry
+ * state objects in a single hook call.
+ *
+ * More efficient than calling `useQuery` in a loop when the set of queries is
+ * known at component render time. The hook maintains only one subscription per
+ * unique `(reference, args)` combination even if entries are duplicated.
+ *
+ * ```tsx
+ * const { header, sidebar } = useQueries({
+ *   header:  { query: api.layout.header },
+ *   sidebar: { query: api.layout.sidebar, args: { userId } },
+ * });
+ *
+ * if (header.isLoading || sidebar.isLoading) return <Spinner />;
+ * ```
+ *
+ * @param entries - A record of named query requests. Each entry can include
+ *   `args: skip` to suppress that specific subscription.
+ * @returns A record with the same keys, each holding a {@link SyncoreQueryState}.
+ */
+declare function useQueries<TEntries extends QueriesRequestInput>(entries: TEntries): UseQueriesResult<TEntries>;
+/**
+ * Subscribe to a paginated Syncore query, incrementally loading more pages.
+ *
+ * The query must accept a `paginationOpts` argument and return a
+ * `PaginationResult`. The hook manages cursors automatically — call the
+ * returned `loadMore` function to append the next page to the results.
+ *
+ * ```tsx
+ * const { results, status, loadMore, hasMore } = usePaginatedQuery(
+ *   api.tasks.list,
+ *   { projectId },
+ *   { initialNumItems: 20 },
+ * );
+ *
+ * return (
+ *   <>
+ *     {results.map((t) => <TaskRow key={t._id} task={t} />)}
+ *     {hasMore && (
+ *       <button
+ *         onClick={() => loadMore(20)}
+ *         disabled={status === "loadingMore"}
+ *       >
+ *         Load more
+ *       </button>
+ *     )}
+ *   </>
+ * );
+ * ```
+ *
+ * Pass `skip` as `args` to suppress the subscription until arguments are
+ * ready.
+ *
+ * @param reference          - A typed query reference whose handler calls
+ *   `ctx.db.query(…).paginate(paginationOpts)`.
+ * @param args               - Arguments for the query (excluding
+ *   `paginationOpts`, which is managed internally), or `skip`.
+ * @param options.initialNumItems - Number of items to load on the first page.
+ * @returns A {@link UsePaginatedQueryResult} with the accumulated results and
+ *   a `loadMore` callback.
  */
-declare function useQueries<TResult>(entries: Array<{
-  key: string;
-  reference: FunctionReference<"query">;
-  args?: Record<string, unknown>;
-}>): Record<string, TResult | undefined>;
+declare function usePaginatedQuery<TReference extends PaginatedQueryReference>(reference: TReference, args: PaginatedQueryArgs<TReference> | Skip, options: {
+  initialNumItems: number;
+}): UsePaginatedQueryResult<PaginatedQueryItem<TReference>>;
 //#endregion
-export { SyncoreProvider, skip, useAction, useMutation, useQueries, useQuery, useSyncore };
+export { SyncoreProvider, UseQueriesResult, skip, useAction, useMutation, usePaginatedQuery, useQueries, useQuery, useQueryState, useSyncore, useSyncoreStatus };
 //# sourceMappingURL=index.d.ts.map

package/dist/_vendor/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.tsx"],"mappings":";;;;;KAkBK,iBAAA,UACH,MAAA,uBAA6B,KAAA,IAAS,IAAA,GAAO,KAAA,KAAU,IAAA,EAAM,KAAA;;;AAPxC;;cAaV,IAAA;AAAA,KACR,IAAA,UAAc,IAAA;;;;;;;iBAUH,eAAA,CAAA;EACd,MAAA;EACA;AAAA;EAEA,MAAA,EAAQ,aAAA;EACR,QAAA,EAAU,SAAA;AAAA,IACX,kBAAA,CAAA,GAAA,CAAA,OAAA;;;;;AAjBD;iBA4BgB,UAAA,CAAA,GAAc,aAAA;;;;AA5BM;;;;iBA2CpB,QAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,UAA2B,KAAA,EAAO,OAAA,MAC1C,IAAA,EAAM,iBAAA,CAAkB,KAAA,KAAU,IAAA,IACpC,OAAA;AAnCH;;;AAAA,iBAgFgB,WAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,aAA8B,KAAA,EAAO,OAAA,QAC3C,IAAA,EAAM,iBAAA,CAAkB,KAAA,MAAW,OAAA,CAAQ,OAAA;;;;iBAQlC,SAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,WAA4B,KAAA,EAAO,OAAA,QACzC,IAAA,EAAM,iBAAA,CAAkB,KAAA,MAAW,OAAA,CAAQ,OAAA;;;;iBAQlC,UAAA,SAAA,CACd,OAAA,EAAS,KAAA;EACP,GAAA;EACA,SAAA,EAAW,iBAAA;EACX,IAAA,GAAO,MAAA;AAAA,KAER,MAAA,SAAe,OAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.tsx"],"mappings":";;;;KA0BK,iBAAA,UACH,MAAA,uBAA6B,KAAA,IAAS,IAAA,GAAO,KAAA,KAAU,IAAA,EAAM,KAAA;AAAA,KAE1D,iBAAA,oBACgB,iBAAA,YAA6B,iBAAA,aAC9C,MAAA,uBAA6B,YAAA,CAAa,UAAA;EAExC,KAAA,EAAO,UAAA;EACP,IAAA,GAAO,YAAA,CAAa,UAAA,IAAc,IAAA;AAAA;EAGlC,KAAA,EAAO,UAAA;EACP,IAAA,EAAM,YAAA,CAAa,UAAA,IAAc,IAAA;AAAA;AAAA,KAGlC,mBAAA,GAAsB,MAAM,SAAS,iBAAA;AAAA,KAErC,kBAAA,WAA6B,MAAA,SAAe,iBAAA,qBAG7C,iBAAA,CAAkB,cAAA,CAAe,UAAA;AAAA,KAGzB,gBAAA,kBAAkC,mBAAA,qBAC7B,QAAA,GAAW,kBAAA,CAAmB,QAAA,CAAS,IAAA;AAAA,KAGnD,uBAAA,GAA0B,iBAAA,UAE7B,MAAA,mBACA,gBAAA;AAAA,KAGG,kBAAA,oBAAsC,iBAAA,aACzC,YAAA,CAAa,UAAA;EAAsB,cAAA,EAAgB,iBAAA;AAAA,IAC/C,IAAA,CAAK,YAAA,CAAa,UAAA;AAAA,KAGnB,kBAAA,oBAAsC,iBAAA,aACzC,cAAA,CAAe,UAAA,UAAoB,gBAAA,gBAC/B,KAAA;;AAvC8D;AAAA;;;;;;;;;;;;;;cAuFvD,IAAA;AAAA,KACR,IAAA,UAAc,IAAI;;;;;;;;;;;;;;;;;;;;;;AA7EoB;AAAA;;iBA8G3B,eAAA,CAAA;EACd,MAAA;EACA;AAAA;EAEA,MAAA,EAAQ,aAAA;EACR,QAAA,EAAU,SAAA;AAAA,gCACX,GAAA,CAAA,OAAA;;;;;;;;;;;;;;iBAmBe,UAAA,CAAA,GAAc,aAAa;;;;AA/HI;AAG/C;;;;;;;;;;;;;;;iBAuJgB,gBAAA,CAAA,GAAoB,oBAAoB;;;AAtJI;AAC1D;;;;;;;;;;;;AAKgB;AAAA;;;;;;;iBAmMF,QAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,UAA2B,KAAA,EAAO,OAAA,MAC1C,IAAA,EAAM,iBAAA,CAAkB,KAAA,KAAU,IAAA,IACpC,OAAA;;;;;;;;;;;;;;;AAjM+B;AAAA;;iBA0NlB,aAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,UAA2B,KAAA,EAAO,OAAA,MAC1C,IAAA,EAAM,iBAAA,CAAkB,KAAA,KAAU,IAAA,IACpC,iBAAA,CAAkB,OAAA;;;;;;;;;;;;;;;AAxNV;AAgDX;;;;AAAmC;AAAC;iBA4NpB,WAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,aAA8B,KAAA,EAAO,OAAA,QAC3C,IAAA,EAAM,iBAAA,CAAkB,KAAA,MAAW,OAAA,CAAQ,OAAA;;;AA7N3B;AAiCvB;;;;;;;;;;;;;;;;;;iBAsNgB,SAAA,gBAAA,CACd,SAAA,EAAW,iBAAA,WAA4B,KAAA,EAAO,OAAA,QACzC,IAAA,EAAM,iBAAA,CAAkB,KAAA,MAAW,OAAA,CAAQ,OAAA;;AAlNjD;AAmBD;;;;AAA2C;AA2B3C;;;;AAAwD;AAmDxD;;;;;;;;;iBA2IgB,UAAA,kBAA4B,mBAAA,CAAA,CAC1C,OAAA,EAAS,QAAA,GACR,gBAAA,CAAiB,QAAA;;;;;;;;;;;;;;;AA1IV;AAyBV;;;;;;;;;;;;;;;;;;;;;;;;;iBA8MgB,iBAAA,oBAAqC,uBAAA,CAAA,CACnD,SAAA,EAAW,UAAA,EACX,IAAA,EAAM,kBAAA,CAAmB,UAAA,IAAc,IAAA,EACvC,OAAA;EACE,eAAA;AAAA,IAED,uBAAA,CAAwB,kBAAA,CAAmB,UAAA"}