@umituz/web-cloudflare 1.4.3 → 1.4.5

package/README.md

@@ -177,7 +177,16 @@ const versions = await wrangler.versionsList();
 await wrangler.versionsRollback(versions[0].id);
 ```
 
-**Note:** Wrangler CLI, Workers, AI Gateway, R2, and D1 services now follow Domain-Driven Design (DDD) architecture with their own domain structures at `src/domains/wrangler/`, `src/domains/workers/`, `src/domains/ai-gateway/`, `src/domains/r2/`, and `src/domains/d1/`.
+**Note:** All services now follow Domain-Driven Design (DDD) architecture with their own domain structures:
+- Wrangler CLI: `src/domains/wrangler/`
+- Workers: `src/domains/workers/`
+- AI Gateway: `src/domains/ai-gateway/`
+- R2: `src/domains/r2/`
+- D1: `src/domains/d1/`
+- KV: `src/domains/kv/`
+- Images: `src/domains/images/`
+- Analytics: `src/domains/analytics/`
+- Workflows: `src/domains/workflows/`
 
 ## 📚 Subpath Exports
 
@@ -187,8 +196,8 @@ await wrangler.versionsRollback(versions[0].id);
 // Workers service (now in domains/)
 import { WorkersService, workersService } from '@umituz/web-cloudflare/workers';
 
-// KV cache
-import { KVService } from '@umituz/web-cloudflare/kv';
+// KV cache (now in domains/)
+import { KVService, kvService } from '@umituz/web-cloudflare/kv';
 
 // R2 storage (now in domains/)
 import { R2Service, r2Service } from '@umituz/web-cloudflare/r2';
@@ -196,11 +205,14 @@ import { R2Service, r2Service } from '@umituz/web-cloudflare/r2';
 // D1 database (now in domains/)
 import { D1Service, d1Service } from '@umituz/web-cloudflare/d1';
 
-// Images optimization
-import { ImagesService } from '@umituz/web-cloudflare/images';
+// Images optimization (now in domains/)
+import { ImagesService, imagesService } from '@umituz/web-cloudflare/images';
 
-// Analytics
-import { AnalyticsService } from '@umituz/web-cloudflare/analytics';
+// Analytics (now in domains/)
+import { AnalyticsService, analyticsService } from '@umituz/web-cloudflare/analytics';
+
+// Workflows (now in domains/)
+import { WorkflowService } from '@umituz/web-cloudflare/workflows';
 
 // Wrangler CLI
 import { WranglerService } from '@umituz/web-cloudflare/wrangler';
@@ -661,32 +673,15 @@ Contributions are welcome!
 │   ├── config/              # Config patterns and types
 │   ├── domains/             # Domain-driven design structure
 │   │   ├── wrangler/        # Wrangler CLI domain
-│   │   │   ├── entities/    # Domain entities
-│   │   │   ├── services/    # Domain services
-│   │   │   ├── types/       # Domain types
-│   │   │   └── index.ts     # Domain exports
 │   │   ├── workers/         # Workers domain
-│   │   │   ├── entities/    # Domain entities
-│   │   │   ├── services/    # Domain services
-│   │   │   ├── types/       # Domain types
-│   │   │   ├── examples/    # Example files
-│   │   │   └── index.ts     # Domain exports
 │   │   ├── ai-gateway/      # AI Gateway domain
-│   │   │   ├── entities/    # Domain entities
-│   │   │   ├── services/    # Domain services
-│   │   │   └── index.ts     # Domain exports
 │   │   ├── r2/              # R2 storage domain
-│   │   │   ├── entities/    # Domain entities
-│   │   │   ├── services/    # Domain services
-│   │   │   ├── types/       # Domain types
-│   │   │   └── index.ts     # Domain exports
-│   │   └── d1/              # D1 database domain
-│   │       ├── entities/    # Domain entities
-│   │       ├── services/    # Domain services
-│   │       ├── types/       # Domain types
-│   │       └── index.ts     # Domain exports
+│   │   ├── d1/              # D1 database domain
+│   │   ├── kv/              # KV storage domain
+│   │   ├── images/          # Images optimization domain
+│   │   ├── analytics/       # Analytics domain
+│   │   └── workflows/       # Workflows domain
 │   ├── infrastructure/
-│   │   ├── services/        # Services (kv, images, analytics, workflows)
 │   │   ├── router/          # Express-like router
 │   │   ├── middleware/      # Middleware collection
 │   │   └── utils/           # Helper functions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-cloudflare",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "description": "Comprehensive Cloudflare Workers integration with config-based patterns, middleware, router, workflows, and AI (Patch-only versioning: only z in x.y.z increments)",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -8,12 +8,12 @@
   "exports": {
     ".": "./src/index.ts",
     "./workers": "./src/domains/workers/index.ts",
-    "./kv": "./src/infrastructure/services/kv/index.ts",
+    "./kv": "./src/domains/kv/index.ts",
     "./r2": "./src/domains/r2/index.ts",
     "./d1": "./src/domains/d1/index.ts",
-    "./images": "./src/infrastructure/services/images/index.ts",
-    "./analytics": "./src/infrastructure/services/analytics/index.ts",
-    "./workflows": "./src/infrastructure/services/workflows/index.ts",
+    "./images": "./src/domains/images/index.ts",
+    "./analytics": "./src/domains/analytics/index.ts",
+    "./workflows": "./src/domains/workflows/index.ts",
     "./ai-gateway": "./src/domains/ai-gateway/index.ts",
     "./workers-ai": "./src/domains/ai-gateway/index.ts",
     "./wrangler": "./src/domains/wrangler/index.ts",
@@ -75,6 +75,7 @@
     "typescript": ">=5.0.0"
   },
   "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260317.1",
     "@types/node": "~22.13.10",
     "typescript": "~5.9.2"
   },

package/src/config/patterns.ts

@@ -3,8 +3,8 @@
  * @description Reusable configuration patterns for different use cases
  */
 
-import type { AIGatewayConfig } from '../infrastructure/domain/ai-gateway.entity';
-import type { WorkflowDefinition } from '../infrastructure/domain/workflows.entity';
+import type { AIGatewayConfig } from '../domains/ai-gateway/entities';
+import type { WorkflowDefinition } from '../domains/workflows/entities';
 import type { WorkerConfig } from './types';
 
 // ============================================================
@@ -106,6 +106,8 @@ export const saasConfig: Partial<WorkerConfig> = {
   },
   workflows: {
     enabled: true,
+    maxExecutionTime: 300,
+    defaultRetries: 2,
   },
 };
 
@@ -149,6 +151,8 @@ export const cdnConfig: Partial<WorkerConfig> = {
   },
   rateLimit: {
     enabled: false,
+    maxRequests: 0,
+    window: 0,
   },
   compression: {
     enabled: true,
@@ -194,7 +198,7 @@ export const aiFirstConfig: Partial<WorkerConfig> = {
           baseURL: 'https://api.openai.com/v1',
           apiKey: '',
           models: ['gpt-4', 'gpt-3.5-turbo'],
-          fallback: 'workers-ai',
+          fallbackProvider: 'workers-ai',
           weight: 1,
         },
       ],
@@ -206,6 +210,8 @@ export const aiFirstConfig: Partial<WorkerConfig> = {
   },
   workflows: {
     enabled: true,
+    maxExecutionTime: 600,
+    defaultRetries: 3,
   },
 };
 
@@ -215,13 +221,18 @@ export const aiFirstConfig: Partial<WorkerConfig> = {
 export const minimalConfig: Partial<WorkerConfig> = {
   cache: {
     enabled: false,
+    defaultTTL: 0,
   },
   rateLimit: {
     enabled: false,
+    maxRequests: 0,
+    window: 0,
   },
   cors: {
     enabled: true,
     allowedOrigins: ['*'],
+    allowedMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+    allowedHeaders: ['*'],
   },
 };
 
@@ -234,26 +245,34 @@ export const minimalConfig: Partial<WorkerConfig> = {
  */
 export function mergeConfigs<T extends Record<string, any>>(
   base: T,
-  ...overrides: Partial<T>[]
+  ...overrides: Array<Partial<Record<string, any>>>
 ): T {
   return overrides.reduce((acc, override) => {
     return deepMerge(acc, override);
   }, base);
 }
 
-function deepMerge<T>(target: T, source: Partial<T>): T {
-  const output = { ...target } as T;
+function deepMerge<T extends Record<string, any>>(
+  target: T,
+  source: Partial<Record<string, any>>
+): T {
+  const output = { ...target };
 
   if (isObject(target) && isObject(source)) {
     Object.keys(source).forEach((key) => {
-      if (isObject(source[key as keyof T])) {
+      const sourceValue = source[key];
+      const targetValue = target[key as keyof T];
+
+      if (isObject(sourceValue)) {
         if (!(key in target)) {
-          Object.assign(output, { [key]: source[key as keyof T] });
+          (output as any)[key] = sourceValue;
+        } else if (isObject(targetValue)) {
+          (output as any)[key] = deepMerge(targetValue, sourceValue);
         } else {
-          (output as any)[key] = deepMerge(target[key as keyof T], source[key as keyof T]);
+          (output as any)[key] = sourceValue;
         }
       } else {
-        Object.assign(output, { [key]: source[key as keyof T] });
+        (output as any)[key] = sourceValue;
       }
     });
   }
@@ -261,7 +280,7 @@ function deepMerge<T>(target: T, source: Partial<T>): T {
   return output;
 }
 
-function isObject(item: unknown): item is Record<string, unknown> {
+function isObject(item: unknown): item is Record<string, any> {
   return Boolean(item && typeof item === 'object' && !Array.isArray(item));
 }
 
@@ -316,52 +335,52 @@ export class ConfigBuilder {
   }
 
   withCache(config: Partial<NonNullable<WorkerConfig['cache']>>): ConfigBuilder {
-    this.config.cache = { ...this.config.cache, ...config };
+    this.config.cache = this.config.cache ? { ...this.config.cache, ...config } : config as NonNullable<WorkerConfig['cache']>;
     return this;
   }
 
   withRateLimit(config: Partial<NonNullable<WorkerConfig['rateLimit']>>): ConfigBuilder {
-    this.config.rateLimit = { ...this.config.rateLimit, ...config };
+    this.config.rateLimit = this.config.rateLimit ? { ...this.config.rateLimit, ...config } : config as NonNullable<WorkerConfig['rateLimit']>;
     return this;
   }
 
   withAI(config: Partial<NonNullable<WorkerConfig['ai']>>): ConfigBuilder {
-    this.config.ai = { ...this.config.ai, ...config };
+    this.config.ai = this.config.ai ? { ...this.config.ai, ...config } : config as NonNullable<WorkerConfig['ai']>;
     return this;
   }
 
   withWorkflows(config: Partial<NonNullable<WorkerConfig['workflows']>>): ConfigBuilder {
-    this.config.workflows = { ...this.config.workflows, ...config };
+    this.config.workflows = this.config.workflows ? { ...this.config.workflows, ...config } : config as NonNullable<WorkerConfig['workflows']>;
     return this;
   }
 
   withCORS(config: Partial<NonNullable<WorkerConfig['cors']>>): ConfigBuilder {
-    this.config.cors = { ...this.config.cors, ...config };
+    this.config.cors = this.config.cors ? { ...this.config.cors, ...config } : config as NonNullable<WorkerConfig['cors']>;
     return this;
   }
 
   withAnalytics(config: Partial<NonNullable<WorkerConfig['analytics']>>): ConfigBuilder {
-    this.config.analytics = { ...this.config.analytics, ...config };
+    this.config.analytics = this.config.analytics ? { ...this.config.analytics, ...config } : config as NonNullable<WorkerConfig['analytics']>;
     return this;
   }
 
   withCompression(config: Partial<NonNullable<WorkerConfig['compression']>>): ConfigBuilder {
-    this.config.compression = { ...this.config.compression, ...config };
+    this.config.compression = this.config.compression ? { ...this.config.compression, ...config } : config as NonNullable<WorkerConfig['compression']>;
     return this;
   }
 
   withImageOptimization(config: Partial<NonNullable<WorkerConfig['imageOptimization']>>): ConfigBuilder {
-    this.config.imageOptimization = { ...this.config.imageOptimization, ...config };
+    this.config.imageOptimization = this.config.imageOptimization ? { ...this.config.imageOptimization, ...config } : config as NonNullable<WorkerConfig['imageOptimization']>;
     return this;
   }
 
   withQueues(config: Partial<NonNullable<WorkerConfig['queues']>>): ConfigBuilder {
-    this.config.queues = { ...this.config.queues, ...config };
+    this.config.queues = this.config.queues ? { ...this.config.queues, ...config } : config as NonNullable<WorkerConfig['queues']>;
     return this;
   }
 
   withScheduledTasks(config: Partial<NonNullable<WorkerConfig['scheduledTasks']>>): ConfigBuilder {
-    this.config.scheduledTasks = { ...this.config.scheduledTasks, ...config };
+    this.config.scheduledTasks = this.config.scheduledTasks ? { ...this.config.scheduledTasks, ...config } : config as NonNullable<WorkerConfig['scheduledTasks']>;
     return this;
   }
 
@@ -449,9 +468,9 @@ export function getEnvironmentConfig(
   switch (environment) {
     case 'development':
       return mergeConfigs(minimalConfig, {
-        cache: { enabled: false },
-        rateLimit: { enabled: false },
-        cors: { allowedOrigins: ['*'] },
+        cache: { enabled: false, defaultTTL: 0 },
+        rateLimit: { enabled: false, maxRequests: 0, window: 0 },
+        cors: { enabled: true, allowedOrigins: ['*'], allowedMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'], allowedHeaders: ['*'] },
       });
 
     case 'staging':

package/src/domain/entities/analytics.entity.ts

@@ -1,47 +1,30 @@
 /**
  * Analytics Entity
- * @description Cloudflare Web Analytics configuration and types
+ * @description Basic Analytics entity placeholder
  */
 
-export interface AnalyticsConfig {
-  readonly siteId: string;
-  readonly scriptUrl?: string;
-}
-
-export interface AnalyticsEvent {
-  readonly timestamp: number;
-  readonly url: string;
-  readonly eventType: "pageview" | "custom" | "outbound-link" | "timing";
-  readonly eventData?: Record<string, unknown>;
-}
-
-export interface AnalyticsPageviewEvent extends AnalyticsEvent {
-  readonly eventType: "pageview";
-  readonly title: string;
-  readonly referrer?: string;
+export interface AnalyticsEntity {
+  siteId: string;
+  eventCount: number;
 }
 
-export interface AnalyticsCustomEvent extends AnalyticsEvent {
-  readonly eventType: "custom";
-  readonly eventName: string;
+export interface AnalyticsConfig {
+  siteId: string;
+  scriptUrl?: string;
 }
 
-export interface AnalyticsTimingEvent extends AnalyticsEvent {
-  readonly eventType: "timing";
-  readonly name: string;
-  readonly value: number;
-  readonly label?: string;
+export interface AnalyticsEvent {
+  timestamp: number;
+  url: string;
+  eventType: string;
+  data?: Record<string, unknown>;
 }
 
 export interface AnalyticsData {
-  readonly siteId: string;
-  readonly events: readonly AnalyticsEvent[];
-  readonly metrics?: AnalyticsMetrics;
-}
-
-export interface AnalyticsMetrics {
-  readonly pageviews: number;
-  readonly uniqueVisitors: number;
-  readonly bounceRate?: number;
-  readonly avgSessionDuration?: number;
+  siteId: string;
+  events: AnalyticsEvent[];
+  metrics?: {
+    pageviews: number;
+    uniqueVisitors: number;
+  };
 }

package/src/domain/entities/d1.entity.ts

@@ -0,0 +1,27 @@
+/**
+ * D1 Entity
+ * @description Basic D1 entity placeholder
+ */
+
+export interface D1Entity {
+  databaseId: string;
+  name: string;
+}
+
+export interface D1DatabaseConfig {
+  name: string;
+  migrations?: string[];
+}
+
+export interface D1QueryResult<T = unknown> {
+  rows: T[];
+  meta?: {
+    duration: number;
+    changes?: number;
+  };
+}
+
+export interface D1BatchResult<T = unknown> {
+  success: boolean;
+  results?: D1QueryResult<T>[];
+}

package/src/domain/entities/image.entity.ts

@@ -1,48 +1,48 @@
 /**
  * Image Entity
- * @description Cloudflare Images configuration and types
+ * @description Basic Image entity placeholder
  */
 
+export interface ImageEntity {
+  id: string;
+  url: string;
+  variant?: string;
+}
+
 export interface ImageConfig {
-  readonly account: string;
-  readonly customDomain?: string;
+  formats?: Array<'webp' | 'avif' | 'jpeg' | 'png'>;
+  quality?: number;
 }
 
 export interface ImageVariant {
-  readonly variant: string;
-  readonly width?: number;
-  readonly height?: number;
-  readonly fit?: "scale-down" | "contain" | "cover" | "crop" | "pad";
-  readonly format?: "jpeg" | "png" | "gif" | "webp" | "avif";
-  readonly quality?: number;
+  width: number;
+  height: number;
+  format: string;
+  url: string;
 }
 
 export interface ImageUploadResult {
-  readonly id: string;
-  readonly filename: string;
-  readonly uploaded: Date;
-  readonly variants: readonly string[];
-  readonly requireSignedURLs: boolean;
+  id: string;
+  url: string;
+  variants: ImageVariant[];
 }
 
 export interface ImageUploadOptions {
-  readonly metadata?: Record<string, string>;
-  readonly requireSignedURLs?: boolean;
-  readonly variants?: readonly ImageVariant[];
+  format?: 'webp' | 'avif' | 'jpeg' | 'png';
+  quality?: number;
+  width?: number;
+  height?: number;
 }
 
 export interface ImageTransformation {
-  readonly width?: number;
-  readonly height?: number;
-  readonly fit?: "scale-down" | "contain" | "cover" | "crop" | "pad";
-  readonly format?: "jpeg" | "png" | "gif" | "webp" | "avif";
-  readonly quality?: number;
-  readonly rotate?: number;
-  readonly flip?: boolean;
-  readonly flop?: boolean;
+  width?: number;
+  height?: number;
+  fit?: 'contain' | 'cover' | 'fill';
+  format?: 'webp' | 'avif' | 'jpeg' | 'png';
+  quality?: number;
 }
 
 export interface SignedURL {
-  readonly url: string;
-  readonly expiresAt: Date;
+  url: string;
+  expires: number;
 }

package/src/domain/entities/kv.entity.ts

@@ -1,34 +1,37 @@
 /**
  * KV Entity
- * @description Cloudflare KV configuration and types
+ * @description Basic KV entity placeholder
  */
 
+export interface KVEntity {
+  namespaceId: string;
+  key: string;
+  value: string;
+}
+
 export interface KVNamespaceConfig {
-  readonly namespace: string;
-  readonly ttl?: number;
+  id: string;
+  ttl?: number;
 }
 
-export interface KVEntry<T = unknown> {
-  readonly key: string;
-  readonly value: T;
-  readonly metadata?: Record<string, unknown>;
-  readonly expiration?: number;
+export interface KVEntry {
+  key: string;
+  value: string;
+  metadata?: Record<string, unknown>;
 }
 
 export interface KVListOptions {
-  readonly limit?: number;
-  readonly cursor?: string;
-  readonly prefix?: string;
+  limit?: number;
+  cursor?: string;
+  prefix?: string;
 }
 
 export interface KVListResult {
-  readonly keys: readonly KVKey[];
-  readonly list_complete: boolean;
-  readonly cursor?: string;
+  keys: KVEntry[];
+  cursor?: string;
 }
 
 export interface KVKey {
-  readonly name: string;
-  readonly metadata?: Record<string, unknown>;
-  readonly expiration?: number;
+  name: string;
+  metadata?: Record<string, unknown>;
 }

package/src/domain/entities/r2.entity.ts

@@ -0,0 +1,49 @@
+/**
+ * R2 Entity
+ * @description Basic R2 entity placeholder
+ */
+
+export interface R2Entity {
+  bucketName: string;
+  key: string;
+}
+
+export interface R2BucketConfig {
+  name: string;
+  location?: string;
+}
+
+export interface R2Object {
+  key: string;
+  size: number;
+  uploaded: Date;
+}
+
+export interface R2UploadResult {
+  key: string;
+  etag?: string;
+}
+
+export interface R2ListOptions {
+  limit?: number;
+  cursor?: string;
+  prefix?: string;
+}
+
+export interface R2ListResult {
+  objects: R2Object[];
+  cursor?: string;
+}
+
+export interface R2PutOptions {
+  customMetadata?: Record<string, string>;
+  httpMetadata?: {
+    contentType?: string;
+    cacheControl?: string;
+  };
+}
+
+export interface R2PresignedURL {
+  url: string;
+  expires: number;
+}

package/src/domain/entities/worker.entity.ts

@@ -0,0 +1,35 @@
+/**
+ * Worker Entity
+ * @description Basic Worker entity placeholder
+ */
+
+export interface WorkerEntity {
+  id: string;
+  name: string;
+}
+
+export interface WorkerConfig {
+  name: string;
+  routes?: string[];
+  schedule?: string;
+  bindings?: Record<string, unknown>;
+}
+
+export interface WorkerResponse {
+  status: number;
+  body?: BodyInit | null;
+}
+
+export interface IncomingRequestCfProperties {
+  colo?: string;
+  country?: string;
+  httpProtocol?: string;
+  tlsVersion?: string;
+  tlsCipher?: string;
+  asn?: number;
+  requestPriority?: number;
+}
+
+export type { WorkerRequest as _WorkerRequest } from '../../domains/workers/entities';
+// Re-export WorkerRequest from workers domain
+export { WorkerRequest } from '../../domains/workers/entities';

package/src/domains/analytics/entities/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Analytics Entity
+ * @description Cloudflare Web Analytics configuration and types
+ */
+
+export interface WebAnalyticsConfig {
+  readonly siteId: string;
+  readonly scriptUrl?: string;
+}
+
+export interface AnalyticsEvent {
+  readonly timestamp: number;
+  readonly url: string;
+  readonly eventType: "pageview" | "custom" | "outbound-link" | "timing";
+  readonly eventData?: Record<string, unknown>;
+}
+
+export interface AnalyticsPageviewEvent extends AnalyticsEvent {
+  readonly eventType: "pageview";
+  readonly title: string;
+  readonly referrer?: string;
+}
+
+export interface AnalyticsCustomEvent extends AnalyticsEvent {
+  readonly eventType: "custom";
+  readonly eventName: string;
+}
+
+export interface AnalyticsTimingEvent extends AnalyticsEvent {
+  readonly eventType: "timing";
+  readonly name: string;
+  readonly value: number;
+  readonly label?: string;
+}
+
+export interface WebAnalyticsData {
+  readonly siteId: string;
+  readonly events: readonly AnalyticsEvent[];
+  readonly metrics?: AnalyticsMetrics;
+}
+
+export interface AnalyticsMetrics {
+  readonly pageviews: number;
+  readonly uniqueVisitors: number;
+  readonly bounceRate?: number;
+  readonly avgSessionDuration?: number;
+}