@linkedrecords/react 0.5.0 → 0.7.0

package/dist/index.d.mts

@@ -26,13 +26,33 @@ interface LinkedRecordsProviderProps {
 }
 declare function LinkedRecordsProvider({ children, serverUrl, config }: LinkedRecordsProviderProps): react_jsx_runtime.JSX.Element;
 
-interface KVValue {
-    [key: string]: KVValue | string | boolean | number | undefined;
-}
-declare function useKeyValueRecords(query: any[]): KVValue[];
+type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+type KVValue = {
+    [key: string]: JSONValue | undefined;
+};
+type KVRecord<T extends object = KVValue> = T & {
+    _id?: string;
+    _createdAt?: Date;
+};
+type CompoundRecordQuery = Parameters<LinkedRecords['Record']['subscribeToQuery']>[0];
+type RecordQueryClause = Exclude<CompoundRecordQuery[string], string>[number];
+declare function useKeyValueRecordsWithStatus<T extends object = KVValue>(query: RecordQueryClause[]): {
+    records: KVRecord<T>[];
+    isLoading: boolean;
+};
+declare function useKeyValueRecords<T extends object = KVValue>(query: RecordQueryClause[]): KVRecord<T>[];
 /** @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 = {
@@ -40,4 +60,6 @@ type UserInfo = {
 };
 declare function useUserInfo(): UserInfo | null;
 
-export { type LinkedRecordsConfig, LinkedRecordsContext, type LinkedRecordsContextType, LinkedRecordsProvider, useKeyValueAttributes, useKeyValueRecords, useLinkedRecords, useUserInfo };
+declare function useActorId(): string | undefined;
+
+export { type KVRecord, type LinkedRecordsConfig, LinkedRecordsContext, type LinkedRecordsContextType, LinkedRecordsProvider, type RecordQueryClause, useActorId, useFacts, useKeyValueAttributes, useKeyValueRecords, useKeyValueRecordsWithStatus, useLinkedRecords, useUserInfo };

package/dist/index.d.ts

@@ -26,13 +26,33 @@ interface LinkedRecordsProviderProps {
 }
 declare function LinkedRecordsProvider({ children, serverUrl, config }: LinkedRecordsProviderProps): react_jsx_runtime.JSX.Element;
 
-interface KVValue {
-    [key: string]: KVValue | string | boolean | number | undefined;
-}
-declare function useKeyValueRecords(query: any[]): KVValue[];
+type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+type KVValue = {
+    [key: string]: JSONValue | undefined;
+};
+type KVRecord<T extends object = KVValue> = T & {
+    _id?: string;
+    _createdAt?: Date;
+};
+type CompoundRecordQuery = Parameters<LinkedRecords['Record']['subscribeToQuery']>[0];
+type RecordQueryClause = Exclude<CompoundRecordQuery[string], string>[number];
+declare function useKeyValueRecordsWithStatus<T extends object = KVValue>(query: RecordQueryClause[]): {
+    records: KVRecord<T>[];
+    isLoading: boolean;
+};
+declare function useKeyValueRecords<T extends object = KVValue>(query: RecordQueryClause[]): KVRecord<T>[];
 /** @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 = {
@@ -40,4 +60,6 @@ type UserInfo = {
 };
 declare function useUserInfo(): UserInfo | null;
 
-export { type LinkedRecordsConfig, LinkedRecordsContext, type LinkedRecordsContextType, LinkedRecordsProvider, useKeyValueAttributes, useKeyValueRecords, useLinkedRecords, useUserInfo };
+declare function useActorId(): string | undefined;
+
+export { type KVRecord, type LinkedRecordsConfig, LinkedRecordsContext, type LinkedRecordsContextType, LinkedRecordsProvider, type RecordQueryClause, 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
 });
@@ -63,11 +66,13 @@ function createClient(serverUrl, config) {
 }
 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 });
+  const value = (0, import_react2.useMemo)(() => ({ lr }), [lr]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(LinkedRecordsContext.Provider, { value, children });
 }
 
 // src/useRecords.ts
 var import_react4 = require("react");
+var import_browser2 = require("@linkedrecords/browser");
 
 // src/useLinkedRecords.ts
 var import_react3 = require("react");
@@ -79,93 +84,136 @@ function useLinkedRecords() {
   return context;
 }
 
-// src/useRecords.ts
-var import_browser2 = require("@linkedrecords/browser");
+// src/queryKey.ts
 function getQueryKey(query) {
   return JSON.stringify(query, (_, v) => typeof v === "function" ? `fn:${v.name}` : v);
 }
-function useKeyValueRecords(query) {
+
+// src/useRecords.ts
+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 {
-          setTimeout(checkActorId, 50);
+    const recordUnsubscribes = /* @__PURE__ */ new Map();
+    const toKVRecord = async (r) => ({
+      _id: r.id,
+      _createdAt: r.createdAt,
+      ...await r.getValue()
+    });
+    const queryUnsubscribe = lr.Record.subscribeToQuery({
+      records: [
+        ["$it", "$hasDataType", import_browser2.KeyValueRecord],
+        ...query
+      ]
+    }, async ({ records: records2 }) => {
+      const kvRecords = records2;
+      const values = await Promise.all(kvRecords.map(toKVRecord));
+      if (cancelled) {
+        return;
+      }
+      setRecords(values);
+      setIsLoading(false);
+      const ids = new Set(kvRecords.map((r) => r.id));
+      recordUnsubscribes.forEach((unsubscribe, id) => {
+        if (!ids.has(id)) {
+          recordUnsubscribes.delete(id);
+          unsubscribe.then((fn) => fn());
         }
-      };
-      checkActorId();
-    }).then(() => {
-      const queryUnsubscribe = lr.Record.subscribeToQuery({
-        records: [
-          ["$it", "$hasDataType", import_browser2.KeyValueRecord],
-          ...query
-        ]
-      }, async ({ records: records2 }) => {
-        const values = await Promise.all(records2.map(async (r) => ({
-          _id: r.id,
-          ...await r.getValue()
-        })));
-        if (cancelled) {
+      });
+      kvRecords.forEach((r) => {
+        if (recordUnsubscribes.has(r.id)) {
           return;
         }
-        setRecords(values);
-        records2.forEach((r) => {
-          if (subscribedRecordIds.has(r.id)) {
+        recordUnsubscribes.set(r.id, r.subscribe(async () => {
+          const newValue = await toKVRecord(r);
+          if (cancelled) {
             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
-            ));
-          });
-        });
+          setRecords((prev) => prev.map((v) => v._id === r.id ? newValue : v));
+        }));
       });
-      return () => {
-        queryUnsubscribe.then((unsubscribe) => unsubscribe());
-      };
+    });
+    queryUnsubscribe.catch((err) => {
+      console.error("useKeyValueRecords: could not subscribe to query", err);
     });
     return () => {
       cancelled = true;
-      unsubscribeFnPromise.then((fn) => fn());
+      queryUnsubscribe.then((unsubscribe) => unsubscribe(), () => {
+      });
+      recordUnsubscribes.forEach((unsubscribe) => unsubscribe.then((fn) => fn()));
     };
   }, [lr, queryKey]);
