@statezero/core 0.2.38 → 0.2.40

package/dist/syncEngine/stores/operationEventHandlers.js

@@ -0,0 +1,348 @@
+import { operationEvents, Status, Type, operationRegistry, OperationMembership } from './operation.js';
+import { modelStoreRegistry } from '../registries/modelStoreRegistry.js';
+import { querysetStoreRegistry } from '../registries/querysetStoreRegistry.js';
+import { metricRegistry } from '../registries/metricRegistry.js';
+import { getFingerprint } from './utils.js';
+import { QuerySet } from '../../flavours/django/querySet.js';
+import { isEqual, isNil } from 'lodash-es';
+import hash from 'object-hash';
+import { filter, applyOrderBy } from '../../filtering/localFiltering.js';
+/**
+ * Evaluates and routes a CREATE operation to querysets, tracking membership state.
+ *
+ * For each queryset:
+ * - If offset > 0: mark as MAYBE (can't determine position based on slicing)
+ * - If item doesn't match filter: mark DEFINITELY_NO
+ * - If item matches filter AND (no limit OR count < limit): mark DEFINITELY_YES
+ * - If item matches filter AND count >= limit: mark MAYBE (ordering determines inclusion)
+ *
+ * @param {Operation} operation - The CREATE operation to route
+ * @param {Function} applyAction - Function to apply the operation to a store
+ */
+function routeCreateOperation(operation, applyAction) {
+    const modelClass = operation.queryset.ModelClass;
+    const instances = operation.instances;
+    Array.from(querysetStoreRegistry._stores.entries()).forEach(([semanticKey, store]) => {
+        if (store.modelClass !== modelClass)
+            return;
+        const serializerOptions = store.queryset?._serializerOptions || {};
+        const { offset, limit } = serializerOptions;
+        // Offset > 0: can't determine position based on slicing
+        if (offset != null && offset > 0) {
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.MAYBE);
+            return;
+        }
+        // Evaluate if instances match this queryset's filter
+        const ast = store.queryset.build();
+        const matchingInstances = filter(instances, ast, modelClass, true);
+        if (matchingInstances.length === 0) {
+            // No instances match - mark DEFINITELY_NO (no need to sync this queryset)
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+            return;
+        }
+        // Item matches filter - check limit
+        if (limit != null) {
+            const currentCount = store.groundTruthPks?.length || 0;
+            // At capacity: check if ordering could affect position
+            if (currentCount >= limit) {
+                // Check explicit ordering on queryset OR implicit ordering from Django Meta
+                const hasExplicitOrdering = store.queryset._orderBy && store.queryset._orderBy.length > 0;
+                const hasImplicitOrdering = (modelClass.schema?.default_ordering?.length || 0) > 0;
+                if (hasExplicitOrdering || hasImplicitOrdering) {
+                    // Use local sorting to determine if new items would be in top N
+                    const orderBy = hasExplicitOrdering
+                        ? store.queryset._orderBy
+                        : modelClass.schema.default_ordering;
+                    // Get current items from model store
+                    const modelStore = modelStoreRegistry.getStore(modelClass);
+                    const renderedItems = modelStore.render(store.groundTruthPks, true, false) || [];
+                    const currentItems = renderedItems.filter(Boolean);
+                    // If some ground truth items couldn't be rendered, we can't trust local sort
+                    if (currentItems.length < store.groundTruthPks.length) {
+                        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.MAYBE);
+                        return;
+                    }
+                    const allItems = [...currentItems, ...matchingInstances];
+                    // Sort and take top N
+                    const sorted = applyOrderBy(allItems, orderBy, modelClass);
+                    const topN = sorted.slice(0, limit);
+                    const topNPks = new Set(topN.map(item => item[modelClass.primaryKeyField]));
+                    // Check if any new items made it into the top N
+                    const newItemPks = matchingInstances.map(item => item[modelClass.primaryKeyField]);
+                    const anyInTopN = newItemPks.some(pk => topNPks.has(pk));
+                    if (anyInTopN) {
+                        applyAction(store);
+                        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_YES);
+                    }
+                    else {
+                        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+                    }
+                }
+                else {
+                    // No ordering - new items go at end, won't be in first N
+                    operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+                }
+                return;
+            }
+            // Room for some or all items - continue to DEFINITELY_YES below
+        }
+        // Matches filter, has room or no limit - DEFINITELY_YES
+        applyAction(store);
+        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_YES);
+    });
+}
+/**
+ * Evaluates and tracks membership state for UPDATE operations.
+ *
+ * For UPDATE, we check filter FIRST (optimization), then offset:
+ * - If item didn't match before AND doesn't match after: DEFINITELY_NO (regardless of offset)
+ * - If item matched before OR matches after AND offset > 0: MAYBE (can't determine position)
+ * - If item matched before OR matches after AND offset = 0: DEFINITELY_YES
+ *
+ * @param {Operation} operation - The UPDATE operation
+ */
+function routeUpdateOperation(operation) {
+    const modelClass = operation.queryset.ModelClass;
+    const beforeInstances = operation.frozenInstances;
+    const afterInstances = operation.instances;
+    Array.from(querysetStoreRegistry._stores.entries()).forEach(([semanticKey, store]) => {
+        if (store.modelClass !== modelClass)
+            return;
+        // Check filter match FIRST (optimization: skip offset check if no match)
+        const ast = store.queryset.build();
+        const matchedBefore = filter(beforeInstances, ast, modelClass, false).length > 0;
+        const matchesAfter = filter(afterInstances, ast, modelClass, false).length > 0;
+        // If item never matched filter, definitely not affected (regardless of offset)
+        if (!matchedBefore && !matchesAfter) {
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+            return;
+        }
+        // Item matches filter - now check offset
+        const serializerOptions = store.queryset?._serializerOptions || {};
+        const { offset } = serializerOptions;
+        if (offset != null && offset > 0) {
+            // Can't determine position in paginated window
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.MAYBE);
+            return;
+        }
+        // Item matched before OR matches after, no offset - definitely affected
+        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_YES);
+    });
+}
+/**
+ * Evaluates and tracks membership state for DELETE operations.
+ *
+ * For DELETE, we check filter FIRST (optimization), then offset:
+ * - If item didn't match before: DEFINITELY_NO (regardless of offset)
+ * - If item matched before AND offset > 0: MAYBE (can't determine position)
+ * - If item matched before AND offset = 0: DEFINITELY_YES
+ *
+ * @param {Operation} operation - The DELETE operation
+ */
+function routeDeleteOperation(operation) {
+    const modelClass = operation.queryset.ModelClass;
+    const beforeInstances = operation.frozenInstances;
+    Array.from(querysetStoreRegistry._stores.entries()).forEach(([semanticKey, store]) => {
+        if (store.modelClass !== modelClass)
+            return;
+        // Check filter match FIRST (optimization: skip offset check if no match)
+        const ast = store.queryset.build();
+        const matchedBefore = filter(beforeInstances, ast, modelClass, false).length > 0;
+        // If item never matched filter, definitely not affected (regardless of offset)
+        if (!matchedBefore) {
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_NO);
+            return;
+        }
+        // Item matched filter - now check offset
+        const serializerOptions = store.queryset?._serializerOptions || {};
+        const { offset } = serializerOptions;
+        if (offset != null && offset > 0) {
+            // Can't determine position in paginated window
+            operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.MAYBE);
+            return;
+        }
+        // Item matched before, no offset - definitely affected
+        operationRegistry.setQuerysetState(operation.operationId, semanticKey, OperationMembership.DEFINITELY_YES);
+    });
+}
+/**
+ * Process an operation in the model store
+ *
+ * @param {Operation} operation - The operation to process
+ * @param {string} actionType - The action to perform ('add', 'update', 'confirm', 'reject')
+ */
+function processModelStore(operation, actionType) {
+    const ModelClass = operation.queryset.ModelClass;
+    const modelStore = modelStoreRegistry.getStore(ModelClass);
+    if (!modelStore)
+        return;
+    switch (actionType) {
+        case 'add':
+            modelStore.addOperation(operation);
+            break;
+        case 'update':
+            modelStore.updateOperation(operation);
+            break;
+        case 'confirm':
+            modelStore.confirm(operation);
+            break;
+        case 'reject':
+            modelStore.reject(operation);
+            break;
+    }
+}
+/**
+ * Process an operation in the queryset stores based on operation type
+ * Uses different routing strategies based on the operation type
+ *
+ * @param {Operation} operation - The operation to process
+ * @param {string} actionType - The action to perform ('add', 'update', 'confirm', 'reject')
+ */
+function processQuerysetStores(operation, actionType) {
+    const ModelClass = operation.queryset.ModelClass;
+    const queryset = operation.queryset;
+    // Apply the appropriate action to a single queryset store
+    const applyAction = (store) => {
+        switch (actionType) {
+            case 'add':
+                store.addOperation(operation);
+                break;
+            case 'update':
+                store.updateOperation(operation);
+                break;
+            case 'confirm':
+                store.confirm(operation);
+                break;
+            case 'reject':
+                store.reject(operation);
+                break;
+        }
+    };
+    let querysetStoreMap;
+    // Route to querysets based on operation type
+    // All operation types track membership state for sync optimization
+    // CREATE: adds operation to store + tracks membership
+    // UPDATE/DELETE: only tracks membership (model store + reactivity handles rendering)
+    switch (operation.type) {
+        case Type.CREATE:
+        case Type.BULK_CREATE:
+        case Type.GET_OR_CREATE:
+        case Type.UPDATE_OR_CREATE:
+            // For creates, evaluate each queryset and track membership state
+            // This allows us to skip syncing querysets that we know don't contain the item
+            routeCreateOperation(operation, applyAction);
+            return;
+        case Type.UPDATE:
+        case Type.UPDATE_INSTANCE:
+            // Track membership for sync optimization
+            // Check both before (frozenInstances) and after (instances) state
+            routeUpdateOperation(operation);
+            return;
+        case Type.DELETE:
+        case Type.DELETE_INSTANCE:
+            // Track membership for sync optimization
+            // Check before state only (item being deleted)
+            routeDeleteOperation(operation);
+            return;
+        case Type.CHECKPOINT:
+            // Model store handles the change, querysets re-render via local filtering
+            // No membership tracking needed for checkpoints
+            return;
+        default:
+            // For other operation types, route like creates
+            routeCreateOperation(operation, applyAction);
+            return;
+    }
+}
+/**
+ * Process an operation in the metric stores
+ *
+ * For metrics, we route operations UP the family tree - any metric on an ancestor
+ * queryset should receive the operation so it can check if it affects the metric.
+ *
+ * @param {Operation} operation - The operation to process
+ * @param {string} actionType - The action to perform ('add', 'update', 'confirm', 'reject')
+ */
+function processMetricStores(operation, actionType) {
+    const queryset = operation.queryset;
+    const allMetricStores = new Set();
+    // Walk up the queryset family tree and collect all metrics
+    let current = queryset;
+    while (current) {
+        const stores = metricRegistry.getAllStoresForQueryset(current);
+        if (stores && stores.length > 0) {
+            stores.forEach(store => allMetricStores.add(store));
+        }
+        current = current.__parent;
+    }
+    if (allMetricStores.size === 0) {
+        return;
+    }
+    // Apply the action to each matching metric store
+    allMetricStores.forEach(store => {
+        switch (actionType) {
+            case 'add':
+                store.addOperation(operation);
+                break;
+            case 'update':
+                store.updateOperation(operation);
+                break;
+            case 'confirm':
+                store.confirm(operation);
+                break;
+            case 'reject':
+                store.reject(operation);
+                break;
+        }
+    });
+}
+/**
+ * Common processing logic for operations, handling validation and routing
+ * to the appropriate store processors
+ *
+ * @param {Operation} operation - The operation to process
+ * @param {string} actionType - The action to perform ('add', 'update', 'confirm', 'reject')
+ */
+function processOperation(operation, actionType) {
+    if (!operation || !operation.queryset || !operation.queryset.ModelClass) {
+        console.warn(`Received invalid operation in processOperation (${actionType})`, operation);
+        return;
+    }
+    if (operation.doNotPropagate) {
+        return;
+    }
+    // Process model store first
+    processModelStore(operation, actionType);
+    // Then process queryset stores with improved routing
+    processQuerysetStores(operation, actionType);
+    // Finally process metric stores
+    processMetricStores(operation, actionType);
+}
+// Define handlers as named arrow functions at the top level
+const handleOperationCreated = operation => processOperation(operation, 'add');
+const handleOperationUpdated = operation => processOperation(operation, 'update');
+const handleOperationMutated = operation => processOperation(operation, 'update');
+const handleOperationConfirmed = operation => processOperation(operation, 'confirm');
+const handleOperationRejected = operation => processOperation(operation, 'reject');
+/**
+ * Initialize the operation event handler system by setting up event listeners
+ */
+export function initEventHandler() {
+    operationEvents.on(Status.CREATED, handleOperationCreated);
+    operationEvents.on(Status.UPDATED, handleOperationUpdated);
+    operationEvents.on(Status.CONFIRMED, handleOperationConfirmed);
+    operationEvents.on(Status.REJECTED, handleOperationRejected);
+    operationEvents.on(Status.MUTATED, handleOperationMutated);
+    console.log('Operation event handler initialized');
+}
+/**
+ * Clean up by removing all event listeners
+ */
+export function cleanupEventHandler() {
+    operationEvents.off(Status.CREATED, handleOperationCreated);
+    operationEvents.off(Status.UPDATED, handleOperationUpdated);
+    operationEvents.off(Status.CONFIRMED, handleOperationConfirmed);
+    operationEvents.off(Status.REJECTED, handleOperationRejected);
+    operationEvents.off(Status.MUTATED, handleOperationMutated);
+    console.log('Operation event handler cleaned up');
+}

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

