@statezero/core 0.1.0

package/dist/syncEngine/stores/querysetStore.js

@@ -0,0 +1,200 @@
+import { Operation, Status, Type, operationRegistry } from './operation.js';
+import { querysetEventEmitter } from './reactivity.js';
+import { isNil, isEmpty, trim } from 'lodash-es';
+import { replaceTempPks, containsTempPk } from '../../flavours/django/tempPk.js';
+import { modelStoreRegistry } from '../registries/modelStoreRegistry.js';
+import { processIncludedEntities } from '../../flavours/django/makeApiCall.js';
+import hash from 'object-hash';
+import { Cache } from '../cache/cache.js';
+export class QuerysetStore {
+    constructor(modelClass, fetchFn, queryset, initialGroundTruthPks = null, initialOperations = null, options = {}) {
+        this.modelClass = modelClass;
+        this.fetchFn = fetchFn;
+        this.queryset = queryset;
+        this.isSyncing = false;
+        this.pruneThreshold = options.pruneThreshold || 10;
+        this.groundTruthPks = initialGroundTruthPks || [];
+        this.operationsMap = new Map();
+        if (Array.isArray(initialOperations)) {
+            for (const opData of initialOperations) {
+                const existing = operationRegistry.get(opData.operationId);
+                const op = existing || new Operation(opData, true);
+                this.operationsMap.set(op.operationId, op);
+            }
+        }
+        this.qsCache = new Cache('queryset-cache', {}, this.onHydrated.bind(this));
+    }
+    // Caching
+    get cacheKey() {
+        return this.queryset.semanticKey;
+    }
+    onHydrated(hydratedData) {
+        if (this.groundTruthPks.length === 0 && this.operationsMap.size === 0) {
+            const cached = this.qsCache.get(this.cacheKey);
+            if (!isNil(cached) && !isEmpty(cached)) {
+                console.log(`[QuerysetStore] Hydrated ${this.modelClass.modelName} queryset with ${cached.length} items from cache`);
+                this.setGroundTruth(cached);
+            }
+        }
+    }
+    setCache(result) {
+        let nonTempPks = [];
+        result.forEach((pk) => {
+            if (typeof pk === 'string' && containsTempPk(pk)) {
+                pk = replaceTempPks(pk);
+                if (isNil(pk) || isEmpty(trim(pk))) {
+                    return;
+                }
+            }
+            nonTempPks.push(pk);
+        });
+        this.qsCache.set(this.cacheKey, nonTempPks);
+    }
+    clearCache() {
+        this.qsCache.delete(this.cacheKey);
+    }
+    // -- Core methods --
+    get operations() {
+        return Array.from(this.operationsMap.values());
+    }
+    get pkField() {
+        return this.modelClass.primaryKeyField;
+    }
+    get groundTruthSet() {
+        return new Set(this.groundTruthPks);
+    }
+    _emitRenderEvent() {
+        querysetEventEmitter.emit(`${this.modelClass.configKey}::${this.modelClass.modelName}::queryset::render`, { ast: this.queryset.build(), ModelClass: this.modelClass });
+    }
+    async addOperation(operation) {
+        this.operationsMap.set(operation.operationId, operation);
+        if (this.operationsMap.size > this.pruneThreshold) {
+            this.prune();
+        }
+        this._emitRenderEvent();
+    }
+    async updateOperation(operation) {
+        if (!this.operationsMap.has(operation.operationId))
+            return;
+        this.operationsMap.set(operation.operationId, operation);
+        this._emitRenderEvent();
+        return true;
+    }
+    async confirm(operation) {
+        if (!this.operationsMap.has(operation.operationId))
+            return;
+        this.operationsMap.set(operation.operationId, operation);
+        this._emitRenderEvent();
+    }
+    async reject(operation) {
+        if (!this.operationsMap.has(operation.operationId))
+            return;
+        this.operationsMap.set(operation.operationId, operation);
+        this._emitRenderEvent();
+    }
+    async setGroundTruth(groundTruthPks) {
+        this.groundTruthPks = Array.isArray(groundTruthPks)
+            ? groundTruthPks
+            : [];
+        this._emitRenderEvent();
+    }
+    async setOperations(operations) {
+        this.operationsMap.clear();
+        if (Array.isArray(operations)) {
+            for (const op of operations) {
+                this.operationsMap.set(op.operationId, op);
+            }
+        }
+        this._emitRenderEvent();
+    }
+    getTrimmedOperations() {
+        const cutoff = Date.now() - 1000 * 60 * 2;
+        return this.operations.filter(op => op.timestamp > cutoff);
+    }
+    getInflightOperations() {
+        return this.operations.filter(operation => operation.status != Status.CONFIRMED &&
+            operation.status != Status.REJECTED);
+    }
+    prune() {
+        const renderedPks = this.render(false);
+        this.setGroundTruth(renderedPks);
+        this.setOperations(this.getInflightOperations());
+    }
+    render(optimistic = true, fromCache = false) {
+        if (fromCache) {
+            const cachedResult = this.qsCache.get(this.cacheKey);
+            if (Array.isArray(cachedResult)) {
+                return cachedResult;
+            }
+        }
+        const renderedPks = this.groundTruthSet;
+        for (const op of this.operations) {
+            if (op.status !== Status.REJECTED && (optimistic || op.status === Status.CONFIRMED)) {
+                this.applyOperation(op, renderedPks);
+            }
+        }
+        let result = Array.from(renderedPks);
+        let limit = this.queryset.build().serializerOptions?.limit;
+        if (limit) {
+            result = result.slice(0, limit);
+        }
+        this.setCache(result);
+        return result;
+    }
+    applyOperation(operation, currentPks) {
+        const pkField = this.pkField;
+        for (const instance of operation.instances) {
+            if (!instance ||
+                typeof instance !== 'object' ||
+                !(pkField in instance)) {
+                console.warn(`[QuerysetStore ${this.modelClass.modelName}] Skipping instance in operation ${operation.operationId} due to missing PK '${String(pkField)}' or invalid format.`);
+                continue;
+            }
+            let pk = instance[pkField];
+            switch (operation.type) {
+                case Type.CREATE:
+                    currentPks.add(pk);
+                    break;
+                case Type.CHECKPOINT:
+                case Type.UPDATE:
+                case Type.UPDATE_INSTANCE:
+                    break;
+                case Type.DELETE:
+                case Type.DELETE_INSTANCE:
+                    currentPks.delete(pk);
+                    break;
+                default:
+                    console.error(`[QuerysetStore ${this.modelClass.modelName}] Unknown operation type: ${operation.type}`);
+            }
+        }
+        return currentPks;
+    }
+    async sync() {
+        const id = this.modelClass.modelName;
+        if (this.isSyncing) {
+            console.warn(`[QuerysetStore ${id}] Already syncing, request ignored.`);
+            return;
+        }
+        this.isSyncing = true;
+        console.log(`[${id}] Starting sync...`);
+        try {
+            const response = await this.fetchFn({
+                ast: this.queryset.build(),
+                modelClass: this.modelClass
+            });
+            const { data, included } = response;
+            console.log(`[${id}] Sync fetch completed. Received: ${JSON.stringify(data)}.`);
+            // Persists all the instances (including nested instances) to the model store
+            processIncludedEntities(modelStoreRegistry, included, this.modelClass);
+            this.setGroundTruth(data);
+            this.setOperations(this.getInflightOperations());
+            console.log(`[${id}] Sync completed.`);
+        }
+        catch (e) {
+            console.error(`[${id}] Failed to sync ground truth:`, e);
+        }
+        finally {
+            this.isSyncing = false;
+        }
+    }
+}

