@d34dman/flowdrop 0.0.15 → 0.0.17

package/dist/registry/plugin.js

@@ -0,0 +1,249 @@
+/**
+ * FlowDrop Plugin System
+ * Provides APIs for external libraries to register custom node components.
+ *
+ * This enables a plugin ecosystem where:
+ * - Third-party libraries can provide custom node types
+ * - Custom nodes are namespaced to avoid conflicts
+ * - Registration is simplified with a clean API
+ */
+import { nodeComponentRegistry, createNamespacedType } from './nodeComponentRegistry.js';
+/**
+ * Register a FlowDrop plugin with custom node components.
+ * All node types are automatically namespaced with the plugin namespace.
+ *
+ * @param config - Plugin configuration with namespace and node definitions
+ * @returns Result object with registered types and any errors
+ *
+ * @example
+ * ```typescript
+ * import { registerFlowDropPlugin } from "@flowdrop/lib";
+ * import FancyNode from "./FancyNode.svelte";
+ * import GlowNode from "./GlowNode.svelte";
+ *
+ * const result = registerFlowDropPlugin({
+ *     namespace: "awesome",
+ *     name: "Awesome Nodes",
+ *     version: "1.0.0",
+ *     nodes: [
+ *         {
+ *             type: "fancy",
+ *             displayName: "Fancy Node",
+ *             component: FancyNode,
+ *             icon: "mdi:sparkles"
+ *         },
+ *         {
+ *             type: "glow",
+ *             displayName: "Glowing Node",
+ *             component: GlowNode,
+ *             icon: "mdi:lightbulb"
+ *         }
+ *     ]
+ * });
+ *
+ * // Result:
+ * // {
+ * //     success: true,
+ * //     namespace: "awesome",
+ * //     registeredTypes: ["awesome:fancy", "awesome:glow"],
+ * //     errors: []
+ * // }
+ * ```
+ */
+export function registerFlowDropPlugin(config) {
+    const result = {
+        success: true,
+        namespace: config.namespace,
+        registeredTypes: [],
+        errors: []
+    };
+    // Validate namespace
+    if (!isValidNamespace(config.namespace)) {
+        result.success = false;
+        result.errors.push(`Invalid namespace "${config.namespace}". ` +
+            `Namespace must be lowercase alphanumeric with optional hyphens.`);
+        return result;
+    }
+    // Register each node
+    for (const nodeDef of config.nodes) {
+        try {
+            const namespacedType = createNamespacedType(config.namespace, nodeDef.type);
+            const registration = {
+                type: namespacedType,
+                displayName: nodeDef.displayName,
+                description: nodeDef.description,
+                component: nodeDef.component,
+                icon: nodeDef.icon,
+                category: nodeDef.category ?? 'custom',
+                source: config.namespace,
+                statusPosition: nodeDef.statusPosition,
+                statusSize: nodeDef.statusSize
+            };
+            nodeComponentRegistry.register(registration);
+            result.registeredTypes.push(namespacedType);
+        }
+        catch (error) {
+            result.success = false;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            result.errors.push(`Failed to register ${config.namespace}:${nodeDef.type}: ${errorMessage}`);
+        }
+    }
+    return result;
+}
+/**
+ * Unregister all nodes from a plugin by namespace.
+ *
+ * @param namespace - The plugin namespace to unregister
+ * @returns Array of unregistered type identifiers
+ *
+ * @example
+ * ```typescript
+ * const removed = unregisterFlowDropPlugin("awesome");
+ * // Returns ["awesome:fancy", "awesome:glow"]
+ * ```
+ */
+export function unregisterFlowDropPlugin(namespace) {
+    const unregistered = [];
+    const types = nodeComponentRegistry.getTypes();
+    for (const type of types) {
+        if (type.startsWith(`${namespace}:`)) {
+            if (nodeComponentRegistry.unregister(type)) {
+                unregistered.push(type);
+            }
+        }
+    }
+    return unregistered;
+}
+/**
+ * Check if a namespace is valid.
+ * Must be lowercase alphanumeric with optional hyphens.
+ *
+ * @param namespace - The namespace to validate
+ * @returns true if valid
+ */
+export function isValidNamespace(namespace) {
+    return /^[a-z][a-z0-9-]*$/.test(namespace);
+}
+/**
+ * Get all registered plugins (unique namespaces).
+ *
+ * @returns Array of namespace strings
+ */
+export function getRegisteredPlugins() {
+    const sources = new Set();
+    const registrations = nodeComponentRegistry.getAll();
+    for (const reg of registrations) {
+        if (reg.source && reg.source !== 'flowdrop') {
+            sources.add(reg.source);
+        }
+    }
+    return Array.from(sources);
+}
+/**
+ * Get the count of nodes registered by a plugin.
+ *
+ * @param namespace - The plugin namespace
+ * @returns Number of nodes registered by this plugin
+ */
+export function getPluginNodeCount(namespace) {
+    return nodeComponentRegistry.getBySource(namespace).length;
+}
+/**
+ * Register a single custom node without a full plugin.
+ * Useful for project-specific custom nodes.
+ *
+ * @param type - Type identifier (can be namespaced or plain)
+ * @param displayName - Display name for UI
+ * @param component - Svelte component
+ * @param options - Additional options
+ *
+ * @example
+ * ```typescript
+ * import { registerCustomNode } from "@flowdrop/lib";
+ * import MyNode from "./MyNode.svelte";
+ *
+ * registerCustomNode("myproject:special", "Special Node", MyNode, {
+ *     icon: "mdi:star",
+ *     description: "A special node for my project"
+ * });
+ * ```
+ */
+export function registerCustomNode(type, displayName, component, options = {}) {
+    nodeComponentRegistry.register({
+        type,
+        displayName,
+        component,
+        description: options.description,
+        icon: options.icon,
+        category: options.category ?? 'custom',
+        source: options.source ?? 'custom',
+        statusPosition: options.statusPosition,
+        statusSize: options.statusSize
+    });
+}
+/**
+ * Create a plugin builder for a fluent API experience.
+ *
+ * @param namespace - Plugin namespace
+ * @param name - Plugin name
+ * @returns Plugin builder with chainable methods
+ *
+ * @example
+ * ```typescript
+ * import { createPlugin } from "@flowdrop/lib";
+ *
+ * createPlugin("awesome", "Awesome Nodes")
+ *     .version("1.0.0")
+ *     .node("fancy", "Fancy Node", FancyNode)
+ *     .node("glow", "Glowing Node", GlowNode, { icon: "mdi:lightbulb" })
+ *     .register();
+ * ```
+ */
+export function createPlugin(namespace, name) {
+    const config = {
+        namespace,
+        name,
+        nodes: []
+    };
+    const builder = {
+        /**
+         * Set plugin version
+         */
+        version(v) {
+            config.version = v;
+            return builder;
+        },
+        /**
+         * Set plugin description
+         */
+        description(desc) {
+            config.description = desc;
+            return builder;
+        },
+        /**
+         * Add a node to the plugin
+         */
+        node(type, displayName, component, options = {}) {
+            config.nodes.push({
+                type,
+                displayName,
+                component,
+                ...options
+            });
+            return builder;
+        },
+        /**
+         * Register the plugin
+         */
+        register() {
+            return registerFlowDropPlugin(config);
+        },
+        /**
+         * Get the config without registering (for testing/inspection)
+         */
+        getConfig() {
+            return { ...config };
+        }
+    };
+    return builder;
+}

