blendsdk 5.34.0 → 5.35.0

package/README.md

@@ -35,20 +35,31 @@ npm install blendsdk
 ### Web API with Express 5
 
 ```typescript
-import { WebApplication, RouteBuilder } from "blendsdk/webafx";
+import { WebApplication, BaseController, RouteDefinition } from "blendsdk/webafx";
+
+// Define a controller with routes
+class HelloController extends BaseController {
+  routes(): RouteDefinition[] {
+    return [
+      this.route()
+        .get("/hello")
+        .handle(async (_req, res) => {
+          this.ok(res, { message: "Hello from BlendSDK!" });
+        }),
+    ];
+  }
+}
 
+// Create the application and register the controller
 const app = new WebApplication({
-  port: 3000,
-  name: "my-api",
+  PORT: 3000,
+  ENV_MODE: "development",
 });
 
-app.route(
-  RouteBuilder.get("/hello").handler((_req, res) => {
-    res.json({ message: "Hello from BlendSDK!" });
-  })
-);
+app.registerController("/api", HelloController);
 
-await app.start();
+const shutdown = await app.start();
+// Server running → GET /api/hello returns { success: true, data: { message: "Hello from BlendSDK!" } }
 ```
 
 ### SQL Expression Building
@@ -58,16 +69,157 @@ import { query } from "blendsdk/expression";
 
 // Build a type-safe WHERE clause
 const filter = query()
-  .field("status")
-  .eq("active")
-  .and()
-  .field("age")
-  .gte(18);
+  .where("status").equals("active")
+  .and("age").greaterThanOrEqual(18);
 
 // Compile to parameterized SQL
