pbtsdb 0.7.3 → 0.9.0

package/llms.txt

@@ -197,28 +197,52 @@ function BooksList() {
 
 ## Common Patterns
 
-**Approach 1: Auto-Expand (Recommended)**
+**Approach 1: Related data (Recommended)**
+
+PocketBase `expand` only files related records into their own collections;
+rows never carry `expand`. Read related records from the target collection.
+
 ```typescript
+import { eq } from '@tanstack/db';
+import { materialize } from 'pbtsdb';
+
 const c = createCollection<Schema>(pb, queryClient);
-const authors = c('authors', {});
+const authors = c('authors', { syncMode: 'on-demand' });
 const books = c('books', {
-    expand: {
-        author: authors  // Auto-expand and auto-upsert
-    }
+    relations: { author: authors },   // where expanded records are filed
+    alwaysFetchRelations: ['author'], // fetched with every books request
 });
 
-// Expand is automatic - no .expand() call needed
-const { data } = useLiveQuery((q) => q.from({ books }));
-
-// Expanded records automatically inserted into authors collection
-// data[0].expand?.author is typed!
+const { data } = useLiveQuery((q) =>
+    q.from({ b: books }).select(({ b }) => ({
+        ...b,
+        author: materialize(
+            q.from({ a: authors }).where(({ a }) => eq(a.id, b.author)).findOne()
+        ),
+    }))
+);
+// data[0].author?.name is Authors | undefined and updates when the author changes
 ```
 
-**When to use Auto-Expand:**
-- You want expanded records to populate their own collections automatically
-- Performance: Single server query with server-side expand
+An id-only load (`eq(id, x)`, `inArray(id, [...])`, or an `or` of those) is
+served from the synced store when every id is present, except through a
+`fetchRelations()` view, whose fetch always goes to PocketBase; anything else
+is fetched in one batched request.
+
+**When to use alwaysFetchRelations:**
+- The parent is the only path by which those rows enter an on-demand collection
+- Performance: single server request per fetch of the parent
 - Related data always available when fetching parent records
 
+**Per-query fetchRelations**
+```typescript
+const books = c('books', { relations: { author: authors, tags } });
+const { data } = useLiveQuery((q) => q.from({ books: books.fetchRelations('tags') }));
+// tags referenced by these books are filed into the tags collection; nested
+// paths like 'book.author' resolve through the target's own relations.
+// Views share the base store, subscription, and mutations.
+```
+
 **Approach 2: TanStack Joins**
 ```typescript
 const c = createCollection<Schema>(pb, queryClient);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pbtsdb",
-    "version": "0.7.3",
+    "version": "0.9.0",
     "description": "Type-safe PocketBase integration with TanStack Query and TanStack DB",
     "keywords": [
         "pocketbase",
@@ -78,9 +78,9 @@
     },
     "devDependencies": {
         "@biomejs/biome": "^2.5.0",
-        "@tanstack/db": ">=0.6.8",
-        "@tanstack/query-db-collection": ">=1.0.40",
-        "@tanstack/react-db": ">=0.1.86",
+        "@tanstack/db": ">=0.9.0",
+        "@tanstack/query-db-collection": ">=1.2.13",
+        "@tanstack/react-db": ">=0.3.8",
         "@tanstack/react-query": ">=5.101.0",
         "@testing-library/react": ">=16.3.2",
         "@types/node": ">=25.0.10",

package/dist/chunk-P3KUBRZK.js

@@ -1,517 +0,0 @@
-import { createCollection as createCollection$1, parseWhereExpression, parseOrderByExpression } from '@tanstack/db';
-export { BTreeIndex, BasicIndex, ReverseIndex, createEffect, toArray } from '@tanstack/db';
-import { queryCollectionOptions, DeleteOperationItemNotFoundError } from '@tanstack/query-db-collection';
-
-// src/core.ts
-
-// src/logger.ts
-var defaultLogger = {
-  debug: (msg, context) => {
-    if (process.env.NODE_ENV === "development") {
-      console.debug(`[pbtsdb] ${msg}`, context || "");
-    }
-  },
-  info: (msg, context) => {
-    console.info(`[pbtsdb] ${msg}`, context || "");
-  },
-  warn: (msg, context) => {
-    console.warn(`[pbtsdb] ${msg}`, context || "");
-  },
-  error: (msg, context) => {
-    console.error(`[pbtsdb] ${msg}`, context || "");
-  }
-};
-var currentLogger = defaultLogger;
-var logger = {
-  debug: (msg, context) => currentLogger.debug(msg, context),
-  info: (msg, context) => currentLogger.info(msg, context),
-  warn: (msg, context) => currentLogger.warn(msg, context),
-  error: (msg, context) => currentLogger.error(msg, context)
-};
-function setLogger(customLogger) {
-  currentLogger = customLogger;
-}
-function resetLogger() {
-  currentLogger = defaultLogger;
-}
-function escapeValue(value) {
-  if (value === null) {
-    return "null";
-  }
-  if (typeof value === "boolean") {
-    return value ? "true" : "false";
-  }
-  if (typeof value === "number") {
-    return value.toString();
-  }
-  if (typeof value === "string") {
-    return `"${value.replace(/"/g, '\\"')}"`;
-  }
-  if (value instanceof Date) {
-    return `"${value.toISOString()}"`;
-  }
-  if (Array.isArray(value)) {
-    return `[${value.map(escapeValue).join(",")}]`;
-  }
-  return `"${String(value)}"`;
-}
-function fieldPathToString(path) {
-  return path.join(".");
-}
-function convertToPocketBaseFilter(where) {
-  if (!where) {
-    return void 0;
-  }
-  const result = parseWhereExpression(where, {
-    handlers: {
-      eq: (field, value) => {
-        return `${fieldPathToString(field)} = ${escapeValue(value)}`;
-      },
-      gt: (field, value) => {
-        return `${fieldPathToString(field)} > ${escapeValue(value)}`;
-      },
-      gte: (field, value) => {
-        return `${fieldPathToString(field)} >= ${escapeValue(value)}`;
-      },
-      lt: (field, value) => {
-        return `${fieldPathToString(field)} < ${escapeValue(value)}`;
-      },
-      lte: (field, value) => {
-        return `${fieldPathToString(field)} <= ${escapeValue(value)}`;
-      },
-      and: (...conditions) => {
-        if (conditions.length === 0) return "";
-        if (conditions.length === 1) return conditions[0];
-        return `(${conditions.join(" && ")})`;
-      },
-      or: (...conditions) => {
-        if (conditions.length === 0) return "";
-        if (conditions.length === 1) return conditions[0];
-        return `(${conditions.join(" || ")})`;
-      },
-      not: (condition) => {
-        return `!(${condition})`;
-      },
-      in: (field, values) => {
-        const valueArray = Array.isArray(values) ? values : [values];
-        const uniqueValues = [...new Set(valueArray)];
-        const fieldStr = fieldPathToString(field);
-        const conditions = uniqueValues.map((v) => `${fieldStr} = ${escapeValue(v)}`);
-        return conditions.length > 1 ? `(${conditions.join(" || ")})` : conditions[0];
-      },
-      like: (field, value) => {
-        return `${fieldPathToString(field)} ~ ${escapeValue(value)}`;
-      },
-      isNull: (field) => {
-        return `${fieldPathToString(field)} = null`;
-      },
-      isUndefined: (field) => {
-        return `${fieldPathToString(field)} = null`;
-      }
-    },
-    onUnknownOperator: (operator, _args) => {
-      throw new Error(
-        `Unsupported operator '${operator}' for PocketBase filter conversion. Supported operators: eq, gt, gte, lt, lte, in, like, and, or, not, isNull, isUndefined`
-      );
-    }
-  });
-  return result || void 0;
-}
-function convertToPocketBaseSort(orderBy) {
-  if (!orderBy) {
-    return void 0;
-  }
-  const sorts = parseOrderByExpression(orderBy);
-  if (sorts.length === 0) {
-    return void 0;
-  }
-  return sorts.map((sort) => {
-    const field = fieldPathToString(sort.field);
-    return sort.direction === "desc" ? `-${field}` : field;
-  }).join(",");
-}
-
-// src/collection.ts
-function createCollection(pb, queryClient, factoryOptions) {
-  return (collectionName, options) => {
-    const expandStores = options?.expand;
-    const expandString = expandStores ? Object.keys(expandStores).sort().join(",") : void 0;
-    const ignoreAutoCancellation = options?.ignoreAutoCancellation ?? true;
-    const refetchOnMutation = options?.refetchOnMutation ?? false;
-    async function upsertExpandedRelation(key, value, stores) {
-      const targetStore = stores[key];
-      if (!targetStore.utils) return;
-      if (!targetStore.isReady()) {
-        if (targetStore.config?.syncMode === "on-demand") {
-          await targetStore._sync.startSync();
-        } else {
-          logger.warn(
-            `not syncing ${key} on ${collectionName} because store is not yet ready`
-          );
-          return;
-        }
-      }
-      const values = Array.isArray(value) ? value : [value];
-      targetStore.utils.writeUpsert(values);
-    }
-    async function upsertExpandedRelations(items) {
-      if (!expandStores) return;
-      for (const record of items) {
-        const expandData = record.expand;
-        if (!expandData) continue;
-        for (const [key, value] of Object.entries(expandData)) {
-          await upsertExpandedRelation(key, value, expandStores);
-        }
-      }
-    }
-    async function fetchItems(loadOptions) {
-      const filter = convertToPocketBaseFilter(loadOptions?.where);
-      const sort = convertToPocketBaseSort(loadOptions?.orderBy);
-      const limit = loadOptions?.limit;
-      if (limit) {
-        const result = await pb.collection(collectionName).getList(1, limit, {
-          filter,
-          sort,
-          skipTotal: true,
-          // Optimize by skipping total count
-          expand: expandString
-        });
-        return result.items;
-      }
-      return await pb.collection(collectionName).getFullList({
-        filter,
-        sort,
-        expand: expandString
-      });
-    }
-    const inFlightConfirmedIds = /* @__PURE__ */ new Set();
-    function markConfirmedPresent(records) {
-      if (inFlightConfirmedIds.size === 0) return;
-      for (const record of records) {
-        const id = record?.id;
-        if (typeof id !== "string") continue;
-        for (const confirmed of inFlightConfirmedIds) confirmed.add(id);
-      }
-    }
-    function withRowsConfirmedMidFlight(items, confirmedMidFlight) {
-      if (confirmedMidFlight.size === 0) return items;
-      const resultIds = new Set(
-        items.map((item) => item?.id)
-      );
-      const mergedIds = [...confirmedMidFlight].filter(
-        (id) => !resultIds.has(id) && collection._state.syncedData.has(id)
-      );
-      if (mergedIds.length === 0) return items;
-      logger.debug("Merging rows confirmed while fetch was in flight", {
-        collectionName,
-        ids: mergedIds
-      });
-      return [
-        ...items,
-        ...mergedIds.map((id) => collection._state.syncedData.get(id))
-      ];
-    }
-    async function fetchRecords(loadOptions, queryKey) {
-      const confirmedMidFlight = /* @__PURE__ */ new Set();
-      inFlightConfirmedIds.add(confirmedMidFlight);
-      try {
-        let items;
-        try {
-          items = await fetchItems(loadOptions);
-        } catch (error) {
-          if (ignoreAutoCancellation && error instanceof Error && error.message.includes("autocancelled")) {
-            return withRowsConfirmedMidFlight(
-              queryClient.getQueryData(queryKey ?? [collectionName]) ?? [],
-              confirmedMidFlight
-            );
-          }
-          throw error;
-        }
-        await upsertExpandedRelations(items);
-        return withRowsConfirmedMidFlight(items, confirmedMidFlight);
-      } finally {
-        inFlightConfirmedIds.delete(confirmedMidFlight);
-      }
-    }
-    const collectionOptions = queryCollectionOptions({
-      ...options?.collectionOptions,
-      queryClient,
-      queryKey: [collectionName],
-      syncMode: options?.syncMode ?? "eager",
-      queryFn: async (ctx) => {
-        return fetchRecords(
-          ctx.meta?.loadSubsetOptions,
-          ctx.queryKey
-        );
-      },
-      getKey: (item) => {
-        const record = item;
-        if (!record || typeof record !== "object" || !("id" in record)) {
-          throw new Error(
-            `Record in collection '${collectionName}' is missing required 'id' field. Received: ${JSON.stringify(item)}`
-          );
-        }
-        return record.id;
-      },
-      onInsert: options?.onInsert === false ? void 0 : options?.onInsert ?? (async ({ transaction }) => {
-        const created = await Promise.all(
-          transaction.mutations.map(async (mutation) => {
-            const {
-              created: _created,
-              updated: _updated,
-              collectionId: _collectionId,
-              collectionName: _collectionName,
-              ...data
-            } = mutation.modified;
-            return pb.collection(collectionName).create(data);
-          })
-        );
-        writeBackAfterPersisted(transaction, created);
-        return { refetch: refetchOnMutation };
-      }),
-      onUpdate: options?.onUpdate === false ? void 0 : options?.onUpdate ?? (async ({ transaction }) => {
-        const updated = await Promise.all(
-          transaction.mutations.map(async (mutation) => {
-            const recordWithId = mutation.original;
-            return pb.collection(collectionName).update(recordWithId.id, mutation.changes);
-          })
-        );
-        writeBackAfterPersisted(transaction, updated);
-        return { refetch: refetchOnMutation };
-      }),
-      onDelete: options?.onDelete === false ? void 0 : options?.onDelete ?? (async ({ transaction }) => {
-        await Promise.all(
-          transaction.mutations.map(async (mutation) => {
-            const recordWithId = mutation.original;
-            await pb.collection(collectionName).delete(recordWithId.id);
-          })
-        );
-        return { refetch: refetchOnMutation };
-      })
-    });
-    function writeBackAfterPersisted(transaction, records) {
-      markConfirmedPresent(records);
-      void transaction.isPersisted.promise.then(
-        () => {
-          if (!collection.utils || !collection.isReady()) return;
-          const fresh = records.filter((record) => !isStaleServerRecord(record));
-          if (fresh.length === 0) return;
-          writeOwn(() => collection.utils.writeUpsert(fresh));
-        },
-        // A rejected transaction rolled its draft back; there is
-        // nothing to write and nothing to report here.
-        () => void 0
-      );
-    }
-    let applyingOwnWrite = false;
-    function writeOwn(fn) {
-      applyingOwnWrite = true;
-      try {
-        fn();
-      } finally {
-        applyingOwnWrite = false;
-      }
-    }
-    function syncedWriteKey(op) {
-      if (op.type !== "insert" && op.type !== "update") return null;
-      if (typeof op.key === "string") return op.key;
-      const id = op.value?.id;
-      return typeof id === "string" ? id : null;
-    }
-    function shouldDropSyncedWrite(op) {
-      const key = syncedWriteKey(op);
-      if (key === null) return false;
-      if (!applyingOwnWrite && hasPendingOptimisticMutation(key) && collection._state.syncedData.has(key)) {
-        logger.debug("Dropping synced write for optimistically-pending row", {
-          collectionName,
-          id: key
-        });
-        return true;
-      }
-      if (isStaleServerRecord(op.value)) {
-        logger.debug("Dropping stale synced write", { collectionName, id: key });
-        return true;
-      }
-      return false;
-    }
-    const innerSync = collectionOptions.sync.sync;
-    collectionOptions.sync = {
-      ...collectionOptions.sync,
-      sync: (params) => {
-        const guardedWrite = (message) => {
-          if (shouldDropSyncedWrite(
-            message
-          )) {
-            return;
-          }
-          return params.write(message);
-        };
-        return innerSync({ ...params, write: guardedWrite });
-      }
-    };
-    const collection = createCollection$1(collectionOptions);
-    function hasPendingOptimisticMutation(key) {
-      const state = collection._state;
-      return state.optimisticUpserts.has(key) || state.optimisticDeletes.has(key);
-    }
-    function recordUpdatedAt(record) {
-      const updated = record?.updated;
-      return typeof updated === "string" && updated !== "" ? updated : void 0;
-    }
-    function isStaleServerRecord(record) {
-      const id = record?.id;
-      if (typeof id !== "string") return false;
-      const incoming = recordUpdatedAt(record);
-      if (!incoming) return false;
-      const current = recordUpdatedAt(
-        collection._state.syncedData.get(id)
-      );
-      if (current === void 0) return false;
-      return incoming < current;
-    }
-    function isStaleEcho(event) {
-      if (event.action !== "create" && event.action !== "update") return false;
-      if (!isStaleServerRecord(event.record)) return false;
-      logger.debug("Ignoring stale realtime echo", {
-        collectionName,
-        id: event.record?.id
-      });
-      return true;
-    }
-    let unsubscribeFn = null;
-    let isSubscribed = false;
-    let subscriptionPromise = null;
-    let subscriptionResolve = null;
-    function markEchoPresence(event) {
-      if (event.action !== "delete") markConfirmedPresent([event.record]);
-    }
-    const handleRealtimeEvent = (event) => {
-      if (!collection.utils) return;
-      markEchoPresence(event);
-      if (isStaleEcho(event)) return;
-      try {
-        writeOwn(
-          () => collection.utils.writeBatch(() => {
-            switch (event.action) {
-              case "create":
-                collection.utils.writeInsert(event.record);
-                break;
-              case "update":
-                collection.utils.writeUpsert(event.record);
-                break;
-              case "delete":
-                if (event.record && "id" in event.record) {
-                  collection.utils.writeDelete(
-                    event.record.id
-                  );
-                }
-                break;
-            }
-          })
-        );
-      } catch (error) {
-        if (error instanceof DeleteOperationItemNotFoundError) {
-          logger.debug("Ignoring delete echo for already-removed record", {
-            collectionName,
-            id: event.record?.id
-          });
-        } else {
-          throw error;
-        }
-      }
-    };
-    const startSubscription = async () => {
-      if (isSubscribed) return;
-      if (!subscriptionPromise) {
-        subscriptionPromise = new Promise((resolve) => {
-          subscriptionResolve = resolve;
-        });
-      }
-      try {
-        unsubscribeFn = await pb.collection(collectionName).subscribe("*", handleRealtimeEvent, factoryOptions?.subscribeOptions?.());
-        isSubscribed = true;
-        logger.debug("Subscription started", { collectionName });
-        if (subscriptionResolve) {
-          subscriptionResolve();
-        }
-      } catch (error) {
-        logger.error("Failed to start subscription", { collectionName, error });
-      }
-    };
-    const stopSubscription = async () => {
-      if (!isSubscribed || !unsubscribeFn) return;
-      try {
-        await unsubscribeFn();
-        unsubscribeFn = null;
-        isSubscribed = false;
-        subscriptionPromise = null;
-        subscriptionResolve = null;
-        logger.debug("Subscription stopped", { collectionName });
-      } catch (error) {
-        logger.debug("Unsubscribe failed (expected if connection closed)", {
-          collectionName,
-          error
-        });
-      }
-    };
-    const waitForSubscription = async (timeout = 5e3) => {
-      if (isSubscribed) return;
-      if (!subscriptionPromise) {
-        await new Promise((resolve) => {
-          const checkInterval = setInterval(() => {
-            if (subscriptionPromise) {
-              clearInterval(checkInterval);
-              resolve();
-            }
-          }, 10);
-          setTimeout(() => {
-            clearInterval(checkInterval);
-            resolve();
-          }, timeout);
-        });
-      }
-      if (subscriptionPromise) {
-        await Promise.race([
-          subscriptionPromise,
-          new Promise(
-            (_, reject) => setTimeout(() => reject(new Error("Subscription timeout")), timeout)
-          )
-        ]);
-      }
-    };
-    collection.on(
-      "subscribers:change",
-      (event) => {
-        const newCount = event.subscriberCount;
-        const previousCount = event.previousSubscriberCount;
-        if (newCount > 0 && previousCount === 0) {
-          startSubscription().catch(() => {
-          });
-        } else if (newCount === 0 && previousCount > 0) {
-          stopSubscription().catch(() => {
-          });
-        }
-      }
-    );
-    Object.assign(collection, {
-      collectionName,
-      waitForSubscription,
-      isSubscribed: () => isSubscribed
-    });
-    return collection;
-  };
-}
-
-// src/util.ts
-function newRecordId() {
-  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
-  let result = "";
-  for (let i = 0; i < 15; i++) {
-    result += chars.charAt(Math.floor(Math.random() * chars.length));
-  }
-  return result;
-}
-
-export { createCollection, newRecordId, resetLogger, setLogger };
-//# sourceMappingURL=chunk-P3KUBRZK.js.map
-//# sourceMappingURL=chunk-P3KUBRZK.js.map