Merge pull request #4 from TouK/dev

release

Author: JulianWielga

cli/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [1.0.2-beta.1](https://github.com/TouK/nu-cloud-lab/compare/v1.0.1...v1.0.2-beta.1) (2026-02-18)
+
+### Bug Fixes
+
+* fixed faker templates, added short prefix `::` ([11766ff](https://github.com/TouK/nu-cloud-lab/commit/11766ff2dba478e45bea8e2b670a4250538b0b14))
+
 ## [1.0.1](https://github.com/TouK/nu-cloud-lab/compare/v1.0.0...v1.0.1) (2026-02-18)
 
 ### Bug Fixes

cli/README.md

@@ -277,9 +277,9 @@ Templates define the structure of generated messages using faker.js for realisti
 The CLI includes a default template with faker.js support:
 
 ```yaml
-name: "faker:person.fullName"
-email: "faker:internet.email"
-age: "faker:number.int(18,65)"
+name: "::person.fullName"
+email: "::internet.email"
+age: "::number.int({min:18, max:65})"
 timestamp: "current_timestamp"
 ```
 
@@ -289,11 +289,12 @@ Create your own template file:
 
 ```yaml
 # my-template.yaml
-userId: "faker:string.uuid"
-username: "faker:internet.userName"
-company: "faker:company.name"
-location: "faker:location.city"
-price: "faker:commerce.price(10,1000)"
+userId: "::string.uuid"
+username: "::internet.userName"
+company: "::company.name"
+location: "::location.city"
+price: "::commerce.price({min:10, max:1000})"
+status: '::helpers.arrayElement(["active","pending","suspended"])'
 ```
 
 **Use it:**
@@ -310,63 +311,81 @@ nu-cli send --template ./my-template.yaml
 
 ### Faker.js Syntax
 
-Supports full [faker.js API](https://fakerjs.dev/api/):
+Full [faker.js API](https://fakerjs.dev/api/) support using `::` prefix. Parameters are parsed as JSON and spread as `...args` to faker functions.
 
-- `faker:person.fullName` → Random full name
-- `faker:internet.email` → Random email
-- `faker:number.int(18,65)` → Random integer between 18 and 65
-- `faker:company.name` → Random company name
-- `faker:location.streetAddress` → Random street address
-- `faker:string.uuid` → Random UUID
-- `faker:commerce.price(10,1000)` → Random price between 10 and 1000
-
-### Legacy Syntax (still supported)
+**Simple calls (no parameters):**
+```yaml
+name: "::person.fullName"
+email: "::internet.email"
+company: "::company.name"
+address: "::location.streetAddress"
+uuid: "::string.uuid"
+```
 
-- `random_name` → Random name from built-in list
-- `random_int(1,100)` → Random integer
-- `current_timestamp` → ISO 8601 timestamp
+**With parameters (use JSON syntax, wrap in single quotes in YAML):**
+```yaml
+# Object parameters
+age: "::number.int({min:18, max:65})"
+price: "::commerce.price({min:10, max:1000})"
 
-## Message Templates
+# Single argument (array)
+event: '::helpers.arrayElement(["login","logout","purchase"])'
 
-Messages are generated from templates defined in `src/lib/template/generator.ts`. To customize message structure, edit the `MESSAGE_TEMPLATE` constant:
+# Multiple arguments (array, options object)
+tags: '::helpers.arrayElements(["tech","sports","music"], {min:2, max:4})'
 
-```typescript
-export const MESSAGE_TEMPLATE: TemplateObject = {
-  "name": "random_name",
-};
+# Multiple arguments (coordinates, distance, isMetric)
+location: '::location.nearbyGPSCoordinate([52.52, 13.40], 10, true)'
 ```
 
-### Example: Complex template
-
-```typescript
-export const MESSAGE_TEMPLATE = {
-  user: {
-    name: "random_name",
-    city: "random_city"
-  },
-  order: {
-    product: "random_product",
-    quantity: "random_int(1,5)",
-    status: "random_status",
-    timestamp: "current_timestamp"
-  }
-};
-```
+**How it works:**
+- `::category.method` maps to `faker.category.method()`
+- Parameters are parsed as JSON: `({min:18,max:65})` → `fn({min:18, max:65})`
+- Supports any faker.js function signature exactly as documented
 
-### Available placeholders
+**Special values:**
+- `current_timestamp` → ISO 8601 timestamp
 
-- `random_name` - Random person name from predefined list
-- `random_city` - Random city name
-- `random_product` - Random product name
-- `random_status` - Random status (pending, completed, failed, in_progress)
-- `random_int(min,max)` - Random integer in range (e.g., `random_int(1,10)`)
-- `current_timestamp` - ISO 8601 timestamp (e.g., `2024-02-16T10:30:00.000Z`)
+### Advanced Examples
 
-After modifying the template, rebuild the CLI:
-```bash
-npm run build
+**Complete event template:**
+```yaml
+# events.yaml
+userId: "::string.uuid"
+eventType: '::helpers.arrayElement(["login","logout","purchase","click"])'
+timestamp: "current_timestamp"
+user:
+  name: "::person.fullName"
+  email: "::internet.email"
+  age: "::number.int({min:18, max:65})"
+metadata:
+  ip: "::internet.ip"
+  device: '::helpers.arrayElement(["mobile","desktop","tablet"])'
+  browser: '::helpers.arrayElement(["Chrome","Firefox","Safari","Edge"])'
+  location: "::location.city"
+  coordinates: '::location.nearbyGPSCoordinate([52.52, 13.40], 10, true)'
+```
+
+**E-commerce order:**
+```yaml
+orderId: "::string.uuid"
+products: '::helpers.arrayElements(["laptop","phone","tablet","watch","headphones"], {min:1, max:3})'
+totalPrice: "::commerce.price({min:50, max:5000})"
+status: '::helpers.arrayElement(["pending","processing","shipped","delivered"])'
+customer:
+  id: "::string.uuid"
+  name: "::person.fullName"
+  email: "::internet.email"
+shippingAddress:
+  street: "::location.streetAddress"
+  city: "::location.city"
+  country: "::location.country"
+  zipCode: "::location.zipCode"
+createdAt: "current_timestamp"
 ```
 
+
+
 ## Examples
 
 ### Continuous production with custom delay

cli/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@nussknacker/cli",
-  "version": "1.0.1",
+  "version": "1.0.2-beta.1",
   "description": "CLI tool for Nussknacker Cloud - produce and consume messages",
   "type": "module",
   "bin": {

cli/package.json

@@ -1,57 +1,45 @@
 import { faker } from '@faker-js/faker';
 import { logger } from '../../utils/logger.js';
 
-export const SAMPLE_DATA = {
-  names: ["Alice", "Bob", "Charlie", "David", "Eve", "Frank", "Grace", "Hannah"],
-  cities: ["New York", "London", "Tokyo", "Paris", "Berlin", "Sydney"],
-  products: ["Laptop", "Phone", "Tablet", "Watch", "Headphones"],
-  statuses: ["pending", "completed", "failed", "in_progress"]
-} as const;
-
 export function getRandomValue(fieldType: string): any {
-  // Faker.js syntax support
-  if (fieldType.startsWith('faker:')) {
+  // Faker.js syntax: faker:category.method or ::category.method
+  if (fieldType.startsWith('faker:') || fieldType.startsWith('::')) {
     return parseFakerExpression(fieldType);
   }
 
-  // Legacy syntax (backward compatibility)
-  if (fieldType === "random_name") {
-    return SAMPLE_DATA.names[Math.floor(Math.random() * SAMPLE_DATA.names.length)];
-  } else if (fieldType === "random_city") {
-    return SAMPLE_DATA.cities[Math.floor(Math.random() * SAMPLE_DATA.cities.length)];
-  } else if (fieldType === "random_product") {
-    return SAMPLE_DATA.products[Math.floor(Math.random() * SAMPLE_DATA.products.length)];
-  } else if (fieldType === "random_status") {
-    return SAMPLE_DATA.statuses[Math.floor(Math.random() * SAMPLE_DATA.statuses.length)];
-  } else if (fieldType === "current_timestamp") {
+  // Special: current_timestamp
+  if (fieldType === "current_timestamp") {
     return new Date().toISOString();
-  } else if (fieldType.startsWith("random_int(")) {
-    const [min, max] = fieldType.slice(11, -1).split(',').map(Number);
-    return Math.floor(Math.random() * (max - min + 1)) + min;
   }
+  
+  // No transformation - return as-is
   return fieldType;
 }
 
 /**
  * Parse and execute faker.js expressions
- * 
+ *
  * Examples:
+ *   "::person.fullName" -> faker.person.fullName()
+ *   "::number.int({min:18,max:65})" -> faker.number.int({min:18, max:65})
+ *   "::helpers.arrayElement([1,2,3])" -> faker.helpers.arrayElement([1,2,3])
+ *   '::helpers.arrayElements([1,2,3],{min:2,max:4})' -> faker.helpers.arrayElements([1,2,3], {min:2, max:4})
+ *   
+ *   Legacy "faker:" prefix still supported:
  *   "faker:person.fullName" -> faker.person.fullName()
- *   "faker:number.int(18,65)" -> faker.number.int({min: 18, max: 65})
- *   "faker:internet.email" -> faker.internet.email()
  */
 function parseFakerExpression(expr: string): any {
-  // Pattern: faker:category.method or faker:category.method(params)
-  const match = expr.match(/^faker:([a-zA-Z.]+)(?:\(([^)]*)\))?$/);
-  
+  // Pattern: ::category.method or faker:category.method (both supported)
+  const match = expr.match(/^(?:faker:|::)([a-zA-Z.]+)(?:\(([^)]*)\))?$/);
+
   if (!match) {
     logger.warn(`Invalid faker syntax: ${expr}`);
     return expr;
   }
-  
+
   const [, path, params] = match;
   const parts = path.split('.');
-  
+
   // Navigate to faker method: faker.person.fullName
   let fn: any = faker;
   for (const part of parts) {
@@ -61,51 +49,45 @@ function parseFakerExpression(expr: string): any {
       return expr;
     }
   }
-  
+
   if (typeof fn !== 'function') {
     logger.warn(`Faker path is not a function: ${path}`);
     return expr;
   }
-  
+
   // Call with params if present
-  if (params && params.trim()) {
+  if (params?.trim()) {
     const args = parseFakerParams(params, path);
-    return fn(args);
+    return fn(...args);
   }
-  
+
   // Call without params
   return fn();
 }
 
 /**
- * Parse faker parameters
- * 
- * Examples:
- *   "18,65" (for number.int) -> {min: 18, max: 65}
- *   "5" (for string methods) -> {length: 5}
+ * Parse faker parameters as JSON array for spreading
+ *
+ * Treats params as JSON array and returns array of arguments:
+ *   "[1,2,3]" -> [[1,2,3]]
+ *   "[1,2,3],{min:2,max:4}" -> [[1,2,3], {min:2, max:4}]
+ *   "{min:18,max:65}" -> [{min:18, max:65}]
+ *
+ * This allows spreading as ...args to faker functions.
  */
-function parseFakerParams(params: string, fakerPath: string): any {
-  const values = params.split(',').map(v => v.trim());
-  
-  // Special handling for number.int/float (min,max)
-  if (fakerPath.startsWith('number.')) {
-    if (values.length === 2) {
-      return {
-        min: parseFloat(values[0]),
-        max: parseFloat(values[1])
-      };
-    }
-    if (values.length === 1) {
-      return { max: parseFloat(values[0]) };
-    }
-  }
-  
-  // Default: single numeric param as length/count
-  if (values.length === 1 && !isNaN(parseFloat(values[0]))) {
-    return { length: parseInt(values[0], 10) };
+function parseFakerParams(params: string, _fakerPath: string): any[] {
+  // Parse as JSON array
+  try {
+    const wrapped = `[${params}]`;
+
+    // Support relaxed JSON syntax (unquoted keys)
+    const relaxed = wrapped.replace(/([{,]\s*)([a-zA-Z_][a-zA-Z0-9_]*)\s*:/g, '$1"$2":');
+
+    const parsed = JSON.parse(relaxed);
+    return Array.isArray(parsed) ? parsed : [parsed];
+  } catch (e) {
+    // JSON parse failed
+    logger.warn(`Failed to parse faker params as JSON: ${params}`);
+    return [];
   }
-  
-  // Fallback: return as object
-  logger.warn(`Unsure how to parse params for ${fakerPath}: ${params}`);
-  return {};
 }

cli/src/lib/template/random.ts

@@ -1,27 +1,28 @@
 # Default message template for Nu Cloud
-# 
-# This template demonstrates faker.js syntax for generating random test data.
+#
+# Faker.js integration for generating realistic test data.
 # Full API reference: https://fakerjs.dev/api/
 #
 # Syntax:
-#   faker:category.method           -> faker.person.fullName()
-#   faker:category.method(params)   -> faker.number.int(18,65)
+#   ::category.method                    -> faker.person.fullName()
+#   ::category.method({...})             -> faker.number.int({min:18, max:65})
+#   ::category.method([...])             -> faker.helpers.arrayElement(["a","b"])
+#   ::category.method([...], {...})      -> faker.helpers.arrayElements([...], {min:2})
 #
-# Legacy syntax (still supported):
-#   random_name                     -> Random name from built-in list
-#   random_int(min,max)             -> Random integer
-#   current_timestamp               -> ISO 8601 timestamp
+# Special values:
+#   current_timestamp                    -> ISO 8601 timestamp
 
-name: "faker:person.fullName"
-email: "faker:internet.email"
-age: "faker:number.int(18,65)"
+name: "::person.fullName"
+email: "::internet.email"
+age: "::number.int({min:18, max:65})"
 timestamp: "current_timestamp"
 
 # More examples (commented out):
-# company: "faker:company.name"
-# address: "faker:location.streetAddress"
-# city: "faker:location.city"
-# phone: "faker:phone.number"
-# uuid: "faker:string.uuid"
-# productName: "faker:commerce.productName"
-# price: "faker:commerce.price(10,1000)"
+# company: "::company.name"
+# address: "::location.streetAddress"
+# city: "::location.city"
+# phone: "::phone.number"
+# uuid: "::string.uuid"
+# productName: "::commerce.productName"
+# price: "::commerce.price({min:10, max:1000})"
+# status: '::helpers.arrayElement(["active","pending","completed"])'