@statezero/core 0.2.37 → 0.2.38

package/dist/cli/configFileLoader.d.ts

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

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

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

package/dist/cli/index.js

@@ -1,22 +0,0 @@
-#!/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

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

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

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