@statezero/core 0.2.38 → 0.2.40

package/dist/cli/configFileLoader.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Loads configuration from file using cosmiconfig and sets it into the global config singleton.
+ *
+ * The function searches for a configuration file (e.g. statezero.config.js, .modelsynrc, etc.)
+ * and checks if an environment variable (STATEZERO_CONFIG_PATH) overrides the default search path.
+ * If a configuration file is found, it is validated and set via configInstance.setConfig().
+ *
+ * @returns {void}
+ */
+export function loadConfigFromFile(): void;

package/dist/cli/configFileLoader.js

@@ -0,0 +1,85 @@
+import { cosmiconfigSync } from 'cosmiconfig';
+import { configInstance } from '../config.js';
+/**
+ * Loads configuration from file using cosmiconfig and sets it into the global config singleton.
+ *
+ * The function searches for a configuration file (e.g. statezero.config.js, .modelsynrc, etc.)
+ * and checks if an environment variable (STATEZERO_CONFIG_PATH) overrides the default search path.
+ * If a configuration file is found, it is validated and set via configInstance.setConfig().
+ *
+ * @returns {void}
+ */
+export function loadConfigFromFile() {
+    const explorerSync = cosmiconfigSync('statezero', {
+        searchPlaces: [
+            'statezero.config.js',
+            'src/statezero.config.js',
+        ],
+        transform: (result) => {
+            if (!result) {
+                console.log('No configuration file found.');
+                return null;
+            }
+            console.log(`Successfully loaded config from: ${result.filepath}`);
+            // Handle ESM modules with default export
+            if (result.config && result.config.__esModule && result.config.default) {
+                result.config = result.config.default;
+            }
+            // Parse any stringified values back to their original format
+            const parseNestedValues = (obj) => {
+                if (!obj || typeof obj !== 'object')
+                    return obj;
+                Object.keys(obj).forEach(key => {
+                    const value = obj[key];
+                    // Don't try to parse functions
+                    if (typeof value === 'string' && !value.includes('Function')) {
+                        try {
+                            // Check if it's a stringified value
+                            if ((value.startsWith('"') && value.endsWith('"')) ||
+                                (value === 'true' || value === 'false')) {
+                                obj[key] = JSON.parse(value);
+                            }
+                        }
+                        catch (e) {
+                            // If parsing fails, keep the original value
+                        }
+                    }
+                    // Recursively parse nested objects
+                    if (value && typeof value === 'object') {
+                        parseNestedValues(value);
+                    }
+                });
+                return obj;
+            };
+            // Parse any stringified values in the config
+            if (result.config && typeof result.config === 'object') {
+                parseNestedValues(result.config);
+            }
+            return result;
+        }
+    });
+    const envConfigPath = process.env.STATEZERO_CONFIG_PATH;
+    let result = null;
+    if (envConfigPath) {
+        console.log(`Attempting to load config from environment path: ${envConfigPath}`);
+        try {
+            result = explorerSync.load(envConfigPath);
+        }
+        catch (error) {
+            console.log(`Failed to load from environment path: ${error.message}`);
+        }
+    }
+    if (!result) {
+        console.log('Searching for statezero configuration files...');
+        result = explorerSync.search();
+    }
+    if (result && result.config) {
+        // Apply the configuration
+        configInstance.setConfig(result.config);
+        console.log(`Configuration set from ${result.filepath}`);
+    }
+    else {
+        console.log('Could not find configuration, using default empty config');
+        configInstance.setConfig({ backendConfigs: {} });
+    }
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import dotenv from "dotenv";
+dotenv.config();
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { generateSchema } from "./commands/syncModels.js";
+import { generateActions } from "./commands/syncActions.js";
+import { sync } from "./commands/sync.js"; // Import the new combined sync function
+yargs(hideBin(process.argv))
+    // The new 'sync' command
+    .command("sync", "Synchronize both models and actions from the backend", {}, // Builder for command-specific options (if any)
+async (argv) => {
+    await sync(argv);
+})
+    .command("sync-models", "Generate model classes from the backend schema", {}, async (argv) => {
+    await generateSchema(argv);
+})
+    .command("sync-actions", "Generate action functions from the backend schema", {}, async (argv) => {
+    await generateActions(); // This function does not take arguments
+})
+    .demandCommand(1, "You must provide a command to run. Use --help to see available commands.")
+    .help().argv;

package/dist/config.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Sets the entire configuration, validating it before storing.
+ * If the configuration is invalid, it throws a ConfigError.
+ */
+export function setConfig(newConfig: any): void;
+/**
+ * Retrieves the validated configuration.
+ * If no configuration has been set, it throws a ConfigError.
+ */
+export function getConfig(): any;
+/**
+ * Merges a partial override into an existing backend config.
+ */
+export function setBackendConfig(backendKey: any, newConfig: any): void;
+/**
+ * Initializes the event receiver based on the configuration.
+ */
+export function initializeEventReceiver(backendKey?: string): PusherEventReceiver | null;
+/**
+ * Initializes event receivers for all configured backends.
+ *
+ * @returns {Object} Map of backend keys to their initialized event receivers
+ * @throws {ConfigError} If configuration is not set or if initialization fails
+ */
+export function initializeAllEventReceivers(): Object;
+/**
+ * Registers the function used to retrieve model classes.
+ * This should be called once during application setup after setConfig.
+ * @param {Function} getterFn - The getModelClass function imported from model-registry.js
+ */
+export function registerModelGetter(getterFn: Function): void;
+/**
+ * Helper function to build file URLs
+ */
+export function buildFileUrl(fileUrl: any, backendKey?: string): any;
+/**
+ * Get a model class by name using the registered getter.
+ *
+ * @param {string} modelName - The model name (e.g., 'app.MyModel')
+ * @param {string} configKey - The config key (backend name)
+ * @returns {Function|null} - The model class or null if not found
+ */
+export function getModelClass(modelName: string, configKey: string): Function | null;
+export namespace liveConfig {
+    let backendConfigs: {};
+}
+export namespace configInstance {
+    export { setConfig };
+    export { getConfig };
+    export { setBackendConfig };
+    export { initializeEventReceiver };
+    export { registerModelGetter };
+    export { getModelClass };
+    export { buildFileUrl };
+}
+export default configInstance;
+import { PusherEventReceiver } from './core/eventReceivers.js';

package/dist/config.js

@@ -0,0 +1,273 @@
+import { z } from 'zod';
+import { ConfigError } from './flavours/django/errors.js';
+import { PusherEventReceiver, setEventReceiver } from './core/eventReceivers.js';
+// The live configuration object. By default it is empty.
+export let liveConfig = {
+    backendConfigs: {}
+};
+// --- Zod Schemas ---
+const pusherSchema = z.object({
+    clientOptions: z.object({
+        appKey: z.string({ required_error: 'Pusher appKey is required' }),
+        cluster: z.string({ required_error: 'Pusher cluster is required' }),
+        forceTLS: z.boolean().optional(),
+        authEndpoint: z.string()
+            .url('Pusher authentication endpoint URL is required'),
+        getAuthHeaders: z.function().optional()
+            .refine((fn) => fn === undefined || typeof fn === 'function', 'getAuthHeaders must be a function if provided')
+    })
+});
+const eventConfigSchema = z.object({
+    type: z.enum(['websocket', 'pusher', 'none']),
+    websocketUrl: z.string().url().optional(),
+    pusher: pusherSchema.optional(),
+    hotpaths: z.array(z.string()).default(['default'])
+}).superRefine((data, ctx) => {
+    // Conditional validation based on type
+    if (data.type === 'websocket') {
+        if (!data.websocketUrl) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['websocketUrl'],
+                message: 'WebSocket URL is required for WebSocket event receiver'
+            });
+        }
+    }
+    if (data.type === 'pusher') {
+        if (!data.pusher) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['pusher'],
+                message: 'Pusher configuration is required for Pusher event receiver'
+            });
+        }
+    }
+});
+const backendSchema = z.object({
+    API_URL: z.string().url("API_URL must be a valid URL"),
+    GENERATED_TYPES_DIR: z.string({
+        required_error: "GENERATED_TYPES_DIR is required",
+    }),
+    GENERATED_ACTIONS_DIR: z.string().optional(),
+    BACKEND_TZ: z.string().optional(),
+    SYNC_TOKEN: z.string().optional(),
+    fileRootURL: z.string().url("fileRootURL must be a valid URL").optional(),
+    fileUploadMode: z.enum(["server", "s3"]).default("server"),
+    getAuthHeaders: z
+        .function()
+        .optional()
+        .refine((fn) => fn === undefined || typeof fn === "function", "getAuthHeaders must be a function if provided"),
+    eventInterceptor: z
+        .function()
+        .optional()
+        .refine((fn) => fn === undefined || typeof fn === "function", "eventInterceptor must be a function if provided"),
+    events: z.lazy(() => eventConfigSchema.optional()),
+});
+const configSchema = z.object({
+    backendConfigs: z.record(z.string(), backendSchema)
+        .refine((configs) => {
+        // Validate each backend config
+        for (const [key, backend] of Object.entries(configs)) {
+            const result = backendSchema.safeParse(backend);
+            if (!result.success) {
+                return false;
+            }
+        }
+        return true;
+    }, (configs) => {
+        // Generate detailed error message
+        const errors = [];
+        for (const [key, backend] of Object.entries(configs)) {
+            const result = backendSchema.safeParse(backend);
+            if (!result.success) {
+                const errorMessages = result.error.errors.map(err => err.message);
+                errors.push(`Backend "${key}" is invalid: ${errorMessages.join(', ')}`);
+            }
+        }
+        return { message: errors.join('; ') };
+    }),
+    periodicSyncIntervalSeconds: z.number().min(5).nullable().optional().default(null),
+});
+// Internal variable to hold the validated configuration.
+let config = null;
+/**
+ * Sets the entire configuration, validating it before storing.
+ * If the configuration is invalid, it throws a ConfigError.
+ */
+export function setConfig(newConfig) {
+    liveConfig = newConfig;
+    const result = configSchema.safeParse(liveConfig);
+    if (!result.success) {
+        const errorMessages = result.error.errors.map(err => err.message);
+        throw new ConfigError(`Error setting configuration: ${errorMessages.join(', ')}`);
+    }
+    config = result.data;
+}
+/**
+ * Retrieves the validated configuration.
+ * If no configuration has been set, it throws a ConfigError.
+ */
+export function getConfig() {
+    if (!config) {
+        throw new ConfigError('Configuration not set. Please call setConfig() with a valid configuration.');
+    }
+    return config;
+}
+/**
+ * Merges a partial override into an existing backend config.
+ */
+export function setBackendConfig(backendKey, newConfig) {
+    try {
+        const cfg = getConfig();
+        if (!cfg.backendConfigs[backendKey]) {
+            throw new ConfigError(`Backend "${backendKey}" not found in configuration.`);
+        }
+        const merged = { ...cfg.backendConfigs[backendKey], ...newConfig };
+        const result = backendSchema.safeParse(merged);
+        if (!result.success) {
+            const errorMessages = result.error.errors.map(err => err.message);
+            throw new ConfigError(`Invalid backend configuration: ${errorMessages.join(', ')}`);
+        }
+        cfg.backendConfigs[backendKey] = result.data;
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            throw error;
+        }
+        throw new ConfigError(error.message || 'Invalid backend configuration');
+    }
+}
+/**
+ * Initializes the event receiver based on the configuration.
+ */
+export function initializeEventReceiver(backendKey = 'default') {
+    try {
+        const cfg = getConfig();
+        if (!cfg.backendConfigs[backendKey]) {
+            throw new ConfigError(`Backend "${backendKey}" not found in configuration.`);
+        }
+        const backendConfig = cfg.backendConfigs[backendKey];
+        if (!backendConfig.events) {
+            return null;
+        }
+        let receiver = null;
+        switch (backendConfig.events.type) {
+            case 'pusher':
+                if (!backendConfig.events.pusher || !backendConfig.events.pusher.clientOptions) {
+                    throw new ConfigError('Pusher client options are required for Pusher event receiver.');
+                }
+                if (!backendConfig.events.pusher.clientOptions.authEndpoint) {
+                    throw new ConfigError('Pusher auth endpoint is required for Pusher event receiver.');
+                }
+                const clientOptions = {
+                    ...backendConfig.events.pusher.clientOptions,
+                    getAuthHeaders: backendConfig.events.pusher.clientOptions.getAuthHeaders || backendConfig.getAuthHeaders
+                };
+                // Pass the backendKey to the constructor
+                receiver = new PusherEventReceiver({ clientOptions }, backendKey);
+                break;
+            case 'none':
+                return null;
+            default:
+                throw new ConfigError(`Unknown event receiver type: ${backendConfig.events.type}`);
+        }
+        if (receiver) {
+            // Pass the backendKey to associate the receiver with this backend
+            setEventReceiver(backendKey, receiver);
+        }
+        return receiver;
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            throw error;
+        }
+        throw new ConfigError(`Failed to initialize event receiver: ${error.message}`);
+    }
+}
+/**
+ * Initializes event receivers for all configured backends.
+ *
+ * @returns {Object} Map of backend keys to their initialized event receivers
+ * @throws {ConfigError} If configuration is not set or if initialization fails
+ */
+export function initializeAllEventReceivers() {
+    try {
+        const cfg = getConfig();
+        const receivers = {};
+        // Initialize event receivers for each backend configuration
+        Object.keys(cfg.backendConfigs).forEach(backendKey => {
+            try {
+                receivers[backendKey] = initializeEventReceiver(backendKey);
+            }
+            catch (error) {
+                console.warn(`Failed to initialize event receiver for backend "${backendKey}": ${error.message}`);
+            }
+        });
+        return receivers;
+    }
+    catch (error) {
+        throw new ConfigError(`Failed to initialize event receivers: ${error.message}`);
+    }
+}
+// --- Declare the variable to hold the registered model getter ---
+let modelGetter = null;
+/**
+ * Registers the function used to retrieve model classes.
+ * This should be called once during application setup after setConfig.
+ * @param {Function} getterFn - The getModelClass function imported from model-registry.js
+ */
+export function registerModelGetter(getterFn) {
+    if (typeof getterFn !== 'function') {
+        throw new ConfigError('Provided model getter must be a function.');
+    }
+    modelGetter = getterFn;
+}
+/**
+ * Helper function to build file URLs
+ */
+export function buildFileUrl(fileUrl, backendKey = 'default') {
+    // If URL is already absolute (cloud storage), use it as-is
+    if (fileUrl && fileUrl.startsWith('http')) {
+        return fileUrl;
+    }
+    const cfg = getConfig();
+    const backend = cfg.backendConfigs[backendKey];
+    if (!backend) {
+        throw new ConfigError(`Backend "${backendKey}" not found in configuration.`);
+    }
+    // If no fileRootURL provided, return relative URL as-is
+    if (!backend.fileRootURL) {
+        return fileUrl;
+    }
+    // Construct full URL
+    return backend.fileRootURL.replace(/\/$/, '') + fileUrl;
+}
+/**
+ * Get a model class by name using the registered getter.
+ *
+ * @param {string} modelName - The model name (e.g., 'app.MyModel')
+ * @param {string} configKey - The config key (backend name)
+ * @returns {Function|null} - The model class or null if not found
+ */
+export function getModelClass(modelName, configKey) {
+    if (!modelGetter) {
+        // Optionally check if config is set first
+        // getConfig(); // This will throw if config isn't set
+        throw new ConfigError('Model registry not registered. Please call registerModelGetter() with the function from model-registry.js during app initialization.');
+    }
+    // Delegate to the function provided by the user from model-registry.js
+    return modelGetter(modelName, configKey);
+}
+/**
+ * Exposes a singleton object for configuration functionality.
+ */
+export const configInstance = {
+    setConfig,
+    getConfig,
+    setBackendConfig,
+    initializeEventReceiver,
+    registerModelGetter,
+    getModelClass,
+    buildFileUrl
+};
+export default configInstance;

