@nesso-how/formats 0.1.0-alpha.33 → 0.1.0-alpha.34

package/dist/index.d.ts

@@ -1,25 +1,38 @@
 import type { Node, Edge } from '@xyflow/react';
-import type { ConceptNodeData, GraphDisplaySettings } from '@nesso-how/types';
-export interface NessoGraphFile {
+import type { GraphDisplaySettings } from '@nesso-how/types';
+/** Current on-disk graph file schema version. Bump only when the envelope shape changes. */
+export declare const GRAPH_FORMAT_VERSION: 1;
+export interface NessoGraphFile<D extends Record<string, unknown> = Record<string, unknown>> {
+    /** File format version — always {@link GRAPH_FORMAT_VERSION} for the current schema. */
+    version: typeof GRAPH_FORMAT_VERSION;
+    /**
+     * Vocabulary this graph was built with: its id (e.g. `@nesso-how/vocab-learning`)
+     * and normative version. Opaque to formats, which only round-trips the reference.
+     */
+    vocabulary?: {
+        id: string;
+        version: string;
+    };
     /** Internal graph id (desktop sync); omitted in manual exports. */
     id?: string;
     /** Last save time (Unix ms); desktop sync metadata. */
     updatedAt?: number;
     name: string;
-    nodes: Node<ConceptNodeData>[];
+    nodes: Node<D>[];
     edges: Edge[];
     display?: Partial<GraphDisplaySettings>;
 }
-export declare function serializeGraph(file: NessoGraphFile): string;
+/** Graph payload for {@link serializeGraph} — format version is injected by the serializer. */
+export type NessoGraphFileInput<D extends Record<string, unknown> = Record<string, unknown>> = Omit<NessoGraphFile<D>, 'version'>;
+/** Serialize a graph to JSON with keys in a stable, human-readable order. */
+export declare function serializeGraph<D extends Record<string, unknown>>(file: NessoGraphFileInput<D>): string;
 /**
  * Parse and structurally validate a graph file. Files are user-editable (and
  * importable from anywhere), so each element is checked before it can reach
  * the store: a node without a valid id/position crashes the canvas and would
- * then be re-persisted. Partial node data (e.g. hand-written files with only
- * `text`) is normalized with fresh review fields.
+ * then be re-persisted. Vocabulary-specific normalization (e.g. private params)
+ * is the caller's responsibility.
  */
-export declare function deserializeGraph(json: string): NessoGraphFile;
-/** Strip personal FSRS / review history for shareable graph export. Keeps text, elaboration, layout. */
-export declare function nodesForGraphShareExport(nodes: Node<ConceptNodeData>[]): Node<ConceptNodeData>[];
-/** Reset review fields on import so shared files never restore someone else's scheduling. */
-export declare function nodesFromGraphShareImport(nodes: Node<ConceptNodeData>[]): Node<ConceptNodeData>[];
+export declare function deserializeGraph<D extends Record<string, unknown> = Record<string, unknown>>(json: string): NessoGraphFile<D>;
+/** Overwrite private node params with vocabulary defaults (e.g. for share export/import). */
+export declare function stripPrivateNodeParams<D extends Record<string, unknown>>(nodes: Node<D>[], privateDefaults: Partial<D>): Node<D>[];

package/dist/index.js

@@ -1,6 +1,18 @@
-import { defaultConceptReviewFields } from '@nesso-how/types';
+/** Current on-disk graph file schema version. Bump only when the envelope shape changes. */
+export const GRAPH_FORMAT_VERSION = 1;
+/** Serialize a graph to JSON with keys in a stable, human-readable order. */
 export function serializeGraph(file) {
-    return JSON.stringify(file, null, 2);
+    const { vocabulary, id, updatedAt, name, nodes, edges, display } = file;
+    return JSON.stringify({
+        version: GRAPH_FORMAT_VERSION,
+        ...(vocabulary !== undefined && { vocabulary }),
+        ...(id !== undefined && { id }),
+        ...(updatedAt !== undefined && { updatedAt }),
+        name,
+        nodes,
+        edges,
+        ...(display !== undefined && { display }),
+    }, null, 2);
 }
 function asRecord(value) {
     return typeof value === 'object' && value !== null ? value : null;
@@ -9,8 +21,8 @@ function asRecord(value) {
  * Parse and structurally validate a graph file. Files are user-editable (and
  * importable from anywhere), so each element is checked before it can reach
  * the store: a node without a valid id/position crashes the canvas and would
- * then be re-persisted. Partial node data (e.g. hand-written files with only
- * `text`) is normalized with fresh review fields.
+ * then be re-persisted. Vocabulary-specific normalization (e.g. private params)
+ * is the caller's responsibility.
  */
 export function deserializeGraph(json) {
     const data = JSON.parse(json);
@@ -18,7 +30,9 @@ export function deserializeGraph(json) {
     if (!root || !Array.isArray(root.nodes) || !Array.isArray(root.edges)) {
         throw new Error('Invalid Nesso graph file: missing nodes or edges array');
     }
-    const review = defaultConceptReviewFields();
+    if (typeof root.version === 'number' && root.version !== GRAPH_FORMAT_VERSION) {
+        throw new Error(`Unsupported Nesso graph file version: ${root.version}`);
+    }
     const nodes = root.nodes.map((value, i) => {
         const node = asRecord(value);
         const pos = node ? asRecord(node.position) : null;
@@ -32,11 +46,7 @@ export function deserializeGraph(json) {
             !Number.isFinite(pos.y)) {
             throw new Error(`Invalid Nesso graph file: node ${i} is missing a valid id or position`);
         }
-        const d = asRecord(node.data) ?? {};
-        return {
-            ...node,
-            data: { ...review, ...d, text: typeof d.text === 'string' ? d.text : '' },
-        };
+        return node;
     });
     const edges = root.edges.map((value, i) => {
         const edge = asRecord(value);
@@ -48,24 +58,17 @@ export function deserializeGraph(json) {
         }
         return edge;
     });
-    return { ...root, nodes, edges };
-}
-/** Strip personal FSRS / review history for shareable graph export. Keeps text, elaboration, layout. */
-export function nodesForGraphShareExport(nodes) {
-    const review = defaultConceptReviewFields();
-    return nodes.map((node) => {
-        const { text, elaboration } = node.data ?? { text: '' };
-        return {
-            ...node,
-            data: {
-                text: text ?? '',
-                ...(elaboration ? { elaboration } : {}),
-                ...review,
-            },
-        };
-    });
+    return {
+        ...root,
+        version: GRAPH_FORMAT_VERSION,
+        nodes,
+        edges,
+    };
 }
-/** Reset review fields on import so shared files never restore someone else's scheduling. */
-export function nodesFromGraphShareImport(nodes) {
-    return nodesForGraphShareExport(nodes);
+/** Overwrite private node params with vocabulary defaults (e.g. for share export/import). */
+export function stripPrivateNodeParams(nodes, privateDefaults) {
+    return nodes.map((node) => ({
+        ...node,
+        data: { ...node.data, ...privateDefaults },
+    }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nesso-how/formats",
-  "version": "0.1.0-alpha.33",
+  "version": "0.1.0-alpha.34",
   "description": "Nesso graph serialization formats — JSON serialize/deserialize",
   "license": "MIT",
   "repository": {
@@ -22,7 +22,7 @@
     }
   },
   "dependencies": {
-    "@nesso-how/types": "0.1.0-alpha.33"
+    "@nesso-how/types": "0.1.0-alpha.34"
   },
   "peerDependencies": {
     "@xyflow/react": "^12.6.4"