@nesso-how/schema 0.1.0-alpha.40 → 0.2.0-beta.0

package/README.md

@@ -27,6 +27,15 @@ const doc: GraphDocument = deserialize(json)
 
 Vocabulary-specific serialization (e.g. Nesso Learning Vocabulary) lives in [`@nesso-how/vocab-learning`](../vocab-learning/README.md).
 
+## Compatibility
+
+`deserialize` requires an explicit envelope `version`. It replays sequential
+migrations for released older formats and rejects files from newer formats
+with `NewerGraphFormatError`.
+
+Envelope format `1` is the first protected beta baseline. Unversioned alpha
+documents are outside the compatibility contract.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,5 +1,13 @@
 /** Current on-disk graph document schema version. Bump only when the envelope shape changes. */
 export declare const GRAPH_FORMAT_VERSION: 1;
+export declare class NewerGraphFormatError extends Error {
+    readonly version: number;
+    constructor(version: number);
+}
+export declare class UnsupportedGraphFormatError extends Error {
+    readonly version: number | undefined;
+    constructor(version: number | undefined);
+}
 export interface GraphConcept<D extends Record<string, unknown> = Record<string, unknown>> {
     id: string;
     label: string;

package/dist/index.js

@@ -1,22 +1,81 @@
 // SPDX-License-Identifier: MIT
 /** Current on-disk graph document schema version. Bump only when the envelope shape changes. */
 export const GRAPH_FORMAT_VERSION = 1;
+const ENVELOPE_MIGRATIONS = {};
+export class NewerGraphFormatError extends Error {
+    version;
+    constructor(version) {
+        super(`This graph uses newer Nesso graph format version ${version}`);
+        this.name = 'NewerGraphFormatError';
+        this.version = version;
+    }
+}
+export class UnsupportedGraphFormatError extends Error {
+    version;
+    constructor(version) {
+        super(version === undefined
+            ? 'This graph does not declare a supported Nesso graph format version'
+            : `Unsupported Nesso graph format version: ${version}`);
+        this.name = 'UnsupportedGraphFormatError';
+        this.version = version;
+    }
+}
+function readEnvelopeVersion(document) {
+    const version = document.version;
+    // Stryker disable next-line ConditionalExpression: typeof guard subsumed by !Number.isInteger and version < 0 — equivalent mutant
+    if (typeof version !== 'number' || !Number.isInteger(version) || version < 0) {
+        throw new UnsupportedGraphFormatError(undefined);
+    }
+    return version;
+}
+function migrateEnvelope(document) {
+    let current = document;
+    let version = readEnvelopeVersion(current);
+    if (version > GRAPH_FORMAT_VERSION) {
+        throw new NewerGraphFormatError(version);
+    }
+    while (version < GRAPH_FORMAT_VERSION) {
+        const migrate = ENVELOPE_MIGRATIONS[version];
+        // Stryker disable next-line ConditionalExpression,EqualityOperator: ENVELOPE_MIGRATIONS is empty at baseline; migrate is always undefined — equivalent mutant
+        if (migrate === undefined) {
+            throw new UnsupportedGraphFormatError(version);
+        }
+        /* c8 ignore start */ // migration-step-advance is unreachable while ENVELOPE_MIGRATIONS is empty
+        // Stryker disable next-line all: migration-step-advance is unreachable while ENVELOPE_MIGRATIONS is empty
+        current = migrate(current);
+        // Stryker disable next-line all: unreachable
+        const nextVersion = readEnvelopeVersion(current);
+        // Stryker disable next-line all: unreachable
+        if (nextVersion !== version + 1) {
+            // Stryker disable next-line all: unreachable
+            throw new Error(`Envelope migration ${version} must produce version ${version + 1}`);
+        }
+        // Stryker disable next-line all: unreachable
+        version = nextVersion;
+        /* c8 ignore stop */
+    }
+    return current;
+}
 /** Serialize a graph document to JSON with keys in a stable, human-readable order. */
 export function serialize(doc) {
     const { vocabulary, id, updatedAt, name, concepts, relations, meta } = doc;
     return JSON.stringify({
         version: GRAPH_FORMAT_VERSION,
+        // Stryker disable next-line ConditionalExpression: JSON.stringify drops undefined values, so always spreading {vocabulary:undefined} is equivalent
         ...(vocabulary !== undefined && { vocabulary }),
+        // Stryker disable next-line ConditionalExpression: JSON.stringify drops undefined values, so always spreading {id:undefined} is equivalent
         ...(id !== undefined && { id }),
+        // Stryker disable next-line ConditionalExpression: JSON.stringify drops undefined values, so always spreading {updatedAt:undefined} is equivalent
         ...(updatedAt !== undefined && { updatedAt }),
         name,
         concepts,
         relations,
+        // Stryker disable next-line ConditionalExpression: JSON.stringify drops undefined values, so always spreading {meta:undefined} is equivalent
         ...(meta !== undefined && { meta }),
     }, null, 2);
 }
 function isRecord(value) {
-    return typeof value === 'object' && value !== null;
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 /**
  * Parse and structurally validate a graph document. Files are user-editable (and
@@ -25,12 +84,13 @@ function isRecord(value) {
  * then be re-persisted. Vocabulary-specific normalization is the caller's responsibility.
  */
 export function deserialize(json) {
-    const data = JSON.parse(json);
-    if (!isRecord(data) || !Array.isArray(data.concepts) || !Array.isArray(data.relations)) {
-        throw new Error('Invalid Nesso graph document: missing concepts or relations array');
+    const parsed = JSON.parse(json);
+    if (!isRecord(parsed)) {
+        throw new Error('Invalid Nesso graph document');
     }
-    if (typeof data.version === 'number' && data.version !== GRAPH_FORMAT_VERSION) {
-        throw new Error(`Unsupported Nesso graph document version: ${data.version}`);
+    const data = migrateEnvelope(parsed);
+    if (!Array.isArray(data.concepts) || !Array.isArray(data.relations)) {
+        throw new Error('Invalid Nesso graph document: missing concepts or relations array');
     }
     const rawConcepts = data.concepts;
     const concepts = rawConcepts.map((value, i) => {
@@ -38,8 +98,10 @@ export function deserialize(json) {
             typeof value.id !== 'string' ||
             value.id === '' ||
             typeof value.label !== 'string' ||
+            // Stryker disable next-line ConditionalExpression: typeof x guard subsumed by !Number.isFinite — equivalent mutant
             typeof value.x !== 'number' ||
             !Number.isFinite(value.x) ||
+            // Stryker disable next-line ConditionalExpression: typeof y guard subsumed by !Number.isFinite — equivalent mutant
             typeof value.y !== 'number' ||
             !Number.isFinite(value.y)) {
             throw new Error(`Invalid Nesso graph document: concept ${i} is missing a valid id, label, or position`);
@@ -82,9 +144,8 @@ export function deserialize(json) {
         vocabulary = { id: vocabValue.id, version: vocabValue.version };
     }
     let meta;
-    const metaValue = data.meta;
-    if (metaValue !== undefined) {
-        meta = metaValue;
+    if (isRecord(data.meta)) {
+        meta = data.meta;
     }
     return {
         version: GRAPH_FORMAT_VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nesso-how/schema",
-  "version": "0.1.0-alpha.40",
+  "version": "0.2.0-beta.0",
   "description": "Nesso knowledge graph document schema — JSON serialize/deserialize",
   "license": "MIT",
   "repository": {