@statezero/core 0.1.0

package/package.json

@@ -0,0 +1,123 @@
+{
+  "name": "@statezero/core",
+  "version": "0.1.0",
+  "type": "module",
+  "module": "ESNext",
+  "description": "The type-safe frontend client for StateZero - connect directly to your backend models with zero boilerplate",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "statezero": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./cli": {
+      "import": "./dist/cli/index.js",
+      "require": "./dist/cli/index.js"
+    },
+    "./react": {
+      "import": "./dist/react-entry.js",
+      "require": "./dist/react-entry.js"
+    },
+    "./vue": {
+      "import": "./dist/vue-entry.js",
+      "require": "./dist/vue-entry.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest run --config=vitest.base.config.ts",
+    "test:e2e": "vitest run --config=vitest.sequential.config.ts tests/e2e",
+    "generate:test-apps": "ts-node scripts/generate-test-apps.js",
+    "test:adaptors": "playwright test tests/adaptors",
+    "test:coverage": "vitest run --coverage",
+    "build": "tsc",
+    "parse-queries": "node scripts/perfect-query-parser.js",
+    "sync-models": "node src/cli/index.js sync-models",
+    "sync-models:dev": "npx cross-env NODE_ENV=test npm run sync-models",
+    "clean": "npx rimraf dist",
+    "prepare": "npm run clean && npm run build",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "typescript",
+    "orm",
+    "backend",
+    "frontend",
+    "database",
+    "sql",
+    "django",
+    "sqlalchemy",
+    "react",
+    "vue",
+    "svelte"
+  ],
+  "author": "Robert Herring <robert.herring@resipilot.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/state-zero/statezero-client.git"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "homepage": "https://www.statezero.dev",
+  "dependencies": {
+    "axios": "^1.7.9",
+    "cli-progress": "^3.12.0",
+    "cosmiconfig": "^9.0.0",
+    "cosmiconfig-typescript-loader": "^6.1.0",
+    "date-fns": "^4.1.0",
+    "dotenv": "^16.4.7",
+    "fs-extra": "^11.3.0",
+    "handlebars": "^4.7.8",
+    "idb": "^8.0.2",
+    "inquirer": "^12.4.2",
+    "lodash-es": "^4.17.21",
+    "luxon": "^3.6.1",
+    "mathjs": "^14.4.0",
+    "mitt": "^3.0.1",
+    "mobx": "^6.13.7",
+    "mobx-utils": "^6.1.0",
+    "object-hash": "^3.0.0",
+    "openapi-typescript": "^6.7.1",
+    "p-queue": "^8.1.0",
+    "pusher-js": "^8.4.0",
+    "rfdc": "^1.4.1",
+    "sift": "^17.1.3",
+    "superjson": "^2.2.2",
+    "uuid": "^11.1.0",
+    "yargs": "^17.7.2",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.50.1",
+    "@types/cli-progress": "^3.11.6",
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "^22.13.1",
+    "@types/react": "^18.3.18",
+    "@types/yargs": "^17.0.32",
+    "@vitest/coverage-v8": "^3.0.5",
+    "fake-indexeddb": "^6.0.0",
+    "fast-glob": "^3.3.3",
+    "react": "^18.2.0",
+    "rimraf": "^5.0.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5",
+    "vue": "^3.2.0"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "bugs": {
+    "url": "https://github.com/state-zero/statezero-client/issues"
+  },
+  "directories": {
+    "test": "tests"
+  }
+}

package/readme.md

