@aglyn/tenant-feature-instance 1.0.0-beta.143

package/src/lib/hooks/helpers/use-doc.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type DocumentReference } from 'firebase/firestore';
+import type { ObservableStatus, FirestoreDocOptions } from '../firebase/firebase-services';
+import { type UseModifyDocCallback } from './use-modify-doc-callback';
+/**
+ * Raw `onSnapshot` listener with its own retry/backoff instead of
+ * reactfire's `useFirestoreDocData` — that hook caches the query's RxJS
+ * Observable, and once it errors the Observable is *terminated forever*:
+ * remounting the component never reopens the Firestore subscription, so a
+ * single transient `permission-denied` (e.g. right after sign-in, before
+ * Firestore's own credential provider has attached the user's ID token)
+ * permanently breaks every caller of `useHost`/`useLayout`/`useScreen`/
+ * `useScreenVersion`/`useLayoutVersion` for the rest of the session
+ * (AGL-216/217/223). A fresh `onSnapshot` call each retry opens a genuinely
+ * new listener, so it recovers once the token has propagated.
+ */
+export declare function useDocData<T>(ref: DocumentReference<T>, options?: FirestoreDocOptions<T>): ObservableStatus<T>;
+export type UseDocData<T> = typeof useDocData<T>;
+export declare function useDoc<T>(ref: DocumentReference<T>, options?: FirestoreDocOptions<T>): {
+    doc: ReturnType<UseDocData<T>>;
+    setDoc: ReturnType<UseModifyDocCallback<T>>;
+};
+export default useDoc;

package/src/lib/hooks/helpers/use-doc.js