package/dist/services/draftStorage.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Draft Storage Service for FlowDrop
+ *
+ * Handles saving and loading workflow drafts to/from localStorage.
+ * Provides interval-based auto-save functionality.
+ *
+ * @module services/draftStorage
+ */
+import type { Workflow } from '../types/index.js';
+/**
+ * Draft metadata stored alongside the workflow
+ */
+interface DraftMetadata {
+    /** Timestamp when the draft was saved */
+    savedAt: string;
+    /** Workflow ID (if available) */
+    workflowId?: string;
+    /** Workflow name */
+    workflowName?: string;
+}
+/**
+ * Complete draft data stored in localStorage
+ */
+interface StoredDraft {
+    /** The workflow data */
+    workflow: Workflow;
+    /** Draft metadata */
+    metadata: DraftMetadata;
+}
+/**
+ * Generate a storage key for a workflow
+ *
+ * If a custom key is provided, use it directly.
+ * Otherwise, generate based on workflow ID or use "new" for unsaved workflows.
+ *
+ * @param workflowId - The workflow ID (optional)
+ * @param customKey - Custom storage key provided by enterprise (optional)
+ * @returns The storage key to use
+ */
+export declare function getDraftStorageKey(workflowId?: string, customKey?: string): string;
+/**
+ * Save a workflow draft to localStorage
+ *
+ * @param workflow - The workflow to save
+ * @param storageKey - The storage key to use
+ * @returns true if saved successfully, false otherwise
+ */
+export declare function saveDraft(workflow: Workflow, storageKey: string): boolean;
+/**
+ * Load a workflow draft from localStorage
+ *
+ * @param storageKey - The storage key to load from
+ * @returns The stored draft, or null if not found
+ */
+export declare function loadDraft(storageKey: string): StoredDraft | null;
+/**
+ * Delete a workflow draft from localStorage
+ *
+ * @param storageKey - The storage key to delete
+ */
+export declare function deleteDraft(storageKey: string): void;
+/**
+ * Check if a draft exists for a given storage key
+ *
+ * @param storageKey - The storage key to check
+ * @returns true if a draft exists
+ */
+export declare function hasDraft(storageKey: string): boolean;
+/**
+ * Get draft metadata without loading the full workflow
+ *
+ * Useful for displaying draft information without parsing the entire workflow.
+ *
+ * @param storageKey - The storage key to check
+ * @returns Draft metadata, or null if not found
+ */
+export declare function getDraftMetadata(storageKey: string): DraftMetadata | null;
+/**
+ * Draft auto-save manager
+ *
+ * Handles interval-based auto-saving of workflow drafts.
+ * Should be instantiated per FlowDrop instance.
+ */
+export declare class DraftAutoSaveManager {
+    /** Interval timer ID */
+    private intervalId;
+    /** Storage key for drafts */
+    private storageKey;
+    /** Auto-save interval in milliseconds */
+    private interval;
+    /** Whether auto-save is enabled */
+    private enabled;
+    /** Function to get current workflow */
+    private getWorkflow;
+    /** Function to check if workflow is dirty */
+    private isDirty;
+    /** Last saved workflow hash (for change detection) */
+    private lastSavedHash;
+    /**
+     * Create a new DraftAutoSaveManager
+     *
+     * @param options - Configuration options
+     */
+    constructor(options: {
+        storageKey: string;
+        interval: number;
+        enabled: boolean;
+        getWorkflow: () => Workflow | null;
+        isDirty: () => boolean;
+    });
+    /**
+     * Start auto-save interval
+     *
+     * Will save drafts at the configured interval if there are unsaved changes.
+     */
+    start(): void;
+    /**
+     * Stop auto-save interval
+     */
+    stop(): void;
+    /**
+     * Save draft if there are unsaved changes
+     *
+     * @returns true if a draft was saved
+     */
+    saveIfDirty(): boolean;
+    /**
+     * Force save the current workflow as a draft
+     *
+     * Saves regardless of dirty state.
+     *
+     * @returns true if saved successfully
+     */
+    forceSave(): boolean;
+    /**
+     * Clear the draft from storage
+     */
+    clearDraft(): void;
+    /**
+     * Mark the current state as saved
+     *
+     * Updates the hash so the next saveIfDirty won't save unless there are new changes.
+     */
+    markAsSaved(): void;
+    /**
+     * Update the storage key
+     *
+     * Useful when the workflow ID changes (e.g., after first save).
+     *
+     * @param newKey - The new storage key
+     */
+    updateStorageKey(newKey: string): void;
+    /**
+     * Simple hash function for change detection
+     *
+     * Not cryptographically secure, just for detecting changes.
+     *
+     * @param workflow - The workflow to hash
+     * @returns A simple hash string
+     */
+    private hashWorkflow;
+    /**
+     * Check if auto-save is currently running
+     */
+    isRunning(): boolean;
+    /**
+     * Get the current storage key
+     */
+    getStorageKey(): string;
+}
+export {};

