starlight-cli 1.1.5 → 1.1.6

package/README.md

@@ -224,6 +224,147 @@ This makes Starlight useful not only as a programming language, but also as a **
 
 ---
 
+## Array Helpers: map, filter, reduce
+
+Starlight provides built-in **functional helpers** for working with arrays: `map`, `filter`, and `reduce`.  
+These helpers are **async-aware**, work seamlessly with **arrow functions**, and integrate fully with Starlight’s runtime and error handling.
+
+Unlike JavaScript, these are **global functions** (not methods), keeping the language simple and consistent.
+
+---
+
+### map(array, fn)
+
+Transforms each element of an array using a callback function and returns a **new array**.
+
+**Syntax:**
+```
+
+map(array, fn)
+
+```
+
+**Example:**
+```
+
+let numbers = [1, 2, 3, 4]
+
+let squared = await map(numbers, x => x * x)
+
+sldeploy squared
+
+```
+
+**Output:**
+```
+
+[ 1, 4, 9, 16 ]
+
+```
+
+- `fn` receives `(value, index, array)`
+- Does **not** modify the original array
+- Supports `async` arrow functions
+
+---
+
+### filter(array, fn)
+
+Selects elements from an array that satisfy a condition and returns a **new array**.
+
+**Syntax:**
+```
+
+filter(array, fn)
+
+```
+
+**Example:**
+```
+
+let numbers = [1, 2, 3, 4, 5, 6]
+
+let evens = await filter(numbers, x => x % 2 == 0)
+
+sldeploy evens
+
+```
+
+**Output:**
+```
+
+[ 2, 4, 6 ]
+
+```
+
+- `fn` must return `true` or `false`
+- `fn` receives `(value, index, array)`
+- Original array remains unchanged
+
+---
+
+### reduce(array, fn, initial)
+
+Reduces an array to a **single value** by accumulating results using a reducer function.
+
+**Syntax:**
+```
+
+reduce(array, fn, initial)
+
+```
+
+**Example:**
+```
+
+let numbers = [1, 2, 3, 4, 5]
+
+let total = await reduce(numbers, (acc, value) => acc + value, 0)
+
+sldeploy total
+
+```
+
+**Output:**
+```
+
+15
+
+```
+
+- `fn` receives `(accumulator, value, index, array)`
+- `initial` is optional, but recommended
+- Throws a runtime error if used on an empty array without an initial value
+
+---
+
+### Async Support
+
+All three helpers support `async` functions:
+
+```
+
+let results = await map(items, async item => {
+await sleep(100)
+return item * 2
+})
+
+```
+
+---
+
+### Why global helpers?
+
+Starlight keeps `map`, `filter`, and `reduce` as **language-level utilities** instead of object methods to:
+
+- Keep syntax minimal and readable
+- Avoid prototype complexity
+- Work consistently with all iterables
+- Integrate cleanly with the evaluator and runtime
+
+---
+
+
 ## Why Starlight?
 
 * A **simple but powerful** scripting language

package/dist/index.js

@@ -10376,6 +10376,64 @@ formatValue(value, seen = new Set()) {
         if (Array.isArray(arg)) return 'array';
         return typeof arg;
     });
