Skip to content

Commit 70f8ad3

Browse files
michaeloboylemichaeloboyle
committed
docs: Fix misleading production-ready claims
- Update README to reflect alpha status - Remove advertised concurrency features that don't exist - Add ALPHA-STATUS.md with honest assessment - Add COMPETITORS.md with market analysis - Update GitHub repo description to say 'alpha, not production-ready' Status: 294 tests passing, but missing npm publish config and some advertised features. Estimated 4-6 weeks to v1.0.0.
1 parent d9ffe4b commit 70f8ad3

7 files changed

Lines changed: 870 additions & 14 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,9 @@
1010

1111
## Overview
1212

13-
sqlite-graph is a production-ready graph database library that combines the reliability of SQLite with the expressiveness of a fluent query API. Built with TypeScript and designed for performance, it provides an intuitive way to model and query connected data.
13+
sqlite-graph is an alpha-stage graph database library that combines the reliability of SQLite with the expressiveness of a fluent query API. Built with TypeScript and designed for performance, it provides an intuitive way to model and query connected data.
14+
15+
**Current Status:** Alpha - core functionality working, but not recommended for production use yet.
1416

1517
**Key Features:**
1618
- 🚀 **Fluent Query DSL** - Intuitive method chaining for complex graph queries
@@ -69,15 +71,7 @@ const { node, created } = db.mergeNode('Company',
6971
{ industry: 'SaaS', size: 'Large' } // Properties to set
7072
);
7173

