@hvakr/firestate 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1105 @@
+import * as react0 from "react";
+import React from "react";
+import { CollectionReference, DocumentReference, Firestore, QueryConstraint, WithFieldValue } from "firebase/firestore";
+import { ZodType, z } from "zod";
+
+//#region src/types.d.ts
+/**
+ * Deep partial type that works with Records and nested objects
+ */
+type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
+/**
+ * A generic object that can be stored in Firestore.
+ *
+ * Uses an `any` index signature (matching Firestore's own `DocumentData`) so
+ * that plain TypeScript interfaces — which lack an implicit index signature —
+ * can satisfy the constraint. Internal call sites cast through more specific
+ * types where needed.
+ */
+type FirestoreObject = Record<string, any>;
+/**
+ * Options for update operations
+ */
+interface UpdateOptions {
+  /** If false, prevents this update from being added to undo stack */
+  undoable?: boolean;
+  /** Group multiple updates into a single undo action */
+  undoGroupId?: string;
+}
+/**
+ * State of a document subscription
+ */
+interface DocumentState<T> {
+  /** Current merged state (local changes applied to sync state) */
+  data: T | undefined;
+  /** Whether initial data has loaded */
+  isLoading: boolean;
+  /** Whether there are pending local changes */
+  isSynced: boolean;
+  /** Error from listener, if any */
+  error: Error | undefined;
+}
+/**
+ * State of a collection subscription
+ */
+interface CollectionState<T> {
+  /** Current merged state keyed by document ID */
+  data: Record<string, T>;
+  /** Whether initial data has loaded */
+  isLoading: boolean;
+  /** Whether there are pending local changes */
+  isSynced: boolean;
+  /** Whether the collection has been activated (for lazy loading) */
+  isActive: boolean;
+  /** Error from listener, if any */
+  error: Error | undefined;
+}
+/**
+ * Document handle returned by useDocument hook
+ */
+interface DocumentHandle<T extends FirestoreObject> {
+  /** Current document data */
+  data: T | undefined;
+  /** Update the document with a partial diff */
+  update: (diff: WithFieldValue<DeepPartial<T>>, options?: UpdateOptions) => void;
+  /** Set the document data (creates or overwrites) */
+  set: (data: T, options?: UpdateOptions) => void;
+  /** Delete the document */
+  delete: (options?: UpdateOptions) => void;
+  /** Whether initial data is loading */
+  isLoading: boolean;
+  /** Whether all changes have synced to Firestore */
+  isSynced: boolean;
+  /** Force sync pending changes immediately */
+  sync: () => Promise<void>;
+  /** Error from listener, if any */
+  error: Error | undefined;
+  /**
+       * Firestore document reference. Undefined when the hook was called with
+       * `enabled: false` (no subscription was created).
+       */
+  ref: DocumentReference<T> | undefined;
+}
+/**
+ * Collection handle returned by useCollection hook
+ */
+interface CollectionHandle<T extends FirestoreObject> {
+  /** Current collection data keyed by document ID */
+  data: Record<string, T>;
+  /** Update one or more documents with partial diffs */
+  update: (diff: WithFieldValue<DeepPartial<Record<string, T>>>, options?: UpdateOptions) => void;
+  /**
+       * Add a new document to the collection. Either pass an explicit `id`, or
+       * omit it to have Firestore generate an auto-id (returned synchronously).
+       *
+       * Returns `undefined` if the mutation was dropped (read-only handle, or
+       * called before the first snapshot has arrived). Callers should narrow
+       * before using the id to navigate or persist references.
+       */
+  add: {
+    (id: string, data: Omit<T, "id">, options?: UpdateOptions): string | undefined;
+    (data: Omit<T, "id">, options?: UpdateOptions): string | undefined;
+  };
+  /** Remove a document from the collection */
+  remove: (id: string, options?: UpdateOptions) => void;
+  /** Whether initial data is loading */
+  isLoading: boolean;
+  /** Whether all changes have synced to Firestore */
+  isSynced: boolean;
+  /** Whether subscription is active (for lazy collections) */
+  isActive: boolean;
+  /** Activate a lazy subscription */
+  load: () => void;
+  /** Force sync pending changes immediately */
+  sync: () => Promise<void>;
+  /** Error from listener, if any */
+  error: Error | undefined;
+  /**
+       * Firestore collection reference. Undefined when the hook was called with
+       * `enabled: false` (no subscription was created).
+       */
+  ref: CollectionReference<T> | undefined;
+}
+/**
+ * An undo/redo action
+ */
+interface UndoAction {
+  /** Function to undo the change */
+  undo: () => Promise<void> | void;
+  /** Function to redo the change */
+  redo: () => Promise<void> | void;
+  /** Optional group ID for batching multiple actions */
+  groupId?: string;
+  /** Optional path/location context for navigation-aware undo */
+  path?: string;
+  /** Human-readable description of the action */
+  description?: string;
+}
+/**
+ * Undo manager state
+ */
+interface UndoManagerState {
+  /** Stack of actions that can be undone */
+  undoStack: readonly UndoAction[];
+  /** Stack of actions that can be redone */
+  redoStack: readonly UndoAction[];
+  /** Whether undo is available */
+  canUndo: boolean;
+  /** Whether redo is available */
+  canRedo: boolean;
+}
+/**
+ * Undo manager handle
+ */
+interface UndoManager extends UndoManagerState {
+  /** Perform undo */
+  undo: () => Promise<void>;
+  /** Perform redo */
+  redo: () => Promise<void>;
+  /** Push a new action onto the undo stack */
+  push: (action: UndoAction) => void;
+  /** Clear all undo/redo history */
+  clear: () => void;
+}
+/**
+ * Configuration for a document definition.
+ *
+ * `TData` is the document's TypeScript shape. Provide it explicitly, or let
+ * it be inferred from `schema` when using `defineDocument`.
+ */
+interface DocumentDefinition<TData extends FirestoreObject> {
+  /**
+       * Optional Zod schema. When provided, firestate runs `schema.parse(...)`
+       * on full-payload writes (`set`, `add`) as a **validation guard** — bad
+       * data throws at the call site, not after a Firestore round trip. The
+       * parsed result is discarded; firestate stores the caller's original
+       * object verbatim. That means schema transforms (`.transform`, `.coerce`,
+       * default values) are NOT applied to stored data — do transforms before
+       * calling `set`/`add`. Partial `update(diff)` calls are NOT validated
+       * because diffs commonly contain Firestore sentinels (`serverTimestamp()`,
+       * `arrayUnion`, etc.) that don't satisfy a strict schema.
+       */
+  schema?: ZodType<TData>;
+  /**
+       * Collection path. Either a static string (may include multiple `/`-
+       * separated segments) or a function that derives the path from route/
+       * params. Use the function form when the collection lives under a dynamic
+       * parent, e.g. `projects/{projectId}/revisions`.
+       */
+  collection: string | ((params: Record<string, string>) => string);
+  /** Document ID or function to derive it */
+  id: string | ((params: Record<string, string>) => string);
+  /** Debounce interval for autosave (ms), default 1000 */
+  autosave?: number;
+  /** Minimum loading indicator time (ms), default 0 */
+  minLoadTime?: number;
+  /** Whether this document is read-only */
+  readOnly?: boolean;
+  /** Retry on listener error */
+  retryOnError?: boolean;
+  /** Retry interval (ms), default 5000 */
+  retryInterval?: number;
+}
+/**
+ * Configuration for a collection definition.
+ *
+ * `TData` is the document shape for entries in this collection.
+ */
+interface CollectionDefinition<TData extends FirestoreObject> {
+  /**
+       * Optional Zod schema for documents in the collection. When provided,
+       * firestate runs `schema.parse(...)` on full-payload writes (`add`) as
+       * a validation guard and stores the caller's original object verbatim.
+       * Schema transforms are not applied to stored data — see
+       * {@link DocumentDefinition.schema} for the full contract.
+       */
+  schema?: ZodType<TData>;
+  /** Collection path (can include path segments) */
+  path: string | ((params: Record<string, string>) => string);
+  /** Debounce interval for autosave (ms), default 1000 */
+  autosave?: number;
+  /** Minimum loading indicator time (ms), default 0 */
+  minLoadTime?: number;
+  /** Whether this collection is read-only */
+  readOnly?: boolean;
+  /** Whether to lazy load (only subscribe when load() is called) */
+  lazy?: boolean;
+  /** Query constraints */
+  queryConstraints?: QueryConstraint[];
+  /** Retry the snapshot listener on transient errors */
+  retryOnError?: boolean;
+  /** Retry interval (ms), default 5000 */
+  retryInterval?: number;
+}
+/**
+ * Configuration for the Firestate store
+ */
+interface FirestateConfig {
+  /** Firestore instance */
+  firestore: Firestore;
+  /** Default autosave interval (ms), default 1000 */
+  autosave?: number;
+  /** Default minimum load time (ms), default 0 */
+  minLoadTime?: number;
+  /** Maximum undo stack length, default 20 */
+  maxUndoLength?: number;
+  /** Enable navigation-aware undo/redo */
+  enableNavigation?: boolean;
+  /** Custom error handler */
+  onError?: (error: Error, context: ErrorContext) => void;
+}
+/**
+ * Context for error handling
+ */
+interface ErrorContext {
+  type: "document" | "collection";
+  path: string;
+  operation: "read" | "write";
+}
+/**
+ * Subscriber callback type
+ */
+type Subscriber<T> = (state: T) => void;
+/**
+ * Unsubscribe function
+ */
+type Unsubscribe = () => void;
+//#endregion
+//#region src/schema.d.ts
+/**
+ * Define a typed document. `TData` is the document's TypeScript shape.
+ *
+ * **Most apps should reach for {@link createFirestate} + {@link doc} instead**
+ * — that builds a registry of every Firestore thing in one object and
+ * generates typed hooks for you. `defineDocument` is the lower-level
+ * escape hatch: use it when you need fully custom `collection` / `id`
+ * derivation, when you're calling firestate outside React, or when a
+ * registry doesn't fit your control flow.
+ *
+ * Two ways to use:
+ *
+ * 1. Plain TypeScript type (no schema, no runtime validation):
+ * ```ts
+ * interface Project { name: string; createdAt: number }
+ *
+ * const projectDoc = defineDocument<Project>({
+ *     collection: 'projects',
+ *     id: (params) => params.projectId,
+ * })
+ * ```
+ *
+ * 2. With a Zod schema — `TData` is inferred from `z.infer<S>`. Firestate
+ *    runs `schema.parse(...)` on full-payload writes (`set`/`add`) so bad
+ *    data throws at the call site. Partial `update(diff)` calls are not
+ *    validated (diffs frequently contain Firestore sentinels).
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const ProjectSchema = z.object({ name: z.string(), createdAt: z.number() })
+ *
+ * const projectDoc = defineDocument({
+ *     schema: ProjectSchema,
+ *     collection: 'projects',
+ *     id: (params) => params.projectId,
+ * })
+ * ```
+ */
+declare function defineDocument<S extends ZodType<FirestoreObject>>(definition: Omit<DocumentDefinition<z.infer<S>>, "schema"> & {
+  schema: S;
+}): DocumentDefinition<z.infer<S>>;
+declare function defineDocument<TData extends FirestoreObject>(definition: DocumentDefinition<TData>): DocumentDefinition<TData>;
+/**
+ * Define a typed collection. `TData` is the shape of each document in the
+ * collection. See {@link defineDocument} for the schema/plain-type tradeoff.
+ *
+ * **Most apps should reach for {@link createFirestate} + {@link col} instead.**
+ * `defineCollection` is the escape hatch for fully custom path derivation
+ * or non-React usage.
+ *
+ * @example
+ * ```ts
+ * interface Space { name: string; area: number }
+ *
+ * const spacesCollection = defineCollection<Space>({
+ *     path: (params) => `projects/${params.projectId}/spaces`,
+ *     lazy: true,
+ * })
+ * ```
+ */
+declare function defineCollection<S extends ZodType<FirestoreObject>>(definition: Omit<CollectionDefinition<z.infer<S>>, "schema"> & {
+  schema: S;
+}): CollectionDefinition<z.infer<S>>;
+declare function defineCollection<TData extends FirestoreObject>(definition: CollectionDefinition<TData>): CollectionDefinition<TData>;
+/**
+ * Infer the document data type from a {@link DocumentDefinition}.
+ */
+type InferDocumentData<T extends DocumentDefinition<FirestoreObject>> = T extends DocumentDefinition<infer D> ? D : never;
+/**
+ * Infer the document data type (with `id` field) from a {@link DocumentDefinition}.
+ */
+type InferDocument<T extends DocumentDefinition<FirestoreObject>> = InferDocumentData<T> & {
+  id: string;
+};
+/**
+ * Infer the document data type from a {@link CollectionDefinition}.
+ */
+type InferCollectionData<T extends CollectionDefinition<FirestoreObject>> = T extends CollectionDefinition<infer D> ? D : never;
+/**
+ * Infer the document data type (with `id` field) from a {@link CollectionDefinition}.
+ */
+type InferCollectionDocument<T extends CollectionDefinition<FirestoreObject>> = InferCollectionData<T> & {
+  id: string;
+};
+//#endregion
+//#region src/undo.d.ts
+/**
+ * Configuration for creating an undo manager
+ */
+interface UndoManagerConfig {
+  /** Maximum number of undo actions to keep, default 20 */
+  maxLength?: number;
+  /** Callback when navigation is requested (for path-aware undo) */
+  onNavigate?: (path: string) => void;
+}
+/**
+ * Create an undo manager instance.
+ * This is a standalone, framework-agnostic implementation.
+ *
+ * @example
+ * ```ts
+ * const undoManager = createUndoManager({ maxLength: 10 })
+ *
+ * undoManager.push({
+ *   undo: () => restoreOldValue(),
+ *   redo: () => applyNewValue(),
+ *   description: 'Update project name',
+ * })
+ *
+ * await undoManager.undo() // Calls restoreOldValue()
+ * await undoManager.redo() // Calls applyNewValue()
+ * ```
+ */
+declare const createUndoManager: (config?: UndoManagerConfig) => UndoManager & {
+  subscribe: (fn: Subscriber<UndoManagerState>) => Unsubscribe;
+  getState: () => UndoManagerState;
+};
+/**
+ * Type for the undo manager with subscription capability
+ */
+type UndoManagerWithSubscribe = ReturnType<typeof createUndoManager>;
+//#endregion
+//#region src/store.d.ts
+/**
+ * Firestate store that holds configuration and shared state
+ */
+interface FirestateStore {
+  /** Firestore instance */
+  readonly firestore: Firestore;
+  /** Undo manager instance */
+  readonly undoManager: UndoManagerWithSubscribe;
+  /** Default autosave interval (ms) */
+  readonly autosave: number;
+  /** Default minimum load time (ms) */
+  readonly minLoadTime: number;
+  /** Report an error */
+  reportError: (error: Error, context: ErrorContext) => void;
+  /**
+       * Replace the error handler at runtime. Used by FirestateProvider to keep
+       * the store identity stable when consumers pass an inline `onError`
+       * callback that changes reference on every render.
+       */
+  setOnError: (handler?: (error: Error, context: ErrorContext) => void) => void;
+  /** Subscribe to sync state changes */
+  subscribeToSyncState: (fn: Subscriber<boolean>) => Unsubscribe;
+  /** Report a document/collection sync state change */
+  reportSyncState: (key: string, isSynced: boolean) => void;
+  /**
+       * Remove a sync-state key. Subscriptions call this on stop() so an
+       * unmounted hook does not leave the global isSynced stuck at false.
+       */
+  unregisterSyncState: (key: string) => void;
+  /** Get whether all tracked resources are synced */
+  readonly isSynced: boolean;
+}
+/**
+ * Create a Firestate store.
+ * This is the central configuration point for your Firestore state management.
+ *
+ * @example
+ * ```ts
+ * import { createStore } from 'firestate'
+ * import { db } from './firebase'
+ *
+ * export const store = createStore({
+ *   firestore: db,
+ *   autosave: 1000,
+ *   maxUndoLength: 20,
+ *   onError: (error, context) => {
+ *     console.error(`Error in ${context.type} ${context.path}:`, error)
+ *   },
+ * })
+ * ```
+ */
+declare const createStore: (config: FirestateConfig) => FirestateStore;
+/**
+ * Type alias for the store type
+ */
+type Store = ReturnType<typeof createStore>;
+//#endregion
+//#region src/hooks.d.ts
+/**
+ * Context for providing the Firestate store
+ */
+declare const FirestateContext: react0.Context<FirestateStore | null>;
+/**
+ * Hook to access the Firestate store
+ */
+declare const useStore: () => FirestateStore;
+/**
+ * Hook to access the undo manager
+ */
+declare const useUndoManager: () => UndoManager;
+/**
+ * Hook to check if all tracked resources are synced
+ */
+declare const useIsSynced: () => boolean;
+/**
+ * Options for useDocument hook
+ */
+interface UseDocumentOptions<TData extends FirestoreObject> {
+  /** Document definition from defineDocument() */
+  definition: DocumentDefinition<TData>;
+  /** Route/path parameters for dynamic paths */
+  params?: Record<string, string>;
+  /** Override read-only setting */
+  readOnly?: boolean;
+  /** Enable undo/redo for this document (default: true) */
+  undoable?: boolean;
+  /**
+       * If false, no subscription is created and a no-op handle is returned
+       * (`{ data: undefined, isLoading: false, isSynced: true, ref: undefined }`).
+       * Use this to gate subscriptions on route params that aren't ready yet.
+       * Default: true.
+       */
+  enabled?: boolean;
+}
+/**
+ * Hook to subscribe to a Firestore document with real-time updates.
+ *
+ * The subscription is keyed on the resolved document path (`definition` +
+ * computed id) and `readOnly`. When that key changes — typically because
+ * `params` produces a different id — the hook tears down the old Firestore
+ * listener and attaches a new one. Toggling `undoable` does not rebuild the
+ * subscription.
+ *
+ * Use `enabled: false` to suppress the subscription entirely (e.g., when
+ * route params aren't ready yet).
+ *
+ * **SSR.** On the server there is no Firestore listener, so this hook returns
+ * the initial handle (`{ data: undefined, isLoading: true }`). Mutations like
+ * `update`/`set` will mutate orphaned local state with no effect — avoid
+ * calling them server-side.
+ *
+ * @example
+ * ```tsx
+ * const projectDoc = defineDocument<Project>({
+ *   collection: 'projects',
+ *   id: (params) => params.projectId,
+ * })
+ *
+ * function ProjectEditor({ projectId }: { projectId: string }) {
+ *   const { data, update, isLoading, isSynced } = useDocument({
+ *     definition: projectDoc,
+ *     params: { projectId },
+ *   })
+ *
+ *   if (isLoading) return <Spinner />
+ *
+ *   return (
+ *     <input
+ *       value={data?.name ?? ''}
+ *       onChange={(e) => update({ name: e.target.value })}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+declare const useDocument: <TData extends FirestoreObject>(options: UseDocumentOptions<TData>) => DocumentHandle<TData>;
+/**
+ * Options for useCollection hook
+ */
+interface UseCollectionOptions<TData extends FirestoreObject> {
+  /** Collection definition from defineCollection() */
+  definition: CollectionDefinition<TData>;
+  /** Route/path parameters for dynamic paths */
+  params?: Record<string, string>;
+  /** Override read-only setting */
+  readOnly?: boolean;
+  /** Additional query constraints */
+  queryConstraints?: QueryConstraint[];
+  /** Enable undo/redo for this collection (default: true) */
+  undoable?: boolean;
+  /**
+       * If false, no subscription is created and a no-op handle is returned
+       * (`{ data: {}, isLoading: false, isActive: false }`). Use this to gate on
+       * route params that aren't ready yet. Default: true.
+       */
+  enabled?: boolean;
+}
+/**
+ * Hook to subscribe to a Firestore collection with real-time updates.
+ *
+ * The subscription is keyed on the resolved collection path, `readOnly`, and
+ * the `queryConstraints` reference. When any of these change, the listener
+ * is torn down and re-attached with the new query. Toggling `undoable` does
+ * not rebuild the subscription.
+ *
+ * **Memoize `queryConstraints`.** An inline array (`queryConstraints={[where(...)]}`)
+ * creates a new reference every render, which will thrash the listener.
+ * Wrap in `useMemo` with the underlying filter values as deps.
+ *
+ * Use `enabled: false` to suppress the subscription entirely (e.g., when
+ * route params aren't ready yet).
+ *
+ * **SSR.** On the server there is no Firestore listener, so this hook returns
+ * the initial handle (`{ data: {}, isLoading: true }` for non-lazy, or
+ * `isActive: false` for lazy). Avoid calling mutations server-side.
+ *
+ * @example
+ * ```tsx
+ * const spacesCollection = defineCollection<Space>({
+ *   path: (params) => `projects/${params.projectId}/spaces`,
+ *   lazy: true,
+ * })
+ *
+ * function SpacesList({ projectId }: { projectId: string }) {
+ *   const { data, update, load, isActive, isLoading } = useCollection({
+ *     definition: spacesCollection,
+ *     params: { projectId },
+ *   })
+ *
+ *   // Lazy load on mount
+ *   useEffect(() => { load() }, [load])
+ *
+ *   if (!isActive) return <Button onClick={load}>Load Spaces</Button>
+ *   if (isLoading) return <Spinner />
+ *
+ *   return (
+ *     <ul>
+ *       {Object.values(data).map((space) => (
+ *         <li key={space.id}>{space.name}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ * ```
+ */
+declare const useCollection: <TData extends FirestoreObject>(options: UseCollectionOptions<TData>) => CollectionHandle<TData>;
+/**
+ * Keyboard shortcut hook for undo/redo
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   useUndoKeyboardShortcuts()
+ *   return <YourApp />
+ * }
+ * ```
+ */
+declare const useUndoKeyboardShortcuts: () => void;
+//#endregion
+//#region src/firestate.d.ts
+/**
+ * Knobs forwarded from a generated document hook to {@link useDocument}.
+ * Same shape as `UseDocumentOptions` minus the fields the registry already
+ * owns (`definition`, `params`).
+ */
+type DocHookOptions<T extends FirestoreObject> = Omit<UseDocumentOptions<T>, "definition" | "params">;
+/**
+ * Knobs forwarded from a generated collection hook to {@link useCollection}.
+ */
+type ColHookOptions<T extends FirestoreObject> = Omit<UseCollectionOptions<T>, "definition" | "params">;
+interface CommonEntryOptions {
+  /** Debounce interval for autosave (ms). */
+  autosave?: number;
+  /** Minimum loading indicator time (ms). */
+  minLoadTime?: number;
+  /** Whether this entry is read-only. */
+  readOnly?: boolean;
+  /** Retry the snapshot listener on transient errors. */
+  retryOnError?: boolean;
+  /** Retry interval (ms). */
+  retryInterval?: number;
+}
+/**
+ * Document entry in a Firestate registry. Produced by {@link doc}.
+ *
+ * The `P` generic carries the path template's string-literal type so the
+ * generated hook can type-check param keys. `__kind` is a runtime
+ * discriminator; `__type` is a phantom field used purely for inference at
+ * the call site and is never read.
+ */
+interface DocEntry<T extends FirestoreObject, P extends string = string> extends CommonEntryOptions {
+  readonly __kind: "document";
+  readonly __type?: T;
+  /** Path template, e.g. `'taskLists/{listId}'`. */
+  path: P;
+  /**
+       * Zod schema. **Required** — firestate's registry API is opinionated
+       * about Zod. The schema is the source of `T` for the generated hooks
+       * via `z.infer`, and firestate runs `schema.parse(...)` on full-payload
+       * writes (`set`/`add`) so bad data throws at the call site rather than
+       * after a Firestore round trip. Partial `update(diff)` is NOT validated
+       * (diffs frequently contain Firestore sentinels like `serverTimestamp()`).
+       *
+       * If you don't want a schema at all, use {@link defineDocument} directly —
+       * the escape hatch keeps the plain-TypeScript form at the cost of looser
+       * param typing and no runtime validation.
+       */
+  schema: ZodType<T>;
+}
+/** Collection entry in a Firestate registry. Produced by {@link col}. */
+interface ColEntry<T extends FirestoreObject, P extends string = string> extends CommonEntryOptions {
+  readonly __kind: "collection";
+  readonly __type?: T;
+  /** Path template, e.g. `'taskLists/{listId}/tasks'`. */
+  path: P;
+  /** Zod schema. Required. See {@link DocEntry.schema}. */
+  schema: ZodType<T>;
+  /** Only subscribe when `load()` is called. */
+  lazy?: boolean;
+  /** Additional Firestore query constraints. */
+  queryConstraints?: QueryConstraint[];
+}
+type FirestateEntry<T extends FirestoreObject = FirestoreObject, P extends string = string> = DocEntry<T, P> | ColEntry<T, P>;
+type FirestateRegistry = Record<string, FirestateEntry<any, any>>;
+/**
+ * Extract `{name}` placeholders from a path template into a params shape.
+ *
+ * - `'users'` → `{}`
+ * - `'users/{userId}'` → `{ userId: string }`
+ * - `'projects/{projectId}/revisions/{revisionId}'` → `{ projectId: string; revisionId: string }`
+ *
+ * When the path is widened to `string` (no literal preserved), we fall
+ * back to `Record<string, string>` so existing call sites keep compiling.
+ */
+type ParamsOf<P extends string> = string extends P ? Record<string, string> : Prettify<RawParamsOf<P>>;
+type RawParamsOf<P extends string> = P extends `${string}{${infer K}}${infer Rest}` ? { [Key in K]: string } & RawParamsOf<Rest> : {};
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+type DocOpts<T extends FirestoreObject> = Omit<DocEntry<T>, "__kind" | "__type" | "path">;
+type ColOpts<T extends FirestoreObject> = Omit<ColEntry<T>, "__kind" | "__type" | "path">;
+/**
+ * Declare a single-document entry for a Firestate registry.
+ *
+ * **A Zod `schema` field is required.** Both the data type (`T`) and the
+ * path's literal type (`P`) are inferred from the call — `T` via
+ * `z.infer<S>`, `P` from `path` — so the generated hook can statically
+ * type-check the params object the caller passes. The schema also runs
+ * at runtime on full-payload writes (`set`/`add`).
+ *
+ * If you'd rather not provide a schema at all, use {@link defineDocument}
+ * directly — that escape hatch keeps the plain-TypeScript form, at the
+ * cost of looser param typing on the hook and no runtime validation.
+ *
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const TaskListSchema = z.object({ name: z.string(), createdAt: z.number() })
+ * doc({ path: 'taskLists/{listId}', schema: TaskListSchema })
+ * // → DocEntry<{ name: string; createdAt: number }, 'taskLists/{listId}'>
+ * ```
+ */
+declare function doc<S extends ZodType<FirestoreObject>, const P extends string = string>(opts: Omit<DocOpts<z.infer<S>>, "schema"> & {
+  schema: S;
+  path: P;
+}): DocEntry<z.infer<S>, P>;
+/**
+ * Declare a collection entry for a Firestate registry. See {@link doc}
+ * for the schema/typing contract.
+ */
+declare function col<S extends ZodType<FirestoreObject>, const P extends string = string>(opts: Omit<ColOpts<z.infer<S>>, "schema"> & {
+  schema: S;
+  path: P;
+}): ColEntry<z.infer<S>, P>;
+type HookName<K extends string> = `use${Capitalize<K>}`;
+type HookFor<E> = E extends DocEntry<infer T, infer P> ? keyof ParamsOf<P> extends never ? (params?: Record<string, string>, options?: DocHookOptions<T>) => DocumentHandle<T> : (params: ParamsOf<P>, options?: DocHookOptions<T>) => DocumentHandle<T> : E extends ColEntry<infer T, infer P> ? keyof ParamsOf<P> extends never ? (params?: Record<string, string>, options?: ColHookOptions<T>) => CollectionHandle<T> : (params: ParamsOf<P>, options?: ColHookOptions<T>) => CollectionHandle<T> : never;
+type FirestateApi<R extends FirestateRegistry> = { [K in keyof R & string as HookName<K>]: HookFor<R[K]> };
+/**
+ * Turn a Firestate registry into a map of typed React hooks. Each entry
+ * `K` produces a hook named `use{Capitalize<K>}`.
+ *
+ * ```ts
+ * export const { useTaskList, useTasks } = createFirestate({
+ *   taskList: doc<TaskList>('taskLists/{listId}'),
+ *   tasks:    col<Task>('taskLists/{listId}/tasks'),
+ * })
+ * ```
+ */
+declare function createFirestate<R extends FirestateRegistry>(registry: R): FirestateApi<R>;
+//#endregion
+//#region src/diff.d.ts
+/**
+ * Check if two values are deeply equal
+ */
+declare const isDeepEqual: (a: unknown, b: unknown) => boolean;
+/**
+ * Compute the minimal diff between two objects for Firestore updates.
+ * Returns only the fields that changed, using deleteField() for removed fields.
+ *
+ * @param from - The original object (sync state)
+ * @param to - The target object (local state)
+ * @returns A partial object containing only changed fields
+ */
+declare const computeDiff: <T extends FirestoreObject>(from: T, to: T | undefined) => WithFieldValue<DeepPartial<T>>;
+/**
+ * Apply a Firestore diff to a target object in place (mutating).
+ * Handles deleteField(), serverTimestamp(), and nested objects.
+ *
+ * Most code should use `applyDiff` (immutable) instead.
+ * This mutable version is useful for performance-critical paths
+ * where you're already working with a cloned object.
+ *
+ * @param target - The object to mutate
+ * @param diff - The diff to apply
+ */
+declare const applyDiffMutable: (target: FirestoreObject, diff: Record<string, unknown>) => void;
+/**
+ * Create a deep clone of an object that's safe for Firestore operations.
+ *
+ * Firestore opaque values (FieldValue sentinels, Timestamp,
+ * DocumentReference, GeoPoint, Bytes, VectorValue) are returned **by
+ * reference**. They are immutable from the user's perspective; cloning
+ * them by walking keys would either lose their prototype — turning a
+ * `DocumentReference` into a plain object Firestore can't recognize —
+ * or destroy a sentinel that needed to reach the server intact.
+ */
+declare const deepClone: <T>(value: T) => T;
+/**
+ * Check if a diff is empty (no changes)
+ */
+declare const isDiffEmpty: (diff: Record<string, unknown>) => boolean;
+/**
+ * Flatten a nested diff object to dot notation for use with Firestore's updateDoc.
+ *
+ * This converts:
+ * ```
+ * { building: { floors: 5, height: 100 }, name: 'Test' }
+ * ```
+ * To:
+ * ```
+ * { 'building.floors': 5, 'building.height': 100, 'name': 'Test' }
+ * ```
+ *
+ * Arrays, FieldValue sentinels (deleteField, serverTimestamp, …) and
+ * Firestore value types (Timestamp, DocumentReference, GeoPoint, Bytes,
+ * VectorValue) are NOT flattened — they're preserved at their path so
+ * Firestore receives them in their original form.
+ *
+ * @param diff - The nested diff object
+ * @param prefix - Internal: current path prefix for recursion
+ * @returns Flattened object with dotted keys
+ */
+declare const flattenDiff: (diff: Record<string, unknown>, prefix?: string) => Record<string, unknown>;
+/**
+ * Merge two diffs together, with the second taking precedence
+ */
+declare const mergeDiffs: <T extends FirestoreObject>(first: WithFieldValue<DeepPartial<T>>, second: WithFieldValue<DeepPartial<T>>) => WithFieldValue<DeepPartial<T>>;
+/**
+ * Apply a diff to an object, returning a new object.
+ * The original object is not modified.
+ *
+ * @example
+ * ```ts
+ * const original = { name: 'Project', count: 5 }
+ * const diff = { name: 'Updated', count: deleteField() }
+ * const result = applyDiff(original, diff)
+ * // result = { name: 'Updated' }
+ * // original is unchanged
+ * ```
+ */
+declare const applyDiff: <T extends FirestoreObject>(state: T, diff: WithFieldValue<DeepPartial<T>>) => T;
+/**
+ * Compute the undo diff that would reverse the effect of applying a diff to a state.
+ *
+ * Given a starting state and a diff that was (or will be) applied to it,
+ * returns a new diff that when applied to the result would restore the original state.
+ *
+ * @example
+ * ```ts
+ * const startState = { name: 'Foo', count: 5 }
+ * const diff = { name: 'Bar', count: deleteField() }
+ *
+ * // Apply the diff
+ * const endState = applyDiff(startState, diff)
+ * // endState = { name: 'Bar' }
+ *
+ * // Compute the undo
+ * const undoDiff = computeUndoDiff(startState, diff)
+ * // undoDiff = { name: 'Foo', count: 5 }
+ *
+ * // Applying undoDiff to endState restores startState
+ * const restored = applyDiff(endState, undoDiff)
+ * // restored = { name: 'Foo', count: 5 }
+ * ```
+ */
+declare const computeUndoDiff: <T extends FirestoreObject>(startState: T, diff: WithFieldValue<DeepPartial<T>>) => WithFieldValue<DeepPartial<T>>;
+/**
+ * Check if a diff affects a specific path (supports dot notation).
+ *
+ * @example
+ * ```ts
+ * const diff = { building: { floors: 5 }, name: 'Test' }
+ *
+ * diffContainsPath(diff, 'name') // true
+ * diffContainsPath(diff, 'building') // true
+ * diffContainsPath(diff, 'building.floors') // true
+ * diffContainsPath(diff, 'building.height') // false
+ * diffContainsPath(diff, 'other') // false
+ * ```
+ */
+declare const diffContainsPath: (diff: Record<string, unknown>, path: string) => boolean;
+/**
+ * Extract the value at a specific path from a diff (supports dot notation).
+ * Returns undefined if the path doesn't exist in the diff.
+ *
+ * @example
+ * ```ts
+ * const diff = { building: { floors: 5, height: 100 }, name: 'Test' }
+ *
+ * extractDiffValue(diff, 'name') // 'Test'
+ * extractDiffValue(diff, 'building') // { floors: 5, height: 100 }
+ * extractDiffValue(diff, 'building.floors') // 5
+ * extractDiffValue(diff, 'building.missing') // undefined
+ * ```
+ */
+declare const extractDiffValue: (diff: Record<string, unknown>, path: string) => unknown;
+/**
+ * Create a diff that sets a value at a specific path (supports dot notation).
+ *
+ * @example
+ * ```ts
+ * createDiffAtPath('name', 'New Name')
+ * // { name: 'New Name' }
+ *
+ * createDiffAtPath('building.floors', 5)
+ * // { building: { floors: 5 } }
+ *
+ * createDiffAtPath('building.config.enabled', true)
+ * // { building: { config: { enabled: true } } }
+ * ```
+ */
+declare const createDiffAtPath: (path: string, value: unknown) => Record<string, unknown>;
+/**
+ * Invert a flattened diff back to nested object structure.
+ * Opposite of flattenDiff.
+ *
+ * @example
+ * ```ts
+ * const flat = { 'building.floors': 5, 'building.height': 100, 'name': 'Test' }
+ * const nested = unflattenDiff(flat)
+ * // { building: { floors: 5, height: 100 }, name: 'Test' }
+ * ```
+ */
+declare const unflattenDiff: (flatDiff: Record<string, unknown>) => Record<string, unknown>;
+//#endregion
+//#region src/document.d.ts
+/**
+ * Options for creating a document subscription
+ */
+interface DocumentOptions<TData extends FirestoreObject> {
+  /** The store instance */
+  store: FirestateStore;
+  /** Document definition from defineDocument() */
+  definition: DocumentDefinition<TData>;
+  /**
+       * Resolved document id. If omitted and `definition.id` is a string, that
+       * value is used. If `definition.id` is a function, this option is required.
+       */
+  docId?: string;
+  /**
+       * Resolved collection path. If omitted and `definition.collection` is a
+       * string, that value is used. If `definition.collection` is a function,
+       * this option is required.
+       */
+  collectionPath?: string;
+  /** Override read-only setting */
+  readOnly?: boolean;
+  /** Callback for pushing undo actions */
+  onPushUndo?: (undoAction: () => void, redoAction: () => void, options?: UpdateOptions) => void;
+}
+/**
+ * Create a document subscription.
+ * This is a low-level API - prefer using useDocument hook in React.
+ *
+ * @example
+ * ```ts
+ * const subscription = createDocumentSubscription({
+ *   store,
+ *   definition: projectDoc,
+ *   docId: '123',
+ * })
+ *
+ * const unsubscribe = subscription.subscribe((state) => {
+ *   console.log('Document state:', state)
+ * })
+ *
+ * subscription.load()
+ * ```
+ */
+declare const createDocumentSubscription: <TData extends FirestoreObject>(options: DocumentOptions<TData>) => {
+  /** Attach the Firestore listener */load: () => void; /** Stop the Firestore listener */
+  stop: () => void; /** Subscribe to state changes */
+  subscribe: (fn: Subscriber<DocumentState<TData>>) => Unsubscribe; /** Get current state */
+  getState: () => DocumentState<TData>; /** Get document handle for updates */
+  getHandle: () => DocumentHandle<TData>; /** Force sync now */
+  sync: () => Promise<void>;
+};
+//#endregion
+//#region src/collection.d.ts
+/**
+ * Options for creating a collection subscription
+ */
+interface CollectionOptions<TData extends FirestoreObject> {
+  /** The store instance */
+  store: FirestateStore;
+  /** Collection definition from defineCollection() */
+  definition: CollectionDefinition<TData>;
+  /**
+       * Resolved collection path. If omitted and `definition.path` is a string,
+       * that value is used. If `definition.path` is a function, this option is
+       * required.
+       */
+  collectionPath?: string;
+  /** Override read-only setting */
+  readOnly?: boolean;
+  /** Additional query constraints */
+  queryConstraints?: QueryConstraint[];
+  /** Callback for pushing undo actions */
+  onPushUndo?: (undoAction: () => void, redoAction: () => void, options?: UpdateOptions) => void;
+}
+/**
+ * Create a collection subscription.
+ * This is a low-level API - prefer using useCollection hook in React.
+ *
+ * @example
+ * ```ts
+ * const subscription = createCollectionSubscription({
+ *   store,
+ *   definition: spacesCollection,
+ *   collectionPath: 'projects/123/spaces',
+ * })
+ *
+ * const unsubscribe = subscription.subscribe((state) => {
+ *   console.log('Collection state:', state)
+ * })
+ *
+ * subscription.load() // For lazy collections
+ * ```
+ */
+declare const createCollectionSubscription: <TData extends FirestoreObject>(options: CollectionOptions<TData>) => {
+  /** Activate the subscription (for lazy loading) */load: () => void; /** Stop the Firestore listener */
+  stop: () => void; /** Subscribe to state changes */
+  subscribe: (fn: Subscriber<CollectionState<TData>>) => Unsubscribe; /** Get current state */
+  getState: () => CollectionState<TData>; /** Get collection handle for updates */
+  getHandle: () => CollectionHandle<TData>; /** Force sync now */
+  sync: () => Promise<void>;
+};
+//#endregion
+//#region src/provider.d.ts
+/**
+ * Props for FirestateProvider
+ */
+interface FirestateProviderProps {
+  /** Firestore instance */
+  firestore: Firestore;
+  /** Default autosave interval (ms), default 1000 */
+  autosave?: number;
+  /** Default minimum load time (ms), default 0 */
+  minLoadTime?: number;
+  /** Maximum undo stack length, default 20 */
+  maxUndoLength?: number;
+  /** Custom error handler */
+  onError?: (error: Error, context: ErrorContext) => void;
+  /** React children */
+  children: React.ReactNode;
+}
+/**
+ * Provider component that sets up Firestate for your application.
+ *
+ * @example
+ * ```tsx
+ * import { FirestateProvider } from 'firestate'
+ * import { db } from './firebase'
+ *
+ * function App() {
+ *   return (
+ *     <FirestateProvider
+ *       firestore={db}
+ *       autosave={1000}
+ *       maxUndoLength={20}
+ *       onError={(error, ctx) => console.error(ctx.path, error)}
+ *     >
+ *       <YourApp />
+ *     </FirestateProvider>
+ *   )
+ * }
+ * ```
+ */
+declare const FirestateProvider: React.FC<FirestateProviderProps>;
+/**
+ * Props for using an existing store
+ */
+interface FirestateStoreProviderProps {
+  /** Pre-created store instance */
+  store: FirestateStore;
+  /** React children */
+  children: React.ReactNode;
+}
+/**
+ * Provider that uses an existing store instance.
+ * Useful when you need to create the store outside of React.
+ *
+ * @example
+ * ```tsx
+ * const store = createStore({ firestore: db })
+ *
+ * function App() {
+ *   return (
+ *     <FirestateStoreProvider store={store}>
+ *       <YourApp />
+ *     </FirestateStoreProvider>
+ *   )
+ * }
+ * ```
+ */
+declare const FirestateStoreProvider: React.FC<FirestateStoreProviderProps>;
+/**
+ * Hook to use navigation blocker when there are unsaved changes.
+ * Works with react-router or similar routers.
+ *
+ * @example
+ * ```tsx
+ * function ProjectPage() {
+ *   const shouldBlock = useUnsavedChangesBlocker()
+ *
+ *   // Use with react-router's useBlocker
+ *   const blocker = useBlocker(
+ *     ({ currentLocation, nextLocation }) =>
+ *       currentLocation.pathname !== nextLocation.pathname && shouldBlock
+ *   )
+ *
+ *   return (
+ *     <>
+ *       <ProjectEditor />
+ *       {blocker.state === 'blocked' && (
+ *         <Dialog>Your changes may not be saved!</Dialog>
+ *       )}
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+declare const useUnsavedChangesBlocker: () => boolean;
+//#endregion
+export { type ColEntry, type CollectionDefinition, type CollectionHandle, type CollectionOptions, type CollectionState, type DeepPartial, type DocEntry, type DocumentDefinition, type DocumentHandle, type DocumentOptions, type DocumentState, type ErrorContext, type FirestateApi, type FirestateConfig, FirestateContext, type FirestateEntry, FirestateProvider, type FirestateProviderProps, type FirestateRegistry, type FirestateStore, FirestateStoreProvider, type FirestateStoreProviderProps, type FirestoreObject, type InferCollectionData, type InferCollectionDocument, type InferDocument, type InferDocumentData, type Store, type UndoAction, type UndoManager, type UndoManagerConfig, type UndoManagerState, type UndoManagerWithSubscribe, type UpdateOptions, type UseCollectionOptions, type UseDocumentOptions, applyDiff, applyDiffMutable, col, computeDiff, computeUndoDiff, createCollectionSubscription, createDiffAtPath, createDocumentSubscription, createFirestate, createStore, createUndoManager, deepClone, defineCollection, defineDocument, diffContainsPath, doc, extractDiffValue, flattenDiff, isDeepEqual, isDiffEmpty, mergeDiffs, unflattenDiff, useCollection, useDocument, useIsSynced, useStore, useUndoKeyboardShortcuts, useUndoManager, useUnsavedChangesBlocker };
+//# sourceMappingURL=index.d.mts.map