dzql 0.6.0 → 0.6.1

package/docs/README.md

@@ -1,6 +1,20 @@
-# TZQL: The Compile-Only Realtime Database Framework
+# DZQL: The Compile-Only Realtime Database Framework
 
-TZQL ("The Zero Query Language") is a PostgreSQL-native framework for building realtime, reactive applications without the runtime overhead or complexity of traditional ORMs or BaaS solutions.
+DZQL ("Database Zero Query Language") is a PostgreSQL-native framework for building realtime, reactive applications without the runtime overhead or complexity of traditional ORMs or BaaS solutions.
+
+## Quick Start
+
+The fastest way to get started is with `bun create`:
+
+```bash
+bun create dzql my-app
+cd my-app
+bun install
+bun run db:rebuild
+bun run dev
+```
+
+This creates a full-stack app with Vue/Vite frontend, DZQL server, and PostgreSQL database.
 
 ## The Problem
 
@@ -10,11 +24,11 @@ Building realtime apps is hard. You typically have to:
 3.  **Handle Atomicity:** Ensure that complex operations (e.g., "Create Order + Reserve Inventory + Notify User") happen in a single transaction.
 4.  **Optimistic Updates:** Write complex client-side logic to "guess" the server's response, often leading to data divergence.
 
-## The TZQL Solution
+## The DZQL Solution
 
-TZQL takes a radically different approach: **Compilation**.
+DZQL takes a radically different approach: **Compilation**.
 
-Instead of a heavy runtime framework, you define your **Domain Schema** (Entities, Relationships, Permissions) in a simple TypeScript configuration. TZQL compiles this definition into:
+Instead of a heavy runtime framework, you define your **Domain Schema** (Entities, Relationships, Permissions) in a simple TypeScript configuration. DZQL compiles this definition into:
 
 1.  **Optimized SQL:** Specialized PostgreSQL functions (`save_order`, `get_product`) with *inlined* permission checks and *atomic* graph operations.
 2.  **Type-Safe Client SDK:** A generated TypeScript client that knows your exact API surface.