@@ -0,0 +1,60 @@
+export class QuerysetStore {
+    constructor(modelClass: any, fetchFn: any, queryset: any, initialGroundTruthPks?: null, initialOperations?: null, options?: {});
+    modelClass: any;
+    fetchFn: any;
+    queryset: any;
+    operationsMap: Map<any, any>;
+    groundTruthPks: never[];
+    isSyncing: boolean;
+    lastSync: number | null;
+    isTemp: any;
+    pruneThreshold: any;
+    includedPks: Map<any, any>;
+    qsCache: Cache;
+    _lastRenderedPks: any[] | null;
+    renderCallbacks: Set<any>;
+    _modelStoreUnregister: any;
+    get cacheKey(): any;
+    onHydrated(hydratedData: any): void;
+    setCache(result: any): void;
+    clearCache(): void;
+    get operations(): any[];
+    get pkField(): any;
+    get groundTruthSet(): Set<never>;
+    _emitRenderEvent(): void;
+    addOperation(operation: any): Promise<void>;
+    updateOperation(operation: any): Promise<true | undefined>;
+    confirm(operation: any): Promise<void>;
+    reject(operation: any): Promise<void>;
+    setGroundTruth(groundTruthPks: any): Promise<void>;
+    setOperations(operations: any): Promise<void>;
+    getTrimmedOperations(): any[];
+    getInflightOperations(): any[];
+    prune(): void;
+    registerRenderCallback(callback: any): () => boolean;
+    /**
+     * Register this store with the model store for change notifications.
+     * Called when a temp store is promoted to permanent.
+     */
+    registerWithModelStore(): void;
+    /**
+     * Helper to validate PKs against the model store and apply local filtering/sorting.
+     * This is the core of the rendering logic.
+     * @private
+     */
+    private _getValidatedAndFilteredPks;
+    render(optimistic?: boolean, fromCache?: boolean): any[];
+    renderFromData(optimistic?: boolean): any[];
+    /**
+     * Render by getting all instances from the model store and filtering locally.
+     * Used when a queryset has no ground truth (temp stores, newly created stores, etc.)
+     */
+    renderFromModelStore(): any[];
+    applyOperation(operation: any, currentPks: any): any;
+    /**
+     * Sync this queryset with the database.
+     * Fetches from DB and sets ground truth.
+     */
+    sync(): Promise<void>;
+}
+import { Cache } from '../cache/cache.js';