alepha 0.13.0 → 0.13.2

package/src/server-proxy/index.ts

@@ -1,11 +1,11 @@
 import { $module } from "alepha";
 import { AlephaServer } from "alepha/server";
-import { $proxy } from "./descriptors/$proxy.ts";
+import { $proxy } from "./primitives/$proxy.ts";
 import { ServerProxyProvider } from "./providers/ServerProxyProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export * from "./descriptors/$proxy.ts";
+export * from "./primitives/$proxy.ts";
 export * from "./providers/ServerProxyProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -18,6 +18,6 @@ export * from "./providers/ServerProxyProvider.ts";
  */
 export const AlephaServerProxy = $module({
   name: "alepha.server.proxy",
-  descriptors: [$proxy],
+  primitives: [$proxy],
   services: [AlephaServer, ServerProxyProvider],
 });

package/src/server-proxy/{descriptors → primitives}/$proxy.ts

@@ -1,10 +1,10 @@
-import { type Async, createDescriptor, Descriptor, KIND } from "alepha";
+import { type Async, createPrimitive, KIND, Primitive } from "alepha";
 import type { ServerRequest } from "alepha/server";
 
 /**
- * Creates a proxy descriptor to forward requests to another server.
+ * Creates a proxy primitive to forward requests to another server.
  *
- * This descriptor enables you to create reverse proxy functionality, allowing your Alepha server
+ * This primitive enables you to create reverse proxy functionality, allowing your Alepha server
  * to forward requests to other services while maintaining a unified API surface. It's particularly
  * useful for microservice architectures, API gateways, or when you need to aggregate multiple
  * services behind a single endpoint.
@@ -84,11 +84,11 @@ import type { ServerRequest } from "alepha/server";
  * }
  * ```
  */
