@korajs/react 1.0.0-beta.11 → 1.0.0-beta.13

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { KoraAppLike as KoraAppLike$1, KoraContextValue as KoraContextValue$1, UseMutationOptions as UseMutationOptions$1, UseMutationResultBase, UseQueryOptions as UseQueryOptions$1, AuthSyncBinding, AuthSyncState } from '@korajs/core/bindings';
+import { KoraAppLike as KoraAppLike$1, KoraContextValue as KoraContextValue$1, UseQueryOptions as UseQueryOptions$1, UseMutationOptions as UseMutationOptions$1, UseMutationResultBase, AuthSyncBinding, AuthSyncState } from '@korajs/core/bindings';
 import { Store, QueryStoreCache, CollectionRecord, QueryBuilder, CollectionAccessor } from '@korajs/store';
 import { SyncEngine, CursorInfo, SyncStatusInfo, AwarenessUser, AwarenessState } from '@korajs/sync';
 import { ReactNode } from 'react';
@@ -6,7 +6,24 @@ import * as Y from 'yjs';
 
 type KoraAppLike = KoraAppLike$1<Store, SyncEngine, QueryStoreCache>;
 type KoraContextValue = KoraContextValue$1<Store, SyncEngine, QueryStoreCache>;
-type UseQueryOptions = UseQueryOptions$1;
+/** Options for {@link useQuery} and {@link useQueryState}. */
+interface UseQueryOptions extends UseQueryOptions$1 {
+    /**
+     * When true (default), `useQuery` throws a failed query to the nearest error
+     * boundary. When false it keeps returning the last good rows; read the error with
+     * `useQueryState`. Ignored by `useQueryState`, which always returns the error.
+     */
+    throwOnError?: boolean;
+}
+/** Result of `useQueryState`. */
+interface UseQueryStateResult<T> {
+    /** The current rows (the last good rows while `error` is set). */
+    data: readonly T[];
+    /** The query's failure, or null. Cleared when results flow again. */
+    error: Error | null;
+    /** False until the first result for the current query arrived (always false on the server). */
+    ready: boolean;
+}
 type UseMutationOptions<TData, TArgs extends unknown[], TContext = void> = UseMutationOptions$1<TData, TArgs, TContext>;
 /**
  * Props for the KoraProvider component.
@@ -53,15 +70,44 @@ interface AuthBoundKoraProviderProps {
         close(): Promise<void>;
     };
     signedOut?: ReactNode;
+    /**
+     * Rendered instead of the app while the session is locked (offline longer
+     * than the auth client's `maxOfflineGraceMs`, or the device clock moved
+     * backwards). The app and its local data stay open underneath; nothing is
+     * wiped. Defaults to `signedOut`.
+     */
+    locked?: ReactNode;
     fallback?: ReactNode;
+    error?: (context: AuthBoundKoraErrorContext) => ReactNode;
     children?: ReactNode;
 }
+interface AuthBoundKoraSession {
+    /** The authenticated identity only. Access tokens are deliberately omitted. */
+    userId: string;
+}
+interface AuthBoundKoraInitializationError {
+    /** Stable Kora/DOM error code suitable for application-owned copy and recovery UI. */
+    code: string;
+    name: string;
+    message: string;
+    /** Sanitized primitive metadata. Credential-shaped keys are always removed. */
+    metadata: Readonly<Record<string, string | number | boolean | null>>;
+    /** Sanitized Error for logging; custom credential-bearing properties are omitted. */
+    cause: Error;
+}
+interface AuthBoundKoraErrorContext {
+    error: AuthBoundKoraInitializationError;
+    retry(): void;
+    session: AuthBoundKoraSession;
+}
+/** Classify initialization failures without requiring applications to parse copy. */
+declare function classifyKoraInitializationError(error: unknown): AuthBoundKoraInitializationError;
 /**
  * Owns the security-sensitive app lifetime for shared-browser applications.
  * The previous app is fully closed before a different user's app is created,
  * and no stale provider tree is rendered across that boundary.
  */