-const { sql, parameters } = filter.compile();
-// sql: "status" = $1 AND "age" >= $2
-// parameters: ["active", 18]
+const { sql, params } = filter.compile();
+// sql: "status = :p1 AND age >= :p2"
+// params: { p1: "active", p2: 18 }
+
+// Nested conditions with grouping
+const advanced = query()
+  .where("status").equals("active")
+  .and(q => q
+    .where("age").greaterThan(21)
+    .or("verified").equals(true)
+  )
+  .compile();
+// sql: "status = :p1 AND (age > :p2 OR verified = :p3)"
+// params: { p1: "active", p2: 21, p3: true }
+```
+
+### CLI Argument Parser
+
+```typescript
+import { CommandLineParser } from "blendsdk/cmdline";
+
+const cli = new CommandLineParser({ name: "my-cli", version: "1.0.0" });
+
+cli.addCommand({
+  name: "deploy",
+  description: "Deploy the application",
+  options: [
+    {
+      name: "environment",
+      short: "e",
+      type: "string",
+      required: true,
+      choices: ["dev", "staging", "production"],
+    },
+    {
+      name: "verbose",
+      short: "v",
+      type: "boolean",
+      description: "Verbose output",
+    },
+  ],
+  handler: async (params) => {
+    console.log(`Deploying to ${params.environment}...`);
+  },
+});
+
+await cli.execute();
+// Usage: my-cli deploy --environment=staging --verbose
+```
+
+### Database CRUD Operations
+
+```typescript
+import { Database } from "blendsdk/dbcore";
+
+// Insert with returning clause
+const user = await db
+  .insert<{ name: string; email: string }>("users")
+  .values({ name: "Alice", email: "alice@example.com" })
+  .returning("*")
+  .execute();
+
+// Update with filter
+await db
+  .update<{ name: string }, { id: number }>("users")
+  .values({ name: "Bob" })
+  .filter({ id: 1 })
+  .returning("*")
+  .execute();
+
+// Delete with expression filter
+await db
+  .delete<{ status: string }>("users")
+  .filterByExpression(q => q.where("status").equals("inactive"))
+  .execute();
+```
+
+### Caching
+
+```typescript
+import { MemoryCacheProvider } from "blendsdk/webafx-cache";
+
+const cache = new MemoryCacheProvider({
+  rootKey: "MyApp",
+  defaultTTL: 300, // 5 minutes
+});
+
+// Simple set/get with type safety
+await cache.set("user:1", { name: "Alice", role: "admin" });
+const user = await cache.get<{ name: string; role: string }>("user:1");
+
+// Cache-aside pattern (getOrSet)
+const product = await cache.getOrSet(
+  "product:42",
+  async () => {
+    return await fetchProductFromDatabase(42);
+  },
+  60, // TTL in seconds
+);
+
+// Pattern-based deletion
+await cache.deletePattern("user:*"); // Remove all user cache entries
+```
+
+### Pub/Sub Messaging
+
+```typescript
+import { MemoryPubSubProvider } from "blendsdk/webafx-cache";
+
+const pubsub = new MemoryPubSubProvider();
+
+// Subscribe to a specific channel with typed messages
+await pubsub.subscribe<{ id: number; total: number }>("order:new", (msg) => {
+  console.log(`New order on ${msg.channel}:`, msg.data);
+});
+
+// Pattern subscription (wildcard matching)
+await pubsub.psubscribe("order:*", (msg) => {
+  console.log(`Order event [${msg.pattern}] on ${msg.channel}`);
+});
+
+// Publish returns the number of receivers
+const receiverCount = await pubsub.publish("order:new", { id: 1, total: 99.99 });
+```
+
+### Internationalization
+
+```typescript
+import { Translator } from "blendsdk/i18n";
+
+const translator = new Translator({
+  defaultLocale: "en",
+  catalog: {
+    greeting: { en: "Hello ${name}", nl: "Hallo ${name}" },
+    farewell: { en: "Goodbye", nl: "Tot ziens" },
+    book: {
+      en: ["${count} book", "${count} books"],
+      nl: ["${count} boek", "${count} boeken"],
+    },
+  },
+});
+
+translator.translate("greeting", "en", { name: "Alice" }); // "Hello Alice"
+translator.translate("greeting", "nl", { name: "Alice" }); // "Hallo Alice"
+translator.translate("book", "en", { count: 1 });           // "1 book"
+translator.translate("book", "en", { count: 5 });           // "5 books"
+translator.translate("farewell", "en_GB");                   // "Goodbye" (falls back to "en")
 ```
 
 ### Utilities

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blendsdk",
-  "version": "5.34.0",
+  "version": "5.35.0",
   "description": "Enterprise-grade TypeScript SDK for web applications, database operations, caching, pub/sub, email, i18n, and code generation",
   "type": "module",
   "engines": {
@@ -74,21 +74,21 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "zod": "^4.0.0"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@blendsdk/stdlib": "5.34.0",
-    "@blendsdk/cmdline": "5.34.0",
-    "@blendsdk/expression": "5.34.0",
-    "@blendsdk/dbcore": "5.34.0",
-    "@blendsdk/postgresql": "5.34.0",
-    "@blendsdk/webafx": "5.34.0",
-    "@blendsdk/webafx-cache": "5.34.0",
-    "@blendsdk/webafx-mailer": "5.34.0",
-    "@blendsdk/webafx-auth": "5.34.0",
-    "@blendsdk/i18n": "5.34.0",
-    "@blendsdk/webafx-i18n": "5.34.0",
-    "@blendsdk/codegen": "5.34.0"
+    "@blendsdk/stdlib": "5.35.0",
+    "@blendsdk/cmdline": "5.35.0",
+    "@blendsdk/expression": "5.35.0",
+    "@blendsdk/dbcore": "5.35.0",
+    "@blendsdk/postgresql": "5.35.0",
+    "@blendsdk/webafx": "5.35.0",
+    "@blendsdk/webafx-cache": "5.35.0",
+    "@blendsdk/webafx-mailer": "5.35.0",
+    "@blendsdk/webafx-auth": "5.35.0",
+    "@blendsdk/i18n": "5.35.0",
+    "@blendsdk/webafx-i18n": "5.35.0",
+    "@blendsdk/codegen": "5.35.0"
   },
   "peerDependencies": {
     "typescript": "^5.6.0",