@statezero/core 0.1.0

package/dist/syncEngine/registries/querysetStoreRegistry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A dynamic wrapper that always returns the latest queryset results
+ * This class proxies array operations to always reflect the current state
+ * of the underlying QuerysetStore.
+ */
+export class LiveQueryset {
+    constructor(queryset: any);
+    /**
+     * Serializes the lqs as a simple array of objects, for freezing e.g in the metric stores
+     */
+    serialize(): any;
+    /**
+     * Get the current items from the store
+     * @private
+     * @returns {Array} The current items in the queryset
+     */
+    private getCurrentItems;
+    #private;
+}
+export const querysetStoreRegistry: QuerysetStoreRegistry;
+declare class QuerysetStoreRegistry {
+    _stores: Map<any, any>;
+    _tempStores: WeakMap<object, any>;
+    followingQuerysets: Map<any, any>;
+    syncManager: () => void;
+    clear(): void;
+    setSyncManager(syncManager: any): void;
+    /**
+     * Add a queryset to the following set for a semantic key
+     */
+    addFollowingQueryset(semanticKey: any, queryset: any): void;
+    getStore(queryset: any, seed?: boolean): any;
+    /**
+     * Get the current state of the queryset, wrapped in a LiveQueryset
+     * @param {Object} queryset - The queryset
+     * @param {Boolean} seed - Should we optimistically seed the queryset with relevant items from the parent?
+     * @param {Boolean} sync - Schedule a sync of the queryset with the backend
+     * @returns {LiveQueryset} - A live view of the queryset
+     */
+    getEntity(queryset: Object, seed?: boolean, sync?: boolean): LiveQueryset;
+    /**
+     * Set ground truth for a queryset
+     * @param {Object} queryset - The queryset
+     * @param {Array} instances - Array of instances to set as ground truth
+     * @returns {Array} - The set instances
+     */
+    setEntity(queryset: Object, instances: any[]): any[];
+    /**
+     * Get all queryset stores for a specific model class
+     * @param {ModelClass} ModelClass - The model class to get stores for
+     * @returns {Array} - Array of queryset stores for this model
+     */
+    getAllStoresForModel(ModelClass: any): any[];
+}
+export {};

package/dist/syncEngine/registries/querysetStoreRegistry.js

