@drop-ai/core 0.2.0

package/dist/audio/ProcessingGraph.js

@@ -0,0 +1,360 @@
+/**
+ * ProcessingGraph — a directed acyclic graph (DAG) for modeling signal-processing
+ * node execution order.
+ *
+ * Inspired by Ardour's internal graph scheduler (`libs/ardour/graph.cc`).
+ * The graph is a standalone utility with no audio-framework dependencies,
+ * making it suitable for unit testing and headless use.
+ *
+ * Key capabilities:
+ * - Add / remove nodes and directed edges (from → to means "from depends on to")
+ * - Topological sort via Kahn's algorithm — produces a valid execution order
+ * - Cycle detection via iterative DFS
+ * - Parallel-group extraction — nodes at the same "depth" can run concurrently
+ *
+ * @module ProcessingGraph
+ */
+/**
+ * ProcessingGraph models a DAG of {@link GraphNode}s connected by directed
+ * dependency edges.
+ *
+ * An edge `from → to` means "node `from` depends on node `to`" — i.e. `to`
+ * must be processed **before** `from`.
+ *
+ * @example
+ * ```ts
+ * const graph = new ProcessingGraph();
+ * graph.addNode({ id: 'input' });
+ * graph.addNode({ id: 'eq' });
+ * graph.addNode({ id: 'compressor' });
+ * graph.addNode({ id: 'output' });
+ *
+ * graph.addEdge('eq', 'input');          // eq depends on input
+ * graph.addEdge('compressor', 'eq');     // compressor depends on eq
+ * graph.addEdge('output', 'compressor'); // output depends on compressor
+ *
+ * const order = graph.topologicalSort(); // [input, eq, compressor, output]
+ * ```
+ */
+export class ProcessingGraph {
+    constructor() {
+        /** All registered nodes keyed by id. */
+        this.nodes = new Map();
+        /**
+         * Adjacency list storing **dependencies** (incoming edges).
+         * `edges.get(nodeId)` → set of node ids that `nodeId` depends on.
+         */
+        this.edges = new Map();
+    }
+    // ---------------------------------------------------------------
+    // Node management
+    // ---------------------------------------------------------------
+    /**
+     * Register a node in the graph.
+     *
+     * If a node with the same `id` already exists it will be replaced,
+     * but its edges are preserved.
+     *
+     * @param node - The graph node to add.
+     */
+    addNode(node) {
+        this.nodes.set(node.id, node);
+        if (!this.edges.has(node.id)) {
+            this.edges.set(node.id, new Set());
+        }
+    }
+    /**
+     * Remove a node and all edges that reference it (both incoming and
+     * outgoing).
+     *
+     * @param nodeId - The id of the node to remove.
+     */
+    removeNode(nodeId) {
+        this.nodes.delete(nodeId);
+        this.edges.delete(nodeId);
+        // Remove references to this node from all other edge sets
+        for (const deps of this.edges.values()) {
+            deps.delete(nodeId);
+        }
+    }
+    /**
+     * Return the node with the given id, or `undefined` if it does not exist.
+     *
+     * @param nodeId - The id to look up.
+     */
+    getNode(nodeId) {
+        return this.nodes.get(nodeId);
+    }
+    /**
+     * The total number of nodes currently in the graph.
+     */
+    get nodeCount() {
+        return this.nodes.size;
+    }
+    // ---------------------------------------------------------------
+    // Edge management
+    // ---------------------------------------------------------------
+    /**
+     * Add a directed dependency edge: `from` depends on `to`.
+     *
+     * Both node ids must already exist in the graph; otherwise the call is a
+     * no-op.
+     *
+     * @param from - The node that has the dependency.
+     * @param to   - The node that must be processed first.
+     */
+    addEdge(from, to) {
+        if (!this.nodes.has(from) || !this.nodes.has(to)) {
+            return;
+        }
+        const deps = this.edges.get(from);
+        if (deps) {
+            deps.add(to);
+        }
+    }
+    /**
+     * Remove a directed dependency edge.
+     *
+     * @param from - The dependent node.
+     * @param to   - The dependency to remove.
+     */
+    removeEdge(from, to) {
+        const deps = this.edges.get(from);
+        if (deps) {
+            deps.delete(to);
+        }
+    }
+    // ---------------------------------------------------------------
+    // Topological sort (Kahn's algorithm)
+    // ---------------------------------------------------------------
+    /**
+     * Return the nodes in a valid execution order (dependencies first) using
+     * Kahn's algorithm.
+     *
+     * @throws {Error} If the graph contains a cycle (not all nodes can be
+     *   sorted).
+     * @returns An array of {@link GraphNode} in topological order.
+     */
+    topologicalSort() {
+        var _a, _b, _c;
+        if (this.nodes.size === 0) {
+            return [];
+        }
+        // Build in-degree map (number of dependencies each node has)
+        const inDegree = new Map();
+        for (const id of this.nodes.keys()) {
+            inDegree.set(id, 0);
+        }
+        // For Kahn's algorithm we need the *forward* adjacency: for each node,
+        // which other nodes depend on it. We also need the in-degree — the
+        // number of dependencies each node has.
+        const forwardAdj = new Map();
+        for (const id of this.nodes.keys()) {
+            forwardAdj.set(id, []);
+        }
+        for (const [nodeId, deps] of this.edges) {
+            inDegree.set(nodeId, deps.size);
+            for (const depId of deps) {
+                (_a = forwardAdj.get(depId)) === null || _a === void 0 ? void 0 : _a.push(nodeId);
+            }
+        }
+        // Seed the queue with nodes that have zero in-degree
+        const queue = [];
+        for (const [id, deg] of inDegree) {
+            if (deg === 0) {
+                queue.push(id);
+            }
+        }
+        const sorted = [];
+        while (queue.length > 0) {
+            // Sort the queue for deterministic output (alphabetical by id)
+            queue.sort();
+            const id = queue.shift();
+            const node = this.nodes.get(id);
+            if (node) {
+                sorted.push(node);
+            }
+            const dependents = (_b = forwardAdj.get(id)) !== null && _b !== void 0 ? _b : [];
+            for (const depId of dependents) {
+                const newDeg = ((_c = inDegree.get(depId)) !== null && _c !== void 0 ? _c : 1) - 1;
+                inDegree.set(depId, newDeg);
+                if (newDeg === 0) {
+                    queue.push(depId);
+                }
+            }
+        }
+        if (sorted.length !== this.nodes.size) {
+            throw new Error('ProcessingGraph contains a cycle — topological sort is not possible');
+        }
+        return sorted;
+    }
+    // ---------------------------------------------------------------
+    // Parallel groups
+    // ---------------------------------------------------------------
+    /**
+     * Partition the graph into groups of nodes that can be executed in
+     * parallel.
+     *
+     * Each group contains nodes whose dependencies have all been satisfied by
+     * earlier groups. Within a group the nodes are independent and can run
+     * concurrently.
+     *
+     * @throws {Error} If the graph contains a cycle.
+     * @returns An array of arrays — each inner array is a parallel group
+     *   ordered from first-to-execute to last.
+     */
+    getParallelGroups() {
+        var _a, _b, _c;
+        if (this.nodes.size === 0) {
+            return [];
+        }
+        // Build in-degree and forward adjacency (same as topologicalSort)
+        const inDegree = new Map();
+        const forwardAdj = new Map();
+        for (const id of this.nodes.keys()) {
+            inDegree.set(id, 0);
+            forwardAdj.set(id, []);
+        }
+        for (const [nodeId, deps] of this.edges) {
+            inDegree.set(nodeId, deps.size);
+            for (const depId of deps) {
+                (_a = forwardAdj.get(depId)) === null || _a === void 0 ? void 0 : _a.push(nodeId);
+            }
+        }
+        // BFS by levels
+        let currentLevel = [];
+        for (const [id, deg] of inDegree) {
+            if (deg === 0) {
+                currentLevel.push(id);
+            }
+        }
+        const groups = [];
+        let processed = 0;
+        while (currentLevel.length > 0) {
+            // Sort for deterministic ordering
+            currentLevel.sort();
+            const group = [];
+            const nextLevel = [];
+            for (const id of currentLevel) {
+                const node = this.nodes.get(id);
+                if (node) {
+                    group.push(node);
+                    processed++;
+                }
+                const dependents = (_b = forwardAdj.get(id)) !== null && _b !== void 0 ? _b : [];
+                for (const depId of dependents) {
+                    const newDeg = ((_c = inDegree.get(depId)) !== null && _c !== void 0 ? _c : 1) - 1;
+                    inDegree.set(depId, newDeg);
+                    if (newDeg === 0) {
+                        nextLevel.push(depId);
+                    }
+                }
+            }
+            if (group.length > 0) {
+                groups.push(group);
+            }
+            currentLevel = nextLevel;
+        }
+        if (processed !== this.nodes.size) {
+            throw new Error('ProcessingGraph contains a cycle — parallel grouping is not possible');
+        }
+        return groups;
+    }
+    // ---------------------------------------------------------------
+    // Cycle detection (iterative DFS)
+    // ---------------------------------------------------------------
+    /**
+     * Detect whether the graph contains any cycles using iterative DFS.
+     *
+     * @returns `true` if a cycle exists, `false` otherwise.
+     */
+    detectCycles() {
+        var _a;
+        const WHITE = 0; // unvisited
+        const GRAY = 1; // in current DFS path
+        const BLACK = 2; // fully processed
+        const color = new Map();
+        for (const id of this.nodes.keys()) {
+            color.set(id, WHITE);
+        }
+        for (const startId of this.nodes.keys()) {
+            if (color.get(startId) !== WHITE) {
+                continue;
+            }
+            // Iterative DFS using an explicit stack.
+            // Each stack entry is [nodeId, isBacktrack].
+            const stack = [[startId, false]];
+            while (stack.length > 0) {
+                const [nodeId, isBacktrack] = stack.pop();
+                if (isBacktrack) {
+                    color.set(nodeId, BLACK);
+                    continue;
+                }
+                if (color.get(nodeId) === GRAY) {
+                    // Already being visited in this path — cycle detected
+                    return true;
+                }
+                if (color.get(nodeId) === BLACK) {
+                    continue;
+                }
+                color.set(nodeId, GRAY);
+                // Push a backtrack marker so we set BLACK when we unwind
+                stack.push([nodeId, true]);
+                // Push all dependencies (neighbors in the dependency direction)
+                const deps = (_a = this.edges.get(nodeId)) !== null && _a !== void 0 ? _a : new Set();
+                for (const depId of deps) {
+                    const depColor = color.get(depId);
+                    if (depColor === GRAY) {
+                        return true; // back edge → cycle
+                    }
+                    if (depColor === WHITE) {
+                        stack.push([depId, false]);
+                    }
+                }
+            }
+        }
+        return false;
+    }
+    // ---------------------------------------------------------------
+    // Dependency queries
+    // ---------------------------------------------------------------
+    /**
+     * Return the ids of all nodes that `nodeId` directly depends on
+     * (its prerequisites).
+     *
+     * @param nodeId - The node to query.
+     * @returns An array of dependency node ids, or an empty array if the node
+     *   has no dependencies or does not exist.
+     */
+    getDependencies(nodeId) {
+        const deps = this.edges.get(nodeId);
+        return deps ? [...deps] : [];
+    }
+    /**
+     * Return the ids of all nodes that directly depend on `nodeId`
+     * (its consumers / dependents).
+     *
+     * @param nodeId - The node to query.
+     * @returns An array of dependent node ids.
+     */
+    getDependents(nodeId) {
+        const result = [];
+        for (const [id, deps] of this.edges) {
+            if (deps.has(nodeId)) {
+                result.push(id);
+            }
+        }
+        return result;
+    }
+    // ---------------------------------------------------------------
+    // Housekeeping
+    // ---------------------------------------------------------------
+    /**
+     * Remove all nodes and edges from the graph.
+     */
+    clear() {
+        this.nodes.clear();
+        this.edges.clear();
+    }
+}
+//# sourceMappingURL=ProcessingGraph.js.map