package/dist/syncEngine/stores/reactivity.d.ts

@@ -0,0 +1,3 @@
+export const modelEventEmitter: import("mitt").Emitter<Record<import("mitt").EventType, unknown>>;
+export const querysetEventEmitter: import("mitt").Emitter<Record<import("mitt").EventType, unknown>>;
+export const metricEventEmitter: import("mitt").Emitter<Record<import("mitt").EventType, unknown>>;

package/dist/syncEngine/stores/reactivity.js

@@ -0,0 +1,4 @@
+import mitt from 'mitt';
+export const modelEventEmitter = mitt();
+export const querysetEventEmitter = mitt();
+export const metricEventEmitter = mitt();

package/dist/syncEngine/stores/utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Guarantees an array of operations, is an array of operations. Handles
+ * the basic failure case of a single operation.
+ */
+export function validateOperationsArray(operationsArray: any): any;
+/**
+ * Extract the minimal signature we're using for “direct‐match” comparison.
+ */
+export function getFingerprint(qs: any): {
+    nodes: any;
+    initialQueryset: any;
+    offset: any;
+    limit: any;
+};

package/dist/syncEngine/stores/utils.js

@@ -0,0 +1,32 @@
+import { isNil, isEqual } from 'lodash-es';
+import { filter } from '../../filtering/localFiltering';
+/**
+ * Guarantees an array of operations, is an array of operations. Handles
+ * the basic failure case of a single operation.
+ */
+export function validateOperationsArray(operationsArray) {
+    // verify the operations list
+    if (Array.isArray(operationsArray)) {
+        if (operationsArray.length > 0) {
+            if (!(operationsArray[0] instanceof Operation)) {
+                throw new Error(`operationsArray must be Operations not ${typeof (operationsArray[0])}`);
+            }
+        }
+    }
+    else if (!isNil(operationsArray)) {
+        if (!(operationsArray instanceof Operation)) {
+            throw new Error(`operationsArray must be Operations not ${typeof (operationsArray)}`);
+        }
+        operationsArray = [operationsArray]; // coerce it to be an array
+    }
+    return operationsArray;
+}
+/**
+ * Extract the minimal signature we're using for “direct‐match” comparison.
+ */
+export function getFingerprint(qs) {
+    const { nodes } = qs;
+    const initialQueryset = qs._initialQueryset;
+    const { offset = null, limit = null } = qs._serializerOptions || {};
+    return { nodes, initialQueryset, offset, limit };
+}