@@ -0,0 +1,244 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _LiveQueryset_queryset, _LiveQueryset_ModelClass, _LiveQueryset_proxy, _LiveQueryset_array;
+import { QuerysetStore } from '../stores/querysetStore.js';
+import { modelStoreRegistry } from '../registries/modelStoreRegistry.js';
+import { wrapReactiveQuerySet } from '../../reactiveAdaptor.js';
+import { processQuery, getRequiredFields, pickRequiredFields } from '../../filtering/localFiltering.js';
+import { filter } from '../../filtering/localFiltering.js';
+import { makeApiCall } from '../../flavours/django/makeApiCall.js';
+import { isNil, pick } from 'lodash-es';
+import hash from 'object-hash';
+import { Operation } from '../stores/operation.js';
+import { Cache } from '../cache/cache.js';
+/**
+ * A dynamic wrapper that always returns the latest queryset results
+ * This class proxies array operations to always reflect the current state
+ * of the underlying QuerysetStore.
+ */
+export class LiveQueryset {
+    constructor(queryset) {
+        _LiveQueryset_queryset.set(this, void 0);
+        _LiveQueryset_ModelClass.set(this, void 0);
+        _LiveQueryset_proxy.set(this, void 0);
+        _LiveQueryset_array.set(this, []);
+        // used internally
+        __classPrivateFieldSet(this, _LiveQueryset_queryset, queryset, "f");
+        __classPrivateFieldSet(this, _LiveQueryset_ModelClass, queryset.ModelClass, "f");
+        __classPrivateFieldGet(this, _LiveQueryset_array, "f").queryset = queryset;
+        __classPrivateFieldGet(this, _LiveQueryset_array, "f").ModelClass = queryset.ModelClass;
+        // Create a proxy that intercepts all array access
+        __classPrivateFieldSet(this, _LiveQueryset_proxy, new Proxy(__classPrivateFieldGet(this, _LiveQueryset_array, "f"), {
+            get: (target, prop, receiver) => {
+                // Expose the touch method through the proxy
+                if (prop === 'touch') {
+                    return () => this.touch();
+                }
+                if (prop === 'serialize') {
+                    return () => this.serialize();
+                }
+                // Special handling for iterators and common array methods
+                if (prop === Symbol.iterator) {
+                    return () => this.getCurrentItems()[Symbol.iterator]();
+                }
+                else if (typeof prop === 'string' && ['forEach', 'map', 'filter', 'reduce', 'some', 'every', 'find'].includes(prop)) {
+                    return (...args) => this.getCurrentItems()[prop](...args);
+                }
+                else if (prop === 'length') {
+                    return this.getCurrentItems().length;
+                }
+                else if (typeof prop === 'string' && !isNaN(parseInt(prop))) {
+                    // Handle numeric indices
+                    return this.getCurrentItems()[prop];
+                }
+                return target[prop];
+            }
+        }), "f");
+        return __classPrivateFieldGet(this, _LiveQueryset_proxy, "f");
+    }
+    /**
+     * Serializes the lqs as a simple array of objects, for freezing e.g in the metric stores
+     */
+    serialize() {
+        const store = querysetStoreRegistry.getStore(__classPrivateFieldGet(this, _LiveQueryset_queryset, "f"));
+        // Get the current primary keys from the store
+        const pks = store.render();
+        // Map primary keys to full model objects
+        return pks.map(pk => {
+            // Get the full model instance from the model store
+            const pkField = __classPrivateFieldGet(this, _LiveQueryset_ModelClass, "f").primaryKeyField;
+            return __classPrivateFieldGet(this, _LiveQueryset_ModelClass, "f").fromPk(pk, __classPrivateFieldGet(this, _LiveQueryset_queryset, "f")).serialize();
+        });
+    }
+    /**
+     * Get the current items from the store
+     * @private
+     * @returns {Array} The current items in the queryset
+     */
+    getCurrentItems(sortAndFilter = true) {
+        const store = querysetStoreRegistry.getStore(__classPrivateFieldGet(this, _LiveQueryset_queryset, "f"));
+        // Get the current primary keys from the store
+        const pks = store.render();
+        // Map primary keys to full model objects
+        const instances = pks.map(pk => {
+            // Get the full model instance from the model store
+            const pkField = __classPrivateFieldGet(this, _LiveQueryset_ModelClass, "f").primaryKeyField;
+            return __classPrivateFieldGet(this, _LiveQueryset_ModelClass, "f").fromPk(pk, __classPrivateFieldGet(this, _LiveQueryset_queryset, "f"));
+        });
+        if (!sortAndFilter)
+            return instances;
+        return filter(instances, __classPrivateFieldGet(this, _LiveQueryset_queryset, "f").build(), __classPrivateFieldGet(this, _LiveQueryset_ModelClass, "f"), true);
+    }
+}
+_LiveQueryset_queryset = new WeakMap(), _LiveQueryset_ModelClass = new WeakMap(), _LiveQueryset_proxy = new WeakMap(), _LiveQueryset_array = new WeakMap();
+class QuerysetStoreRegistry {
+    constructor() {
+        this._stores = new Map(); // Map<semanticKey, Store>
+        this._tempStores = new WeakMap(); // WeakMap<Queryset, Store>
+        this.followingQuerysets = new Map(); // Map<semanticKey, Set<queryset>>
+        this.syncManager = () => { console.warn("SyncManager not set for QuerysetStoreRegistry"); };
+    }
+    clear() {
+        this._stores.forEach((store) => {
+            this.syncManager.unfollowModel(this, store.modelClass);
+        });
+        this._stores = new Map();
+        this.followingQuerysets = new Map();
+    }
+    setSyncManager(syncManager) {
+        this.syncManager = syncManager;
+    }
+    /**
+     * Add a queryset to the following set for a semantic key
+     */
+    addFollowingQueryset(semanticKey, queryset) {
+        if (!this.followingQuerysets.has(semanticKey)) {
+            this.followingQuerysets.set(semanticKey, new Set());
+        }
+        this.followingQuerysets.get(semanticKey).add(queryset);
+    }
+    getStore(queryset, seed = false) {
+        if (isNil(queryset) || isNil(queryset.ModelClass)) {
+            throw new Error("QuerysetStoreRegistry.getStore requires a valid queryset");
+        }
+        // Check if we already have a temporary store for this exact QuerySet instance
+        if (this._tempStores.has(queryset)) {
+            return this._tempStores.get(queryset);
+        }
+        // Get the semanticKey
+        const semanticKey = queryset.semanticKey;
+        // Check if we have a permanent store with this semanticKey
+        if (this._stores.has(semanticKey)) {
+            this.addFollowingQueryset(semanticKey, queryset);
+            return this._stores.get(semanticKey);
+        }
+        // Create a new temporary store
+        const fetchQueryset = async ({ ast, modelClass }) => {
+            // Directly assemble the request and call the API to avoid recursive logic from the
+            // queryset back to the registry / store
+            const payload = {
+                ...ast,
+                type: 'list'
+            };
+            const response = await makeApiCall(queryset, 'list', payload);
+            return response.data;
+        };
+        let initialGroundTruthPks = null;
+        let ast = queryset.build();
+        let ModelClass = queryset.ModelClass;
+        if (queryset.__parent && seed) {
+            let parentLiveQuerySet = this.getEntity(queryset.__parent);
+            initialGroundTruthPks = filter(parentLiveQuerySet, ast, ModelClass, false);
+        }
+        // Get the parent registry    
+        const store = new QuerysetStore(ModelClass, fetchQueryset, queryset, initialGroundTruthPks, // Initial ground truth PKs
+        null // Initial operations
+        );
+        // Store it in the temp store map
+        this._tempStores.set(queryset, store);
+        return store;
+    }
+    /**
+     * Get the current state of the queryset, wrapped in a LiveQueryset
+     * @param {Object} queryset - The queryset
+     * @param {Boolean} seed - Should we optimistically seed the queryset with relevant items from the parent?
+     * @param {Boolean} sync - Schedule a sync of the queryset with the backend
+     * @returns {LiveQueryset} - A live view of the queryset
+     */
+    getEntity(queryset, seed = true, sync = false) {
+        if (isNil(queryset))
+            throw new Error(`qsStoreRegistry: getEntity cannot be called without a queryset`);
+        const semanticKey = queryset.semanticKey;
+        this.addFollowingQueryset(semanticKey, queryset);
+        let store;
+        // If we have a temporary store, promote it
+        if (this._tempStores.has(queryset)) {
+            store = this._tempStores.get(queryset);
+            this._stores.set(semanticKey, store);
+            this.syncManager.followModel(this, queryset.ModelClass);
+        }
+        // Otherwise, ensure we have a permanent store
+        else if (!this._stores.has(semanticKey)) {
+            store = this.getStore(queryset, seed);
+            this._stores.set(semanticKey, store);
+            this.syncManager.followModel(this, queryset.ModelClass);
+        }
+        else {
+            store = this._stores.get(semanticKey);
+        }
+        const liveQueryset = new LiveQueryset(queryset);
+        if (sync)
+            store.sync();
+        return wrapReactiveQuerySet(liveQueryset);
+    }
+    /**
+     * Set ground truth for a queryset
+     * @param {Object} queryset - The queryset
+     * @param {Array} instances - Array of instances to set as ground truth
+     * @returns {Array} - The set instances
+     */
+    setEntity(queryset, instances) {
+        if (isNil(queryset) || isNil(instances))
+            return [];
+        const semanticKey = queryset.semanticKey;
+        this.addFollowingQueryset(semanticKey, queryset);
+        let store;
+        if (this._stores.has(semanticKey)) {
+            store = this._stores.get(semanticKey);
+        }
+        else {
+            // If we have a temp store, promote it
+            if (this._tempStores.has(queryset)) {
+                store = this._tempStores.get(queryset);
+                this._stores.set(semanticKey, store);
+            }
+            else {
+                // Create a new permanent store
+                store = this.getStore(queryset);
+                this._stores.set(semanticKey, store);
+            }
+        }
+        store.setGroundTruth(instances.map(instance => instance[queryset.ModelClass.primaryKeyField] || instance));
+        return instances;
+    }
+    /**
+     * Get all queryset stores for a specific model class
+     * @param {ModelClass} ModelClass - The model class to get stores for
+     * @returns {Array} - Array of queryset stores for this model
+     */
+    getAllStoresForModel(ModelClass) {
+        if (!ModelClass)
+            return [];
+        return Array.from(this._stores.values()).filter(store => store.modelClass === ModelClass);
+    }
+}
+export const querysetStoreRegistry = new QuerysetStoreRegistry();

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