@@ -28,7 +42,9 @@ Instead of a heavy runtime framework, you define your **Domain Schema** (Entitie
 *   **Realtime by Default:** Every database write emits an atomic event batch. The client SDK automatically patches your local state. No "refetching" required.
 *   **JavaScript/TypeScript Native:** Define your schema in code you understand, get full type safety end-to-end.
 
-## Quick Start
+## Manual Setup
+
+If you prefer to set up manually instead of using `bun create dzql`:
 
 ### 1. Define your Domain (`domain.ts`)
 
@@ -51,13 +67,13 @@ export const subscribables = {
 ### 2. Compile
 
 ```bash
-bun run tzql compile domain.ts -o src/generated
+bunx dzql domain.ts -o generated
 ```
 
 ### 3. Use in Client
 
 ```typescript
-import { usePostFeedStore } from '@/generated/client/stores';
+import { usePostFeedStore } from '@generated/client/stores';
 
 const feed = usePostFeedStore();
 // Automatically fetches data AND subscribes to realtime updates
@@ -76,10 +92,10 @@ const { data, loading } = await feed.bind({ user_id: 1 });
 ## Package Exports
 
 ```typescript
-import { ... } from 'tzql';           // Runtime server
-import { ... } from 'tzql/client';    // WebSocket client SDK  
-import { ... } from 'tzql/compiler';  // CLI compiler
-import { TzqlNamespace } from 'tzql/namespace';  // CLI/invokej integration
+import { ... } from 'dzql';           // Runtime server
+import { ... } from 'dzql/client';    // WebSocket client SDK  
+import { ... } from 'dzql/compiler';  // CLI compiler
+import { DzqlNamespace } from 'dzql/namespace';  // CLI/invokej integration
 ```
 
 ## Client Connection & Authentication
@@ -96,7 +112,7 @@ When a client connects to the WebSocket server, it immediately receives a `conne
 ### Client API
 
 ```typescript
-import { WebSocketManager } from 'tzql/client';
+import { WebSocketManager } from 'dzql/client';
 
 const ws = new WebSocketManager();
 await ws.connect('ws://localhost:3000/ws');

package/docs/for_ai.md

@@ -1,10 +1,22 @@
-# TZQL Guide for AI Assistants
+# DZQL Guide for AI Assistants
 
-This document defines the patterns and conventions for generating valid TZQL domain definitions. Use this guide when asked to "Create a TZQL app" or "Add an entity".
+This document defines the patterns and conventions for generating valid DZQL domain definitions. Use this guide when asked to "Create a DZQL app" or "Add an entity".
+
+## Quick Start
+
+The fastest way to create a new DZQL app:
+
+```bash
+bun create dzql my-app
+cd my-app
+bun install
+bun run db:rebuild
+bun run dev
+```
 
 ## Core Concept: The Domain Definition
 
-A TZQL application is defined by a single TypeScript/JavaScript module exporting `entities` and `subscribables`.
+A DZQL application is defined by a single TypeScript/JavaScript module exporting `entities` and `subscribables`.
 
 ### 1. Entity Definition Pattern
 
@@ -523,7 +535,7 @@ When a client connects to the WebSocket server, it immediately receives a `conne
 ### WebSocketManager API
 
 ```typescript
-import { WebSocketManager } from 'tzql/client';
+import { WebSocketManager } from 'dzql/client';
 
 const ws = new WebSocketManager();
 await ws.connect('ws://localhost:3000/ws');
@@ -574,13 +586,13 @@ TZQL provides a namespace export for CLI tools like `invokej` to interact with t
 
 ```typescript
 // cli.ts or server-side script
-import { TzqlNamespace } from 'tzql/namespace';
+import { DzqlNamespace } from 'dzql/namespace';
 import postgres from 'postgres';
 
 const sql = postgres(process.env.DATABASE_URL);
 const manifest = await import('./dist/runtime/manifest.json');
 
-const tzql = new TzqlNamespace(sql, manifest);
+const dzql = new DzqlNamespace(sql, manifest);
 ```
 
 ### CRUD Operations

package/docs/project-setup.md

@@ -1,6 +1,24 @@
-# TZQL Project Setup Guide
+# DZQL Project Setup Guide
 
-Complete guide for setting up a Vue/Pinia client project with TZQL.
+Complete guide for setting up a Vue/Pinia client project with DZQL.
+
+## Quick Start
+
+The fastest way to get started is with `bun create`:
+
+```bash
+bun create dzql my-app
+cd my-app
+bun install
+bun run db:rebuild
+bun run dev
+```
+
+This creates a full-stack app with the structure described below.
+
+## Manual Setup
+
+If you prefer to set up manually:
 
 ## Project Structure
 
@@ -40,14 +58,14 @@ Root `package.json`:
   "private": true,
   "workspaces": ["src", "server"],
   "scripts": {
-    "compile": "tzql compile domain.js -o generated",
+    "compile": "bunx dzql domain.js -o generated",
     "db": "docker compose down -v && docker compose up -d",
     "logs": "docker compose logs -f",
     "dev": "concurrently -n server,client -c blue,green \"bun run --filter @my-app/server dev\" \"bun run --filter @my-app/client dev\""
   },
   "devDependencies": {
     "concurrently": "^9.2.1",
-    "tzql": "link:tzql"
+    "dzql": "^0.6.0"
   }
 }
 ```
@@ -87,7 +105,7 @@ Server `server/package.json`:
     "dev": "cd .. && bun run server/index.ts"
   },
   "dependencies": {
-    "tzql": "link:tzql"
+    "dzql": "^0.6.0"
   }
 }
 ```
@@ -99,7 +117,13 @@ Server `server/package.json`:
 Server `server/index.ts`:
 
 ```typescript