-  return records;
+  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,7 +3,7 @@ import { createContext } from "react";
 var LinkedRecordsContext = createContext(void 0);
 
 // src/LinkedRecordsProvider.tsx
-import { useState } from "react";
+import { useMemo, useState } from "react";
 import LinkedRecords from "@linkedrecords/browser";
 import { jsx } from "react/jsx-runtime";
 function createClient(serverUrl, config) {
@@ -22,11 +22,13 @@ function createClient(serverUrl, config) {
 }
 function LinkedRecordsProvider({ children, serverUrl, config }) {
   const [lr] = useState(() => config ? createClient(serverUrl, config) : LinkedRecords.getPublicClient(serverUrl));
-  return /* @__PURE__ */ jsx(LinkedRecordsContext.Provider, { value: { lr }, children });
+  const value = useMemo(() => ({ lr }), [lr]);
+  return /* @__PURE__ */ jsx(LinkedRecordsContext.Provider, { value, children });
 }
 
 // src/useRecords.ts
 import { useEffect, useState as useState2 } from "react";
+import { KeyValueRecord } from "@linkedrecords/browser";
 
 // src/useLinkedRecords.ts
 import { useContext } from "react";
@@ -38,92 +40,135 @@ function useLinkedRecords() {
   return context;
 }
 
-// src/useRecords.ts
-import { KeyValueRecord } from "@linkedrecords/browser";
+// src/queryKey.ts
 function getQueryKey(query) {
   return JSON.stringify(query, (_, v) => typeof v === "function" ? `fn:${v.name}` : v);
 }
-function useKeyValueRecords(query) {
+
+// src/useRecords.ts
+function useKeyValueRecordsWithStatus(query) {
   const { lr } = useLinkedRecords();
   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 {
-          setTimeout(checkActorId, 50);
+    const recordUnsubscribes = /* @__PURE__ */ new Map();
+    const toKVRecord = async (r) => ({
+      _id: r.id,
+      _createdAt: r.createdAt,
+      ...await r.getValue()
+    });
+    const queryUnsubscribe = lr.Record.subscribeToQuery({
+      records: [
+        ["$it", "$hasDataType", KeyValueRecord],
+        ...query
+      ]
+    }, async ({ records: records2 }) => {
+      const kvRecords = records2;
+      const values = await Promise.all(kvRecords.map(toKVRecord));
+      if (cancelled) {
+        return;
+      }
+      setRecords(values);
+      setIsLoading(false);
+      const ids = new Set(kvRecords.map((r) => r.id));
+      recordUnsubscribes.forEach((unsubscribe, id) => {
+        if (!ids.has(id)) {
+          recordUnsubscribes.delete(id);
+          unsubscribe.then((fn) => fn());
         }
-      };
-      checkActorId();
-    }).then(() => {
-      const queryUnsubscribe = lr.Record.subscribeToQuery({
-        records: [
-          ["$it", "$hasDataType", KeyValueRecord],
-          ...query
-        ]
-      }, async ({ records: records2 }) => {
-        const values = await Promise.all(records2.map(async (r) => ({
-          _id: r.id,
-          ...await r.getValue()
-        })));
-        if (cancelled) {
+      });
+      kvRecords.forEach((r) => {
+        if (recordUnsubscribes.has(r.id)) {
           return;
         }
-        setRecords(values);
-        records2.forEach((r) => {
-          if (subscribedRecordIds.has(r.id)) {
+        recordUnsubscribes.set(r.id, r.subscribe(async () => {
+          const newValue = await toKVRecord(r);
+          if (cancelled) {
             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
-            ));
-          });
-        });
+          setRecords((prev) => prev.map((v) => v._id === r.id ? newValue : v));
+        }));
       });
-      return () => {
-        queryUnsubscribe.then((unsubscribe) => unsubscribe());
-      };
+    });
+    queryUnsubscribe.catch((err) => {
+      console.error("useKeyValueRecords: could not subscribe to query", err);
     });
     return () => {
       cancelled = true;
-      unsubscribeFnPromise.then((fn) => fn());
+      queryUnsubscribe.then((unsubscribe) => unsubscribe(), () => {
+      });
+      recordUnsubscribes.forEach((unsubscribe) => unsubscribe.then((fn) => fn()));
     };
   }, [lr, queryKey]);
-  return records;
+  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 useState3 } from "react";
+import { useEffect as useEffect3, useState as useState4 } from "react";
 function useUserInfo() {
   const { lr } = useLinkedRecords();
-  const [userInfo, setUserInfo] = useState3(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.5.0",
+  "version": "0.7.0",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -25,11 +25,11 @@
   "license": "MIT",
   "description": "",
   "peerDependencies": {
-    "@linkedrecords/browser": "^0.3.0",
+    "@linkedrecords/browser": "^0.4.0",
     "react": ">=18"
   },
   "devDependencies": {
-    "@linkedrecords/browser": "^0.3.0",
+    "@linkedrecords/browser": "^0.4.0",
     "@types/react": "^19.1.12",
     "react": "^19.1.1",
     "tsup": "^8.5.0",

package/src/LinkedRecordsProvider.tsx

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { type ReactNode, useState } from 'react';
+import { type ReactNode, useMemo, useState } from 'react';
 import LinkedRecords from '@linkedrecords/browser';
 import { LinkedRecordsContext } from './linkedRecordsContext';
 
@@ -47,9 +47,11 @@ export function LinkedRecordsProvider({ children, serverUrl, config }: LinkedRec
   const [lr] = useState(() => (config
     ? createClient(serverUrl, config)
     : LinkedRecords.getPublicClient(serverUrl)));
+  // A new context value would re-render every consumer on each render.
+  const value = useMemo(() => ({ lr }), [lr]);
 
   return (
-    <LinkedRecordsContext.Provider value={{ lr }}>
+    <LinkedRecordsContext.Provider value={value}>
       {children}
     </LinkedRecordsContext.Provider>
   );

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,106 +1,107 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import { useEffect, useState } from "react";
-import { useLinkedRecords } from "./useLinkedRecords";
+import type LinkedRecords from '@linkedrecords/browser';
 import { KeyValueRecord } from '@linkedrecords/browser';
+import { useLinkedRecords } from "./useLinkedRecords";
+import { getQueryKey } from "./queryKey";
 
-interface KVValue {
-  [key: string]: KVValue | string | boolean | number | undefined;
-}
+type JSONValue = string | number | boolean | null | JSONValue[] | { [key: string]: JSONValue };
 
-// Callers usually pass a new query array on every render, so the effect
-// depends on a serialized key instead of the array identity. Functions
-// (e.g. record classes) would serialize to null, so they are keyed by name.
-function getQueryKey(query: any[]): string {
-  return JSON.stringify(query, (_, v) => (typeof v === 'function' ? `fn:${v.name}` : v));
-}
+type KVValue = { [key: string]: JSONValue | undefined };
+
+export type KVRecord<T extends object = KVValue> = T & {
+  _id?: string;
+  _createdAt?: Date;
+};
 
-export function useKeyValueRecords(query: any[]): KVValue[]  {
+type CompoundRecordQuery = Parameters<LinkedRecords['Record']['subscribeToQuery']>[0];
+
+// One [subject, predicate, object] clause of a record query, e.g. ['$it', 'isA', 'Todo'].
+export type RecordQueryClause = Exclude<CompoundRecordQuery[string], string>[number];
+
+export function useKeyValueRecordsWithStatus<T extends object = KVValue>(query: RecordQueryClause[]): { records: KVRecord<T>[], isLoading: boolean } {
   const { lr } = useLinkedRecords();
-  const [ records, setRecords ] = useState<KVValue[]>([]);
+  const [ records, setRecords ] = useState<KVRecord<T>[]>([]);
+  const [ isLoading, setIsLoading ] = useState(true);
   const queryKey = getQueryKey(query);
 
   useEffect(() => {
-    // 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>();
+    setIsLoading(true);
 
-    const unsubscribeFnPromise = new Promise<void>((resolve) => {
-      const checkActorId = () => {
-        if (cancelled) {
-          return;
+    // Values are read asynchronously; results which arrive after the query
+    // changed or the component unmounted are dropped.
+    let cancelled = false;
+    // Record observers by record id, so each record in the result is
+    // observed once and records which leave the result are unobserved.
+    const recordUnsubscribes = new Map<string | undefined, Promise<() => void>>();
+
+    // T is the value shape declared by the caller; the hook can not check it.
+    const toKVRecord = async (r: KeyValueRecord) => ({
+      _id: r.id,
+      _createdAt: r.createdAt,
+      ...(await r.getValue()),
+    }) as KVRecord<T>;
+
+    const queryUnsubscribe = lr.Record.subscribeToQuery({
+      records: [
+        ['$it', '$hasDataType', KeyValueRecord],
+        ...query
+      ],
+    }, async ({ records }) => {
+      const kvRecords = records as KeyValueRecord[];
+      const values = await Promise.all(kvRecords.map(toKVRecord));
+
+      if (cancelled) {
+        return;
+      }
+
+      setRecords(values);
+      setIsLoading(false);
+
+      const ids = new Set(kvRecords.map((r) => r.id));
+
+      recordUnsubscribes.forEach((unsubscribe, id) => {
+        if (!ids.has(id)) {
+          recordUnsubscribes.delete(id);
+          unsubscribe.then((fn) => fn());
         }
+      });
 
-        if (lr.actorId !== undefined) {
-          resolve();
-        } else {
-          setTimeout(checkActorId, 50);
-        }
-      };
-      checkActorId();
-    }).then(() => {
-      const queryUnsubscribe = lr.Record.subscribeToQuery({
-        records: [
-          ['$it', '$hasDataType', KeyValueRecord],
-          ...query
-        ],
-      }, async ({ records }) => {
-        const values = await Promise.all(records.map(async (r) => ({
-          _id: r.id,
-          ...(await r.getValue()),
-        })));
-
-        if (cancelled) {
+      kvRecords.forEach((r) => {
+        if (recordUnsubscribes.has(r.id)) {
           return;
         }
 
-        setRecords(values);
+        recordUnsubscribes.set(r.id, r.subscribe(async () => {
+          const newValue = await toKVRecord(r);
 
-        records.forEach((r) => {
-          if (subscribedRecordIds.has(r.id)) {
+          if (cancelled) {
             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 }
-                : v
-            ));
-          });
-        });
+          setRecords(prev => prev.map(v => (v._id === r.id ? newValue : v)));
+        }));
       });
+    });
 
-      return () => {
-        queryUnsubscribe.then(unsubscribe => unsubscribe());
-      };
+    queryUnsubscribe.catch((err) => {
+      console.error('useKeyValueRecords: could not subscribe to query', err);
     });
 
     return () => {
       cancelled = true;
-      unsubscribeFnPromise.then(fn => fn());
+      queryUnsubscribe.then((unsubscribe) => unsubscribe(), () => {});
+      recordUnsubscribes.forEach((unsubscribe) => unsubscribe.then((fn) => fn()));
     }
     // 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;
+  return { records, isLoading };
+}
+
+export function useKeyValueRecords<T extends object = KVValue>(query: RecordQueryClause[]): KVRecord<T>[] {
+  return useKeyValueRecordsWithStatus<T>(query).records;
 }
 
 /** @deprecated Use useKeyValueRecords instead. */