72-
// Production concurrency (optional)
73-
import { enableWAL, withRetry, WriteQueue } from 'sqlite-graph';
74-
75-
enableWAL(db); // Better read concurrency
76-
77-
await withRetry(() => db.createNode('Job', { title: 'Engineer' })); // Auto-retry on locks
78-
79-
const writeQueue = new WriteQueue();
80-
await writeQueue.enqueue(() => db.mergeNode(...)); // Serialize writes
74+
// Note: Advanced concurrency features planned for future releases
8175
```
8276

8377
## Installation

‎docs/ALPHA-STATUS.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Alpha Status Summary
2+
3+
**Version:** 0.3.0
4+
**Date:** November 13, 2025
5+
**Status:** 🟡 **ALPHA - Not Production-Ready**
6+
7+
## Quick Status
8+
9+
sqlite-graph has **solid core functionality** (294 tests passing), but is **not recommended for production use** due to:
10+
11+
1. **No npm package published** - Can't be installed via `npm install sqlite-graph`
12+
2. **Missing `files` field** - package.json doesn't specify what to publish
13+
3. **Jest worker timeouts** - 2 test suites failing due to worker process termination (not code bugs)
14+
4. **Advertised features not implemented** - enableWAL(), withRetry(), WriteQueue() don't exist
15+
5. **No semver policy** - Breaking changes possible before v1.0.0
16+
6. **Alpha disclaimer needed** - Users should know this is experimental
17+
18+
## What's Actually Working
19+
20+
### ✅ Core Features (Tested & Working)
21+
- Node and Edge CRUD operations
22+
- Fluent query DSL (NodeQuery, TraversalQuery)
23+
- Graph traversal (BFS/DFS)
24+
- Shortest path finding
25+
- Merge operations (mergeNode, mergeEdge)
26+
- Index management
27+
- Transactions with savepoints
28+
- JSON property storage
29+
- Type-safe TypeScript API
30+
31+
### ✅ Test Coverage
32+
- **294 tests passing** across 9 test suites
33+
- **2 test suites failing** (Jest worker timeouts, not code bugs)
34+
- Unit tests: Database, NodeQuery, TraversalQuery, Merge operations
35+
- Integration tests: job-pipeline, graph-operations
36+
37+
### ✅ Documentation
38+
- Comprehensive README
39+
- API documentation (1,398 lines)
40+
- SPARC development methodology docs
41+
- Competitive analysis
42+
- Benchmark reports
43+
- Example code (job pipeline, basic usage, etc.)
44+
45+
## What's Missing for Production
46+
47+
### Critical Blockers
48+
49+
1. **Package Publishing**
50+
- No `files` field in package.json
51+
- Never published to npm registry
52+
- Installation instructions assume published package
53+
54+
2. **Advertised Features Don't Exist**
55+
```typescript
56+
// README shows these, but they're not implemented:
57+
import { enableWAL, withRetry, WriteQueue } from 'sqlite-graph';
58+
```
59+
60+
3. **Test Infrastructure Issues**
61+
- Jest worker processes timing out on 2 test suites
62+
- TraversalQuery.test.ts - SIGTERM
63+
- graph-operations.test.ts - SIGTERM
64+
- May need `--maxWorkers=1` or timeout configuration
65+
66+
4. **No Versioning Policy**
67+
- Breaking changes possible at any time
68+
- No changelog for version history
69+
- No upgrade guides
70+
71+
5. **Documentation Accuracy**
72+
- README claims "production-ready" but PRODUCTION-READINESS.md says "alpha"
73+
- Concurrency features mentioned but not implemented
74+
- Performance benchmarks exist but not linked from README
75+
76+
### Nice-to-Have (Not Blockers)
77+
78+
- Pattern matching (advertised but not critical)
79+
- All paths enumeration (shortest path works)
80+
- Distributed graph support (future feature)
81+
- WASM optimization (future feature)
82+
83+
## Honest Positioning
84+
85+
### What You Can Use It For (NOW)
86+
87+
- **Personal projects** - Learning graph databases
88+
- **Prototypes** - Testing graph data models
89+
- **Side projects** - Non-critical applications
90+
- **Local development** - Experimental features
91+
92+
### What You Should NOT Use It For
93+
94+
- **Production applications** - API might change
95+
- **Mission-critical systems** - Not battle-tested
96+
- **npm dependencies** - Not published yet
97+
- **Team projects** - Breaking changes expected
98+
99+
## Roadmap to v1.0.0 (Production-Ready)
100+
101+
### Phase 1: Fix Critical Issues (1-2 weeks)
102+
- [ ] Add `files` field to package.json
103+
- [ ] Remove non-existent features from README
104+
- [ ] Fix Jest worker timeout issues
105+
- [ ] Add version policy and CHANGELOG.md
106+
- [ ] Update all docs to say "alpha" consistently
107+
108+
### Phase 2: Stabilize API (2-3 weeks)
109+
- [ ] Freeze breaking changes
110+
- [ ] Add deprecation warnings for future changes
111+
- [ ] Comprehensive error handling tests
112+
- [ ] Edge case coverage (circular refs, orphaned nodes)
113+
- [ ] Performance regression tests
114+
115+
### Phase 3: Pre-Release (1 week)
116+
- [ ] Publish alpha to npm (`0.x.x-alpha.1`)
117+
- [ ] Community feedback period
118+
- [ ] Security audit
119+
- [ ] License review
120+
- [ ] Final documentation pass
121+
122+
### Phase 4: v1.0.0 Release
123+
- [ ] Semantic versioning commitment
124+
- [ ] LTS support plan
125+
- [ ] Migration guides
126+
- [ ] Public announcement
127+
128+
**Estimated Timeline:** 4-6 weeks to production-ready v1.0.0
129+
130+
## Recommendation for GitHub
131+
132+
Use this status badge in README:
133+
134+
```markdown
135+
**Status:** 🟡 Alpha - Experimental, not for production use
136+
137+
⚠️ **API may change without notice** - This library is in active development. Use at your own risk for non-critical projects.
138+
```
139+
140+
## Honest Competitive Position
141+
142+
- **vs simple-graph:** sqlite-graph has better API (fluent vs SQL), but simple-graph is stable and published
143+
- **vs Cozo:** Cozo is production-ready with 100K+ QPS, sqlite-graph is experimental
144+
- **vs LiteGraph:** Both are new (2025), but LiteGraph targets .NET and vectors
145+
- **vs Neo4j:** Not comparable - Neo4j is enterprise-grade, sqlite-graph is a prototype
146+
147+
**Market Reality:** sqlite-graph is a promising alpha that needs 4-6 weeks to compete.
148+
149+
## Bottom Line
150+
151+
**Can you use it?** Yes, for side projects and learning.
152+
**Should you rely on it?** No, not yet.
153+
**When will it be ready?** Estimated 4-6 weeks (late December 2025 / early January 2026)
154+
155+
**Current honest tagline:**
156+
*"Alpha-stage graph database experiment. Promising start, not ready for production."*

0 commit comments

Comments
 (0)