-import "tzql";
+import { createServer } from "dzql";
+
+const server = createServer({
+  port: process.env.PORT || 3000,
+});
+
+console.log(`DZQL Server running on port ${server.port}`);
 ```
 
 ## 2. Docker Compose for PostgreSQL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Database-first real-time framework with TypeScript support",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -11,10 +11,16 @@ import { writeFileSync, mkdirSync, copyFileSync, rmSync } from "fs";
 import { resolve, dirname } from "path";
 
 const args = process.argv.slice(2);
-const command = args[0];
-const input = args[1];
+let command = args[0];
+let input = args[1];
 let outputDir = "dist"; // Default output directory
 
+// If first arg looks like a file (ends with .ts or .js), treat it as compile target
+if (command && (command.endsWith('.ts') || command.endsWith('.js'))) {
+  input = command;
+  command = 'compile';
+}
+
 // Parse optional output directory flag
 const outputFlagIndex = args.indexOf('-o');
 const longOutputFlagIndex = args.indexOf('--output');
@@ -26,11 +32,11 @@ if (outputFlagIndex > -1 && args[outputFlagIndex + 1]) {
 }
 
 async function main() {
-  console.log("TZQL Compiler v0.0.1");
+  console.log("DZQL Compiler v0.6.0");
 
   if (command === "compile") {
     if (!input) {
-      console.error("Usage: tzql compile <file>");
+      console.error("Usage: dzql <file> or dzql compile <file>");
       process.exit(1);
     }
 
@@ -88,10 +94,6 @@ async function main() {
 
       // Phase 4: Generate Manifest
       const manifest = generateManifest(ir);
-      console.log(`[Compiler] Manifest functions: ${Object.keys(manifest.functions).length}`);
-      if (!manifest.functions['subscribe_venue_detail']) {
-          console.error("[Compiler] ERROR: subscribe_venue_detail missing from manifest functions!");
-      }
 
       // --- OUTPUT GENERATION ---
 

package/src/create/.env.example

@@ -1,8 +0,0 @@
-# Database connection
-DATABASE_URL=postgres://{{name}}:{{name}}@localhost:5432/{{name}}
-
-# JWT Secret (change in production!)
-JWT_SECRET=dev-secret-change-in-production
-
-# Server port
-PORT=3000

package/src/create/README.md

@@ -1,101 +0,0 @@
-# {{name}}
-
-A real-time database application powered by [DZQL](https://github.com/blueshed/dzql).
-
-## Quick Start
-
-```bash
-# Start PostgreSQL
-bun run db:up
-
-# Copy environment file
-cp .env.example .env
-
-# Compile domain and generate SQL
-bun run compile
-
-# Run migrations
-bun run db:migrate
-
-# Start development server
-bun run dev
-```
-
-## Project Structure
-
-```
-├── domain.ts        # Entity definitions and subscriptions
-├── server.ts        # Runtime server configuration
-├── compose.yml      # Docker Compose for PostgreSQL
-├── dist/            # Generated output (after compile)
-│   ├── db/          # SQL migrations
-│   ├── runtime/     # Server manifest
-│   └── client/      # TypeScript SDK & Pinia stores
-└── .env             # Environment variables
-```
-
-## Domain Definition
-
-Edit `domain.ts` to define your entities:
-
-```typescript
-export const entities = {
-  posts: {
-    schema: {
-      id: 'serial PRIMARY KEY',
-      title: 'text NOT NULL',
-      content: 'text'
-    },
-    permissions: {
-      view: [],
-      create: [],
-      update: ['@author_id'],
-      delete: ['@author_id']
-    }
-  }
-};
-```
-
-## API Endpoints
-
-After starting the server:
-
-- **WebSocket**: `ws://localhost:3000/ws`
-- **Health**: `GET http://localhost:3000/health`
-
-## Client Usage
-
-```typescript
-import { TzqlClient } from './dist/client';
-
-const client = new TzqlClient('ws://localhost:3000/ws');
-
-// Register
-await client.api.register_user({ 
-  email: 'user@example.com', 
-  password: 'secret' 
-});
-
-// Login
-const { token } = await client.api.login_user({ 
-  email: 'user@example.com', 
-  password: 'secret' 
-});
-
-// CRUD operations
-const post = await client.api.save_posts({ 
-  title: 'Hello World' 
-});
-
-// Real-time subscription
-await client.api.subscribe_post_detail(
-  { post_id: post.id }, 
-  (data) => console.log('Updated:', data)
-);
-```
-
-## Learn More
-
-- [DZQL Documentation](https://github.com/blueshed/dzql)
-- [Graph Rules](https://github.com/blueshed/dzql/docs/guides/graph-rules.md)
-- [Subscriptions](https://github.com/blueshed/dzql/docs/guides/subscriptions.md)

package/src/create/compose.yml

@@ -1,14 +0,0 @@
-services:
-  postgres:
-    image: postgres:16
-    environment:
-      POSTGRES_USER: {{name}}
-      POSTGRES_PASSWORD: {{name}}
-      POSTGRES_DB: {{name}}
-    ports:
-      - "5432:5432"
-    volumes:
-      - pgdata:/var/lib/postgresql/data
-
-volumes:
-  pgdata:

package/src/create/domain.ts

@@ -1,153 +0,0 @@
-// domain.ts - DZQL Domain Definition
-// Run: bunx dzql domain.ts
-
-export const entities = {
-
-  // Users table with authentication
-  users: {
-    schema: {
-      id: 'serial PRIMARY KEY',
-      name: 'text NOT NULL',
-      email: 'text UNIQUE NOT NULL',
-      password_hash: 'text NOT NULL',
-      created_at: 'timestamptz DEFAULT now()'
-    },
-    label: 'name',
-    searchable: ['name', 'email'],
-    hidden: ['password_hash'],
-    permissions: {
-      view: [],
-      create: [],
-      update: ['@id'],  // Users can only update themselves
-      delete: []
-    }
-  },
-
-  // Posts table with author relationship
-  posts: {
-    schema: {
-      id: 'serial PRIMARY KEY',
-      author_id: 'int NOT NULL REFERENCES users(id)',
-      title: 'text NOT NULL',
-      content: 'text',
-      published: 'boolean DEFAULT false',
-      created_at: 'timestamptz DEFAULT now()',
-      updated_at: 'timestamptz'
-    },
-    label: 'title',
-    searchable: ['title', 'content'],
-    includes: {
-      author: 'users'
-    },
-    fieldDefaults: {
-      author_id: '@user_id',
-      created_at: '@now'
-    },
-    permissions: {
-      view: [],  // Anyone can view
-      create: [],  // Anyone logged in can create
-      update: ['@author_id'],  // Only author can update
-      delete: ['@author_id']   // Only author can delete
-    },
-    graphRules: {
-      on_create: {
-        notify_followers: {
-          description: 'Notify when new post is created',
-          actions: [
-            {
-              type: 'reactor',
-              name: 'new_post',
-              params: { post_id: '@id', author_id: '@author_id' }
-            }
-          ]
-        }
-      },
-      on_update: {
-        track_updates: {
-          description: 'Set updated_at on edit',
-          condition: "@before.title != @after.title OR @before.content != @after.content",
-          actions: [
-            {
-              type: 'update',
-              target: 'posts',
-              data: { updated_at: '@now' },
-              match: { id: '@id' }
-            }
-          ]
-        }
-      }
-    }
-  },
-
-  // Comments on posts
-  comments: {
-    schema: {
-      id: 'serial PRIMARY KEY',
-      post_id: 'int NOT NULL REFERENCES posts(id) ON DELETE CASCADE',
-      author_id: 'int NOT NULL REFERENCES users(id)',
-      content: 'text NOT NULL',
-      created_at: 'timestamptz DEFAULT now()'
-    },
-    label: 'content',
-    searchable: ['content'],
-    includes: {
-      post: 'posts',
-      author: 'users'
-    },
-    fieldDefaults: {
-      author_id: '@user_id',
-      created_at: '@now'
-    },
-    permissions: {
-      view: [],
-      create: [],
-      update: ['@author_id'],
-      delete: ['@author_id', '@post_id->posts.author_id']  // Author or post owner can delete
-    }
-  }
-
-};
-
-// Real-time subscriptions
-export const subscribables = {
-
-  // Post detail with comments
-  post_detail: {
-    params: {
-      post_id: 'int'
-    },
-    root: {
-      entity: 'posts',
-      key: 'post_id'
-    },
-    includes: {
-      author: 'users',
-      comments: {
-        entity: 'comments',
-        includes: {
-          author: 'users'
-        }
-      }
-    },
-    scopeTables: ['posts', 'users', 'comments'],
-    canSubscribe: []  // Anyone can subscribe
-  },
-
-  // User's posts feed
-  my_posts: {
-    params: {},
-    root: {
-      entity: 'users',
-      key: '@user_id'
-    },
-    includes: {
-      posts: {
-        entity: 'posts',
-        filter: { author_id: '@user_id' }
-      }
-    },
-    scopeTables: ['users', 'posts'],
-    canSubscribe: []
-  }
-
-};

package/src/create/package.json

@@ -1,24 +0,0 @@
-{
-  "name": "{{name}}",
-  "version": "0.0.1",
-  "type": "module",
-  "scripts": {
-    "dev": "bun run --watch server.ts",
-    "compile": "bunx dzql domain.ts",
-    "db:up": "docker compose up -d",
-    "db:down": "docker compose down",
-    "db:migrate": "bun run compile && psql $DATABASE_URL -f dist/db/migrations/*.sql"
-  },
-  "dependencies": {
-    "dzql": "^0.6.0",
-    "postgres": "^3.4.3"
-  },
-  "devDependencies": {
-    "@types/bun": "latest",
-    "typescript": "^5.0.0"
-  },
-  "bun-create": {
-    "postinstall": ["./setup.sh", "rm setup.sh"],
-    "start": "bun run dev"
-  }
-}

package/src/create/server.ts

@@ -1,18 +0,0 @@
-// server.ts - DZQL Runtime Server
-import { createServer } from "dzql";
-
-const server = createServer({
-  manifestPath: "./dist/runtime/manifest.json",
-  jwtSecret: process.env.JWT_SECRET || "dev-secret-change-in-production",
-});
-
-const port = process.env.PORT || 3000;
-
-console.log(`DZQL Server running at http://localhost:${port}`);
-console.log(`WebSocket endpoint: ws://localhost:${port}/ws`);
-
-export default {
-  port,
-  fetch: server.fetch,
-  websocket: server.websocket,
-};

package/src/create/setup.sh

@@ -1,11 +0,0 @@
-#!/bin/bash
-# Replace {{name}} with project name from package.json
-NAME=$(grep -o '"name": *"[^"]*"' package.json | head -1 | cut -d'"' -f4)
-if [ -z "$NAME" ] || [ "$NAME" = "{{name}}" ]; then
-  NAME=$(basename "$PWD")
-fi
-sed -i.bak "s/{{name}}/$NAME/g" compose.yml .env.example README.md package.json 2>/dev/null || \
-sed -i "s/{{name}}/$NAME/g" compose.yml .env.example README.md package.json
-cp .env.example .env
-rm -f compose.yml.bak .env.example.bak README.md.bak package.json.bak
-echo "✓ Configured project: $NAME"

package/src/create/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "outDir": "./dist",
-    "rootDir": ".",
-    "types": ["bun-types"]
-  },
-  "include": ["*.ts", "domain.ts"],
-  "exclude": ["node_modules", "dist"]
-}