@statezero/core 0.2.38 → 0.2.40

package/dist/core/eventReceivers.js

@@ -0,0 +1,266 @@
+import Pusher from "pusher-js";
+/**
+ * Structure of events received from the server.
+ * @typedef {Object} ModelEvent
+ * @property {string} [type] - Support both frontend (type) and backend (event) naming conventions.
+ * @property {string} [event]
+ * @property {string} model
+ * @property {any} [data]
+ * @property {string} [operationId]
+ * @property {string} [namespace]
+ * @property {(string|number)[]} [instances] - For bulk events.
+ * @property {string} [pk_field_name]
+ * @property {string} [configKey] - The backend configuration key this event is associated with.
+ * @property {any} [key] - Additional open-ended keys.
+ */
+/**
+ * Event types that can be received from the server.
+ * @readonly
+ * @enum {string}
+ */
+export const EventType = {
+    CREATE: "create",
+    UPDATE: "update",
+    DELETE: "delete",
+    BULK_CREATE: "bulk_create",
+    BULK_UPDATE: "bulk_update",
+    BULK_DELETE: "bulk_delete",
+};
+/**
+ * Callback for handling model events.
+ * @callback EventHandler
+ * @param {ModelEvent} event - The event object.
+ */
+/**
+ * A namespace resolver function.
+ * @callback NamespaceResolver
+ * @param {string} modelName - The model name.
+ * @returns {string} The namespace.
+ */
+/**
+ * Options for instantiating a Pusher client.
+ * @typedef {Object} PusherClientOptions
+ * @property {string} appKey
+ * @property {string} cluster
+ * @property {boolean} [forceTLS]
+ * @property {string} authEndpoint
+ * @property {function(): Object<string, string>} [getAuthHeaders]
+ */
+/**
+ * Configuration options for Pusher event receivers.
+ * @typedef {Object} PusherReceiverOptions
+ * @property {PusherClientOptions} clientOptions
+ * @property {function(string): string} [formatChannelName] - Optional channel name formatter. Default: (namespace) => `private-${namespace}`
+ * @property {NamespaceResolver} [namespaceResolver] - Optional namespace resolver. Default: (modelName) => modelName.
+ */
+/**
+ * Implementation of EventReceiver that uses Pusher.
+ */
+export class PusherEventReceiver {
+    /**
+     * @param {PusherReceiverOptions} options
+     * @param {string} configKey - The backend configuration key
+     */
+    constructor(options, configKey) {
+        const { clientOptions, formatChannelName, namespaceResolver } = options;
+        const CONNECTION_TIMEOUT = 10000; // 10 seconds
+        this.configKey = configKey;
+        this.connectionTimeoutId = null;
+        if (clientOptions.appKey &&
+            /^\d+$/.test(clientOptions.appKey) &&
+            clientOptions.appKey.length < 15) {
+            console.warn(`%c[Pusher Warning] The provided appKey ("${clientOptions.appKey}") looks like a numeric app_id. Pusher requires the alphanumeric key, not the ID. Please verify your configuration for backend: "${this.configKey}".`, "color: orange; font-weight: bold; font-size: 14px;");
+        }
+        this.pusherClient = new Pusher(clientOptions.appKey, {
+            cluster: clientOptions.cluster,
+            forceTLS: clientOptions.forceTLS ?? true,
+            authEndpoint: clientOptions.authEndpoint,
+            auth: { headers: clientOptions.getAuthHeaders?.() || {} },
+        });
+        this.pusherClient.connection.bind("connected", () => {
+            console.log(`Pusher client connected successfully for backend: ${this.configKey}.`);
+            if (this.connectionTimeoutId) {
+                clearTimeout(this.connectionTimeoutId);
+                this.connectionTimeoutId = null;
+            }
+        });
+        this.pusherClient.connection.bind("failed", () => {
+            this._logConnectionError("Pusher connection explicitly failed.");
+            if (this.connectionTimeoutId) {
+                clearTimeout(this.connectionTimeoutId);
+                this.connectionTimeoutId = null;
+            }
+        });
+        this.connectionTimeoutId = setTimeout(() => {
+            if (this.pusherClient.connection.state !== "connected") {
+                this._logConnectionError(`Pusher connection timed out after ${CONNECTION_TIMEOUT / 1000} seconds.`);
+            }
+        }, CONNECTION_TIMEOUT);
+        this.formatChannelName = formatChannelName ?? ((ns) => `private-${ns}`);
+        this.namespaceResolver = namespaceResolver ?? ((modelName) => modelName);
+        this.channels = new Map();
+        this.eventHandlers = new Set();
+    }
+    /**
+     * @private
+     * @param {string} reason
+     */
+    _logConnectionError(reason) {
+        console.error(`%c
+████████████████████████████████████████████████████████████████
+█                                                              █
+█   PUSHER CONNECTION FAILED for backend: "${this.configKey}"  █
+█                                                              █
+████████████████████████████████████████████████████████████████
+%c
+Reason: ${reason}
+
+CRITICAL: Real-time updates from the server will NOT be received.
+This application will not reflect remote changes propagated via Pusher.
+
+Common causes:
+1. Incorrect 'appKey' or 'cluster' in the configuration.
+2. The 'authEndpoint' is unreachable or returning an error (check network tab).
+3. Network connectivity issues (firewall, offline).
+4. Using an 'app_id' instead of the 'appKey'.`, "background-color: red; color: white; font-weight: bold; font-size: 16px; padding: 10px;", "color: red; font-size: 12px;");
+    }
+    /**
+     * Set the namespace resolver function.
+     * @param {NamespaceResolver} resolver
+     */
+    setNamespaceResolver(resolver) {
+        this.namespaceResolver = resolver;
+    }
+    /**
+     * Connect to Pusher (no-op since Pusher handles connection automatically).
+     */
+    connect() { }
+    /**
+     * Subscribe to events for a specific namespace.
+     * @param {string} namespace
+     */
+    subscribe(namespace) {
+        if (this.channels.has(namespace))
+            return;
+        const channelName = namespace.startsWith("private-")
+            ? namespace
+            : this.formatChannelName(namespace);
+        console.log(`Subscribing to channel: ${channelName} for backend: ${this.configKey}`);
+        const channel = this.pusherClient.subscribe(channelName);
+        channel.bind("pusher:subscription_succeeded", () => {
+            console.log(`Subscription succeeded for channel: ${channelName}`);
+        });
+        channel.bind("pusher:subscription_error", (status) => {
+            console.error(`Subscription error for channel: ${channelName}. Status:`, status);
+            if (status.status === 401 || status.status === 403) {
+                console.error(`%cAuthentication failed for channel ${channelName}. Check your authEndpoint and server-side permissions.`, "color: orange; font-weight: bold;");
+            }
+        });
+        Object.values(EventType).forEach((eventType) => {
+            channel.bind(eventType, (data) => {
+                const event = {
+                    ...data,
+                    type: data.event || eventType,
+                    namespace,
+                    configKey: this.configKey,
+                };
+                this.eventHandlers.forEach((handler) => handler(event));
+            });
+        });
+        this.channels.set(namespace, channel);
+    }
+    unsubscribe(namespace) {
+        const channel = this.channels.get(namespace);
+        if (!channel)
+            return;
+        Object.values(EventType).forEach((eventType) => {
+            channel.unbind(eventType);
+        });
+        const channelName = namespace.startsWith("private-")
+            ? namespace
+            : this.formatChannelName(namespace);
+        this.pusherClient.unsubscribe(channelName);
+        this.channels.delete(namespace);
+    }
+    /**
+     * Disconnect from Pusher.
+     */
+    disconnect() {
+        if (this.connectionTimeoutId) {
+            clearTimeout(this.connectionTimeoutId);
+            this.connectionTimeoutId = null;
+        }
+        [...this.channels.keys()].forEach((ns) => this.unsubscribe(ns));
+        this.pusherClient.disconnect();
+    }
+    /**
+     * Add handler for model events
+     * @param {EventHandler} handler
+     */
+    addModelEventHandler(handler) {
+        this.eventHandlers.add(handler);
+    }
+    /**
+     * Legacy method - adds event handler for backwards compatibility
+     * @param {EventHandler} handler
+     */
+    addEventHandler(handler) {
+        this.eventHandlers.add(handler);
+    }
+    /**
+     * Remove an event handler callback.
+     * @param {EventHandler} handler
+     */
+    removeEventHandler(handler) {
+        this.eventHandlers.delete(handler);
+    }
+    /**
+     * Get namespace from model name using the resolver.
+     * @param {string} modelName
+     * @returns {string}
+     */
+    getNamespace(modelName) {
+        return this.namespaceResolver(modelName);
+    }
+}
+// Map of event receivers by backend key
+const eventReceivers = new Map();
+/**
+ * Set an event receiver for a specific backend.
+ * @param {string} configKey - The backend configuration key
+ * @param {EventReceiver} receiver - The event receiver instance
+ */
+export function setEventReceiver(configKey, receiver) {
+    const currentReceiver = eventReceivers.get(configKey);
+    if (currentReceiver) {
+        currentReceiver.disconnect();
+    }
+    eventReceivers.set(configKey, receiver);
+    receiver.connect();
+}
+/**
+ * Get the event receiver for a specific backend.
+ * @param {string} configKey - The backend configuration key
+ * @returns {EventReceiver|null}
+ */
+export function getEventReceiver(configKey = "default") {
+    return eventReceivers.get(configKey);
+}
+/**
+ * Get all registered event receivers.
+ * @returns {Map<string, EventReceiver>}
+ */
+export function getAllEventReceivers() {
+    return eventReceivers;
+}
+/**
+ * Set a custom namespace resolver function for a specific backend.
+ * @param {string} configKey - The backend configuration key
+ * @param {NamespaceResolver} resolver
+ */
+export function setNamespaceResolver(configKey, resolver) {
+    const receiver = getEventReceiver(configKey);
+    if (receiver) {
+        receiver.setNamespaceResolver(resolver);
+    }
+}

