alepha 0.13.1 → 0.13.3

package/src/batch/index.ts

@@ -1,10 +1,10 @@
 import { $module } from "alepha";
-import { $batch } from "./descriptors/$batch.ts";
+import { $batch } from "./primitives/$batch.ts";
 import { BatchProvider } from "./providers/BatchProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export * from "./descriptors/$batch.ts";
+export * from "./primitives/$batch.ts";
 export * from "./providers/BatchProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -53,6 +53,6 @@ export * from "./providers/BatchProvider.ts";
  */
 export const AlephaBatch = $module({
   name: "alepha.batch",
-  descriptors: [$batch],
+  primitives: [$batch],
   services: [BatchProvider],
 });

package/src/batch/{descriptors → primitives}/$batch.ts

@@ -1,14 +1,14 @@
 import {
   $hook,
   $inject,
-  createDescriptor,
-  Descriptor,
+  createPrimitive,
   KIND,
+  Primitive,
   type Static,
   type TSchema,
 } from "alepha";
 import type { DurationLike } from "alepha/datetime";
-import type { RetryDescriptorOptions } from "alepha/retry";
+import type { RetryPrimitiveOptions } from "alepha/retry";
 import {
   type BatchContext,
   type BatchItemState,
@@ -17,19 +17,16 @@ import {
 } from "../providers/BatchProvider.ts";
 
 /**
- * Creates a batch processing descriptor for efficient grouping and processing of multiple operations.
+ * Creates a batch processing primitive for efficient grouping and processing of multiple operations.
  */
 export const $batch = <TItem extends TSchema, TResponse>(
-  options: BatchDescriptorOptions<TItem, TResponse>,
-): BatchDescriptor<TItem, TResponse> =>
-  createDescriptor(BatchDescriptor<TItem, TResponse>, options);
+  options: BatchPrimitiveOptions<TItem, TResponse>,
+): BatchPrimitive<TItem, TResponse> =>
+  createPrimitive(BatchPrimitive<TItem, TResponse>, options);
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface BatchDescriptorOptions<
-  TItem extends TSchema,
-  TResponse = any,
-> {
+export interface BatchPrimitiveOptions<TItem extends TSchema, TResponse = any> {
   /**
    * TypeBox schema for validating each item added to the batch.
    */
@@ -69,7 +66,7 @@ export interface BatchDescriptorOptions<
   /**
    * Retry configuration for failed batch processing operations.
    */
-  retry?: Omit<RetryDescriptorOptions<() => Array<Static<TItem>>>, "handler">;
+  retry?: Omit<RetryPrimitiveOptions<() => Array<Static<TItem>>>, "handler">;
 }
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -78,16 +75,16 @@ export type { BatchItemState, BatchItemStatus };
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class BatchDescriptor<
+export class BatchPrimitive<
   TItem extends TSchema,
   TResponse = any,
-> extends Descriptor<BatchDescriptorOptions<TItem, TResponse>> {
+> extends Primitive<BatchPrimitiveOptions<TItem, TResponse>> {
   protected readonly batchProvider = $inject(BatchProvider);
   protected readonly context: BatchContext<Static<TItem>, TResponse>;
 
   constructor(
     ...args: ConstructorParameters<
-      typeof Descriptor<BatchDescriptorOptions<TItem, TResponse>>
+      typeof Primitive<BatchPrimitiveOptions<TItem, TResponse>>
     >
   ) {
     super(...args);
@@ -172,4 +169,4 @@ export class BatchDescriptor<
   });
 }
 
-$batch[KIND] = BatchDescriptor;
+$batch[KIND] = BatchPrimitive;

package/src/batch/providers/BatchProvider.ts

@@ -213,13 +213,6 @@ export class BatchProvider {
     };
 
     // CAUTION: Do not log.debug/info here as it may cause infinite loops if logging is batched
-    // log.trace is safe
-
-    this.log.trace("Pushing item to batch", {
-      id,
-      partitionKey,
-      item,
-    });
 
     context.itemStates.set(id, itemState);
 

package/src/bucket/index.ts

@@ -1,17 +1,17 @@
 import { $module, type FileLike } from "alepha";
 import {
   $bucket,
-  type BucketDescriptor,
   type BucketFileOptions,
-} from "./descriptors/$bucket.ts";
+  type BucketPrimitive,
+} from "./primitives/$bucket.ts";
 import { FileStorageProvider } from "./providers/FileStorageProvider.ts";
 import { LocalFileStorageProvider } from "./providers/LocalFileStorageProvider.ts";
 import { MemoryFileStorageProvider } from "./providers/MemoryFileStorageProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export * from "./descriptors/$bucket.ts";
 export * from "./errors/FileNotFoundError.ts";
