@soederpop/luca 0.1.2 → 0.2.1

package/dist/node/features/ipc-socket.d.ts

@@ -0,0 +1,298 @@
+import { z } from 'zod';
+import { Feature } from "../feature.js";
+import { NodeContainer } from "../container.js";
+import { Server, Socket } from "net";
+/**
+ * Zod schema for the IpcSocket feature state.
+ * Tracks the operational mode of the IPC socket (server or client).
+ */
+export declare const IpcStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        client: "client";
+        server: "server";
+    }>>;
+    socketPath: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type IpcState = z.infer<typeof IpcStateSchema>;
+export declare const IpcEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    connection: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+    disconnection: z.ZodTuple<[z.ZodString], null>;
+    message: z.ZodTuple<[z.ZodAny, z.ZodOptional<z.ZodString>], null>;
+}, z.core.$strip>;
+/** Metadata for a connected client */
+type ClientInfo = {
+    socket: Socket;
+    id: string;
+    name?: string;
+    connectedAt: number;
+};
+/**
+ * IpcSocket Feature - Inter-Process Communication via Unix Domain Sockets
+ *
+ * This feature provides robust IPC (Inter-Process Communication) capabilities using Unix domain sockets.
+ * It supports both server and client modes, allowing processes to communicate efficiently through
+ * file system-based socket connections.
+ *
+ * **Key Features:**
+ * - Hub-and-spoke: one server, many named clients with identity tracking
+ * - Targeted messaging: sendTo(clientId), broadcast(msg, excludeId)
+ * - Request/reply: ask() + reply() with timeout-based correlation
+ * - Auto-reconnect: clients reconnect with exponential backoff
+ * - Stale socket detection: probeSocket() before listen()
+ * - Clean shutdown: stopServer() removes socket file
+ *
+ * **Server (Hub):**
+ * ```typescript
+ * const ipc = container.feature('ipcSocket');
+ * await ipc.listen('/tmp/hub.sock', true);
+ *
+ * ipc.on('connection', (clientId, socket) => {
+ *   console.log('Client joined:', clientId);
+ * });
+ *
+ * ipc.on('message', (data, clientId) => {
+ *   console.log(`From ${clientId}:`, data);
+ *   // Reply to sender, or ask and wait
+ *   ipc.sendTo(clientId, { ack: true });
+ * });
+ * ```
+ *
+ * **Client (Spoke):**
+ * ```typescript
+ * const ipc = container.feature('ipcSocket');
+ * await ipc.connect('/tmp/hub.sock', { reconnect: true, name: 'worker-1' });
+ *
+ * // Fire and forget
+ * await ipc.send({ type: 'status', ready: true });
+ *
+ * // Request/reply
+ * ipc.on('message', (data) => {
+ *   if (data.requestId) ipc.reply(data.requestId, { result: 42 });
+ * });
+ * ```
+ *
+ * @template T - The state type, defaults to IpcState
+ * @extends {Feature<T>}
+ */
+export declare class IpcSocket<T extends IpcState = IpcState> extends Feature<T> {
+    /** The shortcut path for accessing this feature */
+    static shortcut: "features.ipcSocket";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            client: "client";
+            server: "server";
+        }>>;
+        socketPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        connection: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+        disconnection: z.ZodTuple<[z.ZodString], null>;
+        message: z.ZodTuple<[z.ZodAny, z.ZodOptional<z.ZodString>], null>;
+    }, z.core.$strip>;
+    /** The Node.js net Server instance (when in server mode) */
+    server?: Server;
+    /** Connected clients keyed by client ID (server mode only) */
+    protected clients: Map<string, ClientInfo>;
+    /** Reverse lookup: socket → clientId */
+    private _socketToClient;
+    /** Per-socket NDJSON read buffers for accumulating partial lines */
+    private _buffers;
+    /** Pending request/reply correlation map */
+    private _pending;
+    /** Default timeout for ask() calls in ms */
+    requestTimeoutMs: number;
+    /** Reconnection config (client mode) */
+    private _reconnect;
+    private _socketPath?;
+    /**
+     * Attaches the IpcSocket feature to a NodeContainer instance.
+     * Registers the feature and creates an auto-enabled instance.
+     *
+     * @param container - The NodeContainer to attach to
+     * @returns The container for method chaining
+     */
+    static attach(container: NodeContainer & {
+        ipcSocket?: IpcSocket;
+    }): void;
+    /**
+     * Checks if the IPC socket is operating in client mode.
+     *
+     * @returns True if the socket is configured as a client
+     */
+    get isClient(): boolean;
+    /**
+     * Checks if the IPC socket is operating in server mode.
+     *
+     * @returns True if the socket is configured as a server
+     */
+    get isServer(): boolean;
+    /**
+     * Returns the number of currently connected clients (server mode).
+     */
+    get clientCount(): number;
+    /**
+     * Returns info about all connected clients (server mode).
+     */
+    get connectedClients(): Array<{
+        id: string;
+        name?: string;
+        connectedAt: number;
+    }>;
+    /**
+     * Starts the IPC server listening on the specified socket path.
+     *
+     * This method sets up a Unix domain socket server that can accept multiple client connections.
+     * Each connected client is tracked, and the server automatically handles connection lifecycle
+     * events. Messages received from clients are JSON-parsed and emitted as 'message' events.
+     *
+     * **Server Behavior:**
+     * - Tracks all connected clients in the sockets Set
+     * - Automatically removes clients when they disconnect
+     * - JSON-parses incoming messages and emits 'message' events
+     * - Emits 'connection' events when clients connect
+     * - Prevents starting multiple servers on the same instance
+     *
+     * **Socket File Management:**
+     * - Resolves the socket path relative to the container's working directory
+     * - Optionally removes existing socket files to prevent "address in use" errors
+     * - Throws error if socket file exists and removeLock is false
+     *
+     * @param socketPath - The file system path for the Unix domain socket
+     * @param removeLock - Whether to remove existing socket file (default: false)
+     * @returns Promise resolving to the created Node.js Server instance
+     *
+     * @throws {Error} When already in client mode, server already running, or socket file exists
+     *
+     * @example
+     * ```typescript
+     * // Basic server setup
+     * const server = await ipc.listen('/tmp/myapp.sock');
+     *
+     * // With automatic lock removal
+     * const server = await ipc.listen('/tmp/myapp.sock', true);
+     *
+     * // Handle connections and messages
+     * ipc.on('connection', (socket) => {
+     *   console.log('New client connected');
+     * });
+     *
+     * ipc.on('message', (data) => {
+     *   console.log('Received message:', data);
+     *   // Echo back to all clients
+     *   ipc.broadcast({ echo: data });
+     * });
+     * ```
+     */
+    listen(socketPath: string, removeLock?: boolean): Promise<Server>;
+    /**
+     * Stops the IPC server and cleans up all connections.
+     *
+     * This method gracefully shuts down the server by:
+     * 1. Closing the server listener
+     * 2. Destroying all active client connections
+     * 3. Clearing the sockets tracking set
+     * 4. Resetting the server instance
+     *
+     * @returns Promise that resolves when the server is fully stopped
+     *
+     * @throws {Error} When no server is currently running
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown
+     * try {
+     *   await ipc.stopServer();
+     *   console.log('IPC server stopped successfully');
+     * } catch (error) {
+     *   console.error('Failed to stop server:', error.message);
+     * }
+     * ```
+     */
+    stopServer(): Promise<void>;
+    /** The client connection socket (client mode only) */
+    _connection?: Socket;
+    /**
+     * Gets the current client connection socket.
+     *
+     * @returns The active Socket connection, or undefined if not connected
+     */
+    get connection(): Socket | undefined;
+    /**
+     * Broadcasts a message to all connected clients (server mode only).
+     *
+     * @param message - The message object to broadcast
+     * @param exclude - Optional client ID to exclude from broadcast
+     * @returns This instance for method chaining
+     */
+    broadcast(message: any, exclude?: string): this;
+    /**
+     * Sends a message to a specific client by ID (server mode only).
+     *
+     * @param clientId - The target client ID
+     * @param message - The message to send
+     * @returns True if the message was sent, false if client not found or not writable
+     */
+    sendTo(clientId: string, message: any): boolean;
+    /**
+     * Fire-and-forget: sends a message to the server (client mode only).
+     * For server→client, use sendTo() or broadcast().
+     *
+     * @param message - The message to send
+     */
+    send(message: any): Promise<void>;
+    /**
+     * Sends a message and waits for a correlated reply.
+     * Works in both client and server mode.
+     *
+     * The recipient should call `reply(requestId, response)` to respond.
+     *
+     * @param message - The message to send
+     * @param options - Optional: clientId (server mode target), timeoutMs
+     * @returns The reply data
+     */
+    ask(message: any, options?: {
+        clientId?: string;
+        timeoutMs?: number;
+    }): Promise<any>;
+    /**
+     * Sends a reply to a previous ask() call, correlated by requestId.
+     *
+     * @param requestId - The requestId from the incoming message
+     * @param data - The reply payload
+     * @param clientId - Target client (server mode; for client mode, omit)
+     */
+    reply(requestId: string, data: any, clientId?: string): void;
+    /** The server-assigned client ID (client mode only) */
+    clientId?: string;
+    /**
+     * Connects to an IPC server at the specified socket path (client mode).
+     *
+     * @param socketPath - Path to the server's Unix domain socket
+     * @param options - Optional: reconnect (enable auto-reconnect), name (identify this client)
+     * @returns The established Socket connection
+     */
+    connect(socketPath: string, options?: {
+        reconnect?: boolean;
+        name?: string;
+    }): Promise<Socket>;
+    private _doConnect;
+    private _scheduleReconnect;
+    /**
+     * Disconnects the client and stops any reconnection attempts.
+     */
+    disconnect(): void;
+    /**
+     * Probe an existing socket to see if a live listener is behind it.
+     * Attempts a quick connect — if it succeeds, someone is listening.
+     */
+    probeSocket(socketPath: string): Promise<boolean>;
+    private _handleChunk;
+}
+export default IpcSocket;
+//# sourceMappingURL=ipc-socket.d.ts.map