package/dist/core/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Get a model class by name, loading it from the correct folder structure
+ *
+ * @param {string} modelName - The model name (e.g. 'app.model')
+ * @param {string} configKey - Optional config key override (defaults to Model.configKey)
+ * @returns {Function|null} - The model class or null if not found
+ */
+export function getModelClass(modelName: string, configKey?: string): Function | null;

package/dist/core/utils.js

@@ -0,0 +1,62 @@
+import { configInstance } from '../../config.js';
+// Cache for model classes to avoid repeated imports
+const modelClassCache = {};
+/**
+ * Get a model class by name, loading it from the correct folder structure
+ *
+ * @param {string} modelName - The model name (e.g. 'app.model')
+ * @param {string} configKey - Optional config key override (defaults to Model.configKey)
+ * @returns {Function|null} - The model class or null if not found
+ */
+export function getModelClass(modelName, configKey = this.configKey || 'default') {
+    // Check cache first
+    const cacheKey = `${configKey}:${modelName}`;
+    if (modelClassCache[cacheKey]) {
+        return modelClassCache[cacheKey];
+    }
+    try {
+        const config = configInstance.getConfig();
+        const backendConfig = config.backendConfigs[configKey];
+        if (!backendConfig) {
+            throw new Error(`No backend configuration found for key: ${configKey}`);
+        }
+        const baseDir = backendConfig.GENERATED_TYPES_DIR.replace(/\/$/, '');
+        // Split the model name into parts (e.g., 'app.model' -> ['app', 'model'])
+        const parts = modelName.split('.');
+        // The last part is the actual model name
+        const modelClassName = parts[parts.length - 1];
+        // The path is all parts except the last one, joined by '/'
+        const pathParts = parts.slice(0, parts.length - 1);
+        const path = pathParts.length > 0 ? `/${pathParts.join('/')}` : '';
+        // Construct the full path to the module
+        const modulePath = `${baseDir}${path}/${modelClassName}.js`;
+        // Load the module using require (in Node.js) or dynamic import (in browser)
+        // This implementation uses dynamic import as it's more common in modern JS environments
+        let ModelClass;
+        try {
+            // For Node.js environments, you might use require
+            // ModelClass = require(modulePath).default;
+            // For browser/ES modules using dynamic import
+            // Note: This is a synchronous approach to handle dynamic imports
+            // In a real implementation, this would need to be async or preloaded
+            // Since we can't do a true dynamic import synchronously, here we're assuming
+            // there's a global registry that was populated during build/load time
+            const allModels = window.__MODEL_REGISTRY__ || {};
+            ModelClass = allModels[modulePath];
+            if (!ModelClass) {
+                throw new Error(`Model not found in registry: ${modulePath}`);
+            }
+        }
+        catch (importError) {
+            console.error(`Error loading model class from ${modulePath}:`, importError);
+            return null;
+        }
+        // Cache the model class
+        modelClassCache[cacheKey] = ModelClass;
+        return ModelClass;
+    }
+    catch (error) {
+        console.error(`Error getting model class for ${modelName}:`, error);
+        return null;
+    }
+}