+export * from "./primitives/$bucket.ts";
 export * from "./providers/FileStorageProvider.ts";
 export * from "./providers/LocalFileStorageProvider.ts";
 export * from "./providers/MemoryFileStorageProvider.ts";
@@ -27,7 +27,7 @@ declare module "alepha" {
     "bucket:file:uploaded": {
       id: string;
       file: FileLike;
-      bucket: BucketDescriptor;
+      bucket: BucketPrimitive;
       options: BucketFileOptions;
     };
     /**
@@ -35,7 +35,7 @@ declare module "alepha" {
      */
     "bucket:file:deleted": {
       id: string;
-      bucket: BucketDescriptor;
+      bucket: BucketPrimitive;
     };
   }
 }
@@ -43,9 +43,9 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides file storage capabilities through declarative bucket descriptors with support for multiple storage backends.
+ * Provides file storage capabilities through declarative bucket primitives with support for multiple storage backends.
  *
- * The bucket module enables unified file operations across different storage systems using the `$bucket` descriptor
+ * The bucket module enables unified file operations across different storage systems using the `$bucket` primitive
  * on class properties. It abstracts storage provider differences, offering consistent APIs for local filesystem,
  * cloud storage, or in-memory storage for testing environments.
  *
@@ -55,18 +55,20 @@ declare module "alepha" {
  */
 export const AlephaBucket = $module({
   name: "alepha.bucket",
-  descriptors: [$bucket],
+  primitives: [$bucket],
   services: [
     FileStorageProvider,
     MemoryFileStorageProvider,
     LocalFileStorageProvider,
   ],
-  register: (alepha) =>
+  register: (alepha) => {
     alepha.with({
       optional: true,
       provide: FileStorageProvider,
-      use: alepha.isTest()
-        ? MemoryFileStorageProvider
-        : LocalFileStorageProvider,
-    }),
+      use:
+        alepha.isTest() || alepha.isServerless()
+          ? MemoryFileStorageProvider
+          : LocalFileStorageProvider,
+    });
+  },
 });

package/src/bucket/{descriptors → primitives}/$bucket.ts

@@ -1,9 +1,9 @@
 import {
   $inject,
-  createDescriptor,
-  Descriptor,
+  createPrimitive,
   type FileLike,
   KIND,
+  Primitive,
   type Service,
 } from "alepha";
 import { FileSystemProvider } from "alepha/file";
@@ -12,7 +12,7 @@ import { FileStorageProvider } from "../providers/FileStorageProvider.ts";
 import { MemoryFileStorageProvider } from "../providers/MemoryFileStorageProvider.ts";
 
 /**
- * Creates a bucket descriptor for file storage and management with configurable validation.
+ * Creates a bucket primitive for file storage and management with configurable validation.
  *
  * Provides a comprehensive file storage system that handles uploads, downloads, validation,
  * and management across multiple storage backends with MIME type and size limit controls.
@@ -60,10 +60,10 @@ import { MemoryFileStorageProvider } from "../providers/MemoryFileStorageProvide
  * }
  * ```
  */
