@gonvex/client 0.1.0

package/dist/browser-cache.js

@@ -0,0 +1,67 @@
+import { cacheFailureAction } from "./cache.js";
+import { CacheCoordinatorModel } from "./cache-coordinator.js";
+export class FakeTabWorker {
+    tabId;
+    state = new Map();
+    openCount = 0;
+    writeCount = 0;
+    constructor(tabId) {
+        this.tabId = tabId;
+    }
+    async boot() {
+        this.openCount += 1;
+    }
+    async execute(request) {
+        if (request.operation === "write") {
+            this.writeCount += 1;
+        }
+        return request.execute(this.state);
+    }
+}
+export class BrowserCacheCoordinatorHarness {
+    coordinator = new CacheCoordinatorModel();
+    workers = new Map();
+    requestLog = [];
+    registerTab(tab) {
+        this.coordinator.registerTab(tab);
+        this.workers.set(tab.id, new FakeTabWorker(tab.id));
+    }
+    async bootActiveOwner() {
+        const activeTabId = this.coordinator.snapshot().activeTabId;
+        if (!activeTabId) {
+            return;
+        }
+        const worker = this.workers.get(activeTabId);
+        if (!worker) {
+            return;
+        }
+        await worker.boot();
+        this.coordinator.markActiveOwnerReady();
+    }
+    closeTab(tabId) {
+        this.coordinator.closeTab(tabId);
+    }
+    async request(requestingTabId, request) {
+        const route = this.coordinator.routeRequest();
+        if (route.route === "server") {
+            this.requestLog.push({ requestingTabId, operation: request.operation });
+            return { ok: false, route: "server", reason: route.reason };
+        }
+        const owner = this.workers.get(route.activeTabId);
+        if (!owner) {
+            return { ok: false, route: "server", reason: "active-worker-missing" };
+        }
+        this.requestLog.push({ requestingTabId, ownerTabId: route.activeTabId, operation: request.operation });
+        try {
+            const value = await owner.execute(request);
+            return { ok: true, ownerTabId: route.activeTabId, value };
+        }
+        catch (error) {
+            return { ok: false, route: "server", reason: "local-db-error", failure: cacheFailureAction(error) };
+        }
+    }
+    activeWriters() {
+        return [...this.workers.values()].filter((worker) => worker.writeCount > 0).map((worker) => worker.tabId);
+    }
+}
+//# sourceMappingURL=browser-cache.js.map

package/dist/browser-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-cache.js","sourceRoot":"","sources":["../src/browser-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAA2B,MAAM,YAAY,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAiB,MAAM,wBAAwB,CAAC;AAgB9E,MAAM,OAAO,aAAa;IAKH;IAJZ,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC5C,SAAS,GAAG,CAAC,CAAC;IACd,UAAU,GAAG,CAAC,CAAC;IAEf,YAAqB,KAAa;QAAb,UAAK,GAAL,KAAK,CAAQ;IAAG,CAAC;IAEtC,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,OAAO,CAAI,OAA0B;QACzC,IAAI,OAAO,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;YAClC,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;QACvB,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;CACF;AAED,MAAM,OAAO,8BAA8B;IAChC,WAAW,GAAG,IAAI,qBAAqB,EAAE,CAAC;IAC1C,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC3C,UAAU,GAAyF,EAAE,CAAC;IAE/G,WAAW,CAAC,GAAa;QACvB,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,eAAe;QACnB,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,WAAW,CAAC;QAC5D,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO;QACT,CAAC;QACD,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,IAAI,CAAC,WAAW,CAAC,oBAAoB,EAAE,CAAC;IAC1C,CAAC;IAED,QAAQ,CAAC,KAAa;QACpB,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,OAAO,CAAI,eAAuB,EAAE,OAA0B;QAClE,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,YAAY,EAAE,CAAC;QAC9C,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,eAAe,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;YACxE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QAC9D,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;QACzE,CAAC;QAED,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,eAAe,EAAE,UAAU,EAAE,KAAK,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;QACvG,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAC3C,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,EAAE,CAAC;QAC5D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;QACtG,CAAC;IACH,CAAC;IAED,aAAa;QACX,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5G,CAAC;CACF"}