@@ -0,0 +1,55 @@
+/**
+ * Store for managing a single metric with optimistic updates
+ */
+export class MetricStore {
+    constructor(metricType: any, modelClass: any, queryset: any, field: null | undefined, ast: null | undefined, fetchFn: any);
+    metricType: any;
+    modelClass: any;
+    queryset: any;
+    field: any;
+    ast: any;
+    fetchFn: any;
+    groundTruthValue: any;
+    isSyncing: boolean;
+    strategy: import("../metrics/metricOptCalcs").MetricCalculationStrategy;
+    operations: any[];
+    confirmedOps: Set<any>;
+    metricCache: Cache;
+    _lastCalculatedValue: any;
+    reset(): void;
+    get cacheKey(): string;
+    /**
+     * Add an operation to this metric store
+     * @param {Operation} operation - The operation to add
+     */
+    addOperation(operation: Operation): void;
+    /**
+     * Update an operation in this metric store
+     * @param {Operation} operation - The operation to update
+     */
+    updateOperation(operation: Operation): void;
+    /**
+     * Confirm an operation in this metric store
+     * @param {Operation} operation - The operation to confirm
+     */
+    confirm(operation: Operation): void;
+    /**
+     * Reject an operation in this metric store
+     * @param {Operation} operation - The operation to reject
+     */
+    reject(operation: Operation): void;
+    onHydrated(): void;
+    setCache(): void;
+    clearCache(): void;
+    setGroundTruth(value: any): void;
+    /**
+     * Render the metric with current operations
+     * @returns {any} Calculated metric value
+     */
+    render(): any;
+    /**
+     * Sync metric with server
+     */
+    sync(): Promise<any>;
+}
+import { Cache } from '../cache/cache.js';

