@50arms/ui 0.0.0-stage → 35.1.0

package/dist/types/lib/realtime/registry.d.ts

@@ -0,0 +1,225 @@
+import type { RealtimeDiagnostic, RealtimeEvent, RealtimeHealth, RealtimeScope, RealtimeScopeInput, RealtimeTransport } from "./types";
+import type { RecordPayload } from "../records";
+export interface RegistryOptions {
+    readonly transport: RealtimeTransport;
+    readonly tenant?: string | number;
+    readonly keepaliveIntervalMs?: number;
+    readonly expiryMarginMs?: number;
+    readonly baseBackoffMs?: number;
+    readonly maxBackoffMs?: number;
+    readonly maxAttempts?: number;
+    /**
+     * The event name that means "this record just entered the set".
+     *
+     * Configurable because the name is the backend's, not this library's, and
+     * hard-coding one would be the only domain fact in this module.
+     */
+    readonly createdEventName?: string;
+    /**
+     * Drop a broadcast this client caused.
+     *
+     * A PREDICATE RATHER THAN A FIELD NAME, because the field that says who
+     * caused a change belongs to a wire format, not to a design system. Supplied
+     * by the app or absent; absent means every broadcast is written.
+     *
+     * IT APPLIES TO BROADCASTS ONLY, structurally — a fetch and a mutation's
+     * returned item never pass through here at all. That matters: a mutation
+     * response is self-caused BY DEFINITION, and dropping it would discard the
+     * server-computed fields the client asked for.
+     */
+    readonly isSelfEvent?: (payload: RecordPayload) => boolean;
+    readonly onDiagnostic?: (diagnostic: RealtimeDiagnostic) => void;
+    /** Test seam. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+export declare function readRealtimeEpoch(): number;
+export declare function subscribeToRealtimeEpoch(listener: () => void): () => void;
+/** Every broadcast, AFTER it has been written to the store. */
+export declare function subscribeToRealtimeEvents(listener: (event: RealtimeEvent) => void): () => void;
+/** Test seam. Nothing in the library calls this. */
+export declare function resetRealtimeSignals(): void;
+/**
+ * Normalize a caller's scope and give it a stable key.
+ *
+ * IDS ARE SORTED AND STRINGIFIED so two components asking for the same rows in
+ * a different order coalesce onto one subscription rather than opening two —
+ * and so a numeric id and its string form never split an entry, exactly as the
+ * store keys records.
+ */
+export declare function normalizeScope(input: RealtimeScopeInput): RealtimeScope;
+export declare function scopeKey(scope: RealtimeScope): string;
+/**
+ * The registry's key for a (type, scope) subscription — the identity
+ * `RealtimeEvent.subscriptions` names.
+ *
+ * ONE FUNCTION FOR BOTH SIDES. The registry keys its entries with it and a list
+ * slot keys its declared `createdScope` with it, so the two cannot disagree
+ * about what "the same subscription" means — a type spelled `WorkflowInput`
+ * here and `WorkflowInputResource` there would silently never match.
+ */
+export declare function subscriptionKey(type: string, scope: RealtimeScopeInput | RealtimeScope): string;
+export declare class SubscriptionRegistry {
+    private readonly transport;
+    private readonly entries;
+    private readonly channels;
+    private readonly options;
+    private readonly healthListeners;
+    private tenant;
+    private connection;
+    private stopConnectionObserver;
+    private timer;
+    private healthSnapshot;
+    private lastError;
+    private started;
+    private disposed;
+    constructor(options: RegistryOptions);
+    /**
+     * Begin observing the connection and renewing leases.
+     *
+     * THE TIMER STARTS HERE, NEVER ON IMPORT. A design-system module that starts
+     * an interval because somebody imported it is a worse defect than the leak it
+     * would be preventing: it runs in every consumer, including the ones that
+     * never touch realtime at all.
+     */
+    start(): void;
+    /**
+     * The document became visible again, or the page was restored from the
+     * back/forward cache — either way, a gap of UNKNOWN length just ended.
+     *
+     * `pusher:subscription_succeeded`/`state_change` (what `onConnectionState`
+     * listens for) is the transport TELLING us the socket dropped and came
+     * back. It is not the only way a gap happens: the OS suspending the
+     * machine, or the browser freezing a backgrounded tab under memory
+     * pressure, pauses this process's OWN timers along with everything else —
+     * including whatever ping/pong loop the transport uses to notice its own
+     * connection died. A transport that never got to run its detection code
+     * has nothing to report, so `connectionState()` can read "connected"
+     * throughout a gap the socket did not actually survive, and `tick()`'s own
+     * `isDead()` check — which trusts that string — has nothing to catch.
+     *
+     * Pusher has no event replay. Broadcasting is also gated server-side on a
+     * short-TTL registration (`PusherSubscriptionService`, 300s) that a long
+     * enough gap can outlive on its own. Either way, "did we actually miss
+     * anything" has no answer worth computing — the same reasoning
+     * `onConnectionState`'s reconnect branch already acts on — so becoming
+     * visible again is treated exactly like a reconnect: every entry is
+     * resubscribed (which the SubscriptionRegistry itself dedupes against
+     * one that is still genuinely healthy — a resubscribe is bounded, cheap,
+     * and correctness-preserving even when it turns out to have been
+     * unnecessary), and the epoch bumps on each success, which is what
+     * drives every mounted read (`reads/refetch.ts`'s `onEpoch`) to reissue
+     * the request it already made.
+     */
+    private onResume;
+    private handleVisibilityChange;
+    /** `event.persisted` is a bfcache restore — a full page resume with no `visibilitychange` of its own. */
+    private handlePageShow;
+    /**
+     * Stop the timers. REVERSIBLE, and it keeps every entry and every channel.
+     *
+     * THIS IS WHAT STRICTMODE REQUIRES. React mounts every effect, unmounts it,
+     * and mounts it again in development — so a teardown that dropped the entries
+     * would make the remount issue a SECOND subscribe for a registration that is
+     * still perfectly live, and the whole misbehaviour would exist only in
+     * development, which is the worst place for a realtime bug to live because it
+     * is where the thing is being debugged.
+     *
+     * IT DOES NOT UNSUBSCRIBE, and it does not leave the socket channels. Unmount
+     * never touches the server-side registry — the entry lapses against its own
+     * TTL — and the socket belongs to the application that injected it. A tenant
+     * switch is the one place either of those happens, and it has its own method.
+     */
+    stop(): void;
+    /**
+     * Full teardown: stop, leave every channel, forget every entry.
+     *
+     * NOT what a component unmount calls — see `stop`. This exists for an
+     * application deliberately switching realtime off, which is a decision no
+     * lifecycle can infer.
+     */
+    dispose(): void;
+    /**
+     * Switch tenants: tear the server-side registrations down, clear the socket,
+     * and re-establish everything still mounted under the new tenant.
+     *
+     * THIS IS THE ONE PLACE `unsubscribe` IS CALLED. Never-unsubscribe applies to
+     * UNMOUNT, where tearing down can kill another tab's subscription; a
+     * subscription left lapsing on the PREVIOUS tenant's channel is a leak of a
+     * different kind, and one this library can close on its own.
+     */
+    setTenant(tenant: string | number | undefined): void;
+    getTenant(): string | number | undefined;
+    /**
+     * Declare interest in a (type, scope) with a set of event names.
+     *
+     * THE RETURNED RELEASE IS IDEMPOTENT AND EXACTLY PAIRED, which is what makes
+     * StrictMode's mount / unmount / mount leave exactly ONE subscription: the
+     * refcount goes 1, 0, 1 while the server-side registration is never dropped,
+     * so the remount reuses the live lease instead of issuing a second subscribe.
+     */
+    acquire(type: string, scopeInput: RealtimeScopeInput, events: readonly string[]): () => void;
+    private subscribeEntry;
+    /**
+     * Bounded exponential backoff, then a terminal DEAD state.
+     *
+     * NOTHING IS ESCALATED, EVER. The failure that motivates this is a 401 on a
+     * background resubscribe: routed through an app's ordinary HTTP error path it
+     * clears the session and logs somebody out mid-screen. Here it is a number in
+     * `attempts`, a string in `lastError`, and a status a screen can print.
+     */
+    private scheduleRetry;
+    private clearRetry;
+    /**
+     * Is this subscription failing to deliver?
+     *
+     * THREE INPUTS, ANY ONE SUFFICIENT, and the first is the one no reconnect
+     * hook can see: the lease simply runs out while everything else looks
+     * healthy.
+     */
+    private isDead;
+    /**
+     * One pass: renew what is live, revive what is dead.
+     *
+     * Exposed so a consumer — or a test — can run it without waiting for the
+     * interval. Everything it does is idempotent.
+     */
+    tick(): void;
+    private keepalive;
+    private onConnectionState;
+    private ensureChannel;
+    private leaveAllChannels;
+    /**
+     * One broadcast: filter, write, announce.
+     *
+     * THE TENANT IS THE ONE THE CHANNEL WAS JOINED UNDER, captured at bind time
+     * and never read at delivery time. Reading it on arrival reads the tenant as
+     * it is NOW, which is precisely how a payload from the team you just left
+     * lands in the store as the team you just joined.
+     */
+    private deliver;
+    /**
+     * This client's subscriptions a broadcast satisfied, translated from the
+     * server's names through each entry's lease keys.
+     *
+     * THE WHOLE REASON THIS IS NEEDED: the channel is per type per tenant, so an
+     * event arrives here whenever ANY subscription on the tenant matched — a
+     * teammate's unfiltered list included. Arrival says "somebody on this team
+     * asked"; only this says "you asked". `undefined` when the transport cannot
+     * say, which is a different answer from `[]` ("it said, and none were yours").
+     */
+    private attribute;
+    /** The event name that means "entered the set", for the read binding. */
+    get createdEventName(): string;
+    subscribeToHealth: (listener: () => void) => (() => void);
+    /**
+     * The renderable state, memoized so `getSnapshot` returns the identical
+     * object when nothing changed — the constraint every store in this package is
+     * written around.
+     */
+    readHealth: () => RealtimeHealth;
+    private deriveStatus;
+    private notifyHealth;
+    private requestFor;
+    private callTransport;
+    private diagnose;
+}

package/dist/types/lib/realtime/types.d.ts

@@ -0,0 +1,242 @@
+import type { RecordPayload } from "../records";
+/**
+ * What the socket says about itself.
+ *
+ * IT IS NOT THE SAME QUESTION AS "am I receiving events". A registry entry can
+ * lapse server-side while this reads `"connected"` forever, which is exactly
+ * why liveness is computed from three inputs and not from this one.
+ */
+export type RealtimeConnectionState = "connecting" | "connected" | "disconnected";
+/**
+ * WHICH RECORDS a subscription is asking to hear about.
+ *
+ * - `ids` — the rows on screen. The backend keys its registry entry per model
+ *   id, so this is the scope that pins specific records.
+ * - `filter` — a server-evaluated predicate. The backend re-runs it per save
+ *   and answers "does this record match this filter" — and NOTHING about sort
+ *   position or page boundary. ARRIVAL ALONE PROVES NOTHING about this filter:
+ *   the channel is per type per tenant, so an event arrives whenever ANY
+ *   subscription on the tenant matched, including a teammate's wider one. Only
+ *   `RealtimeEvent.subscriptions` says which of this client's scopes it
+ *   satisfied.
+ * - `all` — every record of the type for this tenant.
+ */
+export type RealtimeScope = {
+    readonly kind: "ids";
+    readonly ids: readonly string[];
+} | {
+    readonly kind: "filter";
+    readonly filter: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: "all";
+};
+/** What a caller may write, before normalization. `"all"` or ids or a filter. */
+export type RealtimeScopeInput = "all" | readonly (string | number)[] | {
+    readonly filter: Readonly<Record<string, unknown>>;
+};
+/** One server-side registration, as the transport receives it. */
+export interface SubscriptionRequest {
+    /** The NORMALIZED model name — never a `Resource` suffix. */
+    readonly type: string;
+    readonly scope: RealtimeScope;
+    /**
+     * The tenant this registration belongs to, passed rather than inferred so a
+     * request issued before a team switch can never be attributed to the team
+     * that came after it.
+     */
+    readonly tenant: string | number | undefined;
+    /** A stable identity for this (type, scope) pair. Useful as a request key. */
+    readonly key: string;
+}
+/**
+ * What the server said about a registration.
+ *
+ * `expiresAt` IS THE WHOLE POINT OF THIS TYPE. The registry holds it and treats
+ * a subscription as DEAD once the clock passes it minus a margin — never
+ * "letting it expire naturally", which is the prior art's exact wording and its
+ * exact bug: two failed keepalives inside one TTL window and that resource
+ * stops updating forever, silently, with a healthy socket.
+ */
+export interface SubscriptionLease {
+    /** Milliseconds since epoch. Omit only if the server genuinely does not say. */
+    readonly expiresAt?: number;
+    /**
+     * The SERVER'S names for this registration — one per server-side entry the
+     * request fanned out to — in the same vocabulary `subscriptionsOf` returns.
+     *
+     * THIS IS HALF OF ATTRIBUTION. A broadcast names the server entries it
+     * satisfied; the registry maps those names back to its own subscriptions
+     * through these. Omitted on a keepalive, the names from the last subscribe
+     * stand — they describe the registration, which a renewal does not change.
+     */
+    readonly keys?: readonly string[];
+}
+/** A joined socket channel. One per type per tenant, and no more. */
+export interface RealtimeChannel {
+    /**
+     * Bind one event name.
+     *
+     * CALLED AGAIN FOR EVERY NEW EVENT NAME A LATER SUBSCRIBER BRINGS, on the
+     * SAME channel object. The prior art returns early when the channel already
+     * exists and never reaches its own bind call, so only the FIRST subscriber's
+     * event names are ever live — two real subscribers collide on that today and
+     * one of them is silently dead in production. A transport implementation must
+     * therefore accept `bind` at any time, not only immediately after joining.
+     */
+    bind(event: string, handler: (payload: RecordPayload) => void): void;
+    /** Leave the channel entirely. Called on a tenant switch and on teardown. */
+    leave(): void;
+}
+/**
+ * Everything environment-specific, in one injected object: the socket, the
+ * three registry endpoints, and the connection observer.
+ *
+ * ONE CONSTRAINT ON THE IMPLEMENTATION THAT IS NOT EXPRESSIBLE IN THE TYPE, and
+ * it is the sharpest one: `subscribe`, `unsubscribe` and `keepalive` MUST NOT
+ * route their failures through an application's global 401 handler. A
+ * background resubscribe is allowed to fail; if that failure clears the
+ * session, a transient auth blip logs somebody out mid-screen — strictly worse
+ * than the stale screen the resubscribe existed to prevent. Reusing the app's
+ * default HTTP client is the easy thing to do and is exactly the bug. The
+ * registry holds up its half: it catches every rejection, backs off, and
+ * renders a DEAD state rather than escalating anything.
+ */
+export interface RealtimeTransport {
+    /** Register interest server-side. Rejecting is normal and is handled. */
+    subscribe(request: SubscriptionRequest): Promise<SubscriptionLease>;
+    /**
+     * Drop a registration.
+     *
+     * CALLED ONLY ON A TENANT SWITCH, never on unmount. The server keys its entry
+     * by USER, so two browser tabs belonging to one person share one entry — and
+     * one tab unmounting a screen would kill the other tab's still-mounted
+     * subscription, silently, with that tab's socket perfectly healthy. In-tab
+     * refcounting cannot fix that; the collision is above the tab. On unmount the
+     * entry is left to lapse against its own TTL, which costs a subscription
+     * outliving its component by a few minutes and nothing else.
+     */
+    unsubscribe(request: SubscriptionRequest): Promise<void>;
+    /**
+     * Renew several registrations at once.
+     *
+     * Resolve with one lease per request, in the SAME ORDER. Rejecting marks
+     * every request in the batch as failed — which is a DEAD subscription, not a
+     * warning, and the registry resubscribes rather than waiting.
+     */
+    keepalive(requests: readonly SubscriptionRequest[]): Promise<readonly SubscriptionLease[]>;
+    /**
+     * Which server-side registrations a broadcast satisfied, in the vocabulary of
+     * `SubscriptionLease.keys` — or `undefined` when this payload does not say.
+     *
+     * WHY IT EXISTS: the channel carries every record of a type for a whole
+     * tenant, and the server sends an event there when ANY subscription on the
+     * tenant matched. Without this a list filtered to schema A counts a record
+     * that arrived only because a teammate has an unfiltered list open —
+     * observed, not theorised. A method rather than a field name because the
+     * field belongs to the wire format, like `isSelfEvent`.
+     *
+     * Optional: a transport whose server cannot attribute leaves it off, and a
+     * list whose membership needs attribution (a `filter` scope) then counts
+     * nothing rather than guessing.
+     */
+    subscriptionsOf?(payload: RecordPayload): readonly string[] | undefined;
+    /** Join (or return) the channel carrying this type for this tenant. */
+    channel(type: string, tenant: string | number | undefined): RealtimeChannel;
+    connectionState(): RealtimeConnectionState;
+    observeConnection(listener: (state: RealtimeConnectionState) => void): () => void;
+}
+/**
+ * Why a subscription is not delivering, in the words a screen can print.
+ *
+ * A DEBUG PANEL SERVES DEVELOPERS; THE READER NEEDS A WORD ON SCREEN. This app
+ * refuses to collapse distinct absences everywhere else it has them, and a
+ * silently dead realtime layer is exactly the absence that gets collapsed by
+ * default — the prior art's observability is console-only behind a keyboard
+ * shortcut, which is why two live bugs in it went unnoticed for years.
+ */
+export type RealtimeStatus = 
+/** No transport was provided. Realtime is off and the app still works. */
+"unconfigured"
+/** Configured, nothing subscribed yet. */
+ | "idle"
+/** A first subscribe is in flight. */
+ | "connecting"
+/** Every active subscription is registered and the socket is connected. */
+ | "live"
+/** At least one subscription is not delivering. The screen should say so. */
+ | "dead";
+/** One subscription, as a devtools panel or a status line would render it. */
+export interface SubscriptionHealth {
+    readonly key: string;
+    readonly type: string;
+    readonly scope: RealtimeScope;
+    /** Bound event names — the UNION of every subscriber's, never the first's. */
+    readonly events: readonly string[];
+    readonly subscribers: number;
+    readonly expiresAt: number | undefined;
+    readonly dead: boolean;
+    /** Consecutive failed resubscribe attempts. Resets on success. */
+    readonly attempts: number;
+    readonly lastError: string | undefined;
+}
+/** The renderable liveness state. */
+export interface RealtimeHealth {
+    readonly status: RealtimeStatus;
+    readonly connection: RealtimeConnectionState;
+    readonly subscriptions: readonly SubscriptionHealth[];
+    /**
+     * Bumps whenever a subscription that WAS dead is restored.
+     *
+     * It is the "you may have missed events" signal, and it is deliberately a
+     * monotonic counter rather than a set of keys: a lapsed registry entry stops
+     * broadcasts without saying which ones were dropped, so the only honest claim
+     * is that something may be missing. The read binding folds it into a refetch
+     * of what is mounted — which keeps the answer on screen and marks it
+     * refreshing, rather than blanking to a skeleton.
+     */
+    readonly epoch: number;
+    readonly lastError: string | undefined;
+}
+/** Something worth recording. Observability only; never control flow. */
+export interface RealtimeDiagnostic {
+    readonly kind: "subscribed" | "resubscribed" | "subscribe-failed" | "keepalive-failed" | "expired" | "disconnected" | "event" | "self-event-dropped" | "unsubscribed";
+    readonly key?: string;
+    readonly type?: string;
+    readonly event?: string;
+    readonly message?: string;
+    readonly at: number;
+}
+/** One broadcast, after the registry has written it into the store. */
+export interface RealtimeEvent {
+    /** Normalized model name. */
+    readonly type: string;
+    /** The event name as bound, e.g. `"created"`. */
+    readonly event: string;
+    /**
+     * `Type:id`, or `undefined` when the payload was not a record OR the store
+     * refused the write — a record that did not land must not reach a list
+     * either.
+     */
+    readonly key: string | undefined;
+    /**
+     * Whether this is the event that means "entered the set".
+     *
+     * COMPUTED HERE rather than compared by the consumer, because the name is the
+     * backend's (`"created"` by default, configurable on the provider) and a
+     * consumer comparing the string would be the second place that fact lives.
+     */
+    readonly isCreate: boolean;
+    /**
+     * This client's subscriptions the broadcast satisfied, by registry key
+     * (`subscriptionKey(type, scope)`), or `undefined` when the transport could
+     * not attribute it.
+     *
+     * AN EMPTY ARRAY IS AN ANSWER, not a missing one: the server attributed the
+     * event and none of the names were this client's — it is on the channel for
+     * somebody else's subscription. That is the case a filtered list must not
+     * count.
+     */
+    readonly subscriptions: readonly string[] | undefined;
+    readonly payload: RecordPayload;
+    readonly tenant: string | number | undefined;
+}

package/dist/types/lib/records/define-record-type.d.ts

@@ -0,0 +1,29 @@
+import type { RecordTypeOptions, RecordTypeToken } from "./types";
+/**
+ * Declare a record type.
+ *
+ * THE NAME IS THE NORMALIZED MODEL NAME — `"WorkflowRun"`, NEVER
+ * `"WorkflowRunResource"`. This is the single most likely thing in this module
+ * to be built wrong, because both readings are plausible and exactly one
+ * matches: the store strips a trailing `Resource` from every incoming `__type`
+ * before keying (created payloads carry the suffix, deletes do not), so the
+ * caller always writes the model name. The wrong one produces a store that
+ * fills up and a screen that never moves, with no error anywhere — which is
+ * why passing the suffixed name warns loudly rather than quietly working.
+ *
+ * @param name normalized model name, e.g. `"WorkflowRun"`
+ * @param options `staleFields` — the fields this type's broadcast cannot carry
+ */
+export declare function defineRecordType<T>(name: string, options?: RecordTypeOptions): RecordTypeToken<T>;
+/**
+ * What a type declared, for the store's own use.
+ *
+ * An UNREGISTERED type is not an error: a nested child of a type nobody
+ * declared is still a record with an identity, and refusing it would lose data
+ * the parent legitimately carries. It simply has no stale fields, which is the
+ * correct default — a type that never declared a gap in its broadcast is
+ * treated as having none.
+ */
+export declare function staleFieldsFor(type: string): readonly string[] | "*";
+/** Test seam. Nothing in the library calls this. */
+export declare function resetRecordTypes(): void;

package/dist/types/lib/records/hooks.d.ts

@@ -0,0 +1,46 @@
+import type { ReadOptions, RecordState, RecordTypeToken, StalenessEntry } from "./types";
+/**
+ * Read one record.
+ *
+ * `needs` IS REQUIRED. It names the field set that must have landed from a
+ * FETCH before this key reports `present`; until then the answer is `unknown`,
+ * even when a broadcast has already seeded the key with real values. That is
+ * the whole guard: a projection function handed a broadcast-seeded record
+ * assumes absent means empty and renders a confident, wrong answer.
+ *
+ * `id` may be `null`/`undefined` for a conditional read — the hook then holds
+ * no subscription and reports `unknown`, rather than forcing a caller into two
+ * code paths around a rule of hooks.
+ */
+export declare function useRecord<T>(token: RecordTypeToken<T>, id: string | number | null | undefined, options: ReadOptions): RecordState<T>;
+/**
+ * Read many records at once, sharing one hydration per key with every other
+ * reader of that key.
+ *
+ * IT TAKES A KEY LIST AND DERIVES A STRING FROM IT rather than depending on the
+ * array's identity, so a caller passing a freshly-mapped array on every render
+ * — the normal thing to do — does not re-subscribe and does not violate
+ * `getSnapshot` identity. The alternative, subscribing to the whole store for a
+ * set of records, is the anti-pattern this package already ships once in
+ * `createSimStore.useById`; per-key notification is the entire reason this
+ * store exists.
+ */
+export declare function useRecords<T>(token: RecordTypeToken<T>, ids: readonly (string | number)[], options: ReadOptions): readonly RecordState<T>[];
+/**
+ * The staleness signal: affected ROOTS and their now-stale field sets.
+ *
+ * ITS ONLY CONSUMER IS THE LAYER THAT PERFORMED THE ORIGINAL FETCH. It
+ * re-issues the request it already made — it needs no registry of loaders,
+ * because "which field set" is not a question it has to answer; it is the one
+ * it already asked. The library contributes the signal and nothing else, which
+ * is what keeps every endpoint and every type name out of this package.
+ *
+ * TWO PROPERTIES THE CONSUMER MUST SUPPLY, because they are not expressible
+ * here: coalescing in BREADTH (twenty-five rows going stale in one burst is one
+ * list refetch, not twenty-five record refetches) and in TIME (a minimum
+ * interval, plus dedup against a refetch already in flight — a second signal
+ * arriving mid-flight sets a re-run flag rather than issuing a second request).
+ * Breadth alone is not enough: an event with no change guard on the server
+ * fires continuously during a long job, so it is a stream rather than a burst.
+ */
+export declare function useStaleness(): readonly StalenessEntry[];

package/dist/types/lib/records/index.d.ts

@@ -0,0 +1,5 @@
+export { defineRecordType, resetRecordTypes } from "./define-record-type";
+export { useRecord, useRecords, useStaleness } from "./hooks";
+export { write, writeAll, peekRecord, readState, readStaleness, subscribeToKey, subscribeToStaleness, subscribeToLayers, layeredKeys, retainKeys, sweepRecords, setRecordStoreTenant, getRecordStoreTenant, subscribeToTenant, flushRecordNotifications, resetRecordStore, recordStoreStats, UNKNOWN_STATE, } from "./store";
+export { normalizeTypeName, normalizeTimestamp, recordKey, isRecordRef, type RecordRef } from "./wire";
+export type { ReadOptions, RecordPayload, RecordState, RecordTypeOptions, RecordTypeToken, StalenessEntry, WriteAllResult, WriteOptions, WriteResult, WriteSource, WriteVerdict, } from "./types";