Skip to content

ALPHA-STATUS.md

Latest commit

 

History

History
156 lines (118 loc) · 5.13 KB

ALPHA-STATUS.md

File metadata and controls

156 lines (118 loc) · 5.13 KB

Alpha Status Summary

Version: 0.3.0 Date: November 13, 2025 Status: 🟡 ALPHA - Not Production-Ready

Quick Status

sqlite-graph has solid core functionality (294 tests passing), but is not recommended for production use due to:

  1. No npm package published - Can't be installed via npm install sqlite-graph
  2. Missing files field - package.json doesn't specify what to publish
  3. Jest worker timeouts - 2 test suites failing due to worker process termination (not code bugs)
  4. Advertised features not implemented - enableWAL(), withRetry(), WriteQueue() don't exist
  5. No semver policy - Breaking changes possible before v1.0.0
  6. Alpha disclaimer needed - Users should know this is experimental

What's Actually Working

✅ Core Features (Tested & Working)

  • Node and Edge CRUD operations
  • Fluent query DSL (NodeQuery, TraversalQuery)
  • Graph traversal (BFS/DFS)
  • Shortest path finding
  • Merge operations (mergeNode, mergeEdge)
  • Index management
  • Transactions with savepoints
  • JSON property storage
  • Type-safe TypeScript API

✅ Test Coverage

  • 294 tests passing across 9 test suites
  • 2 test suites failing (Jest worker timeouts, not code bugs)
  • Unit tests: Database, NodeQuery, TraversalQuery, Merge operations
  • Integration tests: job-pipeline, graph-operations

✅ Documentation

  • Comprehensive README
  • API documentation (1,398 lines)
  • SPARC development methodology docs
  • Competitive analysis
  • Benchmark reports
  • Example code (job pipeline, basic usage, etc.)

What's Missing for Production

Critical Blockers

  1. Package Publishing

    • No files field in package.json
    • Never published to npm registry
    • Installation instructions assume published package

  2. Advertised Features Don't Exist

    // README shows these, but they're not implemented:
import { enableWAL, withRetry, WriteQueue } from 'sqlite-graph';

  3. Test Infrastructure Issues

    • Jest worker processes timing out on 2 test suites
    • TraversalQuery.test.ts - SIGTERM
    • graph-operations.test.ts - SIGTERM
    • May need --maxWorkers=1 or timeout configuration

  4. No Versioning Policy

    • Breaking changes possible at any time
    • No changelog for version history
    • No upgrade guides

  5. Documentation Accuracy

    • README claims "production-ready" but PRODUCTION-READINESS.md says "alpha"
    • Concurrency features mentioned but not implemented
    • Performance benchmarks exist but not linked from README

Nice-to-Have (Not Blockers)

  • Pattern matching (advertised but not critical)
  • All paths enumeration (shortest path works)
  • Distributed graph support (future feature)
  • WASM optimization (future feature)

Honest Positioning

What You Can Use It For (NOW)

  • Personal projects - Learning graph databases
  • Prototypes - Testing graph data models
  • Side projects - Non-critical applications
  • Local development - Experimental features

What You Should NOT Use It For

  • Production applications - API might change
  • Mission-critical systems - Not battle-tested
  • npm dependencies - Not published yet
  • Team projects - Breaking changes expected

Roadmap to v1.0.0 (Production-Ready)

Phase 1: Fix Critical Issues (1-2 weeks)

  • Add files field to package.json
  • Remove non-existent features from README
  • Fix Jest worker timeout issues
  • Add version policy and CHANGELOG.md
  • Update all docs to say "alpha" consistently

Phase 2: Stabilize API (2-3 weeks)

  • Freeze breaking changes
  • Add deprecation warnings for future changes
  • Comprehensive error handling tests
  • Edge case coverage (circular refs, orphaned nodes)
  • Performance regression tests

Phase 3: Pre-Release (1 week)

  • Publish alpha to npm (0.x.x-alpha.1)
  • Community feedback period
  • Security audit
  • License review
  • Final documentation pass

Phase 4: v1.0.0 Release

  • Semantic versioning commitment
  • LTS support plan
  • Migration guides
  • Public announcement

Estimated Timeline: 4-6 weeks to production-ready v1.0.0

Recommendation for GitHub

Use this status badge in README:

**Status:** 🟡 Alpha - Experimental, not for production use

⚠️ **API may change without notice** - This library is in active development. Use at your own risk for non-critical projects.

Honest Competitive Position

  • vs simple-graph: sqlite-graph has better API (fluent vs SQL), but simple-graph is stable and published
  • vs Cozo: Cozo is production-ready with 100K+ QPS, sqlite-graph is experimental
  • vs LiteGraph: Both are new (2025), but LiteGraph targets .NET and vectors
  • vs Neo4j: Not comparable - Neo4j is enterprise-grade, sqlite-graph is a prototype

Market Reality: sqlite-graph is a promising alpha that needs 4-6 weeks to compete.

Bottom Line

Can you use it? Yes, for side projects and learning. Should you rely on it? No, not yet. When will it be ready? Estimated 4-6 weeks (late December 2025 / early January 2026)

Current honest tagline: "Alpha-stage graph database experiment. Promising start, not ready for production."