@3plate/graph-core 0.1.7 → 0.1.10

package/dist/index.d.cts

@@ -3,6 +3,7 @@ type MergeOrder = Side[];
 type NodeAlign = 'natural' | 'top' | 'bottom' | 'left' | 'right';
 type Orientation = 'TB' | 'BT' | 'LR' | 'RL';
 type Nav = 'first' | 'last' | 'prev' | 'next';
+type PortStyle = 'inside' | 'outside' | 'custom';
 type LayoutStep = 'alignChildren' | 'alignParents' | 'compact';
 type Dims = {
     w: number;
@@ -11,11 +12,38 @@ type Dims = {
 
 type MarkerType = 'arrow' | 'circle' | 'diamond' | 'bar' | 'none';
 
+/** WebSocket ingestion configuration */
+type WebSocketIngestionConfig = {
+    type: 'websocket';
+    /** WebSocket URL */
+    url: string;
+    /** Reconnect interval in milliseconds */
+    reconnectMs?: number;
+    /** Callback when the WebSocket connection is established */
+    onConnect?: () => void;
+    /** Callback when the WebSocket connection is closed */
+    onDisconnect?: () => void;
+    /** Callback when the WebSocket connection encounters an error */
+    onError?: (error: Error) => void;
+};
+/** File ingestion configuration */
+type FileIngestionConfig = {
+    type: 'file';
+    /** File URL */
+    url: string;
+    /** Polling interval in milliseconds */
+    intervalMs?: number;
+};
+/**
+ * Ingestion source configuration.
+ * Used to connect to an external data source for graph updates.
+ */
+type IngestionConfig = WebSocketIngestionConfig | FileIngestionConfig;
 /**
  * Arguments to the API constructor.
  *
- * The caller can specify nodes and edges, or history,
- * but not both.
+ * The caller can specify nodes and edges, history, or ingestion config,
+ * but not multiple.
  *
  * The root element ID is required.
  */
@@ -28,6 +56,8 @@ type APIArguments<N, E> = {
     edges?: E[];
     /** Initial history */
     history?: Update<N, E>[];
+    /** Ingestion source configuration */
+    ingestion?: IngestionConfig;
     /** Events */
     events?: EventsOptions<N, E>;
     /** Root element ID */
@@ -370,11 +400,19 @@ declare class API<N, E> {
     private nextNodeId;
     private nextEdgeId;
     private events;
+    private ingest?;
+    private ingestionSource?;
+    private ingestionConfig?;
+    private prevProps;
     root: string;
     constructor(args: APIArguments<N, E>);
     reset(): void;
     /** Initialize the API */
     init(): Promise<void>;
+    /** Connect to the configured ingestion source */
+    private connectIngestion;
+    /** Disconnect from the ingestion source */
+    private disconnectIngestion;
     private applyHistory;
     /** Current history index (0-based) */
     getHistoryIndex(): number;
@@ -446,6 +484,20 @@ declare class API<N, E> {
     }): void;
     /** Update color mode without recreating the canvas */
     setColorMode(colorMode: 'light' | 'dark' | 'system'): void;
+    /**
+     * Apply prop changes by diffing against previously applied props.
+     * This is a convenience method for framework wrappers that centralizes
+     * the logic for detecting and applying changes to nodes, edges, history, and options.
+     * The API stores the previous props internally, so you just pass the new props.
+     *
+     * @param props - The new props to apply
+     */
+    applyProps(props: {
+        nodes?: N[];
+        edges?: E[];
+        history?: Update<N, E>[];
+        options?: APIOptions<N, E>;
+    }): void;
     /** Cleanup resources when the graph is destroyed */
     destroy(): void;
 }
@@ -481,7 +533,14 @@ declare class Ingest<N, E> {
     apply(msg: IngestMessage<N, E>): Promise<void>;
 }
 
-type StatusListener$2 = (status: 'connecting' | 'connected' | 'reconnecting' | 'closed' | 'error', detail?: any) => void;
+type WebSocketStatus = 'connecting' | 'connected' | 'reconnecting' | 'closed' | 'error';
+type WebSocketStatusListener = (status: WebSocketStatus, detail?: any) => void;
+type WebSocketSourceArgs<N, E> = {
+    url: string;
+    onMessage: (msg: IngestMessage<N, E>) => void;
+    onStatus?: WebSocketStatusListener;
+    reconnectMs?: number;
+};
 declare class WebSocketSource<N, E> {
     private url;
     private ws;
@@ -492,7 +551,7 @@ declare class WebSocketSource<N, E> {
     private connectStartTime;
     private totalTimeoutMs;
     private totalTimeoutTimer;
-    constructor(url: string, onMessage: (msg: IngestMessage<N, E>) => void, onStatus?: StatusListener$2, reconnectMs?: number);
+    constructor(args: WebSocketSourceArgs<N, E>);
     connect(): void;
     disconnect(): void;
     private startTotalTimeout;
@@ -501,6 +560,12 @@ declare class WebSocketSource<N, E> {
 }
 
 type StatusListener$1 = (status: 'idle' | 'opened' | 'reading' | 'error' | 'closed', detail?: any) => void;
+type FileSystemSourceArgs<N, E> = {
+    filename: string;
+    onMessage: (msg: IngestMessage<N, E>) => void;
+    onStatus?: StatusListener$1;
+    intervalMs?: number;
+};
 declare class FileSystemSource<N, E> {
     private handle;
     private onMessage;
@@ -509,7 +574,7 @@ declare class FileSystemSource<N, E> {
     private lastSize;
     private filename;
     private intervalMs;
-    constructor(onMessage: (msg: IngestMessage<N, E>) => void, onStatus?: StatusListener$1, filename?: string, intervalMs?: number);
+    constructor(args: FileSystemSourceArgs<N, E>);
     openDirectory(): Promise<void>;
     close(): void;
     private startPolling;
@@ -517,6 +582,12 @@ declare class FileSystemSource<N, E> {
 }
 
 type StatusListener = (status: 'idle' | 'opened' | 'reading' | 'error' | 'closed', detail?: any) => void;
+type FileSourceArgs<N, E> = {
+    url: string;
+    onMessage: (msg: IngestMessage<N, E>) => void;
+    onStatus?: StatusListener;
+    intervalMs?: number;
+};
 declare class FileSource<N, E> {
     private url;
     private onMessage;
@@ -526,7 +597,7 @@ declare class FileSource<N, E> {
     private lastContent;
     private intervalMs;
     private closed;
-    constructor(url: string, onMessage: (msg: IngestMessage<N, E>) => void, onStatus?: StatusListener, intervalMs?: number);
+    constructor(args: FileSourceArgs<N, E>);
     connect(): Promise<void>;
     close(): void;
     private startPolling;
@@ -648,4 +719,4 @@ declare class Playground {
 
 declare function graph<N, E>(args?: APIArguments<N, E>): Promise<API<N, E>>;
 
-export { API, type APIArguments, type APIOptions, type EventsOptions, type Example, type ExampleEdge, type ExampleNode, type ExampleOptions, FileSource, FileSystemSource, type HistoryMessage, Ingest, type IngestMessage, Playground, type PlaygroundOptions, type SnapshotMessage, type Update, type UpdateMessage, Updater, WebSocketSource, graph as default, graph };
+export { API, type APIArguments, type APIOptions, type CanvasTheme, type ColorMode, type EdgeProps, type EdgeTheme, type EventsOptions, type Example, type ExampleEdge, type ExampleNode, type ExampleOptions, FileSource, type FileSourceArgs, FileSystemSource, type FileSystemSourceArgs, type HistoryMessage, Ingest, type IngestMessage, type IngestionConfig, type NewEdge, type NewNode, type NodeAlign, type NodeProps, type NodeTheme, type Orientation, Playground, type PlaygroundOptions, type PortProps, type PortStyle, type PortTheme, type RenderNode, type SnapshotMessage, type ThemeVars, type Update, type UpdateMessage, Updater, WebSocketSource, type WebSocketSourceArgs, type WebSocketStatus, type WebSocketStatusListener, graph as default, graph };

package/dist/index.d.ts

@@ -3,6 +3,7 @@ type MergeOrder = Side[];
 type NodeAlign = 'natural' | 'top' | 'bottom' | 'left' | 'right';
 type Orientation = 'TB' | 'BT' | 'LR' | 'RL';
 type Nav = 'first' | 'last' | 'prev' | 'next';
+type PortStyle = 'inside' | 'outside' | 'custom';
 type LayoutStep = 'alignChildren' | 'alignParents' | 'compact';
 type Dims = {
     w: number;
@@ -11,11 +12,38 @@ type Dims = {
 
 type MarkerType = 'arrow' | 'circle' | 'diamond' | 'bar' | 'none';
 
+/** WebSocket ingestion configuration */
+type WebSocketIngestionConfig = {
+    type: 'websocket';
+    /** WebSocket URL */
+    url: string;
+    /** Reconnect interval in milliseconds */
+    reconnectMs?: number;
+    /** Callback when the WebSocket connection is established */
+    onConnect?: () => void;
+    /** Callback when the WebSocket connection is closed */
+    onDisconnect?: () => void;
+    /** Callback when the WebSocket connection encounters an error */
+    onError?: (error: Error) => void;
+};
+/** File ingestion configuration */
+type FileIngestionConfig = {
+    type: 'file';
+    /** File URL */
+    url: string;
+    /** Polling interval in milliseconds */
+    intervalMs?: number;
+};
+/**
+ * Ingestion source configuration.
+ * Used to connect to an external data source for graph updates.
+ */
+type IngestionConfig = WebSocketIngestionConfig | FileIngestionConfig;
 /**
  * Arguments to the API constructor.
  *
- * The caller can specify nodes and edges, or history,
- * but not both.
+ * The caller can specify nodes and edges, history, or ingestion config,
+ * but not multiple.
  *
  * The root element ID is required.
  */
@@ -28,6 +56,8 @@ type APIArguments<N, E> = {
     edges?: E[];
     /** Initial history */
     history?: Update<N, E>[];
+    /** Ingestion source configuration */
+    ingestion?: IngestionConfig;
     /** Events */
     events?: EventsOptions<N, E>;
     /** Root element ID */
@@ -370,11 +400,19 @@ declare class API<N, E> {
     private nextNodeId;
     private nextEdgeId;
     private events;
+    private ingest?;
+    private ingestionSource?;
+    private ingestionConfig?;
+    private prevProps;
     root: string;
     constructor(args: APIArguments<N, E>);
     reset(): void;
     /** Initialize the API */
     init(): Promise<void>;
+    /** Connect to the configured ingestion source */
+    private connectIngestion;
+    /** Disconnect from the ingestion source */
+    private disconnectIngestion;
     private applyHistory;
     /** Current history index (0-based) */
     getHistoryIndex(): number;
@@ -446,6 +484,20 @@ declare class API<N, E> {
     }): void;
     /** Update color mode without recreating the canvas */
     setColorMode(colorMode: 'light' | 'dark' | 'system'): void;
+    /**
+     * Apply prop changes by diffing against previously applied props.
+     * This is a convenience method for framework wrappers that centralizes
+     * the logic for detecting and applying changes to nodes, edges, history, and options.
+     * The API stores the previous props internally, so you just pass the new props.
+     *
+     * @param props - The new props to apply
+     */
+    applyProps(props: {
+        nodes?: N[];
+        edges?: E[];
+        history?: Update<N, E>[];
+        options?: APIOptions<N, E>;
+    }): void;
     /** Cleanup resources when the graph is destroyed */
     destroy(): void;
 }
@@ -481,7 +533,14 @@ declare class Ingest<N, E> {
     apply(msg: IngestMessage<N, E>): Promise<void>;
 }
 
-type StatusListener$2 = (status: 'connecting' | 'connected' | 'reconnecting' | 'closed' | 'error', detail?: any) => void;
+type WebSocketStatus = 'connecting' | 'connected' | 'reconnecting' | 'closed' | 'error';
+type WebSocketStatusListener = (status: WebSocketStatus, detail?: any) => void;
+type WebSocketSourceArgs<N, E> = {
+    url: string;
+    onMessage: (msg: IngestMessage<N, E>) => void;
+    onStatus?: WebSocketStatusListener;
+    reconnectMs?: number;
+};
 declare class WebSocketSource<N, E> {
     private url;
     private ws;
@@ -492,7 +551,7 @@ declare class WebSocketSource<N, E> {
     private connectStartTime;
     private totalTimeoutMs;
     private totalTimeoutTimer;
-    constructor(url: string, onMessage: (msg: IngestMessage<N, E>) => void, onStatus?: StatusListener$2, reconnectMs?: number);
+    constructor(args: WebSocketSourceArgs<N, E>);
     connect(): void;
     disconnect(): void;
     private startTotalTimeout;
@@ -501,6 +560,12 @@ declare class WebSocketSource<N, E> {
 }
 
 type StatusListener$1 = (status: 'idle' | 'opened' | 'reading' | 'error' | 'closed', detail?: any) => void;
+type FileSystemSourceArgs<N, E> = {
+    filename: string;
+    onMessage: (msg: IngestMessage<N, E>) => void;
+    onStatus?: StatusListener$1;
+    intervalMs?: number;
+};
 declare class FileSystemSource<N, E> {
     private handle;
     private onMessage;
@@ -509,7 +574,7 @@ declare class FileSystemSource<N, E> {
     private lastSize;
     private filename;
     private intervalMs;
-    constructor(onMessage: (msg: IngestMessage<N, E>) => void, onStatus?: StatusListener$1, filename?: string, intervalMs?: number);
+    constructor(args: FileSystemSourceArgs<N, E>);
     openDirectory(): Promise<void>;
     close(): void;
     private startPolling;
@@ -517,6 +582,12 @@ declare class FileSystemSource<N, E> {
 }
 
 type StatusListener = (status: 'idle' | 'opened' | 'reading' | 'error' | 'closed', detail?: any) => void;
+type FileSourceArgs<N, E> = {
+    url: string;
+    onMessage: (msg: IngestMessage<N, E>) => void;
+    onStatus?: StatusListener;
+    intervalMs?: number;
+};
 declare class FileSource<N, E> {
     private url;
     private onMessage;
@@ -526,7 +597,7 @@ declare class FileSource<N, E> {
     private lastContent;
     private intervalMs;
     private closed;
-    constructor(url: string, onMessage: (msg: IngestMessage<N, E>) => void, onStatus?: StatusListener, intervalMs?: number);
+    constructor(args: FileSourceArgs<N, E>);
     connect(): Promise<void>;
     close(): void;
     private startPolling;
@@ -648,4 +719,4 @@ declare class Playground {
 
 declare function graph<N, E>(args?: APIArguments<N, E>): Promise<API<N, E>>;
 
-export { API, type APIArguments, type APIOptions, type EventsOptions, type Example, type ExampleEdge, type ExampleNode, type ExampleOptions, FileSource, FileSystemSource, type HistoryMessage, Ingest, type IngestMessage, Playground, type PlaygroundOptions, type SnapshotMessage, type Update, type UpdateMessage, Updater, WebSocketSource, graph as default, graph };
+export { API, type APIArguments, type APIOptions, type CanvasTheme, type ColorMode, type EdgeProps, type EdgeTheme, type EventsOptions, type Example, type ExampleEdge, type ExampleNode, type ExampleOptions, FileSource, type FileSourceArgs, FileSystemSource, type FileSystemSourceArgs, type HistoryMessage, Ingest, type IngestMessage, type IngestionConfig, type NewEdge, type NewNode, type NodeAlign, type NodeProps, type NodeTheme, type Orientation, Playground, type PlaygroundOptions, type PortProps, type PortStyle, type PortTheme, type RenderNode, type SnapshotMessage, type ThemeVars, type Update, type UpdateMessage, Updater, WebSocketSource, type WebSocketSourceArgs, type WebSocketStatus, type WebSocketStatusListener, graph as default, graph };