package/dist/syncEngine/sync.d.ts

@@ -0,0 +1,32 @@
+export class EventPayload {
+    constructor(data: any);
+    event: any;
+    model: any;
+    operation_id: any;
+    pk_field_name: any;
+    configKey: any;
+    instances: any;
+    _cachedInstances: any;
+    get modelClass(): Function | null;
+    getFullInstances(): Promise<any>;
+}
+export class SyncManager {
+    registries: Map<any, any>;
+    followedModels: Map<any, any>;
+    followAllQuerysets: boolean;
+    followedQuerysets: Map<any, any>;
+    /**
+     * Initialize event handlers for all event receivers
+     */
+    initialize(): void;
+    followModel(registry: any, modelClass: any): void;
+    unfollowModel(registry: any, modelClass: any): void;
+    manageRegistry(registry: any): void;
+    removeRegistry(registry: any): void;
+    handleEvent: (event: any) => void;
+    isQuerysetFollowed(queryset: any): boolean;
+    processQuerysets(event: any): void;
+    processMetrics(event: any): void;
+    processModels(event: any): void;
+}
+export const syncManager: SyncManager;

package/dist/syncEngine/sync.js

@@ -0,0 +1,169 @@
+import { getAllEventReceivers } from "../core/eventReceivers";
+import { operationRegistry } from "./stores/operation";
+import { initializeAllEventReceivers } from "../config";
+import { getEventReceiver } from "../core/eventReceivers";
+import { querysetStoreRegistry } from "./registries/querysetStoreRegistry";
+import { modelStoreRegistry } from "./registries/modelStoreRegistry";
+import { metricRegistry } from "./registries/metricRegistry";
+import { getModelClass, getConfig } from "../config";
+import { isNil } from "lodash-es";
+export class EventPayload {
+    constructor(data) {
+        this.event = data.event;
+        this.model = data.model;
+        this.operation_id = data.operation_id;
+        this.pk_field_name = data.pk_field_name;
+        this.configKey = data.configKey;
+        this.instances = data.instances;
+        this._cachedInstances = null;
+    }
+    get modelClass() {
+        return getModelClass(this.model, this.configKey);
+    }
+    async getFullInstances() {
+        if (this.event === 'delete') {
+            throw new Error("Cannot fetch full instances for delete operation bozo...");
+        }
+        if (isNil(this._cachedInstances)) {
+            this._cachedInstances = await this.modelClass.objects
+                .filter({
+                [`${this.modelClass.primaryKeyField}__in`]: this.instances.map((instance) => instance[this.modelClass.primaryKeyField]),
+            }).fetch();
+        }
+        return this._cachedInstances;
+    }
+}
+export class SyncManager {
+    constructor() {
+        this.handleEvent = (event) => {
+            let payload = new EventPayload(event);
+            let isLocalOperation = operationRegistry.has(payload.operation_id);
+            if (this.registries.has("MetricRegistry")) {
+                this.processMetrics(payload);
+            }
+            if (isLocalOperation) {
+                // This is a local operation, so don't resync querysets or models
+                return;
+            }
+            if (this.registries.has("QuerysetStoreRegistry")) {
+                this.processQuerysets(payload);
+            }
+            if (this.registries.has("ModelStoreRegistry")) {
+                this.processModels(payload);
+            }
+        };
+        this.registries = new Map();
+        // Map of registries to model sets
+        this.followedModels = new Map();
+        // Map of querysets to keep synced
+        this.followAllQuerysets = true;
+        this.followedQuerysets = new Map();
+    }
+    /**
+     * Initialize event handlers for all event receivers
+     */
+    initialize() {
+        // Initialize all event receivers
+        initializeAllEventReceivers();
+        // Get all registered event receivers
+        const eventReceivers = getAllEventReceivers();
+        // Register the event handlers with each receiver
+        eventReceivers.forEach((receiver, configKey) => {
+            if (receiver) {
+                // Model events go to handleEvent
+                receiver.addModelEventHandler(this.handleEvent.bind(this));
+            }
+        });
+    }
+    followModel(registry, modelClass) {
+        const models = this.followedModels.get(registry) || new Set();
+        this.followedModels.set(registry, models);
+        if (models.has(modelClass))
+            return;
+        const alreadyFollowed = [...this.followedModels.values()].some(set => set.has(modelClass));
+        models.add(modelClass);
+        if (!alreadyFollowed) {
+            getEventReceiver(modelClass.configKey)?.subscribe(modelClass.modelName, this.handleEvent);
+        }
+    }
+    unfollowModel(registry, modelClass) {
+        const models = this.followedModels.get(registry);
+        if (!models)
+            return;
+        models.delete(modelClass);
+        const stillFollowed = [...this.followedModels.values()].some(set => set.has(modelClass));
+        if (!stillFollowed) {
+            getEventReceiver(modelClass.configKey)?.unsubscribe(modelClass.modelName, this.handleEvent);
+        }
+    }
+    manageRegistry(registry) {
+        this.registries.set(registry.constructor.name, registry);
+        registry.setSyncManager(this);
+    }
+    removeRegistry(registry) {
+        this.registries.delete(registry.constructor.name);
+    }
+    isQuerysetFollowed(queryset) {
+        let current = queryset;
+        // All followed querysets and their descendents get updated
+        while (current) {
+            if (this.followedQuerysets.has(current)) {
+                return true;
+            }
+            current = current.__parent;
+        }
+        return false;
+    }
+    processQuerysets(event) {
+        const registry = this.registries.get("QuerysetStoreRegistry");
+        for (const [semanticKey, store] of registry._stores.entries()) {
+            if (store.modelClass.modelName === event.model &&
+                store.modelClass.configKey === event.configKey) {
+                if (this.followAllQuerysets) {
+                    store.sync();
+                    continue;
+                }
+                // Get the set of querysets following this semantic key
+                const followingQuerysets = registry.followingQuerysets.get(semanticKey);
+                if (followingQuerysets) {
+                    // Use some() to break early when we find a match
+                    const shouldSync = [...followingQuerysets].some(queryset => {
+                        return this.isQuerysetFollowed(queryset);
+                    });
+                    if (shouldSync) {
+                        console.log(`syncing store for semantic key: ${semanticKey}`);
+                        store.sync();
+                    }
+                }
+            }
+        }
+    }
+    processMetrics(event) {
+        const registry = this.registries.get("MetricRegistry");
+        for (const [key, entry] of registry._stores.entries()) {
+            // Check if the store has a queryset with the model class AND correct backend
+            if (entry.queryset &&
+                entry.queryset.modelClass.modelName === event.model &&
+                entry.queryset.modelClass.configKey === event.configKey) {
+                if (this.followAllQuerysets) {
+                    entry.store.sync();
+                    continue;
+                }
+                // Check if this queryset (or any parent) is being followed
+                if (this.isQuerysetFollowed(entry.queryset)) {
+                    console.log(`syncing metric store for key: ${key}`);
+                    entry.store.sync();
+                }
+            }
+        }
+    }
+    processModels(event) {
+        // No need to sync models, because everything that is live, is synced
+        return;
+    }
+}
+const syncManager = new SyncManager();
+syncManager.manageRegistry(querysetStoreRegistry);
+syncManager.manageRegistry(modelStoreRegistry);
+syncManager.manageRegistry(metricRegistry);
+export { syncManager };

