alepha 0.9.5 → 0.10.1

package/README.md

@@ -10,7 +10,6 @@
 Alepha
 </h1>
 <p style="max-width: 512px">
-🚧
 </p>
 <a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/v/alepha.svg" alt="npm"/></a>
 <a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/l/alepha.svg" alt="npm"/></a>
@@ -19,17 +18,23 @@ Alepha
 <a href="https://github.com/feunard/alepha"><img src="https://img.shields.io/github/stars/feunard/alepha.svg?style=social" alt="GitHub stars"/></a>
 </div>
 
-Alepha is a convention-driven TypeScript framework for building robust, end-to-end type-safe applications, from serverless APIs to full-stack React apps.
+A convention-driven TypeScript framework for building type-safe full-stack applications.
 
-## Installation
+## Quick Start
+
+```bash
+npx @alepha/cli create my-app
+```
+
+Or manually:
 
 ```bash
 npm install alepha
 ```
 
-## Usage
+## What is this?
 
-Minimalist http server with a single endpoint.
+Alepha is an opinionated framework that handles everything from database to frontend. It uses a descriptor-based architecture (`$action`, `$page`, `$repository`, etc.) and enforces type safety across the entire stack.
 
 ```ts
 import { run } from "alepha";
@@ -44,50 +49,84 @@ class App {
 run(App);
 ```
 
