shelving 1.68.0 → 1.68.1

package/index.js

@@ -19,5 +19,8 @@ export * from "./update/index.js";
 export * from "./util/index.js";
 // Integrations.
 // export * from "./react/index.js"; // Not exported.
+// export * from "./firestore/client/index.js"; // Not exported.
+// export * from "./firestore/lite/index.js"; // Not exported.
+// export * from "./firestore/server/index.js"; // Not exported.
 // Testing.
 // export * from "./test/index.js"; // Not exported.

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.68.0",
+	"version": "1.68.1",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -29,11 +29,12 @@
 		"./firestore/lite": "./firestore/lite/index.js",
 		"./firestore/server": "./firestore/server/index.js",
 		"./markup": "./markup/index.js",
+		"./observe": "./observe/index.js",
 		"./provider": "./provider/index.js",
 		"./query": "./query/index.js",
 		"./react": "./react/index.js",
 		"./schema": "./schema/index.js",
-		"./stream": "./stream/index.js",
+		"./state": "./state/index.js",
 		"./test": "./test/index.js",
 		"./update": "./update/index.js",
 		"./util": "./util/index.js"

package/react/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./useLazy.js";
 export * from "./useReduce.js";
 export * from "./useInstance.js";
+export * from "./useCache.js";
 export * from "./useSubscribe.js";
 export * from "./useDocument.js";
 export * from "./useQuery.js";

package/react/index.js

@@ -2,6 +2,7 @@
 export * from "./useLazy.js";
 export * from "./useReduce.js";
 export * from "./useInstance.js";
+export * from "./useCache.js";
 // Observables.
 export * from "./useSubscribe.js";
 // DB.

package/react/useCache.d.ts

@@ -15,12 +15,32 @@ export declare class CacheController<T> {
 /**
  * Default cache
  * - This is a flexible generic cache intended to be the default.
- * - Use this cache unless
+ * - Use this cache unless you want to cache a completely independent set of items without interference.
  */
 export declare const CACHE: CacheController<any>;
-/** Use a global cache in a component. */
+/**
+ * Use a global cache in a component.
+ * - Throws an error if used outside of `<Cache>`
+ */
 export declare const useCache: () => Map<string, any>;
-/** Component that provides a global cache to its children. */
+/**
+ * Component that provides a global cache to its children.
+ *
+ * Note: If mounted globally this cache will bloat over time, so you need a strategy to clear or reset the cache occasionally.
+ *
+ * A good strategy is to wrap a separate `<Cache>` around each page of your app.
+ * This means the cache can only grow to the size of each page and the memory is released when the user navigates to a new page.
+ * You might need to use `<Cache key="something unique to the page">` to ensure the cache component is destroyed and remounted for each page.
+ *
+ * Put a `<Suspense>` boundary _inside_ `<Cache>`
+ * - This prevents promises being thrown up through the cache causing it to be destroyed.
+ * - When the promise resolves and the render is tried again the data would not exist (because the cache was destroyed).
+ * - This will cause an infinite loading loop.
+ *
+ * Put your error boundary _outside_ your `<Cache>`
+ * - The error being thrown up through the cache causes it to be destroyed.
+ * - This means when the uses tells the error boundary to try again (if supported) all data on the page will be retried.
+ */
 export declare const Cache: ({ children }: {
     children: React.ReactNode;
 }) => React.ReactElement | null;

package/react/useCache.js

@@ -27,10 +27,30 @@ const _reduceMap = (previous) => previous || new Map();
 /**
  * Default cache
  * - This is a flexible generic cache intended to be the default.
- * - Use this cache unless
+ * - Use this cache unless you want to cache a completely independent set of items without interference.
  */
 export const CACHE = new CacheController(); // eslint-disable-line @typescript-eslint/no-explicit-any
-/** Use a global cache in a component. */
+/**
+ * Use a global cache in a component.
+ * - Throws an error if used outside of `<Cache>`
+ */
 export const useCache = CACHE.useCache;
-/** Component that provides a global cache to its children. */
+/**
+ * Component that provides a global cache to its children.
+ *
+ * Note: If mounted globally this cache will bloat over time, so you need a strategy to clear or reset the cache occasionally.
+ *
+ * A good strategy is to wrap a separate `<Cache>` around each page of your app.
+ * This means the cache can only grow to the size of each page and the memory is released when the user navigates to a new page.
+ * You might need to use `<Cache key="something unique to the page">` to ensure the cache component is destroyed and remounted for each page.
+ *
+ * Put a `<Suspense>` boundary _inside_ `<Cache>`
+ * - This prevents promises being thrown up through the cache causing it to be destroyed.
+ * - When the promise resolves and the render is tried again the data would not exist (because the cache was destroyed).
+ * - This will cause an infinite loading loop.
+ *
+ * Put your error boundary _outside_ your `<Cache>`
+ * - The error being thrown up through the cache causes it to be destroyed.
+ * - This means when the uses tells the error boundary to try again (if supported) all data on the page will be retried.
+ */
 export const Cache = CACHE.Cache;

package/react/useDocument.d.ts

@@ -23,6 +23,9 @@ export declare class DocumentState<T extends Data> extends State<OptionalEntity<
     protected _addFirstObserver(): void;
     protected _removeLastObserver(): void;
 }
