@statezero/core 0.2.38 → 0.2.40

package/dist/syncEngine/stores/querysetStore.js

@@ -0,0 +1,294 @@
+import { Operation, Status, Type, operationRegistry } from './operation.js';
+import { querysetEventEmitter } from './reactivity.js';
+import { isNil, isEmpty, trim, isEqual } 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 { Cache } from '../cache/cache.js';
+import { filter } from "../../filtering/localFiltering.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.lastSync = null;
+        this.isTemp = options.isTemp || false;
+        this.pruneThreshold = options.pruneThreshold || 10;
+        this.groundTruthPks = initialGroundTruthPks || [];
+        this.operationsMap = new Map();
+        // Track which model PKs are in this queryset's included data
+        // Map<modelName, Set<pk>>
+        this.includedPks = 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));
+        this._lastRenderedPks = null;
+        this.renderCallbacks = new Set();
+        // Register for model store changes to re-render when model data changes
+        // Only register permanent stores - temp stores are transient and should not
+        // accumulate callbacks (causes reactivity cascade when Vue creates new querysets)
+        if (!this.isTemp) {
+            const modelStore = modelStoreRegistry.getStore(this.modelClass);
+            this._modelStoreUnregister = modelStore.registerRenderCallback(() => {
+                this._emitRenderEvent();
+            });
+        }
+    }
+    // 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() {
+        const newPks = this.render(true, false);
+        // 1. Always notify direct child stores to trigger their own re-evaluation.
+        //    They will perform their own check to see if their own results have changed.
+        this.renderCallbacks.forEach((callback) => {
+            try {
+                callback();
+            }
+            catch (error) {
+                console.warn("Error in render callback:", error);
+            }
+        });
+        // 2. Only emit the global event for UI components if the final list of PKs has actually changed.
+        if (!isEqual(newPks, this._lastRenderedPks)) {
+            this._lastRenderedPks = newPks; // Update the cache with the new state
+            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.lastSync = Date.now();
+        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());
+    }
+    registerRenderCallback(callback) {
+        this.renderCallbacks.add(callback);
+        return () => this.renderCallbacks.delete(callback);
+    }
+    /**
+     * Register this store with the model store for change notifications.
+     * Called when a temp store is promoted to permanent.
+     */
+    registerWithModelStore() {
+        if (this._modelStoreUnregister)
+            return; // Already registered
+        const modelStore = modelStoreRegistry.getStore(this.modelClass);
+        this._modelStoreUnregister = modelStore.registerRenderCallback(() => {
+            this._emitRenderEvent();
+        });
+    }
+    /**
+     * Helper to validate PKs against the model store and apply local filtering/sorting.
+     * This is the core of the rendering logic.
+     * @private
+     */
+    _getValidatedAndFilteredPks(pks) {
+        // 1. Convert PKs to instances, filtering out any that are null (deleted).
+        const instances = Array.from(pks)
+            .map((pk) => this.modelClass.fromPk(pk, this.queryset))
+            .filter((instance) => modelStoreRegistry.getEntity(this.modelClass, instance.pk) !== null);
+        // 2. Apply the queryset's AST (filters, ordering) to the validated instances.
+        const ast = this.queryset.build();
+        const finalPks = filter(instances, ast, this.modelClass, false); // false = return PKs
+        return finalPks;
+    }
+    render(optimistic = true, fromCache = false) {
+        // Check cache first if requested
+        if (fromCache) {
+            const cachedResult = this.qsCache.get(this.cacheKey);
+            if (Array.isArray(cachedResult)) {
+                return cachedResult;
+            }
+        }
+        // If no ground truth AND hasn't been synced, render from model store
+        // This handles chained optimistic filters, newly created stores, etc.
+        // (If synced with empty results, that's valid ground truth)
+        const pks = this.groundTruthPks.length === 0 && this.lastSync === null
+            ? this.renderFromModelStore()
+            : this.renderFromData(optimistic);
+        // Validate against model store and apply local filtering/sorting
+        let result = this._getValidatedAndFilteredPks(pks);
+        // Apply pagination limit
+        const limit = this.queryset.build().serializerOptions?.limit;
+        if (limit) {
+            result = result.slice(0, limit);
+        }
+        this.setCache(result);
+        return result;
+    }
+    renderFromData(optimistic = true) {
+        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);
+        return result;
+    }
+    /**
+     * 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() {
+        const modelStore = modelStoreRegistry.getStore(this.modelClass);
+        const allPks = modelStore.groundTruthPks;
+        const allInstances = allPks.map((pk) => this.modelClass.fromPk(pk, this.queryset));
+        const ast = this.queryset.build();
+        return filter(allInstances, ast, this.modelClass, false);
+    }
+    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:
+                case Type.BULK_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;
+    }
+    /**
+     * Sync this queryset with the database.
+     * Fetches from DB and sets ground truth.
+     */
+    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;
+            if (!isNil(data)) {
+                console.log(`[${id}] Sync fetch completed. Received: ${JSON.stringify(data)}.`);
+                // Clear previous included PKs tracking before processing new data
+                this.includedPks.clear();
+                // Persist all instances (including nested) to the model store
+                processIncludedEntities(modelStoreRegistry, included, this.modelClass, this.queryset);
+                this.setGroundTruth(data);
+            }
+            this.setOperations(this.getInflightOperations());
+            this.lastSync = Date.now();
+            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: any;
+export const querysetEventEmitter: any;
+export const metricEventEmitter: any;

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.js';
+/**
+ * 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,51 @@
+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>;
+    periodicSyncTimer: NodeJS.Timeout | null;
+    eventBatch: Map<any, any>;
+    debounceTimer: NodeJS.Timeout | null;
+    maxWaitTimer: NodeJS.Timeout | null;
+    debounceMs: number;
+    maxWaitMs: number;
+    batchStartTime: number | null;
+    withTimeout(promise: any, ms: any): Promise<any>;
+    /**
+     * Initialize event handlers for all event receivers
+     */
+    initialize(): void;
+    startPeriodicSync(): void;
+    syncStaleQuerysets(): Promise<void>;
+    pruneUnreferencedModels(): void;
+    isStoreFollowed(registry: any, semanticKey: any): boolean;
+    cleanup(): void;
+    followModel(registry: any, modelClass: any): void;
+    unfollowModel(registry: any, modelClass: any): void;
+    manageRegistry(registry: any): void;
+    removeRegistry(registry: any): void;
+    /**
+     * Sync querysets that were marked MAYBE for a local operation.
+     * Called when a backend event arrives for an operation we initiated locally.
+     */
+    syncMaybeQuerysets(operationId: any): void;
+    handleEvent: (event: any) => void;
+    processBatch(reason?: string): void;
+    isQuerysetFollowed(queryset: any): boolean;
+    processQuerysetsBatch(representativeEvent: any, allEvents: any): void;
+    processMetrics(event: any): void;
+    processModels(event: any): void;
+}
+export const syncManager: SyncManager;