@pylonsync/react 0.22.47 → 0.22.58

package/src/hooks.ts

@@ -1,5 +1,6 @@
 "use client";
 
+import { compareForOrder, compileWhere } from "./queryFilter";
 import { SyncEngine, generateId, pylonFetch, type Row } from "@pylonsync/sync";
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { callFn, clientTransport } from "./index";
@@ -476,7 +477,7 @@ function applyClientFilter(rows: Iterable<Row>, options?: QueryOptions): Row[] {
     if (!matches || matches(row)) out.push(row);
   }
   for (const [field, dir] of order) {
-    out.sort((a, b) => compare(a[field], b[field], dir));
+    out.sort((a, b) => compareForOrder(a[field], b[field], dir));
   }
   if (typeof limit === "number") {
     return out.slice(0, limit);
@@ -484,73 +485,6 @@ function applyClientFilter(rows: Iterable<Row>, options?: QueryOptions): Row[] {
   return out;
 }
 
-function compileWhere(where: QueryFilter): (row: Row) => boolean {
-  const fields = Object.entries(where)
-    .filter(([key]) => key !== "$order" && key !== "$limit")
-    .map(([key, val]) => ({
-      key,
-      val,
-      operators: val !== null && typeof val === "object" && !Array.isArray(val)
-        ? Object.entries(val as Record<string, unknown>).map(([op, opVal]) => ({
-            op,
-            opVal,
-            members: op === "$in" && Array.isArray(opVal) ? new Set(opVal) : undefined,
-          }))
-        : undefined,
-    }));
-  return (row) => {
-    for (const { key, val, operators } of fields) {
-      const rowVal = row[key];
-      if (operators) {
-        for (const { op, opVal, members } of operators) {
-          switch (op) {
-            case "$not":
-              if (rowVal === opVal) return false;
-              break;
-            case "$gt":
-              if (!(typeof rowVal === "number" && typeof opVal === "number" && rowVal > opVal))
-                return false;
-              break;
-            case "$gte":
-              if (!(typeof rowVal === "number" && typeof opVal === "number" && rowVal >= opVal))
-                return false;
-              break;
-            case "$lt":
-              if (!(typeof rowVal === "number" && typeof opVal === "number" && rowVal < opVal))
-                return false;
-              break;
-            case "$lte":
-              if (!(typeof rowVal === "number" && typeof opVal === "number" && rowVal <= opVal))
-                return false;
-              break;
-            case "$like":
-              if (
-                !(typeof rowVal === "string" && typeof opVal === "string" && rowVal.includes(opVal))
-              )
-                return false;
-              break;
-            case "$in":
-              if (!members?.has(rowVal)) return false;
-              break;
-          }
-        }
-      } else {
-        if (rowVal !== val) return false;
-      }
-    }
-    return true;
-  };
-}
-
-function compare(a: unknown, b: unknown, dir: "asc" | "desc"): number {
-  const mult = dir === "desc" ? -1 : 1;
-  if (a === b) return 0;
-  if (a === undefined || a === null) return mult;
-  if (b === undefined || b === null) return -mult;
-  if (typeof a === "number" && typeof b === "number") return (a - b) * mult;
-  return String(a).localeCompare(String(b)) * mult;
-}
-
 // ---------------------------------------------------------------------------
 // useMutation — call a server-side TypeScript function
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -75,8 +75,12 @@ import {
   pylonFetch,
   pylonFetchRaw,
   PylonHttpError,
+  uploadBytes,
   type Storage as PylonStorage,
   type TransportConfig,
+  type FileVisibility,
+  type UploadBytesOptions,
+  type UploadedFile,
 } from "@pylonsync/sync";
 import { peekActiveEngine } from "./engine-registry";
 
@@ -186,6 +190,30 @@ export type { UseSessionReturn, ResolvedSession } from "./useSession";
 
 export { useSyncStatus } from "./useSyncStatus";
 export type { SyncConnectionStatus } from "./useSyncStatus";
+export { useSyncProgress } from "./useSyncProgress";
+export type { SyncProgress } from "./useSyncProgress";
+
+// Writes not yet on the server, and writes the server rejected.
+export { useOutbox } from "./useOutbox";
+export type { UseOutboxReturn, Outbox, OutboxItem } from "./useOutbox";
+
+// Files kept on the device and uploaded when there is a network.
+export { queueUpload, useFileUrl } from "./offlineUploads";
+export type { QueueUploadOptions, QueuedUploadHandle, UploadAttachTarget } from "./offlineUploads";
+export { UploadQueueFullError, UploadRejectedError } from "@pylonsync/sync";
+
+// Offline service worker registration. The SSR client runtime calls it on
+// every page load; apps opt in with `buildManifest({ offline })`.
+export { registerOfflineWorker } from "./offlineWorker";
+export type { OfflineWorkerOptions } from "./offlineWorker";
+
+// App updates: a newer build is deployed, load it.
+export { useAppUpdate } from "./useAppUpdate";
+export type { UseAppUpdateReturn } from "./useAppUpdate";
+export { AppUpdateBar } from "./AppUpdateBar";
+export type { AppUpdateBarProps } from "./AppUpdateBar";
+export { createAppUpdate, AppUpdater } from "./appUpdate";
+export type { AppBuild, AppUpdateState, AppUpdateEnv } from "./appUpdate";
 
 // One-liner API
 export { db, init, getSync, setSessionToken } from "./db";
@@ -952,29 +980,10 @@ export async function listFns(): Promise<
 // File upload
 // ---------------------------------------------------------------------------
 
-export interface UploadedFile {
-  id: string;
-  /** Where to read the file. Store this on your row. */
-  url: string;
-  size: number;
-}
+export type { UploadedFile, FileVisibility } from "@pylonsync/sync";
 
-/**
- * Who can read an uploaded file through `url`.
- *   - "private" (default): only the uploader.
- *   - "public": anyone, signed in or not. Use it for content every visitor
- *     sees, such as feed photos or listing images.
- * Writes and deletes stay with the uploader either way. On a CDN-backed
- * store (Stack0, a public bucket) every file is served by its URL, so the
- * setting only changes reads that go through `/api/files/<id>`.
- */
-export type FileVisibility = "private" | "public";
-
-export interface UploadFileOptions {
-  filename?: string;
-  contentType?: string;
+export interface UploadFileOptions extends UploadBytesOptions {
   token?: string;
-  visibility?: FileVisibility;
 }
 
 /**
@@ -988,6 +997,9 @@ export interface UploadFileOptions {
  * signature is the credential. The session is never sent to a presigned
  * URL on another origin.
  *
+ * All three steps need the network. For a file taken where there may be
+ * none (a photo in the field), use `queueUpload`.
+ *
  * @example
  * ```ts
  * const photo = await uploadFile(fileFromInput, { visibility: "public" });
@@ -998,87 +1010,8 @@ export async function uploadFile(
   input: File | Blob | ArrayBuffer | Uint8Array,
   options: UploadFileOptions = {}
 ): Promise<UploadedFile> {
-  let body: BodyInit;
-  let size: number;
-  let filename = options.filename;
-  let contentType = options.contentType;
-
-  if (typeof File !== "undefined" && input instanceof File) {
-    body = input;
-    size = input.size;
-    filename ??= input.name;
-    contentType ??= input.type || "application/octet-stream";
-  } else if (typeof Blob !== "undefined" && input instanceof Blob) {
-    body = input;
-    size = input.size;
-    contentType ??= input.type || "application/octet-stream";
-  } else if (input instanceof ArrayBuffer) {
-    body = input;
-    size = input.byteLength;
-  } else {
-    // Newer TS lib types refuse `Uint8Array<ArrayBufferLike>` as BodyInit
-    // directly even though every runtime accepts it. Hand fetch the
-    // underlying ArrayBuffer slice to sidestep the type narrowing.
-    const u8 = input as Uint8Array;
-    body = u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength) as ArrayBuffer;
-    size = u8.byteLength;
-  }
-
-  filename ??= "upload";
-  contentType ??= "application/octet-stream";
-
-  const transport = clientTransport(options.token);
-
-  const slot = await pylonFetch<{ uploadUrl: string; assetId: string }>(
-    transport,
-    "/api/files/init",
-    {
-      method: "POST",
-      json: {
-        filename,
-        mimeType: contentType,
-        size,
-        visibility: options.visibility ?? "private",
-      },
-    },
-  );
-
-  const base = new URL(getBaseUrl() || "http://localhost");
-  const target = new URL(slot.uploadUrl, base);
-  const put =
-    target.origin === base.origin
-      ? await pylonFetchRaw(transport, `${target.pathname}${target.search}`, {
-          method: "PUT",
-          body,
-          headers: { "Content-Type": contentType },
-        })
-      : await fetch(target.toString(), {
-          method: "PUT",
-          body,
-          headers: { "Content-Type": contentType },
-        });
-  // Read the response body to the end, even an empty 204. Chrome cancels a
-  // fetch whose body is never read once the Response is dropped, and
-  // DevTools then lists the upload as failed (net::ERR_ABORTED) although
-  // the server stored the bytes.
-  const putBody = await put.text().catch(() => "");
-  if (!put.ok) {
-    let message = `Upload of ${filename} failed: ${put.status}`;
-    let code: string | undefined;
-    try {
-      const err = JSON.parse(putBody) as { error?: { code?: string; message?: string } };
-      if (err.error?.message) message = err.error.message;
-      code = err.error?.code;
-    } catch {
-      // Not JSON (storage provider XML, proxy page): keep the status text.
-    }
-    throw new PylonHttpError(message, put.status, code);
-  }
-
-  return pylonFetch<UploadedFile>(transport, "/api/files/confirm", {
-    method: "POST",
-    json: { assetId: slot.assetId },
-  });
+  const { token, ...rest } = options;
+  return uploadBytes(clientTransport(token), input, rest);
 }
 
 /**

package/src/offlineUploads.test.tsx

@@ -0,0 +1,66 @@
+// A queued photo shows on its record at once, from the device, and the
+// record shows the uploaded file's URL after the upload runs.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
+import type { SyncEngine } from "@pylonsync/sync";
+import { createTestEnv, type TestEnv } from "@pylonsync/sync/src/test-harness";
+
+import { useQueryOne } from "./hooks";
+import { queueUpload, useFileUrl } from "./offlineUploads";
+
+const asEngine = (e: TestEnv["engine"]): SyncEngine => e as unknown as SyncEngine;
+
+let env: TestEnv | null = null;
+afterEach(async () => {
+  cleanup();
+  if (env) {
+    await env.dispose();
+    env = null;
+  }
+});
+
+function PhotoCard({ engine }: { engine: SyncEngine }) {
+  const { data } = useQueryOne<{ id: string; url: string | null }>(engine, "Photo", "p1");
+  const src = useFileUrl(data?.url, engine);
+  return <span data-testid="src">{src ?? "none"}</span>;
+}
+
+describe("queueUpload + useFileUrl", () => {
+  test("the record shows the local photo at once and the real URL after the upload", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "rep1" });
+    env.server.seed("Photo", [{ id: "p1", url: null, fileId: null }]);
+    await env.start();
+    const engine = asEngine(env.engine);
+    render(<PhotoCard engine={engine} />);
+    expect(screen.getByTestId("src").textContent).toBe("none");
+
+    // Hold the upload so the local stage is observable.
+    env.server.files.dropNextPut();
+    let queued!: Awaited<ReturnType<typeof queueUpload>>;
+    await act(async () => {
+      queued = await queueUpload(new File([new Uint8Array(64)], "door.jpg", { type: "image/jpeg" }), {
+        attach: { entity: "Photo", id: "p1", field: "fileId", urlField: "url" },
+        engine,
+      });
+    });
+    expect(queued.localUrl).toMatch(/^blob:/);
+    expect(screen.getByTestId("src").textContent).toBe(queued.localUrl!);
+
+    await act(async () => {
+      await env!.engine.uploads.process();
+      await queued.done;
+    });
+    await waitFor(() => expect(screen.getByTestId("src").textContent).toBe("/api/files/f_2"));
+  });
+
+  test("a local reference this device does not hold resolves to null", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "rep1" });
+    env.server.seed("Photo", [{ id: "p1", url: "local:upl_from_another_phone", fileId: null }]);
+    await env.start();
+    render(<PhotoCard engine={asEngine(env.engine)} />);
+    await waitFor(() => expect(screen.getByTestId("src").textContent).toBe("none"));
+  });
+});

package/src/offlineUploads.ts

@@ -0,0 +1,77 @@
+"use client";
+
+import {
+	localUploadId,
+	OUTBOX_CHANNEL,
+	type FileVisibility,
+	type QueuedUploadHandle,
+	type SyncEngine,
+	type UploadAttachTarget,
+} from "@pylonsync/sync";
+import { useSyncExternalStore } from "react";
+import { db } from "./db";
+
+export type { QueuedUploadHandle, UploadAttachTarget };
+
+export interface QueueUploadOptions {
+	/** The record the file belongs to, and the field that gets its id
+	 *  (and `urlField`, its URL). */
+	attach: UploadAttachTarget;
+	filename?: string;
+	contentType?: string;
+	visibility?: FileVisibility;
+	/** Defaults to the engine `init()` set up. */
+	engine?: SyncEngine;
+}
+
+/**
+ * Keep a file on the device and upload it when there is a network, then
+ * set it on its record. Returns at once, also with no network.
+ *
+ * At once the record's `attach.field` (and `attach.urlField`) holds
+ * `local:<localId>`; read it with `useFileUrl` to show the photo from the
+ * device. When the upload finishes, the field gets the file id and
+ * `urlField` the file URL. Both changes are ordinary queued writes.
+ *
+ * ```ts
+ * const photoId = await db.insert("Photo", { leadId, fileId: null, url: null });
+ * await queueUpload(file, {
+ *   attach: { entity: "Photo", id: photoId, field: "fileId", urlField: "url" },
+ * });
+ * ```
+ *
+ * Pending and failed uploads are in `useOutbox()` with kind `"upload"`.
+ * Throws `UploadQueueFullError` when the queue already holds
+ * `maxQueuedUploadBytes` (200 MB by default).
+ */
+export function queueUpload(
+	file: Blob,
+	options: QueueUploadOptions,
+): Promise<QueuedUploadHandle> {
+	const { engine, ...rest } = options;
+	return (engine ?? db.sync).queueUpload(file, rest);
+}
+
+/**
+ * The URL to show for a file field: the value itself, or, for a
+ * `local:<localId>` value from `queueUpload`, an object URL of the copy on
+ * this device. Null for an empty value, and for a `local:` value this
+ * device does not hold (another device queued it, or it was dismissed).
+ *
+ * ```tsx
+ * const src = useFileUrl(photo.url);
+ * return src ? <img src={src} /> : <Placeholder />;
+ * ```
+ */
+export function useFileUrl(
+	value: string | null | undefined,
+	engine?: SyncEngine,
+): string | null {
+	const sync = engine ?? db.sync;
+	const localId = localUploadId(value);
+	return useSyncExternalStore(
+		(cb) => sync.store.subscribe(cb, OUTBOX_CHANNEL),
+		() => (localId ? sync.uploadLocalUrl(localId) : (value ?? null)),
+		() => (localId ? null : (value ?? null)),
+	);
+}

package/src/offlineWorker.test.ts

@@ -0,0 +1,110 @@
+// The SSR client runtime calls registerOfflineWorker on every page load. It
+// must register `/pylon-sw.js` only for a production page of an app that
+// opted in, and otherwise remove a Pylon worker an earlier build left behind
+// without touching the app's own workers.
+
+import { expect, test } from "bun:test";
+import { registerOfflineWorker } from "./offlineWorker";
+
+function fakeContainer(scripts: string[] = []) {
+  const registered: Array<{ url: string; scope?: string }> = [];
+  const unregistered: string[] = [];
+  const messages: unknown[] = [];
+  const container = {
+    register: async (url: string, options?: { scope?: string }) => {
+      registered.push({ url, scope: options?.scope });
+      return { scope: "/" };
+    },
+    getRegistrations: async () =>
+      scripts.map((scriptURL) => ({
+        active: { scriptURL },
+        unregister: async () => {
+          unregistered.push(scriptURL);
+          return true;
+        },
+      })),
+    ready: Promise.resolve({ active: { postMessage: (m: unknown) => messages.push(m) } }),
+  };
+  return { container, registered, unregistered, messages };
+}
+
+const loaded = () => Promise.resolve();
+
+test("registers the worker in production when the app opted in", async () => {
+  const f = fakeContainer();
+  const reg = await registerOfflineWorker({
+    optedIn: true,
+    production: true,
+    signedIn: true,
+    navigator: { serviceWorker: f.container },
+    whenLoaded: loaded,
+  });
+  expect(reg).not.toBeNull();
+  expect(f.registered).toEqual([{ url: "/pylon-sw.js", scope: "/" }]);
+  expect(f.messages).toEqual([{ type: "pylon:session", signedIn: true }]);
+});
+
+test("does not register under pylon dev", async () => {
+  const f = fakeContainer();
+  await registerOfflineWorker({
+    optedIn: true,
+    production: false,
+    navigator: { serviceWorker: f.container },
+    whenLoaded: loaded,
+  });
+  expect(f.registered).toEqual([]);
+});
+
+test("does not register when the app did not opt in", async () => {
+  const f = fakeContainer();
+  await registerOfflineWorker({
+    optedIn: false,
+    production: true,
+    navigator: { serviceWorker: f.container },
+    whenLoaded: loaded,
+  });
+  expect(f.registered).toEqual([]);
+});
+
+test("removes a leftover Pylon worker but not the app's own", async () => {
+  const f = fakeContainer([
+    "https://app.example/pylon-sw.js",
+    "https://app.example/push-worker.js",
+  ]);
+  await registerOfflineWorker({
+    optedIn: false,
+    production: true,
+    navigator: { serviceWorker: f.container },
+    whenLoaded: loaded,
+  });
+  expect(f.unregistered).toEqual(["https://app.example/pylon-sw.js"]);
+});
+
+test("a browser without service workers is a no-op", async () => {
+  expect(
+    await registerOfflineWorker({ optedIn: true, production: true, navigator: {} }),
+  ).toBeNull();
+});
+
+test("passes the page's build to useAppUpdate, in production and in dev", async () => {
+  const { appUpdate } = await import("./appUpdate");
+  const f = fakeContainer();
+  await registerOfflineWorker({
+    optedIn: true,
+    production: true,
+    navigator: { serviceWorker: f.container },
+    whenLoaded: loaded,
+    build: { version: "abc", builtAt: "2026-10-22T10:00:00.000Z" },
+  });
+  expect(appUpdate.getSnapshot().version).toBe("abc");
+  expect(appUpdate.getSnapshot().builtAt).toBe("2026-10-22T10:00:00.000Z");
+
+  // Under pylon dev the updater stays empty.
+  await registerOfflineWorker({
+    optedIn: true,
+    production: false,
+    navigator: { serviceWorker: f.container },
+    build: { version: "abc", builtAt: null },
+  });
+  expect(appUpdate.getSnapshot().version).toBeNull();
+});

package/src/offlineWorker.ts

@@ -0,0 +1,103 @@
+// Registers the offline service worker (`/pylon-sw.js`) for apps that set
+// `buildManifest({ offline })`. The SSR client runtime calls this once per
+// page load; apps do not call it themselves.
+//
+// The worker is served by the Pylon runtime and generated per build (see
+// packages/functions/src/offline-sw.ts). It is never registered under
+// `pylon dev`: a worker serves cached build files first, which would hide
+// every edit until the next install.
+
+import { configureAppUpdate, type AppBuild } from "./appUpdate";
+
+const WORKER_URL = "/pylon-sw.js";
+
+export interface OfflineWorkerOptions {
+  /** The app set `buildManifest({ offline })`. */
+  optedIn: boolean;
+  /** Not `pylon dev`. */
+  production: boolean;
+  /** Whether a user is signed in on this page. The worker refetches the
+   *  pages it keeps when this changes, because each one carries the
+   *  signed-in bit. */
+  signedIn?: boolean;
+  /** Defaults to the global `navigator`. */
+  navigator?: { serviceWorker?: ServiceWorkerContainerLike };
+  /** Resolves when the page has loaded, so the worker's downloads do not
+   *  compete with the page's own. Defaults to the window `load` event. */
+  whenLoaded?: () => Promise<void>;
+  /** The build this page runs, from `__PYLON_DATA__`. `useAppUpdate`
+   *  compares it with the latest build. */
+  build?: AppBuild;
+}
+
+/** The parts of `ServiceWorkerContainer` this module uses. */
+export interface ServiceWorkerContainerLike {
+  register(url: string, options?: { scope?: string }): Promise<unknown>;
+  getRegistrations?(): Promise<ReadonlyArray<RegistrationLike>>;
+  ready?: Promise<{ active?: { postMessage(message: unknown): void } | null }>;
+}
+
+interface RegistrationLike {
+  active?: { scriptURL: string } | null;
+  waiting?: { scriptURL: string } | null;
+  installing?: { scriptURL: string } | null;
+  unregister(): Promise<boolean>;
+}
+
+function defaultWhenLoaded(): Promise<void> {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return Promise.resolve();
+  }
+  if (document.readyState === "complete") return Promise.resolve();
+  return new Promise((resolve) =>
+    window.addEventListener("load", () => resolve(), { once: true }),
+  );
+}
+
+function isPylonWorker(reg: RegistrationLike): boolean {
+  const worker = reg.active ?? reg.waiting ?? reg.installing;
+  if (!worker) return false;
+  try {
+    return new URL(worker.scriptURL).pathname === WORKER_URL;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Register the worker when the app opted in and this is a production page.
+ * Otherwise remove a Pylon worker an earlier build left on this origin (an
+ * app that turned offline off, or `pylon dev` after `pylon start`). Workers
+ * the app registered itself are left alone. Never throws: an app works
+ * online without its worker.
+ */
+export async function registerOfflineWorker(
+  opts: OfflineWorkerOptions,
+): Promise<unknown | null> {
+  // Before the service worker checks: a browser without service workers
+  // still learns about new builds from `/_pylon/version`.
+  if (opts.build) configureAppUpdate(opts.build, opts.optedIn && opts.production);
+  const nav =
+    opts.navigator ??
+    (typeof navigator !== "undefined" ? (navigator as any) : undefined);
+  const container = nav?.serviceWorker as ServiceWorkerContainerLike | undefined;
+  if (!container) return null;
+  try {
+    if (!opts.optedIn || !opts.production) {
+      const regs = (await container.getRegistrations?.()) ?? [];
+      await Promise.all(regs.filter(isPylonWorker).map((r) => r.unregister()));
+      return null;
+    }
+    await (opts.whenLoaded ?? defaultWhenLoaded)();
+    const registration = await container.register(WORKER_URL, { scope: "/" });
+    if (typeof opts.signedIn === "boolean" && container.ready) {
+      const ready = await container.ready;
+      ready.active?.postMessage({ type: "pylon:session", signedIn: opts.signedIn });
+    }
+    return registration;
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn("[pylon offline] service worker registration failed:", err);
+    return null;
+  }
+}

package/src/query-filter-cases.json

@@ -0,0 +1,23 @@
+{
+  "about": "Filters answered from the local replica must match the server's answer. packages/react/src/queryFilter.test.ts runs these on the client; crates/runtime/tests/query_filter_parity.rs runs them on the server. Rows are stored as the server returns them (datetimes in canonical UTC form).",
+  "rows": [
+    { "key": "k1", "title": "apple", "occurredAt": "2026-09-30T23:59:59.999Z", "rank": 1 },
+    { "key": "k2", "title": "Banana", "occurredAt": "2026-10-01T00:00:00.000Z", "rank": 2 },
+    { "key": "k3", "title": "cherry", "occurredAt": "2026-10-01T12:30:00.000Z", "rank": 3 },
+    { "key": "k4", "title": "banana", "occurredAt": "2026-10-02T00:00:00.000Z", "rank": 4 },
+    { "key": "k5", "title": "", "occurredAt": null, "rank": 5 }
+  ],
+  "cases": [
+    { "where": { "occurredAt": { "$gte": "2026-10-01T00:00:00Z" } }, "keys": ["k2", "k3", "k4"] },
+    { "where": { "occurredAt": { "$lt": "2026-10-02T00:00:00.000Z" } }, "keys": ["k1", "k2", "k3"] },
+    { "where": { "occurredAt": { "$gte": "2026-09-30T20:00:00-04:00" } }, "keys": ["k2", "k3", "k4"] },
+    { "where": { "occurredAt": { "$gte": "2026-10-01T00:00:00.000Z", "$lt": "2026-10-01T23:00:00Z" } }, "keys": ["k2", "k3"] },
+    { "where": { "occurredAt": { "$lte": "2026-09-30T23:59:59.999Z" } }, "keys": ["k1"] },
+    { "where": { "occurredAt": { "$gt": "2026-10-01T00:00:00.000Z" } }, "keys": ["k3", "k4"] },
+    { "where": { "occurredAt": { "$gte": "2026-10-01" } }, "keys": ["k2", "k3", "k4"] },
+    { "where": { "title": { "$gte": "b" } }, "keys": ["k3", "k4"] },
+    { "where": { "title": { "$lt": "a" } }, "keys": ["k2", "k5"] },
+    { "where": { "rank": { "$gt": 2 } }, "keys": ["k3", "k4", "k5"] },
+    { "where": { "rank": { "$gte": 2, "$lte": 3 } }, "keys": ["k2", "k3"] }
+  ]
+}