@prometheus-ags/prometheus-entity-management 1.0.0 → 1.1.0

package/dist/index.js

@@ -23,6 +23,11 @@ var EMPTY_ENTITY_STATE = {
   error: null,
   stale: false
 };
+var EMPTY_SYNC_METADATA = {
+  synced: true,
+  origin: "server",
+  updatedAt: null
+};
 var EMPTY_LIST_STATE = {
   ids: EMPTY_IDS,
   total: null,
@@ -41,6 +46,9 @@ var EMPTY_LIST_STATE = {
 function defaultEntityState() {
   return { ...EMPTY_ENTITY_STATE };
 }
+function defaultSyncMetadata() {
+  return { ...EMPTY_SYNC_METADATA };
+}
 function defaultListState() {
   return { ...EMPTY_LIST_STATE, ids: [] };
 }
@@ -53,24 +61,33 @@ var useGraphStore = zustand.create()(
       entities: {},
       patches: {},
       entityStates: {},
+      syncMetadata: {},
       lists: {},
       upsertEntity: (type, id, data) => set((s) => {
         if (!s.entities[type]) s.entities[type] = {};
         s.entities[type][id] = { ...s.entities[type][id] ?? {}, ...data };
+        const key = ek(type, id);
+        if (!s.syncMetadata[key]) s.syncMetadata[key] = defaultSyncMetadata();
       }),
       upsertEntities: (type, entries) => set((s) => {
         if (!s.entities[type]) s.entities[type] = {};
-        for (const { id, data } of entries)
+        for (const { id, data } of entries) {
           s.entities[type][id] = { ...s.entities[type][id] ?? {}, ...data };
+          const key = ek(type, id);
+          if (!s.syncMetadata[key]) s.syncMetadata[key] = defaultSyncMetadata();
+        }
       }),
       replaceEntity: (type, id, data) => set((s) => {
         if (!s.entities[type]) s.entities[type] = {};
         s.entities[type][id] = data;
+        const key = ek(type, id);
+        if (!s.syncMetadata[key]) s.syncMetadata[key] = defaultSyncMetadata();
       }),
       removeEntity: (type, id) => set((s) => {
         delete s.entities[type]?.[id];
         delete s.patches[type]?.[id];
         delete s.entityStates[ek(type, id)];
+        delete s.syncMetadata[ek(type, id)];
       }),
       patchEntity: (type, id, patch) => set((s) => {
         if (!s.patches[type]) s.patches[type] = {};
@@ -102,12 +119,20 @@ var useGraphStore = zustand.create()(
         s.entityStates[k].isFetching = false;
         s.entityStates[k].error = null;
         s.entityStates[k].stale = false;
+        s.syncMetadata[k] = { ...s.syncMetadata[k] ?? defaultSyncMetadata(), synced: true, origin: "server", updatedAt: Date.now() };
       }),
       setEntityStale: (type, id, stale) => set((s) => {
         const k = ek(type, id);
         if (!s.entityStates[k]) s.entityStates[k] = defaultEntityState();
         s.entityStates[k].stale = stale;
       }),
+      setEntitySyncMetadata: (type, id, metadata) => set((s) => {
+        const k = ek(type, id);
+        s.syncMetadata[k] = { ...s.syncMetadata[k] ?? defaultSyncMetadata(), ...metadata };
+      }),
+      clearEntitySyncMetadata: (type, id) => set((s) => {
+        delete s.syncMetadata[ek(type, id)];
+      }),
       setListResult: (key, ids, meta) => set((s) => {
         const ex = s.lists[key] ?? defaultListState();
         s.lists[key] = { ...ex, ...meta, ids, isFetching: false, isFetchingMore: false, error: null, stale: false, lastFetched: Date.now() };
@@ -179,11 +204,264 @@ var useGraphStore = zustand.create()(
         if (!base) return null;
         const patch = s.patches[type]?.[id];
         return patch ? { ...base, ...patch } : base;
+      },
+      readEntitySnapshot: (type, id) => {
+        const s = get();
+        const base = s.entities[type]?.[id];
+        if (!base) return null;
+        const patch = s.patches[type]?.[id];
+        const metadata = s.syncMetadata[ek(type, id)] ?? EMPTY_SYNC_METADATA;
+        return {
+          ...patch ? { ...base, ...patch } : base,
+          $synced: metadata.synced,
+          $origin: metadata.origin,
+          $updatedAt: metadata.updatedAt
+        };
       }
     }))
   )
 );
 
+// src/graph-query.ts
+function queryOnce(opts) {
+  const store = useGraphStore.getState();
+  const ids = resolveCandidateIds(store, opts);
+  let rows = ids.map((id) => store.readEntitySnapshot(opts.type, id)).filter((row) => row !== null);
+  if (opts.where) rows = rows.filter(opts.where);
+  if (opts.sort) rows = [...rows].sort(opts.sort);
+  const projected = rows.map((row) => applySelection(projectRow(row, opts.include, store), opts.select));
+  if (opts.id) return projected[0] ?? null;
+  return projected;
+}
+var selectGraph = queryOnce;
+function resolveCandidateIds(store, opts) {
+  if (opts.id) return [opts.id];
+  if (opts.ids) return opts.ids;
+  if (opts.listKey) return store.lists[opts.listKey]?.ids ?? [];
+  return Object.keys(store.entities[opts.type] ?? {});
+}
+function projectRow(row, include, store) {
+  if (!include) return row;
+  const projected = { ...row };
+  for (const [key, relation] of Object.entries(include)) {
+    const related = resolveRelation(row, relation, store);
+    projected[key] = related;
+  }
+  return projected;
+}
+function resolveRelation(entity, relation, store) {
+  const include = relation.include;
+  switch (relation.via.kind) {
+    case "field": {
+      const relatedId = entity[relation.via.field];
+      if (typeof relatedId !== "string") return null;
+      const related = store.readEntitySnapshot(relation.type, relatedId);
+      return related ? projectRow(related, include, store) : null;
+    }
+    case "array": {
+      const ids = entity[relation.via.field];
+      if (!Array.isArray(ids)) return [];
+      return ids.map((id) => typeof id === "string" ? store.readEntitySnapshot(relation.type, id) : null).filter((row) => row !== null).map((row) => projectRow(row, include, store));
+    }
+    case "list": {
+      const key = typeof relation.via.key === "function" ? relation.via.key(entity) : relation.via.key;
+      if (!key) return [];
+      const ids = store.lists[key]?.ids ?? [];
+      return ids.map((id) => store.readEntitySnapshot(relation.type, id)).filter((row) => row !== null).map((row) => projectRow(row, include, store));
+    }
+    case "resolver": {
+      const resolved = relation.via.resolve(entity, store);
+      if (Array.isArray(resolved)) {
+        return resolved.map((id) => store.readEntitySnapshot(relation.type, id)).filter((row) => row !== null).map((row) => projectRow(row, include, store));
+      }
+      if (typeof resolved !== "string") return null;
+      const related = store.readEntitySnapshot(relation.type, resolved);
+      return related ? projectRow(related, include, store) : null;
+    }
+  }
+}
+function applySelection(row, select) {
+  if (!select) return row;
+  if (typeof select === "function") {
+    const result = select(row);
+    return result && typeof result === "object" ? result : { value: result };
+  }
+  const picked = {};
+  for (const key of select) {
+    if (key in row) picked[key] = row[key];
+  }
+  return picked;
+}
+
+// src/graph-actions.ts
+function createGraphTransaction() {
+  const baseline = cloneGraphData();
+  let closed = false;
+  const tx = {
+    upsertEntity(type, id, data) {
+      useGraphStore.getState().upsertEntity(type, id, data);
+      return tx;
+    },
+    replaceEntity(type, id, data) {
+      useGraphStore.getState().replaceEntity(type, id, data);
+      return tx;
+    },
+    removeEntity(type, id) {
+      useGraphStore.getState().removeEntity(type, id);
+      return tx;
+    },
+    patchEntity(type, id, patch) {
+      useGraphStore.getState().patchEntity(type, id, patch);
+      return tx;
+    },
+    clearPatch(type, id) {
+      useGraphStore.getState().clearPatch(type, id);
+      return tx;
+    },
+    insertIdInList(key, id, position) {
+      useGraphStore.getState().insertIdInList(key, id, position);
+      return tx;
+    },
+    removeIdFromAllLists(type, id) {
+      useGraphStore.getState().removeIdFromAllLists(type, id);
+      return tx;
+    },
+    setEntitySyncMetadata(type, id, metadata) {
+      useGraphStore.getState().setEntitySyncMetadata(type, id, metadata);
+      return tx;
+    },
+    markEntityPending(type, id, origin = "optimistic") {
+      useGraphStore.getState().setEntitySyncMetadata(type, id, {
+        synced: false,
+        origin,
+        updatedAt: Date.now()
+      });
+      return tx;
+    },
+    markEntitySynced(type, id, origin = "server") {
+      useGraphStore.getState().setEntitySyncMetadata(type, id, {
+        synced: true,
+        origin,
+        updatedAt: Date.now()
+      });
+      return tx;
+    },
+    commit() {
+      closed = true;
+    },
+    rollback() {
+      if (closed) return;
+      useGraphStore.setState(cloneGraphData(baseline));
+      closed = true;
+    },
+    snapshot() {
+      return cloneGraphData();
+    }
+  };
+  return tx;
+}
+function createGraphAction(opts) {
+  return async (input) => {
+    const tx = createGraphTransaction();
+    try {
+      opts.optimistic?.(tx, input);
+      const result = await opts.run(tx, input);
+      opts.onSuccess?.(result, input, tx);
+      tx.commit();
+      return result;
+    } catch (error) {
+      tx.rollback();
+      const normalized = error instanceof Error ? error : new Error(String(error));
+      opts.onError?.(normalized, input);
+      throw normalized;
+    }
+  };
+}
+function cloneGraphData(source = useGraphStore.getState()) {
+  return {
+    entities: structuredClone(source.entities),
+    patches: structuredClone(source.patches),
+    entityStates: structuredClone(source.entityStates),
+    syncMetadata: structuredClone(source.syncMetadata),
+    lists: structuredClone(source.lists)
+  };
+}
+
+// src/graph-effects.ts
+function createGraphEffect(opts) {
+  const getKey = opts.getKey ?? defaultGetKey;
+  const isEqual = opts.isEqual ?? defaultIsEqual;
+  let initialized = false;
+  let previous = /* @__PURE__ */ new Map();
+  const evaluate = () => {
+    const nextValues = normalizeQueryResult(opts.query());
+    const next = /* @__PURE__ */ new Map();
+    nextValues.forEach((value, index) => {
+      next.set(getKey(value, index), value);
+    });
+    if (!initialized) {
+      initialized = true;
+      previous = next;
+      if (opts.skipInitial) return;
+    }
+    for (const [key, value] of next.entries()) {
+      const previousValue = previous.get(key);
+      if (previousValue === void 0) {
+        opts.onEnter?.({ key, value });
+        continue;
+      }
+      if (!isEqual(previousValue, value)) {
+        opts.onUpdate?.({ key, value, previousValue });
+      }
+    }
+    for (const [key, previousValue] of previous.entries()) {
+      if (!next.has(key)) opts.onExit?.({ key, previousValue });
+    }
+    previous = next;
+  };
+  evaluate();
+  const unsubscribe = useGraphStore.subscribe(() => {
+    evaluate();
+  });
+  return {
+    dispose: () => {
+      unsubscribe();
+    }
+  };
+}
+function normalizeQueryResult(value) {
+  if (value == null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+function defaultGetKey(value, index) {
+  if (value && typeof value === "object") {
+    const record = value;
+    if (typeof record.id === "string") return record.id;
+    if (typeof record.$key === "string") return record.$key;
+  }
+  return String(index);
+}
+function defaultIsEqual(previousValue, nextValue) {
+  return JSON.stringify(previousValue) === JSON.stringify(nextValue);
+}
+
+// src/ai-interop.ts
+function exportGraphSnapshot(opts) {
+  const payload = {
+    scope: opts.scope,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    data: opts.data
+  };
+  return JSON.stringify(payload, null, opts.pretty === false ? 0 : 2);
+}
+function createGraphTool(handler) {
+  return (input) => handler(input, {
+    store: useGraphStore.getState(),
+    queryOnce,
+    exportGraphSnapshot
+  });
+}
+
 // src/engine.ts
 function serializeKey(key) {
   return JSON.stringify(key, (_, v) => v && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort()) : v);
@@ -451,10 +729,7 @@ function useEntity(opts) {
   normalizeRef.current = opts.normalize;
   const data = zustand.useStore(useGraphStore, shallow.useShallow((state) => {
     if (!id) return null;
-    const base = state.entities[type]?.[id];
-    if (!base) return null;
-    const patch = state.patches[type]?.[id];
-    return patch ? { ...base, ...patch } : base;
+    return state.readEntitySnapshot(type, id);
   }));
   const entityState = zustand.useStore(useGraphStore, React5.useCallback(
     (state) => state.entityStates[`${type}:${id}`] ?? EMPTY_ENTITY_STATE,
@@ -492,12 +767,7 @@ function useEntityList(opts) {
     useGraphStore,
     shallow.useShallow((state) => {
       const ids = state.lists[key]?.ids ?? EMPTY_IDS;
-      return ids.map((id) => {
-        const base = state.entities[type]?.[id];
-        if (!base) return null;
-        const patch = state.patches[type]?.[id];
-        return patch ? { ...base, ...patch } : base;
-      }).filter((x) => x !== null);
+      return ids.map((id) => state.readEntitySnapshot(type, id)).filter((x) => x !== null);
     })
   );
   const doFetch = React5.useCallback((params = {}) => {
@@ -534,18 +804,28 @@ function useEntityMutation(opts) {
         const { id, patch } = opt;
         const store = useGraphStore.getState();
         const previous = { ...store.patches[type]?.[id] };
+        const previousSync = store.syncMetadata[`${type}:${id}`];
         store.patchEntity(type, id, patch);
-        rollback = () => Object.keys(previous).length > 0 ? useGraphStore.getState().patchEntity(type, id, previous) : useGraphStore.getState().clearPatch(type, id);
+        store.setEntitySyncMetadata(type, id, { synced: false, origin: "optimistic", updatedAt: Date.now() });
+        rollback = () => {
+          const currentStore = useGraphStore.getState();
+          if (Object.keys(previous).length > 0) currentStore.patchEntity(type, id, previous);
+          else currentStore.clearPatch(type, id);
+          if (previousSync) currentStore.setEntitySyncMetadata(type, id, previousSync);
+          else currentStore.clearEntitySyncMetadata(type, id);
+        };
       }
     }
     try {
       const result = await apiFn(input);
       if (normalize) {
         const { id, data } = normalize(result, input);
-        useGraphStore.getState().upsertEntity(type, id, data);
+        const store = useGraphStore.getState();
+        store.upsertEntity(type, id, data);
+        store.setEntitySyncMetadata(type, id, { synced: true, origin: "server", updatedAt: Date.now() });
         if (optimistic) {
           const opt = optimistic(input);
-          if (opt) useGraphStore.getState().clearPatch(type, opt.id);
+          if (opt) store.clearPatch(type, opt.id);
         }
       }
       if (invalidateLists) for (const k of invalidateLists) useGraphStore.getState().invalidateLists(k);
@@ -1047,12 +1327,7 @@ function useEntityView(opts) {
     shallow.useShallow((state) => {
       const list = state.lists[baseKey] ?? EMPTY_LIST_STATE;
       const sourceIds = completenessMode !== "remote" && remoteResultKey ? state.lists[remoteResultKey]?.ids ?? EMPTY_IDS : list.ids;
-      const getEntity = (id) => {
-        const base = state.entities[type]?.[id];
-        if (!base) return null;
-        const patch = state.patches[type]?.[id];
-        return patch ? { ...base, ...patch } : base;
-      };
+      const getEntity = (id) => state.readEntitySnapshot(type, id);
       return applyView(
         sourceIds,
         getEntity,
@@ -1065,12 +1340,7 @@ function useEntityView(opts) {
   const items = zustand.useStore(
     useGraphStore,
     shallow.useShallow(
-      (state) => localViewIds.map((id) => {
-        const base = state.entities[type]?.[id];
-        if (!base) return null;
-        const patch = state.patches[type]?.[id];
-        return patch ? { ...base, ...patch } : base;
-      }).filter((item) => item !== null)
+      (state) => localViewIds.map((id) => state.readEntitySnapshot(type, id)).filter((item) => item !== null)
     )
   );
   const fireRemoteFetch = React5.useCallback(async (view, cursor) => {
@@ -1125,17 +1395,11 @@ function useEntityView(opts) {
         const isPresent = id in newEntities;
         if (!isPresent) continue;
         const entity = newEntities[id];
-        const patch = store.patches[type]?.[id];
-        const merged = patch ? { ...entity, ...patch } : entity;
+        const merged = store.readEntitySnapshot(type, id) ?? entity;
         const matches = (!view.filter || matchesFilter(merged, view.filter)) && (!view.search?.query || matchesSearch(merged, view.search.query, view.search.fields));
         if (matches && !list.ids.includes(id)) {
           if (view.sort && view.sort.length > 0) {
-            const idx = findInsertionIndex(merged, list.ids, (eid) => {
-              const b = store.entities[type]?.[eid];
-              if (!b) return null;
-              const p = store.patches[type]?.[eid];
-              return p ? { ...b, ...p } : b;
-            }, view.sort);
+            const idx = findInsertionIndex(merged, list.ids, (eid) => store.readEntitySnapshot(type, eid), view.sort);
             store.insertIdInList(baseKey, id, idx);
           } else store.insertIdInList(baseKey, id, "start");
         }
@@ -1313,25 +1577,33 @@ function useEntityCRUD(opts) {
   }, [resetBuffer, selectedId]);
   const applyOptimistic = React5.useCallback(() => {
     if (!selectedId) return;
-    useGraphStore.getState().patchEntity(type, selectedId, editBuffer);
+    const store = useGraphStore.getState();
+    store.patchEntity(type, selectedId, editBuffer);
+    store.setEntitySyncMetadata(type, selectedId, { synced: false, origin: "optimistic", updatedAt: Date.now() });
   }, [type, selectedId, editBuffer]);
   const save = React5.useCallback(async () => {
     if (!selectedId || !onUpdate) return null;
     setIsSaving(true);
     setSaveError(null);
-    const previous = useGraphStore.getState().readEntity(type, selectedId);
-    useGraphStore.getState().upsertEntity(type, selectedId, editBuffer);
+    const store = useGraphStore.getState();
+    const previous = store.readEntity(type, selectedId);
+    const previousSync = store.syncMetadata[`${type}:${selectedId}`];
+    store.upsertEntity(type, selectedId, editBuffer);
+    store.setEntitySyncMetadata(type, selectedId, { synced: false, origin: "optimistic", updatedAt: Date.now() });
     try {
       const result = await onUpdate(selectedId, editBuffer);
       const { id, data } = normalize(result);
-      useGraphStore.getState().replaceEntity(type, id, data);
-      useGraphStore.getState().clearPatch(type, id);
+      store.replaceEntity(type, id, data);
+      store.clearPatch(type, id);
+      store.setEntitySyncMetadata(type, id, { synced: true, origin: "server", updatedAt: Date.now() });
       cascadeInvalidation({ type, id: selectedId, previous, next: data, op: "update" });
       setMode("detail");
       optsRef.current.onUpdateSuccess?.(result);
       return result;
     } catch (err) {
-      if (previous) useGraphStore.getState().replaceEntity(type, selectedId, previous);
+      if (previous) store.replaceEntity(type, selectedId, previous);
+      if (previousSync) store.setEntitySyncMetadata(type, selectedId, previousSync);
+      else store.clearEntitySyncMetadata(type, selectedId);
       const error = err instanceof Error ? err : new Error(String(err));
       setSaveError(error.message);
       optsRef.current.onError?.("update", error);
@@ -1362,15 +1634,17 @@ function useEntityCRUD(opts) {
     setCreateError(null);
     const tempId = `__temp__${Date.now()}`;
     const optimisticData = { ...createBuffer, id: tempId, _optimistic: true };
-    useGraphStore.getState().upsertEntity(type, tempId, optimisticData);
-    useGraphStore.getState().insertIdInList(serializeKey(listQueryKey), tempId, "start");
+    const store = useGraphStore.getState();
+    store.upsertEntity(type, tempId, optimisticData);
+    store.setEntitySyncMetadata(type, tempId, { synced: false, origin: "optimistic", updatedAt: Date.now() });
+    store.insertIdInList(serializeKey(listQueryKey), tempId, "start");
     try {
       const result = await onCreate(createBuffer);
       const { id: realId, data } = normalize(result);
-      useGraphStore.getState().removeEntity(type, tempId);
-      useGraphStore.getState().upsertEntity(type, realId, data);
-      useGraphStore.getState().setEntityFetched(type, realId);
-      const store = useGraphStore.getState();
+      store.removeEntity(type, tempId);
+      store.upsertEntity(type, realId, data);
+      store.setEntityFetched(type, realId);
+      store.setEntitySyncMetadata(type, realId, { synced: true, origin: "server", updatedAt: Date.now() });
       for (const key of Object.keys(store.lists)) {
         const list2 = store.lists[key];
         const idx = list2.ids.indexOf(tempId);
@@ -1388,8 +1662,8 @@ function useEntityCRUD(opts) {
       optsRef.current.onCreateSuccess?.(result);
       return result;
     } catch (err) {
-      useGraphStore.getState().removeEntity(type, tempId);
-      useGraphStore.getState().removeIdFromAllLists(type, tempId);
+      store.removeEntity(type, tempId);
+      store.removeIdFromAllLists(type, tempId);
       const error = err instanceof Error ? err : new Error(String(err));
       setCreateError(error.message);
       optsRef.current.onError?.("create", error);
@@ -2193,10 +2467,7 @@ function useGQLEntity(opts) {
   optsRef.current = opts;
   const data = zustand.useStore(useGraphStore, shallow.useShallow((s) => {
     if (!id) return null;
-    const base = s.entities[type]?.[id];
-    if (!base) return null;
-    const patch = s.patches[type]?.[id];
-    return patch ? { ...base, ...patch } : base;
+    return s.readEntitySnapshot(type, id);
   }));
   const entityState = zustand.useStore(useGraphStore, React5.useCallback(
     (s) => s.entityStates[`${type}:${id}`] ?? EMPTY_ENTITY_STATE,
@@ -2242,12 +2513,7 @@ function useGQLList(opts) {
     useGraphStore,
     shallow.useShallow((s) => {
       const ids = s.lists[key]?.ids ?? EMPTY_IDS;
-      return ids.map((id) => {
-        const base = s.entities[type]?.[id];
-        if (!base) return null;
-        const p = s.patches[type]?.[id];
-        return p ? { ...base, ...p } : base;
-      }).filter((x) => x !== null);
+      return ids.map((id) => s.readEntitySnapshot(type, id)).filter((x) => x !== null);
     })
   );
   const doFetch = React5.useCallback((cursor, append = false) => {
@@ -7978,7 +8244,11 @@ exports.configureEngine = configureEngine;
 exports.createConvexAdapter = createConvexAdapter;
 exports.createElectricAdapter = createElectricAdapter;
 exports.createGQLClient = createGQLClient;
+exports.createGraphAction = createGraphAction;
+exports.createGraphEffect = createGraphEffect;
 exports.createGraphQLSubscriptionAdapter = createGraphQLSubscriptionAdapter;
+exports.createGraphTool = createGraphTool;
+exports.createGraphTransaction = createGraphTransaction;
 exports.createPresetStore = createPresetStore;
 exports.createPrismaEntityConfig = createPrismaEntityConfig;
 exports.createRow = createRow;
@@ -7991,6 +8261,7 @@ exports.deleteAction = deleteAction;
 exports.editAction = editAction;
 exports.enumColumn = enumColumn;
 exports.executeGQL = executeGQL;
+exports.exportGraphSnapshot = exportGraphSnapshot;
 exports.fetchEntity = fetchEntity;
 exports.fetchList = fetchList;
 exports.flattenClauses = flattenClauses;
@@ -8019,9 +8290,11 @@ exports.pureEnumColumn = enumColumn2;
 exports.pureNumberColumn = numberColumn2;
 exports.pureSelectionColumn = selectionColumn2;
 exports.pureTextColumn = textColumn2;
+exports.queryOnce = queryOnce;
 exports.readRelations = readRelations;
 exports.registerSchema = registerSchema;
 exports.resetRealtimeManager = resetRealtimeManager;
+exports.selectGraph = selectGraph;
 exports.selectionColumn = selectionColumn;
 exports.serializeKey = serializeKey;
 exports.startGarbageCollector = startGarbageCollector;