alepha 0.13.1 → 0.13.3

package/src/queue/{descriptors → primitives}/$consumer.ts

@@ -1,21 +1,21 @@
 import {
-  createDescriptor,
-  Descriptor,
+  createPrimitive,
   KIND,
+  Primitive,
   type Static,
   type TSchema,
 } from "alepha";
-import type { QueueDescriptor } from "./$queue.ts";
+import type { QueuePrimitive } from "./$queue.ts";
 
 /**
- * Creates a consumer descriptor to process messages from a specific queue.
+ * Creates a consumer primitive to process messages from a specific queue.
  *
  * Provides a dedicated message consumer that connects to a queue and processes messages
  * with custom handler logic, enabling scalable architectures where multiple consumers
  * can process messages from the same queue.
  *
  * **Key Features**
- * - Seamless integration with any $queue descriptor
+ * - Seamless integration with any $queue primitive
  * - Full type safety inherited from queue schema
  * - Automatic worker management for background processing
  * - Built-in error handling and retry mechanisms
@@ -57,16 +57,16 @@ import type { QueueDescriptor } from "./$queue.ts";
  * ```
  */
 export const $consumer = <T extends TSchema>(
-  options: ConsumerDescriptorOptions<T>,
-): ConsumerDescriptor<T> => {
-  return createDescriptor(ConsumerDescriptor<T>, options);
+  options: ConsumerPrimitiveOptions<T>,
+): ConsumerPrimitive<T> => {
+  return createPrimitive(ConsumerPrimitive<T>, options);
 };
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface ConsumerDescriptorOptions<T extends TSchema> {
+export interface ConsumerPrimitiveOptions<T extends TSchema> {
   /**
-   * The queue descriptor that this consumer will process messages from.
+   * The queue primitive that this consumer will process messages from.
    *
    * This establishes the connection between the consumer and its source queue:
    * - The consumer inherits the queue's message schema for type safety
@@ -90,12 +90,12 @@ export interface ConsumerDescriptorOptions<T extends TSchema> {
    *
    * // Then, create a consumer for that queue
    * emailConsumer = $consumer({
-   *   queue: this.emailQueue,  // Reference the queue descriptor
+   *   queue: this.emailQueue,  // Reference the queue primitive
    *   handler: async (message) => { } // process email
    * });
    * ```
    */
-  queue: QueueDescriptor<T>;
+  queue: QueuePrimitive<T>;
 
   /**
    * Message handler function that processes individual messages from the queue.
@@ -175,8 +175,8 @@ export interface ConsumerDescriptorOptions<T extends TSchema> {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class ConsumerDescriptor<T extends TSchema> extends Descriptor<
-  ConsumerDescriptorOptions<T>
+export class ConsumerPrimitive<T extends TSchema> extends Primitive<
+  ConsumerPrimitiveOptions<T>
 > {}
 
-$consumer[KIND] = ConsumerDescriptor;
+$consumer[KIND] = ConsumerPrimitive;

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

@@ -1,7 +1,7 @@
 import {
-  createDescriptor,
-  Descriptor,
+  createPrimitive,
   KIND,
+  Primitive,
   type Service,
   type Static,
   type TSchema,
@@ -15,9 +15,9 @@ import { MemoryQueueProvider } from "../providers/MemoryQueueProvider.ts";
 import { QueueProvider } from "../providers/QueueProvider.ts";
 
 /**
- * Creates a queue descriptor for asynchronous message processing with background workers.
+ * Creates a queue primitive for asynchronous message processing with background workers.
  *
- * The $queue descriptor enables powerful asynchronous communication patterns in your application.
+ * The $queue primitive enables powerful asynchronous communication patterns in your application.
  * It provides type-safe message queuing with automatic worker processing, making it perfect for
  * decoupling components and handling background tasks efficiently.
  *
@@ -126,14 +126,14 @@ import { QueueProvider } from "../providers/QueueProvider.ts";
  * ```
  */
 export const $queue = <T extends TSchema>(
-  options: QueueDescriptorOptions<T>,
-): QueueDescriptor<T> => {
-  return createDescriptor(QueueDescriptor<T>, options);
+  options: QueuePrimitiveOptions<T>,
+): QueuePrimitive<T> => {
+  return createPrimitive(QueuePrimitive<T>, options);
 };
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface QueueDescriptorOptions<T extends TSchema> {
+export interface QueuePrimitiveOptions<T extends TSchema> {
   /**
    * Unique name for the queue.
    *
@@ -337,8 +337,8 @@ export interface QueueDescriptorOptions<T extends TSchema> {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class QueueDescriptor<T extends TSchema> extends Descriptor<
-  QueueDescriptorOptions<T>
+export class QueuePrimitive<T extends TSchema> extends Primitive<
+  QueuePrimitiveOptions<T>
 > {
   protected readonly log = $logger();
   public readonly provider = this.$provider();
@@ -415,7 +415,7 @@ export class QueueDescriptor<T extends TSchema> extends Descriptor<
   }
 
   /**
-   * Get default job options from descriptor configuration.
+   * Get default job options from primitive configuration.
    */
   protected getDefaultJobOptions() {
     return {
@@ -442,7 +442,7 @@ export class QueueDescriptor<T extends TSchema> extends Descriptor<
   }
 }
 
-$queue[KIND] = QueueDescriptor;
+$queue[KIND] = QueuePrimitive;
 
 // ---------------------------------------------------------------------------------------------------------------------
 

package/src/queue/providers/WorkerProvider.ts

@@ -9,13 +9,13 @@ import {
 } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
-import { $consumer } from "../descriptors/$consumer.ts";
+import type { QueueAcquiredJob } from "../interfaces/QueueJob.ts";
+import { $consumer } from "../primitives/$consumer.ts";
 import {
   $queue,
-  type QueueDescriptor,
   type QueueMessage,
-} from "../descriptors/$queue.ts";
-import type { QueueAcquiredJob } from "../interfaces/QueueJob.ts";
+  type QueuePrimitive,
+} from "../primitives/$queue.ts";
 import { QueueProvider } from "./QueueProvider.ts";
 
 const envSchema = t.object({
@@ -83,7 +83,7 @@ export class WorkerProvider {
     on: "start",
     priority: "last",
     handler: () => {
-      for (const queue of this.alepha.descriptors($queue)) {
+      for (const queue of this.alepha.primitives($queue)) {
         const handler = queue.options.handler;
         if (handler) {
           this.consumers.push({
@@ -93,7 +93,7 @@ export class WorkerProvider {
         }
       }
 
-      for (const consumer of this.alepha.descriptors($consumer)) {
+      for (const consumer of this.alepha.primitives($consumer)) {
         this.consumers.push(consumer.options);
       }
 
@@ -333,7 +333,7 @@ export class WorkerProvider {
 }
 
 export interface Consumer<T extends TSchema = TSchema> {
-  queue: QueueDescriptor<T>;
+  queue: QueuePrimitive<T>;
   handler: (message: QueueMessage<T>) => Promise<void>;
 }
 

package/src/retry/index.ts

@@ -1,12 +1,12 @@
 import { $module } from "alepha";
-import { $retry } from "./descriptors/$retry.ts";
+import { $retry } from "./primitives/$retry.ts";
 import { RetryProvider } from "./providers/RetryProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export * from "./descriptors/$retry.ts";
 export * from "./errors/RetryCancelError.ts";
 export * from "./errors/RetryTimeoutError.ts";
+export * from "./primitives/$retry.ts";
 export * from "./providers/RetryProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -19,6 +19,6 @@ export * from "./providers/RetryProvider.ts";
  */
 export const AlephaRetry = $module({
   name: "alepha.retry",
-  descriptors: [$retry],
+  primitives: [$retry],
   services: [RetryProvider],
 });

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

@@ -1,9 +1,9 @@
 import {
   $inject,
-  createDescriptor,
-  Descriptor,
-  type DescriptorArgs,
+  createPrimitive,
   KIND,
+  Primitive,
+  type PrimitiveArgs,
 } from "alepha";
 import type { DurationLike } from "alepha/datetime";
 import type { RetryBackoffOptions } from "../providers/RetryProvider.ts";
@@ -14,16 +14,16 @@ import { RetryProvider } from "../providers/RetryProvider.ts";
  * with support for exponential backoff, max duration, and cancellation.
  */
 export const $retry = <T extends (...args: any[]) => any>(
-  options: RetryDescriptorOptions<T>,
-): RetryDescriptorFn<T> => {
-  const instance = createDescriptor(RetryDescriptor, options);
+  options: RetryPrimitiveOptions<T>,
+): RetryPrimitiveFn<T> => {
+  const instance = createPrimitive(RetryPrimitive, options);
   const fn = (...args: Parameters<T>) => instance.run(...args);
-  return Object.setPrototypeOf(fn, instance) as RetryDescriptorFn<T>;
+  return Object.setPrototypeOf(fn, instance) as RetryPrimitiveFn<T>;
 };
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface RetryDescriptorOptions<T extends (...args: any[]) => any> {
+export interface RetryPrimitiveOptions<T extends (...args: any[]) => any> {
   /**
    * The function to retry.
    */
@@ -72,13 +72,13 @@ export interface RetryDescriptorOptions<T extends (...args: any[]) => any> {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class RetryDescriptor<
+export class RetryPrimitive<
   T extends (...args: any[]) => any,
-> extends Descriptor<RetryDescriptorOptions<T>> {
+> extends Primitive<RetryPrimitiveOptions<T>> {
   protected readonly retryProvider = $inject(RetryProvider);
   protected appAbortController?: AbortController;
 
-  constructor(args: DescriptorArgs<RetryDescriptorOptions<T>>) {
+  constructor(args: PrimitiveArgs<RetryPrimitiveOptions<T>>) {
     super(args);
 
     this.alepha.events.on("stop", () => {
@@ -100,9 +100,9 @@ export class RetryDescriptor<
   }
 }
 
-export interface RetryDescriptorFn<T extends (...args: any[]) => any>
-  extends RetryDescriptor<T> {
+export interface RetryPrimitiveFn<T extends (...args: any[]) => any>
+  extends RetryPrimitive<T> {
   (...args: Parameters<T>): Promise<ReturnType<T>>;
 }
 
-$retry[KIND] = RetryDescriptor;
+$retry[KIND] = RetryPrimitive;

package/src/scheduler/index.ts

@@ -1,13 +1,13 @@
 import { $module } from "alepha";
 import type { DateTime } from "alepha/datetime";
 import { AlephaLock } from "alepha/lock";
-import { $scheduler } from "./descriptors/$scheduler.ts";
+import { $scheduler } from "./primitives/$scheduler.ts";
 import { CronProvider } from "./providers/CronProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 export * from "./constants/CRON.ts";
-export * from "./descriptors/$scheduler.ts";
+export * from "./primitives/$scheduler.ts";
 export * from "./providers/CronProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -42,6 +42,6 @@ declare module "alepha" {
  */
 export const AlephaScheduler = $module({
   name: "alepha.scheduler",
-  descriptors: [$scheduler],
+  primitives: [$scheduler],
   services: [AlephaLock, CronProvider],
 });

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

@@ -3,9 +3,9 @@ import {
   $inject,
   Alepha,
   type Async,
-  createDescriptor,
-  Descriptor,
+  createPrimitive,
   KIND,
+  Primitive,
   type Static,
   t,
 } from "alepha";
@@ -19,17 +19,17 @@ import { $logger } from "alepha/logger";
 import { CronProvider } from "../providers/CronProvider.ts";
 
 /**
- * Scheduler descriptor.
+ * Scheduler primitive.
  */
 export const $scheduler = (
-  options: SchedulerDescriptorOptions,
-): SchedulerDescriptor => {
-  return createDescriptor(SchedulerDescriptor, options);
+  options: SchedulerPrimitiveOptions,
+): SchedulerPrimitive => {
+  return createPrimitive(SchedulerPrimitive, options);
 };
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export type SchedulerDescriptorOptions = {
+export type SchedulerPrimitiveOptions = {
   /**
    * Function to run on schedule.
    */
@@ -78,7 +78,7 @@ declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
 }
 
-export class SchedulerDescriptor extends Descriptor<SchedulerDescriptorOptions> {
+export class SchedulerPrimitive extends Primitive<SchedulerPrimitiveOptions> {
   protected readonly log = $logger();
   protected readonly env = $env(envSchema);
   protected readonly alepha = $inject(Alepha);
@@ -186,7 +186,7 @@ export class SchedulerDescriptor extends Descriptor<SchedulerDescriptorOptions>
   });
 }
 
-$scheduler[KIND] = SchedulerDescriptor;
+$scheduler[KIND] = SchedulerPrimitive;
 
 // ---------------------------------------------------------------------------------------------------------------------
 

package/src/scheduler/providers/CronProvider.ts

@@ -74,7 +74,7 @@ export class CronProvider {
   /**
    * Registers a cron job.
    *
-   * It's automatically done when using the `$scheduler` descriptor but can also be used manually.
+   * It's automatically done when using the `$scheduler` primitive but can also be used manually.
    */
   public createCronJob(
     name: string,

package/src/security/index.ts

@@ -1,20 +1,20 @@
 import { $module } from "alepha";
-import { $permission } from "./descriptors/$permission.ts";
-import { $realm } from "./descriptors/$realm.ts";
-import { $role } from "./descriptors/$role.ts";
+import { $permission } from "./primitives/$permission.ts";
+import { $realm } from "./primitives/$realm.ts";
+import { $role } from "./primitives/$role.ts";
 import { CryptoProvider } from "./providers/CryptoProvider.ts";
 import { JwtProvider } from "./providers/JwtProvider.ts";
 import { SecurityProvider } from "./providers/SecurityProvider.ts";
 import type { UserAccount } from "./schemas/userAccountInfoSchema.ts";
 
-export * from "./descriptors/$permission.ts";
-export * from "./descriptors/$realm.ts";
-export * from "./descriptors/$role.ts";
-export * from "./descriptors/$serviceAccount.ts";
 export * from "./errors/InvalidCredentialsError.ts";
 export * from "./errors/InvalidPermissionError.ts";
 export * from "./errors/SecurityError.ts";
 export * from "./interfaces/UserAccountToken.ts";
+export * from "./primitives/$permission.ts";
+export * from "./primitives/$realm.ts";
+export * from "./primitives/$role.ts";
+export * from "./primitives/$serviceAccount.ts";
 export * from "./providers/CryptoProvider.ts";
 export * from "./providers/JwtProvider.ts";
 export * from "./providers/SecurityProvider.ts";
@@ -34,7 +34,7 @@ declare module "alepha" {
 /**
  * Provides comprehensive authentication and authorization capabilities with JWT tokens, role-based access control, and user management.
  *
- * The security module enables building secure applications using descriptors like `$realm`, `$role`, and `$permission`
+ * The security module enables building secure applications using primitives like `$realm`, `$role`, and `$permission`
  * on class properties. It offers JWT-based authentication, fine-grained permissions, service accounts, and seamless
  * integration with various authentication providers and user management systems.
  *
@@ -45,6 +45,6 @@ declare module "alepha" {
  */
 export const AlephaSecurity = $module({
   name: "alepha.security",
-  descriptors: [$realm, $role, $permission],
+  primitives: [$realm, $role, $permission],
   services: [SecurityProvider, JwtProvider, CryptoProvider],
 });

package/src/security/{descriptors → primitives}/$permission.ts

@@ -1,4 +1,4 @@
-import { $inject, createDescriptor, Descriptor, KIND } from "alepha";
+import { $inject, createPrimitive, KIND, Primitive } from "alepha";
 import { SecurityProvider } from "../providers/SecurityProvider.ts";
 import type { UserAccount } from "../schemas/userAccountInfoSchema.ts";
 
@@ -6,14 +6,14 @@ import type { UserAccount } from "../schemas/userAccountInfoSchema.ts";
  * Create a new permission.
  */
 export const $permission = (
-  options: PermissionDescriptorOptions = {},
-): PermissionDescriptor => {
-  return createDescriptor(PermissionDescriptor, options);
+  options: PermissionPrimitiveOptions = {},
+): PermissionPrimitive => {
+  return createPrimitive(PermissionPrimitive, options);
 };
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface PermissionDescriptorOptions {
+export interface PermissionPrimitiveOptions {
   /**
    * Name of the permission. Use Property name is not provided.
    */
@@ -32,7 +32,7 @@ export interface PermissionDescriptorOptions {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class PermissionDescriptor extends Descriptor<PermissionDescriptorOptions> {
+export class PermissionPrimitive extends Primitive<PermissionPrimitiveOptions> {
   protected readonly securityProvider = $inject(SecurityProvider);
 
   public get name(): string {
@@ -67,4 +67,4 @@ export class PermissionDescriptor extends Descriptor<PermissionDescriptorOptions
   }
 }
 
-$permission[KIND] = PermissionDescriptor;
+$permission[KIND] = PermissionPrimitive;

package/src/security/{descriptors → primitives}/$realm.ts

@@ -1,10 +1,4 @@
-import {
-  $inject,
-  AlephaError,
-  createDescriptor,
-  Descriptor,
-  KIND,
-} from "alepha";
+import { $inject, AlephaError, createPrimitive, KIND, Primitive } from "alepha";
 import {
   DateTimeProvider,
   type Duration,
@@ -21,13 +15,13 @@ import type { UserAccount } from "../schemas/userAccountInfoSchema.ts";
 /**
  * Create a new realm.
  */
-export const $realm = (options: RealmDescriptorOptions): RealmDescriptor => {
-  return createDescriptor(RealmDescriptor, options);
+export const $realm = (options: RealmPrimitiveOptions): RealmPrimitive => {
+  return createPrimitive(RealmPrimitive, options);
 };
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export type RealmDescriptorOptions = {
+export type RealmPrimitiveOptions = {
   /**
    * Define the realm name.
    * If not provided, it will use the property key.
@@ -109,7 +103,7 @@ export interface RealmExternal {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export class RealmDescriptor extends Descriptor<RealmDescriptorOptions> {
+export class RealmPrimitive extends Primitive<RealmPrimitiveOptions> {
   protected readonly securityProvider = $inject(SecurityProvider);
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
   protected readonly jwt = $inject(JwtProvider);
@@ -342,7 +336,7 @@ export class RealmDescriptor extends Descriptor<RealmDescriptorOptions> {
   }
 }
 
-$realm[KIND] = RealmDescriptor;
+$realm[KIND] = RealmPrimitive;
 
 // ---------------------------------------------------------------------------------------------------------------------
 

package/src/security/{descriptors → primitives}/$role.ts

@@ -1,18 +1,18 @@
-import { $inject, createDescriptor, Descriptor, KIND } from "alepha";
+import { $inject, createPrimitive, KIND, Primitive } from "alepha";
 import { SecurityProvider } from "../providers/SecurityProvider.ts";
-import type { PermissionDescriptor } from "./$permission.ts";
-import type { RealmDescriptor } from "./$realm.ts";
+import type { PermissionPrimitive } from "./$permission.ts";
+import type { RealmPrimitive } from "./$realm.ts";
 
 /**
  * Create a new role.
  */
-export const $role = (options: RoleDescriptorOptions = {}): RoleDescriptor => {
-  return createDescriptor(RoleDescriptor, options);
+export const $role = (options: RolePrimitiveOptions = {}): RolePrimitive => {
+  return createPrimitive(RolePrimitive, options);
 };
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface RoleDescriptorOptions {
+export interface RolePrimitiveOptions {
   /**
    * Name of the role.
    */
@@ -23,7 +23,7 @@ export interface RoleDescriptorOptions {
    */
   description?: string;
 
-  realm?: string | RealmDescriptor;
+  realm?: string | RealmPrimitive;
 
   permissions?: Array<
     | string
@@ -35,7 +35,7 @@ export interface RoleDescriptorOptions {
   >;
 }
 
-export class RoleDescriptor extends Descriptor<RoleDescriptorOptions> {
+export class RolePrimitive extends Primitive<RolePrimitiveOptions> {
   protected readonly securityProvider = $inject(SecurityProvider);
 
   public get name(): string {
@@ -62,19 +62,19 @@ export class RoleDescriptor extends Descriptor<RoleDescriptorOptions> {
   /**
    * Get the realm of the role.
    */
-  public get realm(): string | RealmDescriptor | undefined {
+  public get realm(): string | RealmPrimitive | undefined {
     return this.options.realm;
   }
 
-  public can(permission: string | PermissionDescriptor): boolean {
+  public can(permission: string | PermissionPrimitive): boolean {
     return this.securityProvider.can(this.name, permission);
   }
 
-  public check(permission: string | PermissionDescriptor) {
+  public check(permission: string | PermissionPrimitive) {
     return this.securityProvider.checkPermission(permission, this.name);
   }
 }
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-$role[KIND] = RoleDescriptor;
+$role[KIND] = RolePrimitive;

package/src/security/{descriptors → primitives}/$serviceAccount.ts

@@ -1,7 +1,7 @@
 import { $context } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import type { UserAccount } from "../schemas/userAccountInfoSchema.ts";
-import type { AccessTokenResponse, RealmDescriptor } from "./$realm.ts";
+import type { AccessTokenResponse, RealmPrimitive } from "./$realm.ts";
 
 /**
  * Allow to get an access token for a service account.
@@ -32,8 +32,8 @@ import type { AccessTokenResponse, RealmDescriptor } from "./$realm.ts";
  * ```
  */
 export const $serviceAccount = (
-  options: ServiceAccountDescriptorOptions,
-): ServiceAccountDescriptor => {
+  options: ServiceAccountPrimitiveOptions,
+): ServiceAccountPrimitive => {
   const { alepha } = $context();
   const store: {
     cache?: AccessTokenResponse;
@@ -150,19 +150,19 @@ export const $serviceAccount = (
   };
 };
 
-export type ServiceAccountDescriptorOptions = {
+export type ServiceAccountPrimitiveOptions = {
   gracePeriod?: number; // Grace period in milliseconds before token expiration
 } & (
   | {
-      oauth2: Oauth2ServiceAccountDescriptorOptions;
+      oauth2: Oauth2ServiceAccountPrimitiveOptions;
     }
   | {
-      realm: RealmDescriptor;
+      realm: RealmPrimitive;
       user: UserAccount;
     }
 );
 
-export interface Oauth2ServiceAccountDescriptorOptions {
+export interface Oauth2ServiceAccountPrimitiveOptions {
   /**
    * Get Token URL.
    */
@@ -179,7 +179,7 @@ export interface Oauth2ServiceAccountDescriptorOptions {
   clientSecret: string;
 }
 
-export interface ServiceAccountDescriptor {
+export interface ServiceAccountPrimitive {
   token: () => Promise<string>;
 }
 

package/src/server/index.browser.ts

@@ -9,6 +9,6 @@ export * from "./index.shared.ts";
 
 export const AlephaServer = $module({
   name: "alepha.server",
-  descriptors: [],
+  primitives: [],
   services: [HttpClient],
 });