package/dist/browser-capabilities.d.ts

@@ -0,0 +1,21 @@
+export type BrowserCacheDisableReason = "shared-worker-unavailable" | "web-locks-unavailable" | "dedicated-worker-unavailable" | "persistent-storage-unavailable";
+export type BrowserCacheCapabilities = {
+    sharedWorker: boolean;
+    webLocks: boolean;
+    dedicatedWorker: boolean;
+    opfs: boolean;
+    supported: boolean;
+    disableReason?: BrowserCacheDisableReason;
+};
+type CapabilityGlobal = {
+    SharedWorker?: unknown;
+    Worker?: unknown;
+    navigator?: {
+        locks?: unknown;
+        storage?: {
+            getDirectory?: unknown;
+        };
+    };
+};
+export declare function detectBrowserCacheCapabilities(globalValue?: CapabilityGlobal): BrowserCacheCapabilities;
+export {};

package/dist/browser-capabilities.js

@@ -0,0 +1,31 @@
+export function detectBrowserCacheCapabilities(globalValue = globalThis) {
+    const sharedWorker = typeof globalValue.SharedWorker === "function";
+    const webLocks = typeof globalValue.navigator?.locks === "object" && globalValue.navigator?.locks !== null;
+    const dedicatedWorker = typeof globalValue.Worker === "function";
+    const opfs = typeof globalValue.navigator?.storage?.getDirectory === "function";
+    const disableReason = firstDisableReason({ sharedWorker, webLocks, dedicatedWorker, opfs });
+    return {
+        sharedWorker,
+        webLocks,
+        dedicatedWorker,
+        opfs,
+        supported: disableReason === undefined,
+        disableReason,
+    };
+}
+function firstDisableReason(capabilities) {
+    if (!capabilities.sharedWorker) {
+        return "shared-worker-unavailable";
+    }
+    if (!capabilities.webLocks) {
+        return "web-locks-unavailable";
+    }
+    if (!capabilities.dedicatedWorker) {
+        return "dedicated-worker-unavailable";
+    }
+    if (!capabilities.opfs) {
+        return "persistent-storage-unavailable";
+    }
+    return undefined;
+}
+//# sourceMappingURL=browser-capabilities.js.map

package/dist/browser-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-capabilities.js","sourceRoot":"","sources":["../src/browser-capabilities.ts"],"names":[],"mappings":"AA0BA,MAAM,UAAU,8BAA8B,CAAC,cAAgC,UAAU;IACvF,MAAM,YAAY,GAAG,OAAO,WAAW,CAAC,YAAY,KAAK,UAAU,CAAC;IACpE,MAAM,QAAQ,GAAG,OAAO,WAAW,CAAC,SAAS,EAAE,KAAK,KAAK,QAAQ,IAAI,WAAW,CAAC,SAAS,EAAE,KAAK,KAAK,IAAI,CAAC;IAC3G,MAAM,eAAe,GAAG,OAAO,WAAW,CAAC,MAAM,KAAK,UAAU,CAAC;IACjE,MAAM,IAAI,GAAG,OAAO,WAAW,CAAC,SAAS,EAAE,OAAO,EAAE,YAAY,KAAK,UAAU,CAAC;IAChF,MAAM,aAAa,GAAG,kBAAkB,CAAC,EAAE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC;IAE5F,OAAO;QACL,YAAY;QACZ,QAAQ;QACR,eAAe;QACf,IAAI;QACJ,SAAS,EAAE,aAAa,KAAK,SAAS;QACtC,aAAa;KACd,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CACzB,YAAsG;IAEtG,IAAI,CAAC,YAAY,CAAC,YAAY,EAAE,CAAC;QAC/B,OAAO,2BAA2B,CAAC;IACrC,CAAC;IACD,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;QAC3B,OAAO,uBAAuB,CAAC;IACjC,CAAC;IACD,IAAI,CAAC,YAAY,CAAC,eAAe,EAAE,CAAC;QAClC,OAAO,8BAA8B,CAAC;IACxC,CAAC;IACD,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;QACvB,OAAO,gCAAgC,CAAC;IAC1C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/cache-coordinator.d.ts

