@comapeo/core-react 8.0.0 → 9.0.0

package/dist/esm/lib/map-shares-stores.js

@@ -0,0 +1,291 @@
+import { CUSTOM_MAP_ID } from '@comapeo/map-server/constants.js';
+import { errors } from '@comapeo/map-server/errors.js';
+import ensureError from 'ensure-error';
+import { invalidateMapQueries } from './react-query/maps.js';
+// ============================================
+// ACTION OPTIONS TYPES
+// These are defined here so that VSCode tooltips work for the mutation
+// functions - if the documentation comments are added inline for the store
+// actions, they do not show for the mutate() function in hooks.
+// ============================================
+/** Known reasons for declining a map share */
+export const DeclineReason = {
+    /** User explicitly rejected the map share */
+    user_rejected: 'user_rejected',
+    /** Device storage is full */
+    storage_full: 'storage_full',
+};
+/**
+ * This is like a mini zustand store. Keeping the map shares in an external
+ * store avoids unnecessary re-renders of the entire app when map shares are
+ * updated (e.g. if we kept the state in the context), and it avoids potential
+ * tearing issues with concurrent rendering.
+ *
+ * This is the base store for both sent and received map shares, since they
+ * share a lot of logic around managing the map shares and monitoring their
+ * status.
+ */
+function createMapSharesStore({ mapServerApi }) {
+    let mapShares = [];
+    const listeners = new Set();
+    function update(shareId, stateUpdate) {
+        const index = mapShares.findIndex((s) => s.shareId === shareId);
+        const existing = mapShares[index];
+        if (!existing) {
+            throw new errors.MAP_SHARE_NOT_FOUND(`Map share with id ${shareId} not found`);
+        }
+        assertValidStatusTransition(existing.status, stateUpdate.status);
+        mapShares[index] = { ...existing, ...stateUpdate };
+        const isDownloadProgressUpdate = stateUpdate.status === 'downloading' && existing.status === 'downloading';
+        // IMPORTANT: For download progress updates, the store state is mutated, so
+        // maintains Object.is equality. This means that components listening to the
+        // store state without a selector _will not update_ when download progress
+        // updates. However, all other updates will result in a re-render, and using
+        // a selector to listen to an individual map share will also update during
+        // download progress.
+        if (!isDownloadProgressUpdate) {
+            mapShares = [...mapShares];
+        }
+        emit();
+    }
+    function add(mapShare) {
+        mapShares = [...mapShares, mapShare];
+        emit();
+    }
+    function get(shareId) {
+        const mapShare = mapShares.find((share) => share.shareId === shareId);
+        if (!mapShare) {
+            throw new errors.MAP_SHARE_NOT_FOUND(`Map share with id ${shareId} not found`);
+        }
+        return mapShare;
+    }
+    function handleError(shareId, cause) {
+        const error = ensureError(cause);
+        const errorCode = 'code' in error ? String(error.code) : 'UNKNOWN_ERROR';
+        try {
+            update(shareId, {
+                status: 'error',
+                error: {
+                    message: error.message,
+                    code: errorCode,
+                },
+            });
+        }
+        catch (e) {
+            // TODO: log errors with Sentry
+            console.error(`Failed to update map share ${shareId} with error ${errorCode}:`, e);
+        }
+    }
+    async function monitor(mapShareId, path) {
+        // TODO: add a timeout in case the download stalls and never completes
+        return new Promise((resolve, reject) => {
+            const es = mapServerApi.createEventSource({
+                url: path,
+                onMessage({ data }) {
+                    try {
+                        const stateUpdate = JSON.parse(data);
+                        update(mapShareId, stateUpdate);
+                        if (isFinalStatus(stateUpdate.status)) {
+                            es.close();
+                            resolve(stateUpdate);
+                        }
+                    }
+                    catch (e) {
+                        // NB: Don't handleError here - because we optimistically update the
+                        // status, some of the updates from the event source will throw for
+                        // being an invalid status transition, but we can just ignore those
+                        // errors.
+                        // TODO: Custom errors for status transitions, and only ignore those
+                        es.close();
+                        reject(e);
+                    }
+                },
+            });
+        });
+    }
+    function emit() {
+        listeners.forEach((l) => l());
+    }
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        getSnapshot() {
+            return mapShares;
+        },
+        update,
+        add,
+        get,
+        handleError,
+        monitor,
+    };
+}
+/**
+ * Store and actions for received map shares.
+ */
+export function createReceivedMapSharesStore({ clientApi, mapServerApi, queryClient, }) {
+    const { subscribe, getSnapshot, update, add, get, handleError, monitor } = createMapSharesStore({ mapServerApi });
+    // Tracks downloads in progress so they can be aborted. Currently there is no
+    // cleanup, but this is unlikely to be an issue in practice.
+    const downloads = new Map();
+    clientApi.on('map-share', (mapShare) => {
+        add({ ...mapShare, status: 'pending' });
+    });
+    const actions = {
+        async download({ shareId }) {
+            const mapShare = get(shareId);
+            update(shareId, { status: 'downloading', bytesDownloaded: 0 });
+            try {
+                const downloadIdPromise = mapServerApi
+                    .post(`downloads`, {
+                    json: {
+                        senderDeviceId: mapShare.senderDeviceId,
+                        shareId: mapShare.shareId,
+                        mapShareUrls: mapShare.mapShareUrls,
+                        estimatedSizeBytes: mapShare.estimatedSizeBytes,
+                    },
+                })
+                    .json()
+                    .then(({ downloadId }) => downloadId);
+                // Not strictly necessary, because the `await downloadIdPromise` in the
+                // same tick below ensures that this is handled, but this protects
+                // against a refactor which could add another async function between
+                // setting the promise on the map and awaiting the downloadIdPromise,
+                // which would result in an unhandled rejection without this.
+                downloadIdPromise.catch(noop);
+                downloads.set(shareId, downloadIdPromise);
+                const downloadId = await downloadIdPromise;
+                monitor(shareId, `downloads/${downloadId}/events`)
+                    .then((stateUpdate) => {
+                    downloads.delete(shareId);
+                    // Invalidate map queries when download completes to trigger reload of map
+                    if (stateUpdate.status === 'completed') {
+                        return invalidateMapQueries(queryClient, {
+                            mapId: mapShare.mapId,
+                        });
+                    }
+                })
+                    .catch(noop);
+            }
+            catch (e) {
+                downloads.delete(shareId);
+                handleError(shareId, e);
+                throw e;
+            }
+        },
+        async decline({ shareId, reason }) {
+            const mapShare = get(shareId);
+            update(shareId, { status: 'declined', reason });
+            try {
+                await mapServerApi.post(`mapShares/${shareId}/decline`, {
+                    json: {
+                        senderDeviceId: mapShare.senderDeviceId,
+                        mapShareUrls: mapShare.mapShareUrls,
+                        reason,
+                    },
+                });
+            }
+            catch (e) {
+                handleError(shareId, e);
+                throw e;
+            }
+        },
+        async abort({ shareId }) {
+            update(shareId, { status: 'aborted' });
+            try {
+                const downloadId = await downloads.get(shareId);
+                if (!downloadId) {
+                    throw new errors.DOWNLOAD_NOT_FOUND(`No download in progress for map share with id ${shareId}`);
+                }
+                await mapServerApi.post(`downloads/${downloadId}/abort`);
+            }
+            catch (e) {
+                handleError(shareId, e);
+                throw e;
+            }
+            finally {
+                downloads.delete(shareId);
+            }
+        },
+    };
+    return {
+        subscribe,
+        getSnapshot,
+        actions,
+    };
+}
+/**
+ * Store and actions for sent map share.
+ */
+export function createSentMapSharesStore({ clientApi, mapServerApi, }) {
+    const { subscribe, getSnapshot, update, add, handleError, monitor } = createMapSharesStore({ mapServerApi });
+    const actions = {
+        async createAndSend({ projectId, receiverDeviceId, mapId = CUSTOM_MAP_ID, }) {
+            const mapShare = await mapServerApi
+                .post('mapShares', {
+                json: { receiverDeviceId, mapId },
+            })
+                .json();
+            try {
+                const project = await clientApi.getProject(projectId);
+                await project.$sendMapShare(mapShare);
+            }
+            catch (e) {
+                await mapServerApi.post(`mapShares/${mapShare.shareId}/cancel`);
+                throw e;
+            }
+            add(mapShare);
+            monitor(mapShare.shareId, `mapShares/${mapShare.shareId}/events`).catch(noop);
+            return mapShare;
+        },
+        async cancel({ shareId }) {
+            update(shareId, { status: 'canceled' });
+            try {
+                await mapServerApi.post(`mapShares/${shareId}/cancel`);
+            }
+            catch (e) {
+                handleError(shareId, e);
+                throw e;
+            }
+        },
+    };
+    return {
+        subscribe,
+        getSnapshot,
+        actions,
+    };
+}
+const allowedStatusTransitions = {
+    pending: ['pending', 'downloading', 'declined', 'canceled', 'error'],
+    downloading: ['downloading', 'aborted', 'completed', 'canceled', 'error'],
+    completed: ['error'],
+    canceled: ['error'],
+    aborted: ['error'],
+    declined: ['error'],
+    error: ['error'],
+};
+/**
+ * Asserts that the transition from current to next status is valid. Throws if
+ * the transition is invalid.
+ */
+function assertValidStatusTransition(current, next) {
+    if (!allowedStatusTransitions[current].includes(next)) {
+        throw new Error(`Invalid status transition from ${current} to ${next}`);
+    }
+}
+const finalStatuses = [
+    'declined',
+    'canceled',
+    'aborted',
+    'completed',
+    'error',
+];
+/**
+ * Returns true if the status is a final status, meaning that no further updates
+ * should be expected for the map share.
+ */
+function isFinalStatus(status) {
+    return finalStatuses.includes(status);
+}
+function noop() { }

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