@@ -0,0 +1,213 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { onSnapshot } from "firebase/firestore";
+import { useEffect, useRef, useState } from "react";
+import { DENIAL_STREAK_TO_REPORT, noteFirestoreServerRead, scheduleRefusedReopen, subscribeFirestoreSessionHeal } from "../firestore-denial-reporter.js";
+import { CONFIRMABLE_LISTEN_OPTIONS } from "./listen-options.js";
+import useModifyDocCallback from "./use-modify-doc-callback.js";
+const RETRY_DELAY_MS = 400;
+const MAX_RETRIES = 5;
+// The refused cadence is shared policy — see `scheduleRefusedReopen` in
+// `firestore-denial-reporter.ts` (AGL-1066, AGL-1440, AGL-2944, AGL-2945).
+/**
+ * Raw `onSnapshot` listener with its own retry/backoff instead of
+ * reactfire's `useFirestoreDocData` — that hook caches the query's RxJS
+ * Observable, and once it errors the Observable is *terminated forever*:
+ * remounting the component never reopens the Firestore subscription, so a
+ * single transient `permission-denied` (e.g. right after sign-in, before
+ * Firestore's own credential provider has attached the user's ID token)
+ * permanently breaks every caller of `useHost`/`useLayout`/`useScreen`/
+ * `useScreenVersion`/`useLayoutVersion` for the rest of the session
+ * (AGL-216/217/223). A fresh `onSnapshot` call each retry opens a genuinely
+ * new listener, so it recovers once the token has propagated.
+ */ export function useDocData(ref, options) {
+    const idField = options == null ? void 0 : options.idField;
+    const initialData = options == null ? void 0 : options.initialData;
+    const [status, setStatus] = useState(initialData !== undefined ? 'success' : 'loading');
+    const [data, setData] = useState(initialData);
+    const [error, setError] = useState(undefined);
+    const [hasEmitted, setHasEmitted] = useState(initialData !== undefined);
+    const [hasPendingWrites, setHasPendingWrites] = useState(false);
+    // Un-confirmed until a snapshot says otherwise (AGL-1066).
+    const [fromCache, setFromCache] = useState(true);
+    const [serverDenied, setServerDenied] = useState(false);
+    const resolveFirstValueRef = useRef(undefined);
+    const firstValuePromiseRef = useRef(undefined);
+    if (!firstValuePromiseRef.current) {
+        firstValuePromiseRef.current = new Promise((resolve)=>{
+            resolveFirstValueRef.current = resolve;
+        });
+    }
+    useEffect(()=>{
+        setStatus('loading');
+        setError(undefined);
+        let cancelled = false;
+        let unsubscribe = null;
+        let timer = null;
+        /** Cancels a pending reopen on the refused cadence (AGL-2944). */ let cancelRefusedReopen = null;
+        let attempt = 0;
+        /**
+     * Refusals since the last SERVER snapshot (AGL-1066).
+     *
+     * Still distinct from `attempt` after the flip: `attempt` is a BUDGET
+     * that the heal broadcast may refund, whereas this is EVIDENCE about the
+     * server that only a server snapshot may clear. Counted here to publish
+     * `serverDenied` and to decide the slow cadence — the `session-health`
+     * reporting the other two listener hooks do is a separate decision, and
+     * this hook's callers (the besigner document family) are exactly the ones
+     * a false verdict would hurt most.
+     */ let deniedStreak = 0;
+        /** Epoch ms of the current streak's first refusal (AGL-1440). */ let deniedStreakStartedAt = 0;
+        /**
+     * The retry budget is spent and the server's last word was a refusal —
+     * what keeps `status: 'error'` from being undone by the cached emission
+     * that precedes every reopened refusal (AGL-1066). See the longer note
+     * on the same variable in `use-firestore-collection`.
+     */ let terminal = false;
+        const subscribe = ()=>{
+            unsubscribe = onSnapshot(ref, // Without this the cache→server confirmation is never delivered and
+            // `fromCache` latches true for the life of the listener, refusing
+            // every guarded save on the page (AGL-2486). See `listen-options.ts`.
+            CONFIRMABLE_LISTEN_OPTIONS, (snapshot)=>{
+                if (cancelled) return;
+                // Only the SERVER answering refunds the retry budget, and only a
+                // server snapshot ends a refusal (AGL-1066).
+                if (!snapshot.metadata.fromCache) {
+                    attempt = 0;
+                    terminal = false;
+                    deniedStreak = 0;
+                    setServerDenied(false);
+                    // Evidence only, deliberately not the reporting call: this hook
+                    // stays out of `session-health` (see `deniedStreak` above), but
+                    // its server answers are still proof the session can read, which
+                    // is what `refusedRetryDelayMs` splits the cadence on (AGL-1440).
+                    noteFirestoreServerRead();
+                } else if (deniedStreak === 0) {
+                    // Cached, but nothing has been refused since the server last
+                    // answered — not the AGL-1066 fault, so the budget is refunded
+                    // exactly as it always was. This is what keeps offline inert:
+                    // `unavailable` never enters `deniedStreak`.
+                    attempt = 0;
+                }
+                if (!terminal) {
+                    setStatus('success');
+                    setError(undefined);
+                }
+                // Always true after ANY emission, cached included: this is what
+                // tells a consumer "I have data, the server refused" apart from "I
+                // never had data" — the distinction the besigner editors and the
+                // host setup Theme tab blank on (AGL-1066).
+                setHasEmitted(true);
+                // Kept, not dropped: a snapshot that still carries this client's
+                // own queued write is not evidence of what the store holds
+                // (AGL-1262). Callers that record a "last saved" state need to
+                // know the difference.
+                setHasPendingWrites(snapshot.metadata.hasPendingWrites);
+                setFromCache(snapshot.metadata.fromCache);
+                const value = snapshot.exists() ? _extends({}, snapshot.data(), idField ? {
+                    [idField]: snapshot.id
+                } : {}) : undefined;
+                setData(value);
+                resolveFirstValueRef.current == null ? void 0 : resolveFirstValueRef.current.call(resolveFirstValueRef);
+            }, (err)=>{
+                if (cancelled) return;
+                unsubscribe == null ? void 0 : unsubscribe();
+                // Only a refusal — a lost network produces no error callback at
+                // all, and anything that does surface one carries `unavailable`,
+                // which must never read as a dead session.
+                if ((err == null ? void 0 : err.code) === 'permission-denied') {
+                    deniedStreak += 1;
+                    if (deniedStreak === 1) deniedStreakStartedAt = Date.now();
+                    if (deniedStreak >= DENIAL_STREAK_TO_REPORT) setServerDenied(true);
+                }
+                if (attempt < MAX_RETRIES) {
+                    attempt += 1;
+                    if (deniedStreak > MAX_RETRIES) {
+                        cancelRefusedReopen = scheduleRefusedReopen(subscribe, deniedStreakStartedAt);
+                    } else {
+                        timer = setTimeout(subscribe, RETRY_DELAY_MS);
+                    }
+                } else {
+                    terminal = true;
+                    setStatus('error');
+                    setError(err);
+                    resolveFirstValueRef.current == null ? void 0 : resolveFirstValueRef.current.call(resolveFirstValueRef);
+                    // A refusal streak keeps a slow road back for a recovery nobody
+                    // announced — see the same branch in `use-firestore-collection`.
+                    // The cadence splits on session-vs-ref evidence (AGL-1440), grows
+                    // with the streak's age (AGL-2945) and waits while the tab is
+                    // hidden (AGL-2944).
+                    if (deniedStreak > MAX_RETRIES) {
+                        cancelRefusedReopen = scheduleRefusedReopen(subscribe, deniedStreakStartedAt);
+                    }
+                }
+            });
+        };
+        subscribe();
+        /**
+     * Reopen when the session heals — see the long note on the same
+     * subscription in `use-firestore-collection` (AGL-1066).
+     *
+     * This hook is where it counts most: its deps are `[ref.firestore,
+     * ref.path]`, neither of which moves when a `stale` re-auth signs the
+     * same uid back in, and it is what every besigner editor reads through.
+     * Nothing else was ever going to bring those pages back without a reload.
+     */ const unsubscribeHeal = subscribeFirestoreSessionHeal(()=>{
+            if (cancelled || deniedStreak === 0) return;
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            cancelRefusedReopen == null ? void 0 : cancelRefusedReopen();
+            cancelRefusedReopen = null;
+            unsubscribe == null ? void 0 : unsubscribe();
+            attempt = 0;
+            subscribe();
+        });
+        return ()=>{
+            cancelled = true;
+            unsubscribeHeal();
+            if (timer) clearTimeout(timer);
+            cancelRefusedReopen == null ? void 0 : cancelRefusedReopen();
+            unsubscribe == null ? void 0 : unsubscribe();
+        };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        ref.firestore,
+        ref.path
+    ]);
+    return {
+        status,
+        hasEmitted,
+        isComplete: false,
+        data,
+        error,
+        firstValuePromise: firstValuePromiseRef.current,
+        hasPendingWrites,
+        fromCache,
+        serverDenied
+    };
+}
+export function useDoc(ref, options) {
+    return {
+        doc: useDocData(ref, options),
+        setDoc: useModifyDocCallback(ref)
+    };
+}
+export default useDoc;
+
+//# sourceMappingURL=use-doc.js.map

