@statezero/core 0.2.16 → 0.2.17

package/readme.md

@@ -1,210 +1,210 @@
-# 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" },
-  { 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 statezero
-pip install django-cors-headers pusher
-```
-
-### Frontend
-
-```bash
-npm i @statezero/core
-```
-
-### Generate TypeScript Models
-
-```bash
-npx @statezero/core sync
-```
-
-## 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.
-
-## Get Started
-
-Run `pip install statezero` and `npm install @statezero/core` to begin.
+# 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" },
+  { 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 statezero
+pip install django-cors-headers pusher
+```
+
+### Frontend
+
+```bash
+npm i @statezero/core
+```
+
+### Generate TypeScript Models
+
+```bash
+npx @statezero/core sync
+```
+
+## 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.
+
+## Get Started
+
+Run `pip install statezero` and `npm install @statezero/core` to begin.

package/dist/actions/backend1/django_app/calculate-hash.d.ts

@@ -1,57 +0,0 @@
-/**
- * Calculate hash of input text (demonstrates string processing)
- *
- * @param string text - Text to hash
- * @param 'md5' | 'sha1' | 'sha256' algorithm - Hash algorithm to use
- * @param {Object} [axiosOverrides] - Allows overriding Axios request parameters.
- * @returns {Promise<Object>} A promise that resolves with the action's result.
- */
-export function calculateHash(text: any, algorithm?: string, axiosOverrides?: Object): Promise<Object>;
-export namespace calculateHash {
-    let actionName: string;
-    let title: string;
-    let app: string;
-    let permissions: string[];
-    let configKey: string;
-}
-/**
- * Zod schema for the input of calculateHash.
- * NOTE: This is an object schema for validating the data payload.
- */
-export const calculateHashInputSchema: z.ZodObject<{
-    text: z.ZodString;
-    algorithm: z.ZodDefault<z.ZodOptional<z.ZodEnum<["md5", "sha1", "sha256"]>>>;
-}, "strip", z.ZodTypeAny, {
-    algorithm: "md5" | "sha1" | "sha256";
-    text: string;
-}, {
-    text: string;
-    algorithm?: "md5" | "sha1" | "sha256" | undefined;
-}>;
-/**
- * Zod schema for the response of calculateHash.
- */
-export const calculateHashResponseSchema: z.ZodObject<{
-    original_text: z.ZodString;
-    algorithm: z.ZodString;
-    hash: z.ZodString;
-    text_length: z.ZodNumber;
-    processed_by: z.ZodString;
-    processed_at: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    original_text: string;
-    algorithm: string;
-    hash: string;
-    text_length: number;
-    processed_by: string;
-    processed_at: string;
-}, {
-    original_text: string;
-    algorithm: string;
-    hash: string;
-    text_length: number;
-    processed_by: string;
-    processed_at: string;
-}>;
-export default calculateHash;
-import { z } from 'zod';

package/dist/actions/backend1/django_app/calculate-hash.js

@@ -1,80 +0,0 @@
-/**
- * This file was auto-generated. Do not make direct changes to the file.
- * Action: Calculate Hash
- * App: django_app
- */
-import axios from 'axios';
-import { z } from 'zod';
-import { configInstance, parseStateZeroError, serializeActionPayload } from '../../../../src';
-import actionSchema from './calculate-hash.schema.json' assert { type: 'json' };
-/**
- * Zod schema for the input of calculateHash.
- * NOTE: This is an object schema for validating the data payload.
- */
-export const calculateHashInputSchema = z.object({ text: z.string(),
-    algorithm: z.enum(["md5", "sha1", "sha256"]).optional().default("sha256") });
-/**
- * Zod schema for the response of calculateHash.
- */
-export const calculateHashResponseSchema = z.object({ original_text: z.string(),
-    algorithm: z.string(),
-    hash: z.string(),
-    text_length: z.number().int(),
-    processed_by: z.string(),
-    processed_at: z.string().datetime({ message: "Invalid ISO 8601 datetime string" }) });
-/**
- * Calculate hash of input text (demonstrates string processing)
- *
- * @param string text - Text to hash
- * @param 'md5' | 'sha1' | 'sha256' algorithm - Hash algorithm to use
- * @param {Object} [axiosOverrides] - Allows overriding Axios request parameters.
- * @returns {Promise<Object>} A promise that resolves with the action's result.
- */
-export async function calculateHash(text, algorithm = "sha256", axiosOverrides = {}) {
-    // Construct the data payload from the function arguments
-    const rawPayload = {
-        text,
-        algorithm
-    };
-    // Serialize payload - handles model instances (extracts PK), files, dates, etc.
-    const payload = serializeActionPayload(rawPayload, actionSchema.input_properties);
-    const config = configInstance.getConfig();
-    const backend = config.backendConfigs['backend1'];
-    if (!backend) {
-        throw new Error(`No backend configuration found for key: backend1`);
-    }
-    const baseUrl = backend.API_URL.replace(/\/+$/, '');
-    const actionUrl = `${baseUrl}/actions/calculate_hash/`;
-    const headers = backend.getAuthHeaders ? backend.getAuthHeaders() : {};
-    try {
-        const response = await axios.post(actionUrl, payload, {
-            headers: { 'Content-Type': 'application/json', ...headers },
-            ...axiosOverrides,
-        });
-        return calculateHashResponseSchema.parse(response.data);
-    }
-    catch (error) {
-        if (error instanceof z.ZodError) {
-            throw new Error(`Calculate Hash failed: Invalid response from server. Details: ${error.message}`);
-        }
-        if (error.response && error.response.data) {
-            const parsedError = parseStateZeroError(error.response.data);
-            if (Error.captureStackTrace) {
-                Error.captureStackTrace(parsedError, calculateHash);
-            }
-            throw parsedError;
-        }
-        else if (error.request) {
-            throw new Error(`Calculate Hash failed: No response received from server.`);
-        }
-        else {
-            throw new Error(`Calculate Hash failed: ${error.message}`);
-        }
-    }
-}
-export default calculateHash;
-calculateHash.actionName = 'calculate_hash';
-calculateHash.title = 'Calculate Hash';
-calculateHash.app = 'django_app';
-calculateHash.permissions = ['IsAuthenticated'];
-calculateHash.configKey = 'backend1';

package/dist/actions/backend1/django_app/get-current-username.d.ts

@@ -1,29 +0,0 @@
-/**
- * Get current user's username - simple focused action
- *
- * @param {Object} [axiosOverrides] - Allows overriding Axios request parameters.
- * @returns {Promise<Object>} A promise that resolves with the action's result.
- */
-export function getCurrentUsername(axiosOverrides?: Object): Promise<Object>;
-export namespace getCurrentUsername {
-    let actionName: string;
-    let title: string;
-    let app: string;
-    let permissions: string[];
-    let configKey: string;
-}
-/**
- * Zod schema for the response of getCurrentUsername.
- */
-export const getCurrentUsernameResponseSchema: z.ZodObject<{
-    username: z.ZodString;
-    retrieved_at: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    username: string;
-    retrieved_at: string;
-}, {
-    username: string;
-    retrieved_at: string;
-}>;
-export default getCurrentUsername;
-import { z } from 'zod';

package/dist/actions/backend1/django_app/get-current-username.js

@@ -1,65 +0,0 @@
-/**
- * This file was auto-generated. Do not make direct changes to the file.
- * Action: Get Current Username
- * App: django_app
- */
-import axios from 'axios';
-import { z } from 'zod';
-import { configInstance, parseStateZeroError, serializeActionPayload } from '../../../../src';
-import actionSchema from './get-current-username.schema.json' assert { type: 'json' };
-/**
- * Zod schema for the response of getCurrentUsername.
- */
-export const getCurrentUsernameResponseSchema = z.object({ username: z.string(),
-    retrieved_at: z.string().datetime({ message: "Invalid ISO 8601 datetime string" }) });
-/**
- * Get current user's username - simple focused action
- *
- * @param {Object} [axiosOverrides] - Allows overriding Axios request parameters.
- * @returns {Promise<Object>} A promise that resolves with the action's result.
- */
-export async function getCurrentUsername(axiosOverrides = {}) {
-    // Construct the data payload from the function arguments
-    const rawPayload = {};
-    // Serialize payload - handles model instances (extracts PK), files, dates, etc.
-    const payload = serializeActionPayload(rawPayload, actionSchema.input_properties);
-    const config = configInstance.getConfig();
-    const backend = config.backendConfigs['backend1'];
-    if (!backend) {
-        throw new Error(`No backend configuration found for key: backend1`);
-    }
-    const baseUrl = backend.API_URL.replace(/\/+$/, '');
-    const actionUrl = `${baseUrl}/actions/get_current_username/`;
-    const headers = backend.getAuthHeaders ? backend.getAuthHeaders() : {};
-    try {
-        const response = await axios.post(actionUrl, payload, {
-            headers: { 'Content-Type': 'application/json', ...headers },
-            ...axiosOverrides,
-        });
-        return getCurrentUsernameResponseSchema.parse(response.data);
-    }
-    catch (error) {
-        if (error instanceof z.ZodError) {
-            throw new Error(`Get Current Username failed: Invalid response from server. Details: ${error.message}`);
-        }
-        if (error.response && error.response.data) {
-            const parsedError = parseStateZeroError(error.response.data);
-            if (Error.captureStackTrace) {
-                Error.captureStackTrace(parsedError, getCurrentUsername);
-            }
-            throw parsedError;
-        }
-        else if (error.request) {
-            throw new Error(`Get Current Username failed: No response received from server.`);
-        }
-        else {
-            throw new Error(`Get Current Username failed: ${error.message}`);
-        }
-    }
-}
-export default getCurrentUsername;
-getCurrentUsername.actionName = 'get_current_username';
-getCurrentUsername.title = 'Get Current Username';
-getCurrentUsername.app = 'django_app';
-getCurrentUsername.permissions = ['IsAuthenticated'];
-getCurrentUsername.configKey = 'backend1';