@exellix/graphs-studio-layers-core 0.1.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@exellix/graphs-studio-layers-core",
+  "version": "0.1.0",
+  "description": "Graph authoring layer identity, Mongo document shapes, view transitions, and useGraphLayers hook for Graphs Studio.",
+  "type": "module",
+  "engines": {
+    "node": ">=20.19.0 || >=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/exellix/graphs-studio.git",
+    "directory": "packages/graphs-studio-layers-core"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./server": "./src/server/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "prepublishOnly": "node --test tests/graphs-studio-layers-core.test.mjs"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "react": "^19.2.7"
+  }
+}

package/src/index.js

@@ -0,0 +1,77 @@
+import { useCallback, useMemo, useState } from 'react';
+import { runLayerTransition, resolveInformationFlowForView } from './transitions.js';
+import { computeGraphVersionHash } from './layerIdentity.js';
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.graphId]
+ * @param {string | null} [opts.persistableSnapshotJson]
+ * @param {Record<string, unknown> | null} [opts.conceptLayer]
+ * @param {Record<string, unknown> | null} [opts.dataFlowLayer]
+ * @param {unknown} [opts.liveInformationFlow]
+ * @param {Record<string, unknown> | null} [opts.graphSnapshot]
+ * @param {Record<string, unknown> | null} [opts.graphAnalysis]
+ * @param {object} [opts.handlers]
+ */
+export function useGraphLayers(opts) {
+  const [syncState, setSyncState] = useState(
+    opts.dataFlowLayer?.syncState ?? opts.conceptLayer?.syncState ?? 'clean',
+  );
+
+  const graphVersionHash = useMemo(
+    () => computeGraphVersionHash(opts.persistableSnapshotJson),
+    [opts.persistableSnapshotJson],
+  );
+
+  const informationFlowView = useMemo(
+    () =>
+      resolveInformationFlowForView({
+        liveInformationFlow: opts.liveInformationFlow,
+        dataFlowLayer: opts.dataFlowLayer,
+        currentGraphHash: graphVersionHash,
+      }),
+    [opts.liveInformationFlow, opts.dataFlowLayer, graphVersionHash],
+  );
+
+  const transition = useCallback(
+    (direction) => {
+      const result = runLayerTransition(direction, {
+        graphId: opts.graphId,
+        graphVersionHash,
+        conceptLayer: opts.conceptLayer,
+        dataFlowLayer: opts.dataFlowLayer,
+        graphSnapshot: opts.graphSnapshot,
+        graphAnalysis: opts.graphAnalysis,
+        ...opts.handlers,
+      });
+      if (result.ok && result.dataFlowLayer?.syncState) {
+        setSyncState(result.dataFlowLayer.syncState);
+      }
+      return result;
+    },
+    [opts, graphVersionHash],
+  );
+
+  return {
+    graphVersionHash,
+    syncState,
+    setSyncState,
+    informationFlowView,
+    transition,
+  };
+}
+
+export {
+  computeGraphVersionHash,
+  buildLayerKey,
+  parseLayerKey,
+  nextSyncStateAfterEdit,
+  SYNC_STATES,
+} from './layerIdentity.js';
+export { runLayerTransition, resolveInformationFlowForView } from './transitions.js';
+export {
+  buildConceptLayerDocument,
+  buildDataFlowLayerDocument,
+  CONCEPT_LAYER_FORMAT,
+  DATA_FLOW_LAYER_FORMAT,
+} from './layerDocuments.js';

package/src/layerDocuments.js

