@statezero/core 0.2.38 → 0.2.39

package/dist/syncEngine/metrics/metricOptCalcs.js

@@ -0,0 +1,284 @@
+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 _a, _MetricStrategyFactory_customStrategies, _MetricStrategyFactory_defaultStrategies, _MetricStrategyFactory_generateStrategyKey;
+import { Status, Type } from '../stores/operation.js';
+import { isNil } from 'lodash-es';
+/**
+ * Base class for metric calculation strategies with operations
+ */
+export class MetricCalculationStrategy {
+    /**
+     * Calculate metric based on ground truth and operations
+     */
+    calculateWithOperations(baseValue, operations, field, ModelClass) {
+        // Initialize the current value based on the metric type
+        let currentValue = baseValue === null ? this.getInitialValue() : baseValue;
+        // Process operations sequentially
+        for (const op of operations) {
+            // Skip rejected operations
+            if (op.status === Status.REJECTED)
+                continue;
+            // Process each instance in the operation
+            op.frozenInstances.forEach((originalData, index) => {
+                let pk = originalData[ModelClass.primaryKeyField];
+                // Get the updated data for this instance (for UPDATE operations)
+                const updatedData = op.instances[index] || null;
+                // Create operation data object for the reducer
+                const singleOp = {
+                    originalData, // Pre-operation state
+                    updatedData, // Post-operation state (for updates)
+                    type: op.type,
+                    status: op.status
+                };
+                // Apply this single operation using the strategy-specific reducer
+                currentValue = this.reduceOperation(currentValue, singleOp, field);
+            });
+        }
+        return currentValue;
+    }
+    /**
+     * Get initial value for the metric type
+     * Override in subclasses if needed
+     */
+    getInitialValue() {
+        return 0; // Default for count and sum
+    }
+    /**
+     * Process a single operation - implement in subclasses
+     */
+    reduceOperation(currentValue, operation, field) {
+        throw new Error('reduceOperation must be implemented by subclass');
+    }
+    /**
+     * Safely get a numeric value from an object
+     */
+    safeGetValue(obj, field) {
+        if (!obj || !field)
+            return 0;
+        const value = obj[field];
+        if (isNil(value))
+            return 0;
+        const numValue = parseFloat(value);
+        return isNaN(numValue) ? 0 : numValue;
+    }
+}
+/**
+ * Count strategy implementation
+ */
+export class CountStrategy extends MetricCalculationStrategy {
+    reduceOperation(currentCount, operation, field) {
+        // Skip rejected operations
+        if (operation.status === Status.REJECTED) {
+            return currentCount;
+        }
+        const { type } = operation;
+        // Handle operation types
+        if (type === Type.CREATE) {
+            return currentCount + 1;
+        }
+        else if ([Type.DELETE, Type.DELETE_INSTANCE].includes(type)) {
+            return Math.max(0, currentCount - 1);
+        }
+        // Other operation types don't affect the count
+        return currentCount;
+    }
+}
+/**
+ * Sum strategy implementation
+ */
+export class SumStrategy extends MetricCalculationStrategy {
+    reduceOperation(currentSum, operation, field) {
+        // Skip rejected operations
+        if (operation.status === Status.REJECTED) {
+            return currentSum;
+        }
+        if (!field) {
+            throw new Error('SumStrategy requires a field parameter');
+        }
+        const { type, originalData, updatedData } = operation;
+        switch (type) {
+            case Type.CREATE:
+                // For CREATE, add the value to the sum
+                return currentSum + this.safeGetValue(originalData, field);
+            case Type.CHECKPOINT:
+            case Type.UPDATE:
+                // For UPDATE, subtract old value and add new value
+                if (updatedData) {
+                    const oldValue = this.safeGetValue(originalData, field);
+                    const newValue = this.safeGetValue(updatedData, field);
+                    return currentSum - oldValue + newValue;
+                }
+                return currentSum;
+            case Type.DELETE:
+            case Type.DELETE_INSTANCE:
+                // For DELETE, subtract the value from the sum
+                return currentSum - this.safeGetValue(originalData, field);
+            default:
+                return currentSum;
+        }
+    }
+}
+/**
+ * Min strategy implementation
+ */
+export class MinStrategy extends MetricCalculationStrategy {
+    getInitialValue() {
+        return Infinity;
+    }
+    reduceOperation(currentMin, operation, field) {
+        // Skip rejected operations
+        if (operation.status === Status.REJECTED) {
+            return currentMin;
+        }
+        if (!field) {
+            throw new Error('MinStrategy requires a field parameter');
+        }
+        const { type, originalData, updatedData } = operation;
+        if (type === Type.CREATE) {
+            // For CREATE, check if the new value is smaller than current min
+            const value = this.safeGetValue(originalData, field);
+            return Math.min(currentMin, value);
+        }
+        else if ((type === Type.UPDATE || type.CHECKPOINT) && updatedData) {
+            // For UPDATE, first check if we're updating the minimum value
+            const oldValue = this.safeGetValue(originalData, field);
+            const newValue = this.safeGetValue(updatedData, field);
+            if (oldValue === currentMin) {
+                // We're updating the current minimum, need to find the new minimum
+                if (newValue <= oldValue) {
+                    // Simple case: new value is still the minimum
+                    return newValue;
+                }
+                else {
+                    // Harder case: need to recalculate minimum
+                    // For now, conservatively use the new value
+                    return newValue;
+                }
+            }
+            else if (newValue < currentMin) {
+                // The updated value is a new minimum
+                return newValue;
+            }
+        }
+        // For other cases, maintain current min
+        return currentMin;
+    }
+}
+/**
+ * Max strategy implementation
+ */
+export class MaxStrategy extends MetricCalculationStrategy {
+    getInitialValue() {
+        return -Infinity;
+    }
+    reduceOperation(currentMax, operation, field) {
+        // Skip rejected operations
+        if (operation.status === Status.REJECTED) {
+            return currentMax;
+        }
+        if (!field) {
+            throw new Error('MaxStrategy requires a field parameter');
+        }
+        const { type, originalData, updatedData } = operation;
+        if (type === Type.CREATE) {
+            // For CREATE, check if the new value is larger than current max
+            const value = this.safeGetValue(originalData, field);
+            return Math.max(currentMax, value);
+        }
+        else if ((type === Type.UPDATE || type === Type.CHECKPOINT) && updatedData) {
+            // For UPDATE, first check if we're updating the maximum value
+            const oldValue = this.safeGetValue(originalData, field);
+            const newValue = this.safeGetValue(updatedData, field);
+            if (oldValue === currentMax) {
+                // We're updating the current maximum, need to find the new maximum
+                if (newValue >= oldValue) {
+                    // Simple case: new value is still the maximum
+                    return newValue;
+                }
+                else {
+                    // Harder case: need to recalculate maximum
+                    // For now, conservatively use the new value
+                    return newValue;
+                }
+            }
+            else if (newValue > currentMax) {
+                // The updated value is a new maximum
+                return newValue;
+            }
+        }
+        // For other cases, maintain current max
+        return currentMax;
+    }
+}
+/**
+ * Factory class for creating the appropriate strategy
+ */
+export class MetricStrategyFactory {
+    /**
+     * Clear all custom strategy overrides
+     */
+    static clearCustomStrategies() {
+        __classPrivateFieldGet(this, _a, "f", _MetricStrategyFactory_customStrategies).clear();
+    }
+    /**
+     * Override a strategy for a specific metric type and model class
+     * @param {string} metricType - The type of metric (count, sum, min, max)
+     * @param {Function|null} ModelClass - The model class or null for a generic override
+     * @param {MetricCalculationStrategy} strategy - The strategy to use
+     */
+    static overrideStrategy(metricType, ModelClass, strategy) {
+        if (!metricType || !strategy) {
+            throw new Error('overrideStrategy requires metricType and strategy');
+        }
+        if (!(strategy instanceof MetricCalculationStrategy)) {
+            throw new Error('strategy must be an instance of MetricCalculationStrategy');
+        }
+        let key;
+        if (ModelClass) {
+            // Model-specific override
+            key = __classPrivateFieldGet(this, _a, "m", _MetricStrategyFactory_generateStrategyKey).call(this, metricType, ModelClass);
+        }
+        else {
+            // Generic override for all models
+            key = `${metricType}::*::*`;
+        }
+        __classPrivateFieldGet(this, _a, "f", _MetricStrategyFactory_customStrategies).set(key, strategy);
+    }
+    /**
+     * Get the appropriate strategy for a model class and metric type
+     * @param {string} metricType - The type of metric (count, sum, min, max)
+     * @param {Function} ModelClass - The model class
+     * @returns {MetricCalculationStrategy} The appropriate strategy
+     */
+    static getStrategy(metricType, ModelClass) {
+        const normalizedMetricType = metricType.toLowerCase();
+        // Check for model-specific override first
+        const specificKey = __classPrivateFieldGet(this, _a, "m", _MetricStrategyFactory_generateStrategyKey).call(this, normalizedMetricType, ModelClass);
+        if (__classPrivateFieldGet(this, _a, "f", _MetricStrategyFactory_customStrategies).has(specificKey)) {
+            return __classPrivateFieldGet(this, _a, "f", _MetricStrategyFactory_customStrategies).get(specificKey);
+        }
+        // Check for metric-only override (works across all models)
+        const genericKey = `${normalizedMetricType}::*::*`;
+        if (__classPrivateFieldGet(this, _a, "f", _MetricStrategyFactory_customStrategies).has(genericKey)) {
+            return __classPrivateFieldGet(this, _a, "f", _MetricStrategyFactory_customStrategies).get(genericKey);
+        }
+        // Otherwise, return the default strategy based on the metric type
+        const strategyCreator = __classPrivateFieldGet(this, _a, "f", _MetricStrategyFactory_defaultStrategies).get(normalizedMetricType) || __classPrivateFieldGet(this, _a, "f", _MetricStrategyFactory_defaultStrategies).get('count');
+        return strategyCreator();
+    }
+}
+_a = MetricStrategyFactory, _MetricStrategyFactory_generateStrategyKey = function _MetricStrategyFactory_generateStrategyKey(metricType, ModelClass) {
+    return `${metricType}::${ModelClass.configKey}::${ModelClass.modelName}`;
+};
+// Collection of custom strategy overrides
+_MetricStrategyFactory_customStrategies = { value: new Map() };
+// Default strategy map
+_MetricStrategyFactory_defaultStrategies = { value: new Map([
+        ['count', () => new CountStrategy()],
+        ['sum', () => new SumStrategy()],
+        ['min', () => new MinStrategy()],
+        ['max', () => new MaxStrategy()]
+    ]) };

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

