starlight-cli 1.1.5 → 1.1.7

package/README.md

@@ -224,6 +224,183 @@ 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
+
+---
+
+### Nullish Coalescing (`??`) Support
+
+Our language now supports the **nullish coalescing operator** `??`, which allows you to provide a default value for `null` or `undefined` expressions.
+
+**Syntax:**
+
+```sl
+value = expression1 ?? expression2
+```
+
+* `expression1` is evaluated first.
+* If it is **not null or undefined**, its value is used.
+* Otherwise, the value of `expression2` is used.
+
+**Example:**
+
+```sl
+define a = null
+define b = a ?? 42
+sldeploy b  # Output: 42
+```
+
+**Notes:**
+
+* Only `null` and `undefined` are treated as "empty" values. Other falsy values like `0`, `false`, or `""` will **not** trigger the default.
+* This operator is optional. If you prefer, you can achieve the same result using a simple `if` statement:
+
+```sl
+define a = null
+define b = if a != null then a else 42
+sldeploy b  # Output: 42
+```
+
+This operator simplifies code that needs default values and makes your scripts cleaner and more readable.
+
+---
+
 ## 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) => {
@@ -10884,12 +10942,20 @@ async evalBinary(node, env) {
 
 async evalLogical(node, env) {
   const l = await this.evaluate(node.left, env);
-  if (node.operator === 'AND') return l && await this.evaluate(node.right, env);
-  if (node.operator === 'OR') return l || await this.evaluate(node.right, env);
-  throw new RuntimeError(`Unknown logical operator: ${node.operator}`, node, this.source);
 
+  switch(node.operator) {
+    case 'AND': return l && await this.evaluate(node.right, env);
+    case 'OR': return l || await this.evaluate(node.right, env);
+    case '??': {
+      const r = await this.evaluate(node.right, env);
+      return (l !== null && l !== undefined) ? l : r;
+    }
+    default:
+      throw new RuntimeError(`Unknown logical operator: ${node.operator}`, node, this.source);
+  }
 }
 
+
 async evalUnary(node, env) {
   const val = await this.evaluate(node.argument, env);
   switch (node.operator) {
@@ -11319,6 +11385,18 @@ if (char === '-' && next === '>') {
   this.advance(); this.advance();
   continue;
 }
+if (char === '?' && next === '?') {
+    tokens.push({ type: 'NULLISH_COALESCING', value: '??', line: startLine, column: startCol });
+    this.advance(); 
+    this.advance(); 
+    continue;
+}
+
+if (char === '?') {
+    tokens.push({ type: 'QUESTION', value: '?', line: startLine, column: startCol });
+    this.advance();
+    continue;
+}
 
       if (char === '!' && next === '=') { tokens.push({ type: 'NOTEQ', line: startLine, column: startCol }); this.advance(); this.advance(); continue; }
       if (char === '<' && next === '=') { tokens.push({ type: 'LTE', line: startLine, column: startCol }); this.advance(); this.advance(); continue; }
@@ -11879,7 +11957,7 @@ expression() {
 }
 
 assignment() {
-  const node = this.logicalOr();
+  const node = this.ternary();
   const compoundOps = ['PLUSEQ', 'MINUSEQ', 'STAREQ', 'SLASHEQ', 'MODEQ'];
 
   const t = this.current;
@@ -11899,7 +11977,27 @@ assignment() {
 
   return node;
 }
-
+ternary() {
+  let node = this.nullishCoalescing();
+  while (this.current.type === 'QUESTION') {
+    const t = this.current;
+    this.eat('QUESTION');
+    const consequent = this.expression(); 
+    this.eat('COLON');
+    const alternate = this.expression();   
+    node = { type: 'ConditionalExpression', test: node, consequent, alternate, line: t.line, column: t.column };
+  }
+  return node;
+}
+nullishCoalescing() {
+  let node = this.logicalOr(); 
+  while (this.current.type === 'NULLISH_COALESCING') {
+    const t = this.current;
+    this.eat('NULLISH_COALESCING');
+    node = { type: 'LogicalExpression', operator: '??', left: node, right: this.logicalOr(), line: t.line, column: t.column };
+  }
+  return node;
+}
 logicalOr() {
   let node = this.logicalAnd();
   while (this.current.type === 'OR') {
@@ -12409,7 +12507,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.7';
 
 const COLOR = {
     reset: '\x1b[0m',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-cli",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Starlight Programming Language CLI",
   "bin": {
     "starlight": "index.js"
@@ -9,8 +9,18 @@
     "build": "ncc build src/starlight.js -o dist",
     "prepublishOnly": "npm run build"
   },
-  "author": "Macedon",
+  "author": "Dominex Macedon",
   "license": "MIT",
+  "keywords": [
+    "starlight",
+    "starlight-language",
+    "programming-language",
+    "scripting-language",
+    "server-side",
+    "cli",
+    "interpreter",
+    "starlight-cli"
+  ],
   "dependencies": {
     "blessed": "^0.1.81",
     "markdown-it": "^14.1.0",

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) => {
@@ -674,12 +732,20 @@ async evalBinary(node, env) {
 
 async evalLogical(node, env) {
   const l = await this.evaluate(node.left, env);
-  if (node.operator === 'AND') return l && await this.evaluate(node.right, env);
-  if (node.operator === 'OR') return l || await this.evaluate(node.right, env);
-  throw new RuntimeError(`Unknown logical operator: ${node.operator}`, node, this.source);
 
+  switch(node.operator) {
+    case 'AND': return l && await this.evaluate(node.right, env);
+    case 'OR': return l || await this.evaluate(node.right, env);
+    case '??': {
+      const r = await this.evaluate(node.right, env);
+      return (l !== null && l !== undefined) ? l : r;
+    }
+    default:
+      throw new RuntimeError(`Unknown logical operator: ${node.operator}`, node, this.source);
+  }
 }
 
+
 async evalUnary(node, env) {
   const val = await this.evaluate(node.argument, env);
   switch (node.operator) {

package/src/lexer.js

@@ -179,6 +179,18 @@ if (char === '-' && next === '>') {
   this.advance(); this.advance();
   continue;
 }
+if (char === '?' && next === '?') {
+    tokens.push({ type: 'NULLISH_COALESCING', value: '??', line: startLine, column: startCol });
+    this.advance(); 
+    this.advance(); 
+    continue;
+}
+
+if (char === '?') {
+    tokens.push({ type: 'QUESTION', value: '?', line: startLine, column: startCol });
+    this.advance();
+    continue;
+}
 
       if (char === '!' && next === '=') { tokens.push({ type: 'NOTEQ', line: startLine, column: startCol }); this.advance(); this.advance(); continue; }
       if (char === '<' && next === '=') { tokens.push({ type: 'LTE', line: startLine, column: startCol }); this.advance(); this.advance(); continue; }

package/src/parser.js

@@ -521,7 +521,7 @@ expression() {
 }
 
 assignment() {
-  const node = this.logicalOr();
+  const node = this.ternary();
   const compoundOps = ['PLUSEQ', 'MINUSEQ', 'STAREQ', 'SLASHEQ', 'MODEQ'];
 
   const t = this.current;
@@ -541,7 +541,27 @@ assignment() {
 
   return node;
 }
-
+ternary() {
+  let node = this.nullishCoalescing();
+  while (this.current.type === 'QUESTION') {
+    const t = this.current;
+    this.eat('QUESTION');
+    const consequent = this.expression(); 
+    this.eat('COLON');
+    const alternate = this.expression();   
+    node = { type: 'ConditionalExpression', test: node, consequent, alternate, line: t.line, column: t.column };
+  }
+  return node;
+}
+nullishCoalescing() {
+  let node = this.logicalOr(); 
+  while (this.current.type === 'NULLISH_COALESCING') {
+    const t = this.current;
+    this.eat('NULLISH_COALESCING');
+    node = { type: 'LogicalExpression', operator: '??', left: node, right: this.logicalOr(), line: t.line, column: t.column };
+  }
+  return node;
+}
 logicalOr() {
   let node = this.logicalAnd();
   while (this.current.type === 'OR') {

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.7';
 
 const COLOR = {
     reset: '\x1b[0m',