@comapeo/core-react 2.0.1 → 3.1.0

package/dist/esm/hooks/projects.d.ts

@@ -1,5 +1,6 @@
 import type { BitmapOpts, SvgOpts } from '@comapeo/core/dist/icon-api.js' with { 'resolution-mode': 'import' };
 import type { BlobId } from '@comapeo/core/dist/types.js' with { 'resolution-mode': 'import' };
+import { type SyncState } from '../lib/sync.js';
 /**
  * Retrieve the project settings for a project.
  *
@@ -249,6 +250,28 @@ export declare function useDocumentCreatedBy({ projectId, originalVersionId, }:
     error: Error | null;
     isRefetching: boolean;
 };
+/**
+ * Get the role for the current device in a specified project.
+ * This is a more convenient alternative to using the `useOwnDeviceInfo` and `useManyMembers` hooks.
+ *
+ * @param opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useOwnRoleInProject({
+ *     projectId: '...',
+ *   })
+ * }
+ * ```
+ */
+export declare function useOwnRoleInProject({ projectId }: {
+    projectId: string;
+}): {
+    data: import("@comapeo/core/dist/roles.js").Role<"a12a6702b93bd7ff" | "f7c150f5a3a9a855" | "012fd2d431c0bf60" | "9e6d29263cba36c9" | "8ced989b1904606b" | "08e4251e36f6e7ed">;
+    error: Error | null;
+    isRefetching: boolean;
+};
 export declare function useAddServerPeer({ projectId }: {
     projectId: string;
 }): {
@@ -332,3 +355,52 @@ export declare function useCreateBlob({ projectId }: {
     reset: () => void;
     status: "pending" | "error" | "success" | "idle";
 };
+/**
+ * Hook to subscribe to the current sync state.
+ *
+ * Creates a global singleton for each project, to minimize traffic over IPC -
+ * this hook can safely be used in more than one place without attaching
+ * additional listeners across the IPC channel.
+ *
+ * @example
+ * ```ts
+ * function Example() {
+ *     const syncState = useSyncState({ projectId });
+ *
+ *     if (!syncState) {
+ *         // Sync information hasn't been loaded yet
+ *     }
+ *
+ *     // Actual info about sync state is available...
+ * }
+ * ```
+ *
+ * @param opts.projectId Project public ID
+ */
+export declare function useSyncState({ projectId, }: {
+    projectId: string;
+}): SyncState | null;
+/**
+ * Provides the progress of data sync for sync-enabled connected peers
+ *
+ * @returns `null` if no sync state events have been received. Otherwise returns a value between 0 and 1 (inclusive)
+ */
+export declare function useDataSyncProgress({ projectId, }: {
+    projectId: string;
+}): number | null;
+export declare function useStartSync({ projectId }: {
+    projectId: string;
+}): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<void, Error, {
+        autostopDataSyncAfter: number | null;
+    } | undefined, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};
+export declare function useStopSync({ projectId }: {
+    projectId: string;
+}): {
+    mutate: import("@tanstack/react-query").UseMutateFunction<void, Error, void, unknown>;
+    reset: () => void;
+    status: "pending" | "error" | "success" | "idle";
+};

package/dist/esm/hooks/projects.js

@@ -1,5 +1,7 @@
 import { useMutation, useQueryClient, useSuspenseQuery, } from '@tanstack/react-query';
-import { addServerPeerMutationOptions, attachmentUrlQueryOptions, createBlobMutationOptions, createProjectMutationOptions, documentCreatedByQueryOptions, iconUrlQueryOptions, importProjectConfigMutationOptions, leaveProjectMutationOptions, projectByIdQueryOptions, projectMemberByIdQueryOptions, projectMembersQueryOptions, projectSettingsQueryOptions, projectsQueryOptions, updateProjectSettingsMutationOptions, } from '../lib/react-query/projects.js';
+import { useSyncExternalStore } from 'react';
+import { addServerPeerMutationOptions, attachmentUrlQueryOptions, createBlobMutationOptions, createProjectMutationOptions, documentCreatedByQueryOptions, iconUrlQueryOptions, importProjectConfigMutationOptions, leaveProjectMutationOptions, projectByIdQueryOptions, projectMemberByIdQueryOptions, projectMembersQueryOptions, projectOwnRoleQueryOptions, projectSettingsQueryOptions, projectsQueryOptions, startSyncMutationOptions, stopSyncMutationOptions, updateProjectSettingsMutationOptions, } from '../lib/react-query/projects.js';
+import { SyncStore } from '../lib/sync.js';
 import { useClientApi } from './client.js';
 /**
  * Retrieve the project settings for a project.
@@ -246,6 +248,26 @@ export function useDocumentCreatedBy({ projectId, originalVersionId, }) {
     const { data, error, isRefetching } = useSuspenseQuery(documentCreatedByQueryOptions({ projectApi, projectId, originalVersionId }));
     return { data, error, isRefetching };
 }
+/**
+ * Get the role for the current device in a specified project.
+ * This is a more convenient alternative to using the `useOwnDeviceInfo` and `useManyMembers` hooks.
+ *
+ * @param opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useOwnRoleInProject({
+ *     projectId: '...',
+ *   })
+ * }
+ * ```
+ */
+export function useOwnRoleInProject({ projectId }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { data, error, isRefetching } = useSuspenseQuery(projectOwnRoleQueryOptions({ projectApi, projectId }));
+    return { data, error, isRefetching };
+}
 export function useAddServerPeer({ projectId }) {
     const queryClient = useQueryClient();
     const { data: projectApi } = useSingleProject({ projectId });
@@ -302,3 +324,59 @@ export function useCreateBlob({ projectId }) {
     const { mutate, reset, status } = useMutation(createBlobMutationOptions({ projectApi }));
     return { mutate, reset, status };
 }
+const PROJECT_SYNC_STORE_MAP = new WeakMap();
+function useSyncStore({ projectId }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    let syncStore = PROJECT_SYNC_STORE_MAP.get(projectApi);
+    if (!syncStore) {
+        syncStore = new SyncStore(projectApi);
+        PROJECT_SYNC_STORE_MAP.set(projectApi, syncStore);
+    }
+    return syncStore;
+}
+/**
+ * Hook to subscribe to the current sync state.
+ *
+ * Creates a global singleton for each project, to minimize traffic over IPC -
+ * this hook can safely be used in more than one place without attaching
+ * additional listeners across the IPC channel.
+ *
+ * @example
+ * ```ts
+ * function Example() {
+ *     const syncState = useSyncState({ projectId });
+ *
+ *     if (!syncState) {
+ *         // Sync information hasn't been loaded yet
+ *     }
+ *
+ *     // Actual info about sync state is available...
+ * }
+ * ```
+ *
+ * @param opts.projectId Project public ID
+ */
+export function useSyncState({ projectId, }) {
+    const syncStore = useSyncStore({ projectId });
+    const { subscribe, getStateSnapshot } = syncStore;
+    return useSyncExternalStore(subscribe, getStateSnapshot);
+}
+/**
+ * Provides the progress of data sync for sync-enabled connected peers
+ *
+ * @returns `null` if no sync state events have been received. Otherwise returns a value between 0 and 1 (inclusive)
+ */
+export function useDataSyncProgress({ projectId, }) {
+    const { subscribe, getDataProgressSnapshot } = useSyncStore({ projectId });
+    return useSyncExternalStore(subscribe, getDataProgressSnapshot);
+}
+export function useStartSync({ projectId }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { mutate, reset, status } = useMutation(startSyncMutationOptions({ projectApi }));
+    return { mutate, reset, status };
+}
+export function useStopSync({ projectId }) {
+    const { data: projectApi } = useSingleProject({ projectId });
+    const { mutate, reset, status } = useMutation(stopSyncMutationOptions({ projectApi }));
+    return { mutate, reset, status };
+}

package/dist/esm/index.d.ts

@@ -3,10 +3,6 @@ export { useClientApi, useIsArchiveDevice, useOwnDeviceInfo, useSetIsArchiveDevi
 export { useCreateDocument, useDeleteDocument, useManyDocs, useSingleDocByDocId, useSingleDocByVersionId, useUpdateDocument, } from './hooks/documents.js';
 export { useAcceptInvite, useRejectInvite, useRequestCancelInvite, useSendInvite, } from './hooks/invites.js';
 export { useMapStyleUrl } from './hooks/maps.js';
-export { useAddServerPeer, useAttachmentUrl, useCreateBlob, useCreateProject, useDocumentCreatedBy, useIconUrl, useImportProjectConfig, useLeaveProject, useManyMembers, useManyProjects, useProjectSettings, useSingleMember, useSingleProject, useUpdateProjectSettings, } from './hooks/projects.js';
-export { getClientQueryKey, getDeviceInfoQueryKey, getIsArchiveDeviceQueryKey, } from './lib/react-query/client.js';
-export { getDocumentByDocIdQueryKey, getDocumentByVersionIdQueryKey, getDocumentsQueryKey, getManyDocumentsQueryKey, type WriteableDocument, type WriteableDocumentType, type WriteableValue, } from './lib/react-query/documents.js';
-export { getInvitesQueryKey, getPendingInvitesQueryKey, } from './lib/react-query/invites.js';
-export { getMapsQueryKey, getStyleJsonUrlQueryKey, } from './lib/react-query/maps.js';
-export { getAttachmentUrlQueryKey, getDocumentCreatedByQueryKey, getIconUrlQueryKey, getMemberByIdQueryKey, getMembersQueryKey, getProjectByIdQueryKey, getProjectRoleQueryKey, getProjectSettingsQueryKey, getProjectsQueryKey, } from './lib/react-query/projects.js';
-export { ROOT_QUERY_KEY } from './lib/react-query/shared.js';
+export { useAddServerPeer, useAttachmentUrl, useCreateBlob, useCreateProject, useDataSyncProgress, useDocumentCreatedBy, useIconUrl, useImportProjectConfig, useLeaveProject, useManyMembers, useManyProjects, useOwnRoleInProject, useProjectSettings, useSingleMember, useSingleProject, useStartSync, useStopSync, useSyncState, useUpdateProjectSettings, } from './hooks/projects.js';
+export { type SyncState } from './lib/sync.js';
+export { type WriteableDocument, type WriteableDocumentType, type WriteableValue, } from './lib/types.js';

package/dist/esm/index.js

@@ -3,10 +3,4 @@ export { useClientApi, useIsArchiveDevice, useOwnDeviceInfo, useSetIsArchiveDevi
 export { useCreateDocument, useDeleteDocument, useManyDocs, useSingleDocByDocId, useSingleDocByVersionId, useUpdateDocument, } from './hooks/documents.js';
 export { useAcceptInvite, useRejectInvite, useRequestCancelInvite, useSendInvite, } from './hooks/invites.js';
 export { useMapStyleUrl } from './hooks/maps.js';
-export { useAddServerPeer, useAttachmentUrl, useCreateBlob, useCreateProject, useDocumentCreatedBy, useIconUrl, useImportProjectConfig, useLeaveProject, useManyMembers, useManyProjects, useProjectSettings, useSingleMember, useSingleProject, useUpdateProjectSettings, } from './hooks/projects.js';
-export { getClientQueryKey, getDeviceInfoQueryKey, getIsArchiveDeviceQueryKey, } from './lib/react-query/client.js';
-export { getDocumentByDocIdQueryKey, getDocumentByVersionIdQueryKey, getDocumentsQueryKey, getManyDocumentsQueryKey, } from './lib/react-query/documents.js';
-export { getInvitesQueryKey, getPendingInvitesQueryKey, } from './lib/react-query/invites.js';
-export { getMapsQueryKey, getStyleJsonUrlQueryKey, } from './lib/react-query/maps.js';
-export { getAttachmentUrlQueryKey, getDocumentCreatedByQueryKey, getIconUrlQueryKey, getMemberByIdQueryKey, getMembersQueryKey, getProjectByIdQueryKey, getProjectRoleQueryKey, getProjectSettingsQueryKey, getProjectsQueryKey, } from './lib/react-query/projects.js';
-export { ROOT_QUERY_KEY } from './lib/react-query/shared.js';
+export { useAddServerPeer, useAttachmentUrl, useCreateBlob, useCreateProject, useDataSyncProgress, useDocumentCreatedBy, useIconUrl, useImportProjectConfig, useLeaveProject, useManyMembers, useManyProjects, useOwnRoleInProject, useProjectSettings, useSingleMember, useSingleProject, useStartSync, useStopSync, useSyncState, useUpdateProjectSettings, } from './hooks/projects.js';

package/dist/esm/lib/react-query/documents.d.ts

@@ -1,13 +1,6 @@
 import type { MapeoProjectApi } from '@comapeo/ipc' with { 'resolution-mode': 'import' };
-import type { MapeoDoc, MapeoValue } from '@comapeo/schema' with { 'resolution-mode': 'import' };
 import { type QueryClient } from '@tanstack/react-query';
-export type WriteableDocumentType = Extract<MapeoDoc['schemaName'], 'field' | 'observation' | 'preset' | 'track' | 'remoteDetectionAlert'>;
-export type WriteableValue<D extends WriteableDocumentType> = Extract<MapeoValue, {
-    schemaName: D;
-}>;
-export type WriteableDocument<D extends WriteableDocumentType> = Extract<MapeoDoc, {
-    schemaName: D;
-}>;
+import { WriteableDocument, WriteableDocumentType, WriteableValue } from '../types.js';
 export declare function getDocumentsQueryKey<D extends WriteableDocumentType>({ projectId, docType, }: {
     projectId: string;
     docType: D;

package/dist/esm/lib/react-query/projects.d.ts

@@ -330,3 +330,19 @@ export declare function createBlobMutationOptions({ projectApi, }: {
     networkMode: "always";
     retry: false;
 };
+export declare function startSyncMutationOptions({ projectApi, }: {
+    projectApi: MapeoProjectApi;
+}): {
+    mutationFn: (opts: {
+        autostopDataSyncAfter: number | null;
+    } | undefined) => Promise<void>;
+    networkMode: "always";
+    retry: false;
+};
+export declare function stopSyncMutationOptions({ projectApi, }: {
+    projectApi: MapeoProjectApi;
+}): {
+    mutationFn: () => Promise<void>;
+    networkMode: "always";
+    retry: false;
+};

package/dist/esm/lib/react-query/projects.js

@@ -207,3 +207,21 @@ export function createBlobMutationOptions({ projectApi, }) {
         },
     };
 }
+export function startSyncMutationOptions({ projectApi, }) {
+    return {
+        ...baseMutationOptions(),
+        mutationFn: async (opts) => {
+            // Have to avoid passing `undefined` explicitly
+            // See https://github.com/digidem/rpc-reflector/issues/21
+            return opts ? projectApi.$sync.start(opts) : projectApi.$sync.start();
+        },
+    };
+}
+export function stopSyncMutationOptions({ projectApi, }) {
+    return {
+        ...baseMutationOptions(),
+        mutationFn: async () => {
+            return projectApi.$sync.stop();
+        },
+    };
+}

package/dist/esm/lib/sync.d.ts

@@ -0,0 +1,10 @@
+import type { MapeoProjectApi } from '@comapeo/ipc' with { 'resolution-mode': 'import' };
+export type SyncState = Awaited<ReturnType<MapeoProjectApi['$sync']['getState']>>;
+export declare function getDataSyncCountForDevice(syncStateForDevice: SyncState['remoteDeviceSyncState'][string]): number;
+export declare class SyncStore {
+    #private;
+    constructor(project: MapeoProjectApi);
+    subscribe: (listener: () => void) => () => void;
+    getStateSnapshot: () => import("@comapeo/core/dist/sync/sync-api.js").State | null;
+    getDataProgressSnapshot: () => number | null;
+}

package/dist/esm/lib/sync.js

@@ -0,0 +1,114 @@
+export function getDataSyncCountForDevice(syncStateForDevice) {
+    const { data } = syncStateForDevice;
+    return data.want + data.wanted;
+}
+export class SyncStore {
+    #project;
+    #listeners = new Set();
+    #isSubscribedInternal = false;
+    #error = null;
+    #state = null;
+    // Used for calculating sync progress
+    #perDeviceMaxSyncCount = new Map();
+    constructor(project) {
+        this.#project = project;
+    }
+    subscribe = (listener) => {
+        this.#listeners.add(listener);
+        if (!this.#isSubscribedInternal)
+            this.#startSubscription();
+        return () => {
+            this.#listeners.delete(listener);
+            if (this.#listeners.size === 0)
+                this.#stopSubscription();
+        };
+    };
+    getStateSnapshot = () => {
+        if (this.#error)
+            throw this.#error;
+        return this.#state;
+    };
+    getDataProgressSnapshot = () => {
+        if (this.#state === null) {
+            return null;
+        }
+        let currentSyncCount = 0;
+        let totalMaxSyncCount = 0;
+        let otherEnabledDevicesExist = false;
+        for (const [deviceId, deviceSyncState] of Object.entries(this.#state.remoteDeviceSyncState)) {
+            if (deviceSyncState.data.isSyncEnabled) {
+                otherEnabledDevicesExist = true;
+            }
+            else {
+                continue;
+            }
+            const existingMaxCount = this.#perDeviceMaxSyncCount.get(deviceId);
+            if (typeof existingMaxCount === 'number' && existingMaxCount > 0) {
+                currentSyncCount = getDataSyncCountForDevice(deviceSyncState);
+                totalMaxSyncCount += existingMaxCount;
+            }
+        }
+        if (!otherEnabledDevicesExist) {
+            return null;
+        }
+        if (totalMaxSyncCount === 0) {
+            return 1;
+        }
+        const ratio = (totalMaxSyncCount - currentSyncCount) / totalMaxSyncCount;
+        if (ratio <= 0)
+            return 0;
+        if (ratio >= 1)
+            return 1;
+        return clamp(ratio, 0.01, 0.99);
+    };
+    #notifyListeners() {
+        for (const listener of this.#listeners) {
+            listener();
+        }
+    }
+    #onSyncState = (state) => {
+        const dataSyncWasEnabled = this.#state
+            ? this.#state.data.isSyncEnabled
+            : false;
+        // Reset map keeping track of counts used for progress if data sync is toggled
+        if (dataSyncWasEnabled !== state.data.isSyncEnabled) {
+            this.#perDeviceMaxSyncCount.clear();
+        }
+        else {
+            // Remove devices from #perDeviceMaxSyncCount that are no longer found in the new sync state
+            for (const deviceId of this.#perDeviceMaxSyncCount.keys()) {
+                if (!Object.hasOwn(state.remoteDeviceSyncState, deviceId)) {
+                    this.#perDeviceMaxSyncCount.delete(deviceId);
+                }
+            }
+        }
+        for (const [deviceId, stateForDevice] of Object.entries(state.remoteDeviceSyncState)) {
+            const existingCount = this.#perDeviceMaxSyncCount.get(deviceId);
+            const newCount = getDataSyncCountForDevice(stateForDevice);
+            if (existingCount === undefined || existingCount < newCount) {
+                this.#perDeviceMaxSyncCount.set(deviceId, newCount);
+            }
+        }
+        this.#state = state;
+        this.#error = null;
+        this.#notifyListeners();
+    };
+    #startSubscription = () => {
+        this.#project.$sync.on('sync-state', this.#onSyncState);
+        this.#isSubscribedInternal = true;
+        this.#project.$sync
+            .getState()
+            .then(this.#onSyncState)
+            .catch((e) => {
+            this.#error = e;
+            this.#notifyListeners();
+        });
+    };
+    #stopSubscription = () => {
+        this.#isSubscribedInternal = false;
+        this.#project.$sync.off('sync-state', this.#onSyncState);
+    };
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(value, max));
+}

package/dist/esm/lib/types.d.ts

@@ -0,0 +1,9 @@
+import type { MapeoDoc, MapeoValue } from '@comapeo/schema' with { 'resolution-mode': 'import' };
+export type WriteableDocumentType = Extract<MapeoDoc['schemaName'], 'field' | 'observation' | 'preset' | 'track' | 'remoteDetectionAlert'>;
+export type WriteableValue<D extends WriteableDocumentType> = Extract<MapeoValue, {
+    schemaName: D;
+}>;
+export type WriteableDocument<D extends WriteableDocumentType> = Extract<MapeoDoc, {
+    schemaName: D;
+}>;
+export {};

package/dist/esm/lib/types.js

@@ -0,0 +1 @@
+export {};

package/docs/API.md

@@ -14,12 +14,17 @@
 - [useIconUrl](#useiconurl)
 - [useAttachmentUrl](#useattachmenturl)
 - [useDocumentCreatedBy](#usedocumentcreatedby)
+- [useOwnRoleInProject](#useownroleinproject)
 - [useAddServerPeer](#useaddserverpeer)
 - [useCreateProject](#usecreateproject)
 - [useLeaveProject](#useleaveproject)
 - [useImportProjectConfig](#useimportprojectconfig)
 - [useUpdateProjectSettings](#useupdateprojectsettings)
 - [useCreateBlob](#usecreateblob)
+- [useSyncState](#usesyncstate)
+- [useDataSyncProgress](#usedatasyncprogress)
+- [useStartSync](#usestartsync)
+- [useStopSync](#usestopsync)
 - [useSingleDocByDocId](#usesingledocbydocid)
 - [useSingleDocByVersionId](#usesingledocbyversionid)
 - [useManyDocs](#usemanydocs)
@@ -38,7 +43,7 @@ Create a context provider that holds a CoMapeo API client instance.
 
 | Function | Type |
 | ---------- | ---------- |
-| `ClientApiProvider` | `({ children, clientApi, }: { children: ReactNode; clientApi: MapeoClientApi; }) => FunctionComponentElement<ProviderProps<MapeoClientApi or null>>` |
+| `ClientApiProvider` | `({ children, clientApi, }: { children: ReactNode; clientApi: MapeoClientApi; }) => Element` |
 
 Parameters:
 
@@ -373,6 +378,31 @@ function BasicExample() {
 ```
 
 
+### useOwnRoleInProject
+
+Get the role for the current device in a specified project.
+This is a more convenient alternative to using the `useOwnDeviceInfo` and `useManyMembers` hooks.
+
+| Function | Type |
+| ---------- | ---------- |
+| `useOwnRoleInProject` | `({ projectId }: { projectId: string; }) => { data: Role<"a12a6702b93bd7ff" or "f7c150f5a3a9a855" or "012fd2d431c0bf60" or "9e6d29263cba36c9" or "8ced989b1904606b" or "08e4251e36f6e7ed">; error: Error or null; isRefetching: boolean; }` |
+
+Parameters:
+
+* `opts.projectId`: Project public ID
+
+
+Examples:
+
+```tsx
+function BasicExample() {
+  const { data } = useOwnRoleInProject({
+    projectId: '...',
+  })
+}
+```
+
+
 ### useAddServerPeer
 
 | Function | Type |
@@ -427,13 +457,65 @@ Create a blob for a project.
 
 | Function | Type |
 | ---------- | ---------- |
-| `useCreateBlob` | `({ projectId }: { projectId: string; }) => { mutate: UseMutateFunction<{ driveId: string; name: string; type: "audio" or "video" or "photo"; hash: string; }, Error, { original: string; preview?: string or undefined; thumbnail?: string or undefined; metadata: Metadata; }, unknown>; reset: () => void; status: "pending" or ...` |
+| `useCreateBlob` | `({ projectId }: { projectId: string; }) => { mutate: UseMutateFunction<{ driveId: string; name: string; type: "photo" or "audio" or "video"; hash: string; }, Error, { original: string; preview?: string or undefined; thumbnail?: string or undefined; metadata: Metadata; }, unknown>; reset: () => void; status: "pending" or ...` |
 
 Parameters:
 
 * `opts.projectId`: Public project ID of project to apply to changes to.
 
 
+### useSyncState
+
+Hook to subscribe to the current sync state.
+
+Creates a global singleton for each project, to minimize traffic over IPC -
+this hook can safely be used in more than one place without attaching
+additional listeners across the IPC channel.
+
+| Function | Type |
+| ---------- | ---------- |
+| `useSyncState` | `({ projectId, }: { projectId: string; }) => State or null` |
+
+Parameters:
+
+* `opts.projectId`: Project public ID
+
+
+Examples:
+
+```ts
+function Example() {
+    const syncState = useSyncState({ projectId });
+
+    if (!syncState) {
+        // Sync information hasn't been loaded yet
+    }
+
+    // Actual info about sync state is available...
+}
+```
+
+
+### useDataSyncProgress
+
+Provides the progress of data sync for sync-enabled connected peers
+
+| Function | Type |
+| ---------- | ---------- |
+| `useDataSyncProgress` | `({ projectId, }: { projectId: string; }) => number or null` |
+
+### useStartSync
+
+| Function | Type |
+| ---------- | ---------- |
+| `useStartSync` | `({ projectId }: { projectId: string; }) => { mutate: UseMutateFunction<void, Error, { autostopDataSyncAfter: number or null; } or undefined, unknown>; reset: () => void; status: "pending" or ... 2 more ... or "idle"; }` |
+
+### useStopSync
+
+| Function | Type |
+| ---------- | ---------- |
+| `useStopSync` | `({ projectId }: { projectId: string; }) => { mutate: UseMutateFunction<void, Error, void, unknown>; reset: () => void; status: "pending" or "error" or "success" or "idle"; }` |
+
 ### useSingleDocByDocId
 
 Retrieve a single document from the database based on the document's document ID.
@@ -678,3 +760,28 @@ function ExampleWithRefreshToken() {
 | `ClientApiContext` | `Context<MapeoClientApi or null>` |
 
 
+
+## Types
+
+- [WriteableDocumentType](#writeabledocumenttype)
+- [WriteableValue](#writeablevalue)
+- [WriteableDocument](#writeabledocument)
+
+### WriteableDocumentType
+
+| Type | Type |
+| ---------- | ---------- |
+| `WriteableDocumentType` | `Extract< MapeoDoc['schemaName'], 'field' or 'observation' or 'preset' or 'track' or 'remoteDetectionAlert' >` |
+
+### WriteableValue
+
+| Type | Type |
+| ---------- | ---------- |
+| `WriteableValue` | `Extract< MapeoValue, { schemaName: D } >` |
+
+### WriteableDocument
+
+| Type | Type |
+| ---------- | ---------- |
+| `WriteableDocument` | `Extract< MapeoDoc, { schemaName: D } >` |
+

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@comapeo/core-react",
-	"version": "2.0.1",
+	"version": "3.1.0",
 	"description": "React wrapper for working with @comapeo/core",
 	"repository": {
 		"type": "git",
@@ -35,7 +35,6 @@
 	"types": "./dist/commonjs/index.d.ts",
 	"module": "./dist/esm/index.js",
 	"files": [
-		"CHANGELOG.md",
 		"dist/",
 		"docs/API.md"
 	],
@@ -48,16 +47,14 @@
 		}
 	},
 	"scripts": {
-		"prepare:husky": "husky",
-		"prepare:tshy": "tshy",
-		"prepare": "npm-run-all --parallel prepare:*",
+		"docs:generate": "tsdoc --src=src/contexts/*,src/hooks/*,src/lib/types.ts --dest=docs/API.md --noemoji --types",
 		"lint:eslint": "eslint --cache .",
 		"lint:format": "prettier --cache --check .",
 		"lint": "npm-run-all --parallel --continue-on-error --print-label --aggregate-output lint:*",
-		"types": "tsc",
-		"test:unit": "vitest run",
-		"test": "npm-run-all --parallel --continue-on-error --print-label --aggregate-output types test:*",
-		"docs:generate": "tsdoc --src=src/contexts/*,src/hooks/* --dest=docs/API.md --noemoji --types"
+		"prepack": "tshy",
+		"prepare": "husky",
+		"test": "vitest run",
+		"types": "tsc"
 	},
 	"peerDependencies": {
 		"@comapeo/core": "*",
@@ -67,34 +64,33 @@
 		"react": "^18 || ^19"
 	},
 	"devDependencies": {
-		"@comapeo/core": "2.3.0",
-		"@comapeo/schema": "1.3.0",
-		"@eslint/compat": "1.2.5",
-		"@eslint/js": "9.18.0",
+		"@comapeo/core": "2.3.1",
+		"@comapeo/ipc": "2.1.0",
+		"@comapeo/schema": "1.4.1",
+		"@eslint/compat": "1.2.7",
+		"@eslint/js": "9.23.0",
 		"@ianvs/prettier-plugin-sort-imports": "4.4.1",
 		"@mapeo/crypto": "1.0.0-alpha.10",
-		"@tanstack/eslint-plugin-query": "5.62.16",
-		"@tanstack/react-query": "5.64.1",
+		"@tanstack/eslint-plugin-query": "5.68.0",
+		"@tanstack/react-query": "5.69.0",
 		"@testing-library/dom": "10.4.0",
-		"@testing-library/react": "16.1.0",
-		"@types/lint-staged": "13.3.0",
-		"@types/node": "22.10.5",
-		"@types/react": "19.0.6",
-		"@types/react-dom": "19.0.3",
-		"commit-and-tag-version": "12.5.0",
-		"eslint": "9.18.0",
+		"@testing-library/react": "16.2.0",
+		"@types/node": "22.13.13",
+		"@types/react": "19.0.12",
+		"@types/react-dom": "19.0.4",
+		"eslint": "9.23.0",
 		"fastify": "4.29.0",
-		"globals": "15.14.0",
+		"globals": "16.0.0",
 		"husky": "9.1.7",
-		"lint-staged": "15.3.0",
+		"lint-staged": "15.5.0",
 		"npm-run-all2": "7.0.2",
-		"prettier": "3.4.2",
+		"prettier": "3.5.3",
 		"random-access-memory": "6.2.1",
 		"react": "19.0.0",
-		"tsdoc-markdown": "1.1.0",
+		"tsdoc-markdown": "1.2.0",
 		"tshy": "3.0.2",
-		"typescript": "5.7.3",
-		"typescript-eslint": "8.20.0",
-		"vitest": "2.1.8"
+		"typescript": "5.8.2",
+		"typescript-eslint": "8.27.0",
+		"vitest": "3.0.9"
 	}
 }