Prometheus Entity Management API
    Preparing search index...

    Interface GraphState

    Canonical Zustand store: entities (server truth), patches (UI-only overlay), lists (id order + list meta), and entityStates (per-entity fetch state). Framework bindings subscribe to the vanilla store; stores, adapters, and engines can read it synchronously through graphStore.getState().

    interface GraphState {
        appendListResult: (
            key: string,
            ids: string[],
            meta: Partial<
                Omit<
                    ListState,
                    "ids"
                    | "isFetching"
                    | "isFetchingMore"
                    | "error"
                    | "stale",
                >,
            >,
        ) => void;
        clearEntitySyncMetadata: (type: string, id: string) => void;
        clearPatch: (type: string, id: string) => void;
        entities: Record<EntityType, Record<EntityId, Record<string, unknown>>>;
        entityStates: Record<string, EntityState>;
        ingestFetchedList: (
            type: string,
            entries: { data: Record<string, unknown>; id: string }[],
            options?: IngestFetchedListOptions,
        ) => void;
        insertIdInList: (
            key: string,
            id: string,
            position: number | "end" | "start",
        ) => void;
        invalidateEntity: (type: string, id?: string) => void;
        invalidateLists: (matcher: string | ((key: string) => boolean)) => void;
        invalidateType: (type: string) => void;
        lists: Record<QueryKey, ListState>;
        patchEntity: (
            type: string,
            id: string,
            patch: Record<string, unknown>,
        ) => void;
        patches: Record<EntityType, Record<EntityId, Record<string, unknown>>>;
        prependListResult: (
            key: string,
            ids: string[],
            meta?: Partial<ListState>,
        ) => void;
        readEntity: <T = Record<string, unknown>>(
            type: string,
            id: string,
        ) => T | null;
        readEntitySnapshot: <T = Record<string, unknown>>(
            type: string,
            id: string,
        ) => EntitySnapshot<T & Record<string, unknown>> | null;
        removeEntity: (type: string, id: string) => void;
        removeIdFromAllLists: (type: string, id: string) => void;
        replaceEntity: (
            type: string,
            id: string,
            data: Record<string, unknown>,
        ) => void;
        setEntityError: (type: string, id: string, error: string | null) => void;
        setEntityFetched: (type: string, id: string) => void;
        setEntityFetching: (type: string, id: string, fetching: boolean) => void;
        setEntityStale: (type: string, id: string, stale: boolean) => void;
        setEntitySyncMetadata: (
            type: string,
            id: string,
            metadata: Partial<EntitySyncMetadata>,
        ) => void;
        setListError: (
            key: string,
            error: string | null,
            typed?: EntityError | null,
        ) => void;
        setListFetching: (key: string, fetching: boolean) => void;
        setListFetchingMore: (key: string, fetchingMore: boolean) => void;
        setListResult: (
            key: string,
            ids: string[],
            meta: Partial<
                Omit<
                    ListState,
                    "ids"
                    | "isFetching"
                    | "isFetchingMore"
                    | "error"
                    | "stale",
                >,
            >,
        ) => void;
        setListStale: (key: string, stale: boolean) => void;
        syncMetadata: Record<string, EntitySyncMetadata>;
        unpatchEntity: (type: string, id: string, keys: string[]) => void;
        upsertEntities: (
            type: string,
            entries: { data: Record<string, unknown>; id: string }[],
        ) => void;
        upsertEntity: (
            type: string,
            id: string,
            data: Record<string, unknown>,
        ) => void;
    }
    Index
    appendListResult clearEntitySyncMetadata clearPatch entities entityStates ingestFetchedList insertIdInList invalidateEntity invalidateLists invalidateType lists patchEntity patches prependListResult readEntity readEntitySnapshot removeEntity removeIdFromAllLists replaceEntity setEntityError setEntityFetched setEntityFetching setEntityStale setEntitySyncMetadata setListError setListFetching setListFetchingMore setListResult setListStale syncMetadata unpatchEntity upsertEntities upsertEntity
    appendListResult: (
        key: string,
        ids: string[],
        meta: Partial<
            Omit<
                ListState,
                "ids"
                | "isFetching"
                | "isFetchingMore"
                | "error"
                | "stale",
            >,
        >,
    ) => void

    Append unique ids (e.g. infinite scroll) while merging meta; dedupes id order.

    clearEntitySyncMetadata: (type: string, id: string) => void

    Clear sync metadata for one entity.

    clearPatch: (type: string, id: string) => void

    Drop all patches for an entity (e.g. after successful mutation when server data is authoritative).

    entities: Record<EntityType, Record<EntityId, Record<string, unknown>>>

    Normalized server-confirmed records. Mutate only via upsert/replace/remove — not from components.

    entityStates: Record<string, EntityState>

    Per-entity fetch lifecycle keyed as ${type}:${id}.

    ingestFetchedList: (
        type: string,
        entries: { data: Record<string, unknown>; id: string }[],
        options?: IngestFetchedListOptions,
    ) => void

    Merge one fetched page, mark every row fetched, and update its list projections in one Zustand publication.

    insertIdInList: (
        key: string,
        id: string,
        position: number | "end" | "start",
    ) => void

    Insert or move an id in one list. If the id already exists, it is removed first then re-inserted at position.

    Type Declaration

      • (key: string, id: string, position: number | "end" | "start"): void

      • Parameters

        • key: string
        • id: string
        • position: number | "end" | "start"

          "start", "end", or numeric index

        Returns void

    invalidateEntity: (type: string, id?: string) => void

    Mark one or all entities of a type stale for subscriber-driven refetch. Does not delete data.

    Type Declaration

      • (type: string, id?: string): void

      • Parameters

        • type: string
        • Optionalid: string

          Omit to stale every entity of type

        Returns void

    invalidateLists: (matcher: string | ((key: string) => boolean)) => void

    Mark lists stale by key prefix or custom predicate so the next access triggers background refresh without dropping ids immediately.

    invalidateType: (type: string) => void

    Convenience: stale all entities of a type and lists whose keys start with type.

    lists: Record<QueryKey, ListState>

    List slots keyed by serialized query keys. Values hold id arrays and pagination — not entity clones.

    patchEntity: (type: string, id: string, patch: Record<string, unknown>) => void

    Merge UI-only fields into patches so every subscriber sees selection, expansion, optimistic toggles, etc., without forking canonical data.

    patches: Record<EntityType, Record<EntityId, Record<string, unknown>>>

    Local-only fields merged at read time (readEntity / hooks). Never send patches to the server.

    prependListResult: (
        key: string,
        ids: string[],
        meta?: Partial<ListState>,
    ) => void

    Prepend ids (e.g. “new item at top”) with optional meta merge.

    readEntity: <T = Record<string, unknown>>(type: string, id: string) => T | null

    Single read path: { ...entities[type][id], ...patches[type][id] } or null if no canonical row exists.

    Type Declaration

      • <T = Record<string, unknown>>(type: string, id: string): T | null

      • Type Parameters

        • T = Record<string, unknown>

        Parameters

        • type: string
        • id: string

        Returns T | null

        Merged view suitable for rendering; not a deep clone

    readEntitySnapshot: <T = Record<string, unknown>>(
        type: string,
        id: string,
    ) => EntitySnapshot<T & Record<string, unknown>> | null

    Sync-aware read path: canonical entity + patches + virtual sync metadata ($synced, $origin, $updatedAt).

    removeEntity: (type: string, id: string) => void

    Remove canonical entity, its patches, and its entityState. Does not remove the id from lists — use removeIdFromAllLists if needed.

    removeIdFromAllLists: (type: string, id: string) => void

    After deletes, keep every list consistent by removing an id everywhere it appears and decrementing total when tracked.

    replaceEntity: (type: string, id: string, data: Record<string, unknown>) => void

    Replace the canonical entity entirely (no merge). Use when the server returns a full snapshot and partial merge would leave stale keys behind.

    setEntityError: (type: string, id: string, error: string | null) => void

    Persist terminal fetch failure message and clear fetching — hooks surface error while leaving prior data if any.

    setEntityFetched: (type: string, id: string) => void

    Mark entity successfully loaded; clears error, fetching, stale, and updates lastFetched.

    setEntityFetching: (type: string, id: string, fetching: boolean) => void

    Reflect in-flight GET for a single entity (deduped fetches in the engine still flip this once per logical request).

    setEntityStale: (type: string, id: string, stale: boolean) => void

    Drive background revalidation: when true, hooks refetch while still showing cached readEntity data.

    setEntitySyncMetadata: (
        type: string,
        id: string,
        metadata: Partial<EntitySyncMetadata>,
    ) => void

    Merge sync metadata for one entity without polluting canonical server fields.

    setListError: (
        key: string,
        error: string | null,
        typed?: EntityError | null,
    ) => void

    Record list fetch failure; clears both fetching flags. The optional typed argument is the typed EntityError instance (used by 2.0 hooks); when omitted only the string error field is populated (back-compat with 1.x callers).

    setListFetching: (key: string, fetching: boolean) => void

    Initial or full list fetch in progress (not page-2+).

    setListFetchingMore: (key: string, fetchingMore: boolean) => void

    Pagination / “load more” in progress for the same list key.

    setListResult: (
        key: string,
        ids: string[],
        meta: Partial<
            Omit<
                ListState,
                "ids"
                | "isFetching"
                | "isFetchingMore"
                | "error"
                | "stale",
            >,
        >,
    ) => void

    Replace list ids and merge pagination meta after a primary list fetch (not load-more). Resets fetching flags and clears list error on success path (engine calls this after normalize).

    setListStale: (key: string, stale: boolean) => void

    Mark a list query stale so hooks can refetch without discarding current ids (stale-while-revalidate).

    syncMetadata: Record<string, EntitySyncMetadata>

    Optional sync/provenance state layered beside the canonical entity payload.

    unpatchEntity: (type: string, id: string, keys: string[]) => void

    Remove specific patch keys; other patch keys remain.

    upsertEntities: (
        type: string,
        entries: { data: Record<string, unknown>; id: string }[],
    ) => void

    Batch upsert for list endpoints — avoids N separate writes when hydrating many rows at once.

    Type Declaration

      • (type: string, entries: { data: Record<string, unknown>; id: string }[]): void

      • Parameters

        • type: string

          Entity kind

        • entries: { data: Record<string, unknown>; id: string }[]

          Pairs of id + partial/full payloads to merge

        Returns void

    upsertEntity: (type: string, id: string, data: Record<string, unknown>) => void

    Shallow-merge data into the canonical entity. Use when the API returns partial updates or normalized fragments.

    Type Declaration

      • (type: string, id: string, data: Record<string, unknown>): void

      • Parameters

        • type: string

          Entity kind

        • id: string

          Entity id

        • data: Record<string, unknown>

          Fields to merge into existing canonical data

        Returns void

    Settings
    Member Visibility

    On This Page
    Properties