package/src/lib/hooks/helpers/use-doc.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/helpers/use-doc.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { onSnapshot, type DocumentReference } from 'firebase/firestore'\nimport { useEffect, useRef, useState } from 'react'\nimport type { ObservableStatus, FirestoreDocOptions } from '../firebase/firebase-services'\nimport {\n  DENIAL_STREAK_TO_REPORT,\n  noteFirestoreServerRead,\n  scheduleRefusedReopen,\n  subscribeFirestoreSessionHeal,\n} from '../firestore-denial-reporter'\nimport { CONFIRMABLE_LISTEN_OPTIONS } from './listen-options'\nimport useModifyDocCallback, {\n  type UseModifyDocCallback,\n} from './use-modify-doc-callback'\n\nconst RETRY_DELAY_MS = 400\nconst MAX_RETRIES = 5\n// The refused cadence is shared policy — see `scheduleRefusedReopen` in\n// `firestore-denial-reporter.ts` (AGL-1066, AGL-1440, AGL-2944, AGL-2945).\n\n/**\n * Raw `onSnapshot` listener with its own retry/backoff instead of\n * reactfire's `useFirestoreDocData` — that hook caches the query's RxJS\n * Observable, and once it errors the Observable is *terminated forever*:\n * remounting the component never reopens the Firestore subscription, so a\n * single transient `permission-denied` (e.g. right after sign-in, before\n * Firestore's own credential provider has attached the user's ID token)\n * permanently breaks every caller of `useHost`/`useLayout`/`useScreen`/\n * `useScreenVersion`/`useLayoutVersion` for the rest of the session\n * (AGL-216/217/223). A fresh `onSnapshot` call each retry opens a genuinely\n * new listener, so it recovers once the token has propagated.\n */\nexport function useDocData<T>(\n  ref: DocumentReference<T>,\n  options?: FirestoreDocOptions<T>,\n): ObservableStatus<T> {\n  const idField = options?.idField\n  const initialData = options?.initialData\n  const [status, setStatus] = useState<'loading' | 'error' | 'success'>(\n    initialData !== undefined ? 'success' : 'loading',\n  )\n  const [data, setData] = useState<T>(initialData as T)\n  const [error, setError] = useState<Error | undefined>(undefined)\n  const [hasEmitted, setHasEmitted] = useState(initialData !== undefined)\n  const [hasPendingWrites, setHasPendingWrites] = useState(false)\n  // Un-confirmed until a snapshot says otherwise (AGL-1066).\n  const [fromCache, setFromCache] = useState(true)\n  const [serverDenied, setServerDenied] = useState(false)\n  const resolveFirstValueRef = useRef<(() => void) | undefined>(undefined)\n  const firstValuePromiseRef = useRef<Promise<void> | undefined>(undefined)\n  if (!firstValuePromiseRef.current) {\n    firstValuePromiseRef.current = new Promise((resolve) => {\n      resolveFirstValueRef.current = resolve\n    })\n  }\n\n  useEffect(() => {\n    setStatus('loading')\n    setError(undefined)\n\n    let cancelled = false\n    let unsubscribe: (() => void) | null = null\n    let timer: ReturnType<typeof setTimeout> | null = null\n    /** Cancels a pending reopen on the refused cadence (AGL-2944). */\n    let cancelRefusedReopen: (() => void) | null = null\n    let attempt = 0\n    /**\n     * Refusals since the last SERVER snapshot (AGL-1066).\n     *\n     * Still distinct from `attempt` after the flip: `attempt` is a BUDGET\n     * that the heal broadcast may refund, whereas this is EVIDENCE about the\n     * server that only a server snapshot may clear. Counted here to publish\n     * `serverDenied` and to decide the slow cadence — the `session-health`\n     * reporting the other two listener hooks do is a separate decision, and\n     * this hook's callers (the besigner document family) are exactly the ones\n     * a false verdict would hurt most.\n     */\n    let deniedStreak = 0\n    /** Epoch ms of the current streak's first refusal (AGL-1440). */\n    let deniedStreakStartedAt = 0\n    /**\n     * The retry budget is spent and the server's last word was a refusal —\n     * what keeps `status: 'error'` from being undone by the cached emission\n     * that precedes every reopened refusal (AGL-1066). See the longer note\n     * on the same variable in `use-firestore-collection`.\n     */\n    let terminal = false\n\n    const subscribe = () => {\n      unsubscribe = onSnapshot(\n        ref,\n        // Without this the cache→server confirmation is never delivered and\n        // `fromCache` latches true for the life of the listener, refusing\n        // every guarded save on the page (AGL-2486). See `listen-options.ts`.\n        CONFIRMABLE_LISTEN_OPTIONS,\n        (snapshot) => {\n          if (cancelled) return\n          // Only the SERVER answering refunds the retry budget, and only a\n          // server snapshot ends a refusal (AGL-1066).\n          if (!snapshot.metadata.fromCache) {\n            attempt = 0\n            terminal = false\n            deniedStreak = 0\n            setServerDenied(false)\n            // Evidence only, deliberately not the reporting call: this hook\n            // stays out of `session-health` (see `deniedStreak` above), but\n            // its server answers are still proof the session can read, which\n            // is what `refusedRetryDelayMs` splits the cadence on (AGL-1440).\n            noteFirestoreServerRead()\n          } else if (deniedStreak === 0) {\n            // Cached, but nothing has been refused since the server last\n            // answered — not the AGL-1066 fault, so the budget is refunded\n            // exactly as it always was. This is what keeps offline inert:\n            // `unavailable` never enters `deniedStreak`.\n            attempt = 0\n          }\n          if (!terminal) {\n            setStatus('success')\n            setError(undefined)\n          }\n          // Always true after ANY emission, cached included: this is what\n          // tells a consumer \"I have data, the server refused\" apart from \"I\n          // never had data\" — the distinction the besigner editors and the\n          // host setup Theme tab blank on (AGL-1066).\n          setHasEmitted(true)\n          // Kept, not dropped: a snapshot that still carries this client's\n          // own queued write is not evidence of what the store holds\n          // (AGL-1262). Callers that record a \"last saved\" state need to\n          // know the difference.\n          setHasPendingWrites(snapshot.metadata.hasPendingWrites)\n          setFromCache(snapshot.metadata.fromCache)\n          const value = snapshot.exists()\n            ? ({\n                ...(snapshot.data() as object),\n                ...(idField ? { [idField]: snapshot.id } : {}),\n              } as T)\n            : (undefined as T)\n          setData(value)\n          resolveFirstValueRef.current?.()\n        },\n        (err) => {\n          if (cancelled) return\n          unsubscribe?.()\n          // Only a refusal — a lost network produces no error callback at\n          // all, and anything that does surface one carries `unavailable`,\n          // which must never read as a dead session.\n          if ((err as { code?: string })?.code === 'permission-denied') {\n            deniedStreak += 1\n            if (deniedStreak === 1) deniedStreakStartedAt = Date.now()\n            if (deniedStreak >= DENIAL_STREAK_TO_REPORT) setServerDenied(true)\n          }\n          if (attempt < MAX_RETRIES) {\n            attempt += 1\n            if (deniedStreak > MAX_RETRIES) {\n              cancelRefusedReopen = scheduleRefusedReopen(\n                subscribe,\n                deniedStreakStartedAt,\n              )\n            } else {\n              timer = setTimeout(subscribe, RETRY_DELAY_MS)\n            }\n          } else {\n            terminal = true\n            setStatus('error')\n            setError(err)\n            resolveFirstValueRef.current?.()\n            // A refusal streak keeps a slow road back for a recovery nobody\n            // announced — see the same branch in `use-firestore-collection`.\n            // The cadence splits on session-vs-ref evidence (AGL-1440), grows\n            // with the streak's age (AGL-2945) and waits while the tab is\n            // hidden (AGL-2944).\n            if (deniedStreak > MAX_RETRIES) {\n              cancelRefusedReopen = scheduleRefusedReopen(\n                subscribe,\n                deniedStreakStartedAt,\n              )\n            }\n          }\n        },\n      )\n    }\n    subscribe()\n\n    /**\n     * Reopen when the session heals — see the long note on the same\n     * subscription in `use-firestore-collection` (AGL-1066).\n     *\n     * This hook is where it counts most: its deps are `[ref.firestore,\n     * ref.path]`, neither of which moves when a `stale` re-auth signs the\n     * same uid back in, and it is what every besigner editor reads through.\n     * Nothing else was ever going to bring those pages back without a reload.\n     */\n    const unsubscribeHeal = subscribeFirestoreSessionHeal(() => {\n      if (cancelled || deniedStreak === 0) return\n      if (timer) {\n        clearTimeout(timer)\n        timer = null\n      }\n      cancelRefusedReopen?.()\n      cancelRefusedReopen = null\n      unsubscribe?.()\n      attempt = 0\n      subscribe()\n    })\n\n    return () => {\n      cancelled = true\n      unsubscribeHeal()\n      if (timer) clearTimeout(timer)\n      cancelRefusedReopen?.()\n      unsubscribe?.()\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [ref.firestore, ref.path])\n\n  return {\n    status,\n    hasEmitted,\n    isComplete: false,\n    data,\n    error,\n    firstValuePromise: firstValuePromiseRef.current,\n    hasPendingWrites,\n    fromCache,\n    serverDenied,\n  }\n}\nexport type UseDocData<T> = typeof useDocData<T>\n\nexport function useDoc<T>(\n  ref: DocumentReference<T>,\n  options?: FirestoreDocOptions<T>,\n): {doc: ReturnType<UseDocData<T>>, setDoc: ReturnType<UseModifyDocCallback<T>>} {\n  return {doc: useDocData(ref, options), setDoc: useModifyDocCallback(ref)}\n}\n\n\nexport default useDoc\n"],"names":["onSnapshot","useEffect","useRef","useState","DENIAL_STREAK_TO_REPORT","noteFirestoreServerRead","scheduleRefusedReopen","subscribeFirestoreSessionHeal","CONFIRMABLE_LISTEN_OPTIONS","useModifyDocCallback","RETRY_DELAY_MS","MAX_RETRIES","useDocData","ref","options","idField","initialData","status","setStatus","undefined","data","setData","error","setError","hasEmitted","setHasEmitted","hasPendingWrites","setHasPendingWrites","fromCache","setFromCache","serverDenied","setServerDenied","resolveFirstValueRef","firstValuePromiseRef","current","Promise","resolve","cancelled","unsubscribe","timer","cancelRefusedReopen","attempt","deniedStreak","deniedStreakStartedAt","terminal","subscribe","snapshot","metadata","value","exists","id","err","code","Date","now","setTimeout","unsubscribeHeal","clearTimeout","firestore","path","isComplete","firstValuePromise","useDoc","doc","setDoc"],"mappings":"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"}