@@ -0,0 +1,58 @@
+/**
+ * LiveMetric, a simple wrapper that always returns the latest metric value
+ * using a getter for the value property
+ */
+export class LiveMetric {
+    constructor(queryset: any, metricType: any, field?: null);
+    queryset: any;
+    metricType: any;
+    field: any;
+    get lqs(): import("./querysetStoreRegistry.js").LiveQueryset;
+    /**
+     * Refresh the metric data from the database
+     * Delegates to the underlying store's sync method
+     */
+    refreshFromDb(): any;
+    /**
+     * Getter that always returns the current value from the store
+     */
+    get value(): any;
+}
+/**
+ * Registry to manage metric stores
+ */
+export class MetricRegistry {
+    _stores: Map<any, any>;
+    syncManager: any;
+    clear(): void;
+    setSyncManager(syncManager: any): void;
+    /**
+     * Get all metric stores that match a specific queryset
+     * @param {Queryset} queryset - The queryset to match
+     * @returns {Array} Array of metric stores
+     */
+    getAllStoresForQueryset(queryset: Queryset): any[];
+    _makeKey(metricType: any, queryset: any, field?: null): string;
+    /**
+     * Get a metric store for a specific queryset and metric type
+     */
+    getStore(metricType: any, queryset: any, field?: null): any;
+    /**
+     * Get a metric value for a specific queryset
+     */
+    getEntity(metricType: any, queryset: any, field?: null): Object | null;
+    /**
+     * Set metric ground truth value
+     */
+    setEntity(metricType: any, queryset: any, field: any, value: any): any;
+    /**
+     * Sync a specific metric with the server
+     */
+    syncMetric(metricType: any, queryset: any, field?: null): any;
+    /**
+     * Get the queryset for a specific key
+     * Useful for debugging or auditing
+     */
+    getQuerysetForKey(key: any): any;
+}
+export const metricRegistry: MetricRegistry;

