@linkedrecords/react 0.4.0 → 0.6.0

package/dist/index.d.mts

@@ -8,19 +8,46 @@ interface LinkedRecordsContextType {
 }
 declare const LinkedRecordsContext: react.Context<LinkedRecordsContextType | undefined>;
 
+type OIDCConfig = NonNullable<ConstructorParameters<typeof LinkedRecords>[1]>;
+interface LinkedRecordsConfig {
+    oidcConfig?: OIDCConfig;
+    autoHandleRedirect?: boolean;
+    deferUserInfoFetching?: boolean;
+    loginHandler?: () => void;
+    connectionLostHandler?: (err?: any) => void;
+    unknownServerErrorHandler?: (response: any) => void;
+    quotaViolationErrorHandler?: (response: any) => void;
+    authorizationErrorHandler?: (response: any) => void;
+}
 interface LinkedRecordsProviderProps {
     children: ReactNode;
     serverUrl: string;
+    config?: LinkedRecordsConfig;
 }
-declare function LinkedRecordsProvider({ children, serverUrl }: LinkedRecordsProviderProps): react_jsx_runtime.JSX.Element;
+declare function LinkedRecordsProvider({ children, serverUrl, config }: LinkedRecordsProviderProps): react_jsx_runtime.JSX.Element;
 
 interface KVValue {
-    [key: string]: KVValue | string | boolean | number | undefined;
+    [key: string]: KVValue | string | boolean | number | Date | undefined;
+}
+interface KVRecord extends KVValue {
+    _id?: string;
+    _createdAt?: Date;
 }
-declare function useKeyValueRecords(query: any[]): KVValue[];
+declare function useKeyValueRecordsWithStatus(query: any[]): {
+    records: KVRecord[];
+    isLoading: boolean;
+};
+declare function useKeyValueRecords(query: any[]): KVRecord[];
 /** @deprecated Use useKeyValueRecords instead. */
 declare const useKeyValueAttributes: typeof useKeyValueRecords;
 
