@grafema/util 0.3.21 → 0.3.23

package/src/storage/backends/RFDBServerBackend.ts

@@ -21,6 +21,7 @@
 import { RFDBClient, type BatchHandle } from '@grafema/rfdb-client';
 import type { ChildProcess } from 'child_process';
 import { join, dirname } from 'path';
+import { createHash } from 'crypto';
 
 import type { WireNode, WireEdge, FieldDeclaration, CommitDelta, AttrQuery as RFDBAttrQuery, DatalogExplainResult, ServerStats, CypherResult } from '@grafema/types';
 import type { NodeType, EdgeType } from '@grafema/types';
@@ -119,11 +120,21 @@ export class RFDBServerBackend {
     this.silent = options.silent ?? false;
     this._clientName = options.clientName ?? 'core';
     // Default socket path: next to the database in .grafema folder
-    // This ensures each project has its own socket, avoiding conflicts
+    // This ensures each project has its own socket, avoiding conflicts.
+    // Unix socket paths have a hard limit (SUN_LEN: 104 on macOS, 108 on Linux).
+    // If the project path is too deep, fall back to /tmp with a hash to avoid conflicts.
     if (options.socketPath) {
       this.socketPath = options.socketPath;
     } else if (this.dbPath) {
-      this.socketPath = join(dirname(this.dbPath), 'rfdb.sock');
+      const localSocket = join(dirname(this.dbPath), 'rfdb.sock');
+      const SUN_LEN = process.platform === 'darwin' ? 104 : 108;
+      if (Buffer.byteLength(localSocket) < SUN_LEN) {
+        this.socketPath = localSocket;
+      } else {
+        // Hash the project path to create a unique but short socket path
+        const hash = createHash('md5').update(dirname(this.dbPath)).digest('hex').slice(0, 12);
+        this.socketPath = join('/tmp', `grafema-${hash}.sock`);
+      }
     } else {
       this.socketPath = '/tmp/rfdb.sock'; // fallback, not recommended
     }
@@ -283,6 +294,22 @@ export class RFDBServerBackend {
     this.serverProcess = null;
   }
 
+  /**
+   * Shutdown the RFDB server gracefully (flush + exit).
+   * Use before operations that invalidate the socket (e.g. clear + restart).
+   */
+  async shutdownServer(): Promise<void> {
+    if (!this.client) return;
+    try {
+      await this.client.shutdown();
+    } catch {
+      // Server may already be gone
+    }
+    this.client = null;
+    this.connected = false;
+    this.serverProcess = null;
+  }
+
   /**
    * Clear the database
    */
@@ -326,6 +353,23 @@ export class RFDBServerBackend {
     if (!this.client) throw new Error('Not connected');
     if (!nodes.length) return;
 
+    // Validate required fields
+    for (let i = 0; i < nodes.length; i++) {
+      const n = nodes[i];
+      if (!n.id) {
+        throw new Error(
+          `addNodes: node at index ${i} is missing required 'id' field. ` +
+          `Got keys: [${Object.keys(n).join(', ')}]`
+        );
+      }
+      if (!n.type && !n.nodeType && !n.node_type) {
+        throw new Error(
+          `addNodes: node '${n.id}' is missing type. ` +
+          `Provide one of: type, nodeType, or node_type`
+        );
+      }
+    }
+
     const useV3 = this.protocolVersion >= 3;
     const wireNodes: WireNode[] = nodes.map(n => {
       // Extract metadata from node
@@ -364,9 +408,43 @@ export class RFDBServerBackend {
     if (!this.client) throw new Error('Not connected');
     if (!edges.length) return;
 
+    // Validate required fields
+    if (!skipValidation) {
+      for (let i = 0; i < edges.length; i++) {
+        const e = edges[i];
+        // Check for src/dst (required)
+        if (!e.src) {
+          // Common mistake: using 'source'/'target' instead of 'src'/'dst'
+          const hint = (e as Record<string, unknown>).source
+            ? ` Did you mean 'src'? Found 'source' = '${(e as Record<string, unknown>).source}'`
+            : '';
+          throw new Error(
+            `addEdges: edge at index ${i} is missing required 'src' field.${hint} ` +
+            `Got keys: [${Object.keys(e).join(', ')}]`
+          );
+        }
+        if (!e.dst) {
+          const hint = (e as Record<string, unknown>).target
+            ? ` Did you mean 'dst'? Found 'target' = '${(e as Record<string, unknown>).target}'`
+            : '';
+          throw new Error(
+            `addEdges: edge at index ${i} is missing required 'dst' field.${hint} ` +
+            `Got keys: [${Object.keys(e).join(', ')}]`
+          );
+        }
+        // Check for edge type
+        if (!e.edgeType && !e.edge_type && !(e as Record<string, unknown>).etype && !e.type) {
+          throw new Error(
+            `addEdges: edge ${e.src} → ${e.dst} is missing edge type. ` +
+            `Provide one of: edgeType, edge_type, etype, or type`
+          );
+        }
+      }
+    }
+
     // Track edge types
     for (const e of edges) {
-      const edgeType = e.edgeType || e.edge_type || e.etype || e.type;
+      const edgeType = e.edgeType || e.edge_type || (e as Record<string, unknown>).etype as string || e.type;
       if (typeof edgeType === 'string') this.edgeTypes.add(edgeType);
     }
 

package/src/version.ts

@@ -26,3 +26,42 @@ export function getSchemaVersion(version: string): string {
   const base = version.split('-')[0];
   return base;
 }
+
+export interface ParsedVersion {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+/**
+ * Parse a version string into structured major.minor.patch components.
+ * Strips pre-release tags before parsing.
+ *
+ * @param version - Version string (e.g., "0.2.5-beta")
+ * @returns Parsed version or null if the string is not a valid version
+ */
+export function parseVersion(version: string): ParsedVersion | null {
+  const base = getSchemaVersion(version);
+  const parts = base.split('.');
+  if (parts.length < 2) return null;
+  const major = parseInt(parts[0], 10);
+  const minor = parseInt(parts[1], 10);
+  const patch = parts.length >= 3 ? parseInt(parts[2], 10) : 0;
+  if (isNaN(major) || isNaN(minor) || isNaN(patch)) return null;
+  return { major, minor, patch };
+}
+
+/**
+ * Check if two versions are compatible (same major.minor).
+ * Patch differences are allowed — only major or minor mismatch is incompatible.
+ *
+ * @param configVersion - Version from the config file
+ * @param currentVersion - Currently running Grafema version
+ * @returns true if versions share the same major.minor
+ */
+export function isCompatibleVersion(configVersion: string, currentVersion: string): boolean {
+  const config = parseVersion(configVersion);
+  const current = parseVersion(currentVersion);
+  if (!config || !current) return false;
+  return config.major === current.major && config.minor === current.minor;
+}