package/dist/errorHandler.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Register a global error handler for StateZero errors.
+ * Errors still propagate to call sites - this is for side effects like toasts.
+ *
+ * @param {Function} handler - Callback receiving the error
+ * @returns {Function} Unsubscribe function
+ *
+ * @example
+ * // In a Vue component with access to toast
+ * const unsubscribe = onStateZeroError((error) => {
+ *   toast.error(error.message)
+ * })
+ * onUnmounted(() => unsubscribe())
+ */
+export function onStateZeroError(handler: Function): Function;
+/**
+ * Emit an error to all registered handlers.
+ * @param {Error} error - The error that occurred
+ */
+export function emitError(error: Error): void;
+export const errorEmitter: any;

package/dist/errorHandler.js

@@ -0,0 +1,27 @@
+import mitt from 'mitt';
+export const errorEmitter = mitt();
+/**
+ * Register a global error handler for StateZero errors.
+ * Errors still propagate to call sites - this is for side effects like toasts.
+ *
+ * @param {Function} handler - Callback receiving the error
+ * @returns {Function} Unsubscribe function
+ *
+ * @example
+ * // In a Vue component with access to toast
+ * const unsubscribe = onStateZeroError((error) => {
+ *   toast.error(error.message)
+ * })
+ * onUnmounted(() => unsubscribe())
+ */
+export function onStateZeroError(handler) {
+    errorEmitter.on('error', handler);
+    return () => errorEmitter.off('error', handler);
+}
+/**
+ * Emit an error to all registered handlers.
+ * @param {Error} error - The error that occurred
+ */
+export function emitError(error) {
+    errorEmitter.emit('error', error);
+}

