@statezero/core 0.2.37 → 0.2.38

package/dist/core/eventReceivers.js

@@ -1,266 +0,0 @@
-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

@@ -1,8 +0,0 @@
-/**
- * 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

@@ -1,62 +0,0 @@
-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

@@ -1,21 +0,0 @@
-/**
- * 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

@@ -1,27 +0,0 @@
-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

@@ -1,110 +0,0 @@
-/**
- * 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;