package/dist/node/features/ipc-socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipc-socket.d.ts","sourceRoot":"","sources":["../../../src/node/features/ipc-socket.ts"],"names":[],"mappings":"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"}

package/dist/node/features/json-tree.d.ts

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+import { Feature } from "../feature.js";
+/**
+ * Zod schema for the JsonTree feature state.
+ * Extends FeatureStateSchema and allows any additional string-keyed properties for tree data.
+ */
+export declare const JsonTreeStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$catchall<z.ZodAny>>;
+export type JsonTreeState = z.infer<typeof JsonTreeStateSchema>;
+/**
+ * JsonTree Feature - A powerful JSON file tree loader and processor
+ *
+ * This feature provides functionality to recursively load JSON files from a directory structure
+ * and build a hierarchical tree representation. It automatically processes file paths to create
+ * a nested object structure where file paths become object property paths.
+ *
+ * **Key Features:**
+ * - Recursive JSON file discovery in directory trees
+ * - Automatic path-to-property mapping using camelCase conversion
+ * - Integration with FileManager for efficient file operations
+ * - State-based tree storage and retrieval
+ * - Native JSON parsing for optimal performance
+ *
+ * **Path Processing:**
+ * Files are processed to create a nested object structure:
+ * - Directory names become object properties (camelCased)
+ * - File names become the final property names (without .json extension)
+ * - Nested directories create nested objects
+ *
+ * **Usage Example:**
+ * ```typescript
+ * const jsonTree = container.feature('jsonTree', { enable: true });
+ * await jsonTree.loadTree('data', 'appData');
+ * const userData = jsonTree.tree.appData.users.profiles;
+ * ```
+ *
+ * **Directory Structure Example:**
+ * ```
+ * data/
+ *   users/
+ *     profiles.json    -> tree.data.users.profiles
+ *     settings.json    -> tree.data.users.settings
+ *   config/
+ *     app-config.json  -> tree.data.config.appConfig
+ * ```
+ *
+ * @template T - The state type, defaults to JsonTreeState
+ * @extends {Feature<T>}
+ */
+export declare class JsonTree<T extends JsonTreeState = JsonTreeState> extends Feature<T> {
+    /** The shortcut path for accessing this feature */
+    static shortcut: "features.jsonTree";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$catchall<z.ZodAny>>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    /**
+     * Loads a tree of JSON files from the specified base path and stores them in state.
+     *
+     * This method recursively scans the provided directory for JSON files, processes their
+     * content, and builds a hierarchical object structure. File paths are converted to
+     * camelCase property names, and the resulting tree is stored in the feature's state.
+     *
+     * **Processing Steps:**
+     * 1. Uses FileManager to discover all .json files recursively
+     * 2. Reads each file's content using the file system feature
+     * 3. Parses JSON content using native JSON.parse()
+     * 4. Converts file paths to nested object properties
+     * 5. Stores the complete tree in feature state
+     *
+     * **Path Transformation:**
+     * - Removes the base path prefix from file paths
+     * - Converts directory/file names to camelCase
+     * - Creates nested objects based on directory structure
+     * - Removes .json file extension
+     *
+     * **Example Transformation:**
+     * ```
+     * config/
+     *   database/
+     *     production.json  -> tree.config.database.production
+     *     staging.json     -> tree.config.database.staging
+     *   api/
+     *     endpoints.json   -> tree.config.api.endpoints
+     * ```
+     *
+     * @param basePath - The root directory path to scan for JSON files
+     * @param key - The key to store the tree under in state (defaults to first segment of basePath)
+     * @returns Promise resolving to the complete tree object
+     *
+     * @throws {Error} When FileManager fails to start or files cannot be read/parsed
+     *
+     * @example
+     * ```typescript
+     * // Load all JSON files from 'data' directory into state.data
+     * await jsonTree.loadTree('data');
+     *
+     * // Load with custom key
+     * await jsonTree.loadTree('app/config', 'configuration');
+     *
+     * // Access the loaded data
+     * const dbConfig = jsonTree.tree.data.database.production;
+     * const apiEndpoints = jsonTree.tree.data.api.endpoints;
+     * ```
+     */
+    loadTree(basePath: string, key?: string): Promise<Pick<T, Exclude<keyof T, "enabled">>>;
+    /**
+     * Gets the current tree data, excluding the 'enabled' state property.
+     *
+     * Returns a clean copy of the tree data without internal state management properties.
+     * This provides access to only the JSON tree data that has been loaded through loadTree().
+     *
+     * @returns The tree object containing all loaded JSON data, organized by keys
+     *
+     * @example
+     * ```typescript
+     * await jsonTree.loadTree('data');
+     * await jsonTree.loadTree('config', 'appConfig');
+     *
+     * const allTrees = jsonTree.tree;
+     * // Returns: {
+     * //   data: { users: { ... }, products: { ... } },
+     * //   appConfig: { database: { ... }, api: { ... } }
+     * // }
+     *
+     * // Access specific trees
+     * const userData = jsonTree.tree.data.users;
+     * const dbConfig = jsonTree.tree.appConfig.database;
+     * ```
+     */
+    get tree(): Pick<T, Exclude<keyof T, "enabled">>;
+}
+export default JsonTree;
+//# sourceMappingURL=json-tree.d.ts.map

package/dist/node/features/json-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-tree.d.ts","sourceRoot":"","sources":["../../../src/node/features/json-tree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAGxC;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;8BAAkD,CAAA;AAClF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,QAAQ,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IAE/E,mDAAmD;IACnD,OAAgB,QAAQ,EAAG,mBAAmB,CAAS;IACvD,OAAgB,WAAW;;mCAAsB;IACjD,OAAgB,aAAa;;;;;sBAAuB;IAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAgC;IAgCtE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,IAAI,IAAI,yCAEP;CACF;AAED,eAAe,QAAQ,CAAA"}