package/dist/syncEngine/stores/metricStore.js

@@ -0,0 +1,222 @@
+import { Cache } from '../cache/cache.js';
+import { MetricStrategyFactory } from "../metrics/metricOptCalcs";
+import hash from 'object-hash';
+import { isNil, isEmpty, isEqual } from 'lodash-es';
+import { metricEventEmitter } from './reactivity.js';
+import { Status } from './operation.js';
+/**
+ * Store for managing a single metric with optimistic updates
+ */
+export class MetricStore {
+    constructor(metricType, modelClass, queryset, field = null, ast = null, fetchFn) {
+        this.metricType = metricType;
+        this.modelClass = modelClass;
+        this.queryset = queryset;
+        this.field = field;
+        this.ast = ast;
+        this.fetchFn = fetchFn;
+        this.groundTruthValue = null;
+        this.isSyncing = false;
+        this.strategy = MetricStrategyFactory.getStrategy(metricType, modelClass);
+        // Store operations related to this metric
+        this.operations = [];
+        // Keep track of which operations have been confirmed
+        this.confirmedOps = new Set();
+        // Initialize cache with AST-specific key
+        this.metricCache = new Cache("metric-store-cache", {}, this.onHydrated.bind(this));
+        // Initialize _lastCalculatedValue
+        this._lastCalculatedValue = null;
+    }
+    reset() {
+        this.groundTruthValue = null;
+        this._lastCalculatedValue = null;
+        this.operations = [];
+        this.confirmedOps = new Set();
+        this.isSyncing = false;
+        this.clearCache();
+    }
+    get cacheKey() {
+        return `${this.modelClass.configKey}::${this.modelClass.modelName}::metric::${this.metricType}::${this.field || "null"}::${this.ast ? hash(this.ast) : "global"}`;
+    }
+    /**
+     * Add an operation to this metric store
+     * @param {Operation} operation - The operation to add
+     */
+    addOperation(operation) {
+        // Only track operations for this model
+        if (operation.queryset.ModelClass !== this.modelClass) {
+            return;
+        }
+        // Check if operation already exists to avoid duplicates
+        const existingIndex = this.operations.findIndex((op) => op.operationId === operation.operationId);
+        if (existingIndex !== -1) {
+            // Update existing operation instead of adding a duplicate
+            this.operations[existingIndex] = operation;
+        }
+        else {
+            // Add to our operations list
+            this.operations.push(operation);
+        }
+        // Trigger a render to update the metric value
+        if (!isNil(this.groundTruthValue)) {
+            this.render();
+        }
+    }
+    /**
+     * Update an operation in this metric store
+     * @param {Operation} operation - The operation to update
+     */
+    updateOperation(operation) {
+        // Only track operations for this model
+        if (operation.queryset.ModelClass !== this.modelClass) {
+            return;
+        }
+        // Find and update the operation - use operationId not id
+        const index = this.operations.findIndex((op) => op.operationId === operation.operationId);
+        if (index !== -1) {
+            this.operations[index] = operation;
+        }
+        else {
+            // If not found, add it
+            this.operations.push(operation);
+        }
+        // Trigger a render to update the metric value
+        if (!isNil(this.groundTruthValue)) {
+            this.render();
+        }
+    }
+    /**
+     * Confirm an operation in this metric store
+     * @param {Operation} operation - The operation to confirm
+     */
+    confirm(operation) {
+        // Only track operations for this model
+        if (operation.queryset.ModelClass !== this.modelClass) {
+            return;
+        }
+        // Update operation status in our list and mark as confirmed - use operationId not id
+        const index = this.operations.findIndex((op) => op.operationId === operation.operationId);
+        if (index !== -1) {
+            this.operations[index] = operation;
+            this.confirmedOps.add(operation.operationId);
+        }
+        // Trigger a sync to update ground truth
+        this.render();
+    }
+    /**
+     * Reject an operation in this metric store
+     * @param {Operation} operation - The operation to reject
+     */
+    reject(operation) {
+        // Only track operations for this model
+        if (operation.queryset.ModelClass !== this.modelClass) {
+            return;
+        }
+        // Remove the operation as it's now rejected - use operationId not id
+        this.operations = this.operations.filter((op) => op.operationId !== operation.operationId);
+        this.confirmedOps.delete(operation.operationId);
+        // Trigger a render to update the metric value
+        if (!isNil(this.groundTruthValue)) {
+            this.render();
+        }
+    }
+    onHydrated() {
+        if (this.groundTruthValue === null) {
+            const cached = this.metricCache.get(this.cacheKey);
+            if (!isNil(cached) && !isEmpty(cached)) {
+                console.log(`[MetricStore] Hydrated ${this.metricType} metric for ${this.modelClass.modelName} from cache`);
+                this.setGroundTruth(cached?.value);
+            }
+        }
+    }
+    setCache() {
+        let groundTruthValue = this.groundTruthValue;
+        let serializedGroundTruth = groundTruthValue?.value
+            ? groundTruthValue.value
+            : groundTruthValue;
+        this.metricCache.set(this.cacheKey, {
+            value: serializedGroundTruth,
+        });
+    }
+    clearCache() {
+        this.metricCache.delete(this.cacheKey);
+    }
+    setGroundTruth(value) {
+        // Check if the value has actually changed
+        const valueChanged = !isEqual(this.groundTruthValue, value);
+        this.groundTruthValue = value;
+        this.setCache();
+        // Only emit event if the value changed
+        if (valueChanged) {
+            metricEventEmitter.emit("metric::render", {
+                metricType: this.metricType,
+                ModelClass: this.modelClass,
+                field: this.field,
+                ast: hash(this.ast),
+                valueChanged: true,
+            });
+        }
+    }
+    /**
+     * Render the metric with current operations
+     * @returns {any} Calculated metric value
+     */
+    render() {
+        // Check if ground truth value is null
+        if (isNil(this.groundTruthValue)) {
+            console.log(`groundTruthValue is null, returning null`);
+            return null;
+        }
+        // Calculate the new value using the operations-based approach
+        const newValue = this.strategy.calculateWithOperations(this.groundTruthValue, this.operations, this.field, this.modelClass);
+        // Check if the value has actually changed
+        if (!isEqual(this._lastCalculatedValue, newValue)) {
+            this._lastCalculatedValue = newValue;
+            // Only emit event if the value changed
+            metricEventEmitter.emit("metric::render", {
+                metricType: this.metricType,
+                ModelClass: this.modelClass,
+                field: this.field,
+                ast: hash(this.ast),
+                valueChanged: true,
+            });
+        }
+        return newValue;
+    }
+    /**
+     * Sync metric with server
+     */
+    async sync() {
+        if (this.isSyncing) {
+            console.warn(`[MetricStore] Already syncing ${this.metricType} for ${this.modelClass.modelName}`);
+            return;
+        }
+        this.isSyncing = true;
+        try {
+            console.log(`[MetricStore] Syncing ${this.metricType} metric for ${this.modelClass.modelName}`);
+            // Use fetchFn to get server metric value
+            const result = await this.fetchFn({
+                metricType: this.metricType,
+                modelClass: this.modelClass,
+                field: this.field,
+                ast: this.ast,
+            });
+            // After syncing, remove all confirmed operations
+            if (this.confirmedOps.size > 0) {
+                this.operations = this.operations.filter((op) => !this.confirmedOps.has(op.operationId));
+                this.confirmedOps.clear();
+            }
+            // Update ground truth
+            this.setGroundTruth(result);
+            console.log(`[MetricStore] Synced ${this.metricType} metric with value:`, result);
+            return result;
+        }
+        catch (error) {
+            console.error(`[MetricStore] Failed to sync ${this.metricType} metric:`, error);
+            return null;
+        }
+        finally {
+            this.isSyncing = false;
+        }
+    }
+}

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