-👉 For more information, please visit the [documentation](https://feunard.github.io/alepha/).
+## Examples
 
-## Modules
+### Type-safe API endpoint
 
-Alepha is modular, with a LOT of modules.
+```ts
+import { $action } from "alepha/server";
+import { t } from "alepha/core";
+
+class UserController {
+  getUser = $action({
+    schema: {
+      params: t.object({ id: t.string() }),
+      response: t.object({
+        name: t.string(),
+        email: t.string()
+      })
+    },
+    handler: async ({ params }) => {
+      return { name: "John", email: "john@example.com" };
+    }
+  });
+}
+```
 
-### Core & Application Layer
+### Database with Drizzle ORM
 
-*   **Core ([@alepha/core](https://feunard.github.io/alepha/docs/alepha-core)) 📦:** The heart of the framework, providing a powerful dependency injection container, application lifecycle management, and the core descriptor system.
-*   **Server ([@alepha/server](https://feunard.github.io/alepha/docs/alepha-server)) 🌐:** A high-performance, minimalist HTTP server for creating type-safe REST APIs using declarative `$action` descriptors.
-*   **Database ([@alepha/postgres](https://feunard.github.io/alepha/docs/alepha-postgres)) 🗄️:** A powerful and type-safe ORM built on Drizzle. Define your schema with `$entity` and get fully-typed repositories with `$repository`.
-*   **React ([@alepha/react](https://feunard.github.io/alepha/docs/alepha-react)) ⚛️:** Build full-stack, server-side rendered React applications with a file-based routing system (`$page`) that handles data fetching, hydration, and type-safe props.
+```ts
+import {$entity, $repository, pg} from "alepha/postgres";
+import {t, Static} from "alepha";
 
-### Backend Infrastructure & Abstractions
+export const users = $entity({
+  id: pg.primaryKey(),
+  name: t.string(),
+  email: t.string()
+});
 
-*   **Security ([@alepha/security](https://feunard.github.io/alepha/docs/alepha-security)) 🛡️:** A complete authentication and authorization system. Manage roles (`$role`), permissions (`$permission`), JWTs, and realms (`$realm`).
-*   **Queue ([@alepha/queue](https://feunard.github.io/alepha/docs/alepha-queue)) ⏳:** A simple and robust interface for background job processing. Define workers with the `$queue` descriptor and integrate with backends like Redis.
-*   **Cache ([@alepha/cache](https://feunard.github.io/alepha/docs/alepha-cache)) ⚡:** A flexible caching layer with support for TTL, automatic function caching (`$cache`), and multiple backends like in-memory or Redis.
-*   **Bucket ([@alepha/bucket](https://feunard.github.io/alepha/docs/alepha-bucket)) ☁️:** A unified API for file and object storage. Abstract away the details of local, in-memory, or cloud storage providers like Azure Blob Storage.
-*   **Scheduler ([@alepha/scheduler](https://feunard.github.io/alepha/docs/alepha-scheduler)) ⏰:** Schedule recurring tasks using cron expressions or fixed intervals with the `$scheduler` descriptor, with built-in support for distributed locking.
-*   **Topic ([@alepha/topic](https://feunard.github.io/alepha/docs/alepha-topic)) 📢:** A publish-subscribe (pub/sub) messaging interface for building event-driven architectures with `$topic` and `$subscriber`.
-*   **Lock ([@alepha/lock](https://feunard.github.io/alepha/docs/alepha-lock)) 🔒:** A distributed locking mechanism to ensure safe concurrent access to shared resources, using Redis or other backends.
+type CreateUser = Static<typeof users.$insertSchema>;
 
-### Server Middleware & Plugins
+class UserService {
+  users = $repository(users);
 
-*   **Links ([@alepha/server-links](https://feunard.github.io/alepha/docs/alepha-server-links)) 🔗:** Enables end-to-end type-safe communication between your frontend and backend, or between microservices, with the `$client` descriptor.
-*   **Swagger ([@alepha/server-swagger](https://feunard.github.io/alepha/docs/alepha-server-swagger)) 📜:** Automatically generate OpenAPI 3.0 documentation and a beautiful Swagger UI for all your `$action` API endpoints.
-*   **Helmet ([@alepha/server-helmet](https://feunard.github.io/alepha/docs/alepha-server-helmet)) 🎩:** Enhance your application's security by automatically applying essential HTTP security headers like CSP and HSTS.
-*   **CORS ([@alepha/server-cors](https://feunard.github.io/alepha/docs/alepha-server-cors)) ↔️:** A configurable middleware to handle Cross-Origin Resource Sharing (CORS) for your server.
-*   **Multipart ([@alepha/server-multipart](https://feunard.github.io/alepha/docs/alepha-server-multipart)) 📎:** Seamlessly handle `multipart/form-data` requests for file uploads.
-*   **Compress ([@alepha/server-compress](https://feunard.github.io/alepha/docs/alepha-server-compress)) 📦💨:** Automatically compress server responses with Gzip or Brotli to improve performance.
+  async create(data: CreateUser) {
+    return await this.users.create(data);
+  }
+}
+```
+
+### React SSR Page
 
-And more, like **Request Logging**, **Error Handling**, and **Response Caching**, cookie parsers, and more, to enhance your server's capabilities.
+```tsx
+import { $page } from "alepha/react";
 
-### Full-Stack & React Ecosystem
+class HomePage {
+  index = $page({
+    component: () => <div>Hello from React SSR!</div>
+  });
+}
+```
 
-*   **Auth ([@alepha/react-auth](https://feunard.github.io/alepha/docs/alepha-react-auth)) 🔑:** Simplifies frontend authentication flows, providing the `useAuth` hook to manage user sessions and permissions in your React components.
-*   **Head ([@alepha/react-head](https://feunard.github.io/alepha/docs/alepha-react-head))  SEO:** Manage your document's `<head>` for SEO and metadata. Control titles, meta tags, and more, both on the server and client.
-*   **i18n ([@alepha/react-i18n](https://feunard.github.io/alepha/docs/alepha-react-i18n)) 🌍:** A complete internationalization solution for your React applications, with support for lazy-loaded translation files and the `useI18n` hook.
-*   **Form ([@alepha/react-form](https://feunard.github.io/alepha/docs/alepha-react-form)) 📝:** Create powerful, type-safe forms with automatic validation using the `useForm` hook, powered by your TypeBox schemas.
+## Core Concepts
 
-### Tooling & Utilities
+- **Descriptors**: Define your app logic with `$action`, `$page`, `$repository`, `$cache`, `$email`, etc.
+- **Type Safety**: TypeBox schemas validate data from DB to API to frontend
+- **DI Container**: Built-in dependency injection using `$inject()`
+- **Convention over Config**: Minimal boilerplate, sensible defaults
+- **Full-Stack**: React SSR, Vite, class-based router with type-safe routing
+
+## Stack
+
+- Node.js 22+
+- TypeScript
+- React (SSR)
+- Vite
+- Drizzle ORM
+- PostgreSQL
+
+👉 For more information, please visit the [documentation](https://feunard.github.io/alepha/).
 
-*   **Vite ([@alepha/vite](https://feunard.github.io/alepha/docs/alepha-vite)) ✨:** A seamless Vite plugin that handles all the complex build and development server configurations for your full-stack Alepha applications.
-*   **Command ([@alepha/command](https://feunard.github.io/alepha/docs/alepha-command)) ⌨️:** Build powerful, type-safe command-line interfaces and scripts directly within your application using the `$command` descriptor.
-*   **Retry ([@alepha/retry](https://feunard.github.io/alepha/docs/alepha-retry)) 🔄:** A declarative and powerful decorator (`$retry`) for automatically retrying failed operations with exponential backoff.
+## License
 
+MIT

package/batch.d.ts

@@ -4,6 +4,7 @@ import { DateTimeProvider, DurationLike } from "alepha/datetime";
 import * as _alepha_logger0 from "alepha/logger";
 import * as _alepha_retry0 from "alepha/retry";
 import { RetryDescriptorOptions } from "alepha/retry";
+import * as typebox0 from "typebox";
 
 //#region src/descriptors/$batch.d.ts
 
@@ -532,9 +533,7 @@ declare class BatchDescriptor<TItem extends TSchema, TResponse = any> extends De
   protected readonly dateTime: DateTimeProvider;
   protected readonly partitions: Map<any, any>;
   protected activeHandlers: PromiseWithResolvers<void>[];
-  protected retry: _alepha_retry0.RetryDescriptorFn<(items: (TItem & {
-    params: [];
-  })["static"][]) => TResponse>;
+  protected retry: _alepha_retry0.RetryDescriptorFn<(items: typebox0.StaticType<[], "Encode", {}, {}, TItem>[]) => TResponse>;
   /**
    * Pushes an item into the batch. The item will be processed
    * asynchronously with other items when the batch is flushed.

package/bucket.d.ts

@@ -2,7 +2,7 @@ import * as _alepha_core1 from "alepha";
 import { Alepha, AlephaError, Descriptor, FileLike, KIND, Service } from "alepha";
 import * as fs from "node:fs";
 import * as _alepha_logger0 from "alepha/logger";
-import * as _sinclair_typebox0 from "@sinclair/typebox";
+import * as typebox0 from "typebox";
 
 //#region src/providers/FileStorageProvider.d.ts
 declare abstract class FileStorageProvider {
@@ -519,7 +519,7 @@ interface BucketFileOptions {
   maxSize?: number;
 }
 declare class BucketDescriptor extends Descriptor<BucketDescriptorOptions> {
-  readonly provider: MemoryFileStorageProvider | FileStorageProvider;
+  readonly provider: FileStorageProvider | MemoryFileStorageProvider;
   get name(): string;
   /**
    * Uploads a file to the bucket.
@@ -537,7 +537,7 @@ declare class BucketDescriptor extends Descriptor<BucketDescriptorOptions> {
    * Downloads a file from the bucket.
    */
   download(fileId: string): Promise<FileLike>;
-  protected $provider(): MemoryFileStorageProvider | FileStorageProvider;
+  protected $provider(): FileStorageProvider | MemoryFileStorageProvider;
 }
 interface BucketFileOptions {
   /**
@@ -579,10 +579,10 @@ declare class LocalFileStorageProvider implements FileStorageProvider {
   protected path(container: string, fileId?: string): string;
   protected isErrorNoEntry(error: unknown): boolean;
 }
-declare const fileMetadataSchema: _sinclair_typebox0.TObject<{
-  name: _sinclair_typebox0.TString;
-  type: _sinclair_typebox0.TString;
-  size: _sinclair_typebox0.TNumber;
+declare const fileMetadataSchema: typebox0.TObject<{
+  name: typebox0.TString;
+  type: typebox0.TString;
+  size: typebox0.TNumber;
 }>;
 //#endregion
 //#region src/index.d.ts

package/command.d.ts

@@ -1,10 +1,51 @@
 import * as _alepha_core1 from "alepha";
-import { Alepha, AlephaError, Async, Descriptor, KIND, Static, TObject, TSchema } from "alepha";
+import { Alepha, AlephaError, Async, Descriptor, KIND, Static, TObject, TSchema, TString } from "alepha";
+import * as _alepha_logger0 from "alepha/logger";
 import * as fs from "node:fs/promises";
 import { glob } from "node:fs/promises";
-import * as _alepha_logger0 from "alepha/logger";
-import * as _sinclair_typebox0 from "@sinclair/typebox";
+import * as readline_promises0 from "readline/promises";
+import * as typebox0 from "typebox";
 
+//#region src/helpers/Asker.d.ts
+interface AskOptions<T extends TSchema = TString> {
+  /**
+   * Response schema expected.
+   *
+   * Recommended schemas:
+   * - t.string() - for free text input
+   * - t.number() - for numeric input
+   * - t.boolean() - for yes/no input (accepts "true", "false", "1", "0")
+   * - t.enum(["option1", "option2"]) - for predefined options
+   *
+   * You can use schema.default to provide a default value.
+   *
+   * @example
+   * ```ts
+   * ask("What is your name?", { schema: t.string({ default: "John Doe" }) })
+   * ```
+   *
+   * @default TString
+   */
+  schema?: T;
+  /**
+   * Custom validation function.
+   * Throws an AlephaError in case of validation failure.
+   */
+  validate?: (value: Static<T>) => void;
+}
+interface AskMethod {
+  <T extends TSchema = TString>(question: string, options?: AskOptions<T>): Promise<Static<T>>;
+}
+declare class Asker {
+  protected readonly log: _alepha_logger0.Logger;
+  readonly ask: AskMethod;
+  protected readonly alepha: Alepha;
+  constructor();
+  protected createAskMethod(): AskMethod;
+  protected prompt<T extends TSchema = TString>(question: string, options: AskOptions<T>): Promise<Static<T>>;
+  protected createPromptInterface(): readline_promises0.Interface;
+}
+//#endregion
 //#region src/helpers/Runner.d.ts
 type Task = {
   name: string;
@@ -19,13 +60,9 @@ interface RunOptions {
    * Rename the command for logging purposes.
    */
   alias?: string;
-  /**
-   * If true, the command will not be logged.
-   */
-  silent?: boolean;
 }
 interface RunnerMethod {
-  (cmd: string | Array<string | Task>, fn?: () => any, options?: RunOptions): Promise<string>;
+  (cmd: string | Task | Array<string | Task>, options?: RunOptions | (() => any)): Promise<string>;
   rm: (glob: string | string[], options?: RunOptions) => Promise<string>;
   cp: (source: string, dest: string, options?: RunOptions) => Promise<string>;
 }
@@ -59,14 +96,14 @@ declare class Runner {
  * within your Alepha application structure.
  */
 declare const $command: {
-  <T extends TObject>(options: CommandDescriptorOptions<T>): CommandDescriptor<T>;
+  <T extends TObject, A extends TSchema>(options: CommandDescriptorOptions<T, A>): CommandDescriptor<T, A>;
   [KIND]: typeof CommandDescriptor;
 };
-interface CommandDescriptorOptions<T extends TObject> {
+interface CommandDescriptorOptions<T extends TObject, A extends TSchema> {
   /**
    * The handler function to execute when the command is matched.
    */
-  handler: (args: CommandHandlerArgs<T>) => Async<void>;
+  handler: (args: CommandHandlerArgs<T, A>) => Async<void>;
   /**
    * The name of the command. If omitted, the property key is used.
    *
@@ -85,19 +122,38 @@ interface CommandDescriptorOptions<T extends TObject> {
    * A TypeBox object schema defining the flags for the command.
    */
   flags?: T;
+  /**
+   * An optional TypeBox schema defining the arguments for the command.
+   *
+   * @example
+   * args: t.string()
+   * my-cli command <arg1: string>
+   *
+   * args: t.optional(t.string())
+   * my-cli command [arg1: string]
+   *
+   * args: t.tuple([t.string(), t.number()])
+   * my-cli command <arg1: string> <arg2: number>
+   *
+   * args: t.tuple([t.string(), t.optional(t.number())])
+   * my-cli command <arg1: string> [arg2: number]
+   */
+  args?: A;
   /**
    * If false, skip summary message at the end of the command execution.
    */
   summary?: boolean;
 }
-declare class CommandDescriptor<T extends TObject = TObject> extends Descriptor<CommandDescriptorOptions<T>> {
+declare class CommandDescriptor<T extends TObject = TObject, A extends TSchema = TSchema> extends Descriptor<CommandDescriptorOptions<T, A>> {
   readonly flags: TObject<{}>;
   readonly aliases: string[];
   get name(): string;
 }
-interface CommandHandlerArgs<T extends TObject> {
+interface CommandHandlerArgs<T extends TObject, A extends TSchema = TSchema> {
   flags: Static<T>;
+  args: A extends TSchema ? Static<A> : undefined;
   run: RunnerMethod;
+  ask: AskMethod;
   glob: typeof glob;
   fs: typeof fs;
 }
@@ -123,6 +179,7 @@ declare class CliProvider {
   protected readonly alepha: Alepha;
   protected readonly log: _alepha_logger0.Logger;
   protected readonly runner: Runner;
+  protected readonly asker: Asker;
   options: {
     name: string;
     description: string;
@@ -132,7 +189,7 @@ declare class CliProvider {
     help: {
       aliases: string[];
       description: string;
-      schema: _sinclair_typebox0.TBoolean;
+      schema: typebox0.TBoolean;
     };
   };
   protected readonly onReady: _alepha_core1.HookDescriptor<"ready">;
@@ -144,6 +201,10 @@ declare class CliProvider {
     aliases: string[];
     schema: TSchema;
   }[]): Record<string, any>;
+  protected parseCommandArgs(argv: string[], schema?: TSchema): any;
+  protected parseArgumentValue(value: string, schema: TSchema): any;
+  protected generateArgsUsage(schema?: TSchema): string;
+  protected getTypeName(schema: TSchema): string;
   printHelp(command?: CommandDescriptor<any>): void;
   private getMaxCmdLength;
   private getMaxFlagLength;
@@ -160,7 +221,7 @@ declare class CliProvider {
  * @module alepha.command
  */
 declare const AlephaCommand: _alepha_core1.Service<_alepha_core1.Module>;
-declare module "@sinclair/typebox" {
+declare module "typebox" {
   interface StringOptions {
     /**
      * Additional aliases for the flags.
@@ -173,5 +234,5 @@ declare module "@sinclair/typebox" {
 //# sourceMappingURL=index.d.ts.map
 
 //#endregion
-export { $command, AlephaCommand, CliProvider, CommandDescriptor, CommandDescriptorOptions, CommandError, CommandHandlerArgs, RunOptions, Runner, RunnerMethod, Task };
+export { $command, AlephaCommand, AskMethod, AskOptions, Asker, CliProvider, CommandDescriptor, CommandDescriptorOptions, CommandError, CommandHandlerArgs, RunOptions, Runner, RunnerMethod, Task };
 //# sourceMappingURL=index.d.ts.map