@@ -0,0 +1,37 @@
+export type CacheOwnerStatus = "no_owner" | "electing" | "active_owner_ready" | "owner_lost" | "unsafe_fallback_disabled";
+export type CacheTab = {
+    id: string;
+    hasLivenessLock: boolean;
+    dedicatedWorkerReady: boolean;
+    storageReady?: boolean;
+    integrityVerified?: boolean;
+};
+export type CacheCoordinatorSnapshot = {
+    status: CacheOwnerStatus;
+    activeTabId?: string;
+    tabs: CacheTab[];
+};
+export type DBRequestRoute = {
+    route: "active-worker";
+    activeTabId: string;
+} | {
+    route: "server";
+    reason: "no-active-owner" | "owner-not-ready" | "unsafe-fallback-disabled";
+};
+export declare class CacheCoordinatorModel {
+    private tabs;
+    private activeTabId;
+    private status;
+    registerTab(tab: CacheTab): void;
+    updateTab(tabId: string, patch: Partial<Omit<CacheTab, "id">>): void;
+    closeTab(tabId: string): void;
+    disableUnsafeFallback(): void;
+    verifyActiveOwnerIntegrity(): void;
+    markActiveOwnerStorageReady(): void;
+    markActiveOwnerReady(): void;
+    routeRequest(): DBRequestRoute;
+    snapshot(): CacheCoordinatorSnapshot;
+    private electIfNeeded;
+    private canOwn;
+    private ownerReady;
+}

package/dist/cache-coordinator.js

