dzql 0.2.0 → 0.2.2

package/README.md

@@ -4,11 +4,12 @@ PostgreSQL-powered framework with automatic CRUD operations, live query subscrip
 
 ## Documentation
 
-- **[Getting Started Guide](docs/GETTING_STARTED.md)** - Complete tutorial with working todo app
-- **[API Reference](docs/REFERENCE.md)** - Complete API documentation
-- **[Live Query Subscriptions](../../docs/SUBSCRIPTIONS_QUICK_START.md)** - Real-time denormalized documents (NEW in v0.2.0)
+- **[Documentation Hub](docs/)** - Complete documentation index
+- **[Getting Started Tutorial](docs/getting-started/tutorial.md)** - Complete tutorial with working todo app
+- **[API Reference](docs/reference/api.md)** - Complete API documentation
+- **[Live Query Subscriptions](docs/getting-started/subscriptions-quick-start.md)** - Real-time denormalized documents (NEW in v0.2.0)
 - **[Compiler Documentation](docs/compiler/)** - Entity compilation guide and coding standards
-- **[Claude Guide](docs/CLAUDE.md)** - Development guide for AI assistants
+- **[Claude Guide](docs/for-ai/claude-guide.md)** - Development guide for AI assistants
 - **[Venues Example](../venues/)** - Full working application
 
 ## Quick Install
@@ -55,6 +56,21 @@ const result = compiler.compileFromSQL(sqlContent);
 
 See **[Compiler Documentation](docs/compiler/)** for complete usage guide, coding standards, and advanced features.
 
+## Testing
+
+```bash
+# Start test database
+cd tests/test-utils && docker compose up -d
+
+# Run tests
+bun test
+
+# Stop database
+cd tests/test-utils && docker compose down
+```
+
+All tests use `bun:test` framework with automatic database setup/teardown. See **[tests/test-utils/README.md](tests/test-utils/README.md)** for details.
+
 ## License
 
 MIT

package/docs/README.md