-declare function AuthBoundKoraProvider({ authClient, createApp, signedOut, fallback, children, }: AuthBoundKoraProviderProps): ReactNode;
+declare function AuthBoundKoraProvider({ authClient, createApp, signedOut, locked, fallback, error: renderError, children, }: AuthBoundKoraProviderProps): ReactNode;
 
 /**
  * React hook that returns the Kora app instance from context.
@@ -88,19 +134,137 @@ declare function useApp<T extends KoraAppLike = KoraAppLike>(): T;
 
 /**
  * React hook for reactive queries against the local Kora store.
+ *
+ * Returns the current rows synchronously (no loading state for local data) and
+ * re-renders only when the result set changes. The array keeps its identity while
+ * the result is unchanged. On the server (`renderToString`, Next.js App Router) and
+ * during hydration it returns `[]`; the rows arrive right after hydration.
+ *
+ * A query that fails (for example a where/orderBy on an unknown field) is thrown to
+ * the nearest React error boundary, so the failure is visible instead of an empty
+ * list. Pass `throwOnError: false`, or use {@link useQueryState}, to handle it inline.
+ *
+ * @param query - A query builder, for example `app.todos.where({ completed: false })`
+ * @param options - `enabled` (default true) and `throwOnError` (default true)
+ * @returns The current result rows
+ *
+ * @example
+ * ```tsx
+ * const todos = useQuery(app.todos.where({ completed: false }).orderBy('createdAt'))
+ * ```
  */
 declare function useQuery<T = CollectionRecord>(query: QueryBuilder<T>, options?: UseQueryOptions): readonly T[];
+/**
+ * Like {@link useQuery}, but returns the error instead of throwing it.
+ *
+ * @param query - A query builder
+ * @param options - `enabled` (default true); `throwOnError` is ignored
+ * @returns `{ data, error, ready }`, the same object until one of them changes.
+ *   `ready` is false until the first result for the current query has arrived.
+ *
+ * @example
+ * ```tsx
+ * const { data: todos, error } = useQueryState(app.todos.where({ completed: false }))
+ * if (error) return <p role="alert">{error.message}</p>
+ * ```
+ */
+declare function useQueryState<T = CollectionRecord>(query: QueryBuilder<T>, options?: UseQueryOptions): UseQueryStateResult<T>;
 
 /**
  * React hook for performing mutations against the local Kora store.
+ *
+ * `mutate`, `mutateAsync` and `reset` keep their identity for the component's lifetime
+ * (safe in effect deps and as memoized props), and the result object only changes when
+ * `isLoading` or `error` does. The latest `mutationFn` and `options` are always used.
+ *
+ * @param mutationFn - The mutation to run, for example `app.todos.insert`
+ * @param options - Optional lifecycle callbacks (`onMutate`, `onSuccess`, `onError`, `onSettled`)
+ * @returns `{ mutate, mutateAsync, isLoading, error, reset }`
+ *
+ * @example
+ * ```tsx
+ * const { mutate: addTodo, isLoading } = useMutation(app.todos.insert)
+ * return <button disabled={isLoading} onClick={() => addTodo({ title: 'New' })}>Add</button>
+ * ```
  */
 declare function useMutation<TData, TArgs extends unknown[], TContext = void>(mutationFn: (...args: TArgs) => Promise<TData>, options?: UseMutationOptions<TData, TArgs, TContext>): UseMutationResult<TData, TArgs>;
 
 /**
  * React hook for monitoring the sync engine's connection status.
+ *
+ * Re-renders only when the status payload changes. The returned object, and its nested
+ * `heldNodes`, `initialSync` and `blockedFailure` values, keep their identity while
+ * unchanged, so they are safe as effect or memo dependencies. Beyond `status` and
+ * `pendingOperations` it reports `heldOperations` / `heldNodes` (writes of another
+ * user waiting on this device), `localDurability` (`'degraded'` when the local
+ * database cannot persist) and `serverProtocolVersion` / `protocolDeprecated`.
+ *
+ * @returns The current {@link SyncStatusInfo}
+ *
+ * @example
+ * ```tsx
+ * const { status, pendingOperations, localDurability } = useSyncStatus()
+ * ```
  */
 declare function useSyncStatus(): SyncStatusInfo;
 