package/dist/audio/ProcessingGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessingGraph.js","sourceRoot":"","sources":["../../src/audio/ProcessingGraph.ts"],"names":[],"mappings":"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"}

package/dist/audio/SourceCache.d.ts

@@ -0,0 +1,124 @@
+/**
+ * SourceCache — an LRU cache for decoded audio buffers keyed by source id.
+ *
+ * Inspired by Ardour's `SourceFactory` / `Source::DecodeCache`
+ * (`libs/ardour/source_factory.cc`).
+ *
+ * Large sessions can reference hundreds of audio files.  Decoding them on
+ * demand is expensive, but keeping *every* decoded buffer in memory is not
+ * always feasible.  `SourceCache` strikes a balance by caching up to a
+ * configurable memory limit and evicting least-recently-used entries when
+ * the limit is exceeded.
+ *
+ * This class has **no** external dependencies (no audio framework imports)
+ * and can be unit-tested in isolation.
+ *
+ * @example
+ * ```ts
+ * const cache = new SourceCache(256); // 256 MB limit
+ *
+ * cache.set('kick.wav', decodedBuffer);
+ *
+ * const buf = cache.get('kick.wav');  // cache hit
+ * console.log(cache.getCacheHitRate()); // 1.0
+ * ```
+ *
+ * @module SourceCache
+ */
+/**
+ * SourceCache provides an LRU (least-recently-used) cache for
+ * {@link AudioBuffer} instances, bounded by a configurable memory limit.
+ */
+export declare class SourceCache {
+    /** Map of source id to cache entry. */
+    private cache;
+    /** Maximum allowed memory usage in bytes. */
+    private maxMemoryBytes;
+    /** Running total of cached memory in bytes. */
+    private currentMemoryBytes;
+    /** Number of successful cache lookups. */
+    private hits;
+    /** Number of cache misses. */
+    private misses;
+    /**
+     * @param maxMemoryMB - Maximum cache size in megabytes.  Defaults to
+     *   512 MB.
+     */
+    constructor(maxMemoryMB?: number);
+    /**
+     * Retrieve a cached {@link AudioBuffer} by source id.
+     *
+     * On a hit the entry's `lastAccess` timestamp is refreshed so it is less
+     * likely to be evicted.
+     *
+     * @param sourceId - Unique identifier for the audio source.
+     * @returns The cached buffer, or `null` on a miss.
+     */
+    get(sourceId: string): AudioBuffer | null;
+    /**
+     * Add or replace an {@link AudioBuffer} in the cache.
+     *
+     * If inserting the buffer would exceed the memory limit, LRU entries are
+     * evicted first.  If the buffer itself is larger than the entire cache
+     * limit it is still stored (after evicting everything), allowing
+     * single-buffer lookups to work.
+     *
+     * @param sourceId - Unique identifier for the audio source.
+     * @param buffer   - The decoded audio data to cache.
+     */
+    set(sourceId: string, buffer: AudioBuffer): void;
+    /**
+     * Check whether a source id is present in the cache without affecting
+     * access statistics or the LRU order.
+     *
+     * @param sourceId - The source id to look up.
+     */
+    has(sourceId: string): boolean;
+    /**
+     * Explicitly remove a source from the cache.
+     *
+     * @param sourceId - The source id to remove.
+     */
+    remove(sourceId: string): void;
+    /**
+     * Evict entries using LRU policy until the current memory usage is at or
+     * below the configured limit.
+     *
+     * This is called automatically by {@link set}, but can also be invoked
+     * manually (e.g. after reducing the memory limit at runtime).
+     */
+    evict(): void;
+    /**
+     * Evict the single least-recently-used entry.
+     */
+    private evictOne;
+    /**
+     * Current memory usage in bytes.
+     */
+    getMemoryUsage(): number;
+    /**
+     * Current memory usage in megabytes.
+     */
+    getMemoryUsageMB(): number;
+    /**
+     * Cache hit rate as a ratio `[0, 1]`.
+     *
+     * Returns `0` if no lookups have been performed yet.
+     */
+    getCacheHitRate(): number;
+    /**
+     * Number of entries currently in the cache.
+     */
+    get size(): number;
+    /**
+     * Remove all entries from the cache and reset statistics.
+     */
+    clear(): void;
+    /**
+     * Estimate the memory footprint of a decoded {@link AudioBuffer}.
+     *
+     * Each channel is a `Float32Array` (4 bytes per sample).
+     */
+    private estimateBufferSize;
+}
+//# sourceMappingURL=SourceCache.d.ts.map

package/dist/audio/SourceCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceCache.d.ts","sourceRoot":"","sources":["../../src/audio/SourceCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH;;;GAGG;AACH,qBAAa,WAAW;IACpB,uCAAuC;IACvC,OAAO,CAAC,KAAK,CAAsC;IAEnD,6CAA6C;IAC7C,OAAO,CAAC,cAAc,CAAS;IAE/B,+CAA+C;IAC/C,OAAO,CAAC,kBAAkB,CAAK;IAI/B,0CAA0C;IAC1C,OAAO,CAAC,IAAI,CAAK;IACjB,8BAA8B;IAC9B,OAAO,CAAC,MAAM,CAAK;IAEnB;;;OAGG;gBACS,WAAW,GAAE,MAAY;IAQrC;;;;;;;;OAQG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAWzC;;;;;;;;;;OAUG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IA0BhD;;;;;OAKG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI9B;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAY9B;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;IASb;;OAEG;IACH,OAAO,CAAC,QAAQ;IAoBhB;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;;;OAIG;IACH,eAAe,IAAI,MAAM;IAKzB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;IAWb;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;CAG7B"}