-export const $bucket = (options: BucketDescriptorOptions) =>
-  createDescriptor(BucketDescriptor, options);
+export const $bucket = (options: BucketPrimitiveOptions) =>
+  createPrimitive(BucketPrimitive, options);
 
-export interface BucketDescriptorOptions extends BucketFileOptions {
+export interface BucketPrimitiveOptions extends BucketFileOptions {
   /**
    * File storage provider configuration for the bucket.
    *
@@ -204,7 +204,7 @@ export interface BucketFileOptions {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class BucketDescriptor extends Descriptor<BucketDescriptorOptions> {
+export class BucketPrimitive extends Primitive<BucketPrimitiveOptions> {
   public readonly provider = this.$provider();
   private readonly fileSystem = $inject(FileSystemProvider);
 
@@ -302,7 +302,7 @@ export class BucketDescriptor extends Descriptor<BucketDescriptorOptions> {
   }
 }
 
-$bucket[KIND] = BucketDescriptor;
+$bucket[KIND] = BucketPrimitive;
 
 // ---------------------------------------------------------------------------------------------------------------------
 

package/src/bucket/providers/LocalFileStorageProvider.ts

@@ -17,8 +17,8 @@ import {
 } from "alepha";
 import { FileDetector, FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
-import { $bucket } from "../descriptors/$bucket.ts";
 import { FileNotFoundError } from "../errors/FileNotFoundError.ts";
+import { $bucket } from "../primitives/$bucket.ts";
 import type { FileStorageProvider } from "./FileStorageProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -68,7 +68,7 @@ export class LocalFileStorageProvider implements FileStorageProvider {
         this.alepha.isTest() &&
         this.storagePath === localFileStorageOptions.options.default.storagePath
       ) {
-        this.alepha.state.set(localFileStorageOptions, {
+        this.alepha.store.set(localFileStorageOptions, {
           storagePath: join(tmpdir(), `alepha-test-${Date.now()}`),
         });
       }
@@ -82,7 +82,7 @@ export class LocalFileStorageProvider implements FileStorageProvider {
         await mkdir(this.storagePath, { recursive: true });
       } catch {}
 
-      for (const bucket of this.alepha.descriptors($bucket)) {
+      for (const bucket of this.alepha.primitives($bucket)) {
         if (bucket.provider !== this) {
           continue;
         }

package/src/cache/index.ts

@@ -1,11 +1,11 @@
 import { $module } from "alepha";
-import { $cache } from "./descriptors/$cache.ts";
+import { $cache } from "./primitives/$cache.ts";
 import { CacheProvider } from "./providers/CacheProvider.ts";
 import { MemoryCacheProvider } from "./providers/MemoryCacheProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export * from "./descriptors/$cache.ts";
+export * from "./primitives/$cache.ts";
 export * from "./providers/CacheProvider.ts";
 export * from "./providers/MemoryCacheProvider.ts";
 
@@ -14,7 +14,7 @@ export * from "./providers/MemoryCacheProvider.ts";
 /**
  * Provides high-performance caching capabilities for Alepha applications with configurable TTL and multiple storage backends.
  *
- * The cache module enables declarative caching through the `$cache` descriptor, allowing you to cache method results,
+ * The cache module enables declarative caching through the `$cache` primitive, allowing you to cache method results,
  * API responses, or computed values with automatic invalidation and type safety. It supports both in-memory and
  * persistent storage backends for different performance and durability requirements.
  *
@@ -24,7 +24,7 @@ export * from "./providers/MemoryCacheProvider.ts";
  */
 export const AlephaCache = $module({
   name: "alepha.cache",
-  descriptors: [$cache],
+  primitives: [$cache],
   services: [CacheProvider, MemoryCacheProvider],
   register: (alepha) =>
     alepha.with({

package/src/cache/{descriptors → primitives}/$cache.ts

@@ -1,10 +1,10 @@
 import {
   $env,
   $inject,
-  createDescriptor,
-  Descriptor,
+  createPrimitive,
   type InstantiableClass,
   KIND,
+  Primitive,
   t,
 } from "alepha";
 import { DateTimeProvider, type DurationLike } from "alepha/datetime";
@@ -13,7 +13,7 @@ import { CacheProvider } from "../providers/CacheProvider.ts";
 import { MemoryCacheProvider } from "../providers/MemoryCacheProvider.ts";
 
 /**
- * Creates a cache descriptor for high-performance data caching with automatic management.
+ * Creates a cache primitive for high-performance data caching with automatic management.
  *
  * Provides a caching layer that improves application performance by storing frequently accessed
  * data in memory or external stores like Redis, with support for both function result caching
@@ -61,14 +61,14 @@ import { MemoryCacheProvider } from "../providers/MemoryCacheProvider.ts";
  * ```
  */
 export const $cache = <TReturn = string, TParameter extends any[] = any[]>(
-  options: CacheDescriptorOptions<TReturn, TParameter> = {},
-): CacheDescriptorFn<TReturn, TParameter> => {
-  const instance = createDescriptor(
-    CacheDescriptor<TReturn, TParameter>,
+  options: CachePrimitiveOptions<TReturn, TParameter> = {},
+): CachePrimitiveFn<TReturn, TParameter> => {
+  const instance = createPrimitive(
+    CachePrimitive<TReturn, TParameter>,
     options,
   );
   const fn = (...args: TParameter): Promise<TReturn> => instance.run(...args);
-  return Object.setPrototypeOf(fn, instance) as CacheDescriptorFn<
+  return Object.setPrototypeOf(fn, instance) as CachePrimitiveFn<
     TReturn,
     TParameter
   >;
@@ -76,7 +76,7 @@ export const $cache = <TReturn = string, TParameter extends any[] = any[]>(
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface CacheDescriptorOptions<
+export interface CachePrimitiveOptions<
   TReturn = any,
   TParameter extends any[] = any[],
 > {
@@ -130,10 +130,10 @@ const envSchema = t.object({
   }),
 });
 
-export class CacheDescriptor<
+export class CachePrimitive<
   TReturn = any,
   TParameter extends any[] = any[],
-> extends Descriptor<CacheDescriptorOptions<TReturn, TParameter>> {
+> extends Primitive<CachePrimitiveOptions<TReturn, TParameter>> {
   protected readonly env = $env(envSchema);
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
   protected readonly provider = this.$provider();
@@ -277,14 +277,14 @@ export class CacheDescriptor<
   }
 }
 
-export interface CacheDescriptorFn<
+export interface CachePrimitiveFn<
   TReturn = any,
   TParameter extends any[] = any[],
-> extends CacheDescriptor<TReturn, TParameter> {
+> extends CachePrimitive<TReturn, TParameter> {
   /**
-   * Run the cache descriptor with the provided arguments.
+   * Run the cache primitive with the provided arguments.
    */
   (...args: TParameter): Promise<TReturn>;
 }
 
-$cache[KIND] = CacheDescriptor;
+$cache[KIND] = CachePrimitive;

package/src/cli/apps/AlephaCli.ts

@@ -1,4 +1,6 @@
-import { $module } from "alepha";
+import { join } from "node:path";
+import { $hook, $inject, $module, Alepha } from "alepha";
+import { FileSystemProvider } from "alepha/file";
 import { BiomeCommands } from "../commands/BiomeCommands.ts";
 import { CoreCommands } from "../commands/CoreCommands.ts";
 import { DrizzleCommands } from "../commands/DrizzleCommands.ts";
@@ -6,9 +8,33 @@ import { VerifyCommands } from "../commands/VerifyCommands.ts";
 import { ViteCommands } from "../commands/ViteCommands.ts";
 import { ProcessRunner } from "../services/ProcessRunner.ts";
 
+class AlephaCliExtension {
+  protected readonly alepha = $inject(Alepha);
+  protected readonly fs = $inject(FileSystemProvider);
+  protected readonly onConfigure = $hook({
+    on: "configure",
+    handler: async () => {
+      const extensionPath = join(process.cwd(), "alepha.config.ts");
+      const hasExtension = await this.fs.exists(extensionPath);
+      if (!hasExtension) {
+        return;
+      }
+
+      // import
+      const { default: Extension } = await import(extensionPath);
+      if (typeof Extension !== "function") {
+        return;
+      }
+
+      this.alepha.with(Extension);
+    },
+  });
+}
+
 export const AlephaCli = $module({
   name: "alepha.cli",
   services: [
+    AlephaCliExtension,
     ProcessRunner,
     CoreCommands,
     DrizzleCommands,

package/src/cli/apps/AlephaPackageBuilderCli.ts

@@ -9,6 +9,7 @@ import type { InlineConfig } from "tsdown";
 interface Module {
   name: string;
   dependencies: string[];
+  native?: boolean;
   browser?: boolean;
   node?: boolean;
 }
@@ -41,11 +42,20 @@ export class AlephaPackageBuilderCli {
         pkgData.exports[path] = {};
         // order is important here for compatibility
         pkgData.exports[path].types = `./src/${item.name}/index.ts`;
+        if (item.native) {
+          pkgData.exports[path]["react-native"] =
+            `./src/${item.name}/index.native.ts`;
+        } else if (item.browser) {
+          pkgData.exports[path]["react-native"] =
+            `./src/${item.name}/index.browser.ts`;
+        }
+
         if (item.browser) {
           pkgData.exports[path].browser = `./src/${item.name}/index.browser.ts`;
         }
+
         pkgData.exports[path].import = `./src/${item.name}/index.ts`;
-        pkgData.exports[path].require = `./src/${item.name}/index.ts`;
+        pkgData.exports[path].default = `./src/${item.name}/index.ts`;
       }
 
       if (packageName === "alepha") {
@@ -70,7 +80,9 @@ export class AlephaPackageBuilderCli {
       const external = [
         "alepha",
         packageName,
-        ...modules.map((item) => `${packageName}/${item.name}`),
+        ...modules.map(
+          (item) => `${packageName}/${item.name.replace("-", "/")}`,
+        ),
       ];
 
       await run.rm(this.dist);
@@ -90,6 +102,17 @@ export class AlephaPackageBuilderCli {
           external,
         });
 
+        if (item.native) {
+          entries.push({
+            entry: join(src, "index.native.ts"),
+            outDir: dest,
+            platform: "neutral",
+            sourcemap: true,
+            dts: false,
+            external,
+          });
+        }
+
         if (item.browser) {
           entries.push({
             entry: join(src, "index.browser.ts"),
@@ -244,6 +267,7 @@ export async function analyzeModules(
 
       // Check for browser/node entry points
       const hasBrowser = await fileExists(join(modulePath, "index.browser.ts"));
+      const hasNative = await fileExists(join(modulePath, "index.native.ts"));
       const hasNode = await fileExists(join(modulePath, "index.node.ts"));
 
       // Get all .ts/.tsx files in this module
@@ -276,6 +300,7 @@ export async function analyzeModules(
         dependencies: Array.from(dependencies),
       };
 
+      if (hasNative) module.native = true;
       if (hasBrowser) module.browser = true;
       if (hasNode) module.node = true;
 

package/src/cli/commands/CoreCommands.ts

@@ -62,11 +62,15 @@ export class CoreCommands {
       react: t.optional(
         t.boolean({ description: "Include Alepha React dependencies" }),
       ),
-      admin: t.optional(
-        t.boolean({ description: "Include Alepha admin panel dependencies" }),
+      ui: t.optional(
+        t.boolean({ description: "Include Alepha UI dependencies" }),
       ),
     }),
     handler: async ({ run, flags, root }) => {
+      if (flags.ui) {
+        flags.react = true;
+      }
+
       await run({
         name: "Ensuring configuration files",
         handler: async () => {

package/src/cli/commands/DrizzleCommands.ts

@@ -49,8 +49,8 @@ export class DrizzleCommands {
         alepha.inject<DrizzleKitProvider>("DrizzleKitProvider");
       const accepted = new Set<string>([]);
 
-      for (const descriptor of repositoryProvider.getRepositories()) {
-        const provider = descriptor.provider;
+      for (const primitive of repositoryProvider.getRepositories()) {
+        const provider = primitive.provider;
         const providerName = provider.name;
         if (accepted.has(providerName)) {
           continue;
@@ -124,7 +124,7 @@ export class DrizzleCommands {
    * Generate database migration files
    *
    * - Loads the Alepha instance from the specified entry file.
-   * - Retrieves all repository descriptors to gather database models.
+   * - Retrieves all repository primitives to gather database models.
    * - Creates temporary entity definitions based on the current database schema.
    * - Writes these definitions to a temporary schema file. (node_modules/.db/entities.ts)
    * - Invokes Drizzle Kit's CLI to generate migration files based on the current schema.
@@ -167,7 +167,7 @@ export class DrizzleCommands {
    * Push database schema changes directly to the database
    *
    * - Loads the Alepha instance from the specified entry file.
-   * - Retrieves all repository descriptors to gather database models.
+   * - Retrieves all repository primitives to gather database models.
    * - Creates temporary entity definitions and Drizzle config.
    * - Invokes Drizzle Kit's push command to apply schema changes directly.
    */
@@ -198,7 +198,7 @@ export class DrizzleCommands {
    * Apply pending database migrations
    *
    * - Loads the Alepha instance from the specified entry file.
-   * - Retrieves all repository descriptors to gather database models.
+   * - Retrieves all repository primitives to gather database models.
    * - Creates temporary entity definitions and Drizzle config.
    * - Invokes Drizzle Kit's migrate command to apply pending migrations.
    */
@@ -229,7 +229,7 @@ export class DrizzleCommands {
    * Launch Drizzle Studio database browser
    *
    * - Loads the Alepha instance from the specified entry file.
-   * - Retrieves all repository descriptors to gather database models.
+   * - Retrieves all repository primitives to gather database models.
    * - Creates temporary entity definitions and Drizzle config.
    * - Invokes Drizzle Kit's studio command to launch the web-based database browser.
    */

package/src/cli/commands/VerifyCommands.ts

@@ -35,7 +35,7 @@ export class VerifyCommands {
         await run("alepha test");
       }
 
-      if (await this.utils.hasDir(root, "migrations")) {
+      if (await this.utils.exists(root, "migrations")) {
         await run("alepha db:check-migrations");
       }
 

package/src/cli/commands/ViteCommands.ts

@@ -68,7 +68,12 @@ export class ViteCommands {
         await access(join(root, "index.html"));
       } catch {
         this.log.trace("No index.html found, running entry file with tsx");
-        await this.runner.exec(`tsx watch ${entry}`);
+        let cmd = "tsx --watch";
+        if (await this.utils.exists(root, ".env")) {
+          cmd += ` --env-file=./.env`;
+        }
+        cmd += ` ${entry}`;
+        await this.runner.exec(cmd);
         return;
       }
 
@@ -140,6 +145,7 @@ export class ViteCommands {
         ] ?? {};
 
       const stats = flags.stats ?? viteAlephaBuildOptions.stats ?? false;
+      const hasServer = viteAlephaBuildOptions.serverEntry !== false;
 
       let hasClient = false;
       try {
@@ -184,7 +190,7 @@ export class ViteCommands {
           });
 
           // Server will handle index.html if both client & server are built
-          if (clientBuilt) {
+          if (clientBuilt && hasServer) {
             await unlink(`${distDir}/${clientDir}/index.html`);
           }
         },