@lunora/server 1.0.0-alpha.3 → 1.0.0-alpha.30

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -93,8 +93,58 @@ The builder chain is `<builder>.input(validators).<kind>(handler)`, plus `.use(m
 
 > **Determinism:** `query` and `mutation` handlers must be deterministic — they may be re-run on OCC retry or subscription re-evaluation. Read the current time from **`ctx.now`** (epoch ms, captured once per execution — also on `ActionCtx`) instead of `Date.now()`; compute randomness and network results in an `action` (`crypto.randomUUID()`, `fetch`) and pass them into the mutation as arguments. The `nondeterministic_query_mutation` advisor flags `Date.now()`/`Math.random()`/`fetch` in query/mutation handlers.
 
+### Local-first sync engine
+
+`defineShape` declares a **partial replication shape** (a named table view with a server-resolved `where` predicate, AND-composed with RLS) and `defineMutator` declares a **custom mutator** (an authoritative `server` impl plus an optional optimistic `client` twin). Both are discovered by codegen and drive the [local-first sync engine](https://lunora.sh/docs/concepts/local-first) — clients subscribe to shapes over the poke diff protocol and push optimistic writes rebased over the server's authoritative result. The client-side runtime lives in [`@lunora/db`](https://www.npmjs.com/package/@lunora/db).
+
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/packages/server)**.
 
+### Caching with Workers Cache
+
+Lunora supports Cloudflare Workers Cache for HTTP actions (`httpRoute`). RPC queries and mutations are `POST /_lunora/rpc` and are not cacheable at the edge by design.
+
+**Enable Workers Cache** in `wrangler.jsonc`:
+
+```jsonc
+{
+    "cache": { "enabled": true },
+}
+```
+
+The dev server and CLI automatically bump `compatibility_date` to the minimum required when cache is enabled — you do not need to set it manually.
+
+**Set cache headers declaratively** on an `httpRoute`:
+
+```ts
+import { httpRoute } from "./_generated/server";
+
+export const getProduct = httpRoute
+    .get("/api/products/:id")
+    .params({ id: v.string() })
+    .cacheControl("public, max-age=300, stale-while-revalidate=3600")
+    .cacheTag("products")
+    .handler(async ({ ctx, params }) => {
+        return { id: params.id, name: "Widget" };
+    });
+```
+
+**Purge cache by tag** from an action handler:
+
+```ts
+import { action } from "./_generated/server";
+
+export const refreshProducts = action.action(async ({ ctx }) => {
+    if (!ctx.cache) {
+        throw new Error("Workers Cache is not enabled in wrangler.jsonc");
+    }
+
+    await ctx.cache.purge({ tags: ["products"] });
+    return { ok: true };
+});
+```
+
+The `ctx.cache.purge` API accepts `{ tags?: string[]; purgeEverything?: boolean }`. Only action handlers expose `ctx.cache`; queries and mutations run inside the Durable Object and do not have access to the Worker-level cache binding.
+
 ## Related
 
 - [`@lunora/values`](https://www.npmjs.com/package/@lunora/values) — the `v.*` validators re-exported here.

package/dist/data-model.d.mts

@@ -1,25 +1,25 @@
 /**
-* Schema-independent type machinery for the generated data model.
-*
-* `@lunora/codegen` emits `lunora/_generated/dataModel.ts` with the
-* schema-specific pieces (the per-table `Doc_*` / `Insert_*` interfaces, the
-* `DataModel` / `Relations` / index-name maps) and then binds the generics
-* below to them. Everything here is identical for every project, so it lives
-* in the shipped package rather than in generated output — evolving the query
-* DSL or the table-facade API no longer regenerates a single line of a user's
-* `_generated` directory.
-*
-* The generics are parameterized over the generated maps:
-* - `DM`   — `DataModel`: table name → document type
-* - `IM`   — `InsertModel`: table name → insert shape
-* - `REL`  — `Relations`: table name → relation-descriptor map
-* - `RANK` — `RankIndexNamesByTable`: table name → declared rank-index names
-* - `SEARCH` — `SearchIndexNamesByTable`: table name → declared search-index names
-*
-* Relation descriptors are matched structurally (`{ __relationKind; __target }`)
-* so this module needs no reference to the project-local `OneRelation` /
-* `ManyRelation` aliases the codegen still emits.
-*/
+ * Schema-independent type machinery for the generated data model.
+ *
+ * `@lunora/codegen` emits `lunora/_generated/dataModel.ts` with the
+ * schema-specific pieces (the per-table `Doc_*` / `Insert_*` interfaces, the
+ * `DataModel` / `Relations` / index-name maps) and then binds the generics
+ * below to them. Everything here is identical for every project, so it lives
+ * in the shipped package rather than in generated output — evolving the query
+ * DSL or the table-facade API no longer regenerates a single line of a user's
+ * `_generated` directory.
+ *
+ * The generics are parameterized over the generated maps:
+ * - `DM`   — `DataModel`: table name → document type
+ * - `IM`   — `InsertModel`: table name → insert shape
+ * - `REL`  — `Relations`: table name → relation-descriptor map
+ * - `RANK` — `RankIndexNamesByTable`: table name → declared rank-index names
+ * - `SEARCH` — `SearchIndexNamesByTable`: table name → declared search-index names
+ *
+ * Relation descriptors are matched structurally (`{ __relationKind; __target }`)
+ * so this module needs no reference to the project-local `OneRelation` /
+ * `ManyRelation` aliases the codegen still emits.
+ */
 /** A branded id for table `TName`. Structurally a `string` at runtime. */
 type Id<TName extends string> = string & {
   readonly __table: TName;
@@ -38,7 +38,7 @@ interface WhereOperators<T> {
   notIn?: T[];
 }
 /** A typed `where` tree over a document's columns. */
-type Where<TDocument> = { [K in keyof TDocument]?: TDocument[K] | WhereOperators<TDocument[K]> } & {
+type Where<TDocument> = { [K in keyof TDocument]?: TDocument[K] | WhereOperators<TDocument[K]>; } & {
   AND?: Where<TDocument>[];
   NOT?: Where<TDocument>;
   OR?: Where<TDocument>[];
@@ -50,53 +50,53 @@ interface QueryArgs<TDocument> {
   limit?: number;
   orderBy?: OrderBy<TDocument>[];
   /**
-  * Project each returned row down to these columns (plus the system fields
-  * `_id`/`_creationTime`, always retained). Trims wire payload for wide rows;
-  * relations requested via `with` are still attached. Reactivity is unaffected —
-  * the engine still reads the whole row to track dependencies.
-  */
+   * Project each returned row down to these columns (plus the system fields
+   * `_id`/`_creationTime`, always retained). Trims wire payload for wide rows;
+   * relations requested via `with` are still attached. Reactivity is unaffected —
+   * the engine still reads the whole row to track dependencies.
+   */
   select?: ReadonlyArray<keyof TDocument & string>;
   where?: Where<TDocument>;
 }
 /**
-* A to-one relation predicate node. `is` matches rows whose related record
-* satisfies `W`; `isNot` matches rows whose related record fails `W` *or* has
-* no related record at all (a null/dangling FK) — Prisma's semantics.
-*/
+ * A to-one relation predicate node. `is` matches rows whose related record
+ * satisfies `W`; `isNot` matches rows whose related record fails `W` *or* has
+ * no related record at all (a null/dangling FK) — Prisma's semantics.
+ */
 interface OneRelationWhere<W> {
   is?: W;
   isNot?: W;
 }
 /**
-* A to-many relation predicate node. `some` ⇒ at least one related row matches
-* `W`; `none` ⇒ no related row matches (childless parents included); `every` ⇒
-* every *readable* related row matches (vacuously true for childless parents).
-*/
+ * A to-many relation predicate node. `some` ⇒ at least one related row matches
+ * `W`; `none` ⇒ no related row matches (childless parents included); `every` ⇒
+ * every *readable* related row matches (vacuously true for childless parents).
+ */
 interface ManyRelationWhere<W> {
   every?: W;
   none?: W;
   some?: W;
 }
 /**
-* The relation-predicate portion of {@link WhereOf}: each declared relation on
-* `T` contributes a kind-dispatched node — `one` → `{ is?; isNot? }`, `many` →
-* `{ some?; none?; every? }` — whose inner type is the target table's own
-* relation-aware `where` (so multi-hop predicates type-check inside-out).
-*/
+ * The relation-predicate portion of {@link WhereOf}: each declared relation on
+ * `T` contributes a kind-dispatched node — `one` → `{ is?; isNot? }`, `many` →
+ * `{ some?; none?; every? }` — whose inner type is the target table's own
+ * relation-aware `where` (so multi-hop predicates type-check inside-out).
+ */
 type RelationWhere<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = { [K in keyof REL[T]]?: REL[T][K] extends {
   __relationKind: "one";
   __target: infer Target extends keyof DM;
 } ? OneRelationWhere<WhereOf<DM, REL, Target>> : REL[T][K] extends {
   __relationKind: "many";
   __target: infer Target extends keyof DM;
-} ? ManyRelationWhere<WhereOf<DM, REL, Target>> : never };
+} ? ManyRelationWhere<WhereOf<DM, REL, Target>> : never; };
 /**
-* Relation-aware `where` tree — the column predicates of {@link Where} plus
-* Prisma-style relation predicates resolved by the `@lunora/do` pre-resolver.
-* `Where&lt;DM[T]>` stays the column-only structural mirror for back-compat; the
-* table facade threads `REL` through this richer form.
-*/
-type WhereOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = RelationWhere<DM, REL, T> & { [K in keyof DM[T]]?: DM[T][K] | WhereOperators<DM[T][K]> } & {
+ * Relation-aware `where` tree — the column predicates of {@link Where} plus
+ * Prisma-style relation predicates resolved by the `@lunora/do` pre-resolver.
+ * `Where&lt;DM[T]>` stays the column-only structural mirror for back-compat; the
+ * table facade threads `REL` through this richer form.
+ */
+type WhereOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = RelationWhere<DM, REL, T> & { [K in keyof DM[T]]?: DM[T][K] | WhereOperators<DM[T][K]>; } & {
   AND?: WhereOf<DM, REL, T>[];
   NOT?: WhereOf<DM, REL, T>;
   OR?: WhereOf<DM, REL, T>[];
@@ -105,10 +105,10 @@ type WhereOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = Rel
 interface QueryArgsOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> {
   cursor?: null | string;
   /**
-  * Include soft-deleted rows (`.softDelete()` tables only). Default hides them;
-  * `true` returns deleted rows alongside live ones. No effect on a table
-  * without `.softDelete()`.
-  */
+   * Include soft-deleted rows (`.softDelete()` tables only). Default hides them;
+   * `true` returns deleted rows alongside live ones. No effect on a table
+   * without `.softDelete()`.
+   */
   includeDeleted?: boolean;
   limit?: number;
   orderBy?: OrderBy<DM[T]>[];
@@ -128,11 +128,11 @@ type NestedSelectArgument<WK> = WK extends {
   select: infer S;
 } ? S : undefined;
 /**
-* The `with` argument for table `T`: each relation can be `true` (load with no
-* refinements) or an object. `many` relations accept `where`/`orderBy`/`limit`/
-* `select` plus a nested `with`; `one` relations accept `select` + a nested
-* `with`. The reserved `_count` key requests per-relation aggregate counts.
-*/
+ * The `with` argument for table `T`: each relation can be `true` (load with no
+ * refinements) or an object. `many` relations accept `where`/`orderBy`/`limit`/
+ * `select` plus a nested `with`; `one` relations accept `select` + a nested
+ * `with`. The reserved `_count` key requests per-relation aggregate counts.
+ */
 type WithArg<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = { [K in keyof REL[T]]?: REL[T][K] extends {
   __relationKind: "many";
   __target: infer Target extends keyof DM;
@@ -144,15 +144,15 @@ type WithArg<DM, REL extends Record<keyof DM, object>, T extends keyof DM> = { [
 } ? boolean | {
   select?: ReadonlyArray<keyof DM[Target] & string>;
   with?: WithArg<DM, REL, Target>;
-} : never } & {
-  _count?: { [K in keyof REL[T]]?: true };
+} : never; } & {
+  _count?: { [K in keyof REL[T]]?: true; };
 };
 /**
-* Resolve a single relation descriptor + its with-value to the loaded type,
-* threading the nested `select` tuple into the projected child shape (the 5th
-* `LoadWith` arg) so `with: { author: { select: ["name"] } }` narrows the loaded
-* `author` to the selected columns + system fields.
-*/
+ * Resolve a single relation descriptor + its with-value to the loaded type,
+ * threading the nested `select` tuple into the projected child shape (the 5th
+ * `LoadWith` arg) so `with: { author: { select: ["name"] } }` narrows the loaded
+ * `author` to the selected columns + system fields.
+ */
 type LoadRelation<DM, REL extends Record<keyof DM, object>, R, WK> = R extends {
   __relationKind: "one";
   __target: infer Target extends keyof DM;
@@ -161,47 +161,47 @@ type LoadRelation<DM, REL extends Record<keyof DM, object>, R, WK> = R extends {
   __target: infer Target extends keyof DM;
 } ? LoadWith<DM, REL, Target, NestedWithArgument<WK>, NestedSelectArgument<WK>>[] : never;
 /** The relation keys of `W` that were actually requested (not `false`/`undefined`). */
-type LoadedRelations<DM, REL extends Record<keyof DM, object>, T extends keyof DM, W> = { [K in keyof W as K extends keyof REL[T] ? (W[K] extends false | undefined ? never : K) : never]: K extends keyof REL[T] ? LoadRelation<DM, REL, REL[T][K], W[K]> : never };
+type LoadedRelations<DM, REL extends Record<keyof DM, object>, T extends keyof DM, W> = { [K in keyof W as K extends keyof REL[T] ? (W[K] extends false | undefined ? never : K) : never]: K extends keyof REL[T] ? LoadRelation<DM, REL, REL[T][K], W[K]> : never; };
 /** The `_count` projection of `W`, if any. */
 type LoadedCount<W> = W extends {
   _count: infer C;
 } ? {
-  _count: { [K in keyof C]: number };
+  _count: { [K in keyof C]: number; };
 } : {};
 /** System columns a `select` projection always retains, so cursors and by-id reuse keep working. */
 type SelectAlwaysKeep<DM, T extends keyof DM> = ("_creationTime" | "_id") & keyof DM[T];
 /**
-* `DM[T]` narrowed to the columns named by a `select` tuple `S` (plus the system
-* fields). `undefined` (the default — no `select`) keeps the full document.
-*/
+ * `DM[T]` narrowed to the columns named by a `select` tuple `S` (plus the system
+ * fields). `undefined` (the default — no `select`) keeps the full document.
+ */
 type ProjectDoc<DM, T extends keyof DM, S> = S extends ReadonlyArray<infer K> ? (K extends keyof DM[T] ? Pick<DM[T], (K & keyof DM[T]) | SelectAlwaysKeep<DM, T>> : DM[T]) : DM[T];
 /**
-* `Doc&lt;T>` narrowed to exactly the relations requested in the with-arg `W` and,
-* when a `select` tuple `S` is supplied, to its projected columns. `S` defaults
-* to `undefined` so the 4-argument form (the codegen-emitted callers) keeps the
-* full document.
-*/
+ * `Doc&lt;T>` narrowed to exactly the relations requested in the with-arg `W` and,
+ * when a `select` tuple `S` is supplied, to its projected columns. `S` defaults
+ * to `undefined` so the 4-argument form (the codegen-emitted callers) keeps the
+ * full document.
+ */
 type LoadWith<DM, REL extends Record<keyof DM, object>, T extends keyof DM, W, S = undefined> = LoadedCount<W> & LoadedRelations<DM, REL, T, W> & ProjectDoc<DM, T, S>;
 /** Reducer applied by an aggregate (`avg`/`count`/`max`/`min`/`sum`). */
 type AggregateOp = "avg" | "count" | "max" | "min" | "sum";
 /**
-* Query-options shape shared by every aggregate reader. The RLS-aware ctx
-* populates `baseWhere` so it composes here without a hard import.
-* `restrictsCounts: true` flips `count()` into a thrown `COUNT_RLS_UNSUPPORTED`
-* `LunoraError` rather than silently undercount.
-*/
+ * Query-options shape shared by every aggregate reader. The RLS-aware ctx
+ * populates `baseWhere` so it composes here without a hard import.
+ * `restrictsCounts: true` flips `count()` into a thrown `COUNT_RLS_UNSUPPORTED`
+ * `LunoraError` rather than silently undercount.
+ */
 interface RestrictableQueryOptions<TDocument> {
   baseWhere?: Where<TDocument>;
   restrictsCounts?: boolean;
   where?: Where<TDocument>;
 }
 /**
-* Relation-aware twin of {@link RestrictableQueryOptions}. The `@lunora/do`
-* pre-resolver now resolves relation predicates on the `count`/`aggregate`/
-* `groupBy` paths too (semijoin), so the typed surface threads `REL` through
-* `where`/`baseWhere` to match. `rank`/`rankPage` stay column-only — they use
-* `where` solely to pin a partition and fail closed on a relation predicate.
-*/
+ * Relation-aware twin of {@link RestrictableQueryOptions}. The `@lunora/do`
+ * pre-resolver now resolves relation predicates on the `count`/`aggregate`/
+ * `groupBy` paths too (semijoin), so the typed surface threads `REL` through
+ * `where`/`baseWhere` to match. `rank`/`rankPage` stay column-only — they use
+ * `where` solely to pin a partition and fail closed on a relation predicate.
+ */
 interface RestrictableQueryOptionsOf<DM, REL extends Record<keyof DM, object>, T extends keyof DM> {
   baseWhere?: WhereOf<DM, REL, T>;
   restrictsCounts?: boolean;
@@ -259,41 +259,71 @@ interface RankPage<TDocument> {
   page: TDocument[];
 }
 /**
-* Builder passed to `.withSearchIndex(name, q => …)`. `.search(field, query)`
-* runs the full-text match against the index's searchable field; `.eq(field,
-* value)` narrows by a declared filter field. Field names are constrained to
-* the table's columns.
-*/
+ * Builder passed to `.withSearchIndex(name, q => …)`. `.search(field, query)`
+ * runs the full-text match against the index's searchable field; `.eq(field,
+ * value)` narrows by a declared filter field. Field names are constrained to
+ * the table's columns.
+ */
 interface SearchFilterBuilder<TDocument> {
   eq: <F extends keyof TDocument & string>(field: F, value: TDocument[F]) => SearchFilterBuilder<TDocument>;
   search: (field: keyof TDocument & string, query: string) => SearchFilterBuilder<TDocument>;
 }
 /**
-* Chainable reader returned by `.withSearchIndex()` — rows come back ordered
-* by relevance. `.paginate()` is intentionally absent (a relevance-ordered
-* search can't keyset-paginate); cap the result set with `.take(n)`.
-*/
+ * Chainable reader returned by `.withSearchIndex()` — rows come back ordered
+ * by relevance. `.paginate()` is intentionally absent (a relevance-ordered
+ * search can't keyset-paginate); cap the result set with `.take(n)`.
+ */
 interface SearchReader<TDocument> {
   collect: () => Promise<TDocument[]>;
   first: () => Promise<TDocument | null>;
   take: (limit: number) => Promise<TDocument[]>;
   unique: () => Promise<TDocument | null>;
 }
+/** A latitude/longitude point (WGS84 decimal degrees) accepted by geo queries. */
+interface GeoPointInput {
+  lat: number;
+  lng: number;
+}
+/** An axis-aligned latitude/longitude bounding box (`sw`/`ne` corners). */
+interface GeoBoundingBox {
+  ne: GeoPointInput;
+  sw: GeoPointInput;
+}
+/**
+ * Builder passed to `.withGeoIndex(name, q => …)`. Call exactly one of
+ * `.near(point, radiusMeters)` (proximity, nearest-first) or `.within(box)`
+ * (bounding-box).
+ */
+interface GeoFilterBuilder {
+  near: (point: GeoPointInput, radiusMeters: number) => GeoFilterBuilder;
+  within: (box: GeoBoundingBox) => GeoFilterBuilder;
+}
+/**
+ * Chainable reader returned by `.withGeoIndex()`. `.near()` results come back
+ * ordered nearest-first; `.within()` results by row creation time. `.paginate()`
+ * is intentionally absent — cap the result set with `.take(n)`.
+ */
+interface GeoReader<TDocument> {
+  collect: () => Promise<TDocument[]>;
+  first: () => Promise<TDocument | null>;
+  take: (limit: number) => Promise<TDocument[]>;
+  unique: () => Promise<TDocument | null>;
+}
 /** Read-only typed table accessor exposed on `QueryCtx.db.&lt;table>`. */
-interface TableReaderFacade<DM, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>, T extends keyof DM> {
+interface TableReaderFacade<DM, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>, T extends keyof DM, GEO extends Record<keyof DM, string> = Record<keyof DM, never>> {
   /**
-  * Reduce rows in this table to a scalar (`avg`/`max`/`min`/`sum` — `count`
-  * lives on its own method). Routes through a declared `aggregateIndex` when
-  * the planner can prove the request is answerable; otherwise scans.
-  */
+   * Reduce rows in this table to a scalar (`avg`/`max`/`min`/`sum` — `count`
+   * lives on its own method). Routes through a declared `aggregateIndex` when
+   * the planner can prove the request is answerable; otherwise scans.
+   */
   aggregate: (options: TableAggregateOptionsOf<DM, REL, T>) => Promise<null | number>;
   /**
-  * Count rows. The planner routes `where` keys that match a declared
-  * `aggregateIndex.by` set to the indexed counter (no scan); otherwise
-  * falls back to a SCAN. Accepts either a bare `where` tree or the broader
-  * `RestrictableQueryOptions` shape; the latter is the seam the RLS layer
-  * uses to inject `baseWhere` and `restrictsCounts`.
-  */
+   * Count rows. The planner routes `where` keys that match a declared
+   * `aggregateIndex.by` set to the indexed counter (no scan); otherwise
+   * falls back to a SCAN. Accepts either a bare `where` tree or the broader
+   * `RestrictableQueryOptions` shape; the latter is the seam the RLS layer
+   * uses to inject `baseWhere` and `restrictsCounts`.
+   */
   count: (where?: RestrictableQueryOptionsOf<DM, REL, T> | WhereOf<DM, REL, T>) => Promise<number>;
   /** `true` when at least one row matches `where` (any row when omitted). RLS-filtered exactly like `findFirst`. */
   exists: (where?: WhereOf<DM, REL, T>) => Promise<boolean>;
@@ -311,53 +341,72 @@ interface TableReaderFacade<DM, REL extends Record<keyof DM, object>, RANK exten
   }) => Promise<QueryPage<LoadWith<DM, REL, T, W, S>>>;
   get: (id: Id<string & T>) => Promise<DM[T] | null>;
   /**
-  * Group rows by the named keys and apply `agg` per group (defaults to
-  * `count`). Answered from the counter table when an aggregate index's
-  * `by` matches `options.by` exactly; otherwise scans.
-  */
+   * Group rows by the named keys and apply `agg` per group (defaults to
+   * `count`). Answered from the counter table when an aggregate index's
+   * `by` matches `options.by` exactly; otherwise scans.
+   */
   groupBy: (options: TableGroupByOptionsOf<DM, REL, T>) => Promise<ReadonlyArray<GroupByEntry<DM[T]>>>;
   /**
-  * Return the 1-based position of `options.row` within its partition
-  * under the declared rankIndex `indexName`, plus the partition's total
-  * row count. `null` when the row isn't in the index. Honors the same
-  * `baseWhere` / `restrictsCounts` RLS seam as `count()`.
-  */
+   * Return the 1-based position of `options.row` within its partition
+   * under the declared rankIndex `indexName`, plus the partition's total
+   * row count. `null` when the row isn't in the index. Honors the same
+   * `baseWhere` / `restrictsCounts` RLS seam as `count()`.
+   */
   rank: (indexName: RANK[T], options: TableRankOptions<DM[T]>) => Promise<null | RankResult>;
   /**
-  * Walk the rank companion in declared sort order — sorted pagination
-  * accelerator. `options.where` may pin the partition; `cursor`/`take`
-  * follow the Convex-style keyset shape.
-  */
+   * Walk the rank companion in declared sort order — sorted pagination
+   * accelerator. `options.where` may pin the partition; `cursor`/`take`
+   * follow the Convex-style keyset shape.
+   */
   rankPage: (indexName: RANK[T], options?: TableRankPageOptions<DM[T]>) => Promise<RankPage<DM[T]>>;
   /**
-  * Restrict the query to a declared `.searchIndex()` and run a full-text
-  * match. `indexName` is constrained to this table's search indexes
-  * (`never` when it declares none). Returns a relevance-ordered reader —
-  * finish with `.take(n)` / `.collect()`.
-  */
+   * Restrict the query to a declared `.geoIndex()` and run a proximity /
+   * bounding-box match. `indexName` is constrained to this table's geo indexes
+   * (`never` when it declares none). Returns a distance-ordered reader —
+   * finish with `.take(n)` / `.collect()`.
+   */
+  withGeoIndex: (indexName: GEO[T], build: (q: GeoFilterBuilder) => GeoFilterBuilder) => GeoReader<DM[T]>;
+  /**
+   * Restrict the query to a declared `.searchIndex()` and run a full-text
+   * match. `indexName` is constrained to this table's search indexes
+   * (`never` when it declares none). Returns a relevance-ordered reader —
+   * finish with `.take(n)` / `.collect()`.
+   */
   withSearchIndex: (indexName: SEARCH[T], search: (q: SearchFilterBuilder<DM[T]>) => SearchFilterBuilder<DM[T]>) => SearchReader<DM[T]>;
 }
 /** Read-write typed table accessor exposed on `MutationCtx.db.&lt;table>` / `ActionCtx.db.&lt;table>`. */
-interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>, T extends keyof DM> extends TableReaderFacade<DM, REL, RANK, SEARCH, T> {
+interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>, T extends keyof DM, GEO extends Record<keyof DM, string> = Record<keyof DM, never>> extends TableReaderFacade<DM, REL, RANK, SEARCH, T, GEO> {
   /**
-  * Delete a row by id. On a `.softDelete()` table this flips the marker column
-  * (and cascades as a soft delete) instead of removing the row; use
-  * {@link TableWriterFacade.hardDelete} to force physical removal.
-  */
+   * Delete a row by id. On a `.softDelete()` table this flips the marker column
+   * (and cascades as a soft delete) instead of removing the row; use
+   * {@link TableWriterFacade.hardDelete} to force physical removal.
+   */
   delete: (id: Id<string & T>) => Promise<void>;
-  /** Delete many rows in this table by id in one call; returns the *requested* id count (unknown ids are no-ops). Atomic within a mutation (a throw rolls the mutation back); an action has no transaction span. */
-  deleteMany: (ids: ReadonlyArray<Id<string & T>>, options?: {
-    limit?: number;
-  }) => Promise<{
-    deleted: number;
-  }>;
+  /**
+   * Delete many rows in this table. Pass an array of ids (requested count is
+   * returned; unknown ids are no-ops) or `{ where }` to delete matching rows
+   * (actual removed count is returned). Atomic within a mutation.
+   */
+  deleteMany: {
+    (ids: ReadonlyArray<Id<string & T>>, options?: {
+      limit?: number;
+    }): Promise<{
+      deleted: number;
+    }>;
+    (args: {
+      limit?: number;
+      where: Partial<DM[T]>;
+    }): Promise<{
+      deleted: number;
+    }>;
+  };
   /** Physically remove a row (and physically cascade `onDelete`), bypassing `.softDelete()`. Same as `delete()` on a non-soft table. */
   hardDelete: (id: Id<string & T>) => Promise<void>;
   /**
-  * Insert a document, returning its minted id. With `{ skipDuplicates: true }`
-  * a UNIQUE-constraint breach resolves to `null` (the row already exists)
-  * instead of throwing — the return type widens to `Id | null` on that overload.
-  */
+   * Insert a document, returning its minted id. With `{ skipDuplicates: true }`
+   * a UNIQUE-constraint breach resolves to `null` (the row already exists)
+   * instead of throwing — the return type widens to `Id | null` on that overload.
+   */
   insert: {
     (values: IM[T], options: {
       skipDuplicates: true;
@@ -366,27 +415,53 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
       skipDuplicates?: boolean;
     }): Promise<Id<string & T>>;
   };
-  /** Insert many documents into this table in one call, returning the minted ids in input order. Atomic within a mutation (a throw rolls the mutation back); an action has no transaction span. */
-  insertMany: (values: ReadonlyArray<IM[T]>, options?: {
-    limit?: number;
-  }) => Promise<Id<string & T>[]>;
+  /**
+   * Insert many documents into this table in one call, returning the minted ids
+   * in input order. With `{ skipDuplicates: true }`, UNIQUE breaches resolve to
+   * `null` for that row instead of failing the batch. Atomic within a mutation.
+   */
+  insertMany: {
+    (values: ReadonlyArray<IM[T]>, options: {
+      limit?: number;
+      skipDuplicates: true;
+    }): Promise<(Id<string & T> | null)[]>;
+    (values: ReadonlyArray<IM[T]>, options?: {
+      limit?: number;
+      skipDuplicates?: boolean;
+    }): Promise<Id<string & T>[]>;
+  };
   patch: (id: Id<string & T>, values: Partial<IM[T]>) => Promise<void>;
-  /** Patch many rows in this table by id in one call. Atomic within a mutation (a throw rolls the mutation back); an action has no transaction span. */
-  patchMany: (patches: ReadonlyArray<{
-    id: Id<string & T>;
-    values: Partial<IM[T]>;
-  }>, options?: {
-    limit?: number;
-  }) => Promise<void>;
+  /**
+   * Patch many rows in this table. Pass an array of `{ id, values }` or
+   * `{ where, values }` to patch matching rows with the same values. Returns
+   * the actual patched count. Atomic within a mutation.
+   */
+  patchMany: {
+    (patches: ReadonlyArray<{
+      id: Id<string & T>;
+      values: Partial<IM[T]>;
+    }>, options?: {
+      limit?: number;
+    }): Promise<{
+      patched: number;
+    }>;
+    (args: {
+      limit?: number;
+      values: Partial<IM[T]>;
+      where: Partial<DM[T]>;
+    }): Promise<{
+      patched: number;
+    }>;
+  };
   replace: (id: Id<string & T>, values: IM[T]) => Promise<void>;
   /** Un-soft-delete a row by id: clears the `.softDelete()` marker so list reads see it again. Throws on a non-soft table. */
   restore: (id: Id<string & T>) => Promise<void>;
   /**
-  * Insert when no existing row matches `target`, otherwise patch the match with
-  * `update` (defaulting to `create`). `target` names a `.unique()` column (or a
-  * tuple) used to look it up. Returns the row id and whether it was `created`.
-  * Composes `findFirst` + `insert`/`patch`, so RLS gates each step.
-  */
+   * Insert when no existing row matches `target`, otherwise patch the match with
+   * `update` (defaulting to `create`). `target` names a `.unique()` column (or a
+   * tuple) used to look it up. Returns the row id and whether it was `created`.
+   * Composes `findFirst` + `insert`/`patch`, so RLS gates each step.
+   */
   upsert: (args: {
     create: IM[T];
     target: UpsertTargetOf<DM, T>;
@@ -410,7 +485,7 @@ interface TableWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends
 /** Conflict target for `upsert`/`upsertMany`: one column of table `T`, or a tuple of them. */
 type UpsertTargetOf<DM, T extends keyof DM> = ReadonlyArray<keyof DM[T] & string> | (keyof DM[T] & string);
 /** Per-table read facade — `ctx.db.&lt;table>` on a `QueryCtx`. */
-type DatabaseReaderFacade<DM, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>> = { readonly [T in keyof DM]: TableReaderFacade<DM, REL, RANK, SEARCH, T> };
+type DatabaseReaderFacade<DM, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>, GEO extends Record<keyof DM, string> = Record<keyof DM, never>> = { readonly [T in keyof DM]: TableReaderFacade<DM, REL, RANK, SEARCH, T, GEO>; };
 /** Per-table read-write facade — `ctx.db.&lt;table>` on a `MutationCtx` / `ActionCtx`. */
-type DatabaseWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>> = { readonly [T in keyof DM]: TableWriterFacade<DM, IM, REL, RANK, SEARCH, T> };
-export { AggregateOp, DatabaseReaderFacade, DatabaseWriterFacade, GroupByEntry, Id, LoadWith, ManyRelationWhere, OneRelationWhere, OrderBy, QueryArgs, QueryArgsOf, QueryPage, RankPage, RankResult, RestrictableQueryOptions, RestrictableQueryOptionsOf, SearchFilterBuilder, SearchReader, TableAggregateOptions, TableAggregateOptionsOf, TableGroupByOptions, TableGroupByOptionsOf, TableRankOptions, TableRankPageOptions, TableReaderFacade, TableWriterFacade, UpsertTargetOf, Where, WhereOf, WhereOperators, WithArg };
+type DatabaseWriterFacade<DM, IM extends Record<keyof DM, object>, REL extends Record<keyof DM, object>, RANK extends Record<keyof DM, string>, SEARCH extends Record<keyof DM, string>, GEO extends Record<keyof DM, string> = Record<keyof DM, never>> = { readonly [T in keyof DM]: TableWriterFacade<DM, IM, REL, RANK, SEARCH, T, GEO>; };
+export { AggregateOp, DatabaseReaderFacade, DatabaseWriterFacade, GeoBoundingBox, GeoFilterBuilder, GeoPointInput, GeoReader, GroupByEntry, Id, LoadWith, ManyRelationWhere, OneRelationWhere, OrderBy, QueryArgs, QueryArgsOf, QueryPage, RankPage, RankResult, RestrictableQueryOptions, RestrictableQueryOptionsOf, SearchFilterBuilder, SearchReader, TableAggregateOptions, TableAggregateOptionsOf, TableGroupByOptions, TableGroupByOptionsOf, TableRankOptions, TableRankPageOptions, TableReaderFacade, TableWriterFacade, UpsertTargetOf, Where, WhereOf, WhereOperators, WithArg };