package/dist/syncEngine/registries/metricRegistry.js

@@ -0,0 +1,171 @@
+import { MetricStore } from '../stores/metricStore.js';
+import { isNil, isEmpty } from 'lodash-es';
+import { querysetStoreRegistry } from './querysetStoreRegistry.js';
+import { QueryExecutor } from '../../flavours/django/queryExecutor.js';
+import { wrapReactiveMetric } from '../../reactiveAdaptor.js';
+import hash from 'object-hash';
+/**
+ * LiveMetric, a simple wrapper that always returns the latest metric value
+ * using a getter for the value property
+ */
+export class LiveMetric {
+    constructor(queryset, metricType, field = null) {
+        this.queryset = queryset;
+        this.metricType = metricType;
+        this.field = field;
+    }
+    get lqs() {
+        return querysetStoreRegistry.getEntity(this.queryset);
+    }
+    /**
+     * Refresh the metric data from the database
+     * Delegates to the underlying store's sync method
+     */
+    refreshFromDb() {
+        const store = metricRegistry.getStore(this.metricType, this.queryset, this.field);
+        return store.sync(true);
+    }
+    /**
+     * Getter that always returns the current value from the store
+     */
+    get value() {
+        // Get the latest store from the registry
+        const store = metricRegistry.getStore(this.metricType, this.queryset, this.field);
+        if (!store) {
+            return null;
+        }
+        // Render the current value
+        return store.render();
+    }
+}
+/**
+ * Registry to manage metric stores
+ */
+export class MetricRegistry {
+    constructor() {
+        // Store both the store and a reference to the queryset as a tuple
+        this._stores = new Map();
+        this.syncManager = null;
+    }
+    clear() {
+        for (const entry of this._stores.values()) {
+            this.syncManager.unfollowModel(this, entry.store.modelClass);
+        }
+        this._stores = new Map();
+    }
+    setSyncManager(syncManager) {
+        this.syncManager = syncManager;
+    }
+    /**
+     * Get all metric stores that match a specific queryset
+     * @param {Queryset} queryset - The queryset to match
+     * @returns {Array} Array of metric stores
+     */
+    getAllStoresForQueryset(queryset) {
+        if (isNil(queryset) || isNil(queryset.ModelClass)) {
+            return [];
+        }
+        const stores = [];
+        const modelClass = queryset.ModelClass;
+        for (const [key, entry] of this._stores.entries()) {
+            const store = entry.store;
+            // First check if model class matches
+            if (store.modelClass !== modelClass) {
+                continue;
+            }
+            if (store.queryset.semanticKey != queryset.semanticKey) {
+                continue;
+            }
+            stores.push(store);
+        }
+        return stores;
+    }
+    _makeKey(metricType, queryset, field = null) {
+        const modelClass = queryset.ModelClass;
+        const ast = queryset.build();
+        return `${metricType}::${modelClass.configKey}::${modelClass.modelName}::${field || 'null'}::${hash(ast)}`;
+    }
+    /**
+     * Get a metric store for a specific queryset and metric type
+     */
+    getStore(metricType, queryset, field = null) {
+        if (isNil(metricType) || isNil(queryset) || isNil(queryset.ModelClass)) {
+            return null;
+        }
+        const modelClass = queryset.ModelClass;
+        const ast = queryset.build();
+        const key = this._makeKey(metricType, queryset, field);
+        if (!this._stores.has(key)) {
+            // Create fetch function for this metric
+            const fetchMetricFn = async ({ metricType, modelClass, field, ast }) => {
+                const qs = queryset.clone();
+                return await QueryExecutor.executeAgg(qs, metricType, { field });
+            };
+            // Create new store
+            const store = new MetricStore(metricType, modelClass, queryset, field, ast, fetchMetricFn);
+            // Store both the store and a reference to the queryset
+            this._stores.set(key, {
+                store,
+                queryset // This keeps the queryset alive
+            });
+            this.syncManager.followModel(this, store.modelClass);
+        }
+        return this._stores.get(key).store;
+    }
+    /**
+     * Get a metric value for a specific queryset
+     */
+    getEntity(metricType, queryset, field = null) {
+        // defensive checks
+        if (isNil(metricType) || isNil(queryset) || isNil(queryset.ModelClass)) {
+            return null;
+        }
+        // Get the store (creates if doesn't exist)
+        const store = this.getStore(metricType, queryset, field);
+        // Create a LiveMetric that will always get the latest store and value
+        const liveMetric = new LiveMetric(queryset, metricType, field);
+        // If we're in a reactive environment, wrap the metric
+        return wrapReactiveMetric(liveMetric);
+    }
+    /**
+     * Set metric ground truth value
+     */
+    setEntity(metricType, queryset, field, value) {
+        // defensive checks
+        if (isNil(metricType) || isNil(queryset) || isNil(queryset.ModelClass)) {
+            return null;
+        }
+        const store = this.getStore(metricType, queryset, field);
+        if (!store) {
+            return null;
+        }
+        // check if the store already has a ground truth or operations
+        if (!isNil(store.groundTruthValue) || !isEmpty(store.operations)) {
+            store.reset();
+        }
+        store.setGroundTruth(value);
+        return value;
+    }
+    /**
+     * Sync a specific metric with the server
+     */
+    syncMetric(metricType, queryset, field = null) {
+        const store = this.getStore(metricType, queryset, field);
+        if (store) {
+            return store.sync();
+        }
+        return null;
+    }
+    /**
+     * Get the queryset for a specific key
+     * Useful for debugging or auditing
+     */
+    getQuerysetForKey(key) {
+        if (this._stores.has(key)) {
+            return this._stores.get(key).queryset;
+        }
+        return null;
+    }
+}
+// Export singleton instance
+export const metricRegistry = new MetricRegistry();

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