@@ -0,0 +1,40 @@
+export class ModelStore {
+    constructor(modelClass: any, fetchFn: any, initialGroundTruth?: null, initialOperations?: null, options?: {});
+    modelClass: any;
+    fetchFn: any;
+    groundTruthArray: never[];
+    operationsMap: Map<any, any>;
+    isSyncing: boolean;
+    pruneThreshold: any;
+    modelCache: Cache;
+    /**
+     * Load operations from data and add them to the operations map,
+     * reusing existing operations from the registry if they exist
+     */
+    _loadOperations(operationsData: any): void;
+    get cacheKey(): string;
+    onHydrated(): void;
+    setCache(result: any): void;
+    clearCache(): void;
+    updateCache(items: any, requestedPks: any): void;
+    get operations(): any[];
+    get pkField(): any;
+    addOperation(operation: any): void;
+    updateOperation(operation: any): boolean;
+    confirm(operation: any): void;
+    reject(operation: any): void;
+    setOperations(operations?: any[]): void;
+    setGroundTruth(groundTruth: any): void;
+    getGroundTruth(): never[];
+    get groundTruthPks(): never[];
+    addToGroundTruth(instances: any): void;
+    _filteredOperations(pks: any, operations: any): any;
+    _filteredGroundTruth(pks: any, groundTruthArray: any): Map<any, any>;
+    applyOperation(operation: any, currentInstances: any): any;
+    getTrimmedOperations(): any[];
+    getInflightOperations(): any[];
+    prune(): void;
+    render(pks?: null, optimistic?: boolean): any[];
+    sync(pks?: null): Promise<void>;
+}
+import { Cache } from '../cache/cache.js';