-export const $proxy = (options: ProxyDescriptorOptions): ProxyDescriptor => {
-  return createDescriptor(ProxyDescriptor, options);
+export const $proxy = (options: ProxyPrimitiveOptions): ProxyPrimitive => {
+  return createPrimitive(ProxyPrimitive, options);
 };
 
-export type ProxyDescriptorOptions = {
+export type ProxyPrimitiveOptions = {
   /**
    * Path pattern to match for proxying requests.
    *
@@ -219,6 +219,6 @@ export type ProxyDescriptorOptions = {
   // retry?: RetryOptions;
 };
 
-export class ProxyDescriptor extends Descriptor<ProxyDescriptorOptions> {}
+export class ProxyPrimitive extends Primitive<ProxyPrimitiveOptions> {}
 
-$proxy[KIND] = ProxyDescriptor;
+$proxy[KIND] = ProxyPrimitive;

package/src/server-proxy/providers/ServerProxyProvider.ts

@@ -7,7 +7,7 @@ import {
   type ServerRequest,
   ServerRouterProvider,
 } from "alepha/server";
-import { $proxy, type ProxyDescriptorOptions } from "../descriptors/$proxy.ts";
+import { $proxy, type ProxyPrimitiveOptions } from "../primitives/$proxy.ts";
 
 export class ServerProxyProvider {
   protected readonly log = $logger();
@@ -17,13 +17,13 @@ export class ServerProxyProvider {
   protected readonly configure = $hook({
     on: "configure",
     handler: () => {
-      for (const proxy of this.alepha.descriptors($proxy)) {
+      for (const proxy of this.alepha.primitives($proxy)) {
         this.createProxy(proxy.options);
       }
     },
   });
 
-  public createProxy(options: ProxyDescriptorOptions): void {
+  public createProxy(options: ProxyPrimitiveOptions): void {
     if (options.disabled) {
       return;
     }
@@ -52,7 +52,7 @@ export class ServerProxyProvider {
 
   public createProxyHandler(
     target: string,
-    options: Omit<ProxyDescriptorOptions, "path">,
+    options: Omit<ProxyPrimitiveOptions, "path">,
   ): ServerHandler {
     return async (request) => {
       const url = new URL(target + request.url.pathname);

package/src/server-rate-limit/index.ts

@@ -1,17 +1,17 @@
 import { $module } from "alepha";
 import { AlephaServer } from "alepha/server";
-import { $rateLimit } from "./descriptors/$rateLimit.ts";
+import { $rateLimit } from "./primitives/$rateLimit.ts";
 import { ServerRateLimitProvider } from "./providers/ServerRateLimitProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export * from "./descriptors/$rateLimit.ts";
+export * from "./primitives/$rateLimit.ts";
 export * from "./providers/ServerRateLimitProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 declare module "alepha/server" {
-  interface ActionDescriptorOptions<TConfig> {
+  interface ActionPrimitiveOptions<TConfig> {
     /**
      * Rate limiting configuration for this action.
      * When specified, the action will be rate limited according to these settings.
@@ -47,8 +47,8 @@ export interface RateLimitOptions {
  * Provides rate limiting capabilities for server routes and actions with configurable limits and windows.
  *
  * The server-rate-limit module enables per-route and per-action rate limiting using either:
- * - The `$rateLimit` descriptor with `paths` option for path-based rate limiting
- * - The `rateLimit` option in action descriptors for action-specific limiting
+ * - The `$rateLimit` primitive with `paths` option for path-based rate limiting
+ * - The `rateLimit` option in action primitives for action-specific limiting
  *
  * It offers sliding window rate limiting, custom key generation, and seamless integration with server routes.
  *
@@ -71,6 +71,6 @@ export interface RateLimitOptions {
  */
 export const AlephaServerRateLimit = $module({
   name: "alepha.server.rate-limit",
-  descriptors: [$rateLimit],
+  primitives: [$rateLimit],
   services: [AlephaServer, ServerRateLimitProvider],
 });

package/src/server-rate-limit/{descriptors → primitives}/$rateLimit.ts

@@ -1,4 +1,4 @@
-import { $inject, createDescriptor, Descriptor, KIND } from "alepha";
+import { $inject, createPrimitive, KIND, Primitive } from "alepha";
 import type { ServerRequest } from "alepha/server";
 import type { RateLimitOptions } from "../index.ts";
 import {
@@ -8,7 +8,7 @@ import {
 
 /**
  * Declares rate limiting for server routes or custom usage.
- * This descriptor provides methods to check rate limits and configure behavior
+ * This primitive provides methods to check rate limits and configure behavior
  * within the server request/response cycle.
  *
  * @example
@@ -33,32 +33,32 @@ import {
  * ```
  */
 export const $rateLimit = (
-  options: RateLimitDescriptorOptions = {},
-): AbstractRateLimitDescriptor => {
-  return createDescriptor(RateLimitDescriptor, options);
+  options: RateLimitPrimitiveOptions = {},
+): AbstractRateLimitPrimitive => {
+  return createPrimitive(RateLimitPrimitive, options);
 };
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface RateLimitDescriptorOptions extends RateLimitOptions {
+export interface RateLimitPrimitiveOptions extends RateLimitOptions {
   /** Name identifier for this rate limit (default: property key) */
   name?: string;
   /** Path patterns to match (supports wildcards like /api/*) */
   paths?: string[];
 }
 
-export interface AbstractRateLimitDescriptor {
+export interface AbstractRateLimitPrimitive {
   readonly name: string;
-  readonly options: RateLimitDescriptorOptions;
+  readonly options: RateLimitPrimitiveOptions;
   check(
     request: ServerRequest,
     options?: RateLimitOptions,
   ): Promise<RateLimitResult>;
 }
 
-export class RateLimitDescriptor
-  extends Descriptor<RateLimitDescriptorOptions>
-  implements AbstractRateLimitDescriptor
+export class RateLimitPrimitive
+  extends Primitive<RateLimitPrimitiveOptions>
+  implements AbstractRateLimitPrimitive
 {
   protected readonly serverRateLimitProvider = $inject(ServerRateLimitProvider);
 
@@ -72,7 +72,7 @@ export class RateLimitDescriptor
   }
 
   /**
-   * Checks rate limit for the given request using this descriptor's configuration.
+   * Checks rate limit for the given request using this primitive's configuration.
    */
   public async check(
     request: ServerRequest,
@@ -83,4 +83,4 @@ export class RateLimitDescriptor
   }
 }
 
-$rateLimit[KIND] = RateLimitDescriptor;
+$rateLimit[KIND] = RateLimitPrimitive;

package/src/server-rate-limit/providers/ServerRateLimitProvider.ts

@@ -6,8 +6,8 @@ import {
   type ServerRequest,
   ServerRouterProvider,
 } from "alepha/server";
-import type { RateLimitDescriptorOptions } from "../descriptors/$rateLimit.ts";
 import type { RateLimitOptions } from "../index.ts";
+import type { RateLimitPrimitiveOptions } from "../primitives/$rateLimit.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -85,12 +85,12 @@ export class ServerRateLimitProvider {
   /**
    * Registered rate limit configurations with their path patterns
    */
-  public readonly registeredConfigs: RateLimitDescriptorOptions[] = [];
+  public readonly registeredConfigs: RateLimitPrimitiveOptions[] = [];
 
   /**
-   * Register a rate limit configuration (called by descriptors)
+   * Register a rate limit configuration (called by primitives)
    */
-  public registerRateLimit(config: RateLimitDescriptorOptions): void {
+  public registerRateLimit(config: RateLimitPrimitiveOptions): void {
     this.registeredConfigs.push(config);
   }
 
@@ -168,7 +168,7 @@ export class ServerRateLimitProvider {
    * Build complete rate limit options by merging with global defaults
    */
   protected buildRateLimitOptions(
-    config: RateLimitDescriptorOptions,
+    config: RateLimitPrimitiveOptions,
   ): RateLimitOptions {
     return {
       max: config.max ?? this.globalOptions.max,

package/src/server-security/index.ts

@@ -8,7 +8,7 @@ import {
   type UserAccountToken,
 } from "alepha/security";
 import { AlephaServer, type FetchOptions } from "alepha/server";
-import { $basicAuth } from "./descriptors/$basicAuth.ts";
+import { $basicAuth } from "./primitives/$basicAuth.ts";
 import { ServerBasicAuthProvider } from "./providers/ServerBasicAuthProvider.ts";
 import {
   type ServerRouteSecure,
@@ -17,7 +17,7 @@ import {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export * from "./descriptors/$basicAuth.ts";
+export * from "./primitives/$basicAuth.ts";
 export * from "./providers/ServerBasicAuthProvider.ts";
 export * from "./providers/ServerSecurityProvider.ts";
 
@@ -84,7 +84,7 @@ declare module "alepha/server" {
  */
 export const AlephaServerSecurity = $module({
   name: "alepha.server.security",
-  descriptors: [$realm, $role, $permission, $basicAuth],
+  primitives: [$realm, $role, $permission, $basicAuth],
   services: [
     AlephaServer,
     AlephaSecurity,

package/src/server-security/{descriptors → primitives}/$basicAuth.ts

@@ -1,32 +1,32 @@
-import { $inject, createDescriptor, Descriptor, KIND } from "alepha";
+import { $inject, createPrimitive, KIND, Primitive } from "alepha";
 import type { ServerRequest } from "alepha/server";
 import type {
-  BasicAuthDescriptorConfig,
   BasicAuthOptions,
+  BasicAuthPrimitiveConfig,
 } from "../providers/ServerBasicAuthProvider.ts";
 import { ServerBasicAuthProvider } from "../providers/ServerBasicAuthProvider.ts";
 
 /**
  * Declares HTTP Basic Authentication for server routes.
- * This descriptor provides methods to protect routes with username/password authentication.
+ * This primitive provides methods to protect routes with username/password authentication.
  */
 export const $basicAuth = (
-  options: BasicAuthDescriptorConfig,
-): AbstractBasicAuthDescriptor => {
-  return createDescriptor(BasicAuthDescriptor, options);
+  options: BasicAuthPrimitiveConfig,
+): AbstractBasicAuthPrimitive => {
+  return createPrimitive(BasicAuthPrimitive, options);
 };
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface AbstractBasicAuthDescriptor {
+export interface AbstractBasicAuthPrimitive {
   readonly name: string;
-  readonly options: BasicAuthDescriptorConfig;
+  readonly options: BasicAuthPrimitiveConfig;
   check(request: ServerRequest, options?: BasicAuthOptions): void;
 }
 
-export class BasicAuthDescriptor
-  extends Descriptor<BasicAuthDescriptorConfig>
-  implements AbstractBasicAuthDescriptor
+export class BasicAuthPrimitive
+  extends Primitive<BasicAuthPrimitiveConfig>
+  implements AbstractBasicAuthPrimitive
 {
   protected readonly serverBasicAuthProvider = $inject(ServerBasicAuthProvider);
 
@@ -40,7 +40,7 @@ export class BasicAuthDescriptor
   }
 
   /**
-   * Checks basic auth for the given request using this descriptor's configuration.
+   * Checks basic auth for the given request using this primitive's configuration.
    */
   public check(request: ServerRequest, options?: BasicAuthOptions): void {
     const mergedOptions = { ...this.options, ...options };
@@ -48,4 +48,4 @@ export class BasicAuthDescriptor
   }
 }
 
-$basicAuth[KIND] = BasicAuthDescriptor;
+$basicAuth[KIND] = BasicAuthPrimitive;

package/src/server-security/providers/ServerBasicAuthProvider.ts

@@ -14,7 +14,7 @@ export interface BasicAuthOptions {
   password: string;
 }
 
-export interface BasicAuthDescriptorConfig extends BasicAuthOptions {
+export interface BasicAuthPrimitiveConfig extends BasicAuthOptions {
   /** Name identifier for this basic auth (default: property key) */
   name?: string;
   /** Path patterns to match (supports wildcards like /devtools/*) */
@@ -30,14 +30,14 @@ export class ServerBasicAuthProvider {
   protected readonly realm = "Secure Area";
 
   /**
-   * Registered basic auth descriptors with their configurations
+   * Registered basic auth primitives with their configurations
    */
-  public readonly registeredAuths: BasicAuthDescriptorConfig[] = [];
+  public readonly registeredAuths: BasicAuthPrimitiveConfig[] = [];
 
   /**
-   * Register a basic auth configuration (called by descriptors)
+   * Register a basic auth configuration (called by primitives)
    */
-  public registerAuth(config: BasicAuthDescriptorConfig): void {
+  public registerAuth(config: BasicAuthPrimitiveConfig): void {
     this.registeredAuths.push(config);
   }
 

package/src/server-security/providers/ServerSecurityProvider.ts

@@ -28,7 +28,7 @@ export class ServerSecurityProvider {
   protected readonly onConfigure = $hook({
     on: "configure",
     handler: async () => {
-      for (const action of this.alepha.descriptors($action)) {
+      for (const action of this.alepha.primitives($action)) {
         // -------------------------------------------------------------------------------------------------------------
         // if the action is disabled or not secure, we do NOT create a permission for it
         // -------------------------------------------------------------------------------------------------------------
@@ -87,7 +87,7 @@ export class ServerSecurityProvider {
           this.check(request.user, route.secure);
         }
 
-        this.alepha.state.set(
+        this.alepha.store.set(
           "alepha.server.request.user",
           this.alepha.codec.decode(userAccountInfoSchema, request.user),
         );
@@ -139,7 +139,7 @@ export class ServerSecurityProvider {
           this.check(request.user, route.secure);
         }
 
-        this.alepha.state.set(
+        this.alepha.store.set(
           "alepha.server.request.user",
           // remove sensitive info
           this.alepha.codec.decode(userAccountInfoSchema, request.user),
@@ -198,7 +198,7 @@ export class ServerSecurityProvider {
     let user: UserAccountToken | undefined;
 
     const fromContext = this.alepha.context.get<ServerRequest>("request")?.user;
-    const fromSystem = this.alepha.state.get(
+    const fromSystem = this.alepha.store.get(
       "alepha.server.security.system.user",
     );
 

package/src/server-static/index.ts

@@ -1,11 +1,11 @@
 import { $module } from "alepha";
 import { AlephaServer } from "alepha/server";
-import { $serve } from "./descriptors/$serve.ts";
+import { $serve } from "./primitives/$serve.ts";
 import { ServerStaticProvider } from "./providers/ServerStaticProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export * from "./descriptors/$serve.ts";
+export * from "./primitives/$serve.ts";
 export * from "./providers/ServerStaticProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -18,6 +18,6 @@ export * from "./providers/ServerStaticProvider.ts";
  */
 export const AlephaServerStatic = $module({
   name: "alepha.server.static",
-  descriptors: [$serve],
+  primitives: [$serve],
   services: [AlephaServer, ServerStaticProvider],
 });

package/src/server-static/{descriptors → primitives}/$serve.ts

@@ -1,16 +1,14 @@
-import { createDescriptor, Descriptor, KIND } from "alepha";
+import { createPrimitive, KIND, Primitive } from "alepha";
 import type { DurationLike } from "alepha/datetime";
 
 /**
  * Create a new static file handler.
  */
-export const $serve = (
-  options: ServeDescriptorOptions = {},
-): ServeDescriptor => {
-  return createDescriptor(ServeDescriptor, options);
+export const $serve = (options: ServePrimitiveOptions = {}): ServePrimitive => {
+  return createPrimitive(ServePrimitive, options);
 };
 
-export interface ServeDescriptorOptions {
+export interface ServePrimitiveOptions {
   /**
    * Prefix for the served path.
    *
@@ -26,7 +24,7 @@ export interface ServeDescriptorOptions {
   root?: string;
 
   /**
-   * If true, descriptor will be ignored.
+   * If true, primitive will be ignored.
    *
    * @default false
    */
@@ -53,7 +51,7 @@ export interface ServeDescriptorOptions {
   historyApiFallback?: boolean;
 
   /**
-   * Optional name of the descriptor.
+   * Optional name of the primitive.
    * This is used for logging and debugging purposes.
    *
    * @default Key name.
@@ -91,6 +89,6 @@ export interface CacheControlOptions {
   immutable: boolean;
 }
 
-export class ServeDescriptor extends Descriptor<ServeDescriptorOptions> {}
+export class ServePrimitive extends Primitive<ServePrimitiveOptions> {}
 
-$serve[KIND] = ServeDescriptor;
+$serve[KIND] = ServePrimitive;

package/src/server-static/providers/ServerStaticProvider.ts

@@ -7,7 +7,7 @@ import { DateTimeProvider } from "alepha/datetime";
 import { FileDetector } from "alepha/file";
 import { $logger } from "alepha/logger";
 import { type ServerHandler, ServerRouterProvider } from "alepha/server";
-import { $serve, type ServeDescriptorOptions } from "../descriptors/$serve.ts";
+import { $serve, type ServePrimitiveOptions } from "../primitives/$serve.ts";
 
 export class ServerStaticProvider {
   protected readonly alepha = $inject(Alepha);
@@ -22,14 +22,14 @@ export class ServerStaticProvider {
     handler: async () => {
       await Promise.all(
         this.alepha
-          .descriptors($serve)
+          .primitives($serve)
           .map((it) => this.createStaticServer(it.options)),
       );
     },
   });
 
   public async createStaticServer(
-    options: ServeDescriptorOptions,
+    options: ServePrimitiveOptions,
   ): Promise<void> {
     const prefix = options.path ?? "/";
 
@@ -107,7 +107,7 @@ export class ServerStaticProvider {
 
   public async createFileHandler(
     filepath: string,
-    options: ServeDescriptorOptions,
+    options: ServePrimitiveOptions,
   ): Promise<ServerHandler> {
     const filename = basename(filepath);
 
@@ -184,7 +184,7 @@ export class ServerStaticProvider {
 
   protected getCacheControl(
     filename: string,
-    options: ServeDescriptorOptions,
+    options: ServePrimitiveOptions,
   ): { maxAge: number; immutable: boolean } | undefined {
     if (!options.cacheControl) {
       return;
@@ -228,6 +228,6 @@ export class ServerStaticProvider {
 }
 
 export interface ServeDirectory {
-  options: ServeDescriptorOptions;
+  options: ServePrimitiveOptions;
   files: string[];
 }

package/src/server-swagger/index.ts

@@ -3,18 +3,18 @@ import { $module } from "alepha";
 import { AlephaServer, type RequestConfigSchema } from "alepha/server";
 import { AlephaServerCache } from "alepha/server/cache";
 import { AlephaServerStatic } from "alepha/server/static";
-import { $swagger } from "./descriptors/$swagger.ts";
+import { $swagger } from "./primitives/$swagger.ts";
 import { ServerSwaggerProvider } from "./providers/ServerSwaggerProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export * from "./descriptors/$swagger.ts";
+export * from "./primitives/$swagger.ts";
 export * from "./providers/ServerSwaggerProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 declare module "alepha/server" {
-  interface ActionDescriptorOptions<TConfig extends RequestConfigSchema> {
+  interface ActionPrimitiveOptions<TConfig extends RequestConfigSchema> {
     /**
      * Short description of the route.
      */
@@ -39,13 +39,13 @@ declare module "alepha/server" {
  */
 export const AlephaServerSwagger = $module({
   name: "alepha.server.swagger",
-  descriptors: [$swagger],
+  primitives: [$swagger],
   services: [ServerSwaggerProvider],
   register: (alepha) => {
     alepha.with(AlephaServer);
     alepha.with(AlephaServerCache);
     alepha.with(AlephaServerStatic);
     alepha.with(ServerSwaggerProvider);
-    alepha.state.push("alepha.build.assets", "alepha");
+    alepha.store.push("alepha.build.assets", "alepha");
   },
 });

package/src/server-swagger/{descriptors → primitives}/$swagger.ts

@@ -1,9 +1,9 @@
-import { createDescriptor, Descriptor, KIND } from "alepha";
+import { createPrimitive, KIND, Primitive } from "alepha";
 
 /**
- * Creates an OpenAPI/Swagger documentation descriptor with interactive UI.
+ * Creates an OpenAPI/Swagger documentation primitive with interactive UI.
  *
- * Automatically generates API documentation from your $action descriptors and serves
+ * Automatically generates API documentation from your $action primitives and serves
  * an interactive Swagger UI for testing endpoints. Supports customization, tag filtering,
  * and OAuth configuration.
  *
@@ -24,12 +24,12 @@ import { createDescriptor, Descriptor, KIND } from "alepha";
  * ```
  */
 export const $swagger = (
-  options: SwaggerDescriptorOptions = {},
-): SwaggerDescriptor => {
-  return createDescriptor(SwaggerDescriptor, options);
+  options: SwaggerPrimitiveOptions = {},
+): SwaggerPrimitive => {
+  return createPrimitive(SwaggerPrimitive, options);
 };
 
-export interface SwaggerDescriptorOptions {
+export interface SwaggerPrimitiveOptions {
   info?: OpenApiDocument["info"];
 
   /**
@@ -121,9 +121,9 @@ export interface SwaggerUiOptions {
   };
 }
 
-export class SwaggerDescriptor extends Descriptor<SwaggerDescriptorOptions> {}
+export class SwaggerPrimitive extends Primitive<SwaggerPrimitiveOptions> {}
 
-$swagger[KIND] = SwaggerDescriptor;
+$swagger[KIND] = SwaggerPrimitive;
 
 export interface OpenApiDocument {
   openapi: string;