package/dist/filtering/localFiltering.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Inspect a QuerySet.build() and collect every field path
+ * you’ll need to fetch before running sift.
+ *
+ * @param {Object} queryBuild – result of QuerySet.build()
+ * @param {Class} ModelClass – the root model class
+ * @returns {string[]} Array of dot-notation paths, e.g. ['author.id','createdAt.year']
+ */
+export function getRequiredFields(queryBuild: Object, ModelClass: Class): string[];
+export function pickRequiredFields(requiredPaths: any, instance: any): {};
+/**
+ * Filter and order a collection of data objects according to a QuerySet's AST.
+ * This combines getRequiredFields, pickRequiredFields, and processQuery in one function.
+ *
+ * @param {Array<Object>} data - Collection of objects to filter and order
+ * @param {Object} ast - Abstract Syntax Tree from QuerySet.build()
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @param {boolean} [returnFullObjects=false] - If true, returns full objects instead of just primary keys
+ * @returns {Array} Filtered and ordered results (primary keys or full objects based on returnFullObjects)
+ */
+export function filter(data: Array<Object>, ast: Object, ModelClass: Class, returnFullObjects?: boolean): any[];
+/**
+ * Process a Django-style field path with relationships to match Django ORM behavior.
+ * This handles nested relationships by traversing the model schema and properly
+ * resolving relationship fields to their primary keys.
+ *
+ * @param {string} fieldPath - The Django-style field path (e.g., 'level2__level3__name')
+ * @param {any} value - The value to filter by
+ * @param {Class} ModelClass - The root model class to start traversal from
+ * @param {Object} options - Additional options
+ * @returns {Object} An object with processed field path and operator
+ */
+export function processFieldPath(fieldPath: string, value: any, ModelClass: Class, options?: Object): Object;
+/**
+ * Convert Django-style filter conditions to Sift-compatible criteria
+ * @param {Object} conditions - Filter conditions
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @returns {Object} Sift-compatible criteria
+ */
+export function convertToSiftCriteria(conditions: Object, ModelClass: Class): Object;
+/**
+ * Processes a Q object array to match the backend AST structure
+ * @param {Array} qConditions - Array of Q objects or conditions
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @returns {Object} Sift criteria for Q conditions
+ */
+export function processQConditions(qConditions: any[], ModelClass: Class): Object;
+/**
+ * Convert a filter node to sift criteria with proper relationship traversal
+ * @param {Object} filterNode - The filter node to convert
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @returns {Object} Sift criteria object
+ */
+export function convertFilterNodeToSiftCriteria(filterNode: Object, ModelClass: Class): Object;
+/**
+ * Apply search criteria to a dataset
+ * @param {Array} data - Collection of objects to search
+ * @param {Object} searchNode - Search node from query
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @returns {Array} Filtered results
+ */
+export function applySearch(data: any[], searchNode: Object, ModelClass: Class): any[];
+/**
+ * Applies ordering to a dataset based on a list of fields
+ * @param {Array} data - Collection of objects to order
+ * @param {Array<string>} orderBy - Fields to order by (prefix with - for descending)
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @returns {Array} Ordered results
+ */
+export function applyOrderBy(data: any[], orderBy: Array<string>, ModelClass: Class): any[];
+/**
+ * Process an array of denormalized objects to filter & order them,
+ * then return just the matching primary-keys in order.
+ *
+ * @param {Array<Object>} data       – denormalized rows, e.g. [{ id:1, name:"A", related:{ name:"B" } }, …]
+ * @param {Object}        queryBuild – the result of QuerySet.build()
+ * @param {Class}         ModelClass – your model class (for fieldPath resolution & date-ops)
+ * @returns {Array<*>}              – the primary keys of matching rows, in order
+ */
+export function processQuery(data: Array<Object>, queryBuild: Object, ModelClass: Class): Array<any>;
+/**
+ * Creates custom operations for date parts to be used with Sift
+ * @param {string} timezone - The timezone to use for date operations
+ * @param {Class} ModelClass - The model class for serialization
+ * @returns {Object} Object containing custom operations
+ */
+export function createDateOperations(timezone?: string, ModelClass?: Class): Object;
+/**
+ * Process a Django-style filter query to use with sift, including date part operations
+ * @param {Object} criteria - Sift criteria with possible date operations
+ * @param {Class} ModelClass - The model class for schema traversal
+ * @returns {Function} Sift filter function with date operations support
+ */
+export function createFilterWithDateOperations(criteria: Object, ModelClass: Class): Function;
+/**
+ * Creates a special operator for date part comparison (e.g., created_at__hour__gt: 12)
+ * @param {string} field - Processed field path
+ * @param {string} datePart - The date part to extract ('year', 'month', etc.)
+ * @param {string} comparisonOperator - The comparison operator ('gt', 'lt', etc.)
+ * @param {any} value - Value to filter by
+ * @param {boolean} isRelationship - Whether the field is a relationship
+ * @returns {Object} Object with field name and custom operator
+ */
+export function createDatePartComparisonOperator(field: string, datePart: string, comparisonOperator: string, value: any, isRelationship: boolean): Object;
+/**
+ * Gets the backend timezone for a model class
+ * @param {Class} ModelClass - The model class
+ * @returns {string} The backend timezone or 'UTC' as fallback
+ */
+export function getBackendTimezone(ModelClass: Class): string;