lsh-framework 0.5.4

package/dist/lib/associative-arrays.js

@@ -0,0 +1,285 @@
+/**
+ * Associative Arrays Implementation
+ * Provides ZSH-compatible associative array functionality
+ */
+export class AssociativeArrayManager {
+    context;
+    constructor() {
+        this.context = {
+            arrays: new Map(),
+            arrayTypes: new Map(),
+        };
+    }
+    /**
+     * Declare an associative array with typeset -A
+     */
+    declareAssociativeArray(name) {
+        this.context.arrays.set(name, {});
+        this.context.arrayTypes.set(name, 'associative');
+    }
+    /**
+     * Declare an indexed array with typeset -a
+     */
+    declareIndexedArray(name) {
+        this.context.arrays.set(name, {});
+        this.context.arrayTypes.set(name, 'indexed');
+    }
+    /**
+     * Set a value in an associative array
+     */
+    setAssociativeValue(arrayName, key, value) {
+        if (!this.context.arrays.has(arrayName)) {
+            this.declareAssociativeArray(arrayName);
+        }
+        const array = this.context.arrays.get(arrayName);
+        array[key] = value;
+    }
+    /**
+     * Set a value in an indexed array
+     */
+    setIndexedValue(arrayName, index, value) {
+        if (!this.context.arrays.has(arrayName)) {
+            this.declareIndexedArray(arrayName);
+        }
+        const array = this.context.arrays.get(arrayName);
+        array[index.toString()] = value;
+    }
+    /**
+     * Get a value from an array
+     */
+    getValue(arrayName, key) {
+        const array = this.context.arrays.get(arrayName);
+        return array ? array[key] : undefined;
+    }
+    /**
+     * Get all keys from an associative array
+     */
+    getKeys(arrayName) {
+        const array = this.context.arrays.get(arrayName);
+        if (!array)
+            return [];
+        const type = this.context.arrayTypes.get(arrayName);
+        if (type === 'indexed') {
+            // For indexed arrays, return sorted numeric keys
+            return Object.keys(array)
+                .map(k => parseInt(k, 10))
+                .filter(k => !isNaN(k))
+                .sort((a, b) => a - b)
+                .map(k => k.toString());
+        }
+        else {
+            // For associative arrays, return all keys
+            return Object.keys(array);
+        }
+    }
+    /**
+     * Get all values from an array
+     */
+    getValues(arrayName) {
+        const array = this.context.arrays.get(arrayName);
+        if (!array)
+            return [];
+        const type = this.context.arrayTypes.get(arrayName);
+        if (type === 'indexed') {
+            // For indexed arrays, return values in order
+            const keys = this.getKeys(arrayName);
+            return keys.map(key => array[key]);
+        }
+        else {
+            // For associative arrays, return all values
+            return Object.values(array);
+        }
+    }
+    /**
+     * Get array length
+     */
+    getLength(arrayName) {
+        const array = this.context.arrays.get(arrayName);
+        return array ? Object.keys(array).length : 0;
+    }
+    /**
+     * Check if an array exists
+     */
+    hasArray(arrayName) {
+        return this.context.arrays.has(arrayName);
+    }
+    /**
+     * Get array type
+     */
+    getArrayType(arrayName) {
+        return this.context.arrayTypes.get(arrayName);
+    }
+    /**
+     * Remove an array
+     */
+    removeArray(arrayName) {
+        const hadArray = this.context.arrays.has(arrayName);
+        this.context.arrays.delete(arrayName);
+        this.context.arrayTypes.delete(arrayName);
+        return hadArray;
+    }
+    /**
+     * Get all array names
+     */
+    getAllArrayNames() {
+        return Array.from(this.context.arrays.keys());
+    }
+    /**
+     * Clear all arrays
+     */
+    clearAllArrays() {
+        this.context.arrays.clear();
+        this.context.arrayTypes.clear();
+    }
+    /**
+     * Get array slice (for indexed arrays)
+     */
+    getSlice(arrayName, start, end) {
+        const array = this.context.arrays.get(arrayName);
+        if (!array)
+            return [];
+        const type = this.context.arrayTypes.get(arrayName);
+        if (type !== 'indexed')
+            return [];
+        const keys = this.getKeys(arrayName);
+        const startIdx = Math.max(0, start - 1); // Convert to 0-based
+        const endIdx = end ? Math.min(keys.length, end) : keys.length;
+        return keys.slice(startIdx, endIdx).map(key => array[key]);
+    }
+    /**
+     * Expand array reference like ${array[key]} or ${array[@]}
+     */
+    expandArrayReference(reference) {
+        // Match patterns like ${array[key]}, ${array[@]}, ${array[*]}
+        const match = reference.match(/^\$\{([^[\]]+)(?:\[([^\]]+)\])?(?:\[@\*\]|\[@\]|\[\*\]|\[@\])?\}$/);
+        if (!match)
+            return [];
+        const arrayName = match[1];
+        const key = match[2];
+        if (!this.hasArray(arrayName))
+            return [];
+        if (key) {
+            // Single element access
+            const value = this.getValue(arrayName, key);
+            return value !== undefined ? [value] : [];
+        }
+        else {
+            // All elements access
+            return this.getValues(arrayName);
+        }
+    }
+    /**
+     * Expand array keys like ${(k)array}
+     */
+    expandArrayKeys(reference) {
+        const match = reference.match(/^\$\{\(k\)([^}]+)\}$/);
+        if (!match)
+            return [];
+        const arrayName = match[1];
+        return this.getKeys(arrayName);
+    }
+    /**
+     * Expand array values like ${(v)array}
+     */
+    expandArrayValues(reference) {
+        const match = reference.match(/^\$\{\(v\)([^}]+)\}$/);
+        if (!match)
+            return [];
+        const arrayName = match[1];
+        return this.getValues(arrayName);
+    }
+    /**
+     * Expand array length like ${#array}
+     */
+    expandArrayLength(reference) {
+        const match = reference.match(/^\$\{#([^}]+)\}$/);
+        if (!match)
+            return '';
+        const arrayName = match[1];
+        return this.getLength(arrayName).toString();
+    }
+    /**
+     * Parse typeset command
+     */
+    parseTypesetCommand(args) {
+        if (args.length === 0) {
+            return { success: false, message: 'typeset: missing arguments' };
+        }
+        for (const arg of args) {
+            if (arg === '-A') {
+                // Declare associative array - next argument should be the name
+                const nameIndex = args.indexOf('-A') + 1;
+                if (nameIndex < args.length) {
+                    const name = args[nameIndex];
+                    this.declareAssociativeArray(name);
+                }
+            }
+            else if (arg === '-a') {
+                // Declare indexed array - next argument should be the name
+                const nameIndex = args.indexOf('-a') + 1;
+                if (nameIndex < args.length) {
+                    const name = args[nameIndex];
+                    this.declareIndexedArray(name);
+                }
+            }
+            else if (arg.includes('=')) {
+                // Assignment: name=value or name[key]=value
+                const [left, right] = arg.split('=', 2);
+                const arrayMatch = left.match(/^([^[\]]+)(?:\[([^\]]+)\])?$/);
+                if (arrayMatch) {
+                    const arrayName = arrayMatch[1];
+                    const key = arrayMatch[2];
+                    if (key) {
+                        // Associative array assignment
+                        this.setAssociativeValue(arrayName, key, right);
+                    }
+                    else {
+                        // Regular variable assignment (not array)
+                        // This would be handled by the regular variable system
+                    }
+                }
+            }
+        }
+        return { success: true, message: '' };
+    }
+    /**
+     * Get array information for display
+     */
+    getArrayInfo(arrayName) {
+        if (!this.hasArray(arrayName))
+            return null;
+        const type = this.getArrayType(arrayName);
+        const length = this.getLength(arrayName);
+        const keys = this.getKeys(arrayName);
+        const values = this.getValues(arrayName);
+        return {
+            type: type || 'unknown',
+            length,
+            keys,
+            values,
+        };
+    }
+    /**
+     * Export array data for serialization
+     */
+    exportArrays() {
+        const arrays = {};
+        const types = {};
+        for (const [name, array] of this.context.arrays) {
+            arrays[name] = { ...array };
+            types[name] = this.context.arrayTypes.get(name) || 'unknown';
+        }
+        return { arrays, types };
+    }
+    /**
+     * Import array data from serialization
+     */
+    importArrays(data) {
+        this.clearAllArrays();
+        for (const [name, array] of Object.entries(data.arrays)) {
+            this.context.arrays.set(name, { ...array });
+            this.context.arrayTypes.set(name, data.types[name]);
+        }
+    }
+}
+export default AssociativeArrayManager;