@@ -0,0 +1,222 @@
+# StateZero
+
+**The Real-Time Django to JavaScript Data Bridge**
+
+Connect your Django backend to React/Vue frontends with 90% less code. No repetitive serializers, views, or tight coupling.
+
+## Why StateZero?
+
+**The Problem:** Building modern web apps means writing the same CRUD logic three times - Django models, REST API serializers/views, and frontend data fetching. This creates:
+
+- 80% of app complexity in data shuttling
+- 50% of your codebase devoted to API glue
+- Hundreds of hours maintaining sync between frontend and backend
+
+**The Solution:** StateZero eliminates the API layer entirely. Write Django models once, query them directly from JavaScript with the same ORM syntax you already know.
+
+## Features
+
+✨ **Django ORM Syntax in JavaScript** - Use `.filter()`, `.exclude()`, `.orderBy()` exactly like Django  
+⚡ **Real-Time Updates** - UI automatically updates when backend data changes  
+🔒 **Django Permissions** - Your existing permission classes work on the frontend  
+📝 **Auto-Generated TypeScript** - Perfect type safety from your Django models  
+🚀 **Optimistic Updates** - UI feels instant, syncs in background  
+🔗 **Deep Relationships** - Traverse foreign keys naturally: `todo.category.name`
+
+## Quick Example
+
+### 1. Register Your Django Model
+
+```python
+# todos/crud.py
+from statezero.adaptors.django.config import registry
+from .models import Todo
+
+registry.register(Todo)
+```
+
+### 2. Query From JavaScript Like Django
+
+```javascript
+// Get all incomplete todos, ordered by priority
+const todos = Todo.objects
+  .filter({ is_completed: false })
+  .orderBy("-priority", "created_at");
+
+// Complex queries with relationships
+const urgentWorkTodos = Todo.objects.filter({
+  priority: "high",
+  category__name: "Work",
+  due_date__lt: "2024-12-31",
+});
+
+// Django-style field lookups
+const searchResults = Todo.objects.filter({
+  title__icontains: "meeting",
+  created_by__email__endswith: "@company.com",
+});
+```
+
+### 3. Real-Time Updates in One Line
+
+```vue
+<script setup>
+import { useQueryset } from "@statezero/core/vue";
+
+// This list automatically updates when todos change
+const todos = useQueryset(() => Todo.objects.filter({ is_completed: false }));
+</script>
+
+<template>
+  <div v-for="todo in todos.fetch({ limit: 10 })" :key="todo.id">
+    {{ todo.title }}
+  </div>
+</template>
+```
+
+## The Magic: Optimistic vs Confirmed
+
+### Optimistic (Instant UI)
+
+```javascript
+// UI updates immediately, syncs later
+const newTodo = Todo.objects.create({
+  title: "Buy groceries",
+  priority: "medium",
+});
+
+// Edit optimistically
+todo.title = "Buy organic groceries";
+todo.save(); // UI updates instantly
+
+// Delete optimistically
+todo.delete(); // Gone from UI immediately
+```
+
+### Confirmed (Wait for Server)
+
+```javascript
+// Wait for server confirmation
+const confirmedTodo = await Todo.objects.create({
+  title: "Important meeting",
+});
+
+// Wait for update confirmation
+await todo.save();
+
+// Wait for deletion confirmation
+await todo.delete();
+```
+
+## Advanced Django ORM Features
+
+### Complex Filtering with Q Objects
+
+```javascript
+import { Q } from "@statezero/core";
+
+// Multiple OR conditions
+const urgentTodos = Todo.objects.filter({
+  Q: [Q("OR", { priority: "high" }, { due_date__lt: "tomorrow" })],
+});
+
+// Nested conditions
+const myImportantTodos = Todo.objects.filter({
+  Q: [
+    Q(
+      "AND",
+      { assigned_to: currentUser.id },
+      Q("OR", { priority: "high" }, { is_flagged: true })
+    ),
+  ],
+});
+```
+
+### Aggregation & F Expressions
+
+```javascript
+import { F } from "@statezero/core";
+
+// Count, sum, average like Django
+const todoCount = await Todo.objects.count();
+const avgPriority = await Todo.objects.avg("priority_score");
+
+// Database-level calculations
+await Product.objects.update({
+  view_count: F("view_count + 1"),
+  popularity: F("likes * 2 + shares"),
+});
+```
+
+### Get or Create
+
+```javascript
+// Just like Django's get_or_create
+const [todo, created] = await Todo.objects.getOrCreate(
+  { title: "Daily standup" },
+  { defaults: { priority: "medium", category: workCategory } }
+);
+```
+
+### Relationship Traversal
+
+```javascript
+// Access related objects naturally
+const todo = await Todo.objects.get({ id: 1 });
+console.log(todo.category.name); // Foreign key
+console.log(todo.created_by.username); // Another FK
+console.log(todo.comments.length); // Reverse FK
+
+// Filter by relationships
+const workTodos = Todo.objects.filter({
+  category__name: "Work",
+  assigned_to__department__name: "Engineering",
+});
+```
+
+## Installation
+
+### Backend
+
+```bash
+pip install git+https://github.com/state-zero/statezero
+pip install django-cors-headers pusher
+```
+
+### Frontend
+
+```bash
+npm install https://github.com/state-zero/statezero-client
+```
+
+### Generate TypeScript Models
+
+```bash
+npx statezero sync-models
+```
+
+## Why Choose StateZero Over...
+
+**🆚 HTMX:** Use modern React/Vue with full JavaScript ecosystem while keeping backend simplicity
+
+**🆚 Firebase/Supabase:** Keep your Django backend, models, and business logic. No vendor lock-in.
+
+**🆚 OpenAPI/GraphQL:** Get real-time updates and Django ORM power, not just basic CRUD
+
+**🆚 Traditional REST APIs:** Write 90% less boilerplate. Focus on features, not data plumbing.
+
+## Pricing
+
+StateZero uses a no-rugpull license model:
+
+- **$0/month** for companies with revenue up to $3M
+- **$75/month** for companies with revenue up to $7.5M
+- **$200/month** for companies with revenue up to $20M
+- **$500/month** for companies with revenue up to $100M
+- **$1,000/month** for companies with revenue above $100M
+
+Lock in your rate forever by signing up early. We can't change your fee or cancel your license.
+
+## Get Started
+
+Run `pip install git+https://github.com/state-zero/statezero` and `npm install https://github.com/state-zero/statezero-client` to begin.