alepha 0.15.1 → 0.15.2

package/src/fake/providers/FakeProvider.ts

@@ -24,6 +24,37 @@ export interface FakeOptions {
    * Seed for deterministic fake data generation.
    */
   seed?: number;
+
+  /**
+   * Probability (0-1) that an optional field will be undefined.
+   * @default 0.3
+   */
+  optionalProbability?: number;
+
+  /**
+   * Probability (0-1) that a nullable field will be null.
+   * @default 0.2
+   */
+  nullableProbability?: number;
+
+  /**
+   * Default number of items to generate for arrays when maxItems is not specified.
+   * @default 5
+   */
+  defaultArrayLength?: number;
+
+  /**
+   * Maximum number of items to generate for arrays.
+   * Set to Infinity to respect schema's maxItems without cap.
+   * @default 20
+   */
+  maxArrayLength?: number;
+
+  /**
+   * Default number of entries to generate for record types.
+   * @default { min: 2, max: 5 }
+   */
+  defaultRecordEntries?: { min: number; max: number };
 }
 
 /**
@@ -38,27 +69,98 @@ export interface FakeOptions {
  *   email: t.email(),
  * });
  * const fakeUser = fake.generate(userSchema);
+ *
+ * // Configure options
+ * fake.configure({ seed: 99999, optionalProbability: 0.5 });
  * ```
  */
 export class FakeProvider {
-  protected readonly faker: typeof faker;
-  protected readonly guard: TypeGuard;
-
-  constructor(options?: FakeOptions) {
-    // Set seed for deterministic generation FIRST
-    if (options?.seed !== undefined) {
-      faker.seed(options.seed);
-    }
-
-    // Note: faker.js v9 doesn't have setLocale anymore, locales are set differently
-    // For now, we'll just use the default locale
-    this.faker = faker;
+  protected readonly faker = faker;
+  protected readonly guard = new TypeGuard();
+  protected options: Required<FakeOptions> = {
+    locale: "en",
+    seed: 12345,
+    optionalProbability: 0.3,
+    nullableProbability: 0.2,
+    defaultArrayLength: 5,
+    maxArrayLength: 20,
+    defaultRecordEntries: { min: 2, max: 5 },
+  };
+
+  constructor() {
+    this.faker.seed(this.options.seed);
+  }
 
-    this.guard = new TypeGuard();
+  /**
+   * Configure generation options.
+   * If a seed is provided, the faker instance is reseeded.
+   */
+  public configure(options: Partial<FakeOptions>): this {
+    const oldSeed = this.options.seed;
+
+    this.options = {
+      ...this.options,
+      ...options,
+      // Merge defaultRecordEntries if provided
+      defaultRecordEntries: options.defaultRecordEntries
+        ? {
+            ...this.options.defaultRecordEntries,
+            ...options.defaultRecordEntries,
+          }
+        : this.options.defaultRecordEntries,
+    };
+
+    // Reseed faker if seed is provided (allows resetting to same seed)
+    if (options.seed !== undefined) {
+      this.faker.seed(options.seed);
+    }
+
+    return this;
   }
 
   /**
    * Generate fake data matching the given TypeBox schema.
+   *
+   * For object schemas, property names are used to generate contextually
+   * appropriate values. The following field name patterns are recognized
+   * (case-insensitive, underscores and hyphens are ignored):
+   *
+   * **String fields:**
+   * - `email` → email address
+   * - `firstName`, `first` → first name
+   * - `lastName`, `last` → last name
+   * - `fullName`, `name` → full name
+   * - `username` → username
+   * - `phone`, `mobile` → phone number
+   * - `address` → street address
+   * - `city` → city name
+   * - `country` → country name
+   * - `state`, `province` → state/province
+   * - `zip`, `postal` → postal code
+   * - `company`, `organization` → company name
+   * - `job`, `title`, `position` → job title
+   * - `url`, `website` → URL
+   * - `avatar`, `image`, `photo` → avatar URL
+   * - `color`, `colour` → color name
+   * - `bio`, `about`, `description` → bio text
+   *
+   * **Number/Integer fields:**
+   * - `age` → 18-99
+   * - `year` → past year
+   * - `month` → 1-12
+   * - `day` → 1-31
+   * - `price`, `amount`, `cost` → monetary value
+   *
+   * @example
+   * ```ts
+   * const fake = new FakeProvider();
+   * const schema = t.object({
+   *   user_name: t.string(),  // generates username
+   *   firstName: t.string(),  // generates first name
+   *   "e-mail": t.string(),   // generates email
+   * });
+   * const result = fake.generate(schema);
+   * ```
    */
   public generate<T extends TSchema>(schema: T): StaticDecode<T> {
     return this.generateValue(schema) as StaticDecode<T>;
@@ -78,7 +180,11 @@ export class FakeProvider {
     // Handle optional
     if (this.guard.isOptional(schema)) {
       // 30% chance of being undefined
-      if (this.faker.datatype.boolean({ probability: 0.3 })) {
+      if (
+        this.faker.datatype.boolean({
+          probability: this.options.optionalProbability,
+        })
+      ) {
         return undefined;
       }
       // Generate the inner schema
@@ -92,7 +198,11 @@ export class FakeProvider {
       const hasNull = union.anyOf.some((s) => this.guard.isNull(s));
       if (hasNull) {
         // 20% chance of being null
-        if (this.faker.datatype.boolean({ probability: 0.2 })) {
+        if (
+          this.faker.datatype.boolean({
+            probability: this.options.nullableProbability,
+          })
+        ) {
           return null;
         }
         // Pick a non-null option
@@ -354,7 +464,10 @@ export class FakeProvider {
   protected generateArray(schema: TArray): unknown[] {
     const schemaAny = schema as any;
     const minItems = schemaAny.minItems ?? 0;
-    const maxItems = Math.min(schemaAny.maxItems ?? 5, 5); // Cap at 5 by default
+    const maxItems = Math.min(
+      schemaAny.maxItems ?? this.options.defaultArrayLength,
+      this.options.maxArrayLength,
+    );
     const length = this.faker.number.int({ min: minItems, max: maxItems });
 
     return Array.from({ length }, () => this.generateValue(schema.items));
@@ -383,8 +496,9 @@ export class FakeProvider {
       return this.generateValue(schema);
     }
 
-    // Normalize key name to lowercase for matching
-    const normalizedKey = keyName.toLowerCase();
+    // Normalize key name: lowercase and remove underscores/hyphens
+    // This allows matching "user_name", "user-name", "userName" etc.
+    const normalizedKey = keyName.toLowerCase().replace(/[_-]/g, "");
 
     // Check if this is a string type that could benefit from context
     if (this.guard.isString(schema)) {
@@ -509,7 +623,7 @@ export class FakeProvider {
       : record.additionalProperties;
 
     // Generate 2-5 random key-value pairs
-    const count = this.faker.number.int({ min: 2, max: 5 });
+    const count = this.faker.number.int(this.options.defaultRecordEntries);
     const result: Record<string, unknown> = {};
 
     for (let i = 0; i < count; i++) {

package/src/lock/core/index.ts

@@ -15,12 +15,19 @@ export * from "./providers/MemoryLockProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Lock a resource for a certain period of time.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | rare | stable |
  *
- * This module provides a memory implementation of the lock provider.
- * You probably want to use an implementation like RedisLockProvider for distributed systems.
+ * Resource locking for distributed systems.
+ *
+ * **Features:**
+ * - Distributed locks with timeout
+ * - Time-based lock expiration
+ * - Automatic release on scope exit
+ * - Distributed coordination via Redis
+ * - Providers: Memory (dev), Redis (production)
  *
- * @see {@link $lock}
  * @module alepha.lock
  */
 export const AlephaLock = $module({

package/src/logger/index.ts

@@ -27,72 +27,23 @@ export * from "./services/Logger.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Minimalist logger module for Alepha.
- *
- * It offers a global logger interface (info, warn, ...) via the `$logger` primitive.
- *
- * ```ts
- * import { $logger } from "alepha/logger";
- *
- * class App {
- *   log = $logger();
- * }
- * ```
- *
- * ### Formatting and Destinations
- *
- * `AlephaLogger` is **extensible**, destinations and formatters can be added or replaced.
- *
- * Default log destinations are:
- * - ConsoleDestinationProvider: logs to the console.
- * - MemoryDestinationProvider: stores logs in memory for later retrieval.
- *
- * Default log formatters are:
- * - JsonFormatterProvider: formats logs as JSON.
- * - SimpleFormatterProvider: formats logs as simple text (with colors when possible).
- * - RawFormatterProvider: formats logs as raw text without any formatting.
- *
- * ### Event Emission
- *
- * The logger emits 'log' events that can be listened to by external code, allowing for custom log processing and destinations.
- *
- * ```ts
- * class CustomDestination {
- *   onLog = $hook({
- *     on: "log",
- *     handler: (ev) => {
- *       // ev.message (formatted message)
- *       // ev.entry (level, raw message, ...)
- *     }
- *   });
- * }
- * ```
- *
- * ### Log Level
- *
- * You can configure the log level and format via environment variables:
- *
- * - `LOG_LEVEL`: Sets the default log level for the application.
- * - `LOG_FORMAT`: Sets the default log format for the application.
- *
- * ```bash
- * LOG_LEVEL=debug LOG_FORMAT=json node src/index.ts
- * ```
- *
- * Log level is also available in the state as `logLevel`, which can be used to dynamically change the log level at runtime.
- * ```ts
- * alepha.state.set("alepha.logger.level", "debug");
- * ```
- *
- * Log level is $module aware, meaning you can set different log levels for different modules.
- *
- * **Module-specific configuration:**
- * - `LOG_LEVEL=my.module.name:debug,info` - debug for `my.module.name` (and submodules), info for others
- * - `LOG_LEVEL=alepha:trace,my.app:error,info` - trace for alepha modules, error for my.app modules, info for others
- *
- * **Wildcard patterns (NEW):**
- * - `LOG_LEVEL=alepha.*:debug,info` - debug for all alepha submodules
- * - `LOG_LEVEL=*.test:silent,*.core:trace,info` - silent for test modules, trace for core modules
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | tooling | rare | stable |
+ *
+ * Configurable logging with multiple outputs.
+ *
+ * **Features:**
+ * - Global logger access
+ * - JSON format
+ * - Pretty colored output
+ * - Raw text format
+ * - Console destination
+ * - Memory destination (for devtools)
+ * - Custom handlers
+ * - Configuration via `LOG_LEVEL` and `LOG_FORMAT`
+ *
+ * @module alepha.logger
  */
 export const AlephaLogger = $module({
   name: "alepha.logger",

package/src/mcp/index.ts

@@ -93,35 +93,18 @@ export { StdioMcpTransport } from "./transports/StdioMcpTransport.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Core MCP module with primitives and server provider.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * This module registers the $tool, $resource, and $prompt primitives
- * and the McpServerProvider. You need to add a transport module
- * (AlephaMcpStdio or AlephaMcpSse) for actual communication.
+ * Model Context Protocol for AI tool integration.
  *
- * @example
- * ```ts
- * import { Alepha, run } from "alepha";
- * import { AlephaMcp, AlephaMcpStdio, $tool, t } from "alepha/mcp";
- *
- * class MyMcpServer {
- *   add = $tool({
- *     description: "Add two numbers",
- *     schema: {
- *       params: t.object({ a: t.number(), b: t.number() }),
- *       result: t.number(),
- *     },
- *     handler: async ({ params }) => params.a + params.b,
- *   });
- * }
- *
- * run(
- *   Alepha.create()
- *     .with(AlephaMcp)
- *     .with(AlephaMcpStdio)
- *     .with(MyMcpServer)
- * );
- * ```
+ * **Features:**
+ * - MCP resource definitions
+ * - MCP tool definitions
+ * - MCP prompt definitions
+ * - JSON-RPC protocol
+ * - SSE and Stdio transports
  *
  * @module alepha.mcp
  */

package/src/mcp/transports/SseMcpTransport.ts

@@ -112,14 +112,8 @@ export class SseMcpTransport {
   message = $route({
     method: "POST",
     path: this.env.MCP_SSE_PATH,
-    secure: false,
     schema: {
       body: t.json(),
-      query: t.object({
-        token: t.optional(
-          t.text({ description: "API token for authentication" }),
-        ),
-      }),
     },
     handler: async (request) => {
       try {
@@ -141,11 +135,6 @@ export class SseMcpTransport {
           string | string[] | undefined
         >;
 
-        // Support token as query parameter (for clients that can't set headers)
-        if (request.query.token && !headers.authorization) {
-          headers.authorization = `Bearer ${request.query.token}`;
-        }
-
         const context: McpContext = { headers };
 
         const response = await this.mcpServer.handleMessage(

package/src/orm/__tests__/PostgresProvider.spec.ts

@@ -1,6 +1,6 @@
 import { Alepha } from "alepha";
 import { describe, expect, it } from "vitest";
-import { $repository, AlephaPostgres } from "../index.ts";
+import { $repository, AlephaOrm } from "../index.ts";
 import { userEntity } from "./fixtures/userEntitySchema.ts";
 
 describe("PostgresProvider", () => {
@@ -9,7 +9,7 @@ describe("PostgresProvider", () => {
       users = $repository(userEntity);
     }
 
-    const alepha = Alepha.create().with(AlephaPostgres);
+    const alepha = Alepha.create().with(AlephaOrm);
 
     const userService = alepha.inject(UserService);
 

package/src/orm/index.browser.ts

@@ -3,8 +3,8 @@ import { AlephaDateTime } from "alepha/datetime";
 
 export * from "./index.shared.ts";
 
-export const AlephaPostgres = $module({
-  name: "alepha.postgres",
+export const AlephaOrm = $module({
+  name: "alepha.orm",
   primitives: [],
   services: [AlephaDateTime],
 });

package/src/orm/index.bun.ts

@@ -15,12 +15,14 @@ import { QueryManager } from "./services/QueryManager.ts";
 import { Repository } from "./services/Repository.ts";
 import { SqliteModelBuilder } from "./services/SqliteModelBuilder.ts";
 
+export const SqliteProvider = BunSqliteProvider;
+
 export * from "./index.shared-server.ts";
 export * from "./providers/drivers/BunPostgresProvider.ts";
 export * from "./providers/drivers/BunSqliteProvider.ts";
 
-export const AlephaPostgres = $module({
-  name: "alepha.postgres",
+export const AlephaOrm = $module({
+  name: "alepha.orm",
   primitives: [$sequence, $entity],
   services: [
     AlephaDateTime,

package/src/orm/index.ts

@@ -94,61 +94,35 @@ export * from "./providers/drivers/BunSqliteProvider.ts";
 export * from "./providers/drivers/NodePostgresProvider.ts";
 export * from "./providers/drivers/NodeSqliteProvider.ts";
 
+export const SqliteProvider = NodeSqliteProvider;
+
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Postgres client based on Drizzle ORM, Alepha type-safe friendly.
- *
- * Automatically selects the appropriate provider based on runtime:
- * - Bun: Uses `BunPostgresProvider` or `BunSqliteProvider`
- * - Node.js: Uses `NodePostgresProvider` or `NodeSqliteProvider`
- *
- * ```ts
- * import { t } from "alepha";
- * import { $entity, $repository, db } from "alepha/postgres";
- *
- * const users = $entity({
- *   name: "users",
- *   schema: t.object({
- *     id: db.primaryKey(),
- *     name: t.text(),
- *     email: t.text(),
- *   }),
- * });
- *
- * class App {
- *   users = $repository(users);
- *
- *   getUserByName(name: string) {
- *     return this.users.findOne({ name: { eq: name } });
- *   }
- * }
- * ```
- *
- * This is not a full ORM, but rather a set of tools to work with Postgres databases in a type-safe way.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | epic | stable |
  *
- * It provides:
- * - A type-safe way to define entities and repositories. (via `$entity` and `$repository`)
- * - Custom query builders and filters.
- * - Built-in special columns like `createdAt`, `updatedAt`, `deletedAt`, `version`.
- * - Automatic JSONB support.
- * - Automatic synchronization of entities with the database schema (for testing and development).
- * - Fallback to raw SQL via Drizzle ORM `sql` function.
+ * Full-featured database abstraction built on Drizzle ORM with complete type safety.
  *
- * Migrations are supported via Drizzle ORM, you need to use the `drizzle-kit` CLI tool to generate and run migrations.
+ * **Features:**
+ * - Define database entities with TypeBox schemas
+ * - Automatic timestamps, soft deletes, and versioning columns
+ * - Type-safe CRUD operations with filtering, pagination, sorting, and relationships
+ * - Database transaction support with automatic rollback
+ * - Auto-incrementing sequences for IDs
+ * - PostgreSQL support (Node.js, Bun, Cloudflare Workers via pglite)
+ * - SQLite support (Node.js, Bun, Cloudflare D1)
+ * - Automatic schema sync for development/testing
+ * - Drizzle Kit migrations for production
+ * - Type-safe filters: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `like`, `between`
+ * - JSONB column support
+ * - Relationship joins
  *
- * @see {@link $entity}
- * @see {@link $sequence}
- * @see {@link $repository}
- * @see {@link $transaction}
- * @see {@link NodePostgresProvider} - Node.js Postgres implementation
- * @see {@link NodeSqliteProvider} - Node.js SQLite implementation
- * @see {@link BunPostgresProvider} - Bun Postgres implementation
- * @see {@link BunSqliteProvider} - Bun SQLite implementation
  * @module alepha.postgres
  */
-export const AlephaPostgres = $module({
-  name: "alepha.postgres",
+export const AlephaOrm = $module({
+  name: "alepha.orm",
   primitives: [$sequence, $entity],
   services: [
     AlephaDateTime,

package/src/orm/providers/drivers/BunSqliteProvider.ts

@@ -162,6 +162,7 @@ export class BunSqliteProvider extends DatabaseProvider {
 
   protected readonly onStop = $hook({
     on: "stop",
+    priority: "last",
     handler: async () => {
       if (this.sqlite) {
         this.log.debug("Closing Bun SQLite connection...");

package/src/orm/services/Repository.ts

@@ -616,7 +616,7 @@ export abstract class Repository<T extends TObject> {
    */
   public async updateOne(
     where: PgQueryWhereOrSQL<T>,
-    data: Partial<Static<TObjectUpdate<T>>>,
+    data: WithSQL<Static<TObjectUpdate<T>>>,
     opts: StatementOptions = {},
   ): Promise<Static<T>> {
     await this.alepha.events.emit("repository:update:before", {
@@ -767,7 +767,7 @@ export abstract class Repository<T extends TObject> {
    */
   public async updateById(
     id: string | number,
-    data: Partial<Static<TObjectUpdate<T>>>,
+    data: WithSQL<Static<TObjectUpdate<T>>>,
     opts: StatementOptions = {},
   ): Promise<Static<T>> {
     return await this.updateOne(this.getWhereId(id), data, opts);
@@ -778,7 +778,7 @@ export abstract class Repository<T extends TObject> {
    */
   public async updateMany(
     where: PgQueryWhereOrSQL<T>,
-    data: Partial<Static<TObjectUpdate<T>>>,
+    data: WithSQL<Static<TObjectUpdate<T>>>,
     opts: StatementOptions = {},
   ): Promise<Array<number | string>> {
     await this.alepha.events.emit("repository:update:before", {
@@ -1177,3 +1177,7 @@ export interface StatementOptions {
    */
   now?: DateTime | string;
 }
+
+type WithSQL<T> = {
+  [P in keyof T]?: T[P] | SQL;
+};

package/src/queue/core/index.ts

@@ -16,14 +16,22 @@ export * from "./providers/WorkerProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides asynchronous message queuing and processing capabilities through declarative queue descriptors.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | epic | stable |
  *
- * The queue module enables reliable background job processing and message passing using the `$queue` descriptor
- * on class properties. It supports schema validation, automatic retries, and multiple queue backends for
- * building scalable, decoupled applications with robust error handling.
+ * Asynchronous message processing with automatic worker management.
+ *
+ * **Features:**
+ * - Background job queues with type-safe payloads
+ * - Queue consumer handlers
+ * - Automatic worker threads for non-blocking processing
+ * - Retry mechanisms with exponential backoff
+ * - Dead letter queues for failed messages
+ * - Batch processing support
+ * - Configurable concurrency and worker pools
+ * - Providers: Memory (dev), Redis (production)
  *
- * @see {@link $queue}
- * @see {@link $consumer}
  * @module alepha.queue
  */
 export const AlephaQueue = $module({