learngraph 0.1.1 → 0.2.0

package/dist/esm/storage/base.js

@@ -0,0 +1,221 @@
+/**
+ * Base class and utilities for storage adapters
+ *
+ * @packageDocumentation
+ */
+import { createSkillId, createEdgeId } from '../types/index.js';
+import { NotConnectedError, ValidationError } from './errors.js';
+/**
+ * Generate a unique ID with optional prefix
+ */
+export function generateId(prefix = '') {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 10);
+    return prefix ? `${prefix}_${timestamp}${random}` : `${timestamp}${random}`;
+}
+/**
+ * Get current ISO timestamp
+ */
+export function nowISO() {
+    return new Date().toISOString();
+}
+/**
+ * Convert SkillNodeInput to full SkillNode with generated fields
+ */
+export function inputToSkillNode(input) {
+    const now = nowISO();
+    const node = {
+        id: input.id ?? createSkillId(generateId('skill')),
+        name: input.name,
+        description: input.description,
+        bloomLevel: input.bloomLevel,
+        difficulty: input.difficulty,
+        isThresholdConcept: input.isThresholdConcept,
+        masteryThreshold: input.masteryThreshold,
+        estimatedMinutes: input.estimatedMinutes,
+        tags: input.tags,
+        metadata: input.metadata,
+        createdAt: now,
+        updatedAt: now,
+    };
+    // Only add optional fields if they have values
+    if (input.standardAlignment !== undefined) {
+        node.standardAlignment = input.standardAlignment;
+    }
+    if (input.domain !== undefined) {
+        node.domain = input.domain;
+    }
+    if (input.gradeLevel !== undefined) {
+        node.gradeLevel = input.gradeLevel;
+    }
+    return node;
+}
+/**
+ * Convert PrerequisiteEdgeInput to full PrerequisiteEdge with generated fields
+ */
+export function inputToEdge(input) {
+    const edge = {
+        id: input.id ?? createEdgeId(generateId('edge')),
+        sourceId: input.sourceId,
+        targetId: input.targetId,
+        strength: input.strength,
+        type: input.type,
+        metadata: input.metadata,
+        createdAt: nowISO(),
+    };
+    // Only add optional fields if they have values
+    if (input.reasoning !== undefined) {
+        edge.reasoning = input.reasoning;
+    }
+    return edge;
+}
+/**
+ * Validate skill input data
+ */
+export function validateSkillInput(input) {
+    if (!input.name || input.name.trim().length === 0) {
+        throw new ValidationError('Skill name is required', 'name');
+    }
+    if (input.difficulty < 0 || input.difficulty > 1) {
+        throw new ValidationError('Difficulty must be between 0 and 1', 'difficulty', input.difficulty);
+    }
+    if (input.masteryThreshold < 0 || input.masteryThreshold > 1) {
+        throw new ValidationError('Mastery threshold must be between 0 and 1', 'masteryThreshold', input.masteryThreshold);
+    }
+    if (input.estimatedMinutes < 0) {
+        throw new ValidationError('Estimated minutes cannot be negative', 'estimatedMinutes', input.estimatedMinutes);
+    }
+}
+/**
+ * Validate edge input data
+ */
+export function validateEdgeInput(input) {
+    if (!input.sourceId) {
+        throw new ValidationError('Source skill ID is required', 'sourceId');
+    }
+    if (!input.targetId) {
+        throw new ValidationError('Target skill ID is required', 'targetId');
+    }
+    if (input.sourceId === input.targetId) {
+        throw new ValidationError('Edge cannot reference the same skill as source and target', 'sourceId', input.sourceId);
+    }
+    if (input.strength < 0 || input.strength > 1) {
+        throw new ValidationError('Edge strength must be between 0 and 1', 'strength', input.strength);
+    }
+}
+/**
+ * Ensure adapter is connected before operations
+ */
+export function requireConnection(connected) {
+    if (!connected) {
+        throw new NotConnectedError();
+    }
+}
+/**
+ * Calculate graph statistics from nodes and edges
+ */
+export function calculateStats(nodes, edges) {
+    const inDegree = new Map();
+    const outDegree = new Map();
+    // Initialize degree maps
+    for (const node of nodes) {
+        inDegree.set(node.id, 0);
+        outDegree.set(node.id, 0);
+    }
+    // Count degrees
+    for (const edge of edges) {
+        const source = edge.sourceId;
+        const target = edge.targetId;
+        outDegree.set(source, (outDegree.get(source) || 0) + 1);
+        inDegree.set(target, (inDegree.get(target) || 0) + 1);
+    }
+    // Count roots (no prerequisites / in-degree 0)
+    let rootCount = 0;
+    let leafCount = 0;
+    for (const node of nodes) {
+        if (inDegree.get(node.id) === 0)
+            rootCount++;
+        if (outDegree.get(node.id) === 0)
+            leafCount++;
+    }
+    // Calculate bloom distribution
+    const bloomDistribution = {
+        remember: 0,
+        understand: 0,
+        apply: 0,
+        analyze: 0,
+        evaluate: 0,
+        create: 0,
+    };
+    for (const node of nodes) {
+        bloomDistribution[node.bloomLevel] =
+            (bloomDistribution[node.bloomLevel] || 0) + 1;
+    }
+    // Calculate difficulty distribution
+    const difficultyDistribution = {
+        foundational: 0,
+        basic: 0,
+        intermediate: 0,
+        advanced: 0,
+        expert: 0,
+    };
+    for (const node of nodes) {
+        if (node.difficulty <= 0.2)
+            difficultyDistribution.foundational++;
+        else if (node.difficulty <= 0.4)
+            difficultyDistribution.basic++;
+        else if (node.difficulty <= 0.6)
+            difficultyDistribution.intermediate++;
+        else if (node.difficulty <= 0.8)
+            difficultyDistribution.advanced++;
+        else
+            difficultyDistribution.expert++;
+    }
+    // Calculate max depth via BFS from all roots
+    let maxDepth = 0;
+    const adjacency = new Map();
+    for (const edge of edges) {
+        const source = edge.sourceId;
+        const target = edge.targetId;
+        if (!adjacency.has(source))
+            adjacency.set(source, []);
+        adjacency.get(source).push(target);
+    }
+    function bfsMaxDepth(startId) {
+        const queue = [
+            { id: startId, depth: 0 },
+        ];
+        let max = 0;
+        while (queue.length > 0) {
+            const { id, depth } = queue.shift();
+            max = Math.max(max, depth);
+            const neighbors = adjacency.get(id) || [];
+            for (const neighbor of neighbors) {
+                queue.push({ id: neighbor, depth: depth + 1 });
+            }
+        }
+        return max;
+    }
+    // Find max depth from all root nodes
+    for (const node of nodes) {
+        if (inDegree.get(node.id) === 0) {
+            maxDepth = Math.max(maxDepth, bfsMaxDepth(node.id));
+        }
+    }
+    // Calculate averages
+    const totalInDegree = Array.from(inDegree.values()).reduce((a, b) => a + b, 0);
+    const totalOutDegree = Array.from(outDegree.values()).reduce((a, b) => a + b, 0);
+    return {
+        nodeCount: nodes.length,
+        edgeCount: edges.length,
+        thresholdConceptCount: nodes.filter((n) => n.isThresholdConcept).length,
+        rootNodeCount: rootCount,
+        leafNodeCount: leafCount,
+        maxDepth,
+        avgPrerequisites: nodes.length > 0 ? totalInDegree / nodes.length : 0,
+        avgDependents: nodes.length > 0 ? totalOutDegree / nodes.length : 0,
+        bloomDistribution,
+        difficultyDistribution,
+    };
+}
+//# sourceMappingURL=base.js.map