@@ -0,0 +1,109 @@
+export class CacheCoordinatorModel {
+    tabs = new Map();
+    activeTabId;
+    status = "no_owner";
+    registerTab(tab) {
+        this.tabs.set(tab.id, normalizeTab(tab));
+        this.electIfNeeded();
+    }
+    updateTab(tabId, patch) {
+        const current = this.tabs.get(tabId);
+        if (!current) {
+            return;
+        }
+        this.tabs.set(tabId, normalizeTab({ ...current, ...patch }));
+        if (tabId === this.activeTabId && !this.canOwn(this.tabs.get(tabId))) {
+            this.activeTabId = undefined;
+            this.status = "owner_lost";
+        }
+        this.electIfNeeded();
+    }
+    closeTab(tabId) {
+        this.tabs.delete(tabId);
+        if (this.activeTabId === tabId) {
+            this.activeTabId = undefined;
+            this.status = "owner_lost";
+        }
+        this.electIfNeeded();
+    }
+    disableUnsafeFallback() {
+        this.activeTabId = undefined;
+        this.status = "unsafe_fallback_disabled";
+    }
+    verifyActiveOwnerIntegrity() {
+        if (!this.activeTabId || this.status === "unsafe_fallback_disabled") {
+            return;
+        }
+        this.updateTab(this.activeTabId, { integrityVerified: true });
+    }
+    markActiveOwnerStorageReady() {
+        if (!this.activeTabId || this.status === "unsafe_fallback_disabled") {
+            return;
+        }
+        this.updateTab(this.activeTabId, { storageReady: true });
+    }
+    markActiveOwnerReady() {
+        if (!this.activeTabId || this.status === "unsafe_fallback_disabled") {
+            return;
+        }
+        this.updateTab(this.activeTabId, {
+            dedicatedWorkerReady: true,
+            storageReady: true,
+            integrityVerified: true,
+        });
+        this.electIfNeeded();
+    }
+    routeRequest() {
+        if (this.status === "unsafe_fallback_disabled") {
+            return { route: "server", reason: "unsafe-fallback-disabled" };
+        }
+        if (!this.activeTabId) {
+            return { route: "server", reason: "no-active-owner" };
+        }
+        const active = this.tabs.get(this.activeTabId);
+        if (!this.canOwn(active) || !this.ownerReady(active) || this.status !== "active_owner_ready") {
+            return { route: "server", reason: "owner-not-ready" };
+        }
+        return { route: "active-worker", activeTabId: this.activeTabId };
+    }
+    snapshot() {
+        return {
+            status: this.status,
+            activeTabId: this.activeTabId,
+            tabs: [...this.tabs.values()].map((tab) => ({ ...tab })),
+        };
+    }
+    electIfNeeded() {
+        if (this.status === "unsafe_fallback_disabled") {
+            return;
+        }
+        if (this.activeTabId && this.canOwn(this.tabs.get(this.activeTabId))) {
+            this.status = this.ownerReady(this.tabs.get(this.activeTabId)) ? "active_owner_ready" : "electing";
+            return;
+        }
+        const nextOwner = [...this.tabs.values()]
+            .filter((tab) => this.canOwn(tab))
+            .sort((left, right) => left.id.localeCompare(right.id))[0];
+        if (!nextOwner) {
+            this.activeTabId = undefined;
+            this.status = this.tabs.size > 0 ? "electing" : "no_owner";
+            return;
+        }
+        this.activeTabId = nextOwner.id;
+        this.status = this.ownerReady(nextOwner) ? "active_owner_ready" : "electing";
+    }
+    canOwn(tab) {
+        return Boolean(tab?.hasLivenessLock);
+    }
+    ownerReady(tab) {
+        return Boolean(tab?.dedicatedWorkerReady && tab.storageReady && tab.integrityVerified);
+    }
+}
+function normalizeTab(tab) {
+    return {
+        ...tab,
+        storageReady: tab.storageReady ?? false,
+        integrityVerified: tab.integrityVerified ?? false,
+    };
+}
+//# sourceMappingURL=cache-coordinator.js.map

package/dist/cache-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-coordinator.js","sourceRoot":"","sources":["../src/cache-coordinator.ts"],"names":[],"mappings":"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"}

package/dist/cache.d.ts

@@ -0,0 +1,74 @@
+export type ShapeSyncStatus = "not_started" | "syncing" | "ready" | "stale" | "too_large" | "error";
+export type CacheDBHealth = "healthy" | "initializing" | "unavailable" | "corrupt";
+export type CacheRoutingSource = "local" | "server";
+export type CacheRoutingReason = "local-ready" | "query-has-no-local-plan" | "query-has-no-shape" | "shape-missing" | "shape-does-not-cover-query" | "shape-not-ready" | "shape-too-large" | "query-row-limit-unsafe" | "shape-auth-scope-mismatch" | "shape-epoch-mismatch" | "db-not-healthy" | "db-owner-unsafe";
+export type CacheShapeVisibilityScope = "project" | "tenant" | "user" | "auth";
+export type CacheShapeDefinition = {
+    id: string;
+    tables: string[];
+    visibilityScope: CacheShapeVisibilityScope;
+    maxRows?: number;
+    maxBytes?: number;
+    schemaVersion: string;
+    permissionVersion: string;
+};
+export type CacheShapeState = {
+    id: string;
+    projectId: string;
+    tenantId: string;
+    userId: string;
+    authScope: string;
+    status: ShapeSyncStatus;
+    schemaVersion: string;
+    permissionVersion: string;
+    checkpoint?: string;
+    rowCount?: number;
+    maxRows?: number;
+};
+export type CacheQueryPlan = {
+    queryKey: string;
+    queryPath?: string;
+    projectId: string;
+    tenantId: string;
+    userId: string;
+    authScope: string;
+    requiredShapeId?: string;
+    hasLocalPlan: boolean;
+    schemaVersion: string;
+    permissionVersion: string;
+    coveredByShapeIds?: string[];
+    estimatedRows?: number;
+    limit?: number;
+};
+export type CacheEnvironment = {
+    dbHealth: CacheDBHealth;
+    singleWriter: boolean;
+    shapes: Record<string, CacheShapeState | undefined>;
+    definitions?: Record<string, CacheShapeDefinition | undefined>;
+};
+export type CacheRoutingDecision = {
+    source: CacheRoutingSource;
+    reason: CacheRoutingReason;
+    shape?: CacheShapeState;
+};
+export type CacheFailureAction = {
+    action: "reset-and-server-fallback";
+    reason: "cache-corruption-suspected";
+} | {
+    action: "server-fallback";
+    reason: "ordinary-failure";
+};
+export declare function chooseQuerySource(query: CacheQueryPlan, environment: CacheEnvironment): CacheRoutingDecision;
+export declare function defineVisibleShape(definition: CacheShapeDefinition): CacheShapeDefinition;
+export declare function cacheKey(parts: {
+    projectId: string;
+    tenantId: string;
+    userId: string;
+    authScope: string;
+    queryPath: string;
+    argsHash: string;
+    schemaVersion: string;
+    permissionVersion: string;
+}): string;
+export declare function shouldResetLocalCache(error: unknown): boolean;
+export declare function cacheFailureAction(error: unknown): CacheFailureAction;