@@ -0,0 +1,11 @@
+export class ModelStoreRegistry {
+    _stores: Map<any, any>;
+    syncManager: () => void;
+    clear(): void;
+    setSyncManager(syncManager: any): void;
+    getStore(modelClass: any): any;
+    getEntity(modelClass: any, pk: any): any;
+    setEntity(modelClass: any, pk: any, data: any): any;
+    setEntities(modelClass: any, entities: any): void;
+}
+export const modelStoreRegistry: ModelStoreRegistry;

package/dist/syncEngine/registries/modelStoreRegistry.js

@@ -0,0 +1,63 @@
+import { ModelStore } from '../stores/modelStore.js';
+import { isNil } from 'lodash-es';
+export class ModelStoreRegistry {
+    constructor() {
+        this._stores = new Map();
+        this.syncManager = () => { console.warn("SyncManager not set for ModelStoreRegistry"); };
+    }
+    clear() {
+        for (const modelClass of this._stores.keys()) {
+            this.syncManager.unfollowModel(this, modelClass);
+        }
+        this._stores = new Map();
+    }
+    setSyncManager(syncManager) {
+        this.syncManager = syncManager;
+    }
+    getStore(modelClass) {
+        if (!this._stores.has(modelClass)) {
+            // Create a new ModelStore on demand
+            const fetchModels = async ({ pks, modelClass }) => {
+                return await modelClass.objects.filter({
+                    [`${modelClass.primaryKeyField}__in`]: pks
+                }).fetch().serialize();
+            };
+            this._stores.set(modelClass, new ModelStore(modelClass, fetchModels, null, null));
+            this.syncManager.followModel(this, modelClass);
+        }
+        return this._stores.get(modelClass);
+    }
+    // Get a single entity from the store
+    getEntity(modelClass, pk) {
+        // defensive checks for this nested func
+        if (isNil(modelClass) || isNil(pk))
+            return;
+        if (pk[modelClass.primaryKeyField])
+            throw new Error("getEntity should be called with a pk not an object");
+        // logic
+        const store = this.getStore(modelClass);
+        const renderedData = store.render([pk]);
+        return renderedData[0] || null;
+    }
+    // Add or update an entity ground truth in the store, not for operations!
+    setEntity(modelClass, pk, data) {
+        // defensive checks for this nested func
+        if (isNil(modelClass) || isNil(pk))
+            return;
+        if (pk[modelClass.primaryKeyField])
+            throw new Error("getEntity should be called with a pk not an object");
+        // logic
+        const store = this.getStore(modelClass);
+        store.addToGroundTruth([data]);
+        return data;
+    }
+    // Batch add or update entities in the store ground truth
+    setEntities(modelClass, entities) {
+        if (isNil(modelClass) || !entities?.length)
+            return;
+        const store = this.getStore(modelClass);
+        store.addToGroundTruth(entities);
+    }
+}
+// Export singleton instance
+export const modelStoreRegistry = new ModelStoreRegistry();

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