package/dist/core/eventReceivers.d.ts

@@ -0,0 +1,185 @@
+/**
+ * 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: string, receiver: EventReceiver): void;
+/**
+ * Get the event receiver for a specific backend.
+ * @param {string} configKey - The backend configuration key
+ * @returns {EventReceiver|null}
+ */
+export function getEventReceiver(configKey?: string): EventReceiver | null;
+/**
+ * Get all registered event receivers.
+ * @returns {Map<string, EventReceiver>}
+ */
+export function getAllEventReceivers(): Map<string, EventReceiver>;
+/**
+ * Set a custom namespace resolver function for a specific backend.
+ * @param {string} configKey - The backend configuration key
+ * @param {NamespaceResolver} resolver
+ */
+export function setNamespaceResolver(configKey: string, resolver: NamespaceResolver): void;
+/**
+ * Event types that can be received from the server.
+ */
+export type EventType = string;
+export namespace EventType {
+    let CREATE: string;
+    let UPDATE: string;
+    let DELETE: string;
+    let BULK_CREATE: string;
+    let BULK_UPDATE: string;
+    let BULK_DELETE: string;
+}
+/**
+ * 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: PusherReceiverOptions, configKey: string);
+    configKey: string;
+    connectionTimeoutId: NodeJS.Timeout;
+    pusherClient: any;
+    formatChannelName: (arg0: string) => string;
+    namespaceResolver: NamespaceResolver;
+    channels: Map<any, any>;
+    eventHandlers: Set<any>;
+    /**
+     * @private
+     * @param {string} reason
+     */
+    private _logConnectionError;
+    /**
+     * Set the namespace resolver function.
+     * @param {NamespaceResolver} resolver
+     */
+    setNamespaceResolver(resolver: NamespaceResolver): void;
+    /**
+     * Connect to Pusher (no-op since Pusher handles connection automatically).
+     */
+    connect(): void;
+    /**
+     * Subscribe to events for a specific namespace.
+     * @param {string} namespace
+     */
+    subscribe(namespace: string): void;
+    unsubscribe(namespace: any): void;
+    /**
+     * Disconnect from Pusher.
+     */
+    disconnect(): void;
+    /**
+     * Add handler for model events
+     * @param {EventHandler} handler
+     */
+    addModelEventHandler(handler: EventHandler): void;
+    /**
+     * Legacy method - adds event handler for backwards compatibility
+     * @param {EventHandler} handler
+     */
+    addEventHandler(handler: EventHandler): void;
+    /**
+     * Remove an event handler callback.
+     * @param {EventHandler} handler
+     */
+    removeEventHandler(handler: EventHandler): void;
+    /**
+     * Get namespace from model name using the resolver.
+     * @param {string} modelName
+     * @returns {string}
+     */
+    getNamespace(modelName: string): string;
+}
+/**
+ * Structure of events received from the server.
+ */
+export type ModelEvent = {
+    /**
+     * - Support both frontend (type) and backend (event) naming conventions.
+     */
+    type?: string | undefined;
+    event?: string | undefined;
+    model: string;
+    data?: any;
+    operationId?: string | undefined;
+    namespace?: string | undefined;
+    /**
+     * - For bulk events.
+     */
+    instances?: (string | number)[] | undefined;
+    pk_field_name?: string | undefined;
+    /**
+     * - The backend configuration key this event is associated with.
+     */
+    configKey?: string | undefined;
+    /**
+     * - Additional open-ended keys.
+     */
+    key?: any;
+};
+/**
+ * Callback for handling model events.
+ */
+export type EventHandler = (event: ModelEvent) => any;
+/**
+ * A namespace resolver function.
+ */
+export type NamespaceResolver = (modelName: string) => string;
+/**
+ * Options for instantiating a Pusher client.
+ */
+export type PusherClientOptions = {
+    appKey: string;
+    cluster: string;
+    forceTLS?: boolean | undefined;
+    authEndpoint: string;
+    getAuthHeaders?: (() => {
+        [x: string]: string;
+    }) | undefined;
+};
+/**
+ * Configuration options for Pusher event receivers.
+ */
+export type PusherReceiverOptions = {
+    clientOptions: PusherClientOptions;
+    /**
+     * - Optional channel name formatter. Default: (namespace) => `private-${namespace}`
+     */
+    formatChannelName?: ((arg0: string) => string) | undefined;
+    /**
+     * - Optional namespace resolver. Default: (modelName) => modelName.
+     */
+    namespaceResolver?: NamespaceResolver | undefined;
+};