+    this.global.define('map', async (array, fn) => {
+  if (!Array.isArray(array)) {
+    throw new RuntimeError('map() expects an array', null, this.source);
+  }
+  if (typeof fn !== 'function') {
+    throw new RuntimeError('map() expects a function', null, this.source);
+  }
+
+  const result = [];
+  for (let i = 0; i < array.length; i++) {
+    result.push(await fn(array[i], i, array));
+  }
+  return result;
+});
+this.global.define('filter', async (array, fn) => {
+  if (!Array.isArray(array)) {
+    throw new RuntimeError('filter() expects an array', null, this.source);
+  }
+  if (typeof fn !== 'function') {
+    throw new RuntimeError('filter() expects a function', null, this.source);
+  }
+
+  const result = [];
+  for (let i = 0; i < array.length; i++) {
+    if (await fn(array[i], i, array)) {
+      result.push(array[i]);
+    }
+  }
+  return result;
+});
+this.global.define('reduce', async (array, fn, initial) => {
+  if (!Array.isArray(array)) {
+    throw new RuntimeError('reduce() expects an array', null, this.source);
+  }
+  if (typeof fn !== 'function') {
+    throw new RuntimeError('reduce() expects a function', null, this.source);
+  }
+
+  let acc;
+  let startIndex = 0;
+
+  if (initial !== undefined) {
+    acc = initial;
+  } else {
+    if (array.length === 0) {
+      throw new RuntimeError('reduce() of empty array with no initial value', null, this.source);
+    }
+    acc = array[0];
+    startIndex = 1;
+  }
+
+  for (let i = startIndex; i < array.length; i++) {
+    acc = await fn(acc, array[i], i, array);
+  }
+
+  return acc;
+});
+
     this.global.define('keys', arg => arg && typeof arg === 'object' ? Object.keys(arg) : []);
     this.global.define('values', arg => arg && typeof arg === 'object' ? Object.values(arg) : []);
 this.global.define('range', (...args) => {
@@ -12409,7 +12467,7 @@ const Lexer = __nccwpck_require__(211);
 const Parser = __nccwpck_require__(222);
 const Evaluator = __nccwpck_require__(112);
 
-const VERSION = '1.1.5';
+const VERSION = '1.1.6';
 
 const COLOR = {
     reset: '\x1b[0m',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-cli",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Starlight Programming Language CLI",
   "bin": {
     "starlight": "index.js"

package/src/evaluator.js

@@ -166,6 +166,64 @@ formatValue(value, seen = new Set()) {
         if (Array.isArray(arg)) return 'array';
         return typeof arg;
     });
+    this.global.define('map', async (array, fn) => {
+  if (!Array.isArray(array)) {
+    throw new RuntimeError('map() expects an array', null, this.source);
+  }
+  if (typeof fn !== 'function') {
+    throw new RuntimeError('map() expects a function', null, this.source);
+  }
+
+  const result = [];
+  for (let i = 0; i < array.length; i++) {
+    result.push(await fn(array[i], i, array));
+  }
+  return result;
+});
+this.global.define('filter', async (array, fn) => {
+  if (!Array.isArray(array)) {
+    throw new RuntimeError('filter() expects an array', null, this.source);
+  }
+  if (typeof fn !== 'function') {
+    throw new RuntimeError('filter() expects a function', null, this.source);
+  }
+
+  const result = [];
+  for (let i = 0; i < array.length; i++) {
+    if (await fn(array[i], i, array)) {
+      result.push(array[i]);
+    }
+  }
+  return result;
+});
+this.global.define('reduce', async (array, fn, initial) => {
+  if (!Array.isArray(array)) {
+    throw new RuntimeError('reduce() expects an array', null, this.source);
+  }
+  if (typeof fn !== 'function') {
+    throw new RuntimeError('reduce() expects a function', null, this.source);
+  }
+
+  let acc;
+  let startIndex = 0;
+
+  if (initial !== undefined) {
+    acc = initial;
+  } else {
+    if (array.length === 0) {
+      throw new RuntimeError('reduce() of empty array with no initial value', null, this.source);
+    }
+    acc = array[0];
+    startIndex = 1;
+  }
+
+  for (let i = startIndex; i < array.length; i++) {
+    acc = await fn(acc, array[i], i, array);
+  }
+
+  return acc;
+});
+
     this.global.define('keys', arg => arg && typeof arg === 'object' ? Object.keys(arg) : []);
     this.global.define('values', arg => arg && typeof arg === 'object' ? Object.values(arg) : []);
 this.global.define('range', (...args) => {

package/src/starlight.js

@@ -12,7 +12,7 @@ const Lexer = require('./lexer');
 const Parser = require('./parser');
 const Evaluator = require('./evaluator');
 
-const VERSION = '1.1.5';
+const VERSION = '1.1.6';
 
 const COLOR = {
     reset: '\x1b[0m',