@@ -1,26 +1,72 @@
-import type { MapeoClientApi } from '@comapeo/ipc' with {
-    'resolution-mode': 'import'
+import { type QueryClient, type UseMutationOptions } from '@tanstack/react-query';
+import type { MapServerApi } from '../../contexts/MapServer.js';
+import type { ReceivedMapSharesStore, SentMapSharesStore } from '../map-shares-stores.js';
+type CompatFile = Omit<File, 'lastModified' | 'webkitRelativePath'>;
+type ExpoFileDuckType = CompatFile & {
+    exists: boolean;
 };
-export declare function getMapsQueryKey(): readonly ["@comapeo/core-react", "maps"];
-export declare function getStyleJsonUrlQueryKey({ refreshToken, }: {
-    refreshToken?: string;
-}): readonly ["@comapeo/core-react", "maps", "stylejson_url", {
-    readonly refreshToken: string | undefined;
-}];
-export declare function mapStyleJsonUrlQueryOptions({ clientApi, refreshToken, }: {
-    clientApi: MapeoClientApi;
-    refreshToken?: string;
-}): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<string, Error, string, readonly ["@comapeo/core-react", "maps", "stylejson_url", {
-    readonly refreshToken: string | undefined;
-}]>, "queryFn"> & {
-    queryFn?: import("@tanstack/react-query").QueryFunction<string, readonly ["@comapeo/core-react", "maps", "stylejson_url", {
-        readonly refreshToken: string | undefined;
-    }], never> | undefined;
+export declare function getMapQueryKey({ mapId }: {
+    mapId: string;
+}): readonly ["@comapeo/core-react", "maps", string];
+export declare function getStyleJsonUrlQueryKey({ mapId }: {
+    mapId: string;
+}): readonly ["@comapeo/core-react", "maps", string, "stylejson_url"];
+/**
+ * Invalidate queries for this map and the default map (which internally
+ * redirects to custom) so that they will be refetched with the new map data.
+ */
+export declare function invalidateMapQueries(queryClient: QueryClient, { mapId }: {
+    mapId: string;
+}): Promise<void>;
+export declare function mapStyleJsonUrlQueryOptions({ mapServerApi, mapId, }: {
+    mapServerApi: MapServerApi;
+    mapId?: string;
+}): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<string, Error, string, readonly ["@comapeo/core-react", "maps", string, "stylejson_url"]>, "queryFn"> & {
+    queryFn?: import("@tanstack/react-query").QueryFunction<string, readonly ["@comapeo/core-react", "maps", string, "stylejson_url"], never> | undefined;
 } & {
-    queryKey: readonly ["@comapeo/core-react", "maps", "stylejson_url", {
-        readonly refreshToken: string | undefined;
-    }] & {
+    queryKey: readonly ["@comapeo/core-react", "maps", string, "stylejson_url"] & {
         [dataTagSymbol]: string;
         [dataTagErrorSymbol]: Error;
     };
 };
+export declare function mapInfoQueryOptions({ mapServerApi, mapId, }: {
+    mapServerApi: MapServerApi;
+    mapId?: string;
+}): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<unknown, Error, unknown, readonly ["@comapeo/core-react", "maps", string, "info"]>, "queryFn"> & {
+    queryFn?: import("@tanstack/react-query").QueryFunction<unknown, readonly ["@comapeo/core-react", "maps", string, "info"], never> | undefined;
+} & {
+    queryKey: readonly ["@comapeo/core-react", "maps", string, "info"] & {
+        [dataTagSymbol]: unknown;
+        [dataTagErrorSymbol]: Error;
+    };
+};
+export declare function mapImportMutationOptions({ mapServerApi, queryClient, }: {
+    mapServerApi: MapServerApi;
+    queryClient: QueryClient;
+}): {
+    mutationFn: ({ file }: {
+        file: File | ExpoFileDuckType;
+    }) => Promise<Response>;
+    onSuccess: () => Promise<void>;
+    networkMode: "always";
+    retry: false;
+};
+export declare function mapRemoveMutationOptions({ mapServerApi, queryClient, }: {
+    mapServerApi: MapServerApi;
+    queryClient: QueryClient;
+}): {
+    mutationFn: () => Promise<Response>;
+    onSuccess: () => Promise<void>;
+    networkMode: "always";
+    retry: false;
+};
+/**
+ * Mutation options for actions on sent map shares
+ */
+export declare function mapSharesMutationOptions<TAction extends SentMapSharesStore['actions'][keyof SentMapSharesStore['actions']] | keyof ReceivedMapSharesStore['actions'][keyof ReceivedMapSharesStore['actions']]>(options: {
+    action: Exclude<TAction, SentMapSharesStore['actions']['createAndSend']>;
+} | {
+    action: SentMapSharesStore['actions']['createAndSend'];
+    projectId: string;
+}): UseMutationOptions<ReturnType<TAction>, Error, TAction extends SentMapSharesStore['actions']['createAndSend'] ? Parameters<TAction>[0] : Omit<Parameters<TAction>[0], 'projectId'>>;
+export {};

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

@@ -1,22 +1,119 @@
-import { queryOptions } from '@tanstack/react-query';
-import { baseQueryOptions, ROOT_QUERY_KEY } from './shared.js';
-export function getMapsQueryKey() {
-    return [ROOT_QUERY_KEY, 'maps'];
+import { CUSTOM_MAP_ID, DEFAULT_MAP_ID } from '@comapeo/map-server/constants.js';
+import { queryOptions, } from '@tanstack/react-query';
+import { baseMutationOptions, baseQueryOptions, ROOT_QUERY_KEY, } from './shared.js';
+// ============================================
+// QUERY KEYS
+// ============================================
+const MAPS_ROOT_QUERY_KEY = [ROOT_QUERY_KEY, 'maps'];
+export function getMapQueryKey({ mapId }) {
+    return [...MAPS_ROOT_QUERY_KEY, mapId];
 }
-export function getStyleJsonUrlQueryKey({ refreshToken, }) {
-    return [ROOT_QUERY_KEY, 'maps', 'stylejson_url', { refreshToken }];
+export function getStyleJsonUrlQueryKey({ mapId }) {
+    return [...getMapQueryKey({ mapId }), 'stylejson_url'];
 }
-export function mapStyleJsonUrlQueryOptions({ clientApi, refreshToken, }) {
+/**
+ * Invalidate queries for this map and the default map (which internally
+ * redirects to custom) so that they will be refetched with the new map data.
+ */
+export async function invalidateMapQueries(queryClient, { mapId }) {
+    await Promise.all([
+        queryClient.invalidateQueries({
+            queryKey: getMapQueryKey({ mapId }),
+        }),
+        queryClient.invalidateQueries({
+            queryKey: getMapQueryKey({ mapId: DEFAULT_MAP_ID }),
+        }),
+    ]);
+}
+// ============================================
+// QUERY OPTIONS
+// ============================================
+export function mapStyleJsonUrlQueryOptions({ mapServerApi, mapId = DEFAULT_MAP_ID, }) {
+    if (mapId !== DEFAULT_MAP_ID) {
+        throw new Error('Custom map IDs are not supported yet');
+    }
     return queryOptions({
         ...baseQueryOptions(),
-        queryKey: getStyleJsonUrlQueryKey({ refreshToken }),
+        queryKey: getStyleJsonUrlQueryKey({ mapId }),
         queryFn: async () => {
-            const result = await clientApi.getMapStyleJsonUrl();
-            if (!refreshToken)
-                return result;
+            const result = await mapServerApi.getMapStyleJsonUrl(mapId);
             const u = new URL(result);
-            u.searchParams.set('refresh_token', refreshToken);
+            // This ensures that every time this query is refetched, it will have a different search param, forcing the map to reload.
+            u.searchParams.set('refresh_token', Date.now().toString());
             return u.href;
         },
+        // Keep this cached until the cache is manually invalidated by a map upload
+        staleTime: Infinity,
+        gcTime: Infinity,
+    });
+}
+export function mapInfoQueryOptions({ mapServerApi, mapId = DEFAULT_MAP_ID, }) {
+    if (mapId !== CUSTOM_MAP_ID) {
+        throw new Error('Only custom map ID is currently supported');
+    }
+    return queryOptions({
+        ...baseQueryOptions(),
+        queryKey: [...getMapQueryKey({ mapId }), 'info'],
+        queryFn: async () => {
+            return mapServerApi.get(`maps/${mapId}/info`).json();
+        },
+        // Keep this cached until the cache is manually invalidated by a map upload
+        staleTime: Infinity,
+        gcTime: Infinity,
     });
 }
+// ============================================
+// MUTATION OPTIONS
+// ============================================
+export function mapImportMutationOptions({ mapServerApi, queryClient, }) {
+    // TODO: Support importing to custom map IDs, to support multiple maps.
+    const mapId = CUSTOM_MAP_ID;
+    return {
+        ...baseMutationOptions(),
+        mutationFn: async ({ file }) => {
+            if ('exists' in file && !file.exists) {
+                throw new Error('File does not exist or is not accessible');
+            }
+            return mapServerApi.put(`maps/${mapId}`, {
+                body: file,
+                headers: {
+                    'Content-Type': 'application/octet-stream',
+                },
+            });
+        },
+        onSuccess: async () => {
+            await invalidateMapQueries(queryClient, { mapId });
+        },
+    };
+}
+export function mapRemoveMutationOptions({ mapServerApi, queryClient, }) {
+    // TODO: Support removing from custom map IDs, to support multiple maps.
+    const mapId = CUSTOM_MAP_ID;
+    return {
+        ...baseMutationOptions(),
+        mutationFn: async () => {
+            return mapServerApi.delete(`maps/${mapId}`);
+        },
+        onSuccess: async () => {
+            await invalidateMapQueries(queryClient, { mapId });
+        },
+    };
+}
+/**
+ * Mutation options for actions on sent map shares
+ */
+export function mapSharesMutationOptions(options) {
+    return {
+        ...baseMutationOptions(),
+        mutationFn: async (variables) => {
+            // For consistency with other hooks, we use `projectId` as a parameter of
+            // the hook, rather than a parameter of the mutate function.
+            const actionOptions = 'projectId' in options
+                ? { ...variables, projectId: options.projectId }
+                : variables;
+            return options.action(
+            // @ts-expect-error - TS can't help us here
+            actionOptions);
+        },
+    };
+}

package/dist/esm/lib/react-query/mutation-result.d.ts

@@ -0,0 +1,8 @@
+import type { UseMutationResult } from '@tanstack/react-query';
+import type { DistributedPick } from 'type-fest';
+/**
+ * Filters a `UseMutationResult` to only include a subset of its keys, and uses
+ * `DistributedPick` to preserve the discriminated union types of the mutation
+ * result based on the `status` property.
+ */
+export declare function filterMutationResult<TResult extends UseMutationResult<any, any, any, any>>(mutationResult: TResult): DistributedPick<TResult, "error" | "status" | "mutate" | "reset" | "mutateAsync">;

package/dist/esm/lib/react-query/mutation-result.js

@@ -0,0 +1,19 @@
+const PICKED_MUTATION_RESULT_KEYS = [
+    'error',
+    'mutate',
+    'mutateAsync',
+    'reset',
+    'status',
+];
+/**
+ * Filters a `UseMutationResult` to only include a subset of its keys, and uses
+ * `DistributedPick` to preserve the discriminated union types of the mutation
+ * result based on the `status` property.
+ */
+export function filterMutationResult(mutationResult) {
+    const filteredResult = {};
+    for (const key of PICKED_MUTATION_RESULT_KEYS) {
+        filteredResult[key] = mutationResult[key];
+    }
+    return filteredResult;
+}