-/** Use a document in a React component. */
+/**
+ * Use a document in a React component.
+ * - Uses the default cache, so will error if not used inside `<Cache>`
+ */
 export declare function useDocument<T extends Data>(ref: DocumentReference<T>): DocumentState<T>;
 export declare function useDocument<T extends Data>(ref?: DocumentReference<T>): DocumentState<T> | undefined;

package/react/useDocument.js

@@ -1,5 +1,5 @@
 import { reduceMapItem } from "../util/map.js";
-import { getDocumentData, isSameReference } from "../db/Reference.js";
+import { getDocumentData } from "../db/Reference.js";
 import { CacheProvider } from "../provider/CacheProvider.js";
 import { findSourceProvider } from "../provider/ThroughProvider.js";
 import { State } from "../state/State.js";
@@ -75,7 +75,7 @@ export class DocumentState extends State {
     }
 }
 /** Reuse the previous `DocumentState` or create a new one. */
-const _reduceDocumentState = (existing, ref) => (existing && isSameReference(existing.ref, ref) ? existing : new DocumentState(ref));
+const _reduceDocumentState = (existing, ref) => existing || new DocumentState(ref);
 export function useDocument(ref) {
     const cache = useCache();
     const state = ref ? reduceMapItem(cache, ref.toString(), _reduceDocumentState, ref) : undefined;

package/react/useQuery.d.ts

@@ -40,6 +40,9 @@ export declare class QueryState<T extends Data> extends State<Entities<T>> {
      */
     readonly loadMore: () => Promise<void>;
 }
-/** Use a query in a React component. */
+/**
+ * Use a query in a React component.
+ * - Uses the default cache, so will error if not used inside `<Cache>`
+ */
 export declare function useQuery<T extends Data>(ref: QueryReference<T>): QueryState<T>;
 export declare function useQuery<T extends Data>(ref?: QueryReference<T>): QueryState<T> | undefined;

package/react/useQuery.js

@@ -1,5 +1,5 @@
 import { reduceMapItem } from "../util/map.js";
-import { getQueryFirstData, getQueryFirstValue, isSameReference } from "../db/Reference.js";
+import { getQueryFirstData, getQueryFirstValue } from "../db/Reference.js";
 import { CacheProvider } from "../provider/CacheProvider.js";
 import { findSourceProvider } from "../provider/ThroughProvider.js";
 import { State } from "../state/State.js";
@@ -120,7 +120,7 @@ export class QueryState extends State {
     }
 }
 /** Reuse the previous `QueryState` or create a new one. */
-const _reduceQueryState = (existing, ref) => (existing && isSameReference(existing.ref, ref) ? existing : new QueryState(ref));
+const _reduceQueryState = (existing, ref) => existing || new QueryState(ref);
 export function useQuery(ref) {
     const cache = useCache();
     const state = ref ? reduceMapItem(cache, ref.toString(), _reduceQueryState, ref) : undefined;