package/dist/lib/base-api-server.js

@@ -0,0 +1,290 @@
+/**
+ * Base API Server
+ * Abstract base class for all API servers to eliminate duplication in:
+ * - Express middleware setup
+ * - Server lifecycle management
+ * - Signal handling
+ * - Error handling
+ */
+import express from 'express';
+import cors from 'cors';
+import helmet from 'helmet';
+import { EventEmitter } from 'events';
+import { createLogger } from './logger.js';
+/**
+ * Abstract base class for API servers
+ *
+ * Provides:
+ * - Express app setup with common middleware
+ * - Server lifecycle (start/stop)
+ * - Signal handling (SIGTERM, SIGINT, SIGHUP)
+ * - Error handling (uncaughtException, unhandledRejection)
+ * - Request logging
+ * - Structured logging
+ *
+ * @example
+ * ```typescript
+ * class MyAPIServer extends BaseAPIServer {
+ *   constructor() {
+ *     super({ port: 3000 }, 'MyAPI');
+ *   }
+ *
+ *   protected setupRoutes(): void {
+ *     this.app.get('/api/hello', (req, res) => {
+ *       res.json({ message: 'Hello World' });
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export class BaseAPIServer extends EventEmitter {
+    app;
+    server;
+    config;
+    logger;
+    isShuttingDown = false;
+    /**
+     * Create a new API server
+     *
+     * @param config - Server configuration
+     * @param loggerName - Name for the logger context
+     */
+    constructor(config, loggerName) {
+        super();
+        this.config = {
+            port: 3000,
+            corsOrigins: '*',
+            enableHelmet: true,
+            jsonLimit: '10mb',
+            enableRequestLogging: true,
+            enableSignalHandlers: true,
+            enableErrorHandlers: true,
+            ...config
+        };
+        this.logger = createLogger(loggerName);
+        this.app = express();
+        this.setupMiddleware();
+        if (this.config.enableErrorHandlers) {
+            this.setupErrorHandlers();
+        }
+        if (this.config.enableSignalHandlers) {
+            this.setupSignalHandlers();
+        }
+    }
+    /**
+     * Setup Express middleware
+     * Can be overridden for custom middleware setup
+     */
+    setupMiddleware() {
+        // Security middleware
+        if (this.config.enableHelmet) {
+            this.app.use(helmet({
+                crossOriginEmbedderPolicy: false,
+            }));
+        }
+        // CORS
+        this.app.use(this.configureCORS());
+        // Body parsing
+        this.app.use(express.json({ limit: this.config.jsonLimit }));
+        this.app.use(express.urlencoded({ extended: true }));
+        // Request logging
+        if (this.config.enableRequestLogging) {
+            this.app.use(this.requestLogger.bind(this));
+        }
+    }
+    /**
+     * Configure CORS middleware
+     * Can be overridden for custom CORS configuration
+     */
+    configureCORS() {
+        const origins = this.config.corsOrigins;
+        if (origins === '*') {
+            return cors();
+        }
+        if (Array.isArray(origins)) {
+            return cors({
+                origin: (origin, callback) => {
+                    if (!origin || origins.some(pattern => {
+                        const regex = new RegExp(pattern.replace(/\*/g, '.*'));
+                        return regex.test(origin);
+                    })) {
+                        callback(null, true);
+                    }
+                    else {
+                        callback(new Error('Not allowed by CORS'));
+                    }
+                }
+            });
+        }
+        return cors({ origin: origins });
+    }
+    /**
+     * Request logging middleware
+     */
+    requestLogger(req, res, next) {
+        this.logger.info(`${req.method} ${req.path}`);
+        next();
+    }
+    /**
+     * Setup error handlers for uncaught exceptions and unhandled rejections
+     */
+    setupErrorHandlers() {
+        process.on('uncaughtException', (error) => {
+            this.logger.error('Uncaught Exception', error);
+            this.handleFatalError(error);
+        });
+        process.on('unhandledRejection', (reason, promise) => {
+            this.logger.error('Unhandled Rejection', reason instanceof Error ? reason : new Error(String(reason)), {
+                promise: String(promise)
+            });
+        });
+    }
+    /**
+     * Setup signal handlers for graceful shutdown
+     */
+    setupSignalHandlers() {
+        const signals = ['SIGTERM', 'SIGINT'];
+        signals.forEach(signal => {
+            process.on(signal, () => {
+                this.logger.info(`Received ${signal}, initiating graceful shutdown`);
+                this.gracefulShutdown(signal);
+            });
+        });
+        process.on('SIGHUP', () => {
+            this.logger.info('Received SIGHUP');
+            this.handleSIGHUP();
+        });
+    }
+    /**
+     * Handle SIGHUP signal - can be overridden for custom behavior (e.g., reload config)
+     */
+    handleSIGHUP() {
+        this.logger.info('SIGHUP handler not implemented, ignoring');
+    }
+    /**
+     * Handle fatal errors
+     * @param error - The fatal error
+     */
+    handleFatalError(error) {
+        this.logger.error('Fatal error, shutting down', error);
+        process.exit(1);
+    }
+    /**
+     * Perform graceful shutdown
+     * @param signal - The signal that triggered the shutdown
+     */
+    async gracefulShutdown(signal) {
+        if (this.isShuttingDown) {
+            this.logger.warn('Shutdown already in progress');
+            return;
+        }
+        this.isShuttingDown = true;
+        this.logger.info(`Graceful shutdown initiated by ${signal}`);
+        try {
+            // Give ongoing requests time to complete
+            await this.stop();
+            this.logger.info('Server stopped successfully');
+            process.exit(0);
+        }
+        catch (error) {
+            this.logger.error('Error during shutdown', error);
+            process.exit(1);
+        }
+    }
+    /**
+     * Start the API server
+     * @returns Promise that resolves when server is listening
+     */
+    async start() {
+        return new Promise((resolve, reject) => {
+            try {
+                // Setup routes before starting server
+                this.setupRoutes();
+                this.server = this.app.listen(this.config.port, () => {
+                    this.logger.info(`Server started on port ${this.config.port}`);
+                    this.emit('started');
+                    resolve();
+                });
+                this.server.on('error', (error) => {
+                    this.logger.error('Server error', error);
+                    this.emit('error', error);
+                    reject(error);
+                });
+            }
+            catch (error) {
+                this.logger.error('Failed to start server', error);
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Stop the API server
+     * @param timeout - Maximum time to wait for connections to close (ms)
+     * @returns Promise that resolves when server is stopped
+     */
+    async stop(timeout = 5000) {
+        return new Promise((resolve, reject) => {
+            if (!this.server) {
+                resolve();
+                return;
+            }
+            this.logger.info('Stopping server...');
+            // Set timeout for force shutdown
+            const forceShutdownTimer = setTimeout(() => {
+                this.logger.warn('Force closing server after timeout');
+                this.server?.close();
+                resolve();
+            }, timeout);
+            this.server?.close((error) => {
+                clearTimeout(forceShutdownTimer);
+                if (error) {
+                    this.logger.error('Error stopping server', error);
+                    reject(error);
+                }
+                else {
+                    this.logger.info('Server stopped');
+                    this.emit('stopped');
+                    resolve();
+                }
+            });
+            // Allow subclasses to cleanup
+            this.onStop();
+        });
+    }
+    /**
+     * Hook called when server is stopping
+     * Override this to cleanup resources, close connections, etc.
+     */
+    onStop() {
+        // Override in subclasses if needed
+    }
+    /**
+     * Get the Express application
+     * @returns The Express app instance
+     */
+    getApp() {
+        return this.app;
+    }
+    /**
+     * Get the HTTP server
+     * @returns The HTTP server instance
+     */
+    getServer() {
+        return this.server;
+    }
+    /**
+     * Check if server is running
+     * @returns True if server is running
+     */
+    isRunning() {
+        return !!this.server?.listening;
+    }
+    /**
+     * Get server configuration
+     * @returns The server configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+export default BaseAPIServer;