package/src/lib/hooks/helpers/use-modify-doc-callback.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type DocumentReference, type SetOptions, type UpdateData } from 'firebase/firestore';
+export type UpdateDocCallback<T> = (data: UpdateData<T>) => Promise<void>;
+export type SetDocCallback<T> = (data: Partial<T>, options?: SetOptions) => Promise<void>;
+export type ModifyDocOptions = SetOptions & {
+    shouldSet?: boolean;
+};
+export type ModifyDocCallback<T> = (data: UpdateData<T> | Partial<T>, options?: ModifyDocOptions) => Promise<void>;
+export declare function useUpdateDocCallback<T>(ref: DocumentReference<T>): UpdateDocCallback<T>;
+export declare function useSetDocCallback<T>(ref: DocumentReference<T>): SetDocCallback<T>;
+export declare function useModifyDocCallback<T>(ref: DocumentReference<T>): ModifyDocCallback<T>;
+export type UseModifyDocCallback<T> = typeof useModifyDocCallback<T>;
+export default useModifyDocCallback;

package/src/lib/hooks/helpers/use-modify-doc-callback.js

@@ -0,0 +1,110 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { HOST_UNPERSISTED_FIELDS, ORG_UNPERSISTED_FIELDS } from "@aglyn/aglyn";
+import { serverTimestamp, setDoc, updateDoc } from "firebase/firestore";
+import { useCallback } from "react";
+/**
+ * Every UI write stamps `updatedAt` (AGL-455) — the "last updated" columns
+ * read it, and callers historically forgot it. Spread order lets a caller's
+ * explicit `updatedAt` win (backfills, imports).
+ */ function stampUpdatedAt(data) {
+    return _extends({
+        updatedAt: serverTimestamp()
+    }, data);
+}
+/**
+ * Keys that are never document fields, taken from where that is written down
+ * (AGL-1429). `HOST_UNPERSISTED_FIELDS` and `ORG_UNPERSISTED_FIELDS` each
+ * declare the synthetic `$id` the readers attach; the INTERSECTION is used
+ * deliberately, so this generic boundary only ever strips a key that every
+ * declaration agrees is unpersisted. A key added to one map alone is not
+ * silently stripped from the other collection's writes — the spec's drift
+ * assertion fires instead, and someone decides.
+ */ /*
+ * Resolved on first use, not at module scope. Computing it eagerly made this
+ * module — and therefore every consumer of the write callbacks — fail to LOAD
+ * in any suite that mocks the `@aglyn/aglyn` barrel without re-exporting both
+ * maps, which two console specs do. A write-boundary guard that cannot be
+ * imported is worse than the leak it prevents.
+ */ let unpersistedFields;
+function getUnpersistedFields() {
+    if (unpersistedFields) return unpersistedFields;
+    const host = HOST_UNPERSISTED_FIELDS != null ? HOST_UNPERSISTED_FIELDS : {};
+    const org = ORG_UNPERSISTED_FIELDS != null ? ORG_UNPERSISTED_FIELDS : {};
+    unpersistedFields = Object.freeze(Object.keys(host).filter((key)=>key in org));
+    return unpersistedFields;
+}
+/**
+ * Drop the reader-injected keys before the payload leaves for Firestore.
+ *
+ * This has to happen here rather than in the refs' converters, which is where
+ * it used to live alone (`503f197ca` added the `$id` strip to `useHostRef`'s
+ * `toFirestore`). `updateDoc` never applies a converter — `setDoc` calls
+ * `applyFirestoreDataConverter` and `updateDoc` does not — so a converter
+ * strip is a guarantee about ONE of the two SDK calls, and which one a write
+ * gets is decided by whether its caller happened to pass `merge`. That is how
+ * `hosts/-MtN17_cpfPPLwWjE6z4` came to hold a persisted `$id` (AGL-1423).
+ *
+ * Only exact top-level keys are removed. Dotted `updateDoc` paths address
+ * nested maps, and besigner node maps legitimately store a `$id` per node —
+ * matching those would be the same over-broad scan AGL-1423 warned about.
+ */ function dropUnpersistedFields(data) {
+    const keys = getUnpersistedFields();
+    if (!keys.some((key)=>key in data)) return data;
+    const rest = _extends({}, data);
+    for (const key of keys)delete rest[key];
+    return rest;
+}
+// `updateDoc`'s overload resolution keys off `DocumentReference`'s
+// `DbModelType` param, which defaults to the generic `DocumentData` when a
+// caller only supplies `AppModelType` (as every hook here does) — that
+// makes TS widen `UpdateData<T>` for unconstrained `T` and reject the
+// match. Pin the call to the single-overload signature actually used.
+const typedUpdateDoc = updateDoc;
+export function useUpdateDocCallback(ref) {
+    return useCallback((data)=>typedUpdateDoc(ref, stampUpdatedAt(dropUnpersistedFields(data))), [
+        ref
+    ]);
+}
+export function useSetDocCallback(ref) {
+    return useCallback((data, options)=>setDoc(ref, stampUpdatedAt(dropUnpersistedFields(data)), options != null ? options : {}), [
+        ref
+    ]);
+}
+export function useModifyDocCallback(ref) {
+    const updateDocCb = useUpdateDocCallback(ref);
+    const setDocCb = useSetDocCallback(ref);
+    return useCallback((data, options)=>{
+        // SetOptions semantics (merge/mergeFields) require setDoc: updateDoc
+        // ignores them and, critically, bypasses the ref's withConverter
+        // serialization (e.g. screen-version node compression) — and with it
+        // EVERY strip the converter performs, including `$id` (AGL-1429).
+        //
+        // Nothing downstream of this line may therefore be relied on to clean
+        // a payload. Anything that must hold for both branches belongs above
+        // it, which is where `dropUnpersistedFields` now runs.
+        const shouldSet = (options == null ? void 0 : options.shouldSet) || options && 'merge' in options || options && 'mergeFields' in options;
+        if (shouldSet) return setDocCb(data, options);
+        return updateDocCb(data);
+    }, [
+        updateDocCb,
+        setDocCb
+    ]);
+}
+export default useModifyDocCallback;
+
+//# sourceMappingURL=use-modify-doc-callback.js.map