@@ -0,0 +1,41 @@
+/**
+ * Simple graph for tracking queryset store ancestry
+ */
+export class QuerysetStoreGraph {
+    graph: any;
+    processedQuerysets: Set<any>;
+    /**
+     * Add a queryset and its parent relationship to the graph
+     */
+    addQueryset(queryset: any): void;
+    /**
+     * Find the root (topmost ancestor) of a queryset chain within a subset.
+     * Traverses up the graph but only considers nodes that are in the subset.
+     * Uses the graph to "jump" through nodes not in subset to find connections.
+     *
+     * @param {Object} queryset - The queryset to analyze
+     * @param {Set|null} subset - Set of semanticKeys to consider. If null, considers all nodes in graph.
+     * @returns {Object} { isRoot: boolean, root: semanticKey|null }
+     */
+    findRoot(queryset: Object, subset?: Set<any> | null): Object;
+    /**
+     * Check if parent queryset is a valid data source for creating an edge.
+     * Parent must have data that is a superset of what child needs.
+     * Child with offset must sync independently (can't derive window from parent).
+     *
+     * @param {Object} parentOpts - Parent's serializerOptions
+     * @param {Object} childOpts - Child's serializerOptions
+     * @param {Array|undefined} parentOrderBy - Parent's ordering
+     * @param {Array|undefined} childOrderBy - Child's ordering
+     * @returns {boolean} - True if parent is valid for edge creation
+     */
+    _isValidParentForEdge(parentOpts: Object | undefined, childOpts: Object | undefined, parentOrderBy: any[] | undefined, childOrderBy: any[] | undefined): boolean;
+    /**
+     * Check if two orderings are equivalent.
+     * @param {Array|undefined} orderBy1
+     * @param {Array|undefined} orderBy2
+     * @returns {boolean}
+     */
+    _orderingsMatch(orderBy1: any[] | undefined, orderBy2: any[] | undefined): boolean;
+    clear(): void;
+}