@@ -0,0 +1,71 @@
+# DZQL Documentation
+
+Complete documentation for the DZQL PostgreSQL-powered framework.
+
+## 📚 Getting Started
+
+New to DZQL? Start here:
+
+- **[Tutorial](getting-started/tutorial.md)** - Complete step-by-step guide with a working todo app
+- **[Subscriptions Quick Start](getting-started/subscriptions-quick-start.md)** - Get real-time subscriptions working in 5 minutes
+
+## 📖 Guides
+
+Feature-specific guides and how-tos:
+
+- **[Live Query Subscriptions](guides/subscriptions.md)** - Real-time denormalized documents
+- **[Client Stores](guides/client-stores.md)** - Pinia store patterns for Vue.js
+
+## 📘 Reference
+
+Complete API documentation:
+
+- **[API Reference](reference/api.md)** - The 5 operations, entities, permissions, graph rules
+- **[Client API](reference/client.md)** - WebSocket client and connection management
+- **[Compiler](compiler/)** - Entity compilation, code generation, and coding standards
+
+### Compiler Documentation
+
+- [Quickstart](compiler/QUICKSTART.md) - Get started with the DZQL compiler
+- [Advanced Filters](compiler/ADVANCED_FILTERS.md) - Complex search operators
+- [Coding Standards](compiler/CODING_STANDARDS.md) - Best practices for DZQL code
+- [Comparison](compiler/COMPARISON.md) - DZQL vs other approaches
+
+## 🤖 For AI Assistants
+
+- **[Claude Guide](for-ai/claude-guide.md)** - Complete guide for AI-assisted DZQL development
+
+## 🔗 Quick Links
+
+- [npm Package](https://www.npmjs.com/package/dzql)
+- [GitHub Repository](https://github.com/blueshed/dzql)
+- [Issue Tracker](https://github.com/blueshed/dzql/issues)
+- [Changelog](../../../CHANGELOG.md)
+- [Contributing](../../../CONTRIBUTING.md)
+
+## 🏗️ Architecture
+
+Looking for architecture and design docs? See the [repository docs](../../../docs/):
+
+- [Permissions System](../../../docs/architecture/PERMISSIONS.md)
+- [Project Roadmap](../../../docs/architecture/ROADMAP.md)
+- [Subscription Architecture](../../../docs/architecture/SUBSCRIPTIONS_STRATEGY.md)
+
+## 🧪 Development
+
+Contributing to DZQL? See development documentation:
+
+- [TDD Workflow](../../../docs/development/TDD_WORKFLOW.md)
+- [WebSocket Testing](../../../docs/development/WEBSOCKET_TESTING.md)
+- [Claude Web Setup](../../../docs/development/CLAUDE-WEB.md)
+
+## 📦 Package Contents
+
+This documentation is published with the npm package. For repository-wide documentation (contributors, development workflow, architecture), see [`/docs/`](../../../docs/) in the repository root.
+
+## Need Help?
+
+- 📖 Check the guides above
+- 🐛 [Report an issue](https://github.com/blueshed/dzql/issues)
+- 💬 [Start a discussion](https://github.com/blueshed/dzql/discussions)
+- 🤖 Ask your AI assistant (they have access to this documentation!)

package/docs/compiler/README.md

@@ -0,0 +1,84 @@
+# DZQL Compiler Documentation
+
+The DZQL Compiler transforms declarative entity definitions into optimized PostgreSQL stored procedures.
+
+## Quick Start
+
+- **[Quickstart Guide](QUICKSTART.md)** - Get started with the compiler in 5 minutes
+
+## Guides
+
+- **[Advanced Filters](ADVANCED_FILTERS.md)** - Complex search operators and patterns
+- **[Coding Standards](CODING_STANDARDS.md)** - Best practices for DZQL code
+
+## Reference
+
+- **[Comparison](COMPARISON.md)** - How DZQL compares to other approaches
+- **[Session Summary](SESSION_SUMMARY.md)** - Development session documentation
+- **[Summary](SUMMARY.md)** - Compiler overview and architecture
+- **[Overnight Build](OVERNIGHT_BUILD.md)** - Batch compilation process
+
+## Using the Compiler
+
+### Via CLI
+
+```bash
+dzql compile database/domain.sql -o compiled/
+```
+
+### Programmatically
+
+```javascript
+import { DZQLCompiler } from 'dzql/compiler';
+
+const compiler = new DZQLCompiler();
+const result = compiler.compileFromSQL(sqlContent);
+
+console.log(result.sql);  // Generated PostgreSQL
+```
+
+### Registering Entities
+
+```sql
+SELECT dzql.register_entity(
+  'todos',                              -- Table name
+  'title',                              -- Label field
+  array['title', 'description'],        -- Searchable fields
+  '{}'::jsonb,                          -- FK includes
+  false,                                -- Soft delete
+  '{}'::jsonb,                          -- Graph rules
+  jsonb_build_object(                   -- Notification paths
+    'owner', array['@user_id']
+  ),
+  jsonb_build_object(                   -- Permission paths
+    'view', array['@user_id'],
+    'create', array['@user_id'],
+    'update', array['@user_id'],
+    'delete', array['@user_id']
+  ),
+  '{}'::jsonb                           -- Temporal config
+);
+```
+
+This generates 5 PostgreSQL functions:
+- `get_todos(params, user_id)` - Retrieve single record
+- `save_todos(params, user_id)` - Create or update
+- `delete_todos(params, user_id)` - Delete record
+- `lookup_todos(params, user_id)` - Autocomplete
+- `search_todos(params, user_id)` - Search with filters
+
+## Architecture
+
+The compiler uses a three-phase approach:
+
+1. **Parse** - Extract entity definitions from SQL
+2. **Generate** - Create optimized PostgreSQL functions
+3. **Deploy** - Execute generated SQL
+
+All business logic runs in PostgreSQL, not application code.
+
+## See Also
+
+- [Main Documentation](../) - Full DZQL documentation
+- [API Reference](../reference/api.md) - The 5 operations
+- [For AI](../for-ai/claude-guide.md) - AI-assisted development

package/docs/{CLAUDE.md → for-ai/claude-guide.md}

@@ -1163,7 +1163,7 @@ array['name', 'address', 'city', 'description', 'notes', 'tags', 'metadata']
 
 ## Additional Resources
 
-- **API Reference**: See [packages/dzql/REFERENCE.md](packages/dzql/REFERENCE.md) for complete API documentation
-- **Tutorial**: See [packages/dzql/GETTING_STARTED.md](packages/dzql/GETTING_STARTED.md) for hands-on guide
+- **API Reference**: See [API Reference](../reference/api.md) for complete API documentation
+- **Tutorial**: See [Getting Started Tutorial](../getting-started/tutorial.md) for hands-on guide
 - **Examples**: See `packages/venues/` for complete working application
 - **Tests**: See `packages/venues/tests/` for comprehensive test patterns

package/docs/getting-started/subscriptions-quick-start.md

@@ -0,0 +1,203 @@
+# Live Query Subscriptions - Quick Start
+
+Get up and running with live query subscriptions in 5 minutes.
+
+## Step 1: Create a Subscribable (2 min)
+
+Create `my_subscribable.sql`:
+
+```sql
+SELECT dzql.register_subscribable(
+  'venue_detail',                                               -- Name (use in API)
+  '{"subscribe": ["@org_id->acts_for[org_id=$]{active}.user_id"]}'::jsonb,  -- Who can subscribe
+  '{"venue_id": "int"}'::jsonb,                                -- Subscription parameters
+  'venues',                                                     -- Root table
+  '{"org": "organisations", "sites": {"entity": "sites", "filter": "venue_id=$venue_id"}}'::jsonb  -- Related data
+);
+```
+
+## Step 2: Compile and Deploy (1 min)
+
+```bash
+# Compile to PostgreSQL functions
+bun packages/dzql/src/compiler/cli/compile-subscribable.js my_subscribable.sql | psql $DATABASE_URL
+```
+
+This creates 3 functions:
+- `venue_detail_can_subscribe(user_id, params)` - permission check
+- `get_venue_detail(params, user_id)` - query builder
+- `venue_detail_affected_documents(table, op, old, new)` - change detector
+
+## Step 3: Subscribe from Client (2 min)
+
+```javascript
+import { WebSocketManager } from '@dzql/client';
+
+const ws = new WebSocketManager('ws://localhost:3000/ws');
+await ws.connect();
+
+// Subscribe - get initial data + live updates
+const { data, unsubscribe } = await ws.api.subscribe_venue_detail(
+  { venue_id: 123 },
+  (updatedData) => {
+    console.log('Venue changed!', updatedData);
+  }
+);
+
+console.log('Initial data:', data);
+
+// Later: cleanup
+await unsubscribe();
+```
+
+## That's It!
+
+Your client now receives real-time updates whenever:
+- The venue record changes
+- Related organisation changes
+- Related sites change
+
+All change detection happens in PostgreSQL - zero configuration needed on the server!
+
+## Next Steps
+
+- [Full Documentation](../guides/subscriptions.md)
+- [Permission Paths Guide](../../../../docs/architecture/PERMISSIONS.md)
+- [API Reference](../reference/api.md)
+
+## Common Patterns
+
+### Simple Document (Single Table)
+
+```sql
+SELECT dzql.register_subscribable(
+  'user_settings',
+  '{"subscribe": ["@user_id"]}'::jsonb,  -- Only owner
+  '{"user_id": "int"}'::jsonb,
+  'user_settings',
+  '{}'::jsonb  -- No relations
+);
+```
+
+### With One Relation
+
+```sql
+SELECT dzql.register_subscribable(
+  'booking_summary',
+  '{"subscribe": ["@user_id"]}'::jsonb,
+  '{"booking_id": "int"}'::jsonb,
+  'bookings',
+  '{"venue": "venues"}'::jsonb  -- Include venue
+);
+```
+
+### With Filtered Relations
+
+```sql
+SELECT dzql.register_subscribable(
+  'organisation_dashboard',
+  '{"subscribe": ["@id->acts_for[org_id=$]{active}.user_id"]}'::jsonb,
+  '{"org_id": "int"}'::jsonb,
+  'organisations',
+  '{
+    "members": {
+      "entity": "acts_for",
+      "filter": "org_id=$org_id AND valid_to IS NULL"
+    },
+    "venues": {
+      "entity": "venues",
+      "filter": "org_id=$org_id"
+    }
+  }'::jsonb
+);
+```
+
+### Multiple Permission Paths (OR logic)
+
+```sql
+SELECT dzql.register_subscribable(
+  'venue_admin',
+  '{
+    "subscribe": [
+      "@owner_id",                                    -- Direct owner
+      "@org_id->acts_for[org_id=$]{active}.user_id"  -- OR org member
+    ]
+  }'::jsonb,
+  '{"venue_id": "int"}'::jsonb,
+  'venues',
+  '{"sites": {"entity": "sites", "filter": "venue_id=$venue_id"}}'::jsonb
+);
+```
+
+## Debugging Tips
+
+### Test the functions manually:
+
+```sql
+-- Check permission
+SELECT venue_detail_can_subscribe(1, '{"venue_id": 123}'::jsonb);
+
+-- Get data
+SELECT get_venue_detail('{"venue_id": 123}'::jsonb, 1);
+
+-- Test change detection
+SELECT venue_detail_affected_documents(
+  'venues',
+  'update',
+  '{"id": 123}'::jsonb,
+  '{"id": 123, "name": "New"}'::jsonb
+);
+```
+
+### Check active subscriptions:
+
+```javascript
+// Client-side
+console.log('My subscriptions:', ws.subscriptions.size);
+```
+
+## FAQ
+
+**Q: When should I use subscriptions vs. simple queries?**
+A: Use subscriptions when data changes frequently and client needs to stay in sync. Use simple queries for one-time lookups.
+
+**Q: What happens when client disconnects?**
+A: Server automatically cleans up all subscriptions for that connection.
+
+**Q: Can multiple clients subscribe to the same data?**
+A: Yes! Each subscription is independent. All will receive updates.
+
+**Q: How do I update the subscribable definition?**
+A: Re-compile and deploy. The `register_subscribable()` call uses `ON CONFLICT UPDATE`, so it's safe to run repeatedly.
+
+**Q: What if the underlying data is deleted?**
+A: The `get_<name>()` function returns `null`. Handle this in your callback:
+```javascript
+(data) => {
+  if (!data) {
+    console.log('Record was deleted');
+    return;
+  }
+  updateUI(data);
+}
+```
+
+**Q: How do I subscribe to a list of items?**
+A: Create a subscribable with array parameters or use multiple subscriptions. For dashboard-style views, consider a single subscribable that returns an array.
+
+## Performance Tips
+
+1. **Index your joins**: Make sure foreign keys are indexed
+2. **Keep _affected_documents() simple**: Early return for unrelated tables
+3. **Limit relation depth**: Avoid deeply nested relations (max 2-3 levels)
+4. **Use specific subscription keys**: `venue_id` is better than `org_id` (fewer false positives)
+5. **Unsubscribe when done**: Always cleanup to free server resources
+
+## Architecture Benefits
+
+- ✅ **PostgreSQL-First**: All logic in database, not application code
+- ✅ **Zero Configuration**: No server changes needed for new subscribables
+- ✅ **Type Safe**: Compiled functions validated at deploy time
+- ✅ **Efficient**: In-memory registry, PostgreSQL does matching
+- ✅ **Secure**: Permission paths enforced at database level
+- ✅ **Scalable**: Stateless server, can add instances freely

package/docs/{GETTING_STARTED.md → getting-started/tutorial.md}

@@ -2,7 +2,7 @@
 
 DZQL is a PostgreSQL framework that gives you **atomic real-time updates** via WebSocket. Every database change broadcasts instantly to all connected clients. Zero boilerplate.
 
-> **See also:** [REFERENCE.md](REFERENCE.md) for complete API documentation | [CLAUDE.md](../../docs/CLAUDE.md) for AI development guide
+> **See also:** [API Reference](../reference/api.md) for complete API documentation | [Claude Guide](../for-ai/claude-guide.md) for AI development guide
 
 ## The Core Pattern