package/src/lib/hooks/helpers/use-modify-doc-callback.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../../libs/tenant/feature/instance/src/lib/hooks/helpers/use-modify-doc-callback.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { HOST_UNPERSISTED_FIELDS, ORG_UNPERSISTED_FIELDS } from '@aglyn/aglyn'\nimport {\n  type DocumentReference,\n  serverTimestamp,\n  setDoc,\n  type SetOptions,\n  type UpdateData,\n  updateDoc,\n} from 'firebase/firestore'\nimport { useCallback } from 'react'\n\n/**\n * Every UI write stamps `updatedAt` (AGL-455) — the \"last updated\" columns\n * read it, and callers historically forgot it. Spread order lets a caller's\n * explicit `updatedAt` win (backfills, imports).\n */\nfunction stampUpdatedAt<D extends object>(data: D): D {\n  return { updatedAt: serverTimestamp(), ...data }\n}\n\n/**\n * Keys that are never document fields, taken from where that is written down\n * (AGL-1429). `HOST_UNPERSISTED_FIELDS` and `ORG_UNPERSISTED_FIELDS` each\n * declare the synthetic `$id` the readers attach; the INTERSECTION is used\n * deliberately, so this generic boundary only ever strips a key that every\n * declaration agrees is unpersisted. A key added to one map alone is not\n * silently stripped from the other collection's writes — the spec's drift\n * assertion fires instead, and someone decides.\n */\n/*\n * Resolved on first use, not at module scope. Computing it eagerly made this\n * module — and therefore every consumer of the write callbacks — fail to LOAD\n * in any suite that mocks the `@aglyn/aglyn` barrel without re-exporting both\n * maps, which two console specs do. A write-boundary guard that cannot be\n * imported is worse than the leak it prevents.\n */\nlet unpersistedFields: readonly string[] | undefined\n\nfunction getUnpersistedFields(): readonly string[] {\n  if (unpersistedFields) return unpersistedFields\n  const host = HOST_UNPERSISTED_FIELDS ?? {}\n  const org = ORG_UNPERSISTED_FIELDS ?? {}\n  unpersistedFields = Object.freeze(\n    Object.keys(host).filter((key) => key in org),\n  )\n  return unpersistedFields\n}\n\n/**\n * Drop the reader-injected keys before the payload leaves for Firestore.\n *\n * This has to happen here rather than in the refs' converters, which is where\n * it used to live alone (`503f197ca` added the `$id` strip to `useHostRef`'s\n * `toFirestore`). `updateDoc` never applies a converter — `setDoc` calls\n * `applyFirestoreDataConverter` and `updateDoc` does not — so a converter\n * strip is a guarantee about ONE of the two SDK calls, and which one a write\n * gets is decided by whether its caller happened to pass `merge`. That is how\n * `hosts/-MtN17_cpfPPLwWjE6z4` came to hold a persisted `$id` (AGL-1423).\n *\n * Only exact top-level keys are removed. Dotted `updateDoc` paths address\n * nested maps, and besigner node maps legitimately store a `$id` per node —\n * matching those would be the same over-broad scan AGL-1423 warned about.\n */\nfunction dropUnpersistedFields<D extends object>(data: D): D {\n  const keys = getUnpersistedFields()\n  if (!keys.some((key) => key in data)) return data\n  const rest = { ...data } as Record<string, unknown>\n  for (const key of keys) delete rest[key]\n  return rest as D\n}\n\n\nexport type UpdateDocCallback<T> = (data: UpdateData<T>) => Promise<void>\nexport type SetDocCallback<T> = (\n  data: Partial<T>,\n  options?: SetOptions,\n) => Promise<void>\nexport type ModifyDocOptions = SetOptions & { shouldSet?: boolean }\nexport type ModifyDocCallback<T> = (\n  data: UpdateData<T> | Partial<T>,\n  options?: ModifyDocOptions,\n) => Promise<void>\n\n// `updateDoc`'s overload resolution keys off `DocumentReference`'s\n// `DbModelType` param, which defaults to the generic `DocumentData` when a\n// caller only supplies `AppModelType` (as every hook here does) — that\n// makes TS widen `UpdateData<T>` for unconstrained `T` and reject the\n// match. Pin the call to the single-overload signature actually used.\nconst typedUpdateDoc = updateDoc as <T>(\n  ref: DocumentReference<T>,\n  data: UpdateData<T>,\n) => Promise<void>\n\nexport function useUpdateDocCallback<T>(\n  ref: DocumentReference<T>,\n): UpdateDocCallback<T> {\n  return useCallback(\n    (data: UpdateData<T>) =>\n      typedUpdateDoc(\n        ref,\n        stampUpdatedAt(dropUnpersistedFields(data as object)) as UpdateData<T>,\n      ),\n    [ref],\n  )\n}\n\nexport function useSetDocCallback<T>(\n  ref: DocumentReference<T>,\n): SetDocCallback<T> {\n  return useCallback(\n    (data: Partial<T>, options?: SetOptions) =>\n      setDoc(\n        ref,\n        stampUpdatedAt(dropUnpersistedFields(data as object)) as Partial<T>,\n        options ?? {},\n      ),\n    [ref],\n  )\n}\n\nexport function useModifyDocCallback<T>(\n  ref: DocumentReference<T>,\n): ModifyDocCallback<T> {\n  const updateDocCb = useUpdateDocCallback(ref)\n  const setDocCb = useSetDocCallback(ref)\n  return useCallback(\n    (data: UpdateData<T> | Partial<T>, options?: ModifyDocOptions) => {\n      // SetOptions semantics (merge/mergeFields) require setDoc: updateDoc\n      // ignores them and, critically, bypasses the ref's withConverter\n      // serialization (e.g. screen-version node compression) — and with it\n      // EVERY strip the converter performs, including `$id` (AGL-1429).\n      //\n      // Nothing downstream of this line may therefore be relied on to clean\n      // a payload. Anything that must hold for both branches belongs above\n      // it, which is where `dropUnpersistedFields` now runs.\n      const shouldSet =\n        options?.shouldSet ||\n        (options && 'merge' in options) ||\n        (options && 'mergeFields' in options)\n      if (shouldSet) return setDocCb(data as Partial<T>, options)\n      return updateDocCb(data as UpdateData<T>)\n    },\n    [updateDocCb, setDocCb],\n  )\n}\n\n\nexport type UseModifyDocCallback<T> = typeof useModifyDocCallback<T>\n\nexport default useModifyDocCallback\n"],"names":["HOST_UNPERSISTED_FIELDS","ORG_UNPERSISTED_FIELDS","serverTimestamp","setDoc","updateDoc","useCallback","stampUpdatedAt","data","updatedAt","unpersistedFields","getUnpersistedFields","host","org","Object","freeze","keys","filter","key","dropUnpersistedFields","some","rest","typedUpdateDoc","useUpdateDocCallback","ref","useSetDocCallback","options","useModifyDocCallback","updateDocCb","setDocCb","shouldSet"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,uBAAuB,EAAEC,sBAAsB,QAAQ,eAAc;AAC9E,SAEEC,eAAe,EACfC,MAAM,EAGNC,SAAS,QACJ,qBAAoB;AAC3B,SAASC,WAAW,QAAQ,QAAO;AAEnC;;;;CAIC,GACD,SAASC,eAAiCC,IAAO;IAC/C,OAAO;QAAEC,WAAWN;OAAsBK;AAC5C;AAEA;;;;;;;;CAQC,GACD;;;;;;CAMC,GACD,IAAIE;AAEJ,SAASC;IACP,IAAID,mBAAmB,OAAOA;IAC9B,MAAME,OAAOX,kCAAAA,0BAA2B,CAAC;IACzC,MAAMY,MAAMX,iCAAAA,yBAA0B,CAAC;IACvCQ,oBAAoBI,OAAOC,MAAM,CAC/BD,OAAOE,IAAI,CAACJ,MAAMK,MAAM,CAAC,CAACC,MAAQA,OAAOL;IAE3C,OAAOH;AACT;AAEA;;;;;;;;;;;;;;CAcC,GACD,SAASS,sBAAwCX,IAAO;IACtD,MAAMQ,OAAOL;IACb,IAAI,CAACK,KAAKI,IAAI,CAAC,CAACF,MAAQA,OAAOV,OAAO,OAAOA;IAC7C,MAAMa,OAAO,aAAKb;IAClB,KAAK,MAAMU,OAAOF,KAAM,OAAOK,IAAI,CAACH,IAAI;IACxC,OAAOG;AACT;AAcA,mEAAmE;AACnE,2EAA2E;AAC3E,uEAAuE;AACvE,sEAAsE;AACtE,sEAAsE;AACtE,MAAMC,iBAAiBjB;AAKvB,OAAO,SAASkB,qBACdC,GAAyB;IAEzB,OAAOlB,YACL,CAACE,OACCc,eACEE,KACAjB,eAAeY,sBAAsBX,SAEzC;QAACgB;KAAI;AAET;AAEA,OAAO,SAASC,kBACdD,GAAyB;IAEzB,OAAOlB,YACL,CAACE,MAAkBkB,UACjBtB,OACEoB,KACAjB,eAAeY,sBAAsBX,QACrCkB,kBAAAA,UAAW,CAAC,IAEhB;QAACF;KAAI;AAET;AAEA,OAAO,SAASG,qBACdH,GAAyB;IAEzB,MAAMI,cAAcL,qBAAqBC;IACzC,MAAMK,WAAWJ,kBAAkBD;IACnC,OAAOlB,YACL,CAACE,MAAkCkB;QACjC,qEAAqE;QACrE,iEAAiE;QACjE,qEAAqE;QACrE,kEAAkE;QAClE,EAAE;QACF,sEAAsE;QACtE,qEAAqE;QACrE,uDAAuD;QACvD,MAAMI,YACJJ,CAAAA,2BAAAA,QAASI,SAAS,KACjBJ,WAAW,WAAWA,WACtBA,WAAW,iBAAiBA;QAC/B,IAAII,WAAW,OAAOD,SAASrB,MAAoBkB;QACnD,OAAOE,YAAYpB;IACrB,GACA;QAACoB;QAAaC;KAAS;AAE3B;AAKA,eAAeF,qBAAoB"}