+/**
+ * The collections an app exposes, read from its `collections` namespace. Purely
+ * structural, so it follows whatever accessor types `createApp` infers from the schema.
+ */
+type AppCollections<TApp> = TApp extends {
+    collections: infer C;
+} ? C : never;
+/** The collection names of an app, as string literals. */
+type AppCollectionName<TApp> = Extract<keyof AppCollections<TApp>, string>;
+/** The record type of a collection accessor, inferred from what its queries return. */
+type AccessorRecord<TAccessor> = TAccessor extends {
+    where(...args: never[]): QueryBuilder<infer R>;
+} ? R : CollectionRecord;
+/** The record type of collection `N` of an app. */
+type AppRecord<TApp, N extends AppCollectionName<TApp>> = AccessorRecord<AppCollections<TApp>[N]>;
+/**
+ * Hooks bound to one app type, returned by {@link createKoraHooks}.
+ */
+interface KoraHooks<TApp> {
+    /** The app from the nearest `<KoraProvider app={app}>`, typed as `TApp`. */
+    useApp: () => TApp;
+    /**
+     * The typed accessor of one collection: `insert`, `update` and `where` are checked
+     * against the schema. The accessor keeps its identity across renders.
+     */
+    useCollection: <N extends AppCollectionName<TApp>>(name: N) => AppCollections<TApp>[N];
+    /** {@link useQuery}: rows are typed from the query builder. */
+    useQuery: typeof useQuery;
+    /** {@link useQueryState}: rows are typed from the query builder. */
+    useQueryState: typeof useQueryState;
+    /** {@link useMutation}. */
+    useMutation: typeof useMutation;
+    /** {@link useSyncStatus}. */
+    useSyncStatus: typeof useSyncStatus;
+}
+/**
+ * Creates React hooks typed for one app, so components get schema-checked
+ * collection names, inserts, updates and rows without passing generics around.
+ * Call it once next to `createApp` and import the hooks from there. Nothing runs at
+ * call time; the hooks read the app from `<KoraProvider app={app}>`.
+ *
+ * @returns {@link KoraHooks} for `TApp`
+ *
+ * @example
+ * ```typescript
+ * // kora.ts
+ * export const app = createApp({ schema })
+ * export const { useCollection, useQuery, useMutation } = createKoraHooks<typeof app>()
+ *
+ * // TodoList.tsx
+ * const todos = useCollection('todos')          // 'todoz' is a type error
+ * const rows = useQuery(todos.where({ completed: false }))
+ * const { mutate: add } = useMutation(todos.insert)
+ * ```
+ */
+declare function createKoraHooks<TApp extends KoraAppLike>(): KoraHooks<TApp>;
+
 /**
  * React hook that returns a CollectionAccessor for the given collection name.
  * Convenience hook for accessing a collection without going through the store directly.
@@ -139,8 +303,11 @@ declare function usePresence(user: {
 /**
  * Returns all currently connected collaborators' awareness states.
  *
- * Excludes the local user — only returns remote peers.
+ * Excludes the local user — only returns remote peers. Safe under server rendering
+ * (`renderToString`, Next.js App Router): the server and the hydration pass see `[]`.
+ *
+ * @returns The remote peers' awareness states; the same array until they change
  */
 declare function useCollaborators(): AwarenessState[];
 
-export { AuthBoundKoraProvider, type AuthBoundKoraProviderProps, type KoraAppLike, type KoraContextValue, KoraProvider, type KoraProviderProps, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseRichTextOptions, type UseRichTextResult, useApp, useCollaborators, useCollection, useMutation, usePresence, useQuery, useRichText, useSyncStatus };
+export { type AccessorRecord, type AppCollectionName, type AppCollections, type AppRecord, type AuthBoundKoraErrorContext, type AuthBoundKoraInitializationError, AuthBoundKoraProvider, type AuthBoundKoraProviderProps, type AuthBoundKoraSession, type KoraAppLike, type KoraContextValue, type KoraHooks, KoraProvider, type KoraProviderProps, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseQueryStateResult, type UseRichTextOptions, type UseRichTextResult, classifyKoraInitializationError, createKoraHooks, useApp, useCollaborators, useCollection, useMutation, usePresence, useQuery, useQueryState, useRichText, useSyncStatus };