package/dist/services/draftStorage.js

@@ -0,0 +1,298 @@
+/**
+ * Draft Storage Service for FlowDrop
+ *
+ * Handles saving and loading workflow drafts to/from localStorage.
+ * Provides interval-based auto-save functionality.
+ *
+ * @module services/draftStorage
+ */
+/**
+ * Default storage key prefix
+ */
+const STORAGE_KEY_PREFIX = 'flowdrop:draft';
+/**
+ * Generate a storage key for a workflow
+ *
+ * If a custom key is provided, use it directly.
+ * Otherwise, generate based on workflow ID or use "new" for unsaved workflows.
+ *
+ * @param workflowId - The workflow ID (optional)
+ * @param customKey - Custom storage key provided by enterprise (optional)
+ * @returns The storage key to use
+ */
+export function getDraftStorageKey(workflowId, customKey) {
+    if (customKey) {
+        return customKey;
+    }
+    if (workflowId) {
+        return `${STORAGE_KEY_PREFIX}:${workflowId}`;
+    }
+    return `${STORAGE_KEY_PREFIX}:new`;
+}
+/**
+ * Save a workflow draft to localStorage
+ *
+ * @param workflow - The workflow to save
+ * @param storageKey - The storage key to use
+ * @returns true if saved successfully, false otherwise
+ */
+export function saveDraft(workflow, storageKey) {
+    try {
+        const draft = {
+            workflow,
+            metadata: {
+                savedAt: new Date().toISOString(),
+                workflowId: workflow.id,
+                workflowName: workflow.name
+            }
+        };
+        localStorage.setItem(storageKey, JSON.stringify(draft));
+        return true;
+    }
+    catch (error) {
+        // localStorage might be full or disabled
+        console.warn('Failed to save draft to localStorage:', error);
+        return false;
+    }
+}
+/**
+ * Load a workflow draft from localStorage
+ *
+ * @param storageKey - The storage key to load from
+ * @returns The stored draft, or null if not found
+ */
+export function loadDraft(storageKey) {
+    try {
+        const stored = localStorage.getItem(storageKey);
+        if (!stored) {
+            return null;
+        }
+        const draft = JSON.parse(stored);
+        // Validate the draft structure
+        if (!draft.workflow || !draft.metadata) {
+            console.warn('Invalid draft structure in localStorage');
+            return null;
+        }
+        return draft;
+    }
+    catch (error) {
+        console.warn('Failed to load draft from localStorage:', error);
+        return null;
+    }
+}
+/**
+ * Delete a workflow draft from localStorage
+ *
+ * @param storageKey - The storage key to delete
+ */
+export function deleteDraft(storageKey) {
+    try {
+        localStorage.removeItem(storageKey);
+    }
+    catch (error) {
+        console.warn('Failed to delete draft from localStorage:', error);
+    }
+}
+/**
+ * Check if a draft exists for a given storage key
+ *
+ * @param storageKey - The storage key to check
+ * @returns true if a draft exists
+ */
+export function hasDraft(storageKey) {
+    try {
+        return localStorage.getItem(storageKey) !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get draft metadata without loading the full workflow
+ *
+ * Useful for displaying draft information without parsing the entire workflow.
+ *
+ * @param storageKey - The storage key to check
+ * @returns Draft metadata, or null if not found
+ */
+export function getDraftMetadata(storageKey) {
+    const draft = loadDraft(storageKey);
+    return draft?.metadata ?? null;
+}
+/**
+ * Draft auto-save manager
+ *
+ * Handles interval-based auto-saving of workflow drafts.
+ * Should be instantiated per FlowDrop instance.
+ */
+export class DraftAutoSaveManager {
+    /** Interval timer ID */
+    intervalId = null;
+    /** Storage key for drafts */
+    storageKey;
+    /** Auto-save interval in milliseconds */
+    interval;
+    /** Whether auto-save is enabled */
+    enabled;
+    /** Function to get current workflow */
+    getWorkflow;
+    /** Function to check if workflow is dirty */
+    isDirty;
+    /** Last saved workflow hash (for change detection) */
+    lastSavedHash = null;
+    /**
+     * Create a new DraftAutoSaveManager
+     *
+     * @param options - Configuration options
+     */
+    constructor(options) {
+        this.storageKey = options.storageKey;
+        this.interval = options.interval;
+        this.enabled = options.enabled;
+        this.getWorkflow = options.getWorkflow;
+        this.isDirty = options.isDirty;
+    }
+    /**
+     * Start auto-save interval
+     *
+     * Will save drafts at the configured interval if there are unsaved changes.
+     */
+    start() {
+        if (!this.enabled || this.intervalId) {
+            return;
+        }
+        this.intervalId = setInterval(() => {
+            this.saveIfDirty();
+        }, this.interval);
+    }
+    /**
+     * Stop auto-save interval
+     */
+    stop() {
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+    }
+    /**
+     * Save draft if there are unsaved changes
+     *
+     * @returns true if a draft was saved
+     */
+    saveIfDirty() {
+        if (!this.enabled) {
+            return false;
+        }
+        const workflow = this.getWorkflow();
+        if (!workflow) {
+            return false;
+        }
+        // Only save if dirty
+        if (!this.isDirty()) {
+            return false;
+        }
+        // Check if workflow has actually changed since last save
+        const currentHash = this.hashWorkflow(workflow);
+        if (currentHash === this.lastSavedHash) {
+            return false;
+        }
+        const saved = saveDraft(workflow, this.storageKey);
+        if (saved) {
+            this.lastSavedHash = currentHash;
+        }
+        return saved;
+    }
+    /**
+     * Force save the current workflow as a draft
+     *
+     * Saves regardless of dirty state.
+     *
+     * @returns true if saved successfully
+     */
+    forceSave() {
+        const workflow = this.getWorkflow();
+        if (!workflow) {
+            return false;
+        }
+        const saved = saveDraft(workflow, this.storageKey);
+        if (saved) {
+            this.lastSavedHash = this.hashWorkflow(workflow);
+        }
+        return saved;
+    }
+    /**
+     * Clear the draft from storage
+     */
+    clearDraft() {
+        deleteDraft(this.storageKey);
+        this.lastSavedHash = null;
+    }
+    /**
+     * Mark the current state as saved
+     *
+     * Updates the hash so the next saveIfDirty won't save unless there are new changes.
+     */
+    markAsSaved() {
+        const workflow = this.getWorkflow();
+        if (workflow) {
+            this.lastSavedHash = this.hashWorkflow(workflow);
+        }
+    }
+    /**
+     * Update the storage key
+     *
+     * Useful when the workflow ID changes (e.g., after first save).
+     *
+     * @param newKey - The new storage key
+     */
+    updateStorageKey(newKey) {
+        // If there's an existing draft with the old key, migrate it
+        const existingDraft = loadDraft(this.storageKey);
+        if (existingDraft && this.storageKey !== newKey) {
+            deleteDraft(this.storageKey);
+            saveDraft(existingDraft.workflow, newKey);
+        }
+        this.storageKey = newKey;
+    }
+    /**
+     * Simple hash function for change detection
+     *
+     * Not cryptographically secure, just for detecting changes.
+     *
+     * @param workflow - The workflow to hash
+     * @returns A simple hash string
+     */
+    hashWorkflow(workflow) {
+        // Use a simple stringification for change detection
+        // We only need nodes, edges, name, and description for change detection
+        const toHash = {
+            name: workflow.name,
+            description: workflow.description,
+            nodes: workflow.nodes.map((n) => ({
+                id: n.id,
+                position: n.position,
+                data: n.data
+            })),
+            edges: workflow.edges.map((e) => ({
+                id: e.id,
+                source: e.source,
+                target: e.target,
+                sourceHandle: e.sourceHandle,
+                targetHandle: e.targetHandle
+            }))
+        };
+        return JSON.stringify(toHash);
+    }
+    /**
+     * Check if auto-save is currently running
+     */
+    isRunning() {
+        return this.intervalId !== null;
+    }
+    /**
+     * Get the current storage key
+     */
+    getStorageKey() {
+        return this.storageKey;
+    }
+}