package/dist/cache.js

@@ -0,0 +1,120 @@
+export function chooseQuerySource(query, environment) {
+    if (!query.hasLocalPlan) {
+        return server("query-has-no-local-plan");
+    }
+    if (!query.requiredShapeId) {
+        return server("query-has-no-shape");
+    }
+    if (environment.dbHealth !== "healthy") {
+        return server("db-not-healthy");
+    }
+    if (!environment.singleWriter) {
+        return server("db-owner-unsafe");
+    }
+    const shape = environment.shapes[query.requiredShapeId];
+    if (!shape) {
+        return server("shape-missing");
+    }
+    const definition = environment.definitions?.[query.requiredShapeId];
+    if (!shapeCoversQuery(query, definition)) {
+        return server("shape-does-not-cover-query", shape);
+    }
+    if (shape.status === "too_large") {
+        return server("shape-too-large", shape);
+    }
+    if (shape.status !== "ready") {
+        return server("shape-not-ready", shape);
+    }
+    if (!sameScope(query, shape)) {
+        return server("shape-auth-scope-mismatch", shape);
+    }
+    if (shape.schemaVersion !== query.schemaVersion || shape.permissionVersion !== query.permissionVersion) {
+        return server("shape-epoch-mismatch", shape);
+    }
+    if (shape.maxRows !== undefined && shape.rowCount !== undefined && shape.rowCount > shape.maxRows) {
+        return server("shape-too-large", shape);
+    }
+    if (!queryLimitIsSafe(query, shape, definition)) {
+        return server("query-row-limit-unsafe", shape);
+    }
+    return { source: "local", reason: "local-ready", shape };
+}
+export function defineVisibleShape(definition) {
+    if (!definition.id.trim()) {
+        throw new Error("cache shape id is required");
+    }
+    if (definition.tables.length === 0 || definition.tables.some((table) => !table.trim())) {
+        throw new Error(`cache shape ${definition.id} must include at least one table`);
+    }
+    if (definition.maxRows !== undefined && definition.maxRows <= 0) {
+        throw new Error(`cache shape ${definition.id} maxRows must be positive`);
+    }
+    if (definition.maxBytes !== undefined && definition.maxBytes <= 0) {
+        throw new Error(`cache shape ${definition.id} maxBytes must be positive`);
+    }
+    return {
+        ...definition,
+        tables: [...definition.tables],
+    };
+}
+export function cacheKey(parts) {
+    return [
+        "gonvex",
+        parts.projectId,
+        parts.tenantId,
+        parts.userId,
+        parts.authScope,
+        parts.queryPath,
+        parts.argsHash,
+        parts.schemaVersion,
+        parts.permissionVersion,
+    ].map(escapeKeyPart).join(":");
+}
+export function shouldResetLocalCache(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const message = error.message.toLowerCase();
+    return message.includes("corrupt")
+        || message.includes("integrity")
+        || message.includes("checkpoint")
+        || message.includes("schema mismatch");
+}
+export function cacheFailureAction(error) {
+    if (shouldResetLocalCache(error)) {
+        return { action: "reset-and-server-fallback", reason: "cache-corruption-suspected" };
+    }
+    return { action: "server-fallback", reason: "ordinary-failure" };
+}
+function sameScope(query, shape) {
+    return shape.projectId === query.projectId
+        && shape.tenantId === query.tenantId
+        && shape.userId === query.userId
+        && shape.authScope === query.authScope;
+}
+function shapeCoversQuery(query, definition) {
+    if (query.coveredByShapeIds) {
+        return query.coveredByShapeIds.includes(query.requiredShapeId ?? "");
+    }
+    return definition !== undefined;
+}
+function queryLimitIsSafe(query, shape, definition) {
+    const maxRows = shape.maxRows ?? definition?.maxRows;
+    if (maxRows === undefined) {
+        return true;
+    }
+    if (query.limit !== undefined) {
+        return query.limit <= maxRows;
+    }
+    if (query.estimatedRows !== undefined) {
+        return query.estimatedRows <= maxRows;
+    }
+    return shape.rowCount === undefined || shape.rowCount <= maxRows;
+}
+function server(reason, shape) {
+    return { source: "server", reason, shape };
+}
+function escapeKeyPart(part) {
+    return encodeURIComponent(part);
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AA+EA,MAAM,UAAU,iBAAiB,CAAC,KAAqB,EAAE,WAA6B;IACpF,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC,yBAAyB,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,WAAW,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACvC,OAAO,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,YAAY,EAAE,CAAC;QAC9B,OAAO,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACnC,CAAC;IAED,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IACxD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,MAAM,CAAC,eAAe,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,UAAU,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IACpE,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC;QACzC,OAAO,MAAM,CAAC,4BAA4B,EAAE,KAAK,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;QACjC,OAAO,MAAM,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QAC7B,OAAO,MAAM,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,MAAM,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,KAAK,CAAC,aAAa,KAAK,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,iBAAiB,KAAK,KAAK,CAAC,iBAAiB,EAAE,CAAC;QACvG,OAAO,MAAM,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;QAClG,OAAO,MAAM,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;IACjD,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,UAAgC;IACjE,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QACvF,MAAM,IAAI,KAAK,CAAC,eAAe,UAAU,CAAC,EAAE,kCAAkC,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,UAAU,CAAC,OAAO,KAAK,SAAS,IAAI,UAAU,CAAC,OAAO,IAAI,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CAAC,eAAe,UAAU,CAAC,EAAE,2BAA2B,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,UAAU,CAAC,QAAQ,KAAK,SAAS,IAAI,UAAU,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,KAAK,CAAC,eAAe,UAAU,CAAC,EAAE,4BAA4B,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO;QACL,GAAG,UAAU;QACb,MAAM,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC;KAC/B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KASxB;IACC,OAAO;QACL,QAAQ;QACR,KAAK,CAAC,SAAS;QACf,KAAK,CAAC,QAAQ;QACd,KAAK,CAAC,MAAM;QACZ,KAAK,CAAC,SAAS;QACf,KAAK,CAAC,SAAS;QACf,KAAK,CAAC,QAAQ;QACd,KAAK,CAAC,aAAa;QACnB,KAAK,CAAC,iBAAiB;KACxB,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IAC5C,OAAO,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;WAC7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;WAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;WAC9B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,qBAAqB,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,EAAE,MAAM,EAAE,2BAA2B,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAC;IACvF,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;AACnE,CAAC;AAED,SAAS,SAAS,CAAC,KAAqB,EAAE,KAAsB;IAC9D,OAAO,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS;WACrC,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ;WACjC,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;WAC7B,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS,CAAC;AAC3C,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAqB,EAAE,UAA4C;IAC3F,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC,iBAAiB,CAAC,QAAQ,CAAC,KAAK,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,UAAU,KAAK,SAAS,CAAC;AAClC,CAAC;AAED,SAAS,gBAAgB,CACvB,KAAqB,EACrB,KAAsB,EACtB,UAA4C;IAE5C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,UAAU,EAAE,OAAO,CAAC;IACrD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,KAAK,IAAI,OAAO,CAAC;IAChC,CAAC;IACD,IAAI,KAAK,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC,aAAa,IAAI,OAAO,CAAC;IACxC,CAAC;IACD,OAAO,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,IAAI,OAAO,CAAC;AACnE,CAAC;AAED,SAAS,MAAM,CAAC,MAA0B,EAAE,KAAuB;IACjE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC7C,CAAC;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import type { BrowserTelemetryInfo, JsonValue, MessageTrace, ServerMessage } from "@gonvex/protocol";
+export * from "./cache.js";
+export * from "./cache-coordinator.js";
+export * from "./browser-cache.js";
+export * from "./browser-cache-client.js";
+export * from "./browser-cache-shared-worker.js";
+export * from "./browser-capabilities.js";
+export * from "./persistent-cache.js";
+type SubscriptionHandler = (message: ServerMessage) => void;
+type WatchUpdateHandler = () => void;
+type TelemetryHandler = (event: GonvexTelemetryEvent) => void;
+export type FunctionReference = {
+    kind: string;
+    path: string;
+};
+export type GonvexClientAuth = {
+    project?: string;
+    token?: string;
+    tenant?: string;
+    telemetry?: boolean;
+};
+export type GonvexTelemetryEvent = {
+    type: "mutation" | "action" | "query";
+    id: string;
+    path: string;
+    reason?: "initial" | "invalidate";
+    outcome: "ok" | "error";
+    error?: string;
+    clientSentAtMs?: number;
+    clientReceivedAtMs: number;
+    clientDurationMs?: number;
+    serverTrace?: MessageTrace;
+    device?: BrowserTelemetryInfo;
+};
+export declare class GonvexClient {
+    private readonly url;
+    private socket;
+    private readonly handlers;
+    private readonly querySubscriptions;
+    private readonly telemetryHandlers;
+    private readonly pendingMessages;
+    private auth;
+    private authInFlight;
+    private telemetryEnabled;
+    constructor(url: string, auth?: GonvexClientAuth);
+    setAuth(auth: GonvexClientAuth): void;
+    connect(): void;
+    close(): void;
+    onTelemetry(handler: TelemetryHandler): () => boolean;
+    subscribeQuery(ref: FunctionReference, args: JsonValue | undefined, onMessage: SubscriptionHandler): () => void;
+    watchQuery<T = JsonValue>(ref: FunctionReference, args?: JsonValue): {
+        localQueryResult(): T | undefined;
+        onUpdate(handler: WatchUpdateHandler): () => void;
+    };
+    mutation<T = JsonValue>(ref: FunctionReference, args?: JsonValue): Promise<T>;
+    action<T = JsonValue>(ref: FunctionReference, args?: JsonValue): Promise<T>;
+    query<T = JsonValue>(ref: FunctionReference, args?: JsonValue): Promise<T>;
+    private call;
+    private unsubscribeQueryListener;
+    private emitTelemetryFromCall;
+    private recordTelemetry;
+    private emitTelemetry;
+    private reportTelemetry;
+    private sendAuth;
+    private send;
+    private sendNow;
+    private flushPendingMessages;
+}
+export declare class ConvexReactClient extends GonvexClient {
+    constructor(url: string, auth?: GonvexClientAuth);
+}