@alepha/ui 0.10.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Feunard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,329 @@
+# Alepha Batch
+
+Efficiently process operations in groups by size or time.
+
+## Installation
+
+This package is part of the Alepha framework and can be installed via the all-in-one package:
+
+```bash
+npm install alepha
+```
+
+## Module
+
+This module allows you to group multiple asynchronous operations into a single "batch," which is then processed together.
+This is an essential pattern for improving performance, reducing I/O, and interacting efficiently with rate-limited APIs or databases.
+
+```ts
+import { Alepha, $hook, run, t } from "alepha";
+import { $batch } from "alepha/batch";
+
+class LoggingService {
+  // define the batch processor
+  logBatch = $batch({
+    schema: t.text(),
+    maxSize: 10,
+    maxDuration: [5, "seconds"],
+    handler: async (items) => {
+      console.log(`[BATCH LOG] Processing ${items.length} events:`, items);
+    },
+  });
+
+  // example of how to use it
+  onReady = $hook({
+    on: "ready",
+    handler: async () => {
+      this.logBatch.push("Application started.");
+      this.logBatch.push("User authenticated.");
+      // ... more events pushed from elsewhere in the app
+    },
+  });
+}
+```
+
+This module can be imported and used as follows:
+
+```typescript
+import { Alepha, run } from "alepha";
+import { AlephaBatch } from "alepha/batch";
+
+const alepha = Alepha.create()
+	.with(AlephaBatch);
+
+run(alepha);
+```
+
+## API Reference
+
+### Descriptors
+
+Descriptors are functions that define and configure various aspects of your application. They follow the convention of starting with ` $ ` and return configured descriptor instances.
+
+For more details, see the [Descriptors documentation](/docs/descriptors).
+
+#### $batch()
+
+Creates a batch processing descriptor for efficient grouping and processing of multiple operations.
+
+This descriptor provides a powerful batching mechanism that collects multiple individual items
+and processes them together in groups, significantly improving performance by reducing overhead
+and enabling bulk operations. It supports partitioning, concurrent processing, automatic flushing,
+and intelligent retry mechanisms for robust batch processing workflows.
+
+**Key Features**
+
+- **Intelligent Batching**: Groups items based on size and time thresholds
+- **Partitioning Support**: Process different types of items in separate batches
+- **Concurrent Processing**: Handle multiple batches simultaneously with configurable limits
+- **Automatic Flushing**: Time-based and size-based automatic batch execution
+- **Type Safety**: Full TypeScript support with schema validation using TypeBox
+- **Retry Logic**: Built-in retry mechanisms for failed batch operations
+- **Resource Management**: Automatic cleanup and graceful shutdown handling
+
+**Use Cases**
+
+Perfect for optimizing high-throughput operations:
+- Database bulk inserts and updates
+- API call batching and rate limit optimization
+- Log aggregation and bulk shipping
+- File processing and bulk uploads
+- Event processing and analytics ingestion
+- Notification delivery optimization
+- Cache invalidation batching
+
+**Basic database batch operations:**
+```ts
+import { $batch } from "alepha/batch";
+import { t } from "alepha";
+
+class UserService {
+  userBatch = $batch({
+    schema: t.object({
+      id: t.text(),
+      name: t.text(),
+      email: t.text(),
+      createdAt: t.optional(t.text())
+    }),
+    maxSize: 50,          // Process up to 50 users at once
+    maxDuration: [5, "seconds"],  // Or flush every 5 seconds
+    handler: async (users) => {
+      // Bulk insert users - much faster than individual inserts
+      console.log(`Processing batch of ${users.length} users`);
+
+      const result = await this.database.users.insertMany(users.map(user => ({
+        ...user,
+        createdAt: user.createdAt || new Date().toISOString()
+      })));
+
+      console.log(`Successfully inserted ${result.length} users`);
+      return { inserted: result.length, userIds: result.map(r => r.id) };
+    }
+  });
+
+  async createUser(userData: { name: string; email: string }) {
+    // Individual calls are automatically batched
+    const result = await this.userBatch.push({
+      id: generateId(),
+      name: userData.name,
+      email: userData.email
+    });
+
+    return result; // Returns the batch result once batch is processed
+  }
+}
+```
+
+**API call batching with partitioning:**
+```ts
+class NotificationService {
+  notificationBatch = $batch({
+    schema: t.object({
+      userId: t.text(),
+      type: t.enum(["email", "sms", "push"]),
+      message: t.text(),
+      priority: t.enum(["high", "normal", "low"])
+    }),
+    maxSize: 100,
+    maxDuration: [10, "seconds"],
+    // Partition by notification type for different processing
+    partitionBy: (notification) => notification.type,
+    concurrency: 3,  // Process up to 3 different types simultaneously
+    handler: async (notifications) => {
+      const type = notifications[0].type; // All items in batch have same type
+      console.log(`Processing ${notifications.length} ${type} notifications`);
+
+      switch (type) {
+        case 'email':
+          return await this.emailProvider.sendBulk(notifications.map(n => ({
+            to: n.userId,
+            subject: 'Notification',
+            body: n.message,
+            priority: n.priority
+          })));
+
+        case 'sms':
+          return await this.smsProvider.sendBulk(notifications.map(n => ({
+            to: n.userId,
+            message: n.message
+          })));
+
+        case 'push':
+          return await this.pushProvider.sendBulk(notifications.map(n => ({
+            userId: n.userId,
+            title: 'Notification',
+            body: n.message,
+            priority: n.priority
+          })));
+      }
+    }
+  });
+
+  async sendNotification(userId: string, type: 'email' | 'sms' | 'push', message: string, priority: 'high' | 'normal' | 'low' = 'normal') {
+    // Notifications are automatically batched by type
+    return await this.notificationBatch.push({
+      userId,
+      type,
+      message,
+      priority
+    });
+  }
+}
+```
+
+**Log aggregation with retry logic:**
+```ts
+class LoggingService {
+  logBatch = $batch({
+    schema: t.object({
+      timestamp: t.number(),
+      level: t.enum(["info", "warn", "error"]),
+      message: t.text(),
+      metadata: t.optional(t.record(t.text(), t.any())),
+      source: t.text()
+    }),
+    maxSize: 1000,       // Large batches for log efficiency
+    maxDuration: [30, "seconds"],  // Longer duration for log aggregation
+    concurrency: 2,      // Limit concurrent log shipments
+    retry: {
+      maxAttempts: 5,
+      delay: [2, "seconds"],
+      backoff: "exponential"
+    },
+    handler: async (logEntries) => {
+      console.log(`Shipping ${logEntries.length} log entries`);
+
+      try {
+        // Ship logs to external service (e.g., Elasticsearch, Splunk)
+        const response = await this.logShipper.bulkIndex({
+          index: 'application-logs',
+          body: logEntries.map(entry => ([
+            { index: { _index: 'application-logs' } },
+            {
+              ...entry,
+              '@timestamp': new Date(entry.timestamp).toISOString()
+            }
+          ])).flat()
+        });
+
+        if (response.errors) {
+          console.error(`Some log entries failed to index`, response.errors);
+          // Retry will be triggered by throwing
+          throw new Error(`Failed to index ${response.errors.length} log entries`);
+        }
+
+        console.log(`Successfully shipped ${logEntries.length} log entries`);
+        return { shipped: logEntries.length, indexedAt: Date.now() };
+
+      } catch (error) {
+        console.error(`Failed to ship logs batch`, error);
+        throw error; // Trigger retry mechanism
+      }
+    }
+  });
+
+  async log(level: 'info' | 'warn' | 'error', message: string, metadata?: Record<string, any>, source: string = 'application') {
+    // Individual log calls are batched and shipped efficiently
+    return await this.logBatch.push({
+      timestamp: Date.now(),
+      level,
+      message,
+      metadata,
+      source
+    });
+  }
+}
+```
+
+**File processing with dynamic partitioning:**
+```ts
+class FileProcessingService {
+  fileProcessingBatch = $batch({
+    schema: t.object({
+      filePath: t.text(),
+      fileType: t.enum(["image", "video", "document"]),
+      processingOptions: t.object({
+        quality: t.optional(t.enum(["low", "medium", "high"])),
+        format: t.optional(t.text()),
+        compress: t.optional(t.boolean())
+      }),
+      priority: t.enum(["urgent", "normal", "background"])
+    }),
+    maxSize: 20,         // Smaller batches for file processing
+    maxDuration: [2, "minutes"],  // Reasonable time for file accumulation
+    // Partition by file type and priority for optimal resource usage
+    partitionBy: (file) => `${file.fileType}-${file.priority}`,
+    concurrency: 4,      // Multiple concurrent processing pipelines
+    retry: {
+      maxAttempts: 3,
+      delay: [5, "seconds"]
+    },
+    handler: async (files) => {
+      const fileType = files[0].fileType;
+      const priority = files[0].priority;
+
+      console.log(`Processing ${files.length} ${fileType} files with ${priority} priority`);
+
+      try {
+        const results = [];
+
+        for (const file of files) {
+          const result = await this.processFile(file.filePath, file.fileType, file.processingOptions);
+          results.push({
+            originalPath: file.filePath,
+            processedPath: result.outputPath,
+            size: result.size,
+            duration: result.processingTime
+          });
+        }
+
+        // Update database with batch results
+        await this.updateProcessingStatus(results);
+
+        console.log(`Successfully processed ${files.length} ${fileType} files`);
+        return {
+          processed: files.length,
+          fileType,
+          priority,
+          totalSize: results.reduce((sum, r) => sum + r.size, 0),
+          results
+        };
+
+      } catch (error) {
+        console.error(`Batch file processing failed for ${fileType} files`, error);
+        throw error;
+      }
+    }
+  });
+
+  async processFile(filePath: string, fileType: 'image' | 'video' | 'document', options: any, priority: 'urgent' | 'normal' | 'background' = 'normal') {
+    // Files are automatically batched by type and priority
+    return await this.fileProcessingBatch.push({
+      filePath,
+      fileType,
+      processingOptions: options,
+      priority
+    });
+  }
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+import * as _alepha_core0 from "@alepha/core";
+import { RouterGoOptions, UseActiveOptions } from "@alepha/react";
+import "@mantine/core/styles.css";
+import "@mantine/nprogress/styles.css";
+import "@mantine/spotlight/styles.css";
+import "@mantine/notifications/styles.css";
+import { FormModel, InputField } from "@alepha/react-form";
+import { AutocompleteProps, ButtonProps, ColorSchemeScriptProps, MantineProviderProps, PasswordInputProps, SegmentedControlProps, SelectProps, SwitchProps, TextInputProps, TextareaProps } from "@mantine/core";
+import { ComponentType, ReactNode } from "react";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { ModalsProviderProps } from "@mantine/modals";
+import { NotificationsProps } from "@mantine/notifications";
+import { NavigationProgressProps } from "@mantine/nprogress";
+
+//#region src/components/Action.d.ts
+interface ActionCommonProps extends ButtonProps {
+  children?: ReactNode;
+  textVisibleFrom?: "xs" | "sm" | "md" | "lg" | "xl";
+  /**
+   * If set, a confirmation dialog will be shown before performing the action.
+   * If `true`, a default title and message will be used.
+   * If a string, it will be used as the message with a default title.
+   * If an object, it can contain `title` and `message` properties to customize the dialog.
+   */
+  confirm?: boolean | string | {
+    title?: string;
+    message: string;
+  };
+}
+type ActionProps = ActionCommonProps & (ActiveHrefProps | ActionClickProps | ActionSubmitProps | {});
+declare const Action: (_props: ActionProps) => react_jsx_runtime0.JSX.Element;
+interface ActionSubmitProps extends ButtonProps {
+  form: FormModel<any>;
+}
+interface ActionClickProps extends ButtonProps {
+  onClick: (e: any) => any;
+}
+interface ActiveHrefProps extends ButtonProps {
+  href: string;
+  active?: Partial<UseActiveOptions> | false;
+  routerGoOptions?: RouterGoOptions;
+}
+//#endregion
+//#region src/components/AlephaMantineProvider.d.ts
+interface AlephaMantineProviderProps {
+  children?: ReactNode;
+  mantine?: MantineProviderProps;
+  colorSchemeScript?: ColorSchemeScriptProps;
+  navigationProgress?: NavigationProgressProps;
+  notifications?: NotificationsProps;
+  modals?: ModalsProviderProps;
+}
+declare const AlephaMantineProvider: (props: AlephaMantineProviderProps) => react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/components/Control.d.ts
+interface ControlProps {
+  input: InputField;
+  title?: string;
+  description?: string;
+  icon?: ReactNode;
+  text?: TextInputProps;
+  area?: boolean | TextareaProps;
+  select?: boolean | SelectProps;
+  autocomplete?: boolean | AutocompleteProps;
+  password?: boolean | PasswordInputProps;
+  switch?: boolean | SwitchProps;
+  segmented?: boolean | Partial<SegmentedControlProps>;
+  custom?: ComponentType<CustomControlProps>;
+}
+/**
+ * Generic form control that renders the appropriate input based on the schema and props.
+ *
+ * Supports:
+ * - TextInput
+ * - Textarea
+ * - Select (for enum types)
+ * - Autocomplete
+ * - PasswordInput
+ * - Switch (for boolean types)
+ * - SegmentedControl (for enum types)
+ * - Custom component
+ *
+ * Automatically handles labels, descriptions, error messages, and required state.
+ */
+declare const Control: (props: ControlProps) => react_jsx_runtime0.JSX.Element | null;
+type CustomControlProps = {
+  defaultValue: any;
+  onChange: (value: any) => void;
+};
+//#endregion
+//#region src/index.d.ts
+/**
+ *
+ *
+ * @module alepha.ui
+ */
+declare const AlephaUI: _alepha_core0.Service<_alepha_core0.Module<{}>>;
+//#endregion
+export { Action, AlephaMantineProvider, AlephaUI, Control };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/components/Action.tsx","../src/components/AlephaMantineProvider.tsx","../src/components/Control.tsx","../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;UAWiB,iBAAA,SAA0B;aAC/B;;;;;;;;;;IADK,OAAA,EAAA,MAAA;EAAkB,CAAA;;AAAQ,KAc/B,WAAA,GAAc,iBAdiB,GAAA,CAezC,eAfyC,GAevB,gBAfuB,GAeJ,iBAfI,GAAA,CAAA,CAAA,CAAA;cAmBrC,MAnBgD,EAAA,CAAA,MAAA,EAmB9B,WAnB8B,EAAA,GAmBnB,kBAAA,CAAA,GAAA,CAAA,OAnBmB;AAc/B,UAkEN,iBAAA,SAA0B,WAlEpB,CAAA;MAAG,EAmEnB,SAnEmB,CAAA,GAAA,CAAA;;AACN,UAyFH,gBAAA,SAAyB,WAzFtB,CAAA;SAAmB,EAAA,CAAA,CAAA,EAAA,GAAA,EAAA,GAAA,GAAA;;AAIjC,UA6HW,eAAA,SAAwB,WAtExC,CAAA;EAAA,IAAA,EAAA,MAAA;QAvDuB,CAAA,EA+Hd,OA/Hc,CA+HN,gBA/HM,CAAA,GAAA,KAAA;iBAAW,CAAA,EAgIhB,eAhIgB;;;;UClBlB,0BAAA;aACL;YACD;sBACU;uBACC;kBACL;WACP;;cAGJ,+BAAgC,+BAA0B,kBAAA,CAAA,GAAA,CAAA;;;UCC/C,YAAA;SACT;;;SAKA;SAEA;mBACU;qBACE;2BACM;uBACJ;qBACF;wBACG,QAAQ;EFzBd,MAAA,CAAA,EE2BP,aF3ByB,CE2BX,kBF3BW,CAAA;;;;;AAcnC;;;;;;;AAC+D;;;;;AAiE/D,cEnCM,OFmCW,EAAA,CAAkB,KAAA,EEnCX,YFmCW,EAAA,GEnCC,kBAAA,CAAA,GAAA,CAAA,OAAA,GFmCD,IAAA;AAC5B,KEmLK,kBAAA,GFnLL;cADoC,EAAA,GAAA;EAAW,QAAA,EAAA,CAAA,KAAA,EAAA,GAAA,EAAA,GAAA,IAAA;AAwBtD,CAAA;;;;;;;;cG7Fa,UAAQ,aAAA,CAAA,QAGnB,aAAA,CAHmB"}