package/src/lib/hooks/host-collection-queries.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type CollectionReference, type Query } from 'firebase/firestore';
+/**
+ * ONE ordering decision for the console lists a plugin renders (AGL-2501).
+ *
+ * ## What an unordered `limit()` actually answers
+ *
+ * Firestore answers a capped query with no `orderBy` in DOCUMENT-ID order, and
+ * every collection these cards read is keyed by a generated `createResourceUid`
+ * or by `add()`. So `limit(100)` is not "the first hundred variables" — it is a
+ * pseudo-random hundred, and the rows past it are not merely unrendered, they
+ * are UNREACHABLE, because nothing shows them and nothing asks for more. A
+ * client `.sort()` over that sample is what hides it: the rows on screen run in
+ * a believable order, they are simply the wrong rows, and the ones missing
+ * leave no gap to notice.
+ *
+ * The console's site-artifact lists reached this answer first
+ * (`hostArtifactQuery`) and could not share it: an app cannot be imported from
+ * a library, so every plugin card faced the same question alone and eleven of
+ * them answered it by not ordering at all. This is that decision, where a
+ * plugin can ask for it.
+ *
+ * ## Why the walk orders on the document ID, and not on a field
+ *
+ * The obvious fix is `orderBy` on the field the list is sorted by — `name` for
+ * most of these. It cannot be used. `orderBy` matches only documents that HAVE
+ * the field, so ordering on one that any writer omits does not mis-order the
+ * list, it HIDES rows from it: a worse failure than the one being fixed, and a
+ * silent one.
+ *
+ * Every collection these cards read has such a writer:
+ *
+ *  * `/api/hosts/resources` stores an ALLOW-LIST of fields and validates none
+ *    of them for presence, so a create that sends no name produces a document
+ *    with no `name` at all.
+ *  * `/api/hosts/import` copies only the keys a bundle actually carries through
+ *    `IMPORTABLE_FIELDS` — `variables`, `functions`, `workflows` and `actions`
+ *    are all in it — so a restored document carries a name only if the exported
+ *    one had it.
+ *  * `createdAt`/`updatedAt` are no better: the resources route stamps them
+ *    server-side and an import's `cleanDoc` stamps `updatedAt` only.
+ *
+ * A document's NAME is not a field and cannot be absent, so ordering on it
+ * drops nothing and the walk is TOTAL: every row is reachable by paging, which
+ * is the property the old queries lacked. It is not insertion order — the ids
+ * are random — so no list built on it may claim to be in one. What it is is
+ * stable, complete, and the same on every load.
+ *
+ * ## Callers must not re-sort the page
+ *
+ * Re-sorting a window of an id-ordered walk by name is the same lie the old
+ * code told: rows would run in one order within a page and another across
+ * pages, and the first page would still not be the alphabetical first page. A
+ * caller that holds a whole CEILING may sort — see `ceilingedWindow` — because
+ * it is sorting the entire collection rather than a slice of it.
+ *
+ * ## Why a `Query` is accepted and not only a `CollectionReference`
+ *
+ * A list is often a FILTERED collection — one kind of conversion, one channel
+ * — and a caller holding equality predicates could not reach this ordering
+ * without rebuilding it, which is how a second, unordered `limit()` comes to
+ * be written beside the one this module exists to replace. `query()` composes
+ * onto either, and a `CollectionReference` IS a `Query`, so widening the
+ * parameter adds no behavior: the walk is still ordered on the document name
+ * and is still total over the matching documents.
+ *
+ * Equality predicates only. A range filter or a second ordering would fight
+ * the `orderBy(documentId())` applied here — Firestore requires the range
+ * field to be ordered first — and such a query fails loudly at the listener
+ * rather than quietly returning the wrong rows.
+ */
+export declare function collectionPage(ref: CollectionReference | Query, pageLimit: number): Query;
+/**
+ * The same ordering, for a list that is BOUNDED rather than paged.
+ *
+ * Asks for one document more than the ceiling, which is what turns "there is
+ * more than this" into a fact. Pair it with `ceilingedWindow` to drop the probe
+ * row before rendering.
+ */
+export declare function collectionCeiling(ref: CollectionReference | Query, ceiling: number): Query;
+/** A ceilinged read, and whether the ceiling actually bit. */
+export interface CeilingedWindow<T> {
+    /** At most `ceiling` rows — the probe is never among them. */
+    rows: T[];
+    /** The collection holds MORE than the ceiling. A fact, not an estimate. */
+    truncated: boolean;
+}
+/**
+ * A read that is bounded but not paged, and can say when it is short.
+ *
+ * Some lists cannot be windowed by document and must still be bounded: a
+ * hierarchy sliced by row separates a child from its parent, a bundle
+ * straddling a page renders twice and partial each time, a precedence list
+ * paged by ten cannot swap its tenth row with its eleventh, and a table
+ * assembled from two collections cannot dedupe across a page boundary.
+ *
+ * A bare ceiling is silent, which is the half that matters. Every consequence
+ * on those surfaces is computed from what was read, so a collection above the
+ * ceiling is drawn as a whole one with nothing to distinguish "there is no such
+ * row" from "this card did not read it".
+ *
+ * Asking for ONE document more than the ceiling turns that into a fact for the
+ * price of a single read. The probe is never handed on: a caller that rendered
+ * `ceiling + 1` rows would be describing a window it did not draw.
+ *
+ * `hasMore` in `usePagedCollection` is the same trick for a paged list, and for
+ * the same reason — a comparison against the cap is wrong exactly when the
+ * count is an even multiple of it.
+ */
+export declare function ceilingedWindow<T>(read: readonly T[] | undefined, ceiling: number): CeilingedWindow<T>;