@convex-dev/geospatial/dist/client/index.d.ts

A geospatial index for Convex

import type { FunctionReference, FunctionReturnType, OptionalRestArgs } from "convex/server";
import type { Point, Primitive, Rectangle } from "../component/types.js";
import { point, rectangle } from "../component/types.js";
import type { LogLevel } from "../component/lib/logging.js";
import { type GeospatialQuery } from "./query.js";
import type { ComponentApi } from "../component/_generated/component.js";
export type { Point, Primitive, GeospatialQuery, Rectangle };
export { point, rectangle };
declare global {
    const Convex: Record<string, unknown>;
}
export declare const DEFAULT_MIN_LEVEL = 4;
export declare const DEFAULT_MAX_LEVEL = 16;
export declare const DEFAULT_MAX_CELLS = 8;
export declare const DEFAULT_LEVEL_MOD = 2;
export type GeospatialFilters = Record<string, Primitive | Primitive[]>;
export type GeospatialDocument<Key extends string = string, Filters extends GeospatialFilters = GeospatialFilters> = {
    key: Key;
    coordinates: Point;
    filterKeys: Filters;
    sortKey: number;
};
export type NearestQueryOptions<Doc extends GeospatialDocument = GeospatialDocument> = {
    point: Point;
    limit: number;
    maxDistance?: number;
    filter?: NonNullable<GeospatialQuery<Doc>["filter"]>;
};
/**
 * @deprecated Use `NearestQueryOptions` with `nearest` instead.
 */
export type QueryNearestOptions<Doc extends GeospatialDocument = GeospatialDocument> = Pick<NearestQueryOptions<Doc>, "maxDistance" | "filter">;
export interface GeospatialIndexOptions {
    /**
     * The minimum S2 cell level to use when querying. Defaults to 4.
     */
    minLevel?: number;
    /**
     * The maximum S2 cell level to use when querying. Defaults to 16.
     */
    maxLevel?: number;
    /**
     * The distance between levels when indexing, implying a branching factor of `4^levelMod`. Defaults to 2.
     */
    levelMod?: number;
    /**
     * The maximum number of cells to use when querying. Defaults to 8.
     */
    maxCells?: number;
    /**
     * The log level to use when logging. Defaults to the `GEOSPATIAL_LOG_LEVEL` environment variable, or "INFO" if not set.
     */
    logLevel?: LogLevel;
}
export declare class GeospatialIndex<Key extends string = string, Filters extends GeospatialFilters = GeospatialFilters> {
    private component;
    logLevel: LogLevel;
    minLevel: number;
    maxLevel: number;
    levelMod: number;
    maxCells: number;
    /**
     * Create a new geospatial index, powered by S2 and Convex. This index maps unique string keys to geographic coordinates
     * on the Earth's surface, with the ability to efficiently query for all keys within a given geographic area.
     *
     * @param component - The registered geospatial index from `components`.
     * @param options - The options to configure the index.
     */
    constructor(component: ComponentApi, options?: GeospatialIndexOptions);
    /**
     * Insert a new key-coordinate pair into the index.
     *
     * @param ctx - The Convex mutation context.
     * @param key - The unique string key to associate with the coordinate.
     * @param coordinates - The geographic coordinate `{ latitude, longitude }` to associate with the key.
     * @param filterKeys - The filter keys to associate with the key.
     * @param sortKey - The sort key to associate with the key, defaults to a randomly generated number.
     */
    insert(ctx: MutationCtx, key: Key, coordinates: Point, filterKeys: Filters, sortKey?: number): Promise<void>;
    /**
     * Retrieve the coordinate associated with a specific key.
     *
     * @param ctx - The Convex query context.
     * @param key - The unique string key to retrieve the coordinate for.
     * @returns - The geographic coordinate `{ latitude, longitude }` associated with the key, or `null` if the key is not found.
     */
    get(ctx: QueryCtx, key: Key): Promise<GeospatialDocument<Key, Filters> | null>;
    /**
     * Remove a key-coordinate pair from the index.
     *
     * @param ctx - The Convex mutation context.
     * @param key - The unique string key to remove from the index.
     * @returns - `true` if the key was found and removed, `false` otherwise.
     */
    remove(ctx: MutationCtx, key: Key): Promise<boolean>;
    /**
     * Query for keys within a given shape.
     *
     * @param ctx - The Convex query context.
     * @param query - The query to execute.
     * @param cursor - The continuation cursor to use for paginating through results.
     * @returns - An array of objects with the key-coordinate pairs and optionally a continuation cursor.
     */
    query(ctx: QueryCtx, query: GeospatialQuery<GeospatialDocument<Key, Filters>>, cursor?: string | undefined): Promise<{
        results: {
            key: Key;
            coordinates: Point;
        }[];
        nextCursor?: string;
    }>;
    /**
     * Query for the nearest points to a given point.
     *
     * @param ctx - The Convex query context.
     * @param options - The nearest query parameters.
     * @returns - An array of objects with the key-coordinate pairs and their distance from the query point in meters.
     */
    nearest(ctx: QueryCtx, { point, limit, maxDistance, filter, }: NearestQueryOptions<GeospatialDocument<Key, Filters>>): Promise<{
        key: Key;
        coordinates: Point;
        distance: number;
    }[]>;
    /**
     * Query for the nearest points to a given point.
     *
     * @deprecated Use `nearest(ctx, { point, limit, maxDistance, filter })` instead.
     */
    queryNearest(ctx: QueryCtx, point: Point, maxResults: number, maxDistance?: number): Promise<{
        key: Key;
        coordinates: Point;
        distance: number;
    }[]>;
    /**
     * Debug the S2 cells that would be queried for a given rectangle.
     *
     * @param ctx - The Convex query context.
     * @param rectangle - The geographic area to query.
     * @param maxResolution - The maximum resolution to use when querying.
     * @returns - An array of S2 cell identifiers and their vertices.
     */
    debugCells(ctx: QueryCtx, rectangle: Rectangle, maxResolution?: number): Promise<{
        token: string;
        vertices: Point[];
    }[]>;
}
export type FilterValue<Doc extends GeospatialDocument, FieldName extends keyof Doc["filterKeys"]> = ExtractArray<Doc["filterKeys"][FieldName]>;
type QueryCtx = {
    runQuery: <Query extends FunctionReference<"query", "public" | "internal">>(query: Query, ...args: OptionalRestArgs<Query>) => Promise<FunctionReturnType<Query>>;
};
type MutationCtx = {
    runMutation: <Mutation extends FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: OptionalRestArgs<Mutation>) => Promise<FunctionReturnType<Mutation>>;
} & QueryCtx;
export type FilterObject<Doc extends GeospatialDocument> = {
    [K in keyof Doc["filterKeys"] & string]: {
        filterKey: K;
        filterValue: ExtractArray<Doc["filterKeys"][K]>;
        occur: "should" | "must";
    };
}[keyof Doc["filterKeys"] & string];
type ExtractArray<T> = T extends (infer U)[] ? U : T;
//# sourceMappingURL=index.d.ts.map