@rpcbase/client 0.389.0 → 0.391.0

package/dist/{useQuery-ClKeTB8S.js → useQuery-CUjwBdkK.js}

@@ -298,6 +298,140 @@ const satisfiesProjection = (doc, projection) => {
   }
   return true;
 };
+const getValueAtPath = (doc, path) => {
+  const parts = path.split(".").map((part) => part.trim()).filter(Boolean);
+  if (!parts.length) return void 0;
+  let current = doc;
+  for (const part of parts) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) return void 0;
+    current = current[part];
+  }
+  return current;
+};
+const setValueAtPath = (doc, path, value) => {
+  const parts = path.split(".").map((part) => part.trim()).filter(Boolean);
+  if (!parts.length) return;
+  let current = doc;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const key = parts[i];
+    const existing = current[key];
+    if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+      current[key] = {};
+    }
+    current = current[key];
+  }
+  current[parts[parts.length - 1]] = value;
+};
+const unsetValueAtPath = (doc, path) => {
+  const parts = path.split(".").map((part) => part.trim()).filter(Boolean);
+  if (!parts.length) return;
+  let current = doc;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const key = parts[i];
+    const next = current[key];
+    if (!next || typeof next !== "object" || Array.isArray(next)) return;
+    current = next;
+  }
+  delete current[parts[parts.length - 1]];
+};
+const cloneDoc = (doc) => {
+  try {
+    return structuredClone(doc);
+  } catch {
+    return JSON.parse(JSON.stringify(doc));
+  }
+};
+const toProjectionSpec = (projection) => {
+  const spec = {};
+  for (const [key, value] of Object.entries(projection)) {
+    const path = key.trim();
+    if (!path) continue;
+    if (value === 1 || value === 0) {
+      spec[path] = value;
+    }
+  }
+  return spec;
+};
+const applyProjection = (doc, projection) => {
+  const spec = toProjectionSpec(projection);
+  const includeKeys = Object.keys(spec).filter((key) => spec[key] === 1);
+  const excludeKeys = Object.keys(spec).filter((key) => spec[key] === 0);
+  if (includeKeys.length > 0) {
+    const projected2 = {};
+    for (const key of includeKeys) {
+      const value = getValueAtPath(doc, key);
+      if (value !== void 0) setValueAtPath(projected2, key, value);
+    }
+    if (spec._id !== 0 && Object.hasOwn(doc, "_id")) {
+      projected2._id = doc._id;
+    }
+    return projected2;
+  }
+  const projected = cloneDoc(doc);
+  for (const key of excludeKeys) {
+    unsetValueAtPath(projected, key);
+  }
+  return projected;
+};
+const compareSort = (a, b, sort) => {
+  for (const key of Object.keys(sort)) {
+    const dir = sort[key];
+    const aVal = getValueAtPath(a, key);
+    const bVal = getValueAtPath(b, key);
+    if (typeof aVal === "number" && typeof bVal === "number") {
+      if (aVal < bVal) return -1 * dir;
+      if (aVal > bVal) return 1 * dir;
+      continue;
+    }
+    if (typeof aVal === "string" && typeof bVal === "string") {
+      if (aVal < bVal) return -1 * dir;
+      if (aVal > bVal) return 1 * dir;
+      continue;
+    }
+  }
+  return 0;
+};
+const extractDocId = (value) => {
+  if (typeof value === "string") return value;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "";
+  const id = value._id;
+  return typeof id === "string" ? id : "";
+};
+const matchValue = (docValue, matchValueRaw) => {
+  if (Array.isArray(matchValueRaw)) {
+    if (!Array.isArray(docValue)) return false;
+    if (docValue.length !== matchValueRaw.length) return false;
+    for (let i = 0; i < matchValueRaw.length; i += 1) {
+      const matched = matchValue(docValue[i], matchValueRaw[i]);
+      if (matched === null) return null;
+      if (!matched) return false;
+    }
+    return true;
+  }
+  if (matchValueRaw && typeof matchValueRaw === "object") {
+    const matchObj = matchValueRaw;
+    if (Object.keys(matchObj).some((key) => key.startsWith("$"))) return null;
+    if (!docValue || typeof docValue !== "object" || Array.isArray(docValue)) return false;
+    const docObj = docValue;
+    for (const key of Object.keys(matchObj)) {
+      const matched = matchValue(docObj[key], matchObj[key]);
+      if (matched === null) return null;
+      if (!matched) return false;
+    }
+    return true;
+  }
+  return Object.is(docValue, matchValueRaw);
+};
+const matchesSimpleQuery = (doc, query) => {
+  for (const [key, expected] of Object.entries(query)) {
+    if (key.startsWith("$")) return null;
+    const actual = getValueAtPath(doc, key);
+    const matched = matchValue(actual, expected);
+    if (matched === null) return null;
+    if (!matched) return false;
+  }
+  return true;
+};
 const remapDocFromStorage = (doc) => {
   const next = {};
   for (const [key, value] of Object.entries(doc)) {
@@ -306,10 +440,11 @@ const remapDocFromStorage = (doc) => {
   }
   return next;
 };
-const runQuery = async ({
+const runQueryInternal = async ({
   modelName,
   query = {},
-  options
+  options,
+  strictProjection = false
 }) => {
   const collection = await getCollection(modelName, {
     uid: options.uid
@@ -322,39 +457,291 @@ const runQuery = async ({
     selector: replacedQuery,
     limit
   });
-  let mappedDocs = docs.map(({
+  const mappedDocs = docs.map(({
     _rev: _revIgnored,
     ...rest
   }) => remapDocFromStorage(rest));
+  let filteredDocs = mappedDocs;
   if (options.projection) {
-    mappedDocs = mappedDocs.filter((doc) => satisfiesProjection(doc, options.projection));
+    if (strictProjection && mappedDocs.some((entry) => !satisfiesProjection(entry, options.projection))) {
+      return {
+        data: [],
+        context: {
+          source: "cache"
+        },
+        projectionMismatch: true
+      };
+    }
+    filteredDocs = filteredDocs.filter((entry) => satisfiesProjection(entry, options.projection));
   }
+  let result = filteredDocs;
   if (options.sort) {
-    mappedDocs = mappedDocs.sort((a, b) => {
-      for (const key of Object.keys(options.sort)) {
-        if (!Object.hasOwn(a, key) || !Object.hasOwn(b, key)) continue;
-        const dir = options.sort[key];
-        const aVal = a[key];
-        const bVal = b[key];
-        if (typeof aVal === "number" && typeof bVal === "number") {
-          if (aVal < bVal) return -1 * dir;
-          if (aVal > bVal) return 1 * dir;
-          continue;
-        }
-        if (typeof aVal === "string" && typeof bVal === "string") {
-          if (aVal < bVal) return -1 * dir;
-          if (aVal > bVal) return 1 * dir;
-          continue;
-        }
-      }
-      return 0;
-    });
+    result = result.sort((a, b) => compareSort(a, b, options.sort));
   }
   return {
-    data: mappedDocs,
+    data: result,
     context: {
       source: "cache"
+    },
+    projectionMismatch: false
+  };
+};
+const runQuery = async ({
+  modelName,
+  query = {},
+  options
+}) => {
+  const result = await runQueryInternal({
+    modelName,
+    query,
+    options
+  });
+  return {
+    data: result.data,
+    context: result.context
+  };
+};
+const addWriteDoc = (writes, modelName, doc) => {
+  const docsById = writes.get(modelName) ?? /* @__PURE__ */ new Map();
+  docsById.set(doc._id, doc);
+  writes.set(modelName, docsById);
+};
+const sanitizePopulatedDoc = (doc, populate, writes) => {
+  const next = cloneDoc(doc);
+  for (const entry of populate) {
+    const value = getValueAtPath(next, entry.path);
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      const ids = [];
+      for (const candidate of value) {
+        const id2 = extractDocId(candidate);
+        if (!id2) continue;
+        ids.push(id2);
+        if (!entry.model) continue;
+        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) continue;
+        const candidateDoc = candidate;
+        const nested2 = entry.populate?.length ? sanitizePopulatedDoc(candidateDoc, entry.populate, writes) : cloneDoc(candidateDoc);
+        addWriteDoc(writes, entry.model, nested2);
+      }
+      setValueAtPath(next, entry.path, ids);
+      continue;
     }
+    const id = extractDocId(value);
+    setValueAtPath(next, entry.path, id || null);
+    if (!id) continue;
+    if (!entry.model) continue;
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const valueDoc = value;
+    const nested = entry.populate?.length ? sanitizePopulatedDoc(valueDoc, entry.populate, writes) : cloneDoc(valueDoc);
+    addWriteDoc(writes, entry.model, nested);
+  }
+  return next;
+};
+const updatePopulatedDocs = async ({
+  modelName,
+  data,
+  uid,
+  populate
+}) => {
+  if (!data.length) return;
+  const writes = /* @__PURE__ */ new Map();
+  const roots = data.map((doc) => sanitizePopulatedDoc(doc, populate, writes));
+  await updateDocs(modelName, roots, uid);
+  for (const [targetModelName, docsById] of writes.entries()) {
+    if (!docsById.size) continue;
+    await updateDocs(targetModelName, Array.from(docsById.values()), uid);
+  }
+};
+const loadProjectedDocsByIds = async ({
+  modelName,
+  ids,
+  uid,
+  projection
+}) => {
+  const uniqueIds = Array.from(new Set(ids.filter(Boolean)));
+  if (!uniqueIds.length) {
+    return {
+      rawDocsById: /* @__PURE__ */ new Map(),
+      projectedDocsById: /* @__PURE__ */ new Map(),
+      projectionMismatch: false
+    };
+  }
+  const collection = await getCollection(modelName, {
+    uid
+  });
+  const {
+    docs
+  } = await collection.find({
+    selector: {
+      _id: {
+        $in: uniqueIds
+      }
+    },
+    limit: uniqueIds.length
+  });
+  const rawDocsById = /* @__PURE__ */ new Map();
+  const projectedDocsById = /* @__PURE__ */ new Map();
+  let projectionMismatch = false;
+  for (const rawDoc of docs) {
+    const id = typeof rawDoc._id === "string" ? rawDoc._id : "";
+    if (!id) continue;
+    const {
+      _rev: _revIgnored,
+      ...rest
+    } = rawDoc;
+    const remapped = remapDocFromStorage(rest);
+    if (!satisfiesProjection(remapped, projection)) {
+      projectionMismatch = true;
+      continue;
+    }
+    rawDocsById.set(id, remapped);
+    projectedDocsById.set(id, applyProjection(remapped, projection));
+  }
+  if (projectedDocsById.size < uniqueIds.length) {
+    projectionMismatch = true;
+  }
+  return {
+    rawDocsById,
+    projectedDocsById,
+    projectionMismatch
+  };
+};
+const hydratePopulateEntries = async ({
+  docs,
+  populate,
+  uid
+}) => {
+  const currentDocs = docs;
+  for (const entry of populate) {
+    if (!entry.model) {
+      return {
+        hit: false,
+        data: []
+      };
+    }
+    const descriptors = currentDocs.map((doc) => {
+      const rawValue = getValueAtPath(doc, entry.path);
+      const isArray = Array.isArray(rawValue);
+      const ids = (isArray ? rawValue : [rawValue]).map((candidate) => extractDocId(candidate)).filter(Boolean);
+      return {
+        doc,
+        hasValue: rawValue !== void 0,
+        isArray,
+        ids
+      };
+    });
+    const allIds = descriptors.flatMap((descriptor) => descriptor.ids);
+    const loaded = await loadProjectedDocsByIds({
+      modelName: entry.model,
+      ids: allIds,
+      uid,
+      projection: entry.select
+    });
+    if (loaded.projectionMismatch) {
+      return {
+        hit: false,
+        data: []
+      };
+    }
+    let populatedDocsById = loaded.projectedDocsById;
+    if (entry.match) {
+      const filtered = /* @__PURE__ */ new Map();
+      for (const [id, candidate] of loaded.rawDocsById.entries()) {
+        const matched = matchesSimpleQuery(candidate, entry.match);
+        if (matched === null) return {
+          hit: false,
+          data: []
+        };
+        if (!matched) continue;
+        const projected = populatedDocsById.get(id);
+        if (projected) filtered.set(id, projected);
+      }
+      populatedDocsById = filtered;
+    }
+    if (entry.populate?.length) {
+      const nestedResult = await hydratePopulateEntries({
+        docs: Array.from(populatedDocsById.values()).map((candidate) => cloneDoc(candidate)),
+        populate: entry.populate,
+        uid
+      });
+      if (!nestedResult.hit) {
+        return {
+          hit: false,
+          data: []
+        };
+      }
+      populatedDocsById = nestedResult.data.reduce((acc, candidate) => {
+        const id = extractDocId(candidate);
+        if (id) acc.set(id, candidate);
+        return acc;
+      }, /* @__PURE__ */ new Map());
+    }
+    for (const descriptor of descriptors) {
+      if (!descriptor.hasValue) continue;
+      if (!descriptor.ids.length) {
+        setValueAtPath(descriptor.doc, entry.path, descriptor.isArray ? [] : null);
+        continue;
+      }
+      if (descriptor.isArray) {
+        let values = descriptor.ids.map((id) => populatedDocsById.get(id)).filter((candidate) => Boolean(candidate));
+        if (entry.options?.sort) {
+          values = values.sort((a, b) => compareSort(a, b, entry.options.sort));
+        }
+        if (typeof entry.options?.limit === "number" && Number.isFinite(entry.options.limit)) {
+          values = values.slice(0, Math.max(0, Math.floor(Math.abs(entry.options.limit))));
+        }
+        setValueAtPath(descriptor.doc, entry.path, values);
+        continue;
+      }
+      const value = populatedDocsById.get(descriptor.ids[0]);
+      setValueAtPath(descriptor.doc, entry.path, value ?? null);
+    }
+  }
+  return {
+    hit: true,
+    data: currentDocs
+  };
+};
+const runPopulatedQuery = async ({
+  modelName,
+  query = {},
+  options
+}) => {
+  const rootResult = await runQueryInternal({
+    modelName,
+    query,
+    options: {
+      uid: options.uid,
+      projection: options.projection,
+      sort: options.sort,
+      limit: options.limit
+    },
+    strictProjection: true
+  });
+  if (rootResult.projectionMismatch) {
+    return {
+      hit: false,
+      data: [],
+      context: rootResult.context
+    };
+  }
+  const projectedRoots = rootResult.data.map((doc) => applyProjection(doc, options.projection));
+  const hydrated = await hydratePopulateEntries({
+    docs: projectedRoots.map((doc) => cloneDoc(doc)),
+    populate: options.populate,
+    uid: options.uid
+  });
+  if (!hydrated.hit) {
+    return {
+      hit: false,
+      data: [],
+      context: rootResult.context
+    };
+  }
+  return {
+    hit: true,
+    data: hydrated.data,
+    context: rootResult.context
   };
 };
 const updateDocs = async (modelName, data, uid) => {
@@ -493,6 +880,158 @@ const destroyAllCollections = async () => {
   await Promise.all(dbs.map((db) => db.destroy()));
   collections.clear();
 };
+const EXCLUDE_PROJECTION_ERROR = "must be include-only (value 1); exclusion projection is not supported";
+const sortProjectionSpec = (projection) => {
+  const sorted = {};
+  for (const key of Object.keys(projection).sort()) {
+    sorted[key] = projection[key];
+  }
+  return sorted;
+};
+const normalizeProjectionSpec = (value, source, label) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const raw = value;
+  const normalized = {};
+  let hasExclude = false;
+  for (const [key, rawValue] of Object.entries(raw)) {
+    const path = key.trim();
+    if (!path) continue;
+    if (rawValue === 1 || rawValue === true) {
+      normalized[path] = 1;
+      continue;
+    }
+    if (rawValue === 0 || rawValue === false) {
+      hasExclude = true;
+      continue;
+    }
+    if (typeof rawValue === "number" && Number.isFinite(rawValue)) {
+      if (rawValue === 1) normalized[path] = 1;
+      if (rawValue === 0) hasExclude = true;
+    }
+  }
+  if (hasExclude) {
+    throw new Error(`${source}: ${label} ${EXCLUDE_PROJECTION_ERROR}`);
+  }
+  return Object.keys(normalized).length > 0 ? sortProjectionSpec(normalized) : void 0;
+};
+const normalizeSelectString = (value, source) => {
+  const tokens = value.split(/\s+/).map((token) => token.trim()).filter(Boolean);
+  if (!tokens.length) return void 0;
+  const normalized = {};
+  for (const token of tokens) {
+    let path = token;
+    if (token.startsWith("-")) {
+      throw new Error(`${source}: populate select ${EXCLUDE_PROJECTION_ERROR}`);
+    } else if (token.startsWith("+")) {
+      path = token.slice(1);
+    }
+    path = path.trim();
+    if (!path) continue;
+    normalized[path] = 1;
+  }
+  return Object.keys(normalized).length > 0 ? sortProjectionSpec(normalized) : void 0;
+};
+const normalizePopulateSelect = (value, source) => {
+  if (typeof value === "string") {
+    return normalizeSelectString(value, source);
+  }
+  return normalizeProjectionSpec(value, source, "populate select");
+};
+const normalizePopulateOptions = (value) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const raw = value;
+  const normalized = {};
+  if (raw.sort && typeof raw.sort === "object" && !Array.isArray(raw.sort)) {
+    const sortRaw = raw.sort;
+    const sort = {};
+    for (const [key, rawDirection] of Object.entries(sortRaw)) {
+      const path = key.trim();
+      if (!path) continue;
+      if (rawDirection === 1 || rawDirection === "asc") {
+        sort[path] = 1;
+        continue;
+      }
+      if (rawDirection === -1 || rawDirection === "desc") {
+        sort[path] = -1;
+      }
+    }
+    if (Object.keys(sort).length > 0) {
+      normalized.sort = sort;
+    }
+  }
+  if (typeof raw.limit === "number" && Number.isFinite(raw.limit)) {
+    normalized.limit = Math.max(0, Math.floor(Math.abs(raw.limit)));
+  }
+  return Object.keys(normalized).length > 0 ? normalized : void 0;
+};
+const normalizeString = (value) => {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim();
+  return normalized || void 0;
+};
+const normalizeObject = (value) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  return value;
+};
+const normalizePopulateObject = (value, source) => {
+  const path = normalizeString(value.path);
+  if (!path) {
+    throw new Error(`${source}: populate entries must define a non-empty path`);
+  }
+  const select = normalizePopulateSelect(value.select, source);
+  if (!select) {
+    throw new Error(`${source}: populate entries must define a select projection`);
+  }
+  const nested = value.populate !== void 0 ? normalizePopulateOption(value.populate, source) : void 0;
+  return {
+    path,
+    select,
+    ...normalizeString(value.model) ? {
+      model: normalizeString(value.model)
+    } : {},
+    ...normalizeObject(value.match) ? {
+      match: normalizeObject(value.match)
+    } : {},
+    ...normalizePopulateOptions(value.options) ? {
+      options: normalizePopulateOptions(value.options)
+    } : {},
+    ...nested && nested.length > 0 ? {
+      populate: nested
+    } : {}
+  };
+};
+const normalizePopulateOption = (value, source) => {
+  if (typeof value === "string") {
+    throw new Error(`${source}: populate string syntax is not supported; use object entries with select`);
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      throw new Error(`${source}: populate must contain at least one entry`);
+    }
+    return value.map((entry) => {
+      if (typeof entry === "string") {
+        throw new Error(`${source}: populate string syntax is not supported; use object entries with select`);
+      }
+      return normalizePopulateObject(entry, source);
+    });
+  }
+  return [normalizePopulateObject(value, source)];
+};
+const preparePopulateCacheOptions = (options, source) => {
+  if (!options.populate) return void 0;
+  const rootProjection = normalizeProjectionSpec(options.projection, source, "projection");
+  if (!rootProjection) {
+    throw new Error(`${source}: projection is required when populate is used`);
+  }
+  const populate = normalizePopulateOption(options.populate, source);
+  if (!populate.length) {
+    throw new Error(`${source}: populate must contain at least one entry`);
+  }
+  return {
+    rootProjection,
+    populate
+  };
+};
 const computeRtsQueryKey = (query, options) => {
   const key = options.key ?? "";
   const projection = options.projection ? JSON.stringify(options.projection) : "";
@@ -630,7 +1169,8 @@ const handleQueryPayload = (payload) => {
   if (!callbacks || !callbacks.size) return;
   const subscription = subscriptions.get(cbKey);
   const pageInfo = normalizePageInfo$1(payload.pageInfo);
-  const hasPopulate = Boolean(subscription?.options?.populate);
+  const populateCache = subscription?.populateCache;
+  const hasPopulate = Boolean(populateCache);
   const hasPagination = Boolean(subscription?.options?.pagination || pageInfo);
   const isLocal = !!(txnId && localTxnBuf.includes(txnId));
   const context = {
@@ -648,9 +1188,18 @@ const handleQueryPayload = (payload) => {
   for (const cb of callbacks) cb(null, data, context);
   if (!currentUid) return;
   const docs = Array.isArray(data) ? data.filter(isDocWithId) : [];
-  if (!docs.length) return;
-  if (hasPopulate) return;
   if (hasPagination) return;
+  if (!docs.length) return;
+  if (hasPopulate && populateCache) {
+    void updatePopulatedDocs({
+      modelName,
+      data: docs,
+      uid: currentUid,
+      populate: populateCache.populate
+    }).catch(() => {
+    });
+    return;
+  }
   void updateDocs(modelName, docs, currentUid).catch(() => {
   });
 };
@@ -926,7 +1475,11 @@ const registerQuery = (modelName, query, optionsOrCallback, callbackMaybe, behav
   const cbKey = `${modelName}.${queryKey}`;
   const runInitialNetworkQuery = behavior?.runInitialNetworkQuery !== false;
   const runInitialLocalQuery = behavior?.runInitialLocalQuery !== false;
-  const hasPopulate = Boolean(options.populate);
+  const populateCache = preparePopulateCacheOptions({
+    projection: options.projection,
+    populate: options.populate
+  }, "registerQuery");
+  const hasPopulate = Boolean(populateCache);
   const hasPagination = Boolean(options.pagination);
   const set = queryCallbacks.get(cbKey) ?? /* @__PURE__ */ new Set();
   set.add(callback);
@@ -936,25 +1489,50 @@ const registerQuery = (modelName, query, optionsOrCallback, callbackMaybe, behav
     query,
     options,
     queryKey,
-    runInitialNetworkQuery
+    runInitialNetworkQuery,
+    ...populateCache ? {
+      populateCache
+    } : {}
   });
-  if (currentUid && runInitialLocalQuery && !hasPopulate && !hasPagination) {
-    void runQuery({
-      modelName,
-      query,
-      options: {
-        uid: currentUid,
-        projection: options.projection,
-        sort: options.sort,
-        limit: options.limit
-      }
-    }).then(({
-      data,
-      context
-    }) => {
-      callback?.(null, data, context);
-    }).catch(() => {
-    });
+  if (currentUid && runInitialLocalQuery && !hasPagination) {
+    if (hasPopulate && populateCache) {
+      void runPopulatedQuery({
+        modelName,
+        query,
+        options: {
+          uid: currentUid,
+          projection: populateCache.rootProjection,
+          sort: options.sort,
+          limit: options.limit,
+          populate: populateCache.populate
+        }
+      }).then(({
+        hit,
+        data,
+        context
+      }) => {
+        if (!hit) return;
+        callback?.(null, data, context);
+      }).catch(() => {
+      });
+    } else {
+      void runQuery({
+        modelName,
+        query,
+        options: {
+          uid: currentUid,
+          projection: options.projection,
+          sort: options.sort,
+          limit: options.limit
+        }
+      }).then(({
+        data,
+        context
+      }) => {
+        callback?.(null, data, context);
+      }).catch(() => {
+      });
+    }
   }
   sendToServer({
     type: "register-query",
@@ -988,6 +1566,10 @@ const runNetworkQuery = async ({
   if (typeof modelName !== "string" || modelName.trim().length === 0) {
     throw new Error("runNetworkQuery: modelName must be a non-empty string");
   }
+  preparePopulateCacheOptions({
+    projection: options.projection,
+    populate: options.populate
+  }, "runNetworkQuery");
   const hasTimeout = typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0;
   const timeoutStartedAt = hasTimeout ? Date.now() : 0;
   if (!socket || socket.readyState !== WebSocket.OPEN) {
@@ -1134,10 +1716,20 @@ const flattenLoadedPages = (previousPages, headPage, nextPages) => {
   for (const page of nextPages) merged.push(...page.nodes);
   return dedupeById(merged);
 };
+const assertIncludeOnlyProjection = (projection) => {
+  if (!projection) return;
+  for (const [path, value] of Object.entries(projection)) {
+    if (!path.trim()) continue;
+    if (value !== 1) {
+      throw new Error("useQuery: projection must be include-only (value 1); exclusion projection is not supported");
+    }
+  }
+};
 const useQuery = (modelName, query = {}, options = {}) => {
   if (typeof modelName !== "string" || modelName.trim().length === 0) {
     throw new Error("useQuery: modelName must be a non-empty string");
   }
+  assertIncludeOnlyProjection(options.projection);
   const id = useId();
   const enabled = options.enabled ?? true;
   const ssrEnabled = options.ssr !== false;
@@ -1149,7 +1741,10 @@ const useQuery = (modelName, query = {}, options = {}) => {
   const limitStr = typeof options.limit === "number" ? String(options.limit) : "";
   const populateJson = options.populate ? JSON.stringify(options.populate) : "";
   const paginationJson = options.pagination ? JSON.stringify(options.pagination) : "";
-  const hasPopulate = Boolean(options.populate);
+  preparePopulateCacheOptions({
+    projection: options.projection,
+    populate: options.populate
+  }, "useQuery");
   const isPaginated = Boolean(options.pagination);
   const queryKey = computeRtsQueryKey(query, {
     key,
@@ -1270,7 +1865,7 @@ const useQuery = (modelName, query = {}, options = {}) => {
   useEffect(() => {
     if (!enabled) return;
     const runInitialNetworkQuery = refreshOnMount || !hasSeedData;
-    const runInitialLocalQuery = !hasSeedData && !hasPopulate && !isPaginated;
+    const runInitialLocalQuery = !hasSeedData && !isPaginated;
     const unsubscribe = registerQuery(modelName, query, {
       key,
       projection: options.projection,
@@ -1488,4 +2083,4 @@ export {
   updateDocs as u,
   useQuery as v
 };
-//# sourceMappingURL=useQuery-ClKeTB8S.js.map
+//# sourceMappingURL=useQuery-CUjwBdkK.js.map