@@ -0,0 +1,57 @@
+export const COLLECTION_GRAPH_CONCEPT_LAYERS = 'graph-concept-layers';
+export const COLLECTION_GRAPH_DATA_FLOW_LAYERS = 'graph-data-flow-layers';
+
+export const CONCEPT_LAYER_FORMAT = 'graphs-studio.concept-layer/v1';
+export const DATA_FLOW_LAYER_FORMAT = 'graphs-studio.data-flow-layer/v1';
+
+/**
+ * @param {object} input
+ * @param {string} input.graphId
+ * @param {string} input.graphVersionHash
+ * @param {Record<string, unknown>} input.concept
+ * @param {Record<string, unknown>} [input.studioConcept]
+ * @param {string} [input.sourceGraphHash]
+ * @param {string} [input.syncState]
+ * @param {string} [input.studioId]
+ */
+export function buildConceptLayerDocument(input) {
+  const { graphId, graphVersionHash } = input;
+  return {
+    layerKey: `${graphId}::${graphVersionHash}`,
+    graphId,
+    graphVersionHash,
+    formatVersion: CONCEPT_LAYER_FORMAT,
+    concept: input.concept,
+    studioConcept: input.studioConcept,
+    sourceGraphHash: input.sourceGraphHash ?? graphVersionHash,
+    syncState: input.syncState ?? 'clean',
+    studioId: input.studioId ?? 'default',
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.graphId
+ * @param {string} input.graphVersionHash
+ * @param {Record<string, unknown>} input.informationFlow
+ * @param {string} [input.focusState]
+ * @param {string} [input.sourceGraphHash]
+ * @param {string} [input.syncState]
+ * @param {string} [input.studioId]
+ */
+export function buildDataFlowLayerDocument(input) {
+  const { graphId, graphVersionHash } = input;
+  return {
+    layerKey: `${graphId}::${graphVersionHash}`,
+    graphId,
+    graphVersionHash,
+    formatVersion: DATA_FLOW_LAYER_FORMAT,
+    informationFlow: input.informationFlow,
+    focusState: input.focusState ?? 'graph',
+    sourceGraphHash: input.sourceGraphHash ?? graphVersionHash,
+    syncState: input.syncState ?? 'clean',
+    studioId: input.studioId ?? 'default',
+    updatedAt: new Date().toISOString(),
+  };
+}

package/src/layerIdentity.js

@@ -0,0 +1,52 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * SHA-256 hash of a persistable graph snapshot string.
+ * @param {string | null | undefined} snapshotJson
+ */
+export function computeGraphVersionHash(snapshotJson) {
+  if (!snapshotJson || typeof snapshotJson !== 'string') return null;
+  return createHash('sha256').update(snapshotJson, 'utf8').digest('hex').slice(0, 16);
+}
+
+/**
+ * @param {string} graphId
+ * @param {string} graphVersionHash
+ */
+export function buildLayerKey(graphId, graphVersionHash) {
+  return `${graphId}::${graphVersionHash}`;
+}
+
+/**
+ * @param {string} layerKey
+ */
+export function parseLayerKey(layerKey) {
+  const idx = layerKey.lastIndexOf('::');
+  if (idx <= 0) return null;
+  return {
+    graphId: layerKey.slice(0, idx),
+    graphVersionHash: layerKey.slice(idx + 2),
+  };
+}
+
+export const SYNC_STATES = /** @type {const} */ ([
+  'clean',
+  'concept-ahead',
+  'graph-ahead',
+  'layer-ahead',
+  'conflict',
+]);
+
+/** @typedef {(typeof SYNC_STATES)[number]} SyncState */
+
+/**
+ * @param {SyncState} current
+ * @param {'concept' | 'data-flow' | 'graph'} source
+ */
+export function nextSyncStateAfterEdit(current, source) {
+  if (current === 'conflict') return 'conflict';
+  if (source === 'concept') return 'concept-ahead';
+  if (source === 'data-flow') return 'layer-ahead';
+  if (source === 'graph') return 'graph-ahead';
+  return current;
+}

package/src/server/graphLayersStore.js

@@ -0,0 +1,67 @@
+import {
+  COLLECTION_GRAPH_CONCEPT_LAYERS,
+  COLLECTION_GRAPH_DATA_FLOW_LAYERS,
+  buildConceptLayerDocument,
+  buildDataFlowLayerDocument,
+} from '../layerDocuments.js';
+
+/**
+ * In-memory layer store for tests and server wiring.
+ */
+export class GraphLayersMemoryStore {
+  constructor() {
+    /** @type {Map<string, Record<string, unknown>>} */
+    this.conceptLayers = new Map();
+    /** @type {Map<string, Record<string, unknown>>} */
+    this.dataFlowLayers = new Map();
+  }
+
+  /** @param {Record<string, unknown>} doc */
+  upsertConceptLayer(doc) {
+    this.conceptLayers.set(doc.layerKey, doc);
+    return doc;
+  }
+
+  /** @param {string} layerKey */
+  getConceptLayer(layerKey) {
+    return this.conceptLayers.get(layerKey) ?? null;
+  }
+
+  /** @param {string} graphId */
+  getLatestConceptLayerForGraph(graphId) {
+    let latest = null;
+    for (const doc of this.conceptLayers.values()) {
+      if (doc.graphId !== graphId) continue;
+      if (!latest || String(doc.updatedAt) > String(latest.updatedAt)) latest = doc;
+    }
+    return latest;
+  }
+
+  /** @param {Record<string, unknown>} doc */
+  upsertDataFlowLayer(doc) {
+    this.dataFlowLayers.set(doc.layerKey, doc);
+    return doc;
+  }
+
+  /** @param {string} layerKey */
+  getDataFlowLayer(layerKey) {
+    return this.dataFlowLayers.get(layerKey) ?? null;
+  }
+
+  /** @param {string} graphId */
+  getLatestDataFlowLayerForGraph(graphId) {
+    let latest = null;
+    for (const doc of this.dataFlowLayers.values()) {
+      if (doc.graphId !== graphId) continue;
+      if (!latest || String(doc.updatedAt) > String(latest.updatedAt)) latest = doc;
+    }
+    return latest;
+  }
+}
+
+export {
+  COLLECTION_GRAPH_CONCEPT_LAYERS,
+  COLLECTION_GRAPH_DATA_FLOW_LAYERS,
+  buildConceptLayerDocument,
+  buildDataFlowLayerDocument,
+};

package/src/server/index.js

@@ -0,0 +1,7 @@
+export {
+  GraphLayersMemoryStore,
+  COLLECTION_GRAPH_CONCEPT_LAYERS,
+  COLLECTION_GRAPH_DATA_FLOW_LAYERS,
+  buildConceptLayerDocument,
+  buildDataFlowLayerDocument,
+} from './graphLayersStore.js';

package/src/transitions.js

@@ -0,0 +1,88 @@
+/** @typedef {'concept-to-graph' | 'graph-to-concept' | 'graph-to-data-flow' | 'data-flow-to-graph'} TransitionDirection */
+
+/**
+ * @param {TransitionDirection} direction
+ * @param {object} ctx
+ * @param {string} ctx.graphId
+ * @param {string} [ctx.graphVersionHash]
+ * @param {Record<string, unknown>} [ctx.conceptLayer]
+ * @param {Record<string, unknown>} [ctx.dataFlowLayer]
+ * @param {Record<string, unknown>} [ctx.graphSnapshot]
+ * @param {Record<string, unknown>} [ctx.graphAnalysis]
+ * @param {(input: unknown) => Record<string, unknown> | null} [ctx.buildInformationFlow]
+ * @param {(layer: unknown, graph: unknown) => Record<string, unknown>} [ctx.applyInformationFlowToGraph]
+ * @param {(graph: unknown) => Record<string, unknown>} [ctx.graphToConcept]
+ * @param {(concept: unknown) => Record<string, unknown>} [ctx.conceptToGraph]
+ */
+export function runLayerTransition(direction, ctx) {
+  switch (direction) {
+    case 'graph-to-concept': {
+      if (ctx.graphToConcept && ctx.graphSnapshot) {
+        return { ok: true, conceptLayer: ctx.graphToConcept(ctx.graphSnapshot) };
+      }
+      return { ok: false, error: 'graphToConcept handler missing' };
+    }
+    case 'concept-to-graph': {
+      if (ctx.conceptToGraph && ctx.conceptLayer) {
+        return { ok: true, graphPatch: ctx.conceptToGraph(ctx.conceptLayer) };
+      }
+      return { ok: false, error: 'conceptToGraph handler missing' };
+    }
+    case 'graph-to-data-flow': {
+      if (ctx.buildInformationFlow && ctx.graphSnapshot) {
+        const informationFlow = ctx.buildInformationFlow({
+          graph: ctx.graphSnapshot,
+          graphAnalysis: ctx.graphAnalysis,
+        });
+        if (!informationFlow) {
+          return { ok: false, error: 'Information flow could not be built from graph analysis' };
+        }
+        return {
+          ok: true,
+          dataFlowLayer: {
+            graphId: ctx.graphId,
+            graphVersionHash: ctx.graphVersionHash,
+            informationFlow,
+            syncState: 'clean',
+            sourceGraphHash: ctx.graphVersionHash,
+          },
+        };
+      }
+      return { ok: false, error: 'buildInformationFlow handler missing' };
+    }
+    case 'data-flow-to-graph': {
+      if (ctx.applyInformationFlowToGraph && ctx.dataFlowLayer && ctx.graphSnapshot) {
+        return {
+          ok: true,
+          graphPatch: ctx.applyInformationFlowToGraph(ctx.dataFlowLayer, ctx.graphSnapshot),
+        };
+      }
+      return { ok: false, error: 'applyInformationFlowToGraph handler missing' };
+    }
+    default:
+      return { ok: false, error: `Unknown direction: ${direction}` };
+  }
+}
+
+/**
+ * Resolve information flow for display: live build first, then persisted layer fallback.
+ * @param {object} opts
+ * @param {unknown} opts.liveInformationFlow
+ * @param {Record<string, unknown> | null | undefined} opts.dataFlowLayer
+ * @param {string | null | undefined} opts.currentGraphHash
+ */
+export function resolveInformationFlowForView(opts) {
+  if (opts.liveInformationFlow) {
+    return { informationFlow: opts.liveInformationFlow, stale: false };
+  }
+  const layer = opts.dataFlowLayer;
+  if (layer?.informationFlow) {
+    const stale = Boolean(
+      opts.currentGraphHash &&
+        layer.sourceGraphHash &&
+        layer.sourceGraphHash !== opts.currentGraphHash,
+    );
+    return { informationFlow: layer.informationFlow, stale, fromLayer: true };
+  }
+  return { informationFlow: null, stale: false };
+}