package/dist/esm/storage/base.js.map

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

package/dist/esm/storage/errors.js

@@ -0,0 +1,116 @@
+/**
+ * Storage-specific errors for LearnGraph
+ *
+ * @packageDocumentation
+ */
+/**
+ * Base error class for storage operations
+ */
+export class StorageError extends Error {
+    code;
+    cause;
+    constructor(message, code, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'StorageError';
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+/**
+ * Thrown when connection to storage backend fails
+ */
+export class ConnectionError extends StorageError {
+    constructor(message, cause) {
+        super(message, 'CONNECTION_ERROR', cause);
+        this.name = 'ConnectionError';
+    }
+}
+/**
+ * Thrown when attempting operation without active connection
+ */
+export class NotConnectedError extends StorageError {
+    constructor() {
+        super('Not connected to storage backend', 'NOT_CONNECTED');
+        this.name = 'NotConnectedError';
+    }
+}
+/**
+ * Thrown when a skill or edge is not found
+ */
+export class NotFoundError extends StorageError {
+    entityType;
+    entityId;
+    constructor(entityType, entityId) {
+        super(`${entityType} not found: ${entityId}`, 'NOT_FOUND');
+        this.entityType = entityType;
+        this.entityId = entityId;
+        this.name = 'NotFoundError';
+    }
+}
+/**
+ * Thrown when attempting to create a duplicate entity
+ */
+export class DuplicateError extends StorageError {
+    entityType;
+    entityId;
+    constructor(entityType, entityId) {
+        super(`${entityType} already exists: ${entityId}`, 'DUPLICATE');
+        this.entityType = entityType;
+        this.entityId = entityId;
+        this.name = 'DuplicateError';
+    }
+}
+/**
+ * Thrown when edge references non-existent skill
+ */
+export class ReferenceError extends StorageError {
+    edgeId;
+    missingSkillId;
+    role;
+    constructor(edgeId, missingSkillId, role) {
+        super(`Edge ${edgeId} references non-existent ${role} skill: ${missingSkillId}`, 'REFERENCE_ERROR');
+        this.edgeId = edgeId;
+        this.missingSkillId = missingSkillId;
+        this.role = role;
+        this.name = 'ReferenceError';
+    }
+}
+/**
+ * Thrown when data validation fails
+ */
+export class ValidationError extends StorageError {
+    field;
+    value;
+    constructor(message, field, value) {
+        super(message, 'VALIDATION_ERROR');
+        this.field = field;
+        this.value = value;
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Thrown when a query times out
+ */
+export class TimeoutError extends StorageError {
+    operation;
+    timeoutMs;
+    constructor(operation, timeoutMs) {
+        super(`Operation "${operation}" timed out after ${timeoutMs}ms`, 'TIMEOUT');
+        this.operation = operation;
+        this.timeoutMs = timeoutMs;
+        this.name = 'TimeoutError';
+    }
+}
+/**
+ * Thrown when a cycle is detected in the graph
+ */
+export class CycleDetectedError extends StorageError {
+    path;
+    constructor(path) {
+        super(`Cycle detected in graph: ${path.join(' -> ')}`, 'CYCLE_DETECTED');
+        this.path = path;
+        this.name = 'CycleDetectedError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/storage/errors.js.map

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

package/dist/esm/storage/index.js

@@ -1,11 +1,76 @@
 /**
- * Graph storage adapters
+ * Graph storage adapters for LearnGraph
+ *
+ * Provides a unified interface for storing skill graphs with multiple
+ * backend options:
+ * - **MemoryStorage**: In-memory storage for testing
+ * - **LevelGraphStorage**: Browser/local storage using triples
+ * - **Neo4jStorage**: Production graph database
+ *
+ * @example
+ * ```typescript
+ * import { MemoryStorage, Neo4jStorage, LevelGraphStorage } from 'learngraph/storage';
+ *
+ * // For testing
+ * const testStorage = new MemoryStorage();
+ * await testStorage.connect({ backend: 'memory' });
+ *
+ * // For browser/local development
+ * const localStorage = new LevelGraphStorage();
+ * await localStorage.connect({ backend: 'levelgraph', path: './my-graph' });
+ *
+ * // For production
+ * const prodStorage = new Neo4jStorage();
+ * await prodStorage.connect({
+ *   backend: 'neo4j',
+ *   uri: 'bolt://localhost:7687',
+ *   username: 'neo4j',
+ *   password: 'password',
+ * });
+ *
+ * // Same API for all!
+ * const skill = await storage.createSkill({ ... });
+ * const prereqs = await storage.getPrerequisitesOf(skill.id);
+ * ```
  *
  * @packageDocumentation
  */
-export {};
-// Storage adapters will be implemented in Phase 2
-// export { Neo4jStorage } from './neo4j.js';
-// export { LevelGraphStorage } from './levelgraph.js';
-// export { MemoryStorage } from './memory.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Storage Errors
+// ─────────────────────────────────────────────────────────────────────────────
+export { StorageError, ConnectionError, NotConnectedError, NotFoundError, DuplicateError, ReferenceError, ValidationError, TimeoutError, CycleDetectedError, } from './errors.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Base Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+export { generateId, nowISO, inputToSkillNode, inputToEdge, validateSkillInput, validateEdgeInput, calculateStats, } from './base.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Storage Adapters
+// ─────────────────────────────────────────────────────────────────────────────
+export { MemoryStorage } from './memory.js';
+export { LevelGraphStorage } from './levelgraph.js';
+export { Neo4jStorage } from './neo4j.js';
+import { MemoryStorage } from './memory.js';
+import { LevelGraphStorage } from './levelgraph.js';
+import { Neo4jStorage } from './neo4j.js';
+/**
+ * Create a storage adapter based on configuration.
+ *
+ * @example
+ * ```typescript
+ * const storage = createStorage({ backend: 'memory' });
+ * await storage.connect({ backend: 'memory' });
+ * ```
+ */
+export function createStorage(config) {
+    switch (config.backend) {
+        case 'memory':
+            return new MemoryStorage();
+        case 'levelgraph':
+            return new LevelGraphStorage();
+        case 'neo4j':
+            return new Neo4jStorage();
+        default:
+            throw new Error(`Unknown storage backend: ${config.backend}`);
+    }
+}
 //# sourceMappingURL=index.js.map

package/dist/esm/storage/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;;AAeH,kDAAkD;AAClD,6CAA6C;AAC7C,uDAAuD;AACvD,+CAA+C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAkBH,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAChF,OAAO,EACL,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,cAAc,EACd,eAAe,EACf,YAAY,EACZ,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAChF,OAAO,EACL,UAAU,EACV,MAAM,EACN,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,GACf,MAAM,WAAW,CAAC;AAEnB,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,QAAQ,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,KAAK,QAAQ;YACX,OAAO,IAAI,aAAa,EAAE,CAAC;QAC7B,KAAK,YAAY;YACf,OAAO,IAAI,iBAAiB,EAAE,CAAC;QACjC,KAAK,OAAO;YACV,OAAO,IAAI,YAAY,EAAE,CAAC;QAC5B;YACE,MAAM,IAAI,KAAK,CAAC,4BAA6B,MAAwB,CAAC,OAAO,EAAE,CAAC,CAAC;IACrF,CAAC;AACH,CAAC"}