+type FactQuery = Parameters<LinkedRecords['Fact']['findAll']>[0];
+type Fact = Awaited<ReturnType<LinkedRecords['Fact']['findAll']>>[number];
+declare function useFacts(query: FactQuery): {
+    facts: Fact[];
+    reload: () => void;
+};
+
 declare function useLinkedRecords(): LinkedRecordsContextType;
 
 type UserInfo = {
@@ -28,4 +55,6 @@ type UserInfo = {
 };
 declare function useUserInfo(): UserInfo | null;
 
-export { LinkedRecordsContext, type LinkedRecordsContextType, LinkedRecordsProvider, useKeyValueAttributes, useKeyValueRecords, useLinkedRecords, useUserInfo };
+declare function useActorId(): string | undefined;
+
+export { type KVRecord, type LinkedRecordsConfig, LinkedRecordsContext, type LinkedRecordsContextType, LinkedRecordsProvider, useActorId, useFacts, useKeyValueAttributes, useKeyValueRecords, useKeyValueRecordsWithStatus, useLinkedRecords, useUserInfo };

package/dist/index.d.ts

@@ -8,19 +8,46 @@ interface LinkedRecordsContextType {
 }
 declare const LinkedRecordsContext: react.Context<LinkedRecordsContextType | undefined>;
 
+type OIDCConfig = NonNullable<ConstructorParameters<typeof LinkedRecords>[1]>;
+interface LinkedRecordsConfig {
+    oidcConfig?: OIDCConfig;
+    autoHandleRedirect?: boolean;
+    deferUserInfoFetching?: boolean;
+    loginHandler?: () => void;
+    connectionLostHandler?: (err?: any) => void;
+    unknownServerErrorHandler?: (response: any) => void;
+    quotaViolationErrorHandler?: (response: any) => void;
+    authorizationErrorHandler?: (response: any) => void;
+}
 interface LinkedRecordsProviderProps {
     children: ReactNode;
     serverUrl: string;
+    config?: LinkedRecordsConfig;
 }
-declare function LinkedRecordsProvider({ children, serverUrl }: LinkedRecordsProviderProps): react_jsx_runtime.JSX.Element;
+declare function LinkedRecordsProvider({ children, serverUrl, config }: LinkedRecordsProviderProps): react_jsx_runtime.JSX.Element;
 
 interface KVValue {
-    [key: string]: KVValue | string | boolean | number | undefined;
+    [key: string]: KVValue | string | boolean | number | Date | undefined;
+}
+interface KVRecord extends KVValue {
+    _id?: string;
+    _createdAt?: Date;
 }
-declare function useKeyValueRecords(query: any[]): KVValue[];
+declare function useKeyValueRecordsWithStatus(query: any[]): {
+    records: KVRecord[];
+    isLoading: boolean;
+};
+declare function useKeyValueRecords(query: any[]): KVRecord[];
 /** @deprecated Use useKeyValueRecords instead. */
 declare const useKeyValueAttributes: typeof useKeyValueRecords;
 
+type FactQuery = Parameters<LinkedRecords['Fact']['findAll']>[0];
+type Fact = Awaited<ReturnType<LinkedRecords['Fact']['findAll']>>[number];
+declare function useFacts(query: FactQuery): {
+    facts: Fact[];
+    reload: () => void;
+};
+
 declare function useLinkedRecords(): LinkedRecordsContextType;
 
 type UserInfo = {
@@ -28,4 +55,6 @@ type UserInfo = {
 };
 declare function useUserInfo(): UserInfo | null;
 
-export { LinkedRecordsContext, type LinkedRecordsContextType, LinkedRecordsProvider, useKeyValueAttributes, useKeyValueRecords, useLinkedRecords, useUserInfo };
+declare function useActorId(): string | undefined;
+
+export { type KVRecord, type LinkedRecordsConfig, LinkedRecordsContext, type LinkedRecordsContextType, LinkedRecordsProvider, useActorId, useFacts, useKeyValueAttributes, useKeyValueRecords, useKeyValueRecordsWithStatus, useLinkedRecords, useUserInfo };

package/dist/index.js

@@ -32,8 +32,11 @@ var index_exports = {};
 __export(index_exports, {
   LinkedRecordsContext: () => LinkedRecordsContext,
   LinkedRecordsProvider: () => LinkedRecordsProvider,
+  useActorId: () => useActorId,
+  useFacts: () => useFacts,
   useKeyValueAttributes: () => useKeyValueAttributes,
   useKeyValueRecords: () => useKeyValueRecords,
+  useKeyValueRecordsWithStatus: () => useKeyValueRecordsWithStatus,
   useLinkedRecords: () => useLinkedRecords,
   useUserInfo: () => useUserInfo
 });
@@ -47,8 +50,22 @@ var LinkedRecordsContext = (0, import_react.createContext)(void 0);
 var import_react2 = require("react");
 var import_browser = __toESM(require("@linkedrecords/browser"));
 var import_jsx_runtime = require("react/jsx-runtime");
-function LinkedRecordsProvider({ children, serverUrl }) {
-  const lr = import_browser.default.getPublicClient(serverUrl);
+function createClient(serverUrl, config) {
+  const lr = new import_browser.default(
+    new URL(serverUrl),
+    config.oidcConfig,
+    config.autoHandleRedirect,
+    config.deferUserInfoFetching
+  );
+  if (config.loginHandler) lr.setLoginHandler(config.loginHandler);
+  if (config.connectionLostHandler) lr.setConnectionLostHandler(config.connectionLostHandler);
+  if (config.unknownServerErrorHandler) lr.setUnknownServerErrorHandler(config.unknownServerErrorHandler);
+  if (config.quotaViolationErrorHandler) lr.setQuotaViolationErrorHandler(config.quotaViolationErrorHandler);
+  if (config.authorizationErrorHandler) lr.setAuthorizationErrorHandler(config.authorizationErrorHandler);
+  return lr;
+}
+function LinkedRecordsProvider({ children, serverUrl, config }) {
+  const [lr] = (0, import_react2.useState)(() => config ? createClient(serverUrl, config) : import_browser.default.getPublicClient(serverUrl));
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(LinkedRecordsContext.Provider, { value: { lr }, children });
 }
 
@@ -65,14 +82,27 @@ function useLinkedRecords() {
   return context;
 }
 
+// src/queryKey.ts
+function getQueryKey(query) {
+  return JSON.stringify(query, (_, v) => typeof v === "function" ? `fn:${v.name}` : v);
+}
+
 // src/useRecords.ts
 var import_browser2 = require("@linkedrecords/browser");
-function useKeyValueRecords(query) {
+function useKeyValueRecordsWithStatus(query) {
   const { lr } = useLinkedRecords();
   const [records, setRecords] = (0, import_react4.useState)([]);
+  const [isLoading, setIsLoading] = (0, import_react4.useState)(true);
+  const queryKey = getQueryKey(query);
   (0, import_react4.useEffect)(() => {
+    setIsLoading(true);
+    let cancelled = false;
+    const subscribedRecordIds = /* @__PURE__ */ new Set();
     const unsubscribeFnPromise = new Promise((resolve) => {
       const checkActorId = () => {
+        if (cancelled) {
+          return;
+        }
         if (lr.actorId !== void 0) {
           resolve();
         } else {
@@ -89,14 +119,29 @@ function useKeyValueRecords(query) {
       }, async ({ records: records2 }) => {
         const values = await Promise.all(records2.map(async (r) => ({
           _id: r.id,
+          _createdAt: r.createdAt,
           ...await r.getValue()
         })));
+        if (cancelled) {
+          return;
+        }
         setRecords(values);
+        setIsLoading(false);
         records2.forEach((r) => {
+          if (subscribedRecordIds.has(r.id)) {
+            return;
+          }
+          subscribedRecordIds.add(r.id);
           r.subscribe(async () => {
+            if (cancelled) {
+              return;
+            }
             const newValue = await r.getValue();
+            if (cancelled) {
+              return;
+            }
             setRecords((prev) => prev.map(
-              (v) => v._id === r.id ? { _id: r.id, ...newValue } : v
+              (v) => v._id === r.id ? { _id: r.id, _createdAt: r.createdAt, ...newValue } : v
             ));
           });
         });
@@ -106,29 +151,77 @@ function useKeyValueRecords(query) {
       };
     });
     return () => {
+      cancelled = true;
       unsubscribeFnPromise.then((fn) => fn());
     };
-  }, [lr.Record, setRecords]);
-  return records;
+  }, [lr, queryKey]);
+  return { records, isLoading };
+}
+function useKeyValueRecords(query) {
+  return useKeyValueRecordsWithStatus(query).records;
 }
 var useKeyValueAttributes = useKeyValueRecords;
 
-// src/useUserInfo.ts
+// src/useFacts.ts
 var import_react5 = require("react");
-function useUserInfo() {
+function useFacts(query) {
   const { lr } = useLinkedRecords();
-  const [userInfo, setUserInfo] = (0, import_react5.useState)(null);
+  const [facts, setFacts] = (0, import_react5.useState)([]);
+  const [reloadCount, setReloadCount] = (0, import_react5.useState)(0);
+  const queryKey = getQueryKey(query);
   (0, import_react5.useEffect)(() => {
+    let cancelled = false;
+    lr.Fact.findAll(query).then((result) => {
+      if (!cancelled) {
+        setFacts(result);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [lr, queryKey, reloadCount]);
+  const reload = (0, import_react5.useCallback)(() => setReloadCount((c) => c + 1), []);
+  return { facts, reload };
+}
+
+// src/useUserInfo.ts
+var import_react6 = require("react");
+function useUserInfo() {
+  const { lr } = useLinkedRecords();
+  const [userInfo, setUserInfo] = (0, import_react6.useState)(null);
+  (0, import_react6.useEffect)(() => {
     lr.getCurrentUserEmail().then((email) => setUserInfo({ email })).catch(() => setUserInfo(null));
   }, [lr]);
   return userInfo;
 }
+
+// src/useActorId.ts
+var import_react7 = require("react");
+function useActorId() {
+  const { lr } = useLinkedRecords();
+  const [actorId, setActorId] = (0, import_react7.useState)(lr.actorId);
+  (0, import_react7.useEffect)(() => {
+    let cancelled = false;
+    lr.ensureUserIdIsKnown().then((id) => {
+      if (!cancelled) {
+        setActorId(id);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [lr]);
+  return actorId;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   LinkedRecordsContext,
   LinkedRecordsProvider,
+  useActorId,
+  useFacts,
   useKeyValueAttributes,
   useKeyValueRecords,
+  useKeyValueRecordsWithStatus,
   useLinkedRecords,
   useUserInfo
 });

package/dist/index.mjs

@@ -3,16 +3,30 @@ import { createContext } from "react";
 var LinkedRecordsContext = createContext(void 0);
 
 // src/LinkedRecordsProvider.tsx
-import "react";
+import { useState } from "react";
 import LinkedRecords from "@linkedrecords/browser";
 import { jsx } from "react/jsx-runtime";
-function LinkedRecordsProvider({ children, serverUrl }) {
-  const lr = LinkedRecords.getPublicClient(serverUrl);
+function createClient(serverUrl, config) {
+  const lr = new LinkedRecords(
+    new URL(serverUrl),
+    config.oidcConfig,
+    config.autoHandleRedirect,
+    config.deferUserInfoFetching
+  );
+  if (config.loginHandler) lr.setLoginHandler(config.loginHandler);
+  if (config.connectionLostHandler) lr.setConnectionLostHandler(config.connectionLostHandler);
+  if (config.unknownServerErrorHandler) lr.setUnknownServerErrorHandler(config.unknownServerErrorHandler);
+  if (config.quotaViolationErrorHandler) lr.setQuotaViolationErrorHandler(config.quotaViolationErrorHandler);
+  if (config.authorizationErrorHandler) lr.setAuthorizationErrorHandler(config.authorizationErrorHandler);
+  return lr;
+}
+function LinkedRecordsProvider({ children, serverUrl, config }) {
+  const [lr] = useState(() => config ? createClient(serverUrl, config) : LinkedRecords.getPublicClient(serverUrl));
   return /* @__PURE__ */ jsx(LinkedRecordsContext.Provider, { value: { lr }, children });
 }
 
 // src/useRecords.ts
-import { useEffect, useState } from "react";
+import { useEffect, useState as useState2 } from "react";
 
 // src/useLinkedRecords.ts
 import { useContext } from "react";
@@ -24,14 +38,27 @@ function useLinkedRecords() {
   return context;
 }
 
+// src/queryKey.ts
+function getQueryKey(query) {
+  return JSON.stringify(query, (_, v) => typeof v === "function" ? `fn:${v.name}` : v);
+}
+
 // src/useRecords.ts
 import { KeyValueRecord } from "@linkedrecords/browser";
-function useKeyValueRecords(query) {
+function useKeyValueRecordsWithStatus(query) {
   const { lr } = useLinkedRecords();
-  const [records, setRecords] = useState([]);
+  const [records, setRecords] = useState2([]);
+  const [isLoading, setIsLoading] = useState2(true);
+  const queryKey = getQueryKey(query);
   useEffect(() => {
+    setIsLoading(true);
+    let cancelled = false;
+    const subscribedRecordIds = /* @__PURE__ */ new Set();
     const unsubscribeFnPromise = new Promise((resolve) => {
       const checkActorId = () => {
+        if (cancelled) {
+          return;
+        }
         if (lr.actorId !== void 0) {
           resolve();
         } else {
@@ -48,14 +75,29 @@ function useKeyValueRecords(query) {
       }, async ({ records: records2 }) => {
         const values = await Promise.all(records2.map(async (r) => ({
           _id: r.id,
+          _createdAt: r.createdAt,
           ...await r.getValue()
         })));
+        if (cancelled) {
+          return;
+        }
         setRecords(values);
+        setIsLoading(false);
         records2.forEach((r) => {
+          if (subscribedRecordIds.has(r.id)) {
+            return;
+          }
+          subscribedRecordIds.add(r.id);
           r.subscribe(async () => {
+            if (cancelled) {
+              return;
+            }
             const newValue = await r.getValue();
+            if (cancelled) {
+              return;
+            }
             setRecords((prev) => prev.map(
-              (v) => v._id === r.id ? { _id: r.id, ...newValue } : v
+              (v) => v._id === r.id ? { _id: r.id, _createdAt: r.createdAt, ...newValue } : v
             ));
           });
         });
@@ -65,28 +107,76 @@ function useKeyValueRecords(query) {
       };
     });
     return () => {
+      cancelled = true;
       unsubscribeFnPromise.then((fn) => fn());
     };
-  }, [lr.Record, setRecords]);
-  return records;
+  }, [lr, queryKey]);
+  return { records, isLoading };
+}
+function useKeyValueRecords(query) {
+  return useKeyValueRecordsWithStatus(query).records;
 }
 var useKeyValueAttributes = useKeyValueRecords;
 
+// src/useFacts.ts
+import { useCallback, useEffect as useEffect2, useState as useState3 } from "react";
+function useFacts(query) {
+  const { lr } = useLinkedRecords();
+  const [facts, setFacts] = useState3([]);
+  const [reloadCount, setReloadCount] = useState3(0);
+  const queryKey = getQueryKey(query);
+  useEffect2(() => {
+    let cancelled = false;
+    lr.Fact.findAll(query).then((result) => {
+      if (!cancelled) {
+        setFacts(result);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [lr, queryKey, reloadCount]);
+  const reload = useCallback(() => setReloadCount((c) => c + 1), []);
+  return { facts, reload };
+}
+
 // src/useUserInfo.ts
-import { useEffect as useEffect2, useState as useState2 } from "react";
+import { useEffect as useEffect3, useState as useState4 } from "react";
 function useUserInfo() {
   const { lr } = useLinkedRecords();
-  const [userInfo, setUserInfo] = useState2(null);
-  useEffect2(() => {
+  const [userInfo, setUserInfo] = useState4(null);
+  useEffect3(() => {
     lr.getCurrentUserEmail().then((email) => setUserInfo({ email })).catch(() => setUserInfo(null));
   }, [lr]);
   return userInfo;
 }
+
+// src/useActorId.ts
+import { useEffect as useEffect4, useState as useState5 } from "react";
+function useActorId() {
+  const { lr } = useLinkedRecords();
+  const [actorId, setActorId] = useState5(lr.actorId);
+  useEffect4(() => {
+    let cancelled = false;
+    lr.ensureUserIdIsKnown().then((id) => {
+      if (!cancelled) {
+        setActorId(id);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [lr]);
+  return actorId;
+}
 export {
   LinkedRecordsContext,
   LinkedRecordsProvider,
+  useActorId,
+  useFacts,
   useKeyValueAttributes,
   useKeyValueRecords,
+  useKeyValueRecordsWithStatus,
   useLinkedRecords,
   useUserInfo
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkedrecords/react",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",

package/src/LinkedRecordsProvider.tsx

@@ -1,14 +1,52 @@
-import { type ReactNode } from 'react';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { type ReactNode, useState } from 'react';
 import LinkedRecords from '@linkedrecords/browser';
 import { LinkedRecordsContext } from './linkedRecordsContext';
 
+type OIDCConfig = NonNullable<ConstructorParameters<typeof LinkedRecords>[1]>;
+
+export interface LinkedRecordsConfig {
+  // Omit to use cookie based auth, where the LinkedRecords server handles the login.
+  oidcConfig?: OIDCConfig;
+  autoHandleRedirect?: boolean;
+  deferUserInfoFetching?: boolean;
+  loginHandler?: () => void;
+  connectionLostHandler?: (err?: any) => void;
+  unknownServerErrorHandler?: (response: any) => void;
+  quotaViolationErrorHandler?: (response: any) => void;
+  authorizationErrorHandler?: (response: any) => void;
+}
+
 interface LinkedRecordsProviderProps {
   children: ReactNode;
   serverUrl: string;
+  // Read once on mount. Without it, the shared public client for serverUrl is used.
+  config?: LinkedRecordsConfig;
+}
+
+function createClient(serverUrl: string, config: LinkedRecordsConfig): LinkedRecords {
+  const lr = new LinkedRecords(
+    new URL(serverUrl),
+    config.oidcConfig,
+    config.autoHandleRedirect,
+    config.deferUserInfoFetching,
+  );
+
+  // Handlers are installed before any child renders, so the first
+  // requests made by child components already go through them.
+  if (config.loginHandler) lr.setLoginHandler(config.loginHandler);
+  if (config.connectionLostHandler) lr.setConnectionLostHandler(config.connectionLostHandler);
+  if (config.unknownServerErrorHandler) lr.setUnknownServerErrorHandler(config.unknownServerErrorHandler);
+  if (config.quotaViolationErrorHandler) lr.setQuotaViolationErrorHandler(config.quotaViolationErrorHandler);
+  if (config.authorizationErrorHandler) lr.setAuthorizationErrorHandler(config.authorizationErrorHandler);
+
+  return lr;
 }
 
-export function LinkedRecordsProvider({ children, serverUrl }: LinkedRecordsProviderProps) {
-  const lr = LinkedRecords.getPublicClient(serverUrl);
+export function LinkedRecordsProvider({ children, serverUrl, config }: LinkedRecordsProviderProps) {
+  const [lr] = useState(() => (config
+    ? createClient(serverUrl, config)
+    : LinkedRecords.getPublicClient(serverUrl)));
 
   return (
     <LinkedRecordsContext.Provider value={{ lr }}>

package/src/index.tsx

@@ -1,5 +1,7 @@
 export * from './linkedRecordsContext';
 export * from './LinkedRecordsProvider';
 export * from './useRecords';
+export * from './useFacts';
 export * from './useLinkedRecords';
 export * from './useUserInfo';
+export * from './useActorId';

package/src/queryKey.ts

@@ -0,0 +1,6 @@
+// Callers usually pass a new query on every render, so effects depend on a
+// serialized key instead of the query identity. Functions (e.g. record
+// classes) would serialize to null, so they are keyed by name.
+export function getQueryKey(query: unknown): string {
+  return JSON.stringify(query, (_, v) => (typeof v === 'function' ? `fn:${v.name}` : v));
+}

package/src/useActorId.ts

@@ -0,0 +1,24 @@
+import { useEffect, useState } from "react";
+import { useLinkedRecords } from "./useLinkedRecords";
+
+// The id of the logged in user, undefined until it is known.
+export function useActorId(): string | undefined {
+  const { lr } = useLinkedRecords();
+  const [ actorId, setActorId ] = useState<string | undefined>(lr.actorId);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    lr.ensureUserIdIsKnown().then((id) => {
+      if (!cancelled) {
+        setActorId(id);
+      }
+    });
+
+    return () => {
+      cancelled = true;
+    }
+  }, [ lr ]);
+
+  return actorId;
+}

package/src/useFacts.ts

@@ -0,0 +1,39 @@
+import { useCallback, useEffect, useState } from "react";
+import type LinkedRecords from '@linkedrecords/browser';
+import { useLinkedRecords } from "./useLinkedRecords";
+import { getQueryKey } from "./queryKey";
+
+type FactQuery = Parameters<LinkedRecords['Fact']['findAll']>[0];
+type Fact = Awaited<ReturnType<LinkedRecords['Fact']['findAll']>>[number];
+
+// The SDK can not subscribe to facts, so the facts are fetched whenever the
+// query changes. Call reload after writing facts which affect the result.
+export function useFacts(query: FactQuery): { facts: Fact[], reload: () => void } {
+  const { lr } = useLinkedRecords();
+  const [ facts, setFacts ] = useState<Fact[]>([]);
+  const [ reloadCount, setReloadCount ] = useState(0);
+  const queryKey = getQueryKey(query);
+
+  useEffect(() => {
+    // Ignore responses which arrive after the query changed or the
+    // component unmounted.
+    let cancelled = false;
+
+    lr.Fact.findAll(query).then((result) => {
+      if (!cancelled) {
+        setFacts(result);
+      }
+    });
+
+    return () => {
+      cancelled = true;
+    }
+    // query is represented by queryKey; depending on the object itself would
+    // refetch on every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ lr, queryKey, reloadCount ]);
+
+  const reload = useCallback(() => setReloadCount((c) => c + 1), []);
+
+  return { facts, reload };
+}

package/src/useRecords.ts

@@ -1,19 +1,40 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { useEffect, useState } from "react";
 import { useLinkedRecords } from "./useLinkedRecords";
+import { getQueryKey } from "./queryKey";
 import { KeyValueRecord } from '@linkedrecords/browser';
 
 interface KVValue {
-  [key: string]: KVValue | string | boolean | number | undefined;
+  [key: string]: KVValue | string | boolean | number | Date | undefined;
 }
 
-export function useKeyValueRecords(query: any[]): KVValue[]  {
+export interface KVRecord extends KVValue {
+  _id?: string;
+  _createdAt?: Date;
+}
+
+export function useKeyValueRecordsWithStatus(query: any[]): { records: KVRecord[], isLoading: boolean } {
   const { lr } = useLinkedRecords();
-  const [ records, setRecords ] = useState<KVValue[]>([]);
+  const [ records, setRecords ] = useState<KVRecord[]>([]);
+  const [ isLoading, setIsLoading ] = useState(true);
+  const queryKey = getQueryKey(query);
 
   useEffect(() => {
+    setIsLoading(true);
+
+    // The SDK has no way to remove a record observer, so observers registered
+    // by this effect run check this flag and become no-ops after cleanup.
+    let cancelled = false;
+    // Records this effect run already observes, so repeated query results
+    // do not stack up observers on the same record.
+    const subscribedRecordIds = new Set<string | undefined>();
+
     const unsubscribeFnPromise = new Promise<void>((resolve) => {
       const checkActorId = () => {
+        if (cancelled) {
+          return;
+        }
+
         if (lr.actorId !== undefined) {
           resolve();
         } else {
@@ -30,19 +51,39 @@ export function useKeyValueRecords(query: any[]): KVValue[]  {
       }, async ({ records }) => {
         const values = await Promise.all(records.map(async (r) => ({
           _id: r.id,
+          _createdAt: r.createdAt,
           ...(await r.getValue()),
         })));
 
+        if (cancelled) {
+          return;
+        }
+
         setRecords(values);
+        setIsLoading(false);
 
         records.forEach((r) => {
+          if (subscribedRecordIds.has(r.id)) {
+            return;
+          }
+
+          subscribedRecordIds.add(r.id);
+
           r.subscribe(async () => {
+            if (cancelled) {
+              return;
+            }
+
             const newValue = await r.getValue();
 
+            if (cancelled) {
+              return;
+            }
+
             // Use functional update to avoid stale closure
             setRecords(prev => prev.map(v =>
               v._id === r.id
-                ? { _id: r.id, ...newValue }
+                ? { _id: r.id, _createdAt: r.createdAt, ...newValue }
                 : v
             ));
           });
@@ -55,11 +96,19 @@ export function useKeyValueRecords(query: any[]): KVValue[]  {
     });
 
     return () => {
+      cancelled = true;
       unsubscribeFnPromise.then(fn => fn());
     }
-  }, [ lr.Record, setRecords ]);
+    // query is represented by queryKey; depending on the array itself would
+    // resubscribe on every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ lr, queryKey ]);
+
+  return { records, isLoading };
+}
 
-  return records;
+export function useKeyValueRecords(query: any[]): KVRecord[] {
+  return useKeyValueRecordsWithStatus(query).records;
 }
 
 /** @deprecated Use useKeyValueRecords instead. */