package/dist/vue-entry.d.ts

@@ -0,0 +1,6 @@
+import { ModelAdaptor } from './adaptors/vue/index.js';
+import { QuerySetAdaptor } from './adaptors/vue/index.js';
+import { MetricAdaptor } from './adaptors/vue/index.js';
+import { useQueryset } from './adaptors/vue/index.js';
+import { querysets } from './adaptors/vue/index.js';
+export { ModelAdaptor, QuerySetAdaptor, MetricAdaptor, useQueryset, querysets };

package/dist/vue-entry.js

@@ -0,0 +1,2 @@
+import { ModelAdaptor, QuerySetAdaptor, MetricAdaptor, useQueryset, querysets } from './adaptors/vue/index.js';
+export { ModelAdaptor, QuerySetAdaptor, MetricAdaptor, useQueryset, querysets };

package/license.md

@@ -0,0 +1,116 @@
+# **StateZero License Agreement**
+
+_Last Updated: 2025-06-29_
+
+## **1. Copyright and Ownership**
+
+1.1. **StateZero is proprietary software** developed and owned by **Hoza Holdings Pte Ltd** ("Licensor").
+1.2. **StateZero is not open-source.** All rights not expressly granted in this License are **reserved by the Licensor**.
+1.3. **Distribution**: StateZero is made available via **PyPI** (Python Package Index), **npm** (Node Package Manager), and **GitHub**.
+1.4. **Early Release Status**: This is an **early release version** of StateZero designed for community feedback. It is **not considered production ready**. Users are encouraged to provide feedback but should exercise caution when implementing in critical systems.
+
+## **2. Commercial No-Rugpull License**
+
+2.1. **No-Rugpull Guarantee**: StateZero is available under a commercial "no-rugpull" license, which means:
+
+- You receive an **irrevocable right** to use StateZero forever for a fixed monthly fee
+- We **cannot change your fee**, other than a fixed CPI (Consumer Price Index) increase that's automatically added each year
+- As long as you pay the fee and don't build a competitive product, the license will continue
+- If we no longer wish to be associated with your use case, we will ask you not to pay the fee, but **your license will remain valid**
+
+  2.2. **License Philosophy**: If SaaS is like renting and open-source is like owning, our license is like a **999-year leasehold on fixed rent**. It provides the security you need to build and grow your company around StateZero, while allowing us to maintain and develop StateZero to a high standard.
+
+  2.3. **Rate Lock Guarantee**: You lock in the **full rate card for all tiers** at the time you sign up, meaning your fees remain predictable no matter how much your revenue or our pricing changes. To lock in your rates, simply contact us at **robert.herring@resipilot.com**.
+
+## **3. Pricing Structure**
+
+3.1. **Revenue-Based Pricing**:
+
+- **$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**
+- **$1,000/month** for companies with revenue up to **$100M**
+- **$5,000/month** for companies with revenue above **$100M**
+
+  3.2. **Free Usage Guarantee**: StateZero will **always remain free** for companies with **annual revenue below $3 million**.
+
+  3.3. **Annual CPI Adjustment**: Pricing may be adjusted annually based on the Consumer Price Index, but no other fee changes are permitted once you have locked in your rate.
+
+## **4. Grant of License**
+
+4.1. **Standard Usage License**:
+
+- Licensor grants you a **non-exclusive, non-transferable, worldwide license** to download, install, and use StateZero
+- StateZero **may be used** in both **development and production** environments
+- You may **install StateZero** within your organization but **may not provide StateZero as a service to third parties** without explicit written permission
+
+  4.2. **Scope and Limitations**:
+
+- This License **does not** transfer ownership of StateZero or any intellectual property rights
+- Usage is subject to the pricing structure outlined in Section 3
+
+## **5. LLM Training License**
+
+5.1. **Separate License Required**: Use of StateZero for **Large Language Model (LLM) training purposes** requires a separate license agreement.
+
+5.2. **LLM Training License Fee**: The annual license fee for LLM training usage is **$250,000 per year**.
+
+5.3. **Contact for LLM License**: Organizations requiring LLM training rights must contact **Airhome Sp Zoo** at **robert.herring@resipilot.com** to arrange a separate licensing agreement.
+
+## **6. Restrictions**
+
+6.1. **Prohibited Actions**:
+
+- You **may not** modify, reverse engineer, decompile, or disassemble StateZero
+- You **may not** remove, alter, or obscure any **proprietary notices, branding, or license enforcement mechanisms**
+- You **may not** sublicense, resell, or distribute StateZero to any third party **without explicit written permission**
+- You **may not** use StateZero to develop or offer **a competing product or service**
+- You **may not** use StateZero to create a cloud-hosted version of our service (similar to services like Heroku, Netlify, AWS, etc.)
+- You **may not** use StateZero for LLM training without the separate license outlined in Section 5
+
+## **7. Payment Terms**
+
+7.1. **Payment Obligations**: Companies exceeding the free tier revenue threshold must pay the applicable monthly fee as outlined in Section 3.
+
+7.2. **Revenue Tier Reporting**: You are responsible for accurately reporting your revenue tier and upgrading to the appropriate pricing tier when revenue thresholds are exceeded.
+
+7.3. **Rate Lock Process**: To lock in current pricing for all tiers, contact us at **robert.herring@resipilot.com**.
+
+## **8. Disclaimer of Warranty**
+
+8.1. **AS-IS Basis**: StateZero is provided **"AS IS"**, without warranties or guarantees of any kind.
+8.2. The Licensor **expressly disclaims** all implied warranties, including but not limited to **merchantability, fitness for a particular purpose, or non-infringement**.
+
+## **9. Limitation of Liability**
+
+9.1. **No Liability for Damages**: To the **maximum extent permitted by law**, the Licensor **shall not** be liable for any damages resulting from the use or inability to use StateZero, including:
+
+- Loss of revenue, data, or business opportunities
+- Incidental, consequential, punitive, or special damages, even if advised of the possibility
+
+## **10. Termination**
+
+10.1. **License Irrevocability**: Under the no-rugpull guarantee, **we cannot terminate your license to use StateZero** as long as you:
+
+- Pay the applicable monthly fee (if any), OR
+- We have asked you not to pay the fee (as outlined in Section 2.1)
+- AND you comply with the restrictions in Section 6 (primarily not building a competing product)
+
+  10.2. **Limited Termination Rights**: The Licensor may only terminate this License for material violations of Section 6 (Restrictions), and only after providing 30 days written notice and opportunity to cure such violations.
+
+  10.3. **Upon Valid Termination**: Only in cases of valid termination under Section 10.2, you must **uninstall StateZero** and delete all copies in your possession.
+
+  10.4. **No-Rugpull Protection**: Your license to use StateZero is **irrevocable** under normal circumstances. Even if we no longer wish to be associated with your use case, we will simply ask you to stop paying fees, but your license remains valid and enforceable.
+
+## **11. Governing Law**
+
+11.1. This License shall be governed by and construed in accordance with the **laws of Singapore**, without regard to conflict of law principles.
+
+## **12. Contact Information**
+
+12.1. For general inquiries and rate lock requests, contact **Airhome Sp Zoo** at **robert.herring@resipilot.com**.
+12.2. For LLM training license inquiries, contact **Airhome Sp Zoo** at **robert.herring@resipilot.com**.
+
+---
+
+**By downloading, installing, or using StateZero, you acknowledge that you have read, understood, and agree to be bound by the terms of this License Agreement.**